CAcarecycle
Ping Post

Check availability before transferring a caller

Ask whether careCycle can take a live caller right now, before you transfer them. 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).

post/v2/ping

Request

  • Base URL
    https://api.carecycle.ai
  • URL
    https://api.carecycle.ai/v2/ping
  • Auth
    API key in header x-api-key

Request body

source_idstring required

Public source identifier assigned by careCycle

campaign_source_idstring uuid

Campaign-source assignment ID. Required when the source has more than one enabled live-call destination.

caller_idstring required

Phone number of the caller you intend to transfer (North American, with or without +1)

transfer_consenttrue required

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.

consent_basis'verbal_agreement' | 'caller_initiated' | 'pewc'

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.

sub_idstring

Optional vendor traffic granularity below the source

first_namestring
last_namestring
date_of_birthstring

YYYY-MM-DD preferred; alias: dob. Optional; age or birth year is enough for routing; send full DOB only if you already have it

dobstring
statestring

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

postal_codestring

5-digit postal code; alias: zip_code

zip_codestring
existing_coveragestring
household_incomestring
qualification_statusstring
filing_statusstring
dependentsstring
consent_timestampstring date-time

ISO timestamp of the caller's verbal transfer agreement

pewc_artifactstring

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_cert_urlstring

TrustedForm certificate URL of the originating web opt-in

truecall_idstring

ActiveProspect TrueCall ID proving consumer-initiated call

jornaya_leadidstring

Jornaya LeadiD token of the originating lead

agent_npnstring

NPN of the transferring licensed agent, when agent-initiated

Response

POST /v2/ping Positive response

agent_availableboolean required

Whether the call can be taken right now

numberstring nullable required
expires_in_secondsinteger nullable required
reason'caller_suppressed' | 'campaign_inactive' | 'no_agents_available' | 'after_hours' | 'no_live_coverage' | 'no_licensed_agents'

Machine-readable reason when agent_available is false

Changes

No recorded changes to this operation across all 2 revisions of this API.