Get started

DID monitoring checks your own phone numbers for spam and scam flags. You submit your numbers one time. CallerAPI checks each number on a schedule and keeps the last result. When a number becomes flagged, or becomes clean again, CallerAPI sends an event to your webhook.

You do not run the checks. You do not call an endpoint for each number. You read the results when you need them, and you get an event when a result changes.

What you need

Your API key from the dashboard. It is the same key as the rest of the CallerAPI API.

Credits on the account. Each check of a number uses 1 credit. See the Billing and limits page.

For webhooks, a paid plan and an HTTPS URL on port 443 or 8443. Webhooks are not available on the Free plan.

Authentication

Send your API key in the X-Auth header on every request.

X-Auth: YOUR_API_KEY

Base URL: https://api.callerapi.com/api/did-monitoring/v1

Every JSON response has "status": "success" with data, or "status": "error" with a message. A missing or wrong key returns 401 with an error field. See the Errors page.

Quick start

Step 1: submit your numbers

Send your numbers in E.164 format. You can send at most 100,000 numbers in one request.

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

Each new number starts as pending. CallerAPI checks new numbers in a first pass, at about 80 numbers a minute. After the first pass, CallerAPI checks each number one time a day. If you set a schedule in the dashboard before, CallerAPI keeps that schedule. To change the schedule, see Step 4.

Step 2: read the results

This request returns all your numbers with the result of the last check. It is the full result set. Webhooks send only changes.

{
  "status": "success",
  "data": {
    "counts": {"total": 1, "flagged": 1, "clean": 0, "pending": 0, "unknown": 0},
    "numbers": [
      {
        "phone": "+13058901598",
        "status": "flagged",
        "label": "Spam or scam risk",
        "status_changed_at": "2026-10-29T08:02:11Z",
        "last_checked_at": "2026-10-29T08:02:11Z",
        "next_check_at": "2026-10-30T00:00:00Z"
      }
    ],
    "next_cursor": null
  }
}

When next_cursor is not null, send it as cursor to get the next page. Add status=flagged to get only the flagged numbers. This request does not use credits.

The Statuses and labels page tells you what each status means.

Step 3: add a webhook

Save one HTTPS URL for the account.

{
  "status": "success",
  "data": {
    "url": "https://hooks.example.com/callerapi",
    "active": true,
    "secret": "whsec_REPLACE_WITH_YOUR_SECRET"
  }
}

Keep the secret in a safe place. CallerAPI shows it one time only. Use it to check the signature of each event.

Send a test event to your URL:

The response gives the HTTP status that your endpoint returned. The Webhooks page shows the events, the headers, and the signature check.

Step 4: set the check schedule (optional)

The default is one check a day, every day, in UTC. To check every hour, send this request:

The response contains a credit estimate for one month. More checks use more credits. See the Billing and limits page.

Endpoints

Method	Path	Purpose
POST	`/numbers`	Submit numbers
GET	`/numbers`	List number status
GET	`/numbers/{phone}`	Read one number
DELETE	`/numbers/{phone}`	Remove a number
GET	`/schedule`	Read the check schedule
PUT	`/schedule`	Set the check schedule
PUT	`/webhook`	Save the webhook URL
GET	`/webhook`	Read the webhook
DELETE	`/webhook`	Delete the webhook
POST	`/webhook/test`	Send a test event
POST	`/webhook/rotate-secret`	Rotate the webhook secret

All paths start with /api/did-monitoring/v1. Each endpoint page has the request fields, the response schema, and examples.

Where to go when something breaks

The Errors page lists what you see and what causes it. Read it before you open a support ticket.

What you need#

Authentication#

Quick start#

Step 1: submit your numbers#

Step 2: read the results#

Step 3: add a webhook#

Step 4: set the check schedule (optional)#

Endpoints#

Where to go when something breaks#