Announce a call

POST

/api/bcid/v1/calls

Call this from the originating dialler at dial time. This is an HTTP request. It is not a SIP header.

Auth is X-BCID-Publish-Token, not the API key. Get the token from the dashboard. It is shown once. Do not put the token in a SIP header. Do not send it to the terminating switch.

The business pays 2 credits for a signed announcement. from must be an approved number you own. to binds the announcement to this callee, then CallerAPI drops it. The announcement is valid for 90 seconds.

A number still in review returns 403. Not enough credits returns 402. A deployment that cannot sign returns 503.

Request

Authorization

API Key

Add parameter in header

x-auth

Example:

x-auth: ********************

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢200Announcement stored

application/json

The announcement is stored. The business paid 2 credits. The terminating switch can verify this call until expires_at.

Bodyapplication/json

🟠400Missing or invalid from or to

🟠401Missing or invalid publish token

🟠403Number not approved or not yours

🔴503Announcement is not available

🟠402Insufficient credits

Request Example

Shell

JavaScript

Java

Swift

curl --location 'https://api.callerapi.com/api/bcid/v1/calls' \
--header 'X-BCID-Publish-Token: YOUR_PUBLISH_TOKEN' \
--header 'x-auth: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
  "from": "+18883578668",
  "to": "+14155550123"
}'

Response Example

200 - Example 1

{
    "status": "success",
    "data": {
        "expires_at": "2019-08-24T14:15:22.123Z",
        "valid_for_seconds": 0,
        "credits_charged": 0
    }
}

Modified at 2026-09-21 16:59:03

Fetch the logo

Signer reputation by SPC