---
title: "Check availability before transferring a caller"
method: POST
path: "/v2/ping"
tags: ["Ping Post"]
---

# Check availability before transferring a caller

`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`

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).

## Request body

- PostV2PingRequestBody
  - `source_id` string, required: Public source identifier assigned by careCycle
  - `campaign_source_id` string, uuid: Campaign-source assignment ID. Required when the source has more than one enabled live-call destination.
  - `caller_id` string, required: Phone number of the caller you intend to transfer (North American, with or without +1)
  - `transfer_consent` true, 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_id` string: Optional vendor traffic granularity below the source
  - `first_name` string
  - `last_name` string
  - `date_of_birth` string: YYYY-MM-DD preferred; alias: dob. Optional; age or birth year is enough for routing; send full DOB only if you already have it
  - `dob` string
  - `state` string: 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_code` string: 5-digit postal code; alias: zip_code
  - `zip_code` string
  - `existing_coverage` string
  - `household_income` string
  - `qualification_status` string
  - `filing_status` string
  - `dependents` string
  - `consent_timestamp` string, date-time: ISO timestamp of the caller's verbal transfer agreement
  - `pewc_artifact` string: 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_url` string: TrustedForm certificate URL of the originating web opt-in
  - `truecall_id` string: ActiveProspect TrueCall ID proving consumer-initiated call
  - `jornaya_leadid` string: Jornaya LeadiD token of the originating lead
  - `agent_npn` string: NPN of the transferring licensed agent, when agent-initiated

## Response `200`

POST /v2/ping Positive response

- PostV2PingPositiveResponse
  - `agent_available` boolean, required: Whether the call can be taken right now
  - `number` string, nullable, required
  - `expires_in_seconds` integer, 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

## Other responses

- `400`: POST /v2/ping Negative response 400
- `401`: POST /v2/ping Negative response 401
- `403`: POST /v2/ping Negative response 403
- `404`: POST /v2/ping Negative response 404
- `409`: POST /v2/ping Negative response 409
- `422`: POST /v2/ping Negative response 422
- `429`: POST /v2/ping Negative response 429
- `500`: POST /v2/ping Negative response 500
- `502`: POST /v2/ping Negative response 502
- `503`: POST /v2/ping Negative response 503

---

[API](https://skmtc.dev/carecycle/apis/carecycle-public-api.md) - [All operations](https://skmtc.dev/carecycle/apis/carecycle-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/carecycle/apis/carecycle-public-api/revisions/db390c743c36?raw)