Each monitored number has one status and one label. The status is for your code. The label is a short text for a person. Both come from the last check of the number.Statuses#
status | label | Meaning | What to do |
|---|
pending | Waiting for first check | CallerAPI stored the number. The first check did not run yet. | Wait. The first pass checks about 80 numbers a minute. |
clean | No flags | The last check found no spam or scam flag. | Nothing. |
flagged | Spam or scam risk | The last check found a spam or scam flag on the number. | Examine the calls from this number. |
unknown | Check failed, retrying | The last check did not finish. | Wait. The number gets a new check in the next pass. |
The label for flagged is always "Spam or scam risk". The API does not tell you which kind of flag it found.Use the status field in your code. Do not parse the label. A label can change. A status value does not change.Times on each number#
| Field | Meaning |
|---|
last_checked_at | When the last check finished. null before the first check. |
status_changed_at | When the number last became flagged, or became clean after a flag. null if this did not occur. |
next_check_at | When the next scheduled pass starts. null when scheduled checks are off or paused. |
All times are RFC 3339 in UTC.When the status changes#
| From | To | Webhook event |
|---|
pending, clean, or unknown | flagged | number.flagged |
flagged | clean | number.cleared |
pending | clean | None |
| Any status | unknown | None |
unknown | clean | None |
A number that goes from flagged to unknown and then to clean does not send number.cleared. Send GET /api/did-monitoring/v1/numbers to get the current status of all numbers. Use status=flagged to get only the flagged numbers.Monitoring state#
The submit and schedule responses have a state. It tells you if scheduled checks run.state | Meaning |
|---|
scheduled | Scheduled checks are on. The next pass waits for its time. |
checking | A pass runs now. |
paused | Checks stopped. The account has no credits left, or the schedule uses more credits than the plan includes. See the Billing and limits page. |
off | Scheduled checks are off. New numbers still get their first check. |
Modified at 2026-10-29 10:43:45
