> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dnclatam.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scrub a batch of phone numbers



## OpenAPI

````yaml https://api.dnclatam.com/openapi.json post /v1/scrub
openapi: 3.1.0
info:
  title: DNC LATAM API
  version: 1.1.0
  description: >-
    Scrub phone numbers against Mexico's REPEP and Argentina's Registro Nacional
    No Llame. Customer phone numbers are processed with zero data retention.
servers:
  - url: https://api.dnclatam.com
security: []
paths:
  /v1/scrub:
    post:
      summary: Scrub a batch of phone numbers
      operationId: scrubPhones
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          description: >-
            Opaque key for one logical request, scoped to the authenticated API
            key. Use a random UUID and never include phone numbers or other PII.
            Exact retries are protected for at least 7 days; only a keyed,
            non-reversible fingerprint is retained.
          schema:
            type: string
            minLength: 1
            maxLength: 255
            pattern: ^[\x21-\x7e]+$
          example: 018f47c2-9b0d-7c95-bf47-cd84c12f8912
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                country:
                  type: string
                  enum:
                    - mx
                    - ar
                  description: Registry country.
                phones:
                  type: array
                  minItems: 1
                  maxItems: 500000
                  items:
                    type: string
                    maxLength: 64
                  description: Phone numbers in international or supported local formats.
              required:
                - country
                - phones
              additionalProperties: false
            examples:
              mexico:
                value:
                  country: mx
                  phones:
                    - +52 55 1234 5678
                    - 55 8765 4321
                    - abc
      responses:
        '200':
          description: Scrub completed
          headers:
            x-retention:
              schema:
                type: string
                const: zero
              description: Customer phone numbers are not persisted.
            Idempotency-Replayed:
              schema:
                type: string
                const: 'true'
              description: >-
                Present when a completed request was recalculated without
                charging or recording usage again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScrubResult'
              examples:
                mixedResults:
                  summary: Prohibited, safe, and invalid numbers
                  value:
                    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
        '400':
          description: Missing or invalid Idempotency-Key, country, body, or batch size
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing, invalid, or revoked API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: >-
            The requested country is backed by Stripe and the subscription is
            inactive
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionInactiveError'
        '403':
          description: The organization is suspended or has no entitlement for this country
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/AccountSuspendedError'
                  - $ref: '#/components/schemas/CountryNotInPlanError'
        '409':
          description: >-
            The same Idempotency-Key is still processing, or was reused with a
            different payload
          headers:
            Retry-After:
              schema:
                type: integer
                minimum: 1
              description: >-
                Seconds before retrying an in-progress request. Present only for
                `idempotency_request_in_progress`.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/IdempotencyInProgressError'
                  - $ref: '#/components/schemas/IdempotencyConflictError'
        '413':
          description: Request body exceeds 25 MiB
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: >-
            Temporary source-IP block, technical per-organization request rate
            limit, or monthly country quota exceeded. Inspect `error` to
            distinguish them.
          headers:
            Retry-After:
              schema:
                type: integer
                minimum: 1
              description: >-
                Seconds until another request can be attempted. Present for
                `temporarily_blocked` and `rate_limit_exceeded`.
            X-RateLimit-Limit:
              schema:
                type: integer
                const: 60
            X-RateLimit-Remaining:
              schema:
                type: integer
                minimum: 0
                maximum: 60
            X-RateLimit-Reset:
              schema:
                type: integer
              description: Unix timestamp when the technical window resets.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/TemporaryBlockError'
                  - $ref: '#/components/schemas/RateLimitError'
                  - $ref: '#/components/schemas/QuotaError'
        '503':
          description: >-
            This API process is at its bounded database-preflight, in-flight
            request, or bulk-batch capacity; retry shortly
          headers:
            Retry-After:
              schema:
                type: integer
                const: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CapacityError'
      security:
        - bearerAuth: []
