Ping for a bid · InboundX docs

Endpoint

GETPOSThttps://app.inboundx.io/api/rtb/ping

Send the parameters in the query string, as a form, or as JSON. Names aren't case-sensitive. When a name is in both the query string and the body, the query string wins.

curl -X POST "https://app.inboundx.io/api/rtb/ping" \
  -d "key=YOUR_PING_KEY" \
  -d "caller_number=+15555550123" \
  -d "caller_state=TX" \
  -d "request_id=abc-123"

Parameters

Parameter	Also accepted	Required	Max length	What it is
`key`	None	Yes	128 characters	Your ping key for this campaign.
`caller_number`	`caller_idcalleridfromani`	Yes	64 characters	The caller's phone number, ideally with the country code. We match the call to its bid by this number when it arrives.
`request_id`	`ringba-requestidringba_requestidcall_idcallidsourcecallidsource_call_idtraceexternal_idclickid`	Recommended	512 characters	Your own ID for this call. We send it back in your postback as `{CALL_ID}`, and a repeat ping with the same ID gets the same bid back.
`caller_zip`	`zipzipcodezip_codepostal_codeinboundzipcode`	Recommended	16 characters	The caller's five-digit ZIP code (ZIP+4 is fine; we keep the first five). If you don't send a state we can read, the zip decides it before the area code does.
`caller_state`	`state`	Optional	32 characters	The caller's US state: its two-letter code or its full name ("TX" or "Texas"). If you leave it out, or we can't read it, we work it out from the zip, then from the area code.
`publisher_id`	`publisherafid`	Optional	128 characters	Your publisher ID. When you send it, it must match the key.
`caller_city`	`city`	Optional	64 characters	The caller's city, shown on the call. Letters, spaces and `.'-` only, up to 64 characters.
`caller_npa_nxx`	`npanxxcaller_prefix`	If the campaign asks for it	128 characters	The first three or six digits of the caller's number. Shown for context only; a call is never matched by it.
`age`	`caller_age`	If the campaign asks for it	128 characters	The caller's age, a whole number from 18 to 120.
`dob`	`date_of_birth`	If the campaign asks for it	128 characters	The caller's date of birth, as year-month-day or month/day/year. The agent sees the age, not the date.
`homeowner`	`home_ownerowns_home`	If the campaign asks for it	128 characters	Whether the caller owns their home: yes or no.
`insured`	`currently_insuredhas_insurance`	If the campaign asks for it	128 characters	Whether the caller has insurance now: yes or no.
`current_carrier`	`current_insurer`	If the campaign asks for it	128 characters	The caller's current insurer, up to 64 characters.
`debt_amount`	`unsecured_debtdebt`	If the campaign asks for it	128 characters	The caller's debt, in whole dollars. A dollar sign and thousands separators are fine.
`destination_zip`	`to_zipmove_to_zip`	If the campaign asks for it	128 characters	Where the caller is moving to: a five-digit ZIP code.
`loan_amount`	`mortgage_balance`	If the campaign asks for it	128 characters	The loan or mortgage balance, in whole dollars.
`accident_date`	`incident_date`	If the campaign asks for it	128 characters	The date of the accident, as year-month-day or month/day/year.
`has_attorney`	`attorneyrepresented`	If the campaign asks for it	128 characters	Whether the caller already has an attorney: yes or no.
`trusted_form_cert_url`	`trustedform_cert_urltrusted_form_certtrusted_formtrustedformxxtrustedformcerturl`	If the campaign asks for it	128 characters	The address of the caller's consent certificate, on https. Kept with the call for the buyer; never shown to the agent.
`jornaya_leadid`	`jornaya_lead_idjornayaleadidjleadidleadid_tokenuniversal_leadid`	If the campaign asks for it	128 characters	Your lead's universal ID. Kept with the call; never shown to the agent.
`sub_id`	`subidsub1source_id`	If the campaign asks for it	128 characters	Your own ID for the traffic source, up to 128 characters. Kept with the call; never shown to the agent.

The bid

Repeat pings for the same caller and campaign reuse the active bid. Holds default to 15 seconds; a campaign may use 10–30 seconds. Always dial before expires_at. During a database interruption, a clean no-target response is returned within one second. Optional traffic shields may reduce bids from sources that send pings without calls.

JSON · 200 · reserved

{
  "uuid": "3f1c2a4e-9b7d-4c1e-8a2f-5d6b7c8e9f01",
  "status": "reserved",
  "payout": 45,
  "seconds": 60,
  "sip_address": "inboundx@inboundx.sip.telnyx.com",
  "expires_at": "2026-01-15T17:30:15.000Z",
  "caller_number": "+15555550123"
}

Field	What it is
`uuid`	The bid's ID.
`status`	Always `reserved` on a bid.
`retreaver_payout`	What the call pays, in US dollars. The same number as `payout`, present only for Retreaver or unknown/legacy connection platforms.
`retreaver_seconds`	How long the call must last to pay, in seconds. The same number as `seconds`, present only for Retreaver or unknown/legacy connection platforms.
`payout`	What the call pays, in US dollars.
`seconds`	How long the call must last to pay, in seconds.
`sip_address`	Where to send the call. Dial it exactly as it is.
`expires_at`	When the hold ends. Send the call before then.
`caller_number`	The caller's number as we read it. Compare it with yours to catch a formatting problem.

Every bid includes payout and seconds. Retreaver connections also receive retreaver_payout and retreaver_seconds with the same values. Connections without a known saved platform keep both sets for compatibility; all other selected platforms receive only the neutral fields. The platform is chosen by your buyer on your connection, not by a ping parameter.

Transfer timing

Transfer the call before the bid's expires_at. If you can't, don't send the call on that bid: once it has expired, ping again right before you transfer. A new ping costs nothing and won't double-book the caller.

No bid

When we can't take the caller, the answer is still HTTP 200:

JSON · 200 · no-target

{
  "status": "no-target",
  "reason": "state_not_covered"
}

Don't send the call. Ping again for your next caller.

Every reason, and what to do

A no-bid carries a reason. Your ping log in the portal shows the same decline in plain words. The reasons fall into three groups.

Something to fix on your side

Your ping log shows	Reason	Class	What to do
Ping key missing	missing_key	Technical	Send your ping key as `key`.
Caller state not valid	bad_caller_state	Technical	Send the state as two letters or its full name, or leave it out and we'll work it out from the zip, then the number.
Ping key not recognised	unknown_key	Technical	Check the key. Each campaign has its own, so ask your buyer if you're not sure which one to use.
Ping key does not match that account	publisher_mismatch	Technical	The publisher ID you sent isn't the one this key belongs to. Fix it, or leave it out.
Account not active	publisher_inactive	Technical	Your account with this buyer is switched off. Ask your buyer.
Account not set up to receive traffic	publisher_no_campaign	Technical	This key has no campaign behind it yet. Ask your buyer.
Not buying right now	campaign_inactive	Technical	The buyer isn't taking calls on this campaign right now. Ask them when it starts again.
Campaign not live yet	offer_not_live	Technical	This campaign isn't live yet. Your buyer turns it on when your setup is ready.
Campaign paused	offer_paused	Technical	Your buyer has paused this campaign. Ask them when it starts again.
Unknown state	no_caller_state	Technical	Use a US caller number with a US area code. Anonymous, toll-free and non-US callers cannot be routed on an all-states line.
Caller number missing	no_caller_number	Technical	Send the caller's number as `caller_number`.
Caller not accepted	caller_blocked	Technical	This caller isn't accepted. Don't send them again.
State not accepted	state_not_covered	Capacity	We don't take callers from this state on this campaign. Don't send callers from it.
Zip code needed for this campaign	no_caller_zip	Capacity	This campaign buys calls by zip code. Send the caller's zip as `caller_zip`.
Zip code not accepted	zip_not_covered	Capacity	We don't take callers from this zip code on this campaign. Don't send callers from it.
Caller already on a call with us	caller_on_live_call	Capacity	This caller is already on a call with us. Send each caller once.
At-once cap reached	cap_concurrent	Capacity	You've reached this campaign's limit on calls at once. Ping again when one of your calls ends.
Hourly cap reached	cap_hourly	Capacity	You've reached this campaign's limit for this hour. It resets at the top of the hour, on your buyer's clock.
Daily cap reached	cap_daily	Capacity	You've reached this campaign's limit for today. It resets at midnight, on your buyer's clock.
Bid expired before the call arrived	no_reservation_for_caller	Capacity	The call arrived with no bid held for it: the bid had expired, or the caller ID wasn't the caller's own number. Send the call within 15 seconds of the bid, with the caller's number as the caller ID.
Caller state missing or not valid	missing_caller_state	Technical	This campaign needs this field in every ping. Send it as `caller_state`, or ask your buyer whether it can be left out.
Call ID missing	missing_trace	Technical	This campaign needs this field in every ping. Send it as `ringba-requestid`, or ask your buyer whether it can be left out.
Zip code missing or not valid	missing_zip	Technical	This campaign needs this field in every ping. Send it as `caller_zip`, or ask your buyer whether it can be left out.
City missing or not valid	missing_city	Technical	This campaign needs this field in every ping. Send it as `caller_city`, or ask your buyer whether it can be left out.
Partial caller number missing or not valid	missing_caller_number_partial	Technical	This campaign needs this field in every ping. Send it as `caller_npa_nxx`, or ask your buyer whether it can be left out.
Age missing or not valid	missing_age	Technical	This campaign needs this field in every ping. Send it as `age`, or ask your buyer whether it can be left out.
Date of birth missing or not valid	missing_dob	Technical	This campaign needs this field in every ping. Send it as `dob`, or ask your buyer whether it can be left out.
Homeowner answer missing	missing_homeowner	Technical	This campaign needs this field in every ping. Send it as `homeowner`, or ask your buyer whether it can be left out.
Insurance answer missing	missing_insured	Technical	This campaign needs this field in every ping. Send it as `insured`, or ask your buyer whether it can be left out.
Current insurer missing	missing_current_carrier	Technical	This campaign needs this field in every ping. Send it as `current_carrier`, or ask your buyer whether it can be left out.
Debt amount missing or not valid	missing_debt_amount	Technical	This campaign needs this field in every ping. Send it as `debt_amount`, or ask your buyer whether it can be left out.
Destination zip code missing or not valid	missing_destination_zip	Technical	This campaign needs this field in every ping. Send it as `destination_zip`, or ask your buyer whether it can be left out.
Loan amount missing or not valid	missing_loan_amount	Technical	This campaign needs this field in every ping. Send it as `loan_amount`, or ask your buyer whether it can be left out.
Accident date missing or not valid	missing_accident_date	Technical	This campaign needs this field in every ping. Send it as `accident_date`, or ask your buyer whether it can be left out.
Attorney answer missing	missing_has_attorney	Technical	This campaign needs this field in every ping. Send it as `has_attorney`, or ask your buyer whether it can be left out.
Consent certificate missing or not valid	missing_consent_cert_url	Technical	This campaign needs this field in every ping. Send it as `trusted_form_cert_url`, or ask your buyer whether it can be left out.
Lead ID missing or not valid	missing_lead_id	Technical	This campaign needs this field in every ping. Send it as `jornaya_leadid`, or ask your buyer whether it can be left out.
Sub ID missing	missing_sub_id	Technical	This campaign needs this field in every ping. Send it as `sub_id`, or ask your buyer whether it can be left out.

No capacity right now

We couldn't take this caller at this moment. Nothing is wrong with your setup: ping again for your next caller. Your ping log shows all of these as “No capacity”.

campaign_no_rosternoise_shieldclaim_throttledempty_rosterno_agent_onlineno_eligible_agentalready_reservedall_candidates_leasedno_agentno_capacity

no_capacity means your buyer can't take calls right now for a reason on their side. Send the caller to your next buyer, and ping this one again later.

A problem on our side

Something failed on our side. Your ping log shows all of these as “Temporarily unavailable”. Ping again. If it keeps happening, check the status page and tell your buyer.

lookup_failedingress_not_configuredcampaign_missingdb_budget_exceededdb_circuit_openinternal_errortrace_reused_for_different_callerbad_ttlcampaign_not_foundreserve_failednot_reserved

Answers and limits

200 · reserved

A bid. Send the call to sip_address before its expiry. The default hold is 15 seconds; your campaign may allow longer.

200 · no-target

No bid, with a reason. Don't send the call.

Same call ID, same caller

Returns the same bid, so a retry is safe.

Value too long

Cut to the parameter's max length above, then validated.