Response dictionary

A successful scrub returns HTTP 200 with four top-level fields:

{
  "prohibited_numbers_to_call": ["+52 55 1234 5678"],
  "safe_numbers_to_call": ["55 8765 4321"],
  "invalid_numbers": [
    {
      "input": "abc",
      "reason": "unparseable"
    }
  ],
  "summary": {
    "total_checked": 3,
    "prohibited_numbers": 1,
    "safe_numbers": 1,
    "invalid_numbers": 1
  }
}

Top-level fields

Field	Type	Meaning
`prohibited_numbers_to_call`	`string[]`	Original, structurally valid inputs found in the selected DNC registry. Do not call these numbers.
`safe_numbers_to_call`	`string[]`	Original, structurally valid inputs not found in the selected registry at the time of the check.
`invalid_numbers`	`InvalidPhone[]`	Inputs that could not be normalized for the selected country. Each item contains the original `input` and a `reason`.
`summary`	`object`	A complete count of prohibited, safe, and invalid results.

In safe_numbers_to_call, “safe” means only “not found in the selected DNC registry at the time of this check.” It does not prove that the number is active, reachable, assigned, supported by consent, or callable under every other law or rule.

Summary

Field	Meaning
`summary.total_checked`	Total array elements submitted, including duplicates and invalid inputs.
`summary.prohibited_numbers`	Number of entries returned in `prohibited_numbers_to_call`, including repeated inputs.
`summary.safe_numbers`	Number of entries returned in `safe_numbers_to_call`, including repeated inputs.
`summary.invalid_numbers`	Number of entries returned in `invalid_numbers`.

The response always satisfies:

summary.total_checked =
  summary.prohibited_numbers +
  summary.safe_numbers +
  summary.invalid_numbers

Each summary count is also the length of its corresponding top-level array.

Ordering and formatting

Response arrays contain the original strings, not canonicalized phone numbers.
Relative order is preserved within each of the three result arrays.
Duplicate input occurrences remain duplicated in the output.
Because the response is partitioned into categories, the original global order across all categories is not represented by a single array.

Invalid entry

Each invalid item has this shape:

type InvalidPhone = {
  input: string;
  reason:
    | "empty"
    | "unparseable"
    | "wrong_country"
    | "too_short"
    | "too_long";
};

See Phone inputs for the complete reason-code dictionary.

Earlier prelaunch examples used matched, clean, invalid, and stats. Those names are not part of the current public response. Update test integrations to use the fields documented above.

Getting started

Core concepts

Reliability and privacy

Use with AI

API reference

Top-level fields

Summary

Ordering and formatting

Invalid entry

​Top-level fields

​Summary

​Ordering and formatting

​Invalid entry

Top-level fields

Summary

Ordering and formatting

Invalid entry