Submit numbers

POST

/api/did-monitoring/v1/numbers

Adds phone numbers to monitoring. Send numbers in E.164 format. You can also send national numbers with default_country. Send at most 100,000 numbers in one request.

Each new number has the status pending. CallerAPI checks new numbers in a first pass, at about 80 numbers a minute. After the first pass, the check schedule sets when the next checks run.

If the account has no monitoring list, this request makes one with one check a day, every day, in UTC. If you set a schedule before, CallerAPI keeps it.

A number that the account monitors already counts as a duplicate. An input that is not a valid number goes into invalid with a reason code.

INFO

This request does not use credits. Each check of a number uses 1 credit. The number of monitored numbers cannot be more than the credits that your plan includes each month.

Request

Authorization

Body Params application/jsonRequired

Examples

Responses

🟢200OK

application/json

Bodyapplication/json

🟠400Bad request

🟠401Unauthorized

🟠403Requires upgrade

🟠404Not found

🟠429Too many requests

🔴503Service unavailable

Request Example

Shell

JavaScript

Java

Swift

curl --location 'https://api.callerapi.com/api/did-monitoring/v1/numbers' \
--header 'Content-Type: application/json' \
--data '{
    "numbers": [
        "+13058901598"
    ],
    "default_country": "US"
}'

Response Example

200 - added

{
    "status": "success",
    "data": {
        "added": 1,
        "duplicates": 0,
        "invalid": [],
        "monitoring": {
            "state": "scheduled",
            "schedule": "Every 24 hours",
            "next_check_at": "2026-10-30T00:00:00Z"
        }
    }
}

Modified at 2026-10-29 10:41:34

Errors

List number status