[!CAUTION] Beta. This endpoint is still being built: more options are being added, and what it accepts may change.

Not available yet, and still set in the application:

• Google Sheets delivery
• Static fields
• Ping caps and cap notifications
• Creating or editing buyer groups (listing them and assigning a buyer to one are supported)
• Deleting, cloning or importing a buyer
• Testing a buyer
• Reading back post conditions, payloads and headers (write-only)

Add a buyer to a campaign: which client it is, what it pays per lead, and how leads are delivered to it.

A new buyer starts paused, as it does in the application, so its setup can be checked before leads flow. Resume it with the pause & resume endpoint.

Delivery types

An HTTP request

A direct_post is one request, written directly under delivery. A ping_post is two, under delivery.ping and delivery.post, each with the same properties. Only the url is required; what is left out gets the application's defaults:

The deprecated <> tag syntax is refused in the url, the payload and the headers; write tags as {{field_name}}.

Reading the buyer's answer

response_mapping says what the answer looks like when the lead was accepted and when it was duplicated. A ping has accepted only.

Real-time pricing

With real_time_price on, the amount the buyer pays is read out of its answer at real_time_price_key. It needs a json or xml response, and pricing.static must not be sent with it: the price is saved as 0 and comes from the answer.

On a direct post and on the post leg it is refused where the price is decided another way: a highest-bidder campaign, a buyer in a highest-bidder group, a ping-post exchange, and a one-to-one campaign. The ping leg is not restricted.

Post conditions (ping-post)

delivery.post_conditions holds conditions the ping's answer must meet before the post is sent. Optional: without them the post is always sent. They need a json or xml ping response.

Groups are joined by match (any or all); so are the rules inside a group.

between takes two values, one_of a list, every other condition one. Post conditions are write-only for now: no response publishes them.

One-to-one

Only on a one-to-one campaign. A ping and a post, as a ping_post takes them, plus a buyers object on each that says where the answer lists the buyers:

The bids are priced by the ping's answer, so a one-to-one buyer takes no pricing.static, pricing.rules, pricing.bid_penalty, pricing.bid or pricing.supplier_margins, no real_time_price and no post_conditions. pricing.margin_override applies.

Customized API response (one-to-one campaigns)

api_response adds keys to each bid the supplier receives, on any buyer of a one-to-one campaign. A list of {"name": "...", "value": {"type": "...", "value": "..."}, "ping": true, "post": true}, replaced as a whole when sent; null removes it.

id, price, execution_time and buyer_id are in every bid already and cannot be names. tcpa_name is the one predefined key: it needs a value, is returned on both the ping and the post, takes static (and ping_response or post_response on a ping_post), and is not available on a one_to_one buyer, which reads it at buyers.tcpa_name_key. Changing a buyer to one_to_one removes it.

Email

Conditional prices

pricing.rules is a list of conditional prices. For each lead they are checked in order: the first whose rules match sets the price, and pricing.static applies when none does. Not accepted with real-time pricing, and turning real-time pricing on removes them.

"pricing": {
  "static": 10,
  "rules": [
    {"price": 25, "match": "all", "rules": [
      {"type": "field", "field": "state", "condition": "one_of", "value": ["CA", "NY"]},
      {"type": "field", "field": "loan_amount", "condition": "gte", "value": "50000"}
    ]},
    {"price": 15, "match": "any", "rules": [
      {"type": "day_time", "windows": ["sat|12:00 AM|12:00 AM|America/New_York", "sun|12:00 AM|12:00 AM|America/New_York"]}
    ]}
  ]
}

Here a California or New York lead asking for 50,000 or more pays 25, any other lead on a weekend pays 15, and everything else pays 10.

Rule types

With match: all a field can be used once per item.

Conditions (field rules)

Text comparisons ignore case. An empty value matches only blank and neq.

Which conditions a field takes depends on its type, from the campaign's fields:

Day and time

day_time windows are written as a DAY_HOUR filter's (see Delivery schedule windows): day|start|end|timezone, 12-hour times on the quarter hour, one timezone for all windows, no overlaps. Two differences: a window cannot run past midnight (split it at 12:00 AM into two days, fri|10:00 PM|12:00 AM|... and sat|12:00 AM|02:00 AM|...), and start equal to end is the whole day.

Bid override (highest bidder)

On a highest-bidder campaign or in a highest-bidder buyer group, pricing.bid changes where the buyer stands when buyers are ordered by bid. It never changes what the buyer pays.

"bid": null inside pricing turns it off. The bid penalty is a separate setting, applied on top of the override; it has no effect with position.

Supplier-specific margins (ping-post exchange)

pricing.supplier_margins sets a margin on this buyer's bids for chosen suppliers: {"enabled": true, "suppliers": [{"supplier_id": 779, "margin": 40}]}. It has its own switch, independent of pricing.margin_override, and the list is kept while it is off. A margin for a supplier wins over that supplier's own margin override.

Settings that depend on the campaign

Each is refused with 422 on a campaign where the application does not show it.

Full examples

One complete body per delivery type. Field names such as state and phone are the campaign's own; use yours.

