Spam monitoring

The Spam Monitoring API watches your outbound phone numbers and tells you when a carrier starts flagging them as spam or scam-likely. OptimalDial places periodic test calls to each monitored number across the major US carriers (AT&T, T-Mobile, Verizon), records the label each carrier shows, captures a screenshot, and exposes the result through these endpoints — or pushes it to you over webhooks. It’s available to every account with an API key and an active subscription. Standard rate limits and the 429 envelope apply, exactly as on the rest of the v1 API.

Lifecycle

POST /api/v1/spam/numbers — add a number. Verification is auto-initiated (a call or SMS to the number).
The recipient reads back the code; you submit it to POST /api/v1/spam/numbers/{id}/verify. Missed it? …/verify/resend.
Once verified, OptimalDial re-tests the number daily across each carrier.
You read results via GET /api/v1/spam/numbers / …/{id} (latest per-carrier status), …/{id}/history (recent runs), and …/{id}/screenshot (the captured image) — or subscribe to the spam.detected and number.verified webhook events.

The MonitoredNumber object

Field	Type	Notes
`id`	string (UUID)	Stable identifier.
`phone_number`	string	E.164-normalized phone (US/CA only).
`verified`	boolean	Whether the number completed verification. Monitoring runs only for verified numbers.
`carrier`	string \| null	The number’s own carrier, when known. Used to flag same-carrier tests.
`same_carrier_warning`	boolean	`true` when a test ran from the same carrier as the number, which can skew the result. Treat such results with care.
`status`	`"active"` \| `"paused"`	Whether monitoring is currently running for this number.
`created_at`	string (ISO 8601)	UTC timestamp.
`updated_at`	string (ISO 8601) \| null	UTC timestamp of the last change.
`carrier_statuses`	CarrierStatus[]	Latest status for each carrier tested. See below.

The CarrierStatus object

Field	Type	Notes
`carrier`	string	Carrier this row applies to — one of `at&t`, `t-mobile`, `verizon`.
`status`	`"pending"` \| `"running"` \| `"completed"` \| `"failed"`	State of the latest test for this carrier.
`spam_detected`	boolean \| null	Whether the number was flagged on this carrier. `null` until the latest run completes.
`spam_label`	string \| null	The carrier-displayed label (e.g. `"Scam Likely"`), when flagged.
`test_run_id`	string \| null	The run that produced this status.
`captured_at`	string (ISO 8601) \| null	When the latest result was captured.
`screenshot_available`	boolean	Whether a screenshot can be fetched for this carrier’s latest run.

Verification (SMS or call)

Verification is required for the monitoring service to function — OptimalDial must verify the number before it can place test calls on its behalf. It is not an ownership or security gate; it’s a carrier prerequisite for the test traffic.

The add endpoint auto-initiates verification. By default it places a call (verification_method: "call"); pass "sms" to receive a text instead.
The recipient reads back (or copies) the code and you submit it to …/verify.
SMS isn’t deliverable to landlines. Requesting "sms" for a non-SMS-capable number returns 400 — fall back to call.
Use …/verify/resend to re-send the code, optionally switching method (e.g. from sms to call).

A number’s verified flag flips to true once a correct code is submitted, and the number.verified webhook fires.

Add a monitored number

POST /api/v1/spam/numbers

Registers a number for monitoring and auto-sends a verification code. Returns 201 with the new MonitoredNumber and a verification block describing how the code was dispatched.

Request body

Field	Type	Required	Notes
`phone_number`	string	yes	Any common format. Normalized to E.164. Must be US or Canadian.
`verification_method`	`"call"` \| `"sms"`	no	How to deliver the code. Defaults to `call`. `sms` is only valid for SMS-capable numbers.

cURL
Node.js
Python

curl -X POST https://api.optimaldial.com/api/v1/spam/numbers \
  -H "Authorization: Bearer $OPTIMALDIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+15551234567",
    "verification_method": "call"
  }'

const res = await fetch("https://api.optimaldial.com/api/v1/spam/numbers", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OPTIMALDIAL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phone_number: "+15551234567",
    verification_method: "call",
  }),
});
const { number, verification } = await res.json();
// Tell the recipient: verification.instructions

