Ping-Post Vendor Integration

This guide is for call vendors who received a careCycle API key and source ID from an agency. The whole integration is one HTTP request before each transfer.

Here's the model: before you transfer a caller, you ping careCycle with the caller's phone number and any qualification data you have. The response tells you whether the call can be taken right now, and which number to send the caller to. The "post" is the call itself. When the caller arrives at that number within 30 minutes, it links back to your ping automatically. There's no token to echo and no second request to make.

The consent attestation

How you capture consent and what you disclose to callers is between you and the agency you work with; it's governed by your agreement with them, not by this API. What the API requires is an attestation on every ping that you have a permitted basis to connect this caller and share what you're sending:

• transfer_consent: true is required. Pings without it are rejected with a 400.
• consent_basis records which situation applies: verbal_agreement (the caller agreed to the transfer on the call), caller_initiated (the caller dialed a number that routes here, like an ad's click-to-call), or pewc (written consent naming the agency is on file). Recommended: the agency sees it per ping in their audit trail.
• The evidence fields (trustedform_cert_url, pewc_artifact, consent_timestamp, truecall_id, jornaya_leadid, agent_npn) let you attach whatever your agreement with the agency calls for.

What careCycle does with what you send: a ping reaches exactly one agency, and the payload is kept when the caller actually connects. Failed pings are scrubbed after 72 hours unless the ping carried written-consent evidence (pewc_artifact, or consent_basis: "pewc"), in which case the data is retained for the agency.

Authentication

Every request carries your API key in the x-api-key header. The key is scoped to your source(s) and can only call this endpoint.

x-api-key: cc_your_api_key

The ping request

POST https://api.carecycle.ai/v2/ping
Content-Type: application/json

Note that this is a POST with a JSON body. Caller names and dates of birth belong in the body, never in a URL where access logs would keep them.

Required fields

Optional fields

Numbers are fine where you'd expect strings ("postal_code": 33101 works). Fields we don't recognize are kept, so feel free to pass through whatever your system already knows about the caller. Everything you send pre-fills the customer record and shows up on the receiving agent's screen when the call connects.

Example

curl -X POST 'https://api.carecycle.ai/v2/ping' \
  -H 'x-api-key: cc_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "source_id": "ABC_K7H9M2NP",
    "caller_id": "+14039932200",
    "transfer_consent": true,
    "consent_basis": "caller_initiated",
    "trustedform_cert_url": "https://cert.trustedform.com/2605...",
    "sub_id": "fb-adset-42",
    "first_name": "Jane",
    "state": "FL",
    "postal_code": "33101"
  }'

The response

{
  "agent_available": true,
  "number": "+18005551234",
  "expires_in_seconds": 1800
}

{
  "agent_available": false,
  "number": null,
  "expires_in_seconds": null,
  "reason": "no_agents_available"
}

Errors

If you're getting a 403 or 404, contact the agency that issued your key. Those are configuration issues on their side, not transient errors worth retrying.

Transfer semantics

• Ping right before you transfer. The answer is a point-in-time availability check, not a reservation. An agent can get busy between a stale ping and a late transfer.
• Transfer from the number you pinged about. Matching is done by caller ID. If the caller arrives from a different number than the caller_id you sent, the call still gets answered, but your data won't attach to it.
• Re-pinging is safe. Pinging the same caller again refreshes your data and restarts the 30-minute window instead of creating duplicates. Retrying after a network error is safe for the same reason.
• Don't cache numbers. Tracking numbers are per-source and can change. Use the number from each ping.

Best practices

1. Send every qualification field you have. It lands on the agent's screen the moment the call connects, and the caller notices the difference. state matters most: buyers who route by agent licensure use it to check that someone licensed in the caller's state is actually available before saying yes. Without it, the availability answer can't account for licensing.
2. Use a distinct sub_id for each traffic source (campaign, ad set, placement). Agencies see quality per sub_id, and clean sub-IDs make budget conversations go your way.
3. Take agent_available: false at face value and route the caller to your fallback. If the reason is after_hours, nobody is going to pick up.
4. Alert on sustained 401 or 403 responses. Agencies can rotate or revoke keys, and catching that in minutes beats losing a day of traffic.

Full API reference

The machine-readable contract, with every field and response shape, lives in the Ping Post API reference.