API reference

Scrub a small batch of phone numbers synchronously

Use v1 for batches of up to 10,000 inputs and 25 MiB of JSON body, whichever limit is reached first, that should complete within the 15-second synchronous execution budget. The response is one complete result or an error; no partial result is returned. Every v1 response, including 4xx and 5xx errors, carries x-retention: zero and Cache-Control: no-store, max-age=0. Phone Input and per-number Scrub Result exist only in request memory; bounded non-phone request metadata (including idempotency digests and quota state) and approved aggregate usage data may remain. Country examples are contractual and still require a matching Country Purchase and operational/activation gates. Use v2 for larger batches or work that may wait on a country service.

POST

https://api.dnclatam.com

scrub

curl --request POST \
  --url https://api.dnclatam.com/v1/scrub \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "country": "mx",
  "phones": [
    "+52 55 1234 5678",
    "55 8765 4321",
    "abc"
  ]
}
'

{
  "prohibited_numbers_to_call": [
    "<string>"
  ],
  "safe_numbers_to_call": [
    "<string>"
  ],
  "invalid_numbers": [
    {
      "input": "<string>",
      "reason": "empty"
    }
  ],
  "summary": {
    "total_checked": 1,
    "prohibited_numbers": 1,
    "safe_numbers": 1,
    "invalid_numbers": 1
  },
  "scrub_record": {
    "record_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "record_version": "1",
    "surface": "api_v1",
    "organization": {
      "name": "<string>"
    },
    "country": "mx",
    "registry": {
      "authority": "<string>",
      "mode": "snapshot",
      "source_observed_at": "2023-11-07T05:31:56Z",
      "consulted_at": "2023-11-07T05:31:56Z"
    },
    "status": "succeeded",
    "counts": {
      "submitted": 2,
      "prohibited": 1,
      "safe": 1,
      "invalid": 1
    },
    "submitted_at": "2023-11-07T05:31:56Z",
    "completed_at": "2023-11-07T05:31:56Z",
    "record_issued_at": "2023-11-07T05:31:56Z",
    "request_id": "<string>",
    "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "client_scrub_reference": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "failure": {
      "error": "<string>",
      "country": "mx"
    }
  }
}

{
  "error": "missing_idempotency_key",
  "message": "<string>",
  "max": 2,
  "max_chars": 2
}

{
  "error": "invalid_key"
}

{
  "error": "subscription_inactive",
  "message": "<string>",
  "request_id": "<string>"
}

{
  "error": "account_suspended",
  "message": "<string>",
  "request_id": "<string>"
}

{
  "error": "method_not_allowed",
  "message": "<string>"
}

{
  "error": "idempotency_request_in_progress",
  "message": "<string>",
  "request_id": "<string>"
}

{
  "error": "payload_too_large",
  "max_bytes": 26214400,
  "message": "<string>",
  "request_id": "<string>"
}

{
  "error": "rate_limit_exceeded",
  "message": "<string>",
  "limit": 30000,
  "window_seconds": 60,
  "retry_after": 2,
  "request_id": "<string>"
}

{
  "error": "internal",
  "request_id": "<string>",
  "message": "<string>"
}