resp = requests.post(
    "https://api.optimaldial.com/api/v1/spam/numbers",
    headers={
        "Authorization": f"Bearer {os.environ['OPTIMALDIAL_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "phone_number": "+15551234567",
        "verification_method": "call",
    },
)
data = resp.json()
number, verification = data["number"], data["verification"]

Response

201 Created:

{
  "number": {
    "id": "7c2a1f0e-9b3d-4a8e-bf21-0c5d6e7f8a90",
    "phone_number": "+15551234567",
    "verified": false,
    "carrier": null,
    "same_carrier_warning": false,
    "status": "active",
    "created_at": "2026-06-26T15:04:01+00:00",
    "updated_at": null,
    "carrier_statuses": []
  },
  "verification": {
    "required": true,
    "sent": true,
    "method": "call",
    "instructions": "We're calling +15551234567 now. Enter the 6-digit code the call reads out to finish verification.",
    "error": null
  }
}

Errors

Status	When
`400`	Phone is unparseable/not US-CA, or `verification_method: "sms"` was requested for a non-SMS-capable (landline) number
`401`	Auth failure
`403`	No active subscription, or your plan’s spam-monitoring number limit is reached
`409`	This number is already monitored in your organization
`429`	Rate limit hit

Submit a verification code

POST /api/v1/spam/numbers/{number_id}/verify

Submits the code the recipient received. On success the number becomes verified and daily monitoring begins.

Request body

Field	Type	Required	Notes
`code`	string	yes	The code from the verification call or SMS.

cURL
Node.js
Python

curl -X POST "https://api.optimaldial.com/api/v1/spam/numbers/$NUMBER_ID/verify" \
  -H "Authorization: Bearer $OPTIMALDIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

const res = await fetch(
  `https://api.optimaldial.com/api/v1/spam/numbers/${numberId}/verify`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.OPTIMALDIAL_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ code: "123456" }),
  },
);

requests.post(
    f"https://api.optimaldial.com/api/v1/spam/numbers/{number_id}/verify",
    headers={
        "Authorization": f"Bearer {os.environ['OPTIMALDIAL_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={"code": "123456"},
)

Response

{
  "success": true,
  "verified": true,
  "phone_number": "+15551234567",
  "message": "Number verified. Daily spam monitoring is now active."
}

Errors

Status	When
`400`	Code is incorrect, or the number is already verified
`401`	Auth failure
`404`	Number not found, or belongs to another organization
`429`	Rate limit hit

Resend a verification code

POST /api/v1/spam/numbers/{number_id}/verify/resend

Re-sends the code, optionally switching delivery method. Use this if the first call/SMS was missed, or to fall back to call when sms couldn’t be delivered.

Request body (optional)

Field	Type	Required	Notes
`method`	`"call"` \| `"sms"`	no	Delivery method for the re-sent code. Defaults to `call`.

curl -X POST "https://api.optimaldial.com/api/v1/spam/numbers/$NUMBER_ID/verify/resend" \
  -H "Authorization: Bearer $OPTIMALDIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method": "sms"}'

Response

{
  "success": true,
  "phone_number": "+15551234567",
  "method": "sms",
  "message": "A new code is on its way by SMS."
}

Errors

Status	When
`401`	Auth failure
`404`	Number not found, or belongs to another organization
`429`	Rate limit hit
`502`	The verification could not be sent — retry, or switch `method`

List monitored numbers

GET /api/v1/spam/numbers

Returns your monitored numbers, each with its latest per-carrier status, plus the maximum your plan allows.

Query parameters

Param	Type	Default	Notes
`limit`	integer (1–500)	100	Page size.
`offset`	integer (≥0)	0	Number of rows to skip.

curl "https://api.optimaldial.com/api/v1/spam/numbers?limit=100&offset=0" \
  -H "Authorization: Bearer $OPTIMALDIAL_API_KEY"

Response