Lead store

{
  "client_id": 50,
  "nickname": "Acme Buyer - Lead store",
  "pricing": {"static": 8},
  "delivery": {"type": "lead_store"}
}

Direct post, paying 20 for California and New York leads and 12.50 for the rest:

{
  "client_id": 50,
  "nickname": "Acme Buyer - Direct post",
  "pricing": {
    "static": 12.5,
    "rules": [
      {"price": 20, "rules": [{"type": "field", "field": "state", "condition": "one_of", "value": ["CA", "NY"]}]}
    ]
  },
  "delivery": {
    "type": "direct_post",
    "url": "https://example.com/leads?source={{lp_supplier_id}}",
    "method": "POST",
    "payload_type": "json",
    "payload": "{\"first_name\": \"{{first_name}}\", \"last_name\": \"{{last_name}}\", \"phone\": \"{{phone}}\", \"state\": \"{{state}}\", \"zip\": \"{{zip_code}}\"}",
    "headers": [{"name": "Authorization", "value": "Bearer abc123"}],
    "timeout": 30,
    "response_type": "json",
    "response_mapping": {
      "accepted": {"key": "status", "condition": "equal", "value": "ok"},
      "duplicated": {"condition": "response_has", "value": "duplicate"}
    }
  }
}

Ping post. The buyer answers the ping with {"accepted": true, "ping_id": "…", "bid": 12}; the post is sent only when bid is 10 or more, and carries the ping_id back:

{
  "client_id": 50,
  "nickname": "Acme Buyer - Ping post",
  "pricing": {"static": 15},
  "delivery": {
    "type": "ping_post",
    "ping": {
      "url": "https://example.com/ping",
      "payload_type": "json",
      "payload": "{\"state\": \"{{state}}\", \"zip\": \"{{zip_code}}\"}",
      "timeout": 10,
      "response_type": "json",
      "response_mapping": {
        "accepted": {"key": "accepted", "condition": "equal", "value": "true"}
      }
    },
    "post": {
      "url": "https://example.com/post",
      "payload_type": "json",
      "payload": "{\"ping_id\": \"{{lp_ping_response:ping_id}}\", \"first_name\": \"{{first_name}}\", \"last_name\": \"{{last_name}}\", \"phone\": \"{{phone}}\"}",
      "timeout": 30,
      "response_type": "json",
      "response_mapping": {
        "accepted": {"key": "status", "condition": "equal", "value": "ok"},
        "duplicated": {"key": "status", "condition": "equal", "value": "duplicate"}
      }
    },
    "post_conditions": {
      "groups": [
        {"rules": [{"type": "ping_response", "field": "bid", "condition": "gte", "value": "10"}]}
      ]
    }
  }
}

Email

{
  "client_id": 50,
  "nickname": "Acme Buyer - Email",
  "pricing": {"static": 5},
  "delivery": {
    "type": "email",
    "recipients": ["leads@example.com", "sales@example.com"],
    "subject": "New lead from {{lp_campaign_name}}",
    "from_name": "Acme Leads",
    "reply_to": "support@example.com",
    "payload": "Name: {{first_name}} {{last_name}}\nPhone: {{phone}}\nState: {{state}}"
  }
}

{
  "client_id": 50,
  "nickname": "Acme Buyer - Direct post",
  "pricing": {
    "static": 12.5,
    "rules": [
      {
        "rules": [
          {
            "windows": [
              "mon|09:00 AM|05:00 PM|America/New_York"
            ]
          }
        ]
      }
    ],
    "bid": {
      "rules": [
        {
          "rules": [
            {
              "windows": [
                "mon|09:00 AM|05:00 PM|America/New_York"
              ]
            }
          ]
        }
      ]
    }
  },
  "api_response": [
    {
      "name": "source"
    }
  ],
  "delivery": {
    "url": "https://example.com/leads",
    "headers": [
      {
        "name": "Authorization",
        "value": "Bearer …"
      }
    ],
    "real_time_price_key": "data.price",
    "response_mapping": {
      "accepted": {
        "key": "status",
        "value": "ok"
      },
      "duplicated": {
        "key": "status",
        "value": "ok"
      }
    },
    "ping": {
      "url": "https://example.com/leads",
      "headers": [
        {
          "name": "Authorization",
          "value": "Bearer …"
        }
      ],
      "real_time_price_key": "data.price",
      "response_mapping": {
        "accepted": {
          "key": "status",
          "value": "ok"
        }
      },
      "buyers": {
        "list_key": "bids",
        "bid_id_key": "id",
        "price_key": "price",
        "tcpa_name_key": "name"
      }
    },
    "post": {
      "url": "https://example.com/leads",
      "headers": [
        {
          "name": "Authorization",
          "value": "Bearer …"
        }
      ],
      "real_time_price_key": "data.price",
      "response_mapping": {
        "accepted": {
          "key": "status",
          "value": "ok"
        },
        "duplicated": {
          "key": "status",
          "value": "ok"
        }
      },
      "buyers": {
        "list_key": "bids",
        "bid_id_key": "id"
      }
    }
  }
}