{
  "error": "country_service_maintenance",
  "message": "<string>",
  "country": "mx",
  "request_id": "<string>",
  "retry_after": 2
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key

string

required

Opaque key for one logical request, scoped to the authenticated API key. Use a high-entropy value and never include phone numbers or other PII. Exact retries are protected for at least 7 days for v1; v2 keeps the accepted job identity for the job metadata lifetime.

Required string length: 1 - 255

Pattern: ^[\x21-\x7e]+$

Body

application/json

The v1 body is limited by both 10,000 phone entries and a 25 MiB JSON body. The first limit reached controls admission.

country

enum<string>

required

Technical country code. The current sellable catalog is mx/ar/co. es/au/sg are planned product coverage, end of September 2026, and are not sellable at checkout until their catalog and runtime are released together. Every real request requires a matching Country Purchase and country availability/activation. Colombia is sellable and operational, and a successful initial payment activates its complete API access immediately without manual approval; entitlement and operational availability are still evaluated at admission.

Available options:

mx,

ar,

co,

es,

au,

sg

phones

string[]

required

Phone numbers in international or supported local formats. Invalid and duplicate entries count toward Customer Quota.

Required array length: 1 - 10000 elements

Maximum string length: 64

Response

Scrub completed

One complete result for the submitted Scrub Batch. No provider chunks or partial result are exposed.

prohibited_numbers_to_call

string[]

required

Original, structurally valid inputs found in the selected DNC registry. Do not call these numbers. Original formatting and relative order within this category are preserved; duplicates are returned once per occurrence.

safe_numbers_to_call

string[]

required

Original, structurally valid inputs not found in the selected DNC registry at the time of the check. safe is limited to this registry result; it does not confirm that a number is active or reachable, prove consent, or grant universal legal permission to call.

invalid_numbers

object[]

required

Inputs that failed structural validation or were explicitly rejected by the selected registry, in their original relative order.

Hide child attributes

invalid_numbers.input

string

required

Original input exactly as submitted.

invalid_numbers.reason

enum<string>

required

empty: blank or separators only. unparseable: not recognizable as a phone number. wrong_country: explicit country code does not match the requested registry. too_short or too_long: normalized national number has the wrong number of digits. provider_rejected: the selected registry did not return an acceptable determination for this otherwise structurally valid input; it is not classified as safe.

Available options:

empty,

unparseable,

wrong_country,

too_short,

too_long,

provider_rejected

summary

object

required

Aggregate counts for this request. summary.total_checked equals summary.prohibited_numbers + summary.safe_numbers + summary.invalid_numbers.

Hide child attributes

summary.total_checked

integer

required

Total inputs submitted, including invalid inputs and duplicates.

Required range: x >= 0

summary.prohibited_numbers

integer

required

Number of entries returned in prohibited_numbers_to_call, including repeated inputs.

Required range: x >= 0

summary.safe_numbers

integer

required

Number of entries returned in safe_numbers_to_call, including repeated inputs.

Required range: x >= 0

summary.invalid_numbers

integer

required

Number of entries returned in invalid_numbers.

Required range: x >= 0

scrub_record

object

Phone-free Screening record for this successful Scrub. Delivered with the Scrub Result; v1 does not persist it.

Hide child attributes

scrub_record.record_id

string<uuid>

required

Opaque lowercase UUIDv4 generated by DNC LATAM. It carries no country, tenant, provider, or execution meaning; tenant identity remains internal and is never returned.

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

scrub_record.record_version

string

required

Allowed value: "1"

scrub_record.surface

enum<string>

required

Available options:

api_v1,

api_v2,

panel_csv

scrub_record.organization

object

required

Hide child attributes

scrub_record.organization.name

string

required

Required string length: 1 - 200

scrub_record.country

enum<string>

required

Available options:

mx,

ar,

co,

es,

au,

sg

scrub_record.registry

object

required

Hide child attributes

scrub_record.registry.authority

string

required

scrub_record.registry.mode

enum<string>

required

Available options:

snapshot,

live_consult

scrub_record.registry.source_observed_at

string<date-time>

scrub_record.registry.consulted_at

string<date-time>

scrub_record.status

enum<string>

required

Available options:

succeeded,

failed,

cancelled,

expired

scrub_record.counts

object

required

Hide child attributes

scrub_record.counts.submitted

integer

required

Required range: x >= 1

scrub_record.counts.prohibited

integer

required

Required range: x >= 0

scrub_record.counts.safe

integer

required

Required range: x >= 0

scrub_record.counts.invalid

integer

required

Required range: x >= 0

scrub_record.submitted_at

string<date-time>

required

scrub_record.completed_at

string<date-time>

required

scrub_record.record_issued_at

string<date-time>

required

scrub_record.request_id

string

Present only for api_v1.

scrub_record.job_id

string<uuid>

Present only for api_v2.

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

scrub_record.client_scrub_reference

string<uuid>

Optional UUIDv4 Client Scrub Reference on the record when supplied. Not an idempotency key. Request-body acceptance is not published in this contract version.

scrub_record.failure

object

Hide child attributes

scrub_record.failure.error

string

required

scrub_record.failure.country

enum<string>

required

Available options:

mx,

ar,

co,

es,

au,

sg

curl --request POST \
  --url https://api.dnclatam.com/v1/scrub \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "country": "mx",
  "phones": [
    "+52 55 1234 5678",
    "55 8765 4321",
    "abc"
  ]
}
'

{
  "prohibited_numbers_to_call": [
    "<string>"
  ],
  "safe_numbers_to_call": [
    "<string>"
  ],
  "invalid_numbers": [
    {
      "input": "<string>",
      "reason": "empty"
    }
  ],
  "summary": {
    "total_checked": 1,
    "prohibited_numbers": 1,
    "safe_numbers": 1,
    "invalid_numbers": 1
  },
  "scrub_record": {
    "record_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "record_version": "1",
    "surface": "api_v1",
    "organization": {
      "name": "<string>"
    },
    "country": "mx",
    "registry": {
      "authority": "<string>",
      "mode": "snapshot",
      "source_observed_at": "2023-11-07T05:31:56Z",
      "consulted_at": "2023-11-07T05:31:56Z"
    },
    "status": "succeeded",
    "counts": {
      "submitted": 2,
      "prohibited": 1,
      "safe": 1,
      "invalid": 1
    },
    "submitted_at": "2023-11-07T05:31:56Z",
    "completed_at": "2023-11-07T05:31:56Z",
    "record_issued_at": "2023-11-07T05:31:56Z",
    "request_id": "<string>",
    "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "client_scrub_reference": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "failure": {
      "error": "<string>",
      "country": "mx"
    }
  }
}

{
  "error": "missing_idempotency_key",
  "message": "<string>",
  "max": 2,
  "max_chars": 2
}

{
  "error": "invalid_key"
}

{
  "error": "subscription_inactive",
  "message": "<string>",
  "request_id": "<string>"
}

{
  "error": "account_suspended",
  "message": "<string>",
  "request_id": "<string>"
}

{
  "error": "method_not_allowed",
  "message": "<string>"
}

{
  "error": "idempotency_request_in_progress",
  "message": "<string>",
  "request_id": "<string>"
}

{
  "error": "payload_too_large",
  "max_bytes": 26214400,
  "message": "<string>",
  "request_id": "<string>"
}

{
  "error": "rate_limit_exceeded",
  "message": "<string>",
  "limit": 30000,
  "window_seconds": 60,
  "retry_after": 2,
  "request_id": "<string>"
}

{
  "error": "internal",
  "request_id": "<string>",
  "message": "<string>"
}

{
  "error": "country_service_maintenance",
  "message": "<string>",
  "country": "mx",
  "request_id": "<string>",
  "retry_after": 2
}

Getting started

Core concepts

Reliability and privacy

Use with AI

API reference

Scrub a small batch of phone numbers synchronously

Authorizations

Headers

Body

Response