{
  "numbers": [
    {
      "id": "7c2a1f0e-9b3d-4a8e-bf21-0c5d6e7f8a90",
      "phone_number": "+15551234567",
      "verified": true,
      "carrier": "verizon",
      "same_carrier_warning": false,
      "status": "active",
      "created_at": "2026-06-26T15:04:01+00:00",
      "updated_at": "2026-06-26T15:09:42+00:00",
      "carrier_statuses": [
        {
          "carrier": "at&t",
          "status": "completed",
          "spam_detected": false,
          "spam_label": null,
          "test_run_id": "run_8f1c…",
          "captured_at": "2026-06-26T15:08:10+00:00",
          "screenshot_available": true
        },
        {
          "carrier": "t-mobile",
          "status": "completed",
          "spam_detected": true,
          "spam_label": "Scam Likely",
          "test_run_id": "run_8f1d…",
          "captured_at": "2026-06-26T15:08:55+00:00",
          "screenshot_available": true
        },
        {
          "carrier": "verizon",
          "status": "running",
          "spam_detected": null,
          "spam_label": null,
          "test_run_id": "run_8f1e…",
          "captured_at": null,
          "screenshot_available": false
        }
      ]
    }
  ],
  "total": 12,
  "spam_monitoring_limit": 20
}

spam_monitoring_limit is your effective limit: the numbers included with your plan plus any additional numbers purchased at $5/month each. It is null when your plan (or an admin account) has no cap. Adding a number beyond this limit returns 403. Numbers already monitored beyond the limit (for example after a downgrade) are kept but not tested — the oldest numbers up to the limit are the ones that receive daily tests. Owners can raise the limit from Billing → Spam Monitoring Add-On in the dashboard.

Errors

Status	When
`401`	Auth failure
`403`	No active subscription on the organization
`429`	Rate limit hit

Retrieve a monitored number

GET /api/v1/spam/numbers/{number_id}

Returns a single MonitoredNumber with its latest per-carrier status.

curl "https://api.optimaldial.com/api/v1/spam/numbers/$NUMBER_ID" \
  -H "Authorization: Bearer $OPTIMALDIAL_API_KEY"

Errors

Status	When
`401`	Auth failure
`403`	No active subscription on the organization
`404`	Number not found, or belongs to another organization
`429`	Rate limit hit

List recent test runs

GET /api/v1/spam/numbers/{number_id}/history

Returns the number’s individual test runs from the last 7 days, newest first. Each row is one carrier’s test on one day.

curl "https://api.optimaldial.com/api/v1/spam/numbers/$NUMBER_ID/history" \
  -H "Authorization: Bearer $OPTIMALDIAL_API_KEY"

Response

{
  "number_id": "7c2a1f0e-9b3d-4a8e-bf21-0c5d6e7f8a90",
  "phone_number": "+15551234567",
  "results": [
    {
      "test_run_id": "run_8f1d…",
      "carrier": "t-mobile",
      "status": "completed",
      "spam_detected": true,
      "spam_label": "Scam Likely",
      "sip_response_code": "200",
      "caller_id_verified": false,
      "screenshot_available": true,
      "tested_at": "2026-06-26T15:08:55+00:00"
    },
    {
      "test_run_id": "run_8e90…",
      "carrier": "t-mobile",
      "status": "completed",
      "spam_detected": false,
      "spam_label": null,
      "sip_response_code": "200",
      "caller_id_verified": true,
      "screenshot_available": true,
      "tested_at": "2026-06-25T15:07:11+00:00"
    }
  ],
  "total": 9
}

The TestRunHistoryItem object

Field	Type	Notes
`test_run_id`	string	Identifier for this carrier-test run.
`carrier`	string	Carrier tested (e.g. `at&t`, `t-mobile`, `verizon`).
`status`	`"pending"` \| `"running"` \| `"completed"` \| `"failed"`	State of this run.
`spam_detected`	boolean \| null	Whether the number was flagged on this run.
`spam_label`	string \| null	The carrier-displayed label, when flagged.
`sip_response_code`	string \| null	SIP response observed on the test call (e.g. `"200"`, `"603"`).
`caller_id_verified`	boolean \| null	Whether the carrier showed the number as a verified caller ID (STIR/SHAKEN).
`screenshot_available`	boolean	Whether a screenshot can be fetched for this run.
`tested_at`	string (ISO 8601)	When the test ran.

Errors

Status	When
`401`	Auth failure
`403`	No active subscription on the organization
`404`	Number not found, or belongs to another organization
`429`	Rate limit hit

Get the latest screenshot

GET /api/v1/spam/numbers/{number_id}/screenshot

