Quickstart

POST /v1/scan audits one number. It requires contact and phone_number_format.

export DIALRIGHT_TOKEN="YOUR_ORG_API_TOKEN"

curl --request POST \
  --url https://dialright-api.calleridreputation.com/v1/scan \
  --header "Authorization: Bearer $DIALRIGHT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "data_sources": ["reassigned-numbers", "dr-score-and-basic-info"],
    "dr_score_attributes": ["do-not-call-registry", "do-not-call-registry-by-state"],
    "contact": {
      "phone_number": "12345678900",
      "last_point_contact": "2024-01-02"
    },
    "phone_number_format": "E164",
    "test_mode": false
  }'

Bulk scans: POST /v1/scan/bulk, max 1000 numbers, 1 request per second. Use it for anything beyond a handful of numbers.

Real scans bill the organization per number and per data source (metadata.cost in the response). Set test_mode: true to validate the request without a charge; the result values are then synthetic placeholders.

Selectors

Omit data_sources, or send an empty array, to enable every source your org can use.
Any list that contains "none" disables all sources, even if other selectors are present.
Selecting sources requires Split Data Services on the organization.
Omit dr_score_attributes to enable all attributes. An empty list or any list containing "none" disables them.
last_point_contact is required and parsed as YYYY-MM-DD only when reassigned-numbers is enabled.

Score range

dialright_score is an integer from 0 to 100, or null when no activity data exists for the number. Higher means the number is more likely live, reachable, and low risk.

0: the number is a known litigator or TCPA risk, or it is on a do-not-call list you enabled through dr_score_attributes. Do not dial.
1 to 25: capped here when the number is associated with DNC complainants.
50 and above: DialRight treats these as high-score numbers in job summaries.

The value 50 itself is never returned; it is reported as 51.

Reading the result

Every field except phone_number appears only when its data source ran. Full field docs are on the ScanResult schema.

Field	Meaning
`dialright_score`	0–100, higher is safer and more reachable. `null` when no activity data exists.
`is_valid`	`false` means malformed or unassigned. Do not dial.
`likely_litigator_associated`	`true` when the number is in the TCPA litigator database with status `tcpa` or `troll`.
`risk_level`	Litigator-database status: `clean`, `tcpa`, `troll`, `dnc_complainers`, `federal_dnc`, `state_dnc`.
`litigator_name`, `case_reference`, `repeat_filer`	Who the litigator is, their most recent case title, and whether they have filed more than once.
`dnc_fed_number`, `dnc_state_number`	On the federal or a state Do Not Call registry.
`line_type`, `carrier`, `is_prepaid`	`Landline`, `Mobile`, `FixedVOIP`, `NonFixedVOIP`, `TollFree`, `Premium`, `Voicemail`, `Other`; current carrier; prepaid flag.
`business_associated_number`	Known business line rather than a consumer.
`reassigned_numbers_result.contact_disconnected`	`true` when the RND reports a disconnect after `last_point_contact`; re-consent before dialing.
`state`, `country_code`, `country_name`, `country_calling_code`	Location derived from the number.
`error`	A data-source lookup failed for this number; fields from that source may be missing.

Rate limits

Limits are per organization API token, per endpoint, on a sliding window.

Endpoint	Limit
`POST /v1/scan`	64 requests per second
`POST /v1/scan/bulk`	1 request per second (up to 1000 contacts per request)
Every other `/v1` endpoint	200 requests per 45 seconds

Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. A 429 includes Retry-After; wait that many seconds before retrying.