# Ping-Post (/docs/guides/sources/ping-post) Ping-post gives your call vendors a way to ask "can you take this caller right now?" before they transfer. careCycle answers with a live yes or no and the number to send the caller to. Any caller details the vendor includes with the ping get saved, so when the call shows up a few seconds later, the customer record and the agent's screen are already filled in. Every ping is logged against the source. That means you can finally see which vendors send the callers they say they will, and which ones ping a lot but never follow through. **The flow, start to finish:** 1. The vendor pings careCycle with the caller's phone number and whatever qualification data they have, using an API key you give them. 2. careCycle checks whether the caller is suppressed and whether someone can answer. If the call can be accepted, it returns the source's tracking number. 3. The vendor transfers an accepted caller to that number. The arriving call links back to the ping automatically, so attribution, billing, and the pre-filled customer record all just work. Vendors can still transfer without pinging. Those calls follow normal inbound routing and suppression checks, with attribution by the tracking number. Pinging adds the availability check, the pre-filled records, and per-vendor conversion reporting on top. Setting up a vendor [#setting-up-a-vendor] Create the source [#create-the-source] Create a source for the vendor's traffic the same way you always have, either from the Sources page or through the [Create Source API](/docs/api-reference/sources/create-a-new-source). Creating a source with a live-call assignment in the app requests a `pingPostApiKey`. Through the API, set `createPingPostKey: true` to request one. Lead-only sources do not receive ping-post credentials automatically. This is the key you hand to the vendor. It can only call the ping endpoint, and only for this source. You'll see it exactly once, because we store keys hashed and can't show them again. Copy it right away. When creating a live-call source from campaign configuration, turn on **Create vendor ping-post key** to request credentials. Source creation shows the key once; select a tracking number and save the campaign assignment before vendors ping it. Tracking-number attribution without ping-post does not require this key. In the web app, the confirmation screen after creating a source shows everything the vendor needs in one place: the source ID, the tracking number if you assigned a campaign, the one-time API key, and a link to the integration guide. Copy the key before closing that dialog. Through the API, the key is the `pingPostApiKey` field on the create response. Missed the key? No need to recreate the source. Mint a replacement from **Settings > Developer > API Keys** with the ping-post permission scoped to the source. Configure a live-call assignment [#configure-a-live-call-assignment] Select **Live inbound calls** as the assignment's acquisition type and choose an existing campaign-owned tracking number. This works independently of the campaign's primary direction. The Receptionist is not available for source assignment. That tracking number is what the ping hands back to the vendor as the routing group. When a source has multiple enabled live-call assignments, send the destination's `campaign_source_id` with each ping. Copy the assignment ID from the source's assignment list. Omitting it in this case returns `400`, rather than choosing a campaign implicitly. If the source has no enabled inbound tracking number, pings for it return a `404`. Vendors usually report that as "source not found." Send the vendor their credentials [#send-the-vendor-their-credentials] The vendor needs three things from you. Share them over a secure channel, like a password manager share or an encrypted message. Not plain email. * Their **API key** (`cc_...`) * Their **source ID** (for example `ABC_K7H9M2NP`) * A link to the [Vendor Integration guide](/docs/guides/developers/ping-post-vendor-integration) Stick to one source and one key per vendor traffic source. It keeps reporting, pricing, and revocation clean for each relationship. Managing vendor keys [#managing-vendor-keys] Vendor keys are regular careCycle API keys with two restrictions built in: * **Permission:** ping-post only. The key can't read or write anything else in your account. If it ever leaks, the worst it can do is check availability. * **Source scope:** the key only works for the sources it's scoped to. Pinging any other source returns a `403`. Keys are organization credentials, not personal ones. They keep working when the employee who created them leaves your team, so vendor integrations survive staff changes. Revoking access is always per key, from Settings > Developer > API Keys. You manage them from **Settings > Developer > API Keys**: * **Rotate** by creating a new key scoped to the same source, handing it to the vendor, and deleting the old one once they've switched over. * **Revoke** by deleting or disabling the key. The vendor loses access immediately and the source itself is untouched. * **Vendors with multiple traffic sources** can share a single key scoped to several sources (or all of them), though separate keys keep revocation surgical if a relationship goes sideways. Suppressed callers [#suppressed-callers] When a vendor pings for a number on your suppression list, the response is HTTP `200` with: ```json { "agent_available": false, "number": null, "expires_in_seconds": null, "reason": "caller_suppressed" } ``` The vendor should not transfer that caller. This response means the number is blocked, even if your agents are available. An earlier available ping does not override a suppression added before the call arrives. If a number should be allowed again, an authorized team member can remove it from **Phone Suppressions**. See [Suppress Unwanted Callers](/docs/guides/phone-numbers/suppress-unwanted-callers). Watching vendor performance [#watching-vendor-performance] Source performance reporting includes a full ping funnel for every source, from the vendor's first ping all the way to the sale: | Metric | What it counts | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `pings_total` | Every ping the vendor sent | | `pings_available` | Pings we answered "yes, send the caller" | | `pings_dialed` | Available pings where the caller actually showed up | | `pings_billable` | Dialed pings whose call met your billing trigger, so you can reconcile what the vendor charges against what actually arrived | | `pings_converted` | Dialed pings whose caller went on to convert (a policy was created or a sale recorded) | | `ping_to_call_rate` | `pings_dialed / pings_available` | Conversions use cohort attribution: a conversion counts toward the ping that produced the caller, even if the sale closes after your report window ends. That keeps funnel percentages stable and comparable across vendors. On the Sources performance page, sources with ping traffic get a Pings column. Click it to open the ping activity view: volume and accept-rate charts over time, plus a table of every individual ping with its answer, decline reason, qualification fields, whether the caller arrived, and whether the call went billable and converted. The same data is available through the API as [List ping activity](/docs/api-reference/sources/list-ping-activity) if you'd rather pull it into your own reporting. How to read it: * **Low `ping_to_call_rate`** means the vendor pings but doesn't send the caller. Often they're shopping the caller to several buyers at once and losing races, or pinging speculatively. * **A wide gap between dialed and billable** means callers arrive but hang up before your billing threshold, a caller-quality signal worth raising with the vendor. * **A wide gap between billable and converted** means you are paying for calls that do not become business: the traffic connects but does not buy. Compare `pings_converted` across vendors before renewing anyone's budget. * **Calls with no pings** mean the vendor is transferring blind. They lose the customer pre-fill and risk dropping callers into closed hours. * **Lots of unavailable answers** deserve a look at the reasons. `caller_suppressed` means the number is on your suppression list, not that you need more agents. `no_agents_available` during business hours is a staffing signal. `after_hours` means the vendor sends traffic outside your coverage window, which is a good argument for after-hours AI coverage on that campaign. `no_licensed_agents` means the vendor sends states your team isn't licensed for, which is a conversation about their targeting, your hiring, or both. Ping sessions stay open for 30 minutes after we answer. Sessions that expire are your "pinged but never called" number. Controlling who answers a vendor's calls [#controlling-who-answers-a-vendors-calls] The availability answer is only as honest as the pool behind it, so the same controls that route real calls also shape ping answers: * **Per-agent source blocks.** If an agent shouldn't take calls from a specific vendor, block that source for them, either from the campaign's routing settings or straight from the Air Status board on the dialer wallboard (each agent and campaign cell has a Sources menu). Blocked agents don't ring for that source's calls, and they don't count toward its ping availability. If the only agent on air is blocked from the source, its pings get `no_agents_available`. * **Air status.** Agents taken off air for a campaign stop counting toward every source on it. * **State licensing.** If the campaign's routing is set to only ring state-licensed agents, a ping that includes the caller's `state` only gets a yes when someone licensed in that state is actually available. Otherwise the vendor sees `no_licensed_agents`. The setting lives in the campaign's agent routing, and agent licenses live on each member's profile. AI-answered numbers accept any state, since licensing is enforced when the AI hands the caller to a human. Compliance built in [#compliance-built-in] The ping flow is designed around the CMS rules for sharing beneficiary data between marketing organizations (42 CFR 422.2274): * **Consent attestation is required.** Every ping must carry `transfer_consent: true`, the vendor's attestation that a permitted basis applies: the caller verbally agreed to the transfer (to an agent or an IVR prompt), the caller dialed the number themselves (ad click-to-call routed straight through), or written consent naming your agency is on file. Vendors record which basis via `consent_basis`, and it's stored on every session for audits. Pings without the attestation are rejected. * **Failed pings are scrubbed, unless consent says otherwise.** When a ping never becomes a connected call, the caller's personal data (name, DOB, phone, qualification fields) is purged from the session after 72 hours: without a connection, there's no lawful basis to hold it, and the one thing you could do with it (call them back) is the exact move regulators flag. The exception is pings that carried written-consent evidence naming your agency (`pewc_artifact` or `consent_basis: "pewc"`): those callers consented to you having their data, so the sessions are retained as recoverable leads. Consent evidence and funnel metrics always survive the purge, and data from completed transfers stays with the call record it belongs to. * **Consent evidence rides along.** Vendors can attach `consent_timestamp`, PEWC references, TrustedForm certificates, TrueCall IDs, Jornaya LeadiDs, and the transferring agent's NPN. Everything lands on the ping session where you can produce it in a plan or CMS audit. The platform enforces the attestation and the data handling; the rest of TPMO oversight lives in your vendor agreements. Terms worth writing into them: * Pings carry only data the caller provided themselves, backed by the consent captured where they gave it (form consent for web-originated traffic). No appended or purchased data. * The licensed-agent transfer disclosure is delivered on the vendor's leg (agent script, or the IVR greeting on click-to-call routes), and recording disclosure on any leg they record. * Consent evidence (`consent_basis`, TrustedForm certificates, PEWC references) is sent with every ping so your audit trail builds itself. Your side of the call keeps the TPMO disclaimer and your own recording disclosure in the greeting flow. None of this is legal advice. Have your compliance counsel review your vendor contracts and consent capture before turning on live traffic. When a vendor reports a problem [#when-a-vendor-reports-a-problem] | Vendor sees | What's going on | What to do | | ------------------------ | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | Malformed request, or the `transfer_consent` attestation is missing | Vendor must obtain verbal transfer agreement and send `transfer_consent: true` | | `401` | Missing or invalid key, or the key lacks the ping-post permission | Re-issue the key from Settings > Developer > API Keys | | `403` | Their key isn't scoped to the source they pinged | Add the source to the key's scope, or issue a per-source key | | `404` | The source is inactive or has no enabled inbound tracking number | Activate the source or assign it to an inbound campaign | | `429` | They're over the per-key rate limit | Have them wait the `retryAfter` seconds from the response body; ask careCycle to raise the key's limit if the volume is legitimate | | `agent_available: false` | A real answer, not an error. Check the `reason` field | `no_agents_available`, `after_hours`, `campaign_inactive`, or `no_live_coverage` (the source's [resolved inbound route](/docs/guides/phone-numbers/how-inbound-calls-route) currently ends in voicemail) |