ads
POST /v1/ads/connections/{connection_id}/call-numbers
Buy one tracking number that forwards to the customer's own number (za-160).
Authentication
Send an API key as a bearer token. The key must carry the ads.manage permission; a key without it is refused with 403, not 404.
This endpoint takes no organisation id. Your key already identifies the organisation it belongs to, and the response is scoped to it.
Try it
Replace anything in angle brackets with your own values, and the key placeholder with a key from your dashboard.
curl -X POST https://api.zinndigital.com/v1/ads/connections/{connection_id}/call-numbers \
-H "Authorization: Bearer zdk_live_…" \
-H "Content-Type: application/json" \
-d '{ "phone_number": <string>, "forward_to": <string> }'Signed in? The API console in your dashboard fills in your real organisation id and your own key, and runs the request against the live API so you can see the actual response. Open this endpoint in the API console
Details
Gated on ads.manage; audit action ads.call_number_ordered (no phone number in its metadata). The price is the voice vendor's own answer for that number, re-read now, times the platform margin; the first charge (the vendor's upfront fee plus the first month, both taken by the vendor at purchase) is taken from the org's prepaid Zinn® credit BEFORE the order and returned if the vendor refuses it. Refused (422) when call tracking is not open (callNotOpen), the CRM source telnyx is not set up (callNoSource), the forward-to number is not a United States number or is one of our own tracking numbers (a call loop, callForwardToNotOffered), the account holds its cap (callTooMany), the account is not in good standing (callAccountOnHold), the credit is short (callNoCredit), the only credit left is AI Hosting plan-included credit, which pays for AI Hosting only (callPlanCreditsOnly, 402), the number was taken (callNumberGone) or its price is no longer the first_month_usd_micros the customer was shown (callPriceChanged, nothing charged). An order the vendor has not finished yet leaves the number ordering and starts the account's number sweep at once (retried until it completes); a vendor that does not answer the order leaves it ordering too: it is found by its reference, or refunded.
Parameters
| Name | Type | Required | What it is |
|---|---|---|---|
connection_id (path) | string | Yes | — |
Request body
| Name | Type | Required | What it is |
|---|---|---|---|
phone_number | string | Yes | E.164 |
forward_to | string | Yes | The customer's own US number |
name | string | No | — |
first_month_usd_micros | integer | No | The first-month price the customer was shown by searchAdsCallNumbers (USD micros). A different price now is refused (callPriceChanged), never charged. |
Response
| Name | Type | Required | What it is |
|---|---|---|---|
id | string | Yes | — |
connection_id | string | Yes | — |
name | string | Yes | — |
phone_number | string | Yes | — |
country | string | Yes | — |
forward_to | string | Yes | Where calls are forwarded; "" = forwarding switched off (calls refused unanswered). |
status | string<ordering, active, suspended, releasing, released, failed> | Yes | — |
monthly_usd_micros | integer | Yes | — |
paid_through | string | Yes | — |
suspended_at | string | Yes | — |
calls | integer | Yes | — |
refused_calls | integer | Yes | — |
ordered_at | string | Yes | — |
released_at | string | Yes | — |
Errors this endpoint can return
401 · 403 · 404 · 422 · 429