components:
  schemas:
    ScrubResult:
      type: object
      properties:
        prohibited_numbers_to_call:
          type: array
          items:
            type: string
          description: >-
            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:
          type: array
          items:
            type: string
          description: >-
            Original, structurally valid inputs not found in the selected DNC
            registry at the time of the check. Here, `safe` is limited to this
            DNC registry result; it does not confirm that a number is active or
            reachable, prove consent, or grant universal legal permission to
            call. Original formatting and relative order within this category
            are preserved; duplicates are returned once per occurrence.
        invalid_numbers:
          type: array
          items:
            $ref: '#/components/schemas/InvalidPhone'
          description: >-
            Inputs that could not be normalized for the selected country, in
            their original relative order.
        summary:
          type: object
          description: >-
            Aggregate counts for this request. `summary.total_checked` equals
            `summary.prohibited_numbers + summary.safe_numbers +
            summary.invalid_numbers`.
          properties:
            total_checked:
              type: integer
              minimum: 0
              description: Total inputs submitted, including invalid inputs and duplicates.
            prohibited_numbers:
              type: integer
              minimum: 0
              description: >-
                Number of entries returned in `prohibited_numbers_to_call`,
                including repeated inputs.
            safe_numbers:
              type: integer
              minimum: 0
              description: >-
                Number of entries returned in `safe_numbers_to_call`, including
                repeated inputs.
            invalid_numbers:
              type: integer
              minimum: 0
              description: Number of entries returned in `invalid_numbers`.
          required:
            - total_checked
            - prohibited_numbers
            - safe_numbers
            - invalid_numbers
      required:
        - prohibited_numbers_to_call
        - safe_numbers_to_call
        - invalid_numbers
        - summary
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
      required:
        - error
    SubscriptionInactiveError:
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            error:
              type: string
              const: subscription_inactive
          required:
            - error
            - message
    AccountSuspendedError:
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            error:
              type: string
              const: account_suspended
          required:
            - error
            - message
    CountryNotInPlanError:
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            error:
              type: string
              const: country_not_in_plan
          required:
            - error
            - message
    IdempotencyInProgressError:
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            error:
              type: string
              const: idempotency_request_in_progress
          required:
            - error
            - message
    IdempotencyConflictError:
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            error:
              type: string
              const: idempotency_key_reused
          required:
            - error
            - message
    TemporaryBlockError:
      description: The source IP triggered repeated unknown-route abuse protection.
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            error:
              type: string
              const: temporarily_blocked
            retry_after:
              type: integer
              minimum: 1
              maximum: 900
          required:
            - error
            - message
            - retry_after
    RateLimitError:
      description: >-
        The organization exceeded the shared technical request limit across all
        of its API keys.
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            error:
              type: string
              const: rate_limit_exceeded
            limit:
              type: integer
              const: 60
            window_seconds:
              type: integer
              const: 60
            retry_after:
              type: integer
              minimum: 1
          required:
            - error
            - limit
            - window_seconds
            - retry_after
    QuotaError:
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            error:
              type: string
              const: monthly_quota_exceeded
            country:
              type: string
              enum:
                - mx
                - ar
            limit:
              type: integer
              minimum: 0
            used:
              type: integer
            requested:
              type: integer
            upgrade_url:
              type: string
              format: uri
          required:
            - error
            - country
            - limit
            - used
            - requested
            - upgrade_url
    CapacityError:
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            error:
              type: string
              const: capacity_exceeded
            retry_after:
              type: integer
              const: 1
          required:
            - error
            - message
            - retry_after
    InvalidPhone:
      type: object
      description: >-
        An original input that could not be normalized for the selected registry
        country. Invalid inputs do not fail the batch.
      properties:
        input:
          type: string
          description: Original input exactly as submitted.
        reason:
          type: string
          description: >-
            `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.
          enum:
            - empty
            - unparseable
            - wrong_country
            - too_short
            - too_long
      required:
        - input
        - reason
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: dnc_live_*

````