Durable Scrub Jobs

Use the durable API when a batch is larger than the synchronous limit or may need to wait for a country service. The public API always accepts JSON arrays; CSV remains a panel-only workflow.

Choose the API

API	Input limit	Response	Retention
`POST /v1/scrub`	10,000 inputs	`200` with the complete result	No input or result persistence; idempotency fingerprint for 7 days
`POST /v2/scrub`	Up to 500,000 inputs and 25 MiB of JSON body, whichever comes first	`202` with a job resource, or `200` on a terminal replay	Input purge due at terminal state, or unknown-upload revalidation due at the 24-hour hard cap; result for 7 days from success; metadata for 30 days from terminalization

The v1 execution budget is 15 seconds. A v1 request that cannot finish within that budget fails as a complete unit; it does not become a hidden background job. Submit the same logical work to v2 when it needs durable execution. The v2 admission budget is 5 seconds. It covers authentication, validation, entitlement, Customer Quota reservation, and enqueueing only; it does not include country execution or internal retries.

Submit a job

Colombia is enabled for durable jobs. After the initial invoice is paid, the organization’s Colombia Country Purchase becomes active immediately and a valid request can return 202 Accepted; no manual activation is required. Normal entitlement, quota, maintenance, and temporary provider-availability checks still apply at admission.

curl https://api.dnclatam.com/v2/scrub \
  -X POST \
  -H "Authorization: Bearer ${DNC_LATAM_API_KEY}" \
  -H "Idempotency-Key: ${DNC_LATAM_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "co",
    "phones": ["+57 300 555 0101", "+57 601 555 0102"]
  }'

