Verify the calling number

POST

/api/bcid/v1/verify

Call this from the switch or SBC at INVITE, before the phone rings. Send the calling number and the called number. The response says whether the registered owner announced this exact call.

Verify is free for the telco. When the verdict is verified, the telco receives 1 credit. The business already paid 2 credits on announce.

Verdicts:

verified: the registered owner announced this call. Show the name, the mark, and the logo.

spoofed: the owner requires proof for every call from this number and none exists, or the number cannot place a call. Recommended action is drop.

unverified: the number is registered, the owner has not turned on enforcement, and this call carries no proof. Show the name only.

unregistered: nobody registered the number. Let the call through with no branding.

The called number is used for the binding check only. It is not stored and it is not returned. Do not put a business API key on the switch.

Request

Authorization

API Key

Add parameter in header

x-auth

Example:

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

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢200A verdict for this call

application/json

A verdict for this call. Verify is free. rewarded_credits is present on verified.

Bodyapplication/json

🟠400Missing or invalid from or to

🟠401Missing or wrong API key

🔴503Verification is not available

Request Example

Shell

JavaScript

Java

Swift

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

Response Example

200 - Example 1

{
    "status": "success",
    "data": {
        "from": "string",
        "verdict": "verified",
        "action": "allow",
        "reason": "string",
        "identity": {
            "verified": true,
            "name": "string",
            "logo_id": "string",
            "logo_url": "string"
        },
        "checked_at": "2019-08-24T14:15:22.123Z",
        "rewarded_credits": 0
    }
}

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

Read a verdict

Fetch the logo