Lead Docs LeadExchange API

LeadExchange API Docs

Use the live LeadExchange runtime to validate, price, and deliver leads with a ping/post workflow.

Base URL
https://lead-api.calarax.com
Live Endpoints
Ping: POST https://lead-api.calarax.com/ping
Post: POST https://lead-api.calarax.com/post
Direct Post: POST https://lead-api.calarax.com/direct_post

Campaign Setup

  1. Create a campaign in LeadExchange and choose the traffic type (ping/post or direct post).
  2. Define your campaign schema. System fields below are always available; add custom fields as needed.
  3. Configure traffic sources with their credentials and endpoint URLs.
  4. Configure buyers with ping and post endpoints, then map fields.
  5. Send a test ping and test post to validate the setup.
Authentication is provided by including SRC and KEY fields in the payload (no auth header required).
For ping/post campaigns, send POST https://lead-api.calarax.com/ping first. If the ping is accepted, reuse the returned public Calarax ping_id on POST https://lead-api.calarax.com/post. Any field marked Required on Ping must be included in the ping request, and Required on Post must be included in the post request.
For safe source-side testing, send data.Test_Mode = 1. Test-mode requests are accepted synthetically for validation and audit, and they never ping or post to downstream buyers.
Calarax may receive a separate downstream buyer promise token during buyer ping. That buyer token is different from the public Calarax ping_id returned to the source. Buyer post fields sourced from ping_response use the winning buyer's actual ping response, and bid extraction is configured in Buyer Delivery Setup with ping_response_settings.bid_path.

Field Requirements

These are the default system fields for this campaign, followed by your custom (non-system) fields from the database.

Field Type Required on Ping Required on Post Enum Values Description
ping_id string Optional Required -- Returned Ping ID from the Ping Post
SRC string Required Required -- Will be provided to you
KEY string Required Required -- Will be provided to you
Test_Mode string Optional Optional -- Optional source test flag. Send 1 for safe synthetic testing.
sub_id string Required Optional -- Publisher sub ID
pub_id string Required Optional -- Publisher ID
first_name string Optional Required -- Lead's first name
last_name string Optional Required -- Lead's last name
email string Required Required -- Lead email address
phone string Optional Required -- Lead phone number
zipcode string Required Required -- Lead ZIP code
street_address string Optional Required -- Lead street address
city string Required Required -- Lead city
state string Required Required -- Lead state
ip_address string Required Required -- Submitter IP address
user_agent string Required Optional -- Submitter user agent
trusted_form_url string Required Required -- TrustedForm or equivalent URL
jornaya_lead_id string Required Optional -- Jornaya lead ID
consent_text string Required Required -- Consent disclosure text
landing_page_url string Required Optional -- Landing page URL
unique_identifier string Required Optional -- Unique lead identifier

Ping/Post Flow

Ping

Evaluate a lead before you deliver the full payload.

  • Send a lightweight ping payload to POST https://lead-api.calarax.com/ping.
  • Calarax pings eligible buyers, stores every buyer ping response, and picks the winner using the configured routing mode.
  • If accepted, store the returned public Calarax ping_id and returned source payout bid when available.
  • If you send data.Test_Mode = 1, Calarax validates and returns a synthetic success without contacting any buyers.

Post

Deliver the full lead payload after an accepted ping.

  • Attach the accepted public Calarax ping_id.
  • Send the full lead data to POST https://lead-api.calarax.com/post.
  • Only the winning buyer receives the full post, and any ping_response mapping uses that buyer's actual ping response.
  • Receive delivered, rejected, or failed business status.
Token Distinction
  • The public Calarax ping_id is the source-facing token returned by POST https://lead-api.calarax.com/ping.
  • The downstream buyer may return its own promise token during buyer ping.
  • That downstream buyer promise is forwarded through Buyer Delivery Setup, not by adding extra top-level source payload fields.
  • The accepted ping response bid is the publisher payout returned to the source. Internal buyer bid and buyer price stay inside Calarax runtime and audit screens.

Example Requests

POST https://lead-api.calarax.com/ping
{
    "SRC": "SRC_MAIN",
    "KEY": "live_key_value",
    "data": {
        "sub_id": "publisher_123",
        "pub_id": "publisher_123",
        "email": "sam.carter@example.com",
        "phone": "3105550102",
        "zipcode": "90210",
        "state": "CA",
        "ip_address": "192.168.1.10",
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
        "trusted_form_url": "https://cert.trustedform.com/abc123",
        "jornaya_lead_id": "JRN-2D8BC3A4E5F6",
        "consent_text": "By clicking submit, I agree to be contacted.",
        "landing_page_url": "https://example.com/quote"
    }
}
To run a safe source test, add "Test_Mode": 1 inside the data object.
Ping Response
{
    "status": "accepted",
    "bid": 5.95,
    "ping_id": "PING-69AF38159B56A"
}
POST https://lead-api.calarax.com/post
{
    "SRC": "SRC_MAIN",
    "KEY": "live_key_value",
    "data": {
        "first_name": "Sam",
        "last_name": "Carter",
        "email": "sam.carter@example.com",
        "phone": "3105550102",
        "zipcode": "90210",
        "state": "CA",
        "city": "Los Angeles",
        "street_address": "123 Main St",
        "ip_address": "192.168.1.10",
        "trusted_form_url": "https://cert.trustedform.com/abc123",
        "consent_text": "By clicking submit, I agree to be contacted."
    },
    "ping_id": "PING-69AF38159B56A"
}
For ping/post test traffic, keep the public Calarax ping_id and include "Test_Mode": 1 inside data.
Post Response
{
    "status": "delivered",
    "lead_id": "L-5C8D9E0F1A2B3C",
    "delivery_id": "DEL-90AB12CD34EF56"
}

Error Codes

Status Code Meaning
200 rejected Business-level rejection such as campaign_inactive, source_cap_reached, schema_validation_failed, no_eligible_buyer, invalid_ping_id, or ping_id_already_consumed.
200 failed Business-level delivery failure such as buyer_delivery_failed, downstream_timeout, or downstream_invalid_response.
401 missing_credentials | invalid_key SRC and KEY are missing or the provided KEY does not match the credential.
403 credential_disabled The credential exists but is disabled for runtime traffic.
422 invalid_payload_shape The request body shape is malformed, for example when data is missing or is not a JSON object.
500 server_error Unexpected system failure while processing the runtime request.