Streams the most recent captured screenshot for the number as a binary image/jpeg — not JSON. Pass carrier to select a specific carrier’s screenshot; omit it for the most recent across carriers.

Query parameters

Param	Type	Default	Notes
`carrier`	`"at&t"` \| `"t-mobile"` \| `"verizon"`	—	Which carrier’s screenshot to return. Omit for the most recent.

curl "https://api.optimaldial.com/api/v1/spam/numbers/$NUMBER_ID/screenshot?carrier=verizon" \
  -H "Authorization: Bearer $OPTIMALDIAL_API_KEY" \
  --output screenshot.jpg

The response body is the raw JPEG bytes with Content-Type: image/jpeg. Write it straight to a file (as above) rather than parsing it as JSON. Screenshots captured before the JPEG rollout may still return image/png for up to 7 days (the screenshot retention window) — check the Content-Type header if the distinction matters to you.

Errors

Status	When
`401`	Auth failure
`403`	No active subscription on the organization
`404`	No screenshot available for this number (or carrier), or the number belongs to another organization
`429`	Rate limit hit

Stop monitoring a number

DELETE /api/v1/spam/numbers/{number_id}

Removes the number from monitoring. No further test runs are scheduled.

curl -X DELETE "https://api.optimaldial.com/api/v1/spam/numbers/$NUMBER_ID" \
  -H "Authorization: Bearer $OPTIMALDIAL_API_KEY"

Response

{ "status": "deleted", "id": "7c2a1f0e-9b3d-4a8e-bf21-0c5d6e7f8a90" }

Errors

Status	When
`401`	Auth failure
`404`	Number not found, or belongs to another organization
`429`	Rate limit hit

Webhook alerts

Instead of polling, subscribe to spam-monitoring events on your existing webhook endpoints. They use the same HMAC signing, headers, and retry behaviour as every other event — see the Receiving webhooks guide. Register interest by including the event types when you create or update an endpoint:

curl -X POST https://api.optimaldial.com/api/v1/webhooks \
  -H "Authorization: Bearer $OPTIMALDIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/optimaldial",
    "events": ["spam.detected", "number.verified"]
  }'

Event	Fires when
`spam.detected`	A carrier transitions a number from clean → flagged. Edge-triggered: fires once on the transition per carrier, not on every daily re-test while it stays flagged.
`number.verified`	A monitored number completes verification.

See the webhooks guide for the full payload bodies. In short, spam.detected carries the flagging carrier, label, SIP response, and a screenshot_available flag; number.verified carries the number’s id, phone, carrier, and verification time.

Get started

Endpoint guides

Webhooks

API Reference

Resources

Lifecycle

The MonitoredNumber object

The CarrierStatus object

Verification (SMS or call)

Add a monitored number

Request body

Response

Errors

Submit a verification code

Request body

Response

Errors

Resend a verification code

Request body (optional)

Response

Errors

List monitored numbers

Query parameters

Response

Errors

Retrieve a monitored number

Errors

List recent test runs

Response

The TestRunHistoryItem object

Errors

Get the latest screenshot

Query parameters

Errors

Stop monitoring a number

Response

Errors

Webhook alerts

​Lifecycle

​The MonitoredNumber object

​The CarrierStatus object

​Verification (SMS or call)

​Add a monitored number

​Request body

​Response

​Errors

​Submit a verification code

​Request body

​Response

​Errors

​Resend a verification code

​Request body (optional)

​Response

​Errors

​List monitored numbers

​Query parameters

​Response

​Errors

​Retrieve a monitored number

​Errors

​List recent test runs

​Response

​The TestRunHistoryItem object

​Errors

​Get the latest screenshot

​Query parameters

​Errors

​Stop monitoring a number

​Response

​Errors

​Webhook alerts

Lifecycle

The MonitoredNumber object

The CarrierStatus object

Verification (SMS or call)

Add a monitored number

Request body

Response

Errors

Submit a verification code

Request body

Response

Errors

Resend a verification code

Request body (optional)

Response

Errors

List monitored numbers

Query parameters

Response

Errors

Retrieve a monitored number

Errors

List recent test runs

Response

The TestRunHistoryItem object

Errors

Get the latest screenshot

Query parameters

Errors

Stop monitoring a number

Response

Errors

Webhook alerts