Check availability before transferring a caller
Ping before transferring a live caller to a source tracking number. Returns whether the call can be taken right now (agent_available) and the tracking number to transfer the caller to (number).
Availability is a real check: live agent presence, business hours, AI coverage, and per-agent source blocks. When the ping includes state and the destination routes by agent licensure, availability also requires an agent licensed in that state (declined as no_licensed_agents).
Include any qualification data you have (name, date of birth, state, postal code, etc.) in the JSON body. It is stored with the ping and used to pre-fill the customer record when the call arrives. Unrecognized body fields are preserved as additional customer data.
Requires an API key with the ping-post permission scoped to the pinged source (x-api-key header).
Authorization
x-api-key API key required for authentication.
Keys begin with 'cc_' prefix. Get your API key from the Developer Dashboard.
In: header
Request Body
application/json
POST /v2/ping Request body
TypeScript Definitions
Use the request body type in TypeScript.
Public source identifier assigned by careCycle
Phone number of the caller you intend to transfer (North American, with or without +1)
Attestation that a permitted consent basis applies: the caller verbally agreed to the transfer during the live call (agent script or IVR prompt), the caller placed this call themselves to be connected (direct dial / click-to-call), or prior express written consent naming the agency is on file. Required; pings without it are rejected.
Which basis applies: verbal_agreement (caller said yes to the transfer, to a human or an IVR prompt), caller_initiated (caller dialed a number that connects here), pewc (prior express written consent naming the agency). Strongly recommended for audit trails.
Optional vendor traffic granularity below the source
YYYY-MM-DD preferred; alias: dob. Optional; age or birth year is enough for routing; send full DOB only if you already have it
Two-letter state code. When the receiving campaign routes by agent licensure, availability is checked against agents licensed in this state; without it, the answer cannot account for licensing
5-digit postal code; alias: zip_code
ISO timestamp of the caller's verbal transfer agreement
Reference (URL or ID) to prior express written consent naming the receiving agency, when relying on PEWC instead of the live-transfer carve-out
TrustedForm certificate URL of the originating web opt-in
ActiveProspect TrueCall ID proving consumer-initiated call
Jornaya LeadiD token of the originating lead
NPN of the transferring licensed agent, when agent-initiated
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://api.carecycle.ai/v2/ping" \ -H "Content-Type: application/json" \ -d '{ "source_id": "string", "caller_id": "string", "transfer_consent": true, "property1": "string", "property2": "string" }'{
"agent_available": true,
"number": "string",
"expires_in_seconds": -9007199254740991,
"reason": "campaign_inactive"
}{
"message": "string",
"code": "string"
}{
"message": "string",
"code": "string"
}{
"message": "string",
"code": "string"
}{
"message": "string",
"code": "string"
}{
"message": "string",
"code": "VALIDATION_ERROR",
"errors": [
{
"path": [
"string"
],
"message": "string",
"expected": "string",
"received": "string",
"code": "string"
}
],
"failedRecords": [
{
"index": 0,
"phoneNumber": "string",
"firstName": "string",
"lastName": "string",
"externalId": "string"
}
]
}{
"message": "string",
"code": "string",
"retryAfter": 0
}{
"message": "string",
"code": "string"
}