---
title: "Answer intent and spam flags, programmatically."
url: "https://optimaldial.com/developers"
description: "REST API + webhooks for the OptimalDial platform. Score numbers by answer intent, monitor outbound caller IDs for carrier spam flags, and pipe both into your dialer or CRM. Included on every paid plan."
---

Two APIs · One key

# Answer intent and spam flags, programmatically.

Score phone numbers by who actually picks up, and monitor your outbound caller IDs for carrier spam flags — both from one REST API, one key, and the same webhooks.

[Read the docs →](https://docs.optimaldial.com) [Get an API key](https://app.optimaldial.com)

*   REST
*   Webhooks
*   API key auth
*   curl · Node · Python

POST /api/v1/uploads

```
# Upload a list and get scoring back
curl https://api.optimaldial.com/api/v1/uploads \
  -H "Authorization: Bearer od_live_•••" \
  -H "Content-Type: application/json" \
  -d '{"numbers": ["+14155551212", ...]}'

# → webhook fires when ready
{
  "event": "upload.processed",
  "upload_id": "upl_8fK2...",
  "results_url": "https://..."
}
```

The platform

## One key. Two APIs.

Everything below runs on the same base URL, the same `od_live_` key, and the same signed webhooks. Pick a track to jump in.

[

POSTGET

### Answer Intent API

Score phone numbers by who will actually pick up, so your reps stop dialing into voicemail.

Jump to quickstart →](#answer-intent-api)[

POSTGETDELETE

### Spam Monitoring API

Watch your outbound caller IDs for carrier spam flags across AT&T, T-Mobile, and Verizon — with screenshot proof.

Jump to quickstart →](#spam-monitoring-api)

Answer Intent API

## From CSV exports to live integrations.

Same scoring engine, same data, now wired into wherever your reps work.

### Score lists from your dialer

Submit numbers from your CRM, dialer, or workflow. Get back the same Answer Intent labels you see in the dashboard — without the CSV middle step.

### Real-time webhooks

Subscribe once, then react the moment a list is created, finishes processing, or fails. No polling, no cron jobs.

### Pipe signals into your stack

Push connect-rate signals into HubSpot, Salesforce, Outreach, SalesLoft, or anything custom. Build it once, run it on every list.

Quickstart

## Your first call, in three lines.

Generate a key, POST a list of numbers, and listen for the webhook when scoring is ready.

curlNodePython Copy

```
curl https://api.optimaldial.com/api/v1/uploads \
  -H "Authorization: Bearer od_live_•••" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q4 enterprise list",
    "numbers": ["+14155551212", "+12025550143"],
    "webhook_url": "https://yourapp.com/hooks/optimaldial"
  }'
```

```
const res = await fetch("https://api.optimaldial.com/api/v1/uploads", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OPTIMALDIAL_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Q4 enterprise list",
    numbers: ["+14155551212", "+12025550143"],
    webhook_url: "https://yourapp.com/hooks/optimaldial",
  }),
});

const upload = await res.json();
console.log(upload.id); // upl_8fK2…
```

```
import os, requests

res = requests.post(
    "https://api.optimaldial.com/api/v1/uploads",
    headers={
        "Authorization": f"Bearer {os.environ['OPTIMALDIAL_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "name": "Q4 enterprise list",
        "numbers": ["+14155551212", "+12025550143"],
        "webhook_url": "https://yourapp.com/hooks/optimaldial",
    },
)

upload = res.json()
print(upload["id"])  # upl_8fK2…
```

Spam Monitoring API

## Monitor carrier spam flags, programmatically.

Add your outbound caller IDs, verify ownership, and read per-carrier spam status for AT&T, T-Mobile, and Verizon — with screenshot proof — from the same API and the same `od_live_` key you already use.

Endpoints

### Numbers and status.

Manage the full lifecycle of every monitored caller ID — add, verify, list, retire — and read each carrier's latest verdict.

*   POST `/spam/numbers` Add an outbound number; ownership verification starts automatically.
*   GET `/spam/numbers` List monitored numbers with per-carrier spam status.
*   GET `/spam/numbers/{id}/screenshot` Pull the PNG proof of how a carrier displays your number.
*   DELETE `/spam/numbers/{id}` Stop monitoring a number.

[Endpoint reference →](https://docs.optimaldial.com)

Webhooks

### Alerts that fire themselves.

Two new events join the upload lifecycle, delivered over the same signed-webhook setup:

*   spam.detected a carrier flagged one of your numbers
*   number.verified a monitored number cleared ownership verification

Same HMAC-SHA256 `X-OptimalDial-Signature` you already verify.

[Webhook reference →](https://docs.optimaldial.com)

POST /api/v1/spam/numbers

```
# Add an outbound number to monitoring
curl https://api.optimaldial.com/api/v1/spam/numbers \
  -H "Authorization: Bearer od_live_•••" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+14155551212", "verification_method": "call"}'

# → webhook fires the moment a carrier flags it
{
  "event": "spam.detected",
  "number_id": "num_7bQ1...",
  "carrier": "t-mobile",
  "label": "Scam Likely"
}
```

Built in

## Webhooks and auth, out of the box.

Webhooks

### No polling. Just listen.

Subscribe once, get notified the moment anything changes state. Events cover both APIs over a single subscription:

Answer Intent

*   upload.created we acknowledged your list and queued it
*   upload.processed scoring complete, results available
*   upload.failed something broke, here's why

Spam Monitoring

*   number.verified a monitored number cleared ownership verification
*   spam.detected a carrier flagged one of your numbers

[Webhook reference →](https://docs.optimaldial.com)

Auth

### API keys. Nothing weirder.

Generate a key from the developer panel in your dashboard, send it as a Bearer token, and you're in. One key works across both the Answer Intent and Spam Monitoring APIs.

```
Authorization: Bearer od_live_•••••••••••
```

*   Separate **live** and **test** keys per workspace
*   Rotate or revoke any key without downtime
*   Scoped to a single workspace — never leak across customers

[Authentication guide →](https://docs.optimaldial.com)

Reference

## The whole API at a glance.

Four resource groups. Full reference, schemas, and examples live in the [docs](https://docs.optimaldial.com).

*   [
    
    Uploads Submit a list of phone numbers and get scoring back.
    
    POSTGET
    
    →](https://docs.optimaldial.com)
*   [
    
    Spam Monitoring Monitor outbound caller IDs for carrier spam flags, with per-carrier status and screenshot proof.
    
    POSTGETDELETE
    
    →](https://docs.optimaldial.com)
*   [
    
    Webhooks Subscribe to lifecycle events for any list you submit.
    
    POSTGETDELETE
    
    →](https://docs.optimaldial.com)
*   [
    
    API keys Create, list, and revoke keys directly from the developer panel.
    
    UI
    
    →](https://app.optimaldial.com)

### Included on every paid plan

API access ships with all paid tiers — no add-on, no separate quota.

### Your data stays yours

We never resell phone numbers or share lists between customers. US-based infrastructure.

FAQ

## Common Questions

[Talk to us →](#)

Is the API included in my plan?

Yes. API access ships with every paid OptimalDial plan — there’s no separate quota and no add-on. Generate a key from the developer panel in your dashboard and start integrating.

Can I monitor caller-ID spam flags through the API?

Yes. The Spam Monitoring API lets you add outbound numbers, run ownership verification, and read per-carrier flag status for AT&T, T-Mobile, and Verizon — including the screenshot proof — without touching the dashboard. Subscribe to the spam.detected webhook to get alerted the moment a carrier flags one of your numbers. It uses the same od\_live\_ keys and signed-webhook setup as the rest of the API.

How do I get an API key?

Sign in to your OptimalDial dashboard, open the developer panel, and create a key. Keys look like od\_live\_… and you send them as an Authorization Bearer token. You can rotate or revoke any key without downtime.

What about rate limits?

We apply fair-use rate limits scaled to your plan. The full limits, retry semantics, and error codes are documented in the API reference. If you’re building something with unusual throughput, talk to us — we’ll work with you.

How do webhooks work?

You provide a webhook URL when you create an upload (or set a default in your workspace). We POST a JSON payload to it when the list is created, finishes processing, or fails — so you don’t need to poll. Each delivery is signed so you can verify it came from us.

Can I use it from a no-code tool?

Yes. Anything that can make an HTTPS request with a Bearer token — Zapier, Make, n8n, Retool, custom scripts — can hit the API. Webhooks land as standard JSON HTTP POSTs.

## Stop dialing into voicemail. Programmatically.

Generate a key and send your first list in under a minute.

[Read the docs →](https://docs.optimaldial.com) [Talk to engineering](#)

REST · Webhooks · API key auth · curl, Node, Python examples