Exchange Transactions

Create Lead Transaction(s)

As a buyer, use this endpoint to confirm leads you've received against a marketplace offer (e.g. a landing-page form completion). Each confirmed lead creates a lead transaction that credits the attributed seller.

• 🔐 Permissions: ["marketplace_transaction.create"]

Each lead references the send it came from using exactly one of campaign_id, send_id, or click_id (the same matchback identifiers used by sales uploads), plus a buyer-supplied resource_id used for audit/idempotency. Every lead must match back to a marketplace offer your organisation owns — leads that resolve to a non-marketplace campaign are rejected.

You can optionally set the status of each lead in the same call, accepting or rejecting it up front instead of creating it and then calling Update Transaction Status separately. See Setting the status on create.

POST Request

POST /exchange/buyer/transaction

Upload leads in bulk (1–1000 per request).

Body

type Body = {
  /** Buyer-supplied unique id for this lead — used for audit/idempotency */
  resource_id: string;
  /** The cell number of the contact. Can be in local or international format (if local, the country of the corresponding campaign is used) */
  cell: string;
  /** The campaign ID this lead matches back to */
  campaign_id?: string;
  /** The send_id this lead matches back to */
  send_id?: string;
  /** The click_id this lead matches back to */
  click_id?: string;
  /**
   * Accept, reject, or hold the resulting transaction as it is created.
   * Defaults to the offer's configured default status.
   */
  status?: "completed" | "pending" | "rejected";
}[];

Note: Provide exactly one of campaign_id, send_id, or click_id per lead — supplying none or more than one is rejected.

Example

[
  {
    "resource_id": "lead-0001",
    "cell": "27112223333",
    "campaign_id": "639978184d735c88ed8bbd68",
    "status": "completed"
  }
]

GET Request

GET /exchange/buyer/transaction/create

Confirm / postback a single lead via a GET request.

Params

The same values as used in a POST request (for a single lead) but now used as search parameters of the url, plus your API key.

type Params = {
  /** Your account API key with the required permissions */
  key: string;
  /** Buyer-supplied unique id for this lead — used for audit/idempotency */
  resource_id: string;
  /** The cell number of the contact. Can be in local or international format */
  cell: string;
  /** The campaign ID this lead matches back to */
  campaign_id?: string;
  /** The send_id this lead matches back to */
  send_id?: string;
  /** The click_id this lead matches back to */
  click_id?: string;
  /**
   * Accept, reject, or hold the resulting transaction as it is created.
   * Defaults to the offer's configured default status.
   */
  status?: "completed" | "pending" | "rejected";
};

Example

https://api.dripcel.com/exchange/buyer/transaction/create?key=KEY&resource_id=lead-0001&campaign_id=CAMPAIGN_ID&cell=27112223333&status=completed

Setting the status on create

By default a new lead transaction takes the offer's configured default status (either completed or pending). Supplying status overrides that per lead:

status	Effect
completed	Accept the lead immediately. Credits the seller's wallet, deducts your credits, and counts toward the offer's caps.
pending	Hold the lead for review. No wallet or credit movement until you accept it via Update Transaction Status.
rejected	Reject the lead immediately. No wallet or credit movement.

This saves a round trip: creating a lead and accepting it is one call rather than two.

The requested status is not always applied. Two protections take precedence:

• Duplicates. If the same contact already has a transaction against the same offer within the last 7 days, the transaction is created as rejected regardless of the status you asked for. You are not charged for a duplicate lead.
• Offer caps. If the offer has reached a configured cap, the transaction is held as pending instead of completed, so it can't spend past the cap. You can still explicitly send rejected to reject a capped lead outright.

To confirm the status a transaction actually landed on, use Search Transactions.

Response

Success

201

{
  ok: true;
  data: "Lead(s) submitted";
}

Error

404

{
  ok: false;
  // No matching marketplace offer for the given resource_id(s)
  error: "No matching marketplace offer for: ...";
}

Update Transaction Status

As a buyer, use this endpoint to accept or reject a pending transaction.

If you already know the outcome when you submit the lead, you can skip this call and set the status directly on create instead — see Setting the status on create.

Request

PUT /exchange/buyer/transaction/:id/status

Body

type Body = {
  status: "completed" | "rejected";
};

Search Transactions

Request

POST /exchange/buyer/transaction/search

Body

type Body = {
    /** The transaction IDs to search for */
    _id?: string | string[];
    /** The transaction statuses to search for */
    status?: "pending" | "completed" | "rejected";
    /** Offer IDs to search for */
    offer_id?: string | string[];
    /** The date the transaction was created. */
    createdAt?: { $gte?: string; $lte?: string };
}

Example

{
    "_id": "63f5d0e0d9e9d1a0f0a3d8e1",
    "status": "completed",
    "offer_id": "63f5d0e0d9e9d1a0f0a3d8e1",
    "createdAt": { $gte: "2023-02-14T09:02:51.000Z" }
}