const response = await fetch("https://api.dnclatam.com/v2/scrub", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DNC_LATAM_API_KEY}`,
    "Idempotency-Key": process.env.DNC_LATAM_IDEMPOTENCY_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    country: "co",
    phones: ["+57 300 555 0101", "+57 601 555 0102"],
  }),
});

if (response.status !== 200 && response.status !== 202) {
  const error = await response.json();
  throw new Error(`admission failed: ${response.status} ${error.error}`);
}

const job = await response.json();

import os

import requests

response = requests.post(
    "https://api.dnclatam.com/v2/scrub",
    headers={
        "Authorization": f"Bearer {os.environ['DNC_LATAM_API_KEY']}",
        "Idempotency-Key": os.environ["DNC_LATAM_IDEMPOTENCY_KEY"],
    },
    json={
        "country": "co",
        "phones": ["+57 300 555 0101", "+57 601 555 0102"],
    },
    timeout=30,
)

if response.status_code not in (200, 202):
    raise RuntimeError(f"admission failed: {response.status_code} {response.json()['error']}")

job = response.json()

The API returns 202 Accepted:

{
  "job_id": "7a8f6d2c-4b1e-4f82-9d73-2c5e9b1a6f40",
  "status": "queued",
  "country": "co",
  "submitted_count": 2,
  "created_at": "2026-08-21T15:00:00Z",
  "status_url": "https://api.dnclatam.com/v2/scrub/7a8f6d2c-4b1e-4f82-9d73-2c5e9b1a6f40",
  "result_url": "https://api.dnclatam.com/v2/scrub/7a8f6d2c-4b1e-4f82-9d73-2c5e9b1a6f40/result",
  "cancel_url": "https://api.dnclatam.com/v2/scrub/7a8f6d2c-4b1e-4f82-9d73-2c5e9b1a6f40/cancel",
  "expires_at": "2026-08-22T15:00:00Z"
}

The identifier is an opaque lowercase UUID. Do not infer a country, organization, tenant, provider, or execution state from it. Tenant identity is internal and is never returned in the public job resource. An exact retry uses the same idempotency key, country, and array. It returns the same job identity and does not reserve Customer Quota again. Active jobs replay as 202; jobs that have already terminalized replay as 200. Reusing the key with a different payload returns 409 idempotency_key_reused.

Poll status

curl "https://api.dnclatam.com/v2/scrub/${JOB_ID}" \
  -H "Authorization: Bearer ${DNC_LATAM_API_KEY}"

The public state machine is:

queued → running → succeeded
                 ↘ failed
                 ↘ cancelled
                 ↘ expired
queued ───────────→ cancelled

queued and running are non-terminal. succeeded, failed, cancelled, and expired are terminal. expired means the job did not terminalize before the 24-hour active-job/input hard cap: Customer Quota is released and input is due for exact-identity cleanup or already verified absent. expires_at is state-dependent: admission plus 24 hours while queued or running; successful terminalization plus 7 days for a succeeded job; and terminalization plus 30 days for failed, cancelled, or expired metadata. A status response never includes provider names, attempt counts, chunks, costs, balances, credentials, or raw provider errors. Poll with bounded backoff and honor Retry-After when it is present. Do not create a new job on every poll or retry an admission with a new key unless you intend to submit a new logical batch.

Retrieve the result

curl "https://api.dnclatam.com/v2/scrub/${JOB_ID}/result" \
  -H "Authorization: Bearer ${DNC_LATAM_API_KEY}"

Only a succeeded job has a result. The result uses the same prohibited_numbers_to_call, safe_numbers_to_call, invalid_numbers, and summary model as v1. A job is always complete: the API never presents an internal chunk that failed as a partial success.

409 job_result_not_ready: the job is queued, running, failed, or cancelled. It may include a Retry-After header while queued or running; failed and cancelled jobs are terminal and have no complete result to retrieve. A failed status always includes a JobError; a cancelled status never includes one because cancellation is not an error.
410 job_expired: the job did not terminalize before its 24-hour hard cap; its reservation was released and input cleanup is due or already verified.
410 job_result_expired: the successful result exceeded its seven-day retention window.
404 job_not_found: the job does not exist or belongs to another organization. Both cases intentionally look the same to prevent cross-tenant enumeration.

Unlike v1, v2 temporarily stores the input and successful result encrypted so the job can survive a request ending. An attached input is eligible for purge when the job terminalizes. If an upload finishes with an unknown outcome, its exact canonical object becomes due for revalidation at the 24-hour hard cap. A failed cleanup remains retryable and observable until exact absence is verified. Results and non-phone metadata are purged according to the TTLs above. Every v2 response, including errors, exposes x-retention: transient-encrypted; technical v2 responses also expose the effective per-organization X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset, while 429 responses include Retry-After. The safe technical default is 60 requests per 60-second window; operator overrides are bounded from 1 to 60,000 and are independent of Customer Quota. The public contract does not claim that a government retains or deletes data on the same schedule.

Complete polling example

The API does not deliver webhooks; polling the status resource is the integration model. The examples below submit a batch, poll until the job is terminal while honoring Retry-After and applying bounded backoff with jitter, and retrieve the result only after succeeded.

const BASE_URL = "https://api.dnclatam.com";
const TERMINAL_STATES = new Set(["succeeded", "failed", "cancelled", "expired"]);
const RETRYABLE_CONTROL_STATUSES = new Set([429, 500, 503]);

const headers = {
  Authorization: `Bearer ${process.env.DNC_LATAM_API_KEY}`,
};

function deadlineError() {
  return new Error("durable scrub deadline exceeded");
}

function remainingMs(deadlineAt) {
  const remaining = deadlineAt - Date.now();
  if (remaining <= 0) throw deadlineError();
  return remaining;
}

async function fetchBeforeDeadline(url, options, deadlineAt) {
  const signal = AbortSignal.timeout(remainingMs(deadlineAt));
  try {
    return await fetch(url, { ...options, signal });
  } catch (error) {
    if (Date.now() >= deadlineAt || error?.name === "TimeoutError") {
      throw deadlineError();
    }
    throw error;
  }
}

async function sleepBeforeDeadline(delayMs, deadlineAt) {
  if (delayMs >= remainingMs(deadlineAt)) throw deadlineError();
  await new Promise((resolve) => setTimeout(resolve, delayMs));
}

function retryDelayMs(response, attempt) {
  const retryAfter = Number(response.headers.get("retry-after"));
  if (Number.isFinite(retryAfter) && retryAfter > 0) return retryAfter * 1_000;

  const backoff = Math.min(2_000 * 2 ** attempt, 60_000);
  return backoff / 2 + Math.random() * (backoff / 2);
}

async function apiError(response) {
  try {
    return (await response.json()).error ?? "unknown_error";
  } catch {
    return "invalid_error_response";
  }
}

async function scrubDurably(
  country,
  phones,
  { idempotencyKey, deadlineMs = 2 * 60 * 60 * 1000 },
) {
  if (!idempotencyKey) throw new Error("a persisted idempotency key is required");
  if (!Number.isFinite(deadlineMs) || deadlineMs <= 0) {
    throw new RangeError("deadlineMs must be positive");
  }
  const deadlineAt = Date.now() + deadlineMs;

  const submit = await fetchBeforeDeadline(`${BASE_URL}/v2/scrub`, {
    method: "POST",
    headers: {
      ...headers,
      "Idempotency-Key": idempotencyKey,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ country, phones }),
  }, deadlineAt);
  if (submit.status !== 200 && submit.status !== 202) {
    throw new Error(`admission failed: ${submit.status} ${await apiError(submit)}`);
  }
  const job = await submit.json();

  let attempt = 0;
  let status = job;

  while (!TERMINAL_STATES.has(status.status)) {
    const poll = await fetchBeforeDeadline(job.status_url, { headers }, deadlineAt);
    if (RETRYABLE_CONTROL_STATUSES.has(poll.status)) {
      const delay = retryDelayMs(poll, attempt);
      attempt += 1;
      await poll.body?.cancel();
      await sleepBeforeDeadline(delay, deadlineAt);
      continue;
    }
    if (!poll.ok) {
      throw new Error(`status failed: ${poll.status} ${await apiError(poll)}`);
    }
    status = await poll.json();
    if (TERMINAL_STATES.has(status.status)) break;

    const delay = retryDelayMs(poll, attempt);
    attempt += 1;
    await sleepBeforeDeadline(delay, deadlineAt);
  }

  if (status.status !== "succeeded") {
    // failed and expired carry a JobError object; cancelled does not.
    throw new Error(`job ${job.job_id} ended ${status.status}: ${status.error?.error ?? "no error"}`);
  }

  while (true) {
    const result = await fetchBeforeDeadline(job.result_url, { headers }, deadlineAt);
    if (RETRYABLE_CONTROL_STATUSES.has(result.status)) {
      const delay = retryDelayMs(result, attempt);
      attempt += 1;
      await result.body?.cancel();
      await sleepBeforeDeadline(delay, deadlineAt);
      continue;
    }
    if (!result.ok) {
      throw new Error(`result failed: ${result.status} ${await apiError(result)}`);
    }
    return result.json();
  }
}

const idempotencyKey = process.env.DNC_LATAM_IDEMPOTENCY_KEY;
const result = await scrubDurably(
  "co",
  ["+57 300 555 0101", "+57 601 555 0102"],
  { idempotencyKey },
);
console.log(result.summary);

import os
import random
import time

import requests

BASE_URL = "https://api.dnclatam.com"
TERMINAL_STATES = {"succeeded", "failed", "cancelled", "expired"}
RETRYABLE_CONTROL_STATUSES = {429, 500, 503}

HEADERS = {"Authorization": f"Bearer {os.environ['DNC_LATAM_API_KEY']}"}


def remaining_seconds(deadline):
    remaining = deadline - time.monotonic()
    if remaining <= 0:
        raise TimeoutError("durable scrub deadline exceeded")
    return remaining


def request_timeout(deadline):
    return min(30, remaining_seconds(deadline))


def sleep_before_deadline(delay, deadline):
    if delay >= remaining_seconds(deadline):
        raise TimeoutError("durable scrub deadline exceeded")
    time.sleep(delay)


def retry_delay(response, attempt):
    retry_after = response.headers.get("Retry-After")
    if retry_after:
        try:
            if int(retry_after) > 0:
                return int(retry_after)
        except ValueError:
            pass

    backoff = min(2 * 2**attempt, 60)
    return backoff / 2 + random.uniform(0, backoff / 2)


def api_error(response):
    try:
        return response.json().get("error", "unknown_error")
    except requests.exceptions.JSONDecodeError:
        return "invalid_error_response"


def scrub_durably(country, phones, idempotency_key, deadline_seconds=2 * 60 * 60):
    if not idempotency_key:
        raise ValueError("a persisted idempotency key is required")
    if deadline_seconds <= 0:
        raise ValueError("deadline_seconds must be positive")
    deadline = time.monotonic() + deadline_seconds

    submit = requests.post(
        f"{BASE_URL}/v2/scrub",
        headers={**HEADERS, "Idempotency-Key": idempotency_key},
        json={"country": country, "phones": phones},
        timeout=request_timeout(deadline),
    )
    if submit.status_code not in (200, 202):
        raise RuntimeError(f"admission failed: {submit.status_code} {api_error(submit)}")
    job = submit.json()

    attempt = 0
    status = job

    while status["status"] not in TERMINAL_STATES:
        poll = requests.get(
            job["status_url"],
            headers=HEADERS,
            timeout=request_timeout(deadline),
        )
        if poll.status_code in RETRYABLE_CONTROL_STATUSES:
            delay = retry_delay(poll, attempt)
            attempt += 1
            poll.close()
            sleep_before_deadline(delay, deadline)
            continue
        if not poll.ok:
            raise RuntimeError(f"status failed: {poll.status_code} {api_error(poll)}")
        status = poll.json()
        if status["status"] in TERMINAL_STATES:
            break

        delay = retry_delay(poll, attempt)
        attempt += 1
        sleep_before_deadline(delay, deadline)

    if status["status"] != "succeeded":
        # failed and expired carry a JobError object; cancelled does not.
        raise RuntimeError(
            f"job {job['job_id']} ended {status['status']}: {(status.get('error') or {}).get('error')}"
        )

    while True:
        result = requests.get(
            job["result_url"],
            headers=HEADERS,
            timeout=request_timeout(deadline),
        )
        if result.status_code in RETRYABLE_CONTROL_STATUSES:
            delay = retry_delay(result, attempt)
            attempt += 1
            result.close()
            sleep_before_deadline(delay, deadline)
            continue
        if not result.ok:
            raise RuntimeError(f"result failed: {result.status_code} {api_error(result)}")
        return result.json()


result = scrub_durably(
    "co",
    ["+57 300 555 0101", "+57 601 555 0102"],
    os.environ["DNC_LATAM_IDEMPOTENCY_KEY"],
)
print(result["summary"])

Generate one idempotency key per logical batch and persist it with your own job record before the first admission attempt. The examples require that persisted value through DNC_LATAM_IDEMPOTENCY_KEY; reuse it only to retry the exact same country and phone array.

Cancel a job

curl "https://api.dnclatam.com/v2/scrub/${JOB_ID}/cancel" \
  -X POST \
  -H "Authorization: Bearer ${DNC_LATAM_API_KEY}"

Cancellation is an explicit, idempotent action. A queued job can be cancelled immediately. If a government call is already in progress, cancellation is accepted but the job remains running until its external effect is reconciled. Once reconciliation establishes the provider call’s outcome, the job becomes cancelled, its complete result is discarded, and Customer Quota is released. A job that was already terminal keeps its terminal state. The API never claims that an uncertain call was cancelled, never returns a partial result, and never charges Customer Quota for an incomplete batch.

Country failures and quota

If a country is in a known maintenance window, the job fails with country_service_maintenance. Other temporary country failures use country_service_temporarily_unavailable. Both errors include the country, may include Retry-After, return no partial result, and consume no Customer Quota. A paid country that is still pending_activation is deliberately reported as country_service_temporarily_unavailable; the API never exposes that state, Registry Capacity, provider balance, or prepaid credits. Internal durable classifications map to a closed public error vocabulary:

Internal outcome class	Public `JobError`
Known country maintenance	`country_service_maintenance`
Temporary or inconclusive country execution	`country_service_temporarily_unavailable`
DNC LATAM worker, storage, or lease failure	`platform_failure`
Active-job hard cap	`job_expired`
Cancellation	No `JobError`; status is `cancelled`

Admission and provider-capacity failures map to the same generic public country/platform errors above. The public contract never exposes provider names, balances, costs, credentials, capacity causes, or raw internal error codes.

Getting started

Core concepts

Reliability and privacy

Use with AI

API reference

Choose the API

Submit a job

Poll status

Retrieve the result

Complete polling example

Cancel a job

Country failures and quota

​Choose the API

​Submit a job

​Poll status

​Retrieve the result

​Complete polling example

​Cancel a job

​Country failures and quota

Choose the API

Submit a job

Poll status

Retrieve the result

Complete polling example

Cancel a job

Country failures and quota