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

# Check a phone number

> Returns whether the number is on its country's do-not-call register. Send `webhook_url` to get the answer as a POST instead. See [Webhooks](/api-reference/webhooks).

Send numbers in E.164 with the national leading zero dropped: UK `01000822380` is `+441000822380`.



## OpenAPI

````yaml /api-reference/openapi.json get /check_phone_number
openapi: 3.1.0
info:
  title: Meer API
  version: 1.2.0
  description: >-
    Check phone numbers against national do-not-call registers.


    Authenticate with `Authorization: Bearer <YOUR_API_KEY>`. The `Bearer`
    prefix is optional.


    Lookups use credits from your limit for the billing period. The cost varies
    by country; each response reports it in `X-Credit-Cost` and `cost`.


    Resellers must send `X-Forwarded-Host` with a unique ID for the end customer
    on every request.
  contact:
    name: API Support
    email: support@meerapi.com
servers:
  - url: https://api.meerapi.com
    description: Production
security:
  - apiKey: []
tags:
  - name: Phone Numbers
    description: Do-not-call lookups
  - name: Usage
    description: Usage for your account
paths:
  /check_phone_number:
    get:
      tags:
        - Phone Numbers
      summary: Check a phone number
      description: >-
        Returns whether the number is on its country's do-not-call register.
        Send `webhook_url` to get the answer as a POST instead. See
        [Webhooks](/api-reference/webhooks).


        Send numbers in E.164 with the national leading zero dropped: UK
        `01000822380` is `+441000822380`.
      operationId: checkPhoneNumber
      parameters:
        - name: phone_number
          in: query
          required: true
          description: E.164, URL-encoded (`+` becomes `%2B`). The `+` is optional.
          schema:
            type: string
          examples:
            au:
              summary: AU number
              value: '+61491570006'
            us:
              summary: US number
              value: '+14155552671'
            gb:
              summary: UK number
              value: '+442071234567'
        - name: webhook_url
          in: query
          required: false
          description: >-
            Turns on webhook mode. https only, at most 2048 characters, a public
            host, no embedded credentials.
          schema:
            type: string
            format: uri
            maxLength: 2048
        - name: X-Forwarded-Host
          in: header
          required: false
          description: >-
            Resellers only, and required for them: a unique identifier for your
            customer that you must be able to provide exact details for e.g.
            `id-123` that we can later link to a customer name
          schema:
            type: string
      responses:
        '200':
          description: The answer.
          headers:
            X-Meer-Correlation-Id:
              $ref: '#/components/headers/CorrelationId'
            X-Credit-Cost:
              $ref: '#/components/headers/CreditCost'
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Answer'
              examples:
                listed:
                  value:
                    do_not_call: true
                    timestamp: '2026-09-28T04:01:05.123456+00:00'
                    dnc_list_source: https://www.donotcall.gov.au
                    cost:
                      credits_used_for_query: 2
                      total_credits_used: 5120
                      credit_limit: 25000
                  summary: On the register
                not_listed:
                  summary: Not on the register
                  value:
                    do_not_call: false
                    timestamp: '2026-09-28T04:01:05.123456+00:00'
                    dnc_list_source: null
                    cost:
                      credits_used_for_query: 1
                      total_credits_used: 5121
                      credit_limit: 25000
        '202':
          description: >-
            Webhook mode: the lookup is queued. The answer is POSTed to
            `webhook_url`.
          headers:
            X-Meer-Correlation-Id:
              $ref: '#/components/headers/CorrelationId'
            X-Credit-Cost:
              $ref: '#/components/headers/CreditCost'
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Receipt'
              examples:
                started:
                  value:
                    status: started
                    correlation_id: 0f5d6c2e-6a1f-4c6e-9d6b-2b1f0c7e8a91
                    phone_number: '+61491570006'
                    country: AU
        '400':
          description: >-
            Bad request, or the register rejected the number
            (`invalid_phone_number`, charged).
          headers:
            X-Meer-Correlation-Id:
              $ref: '#/components/headers/CorrelationId'
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/RequestError'
                  - $ref: '#/components/schemas/LookupError'
              examples:
                missing_parameter:
                  value:
                    error: missing phone_number parameter
                not_e164:
                  value:
                    error: >-
                      phone number is not in e.164 format - please double check
                      the format and try again
                malformed_number:
                  value:
                    error: >-
                      phone number is malformed - please double check the format
                      and try again
                bad_webhook_url:
                  value:
                    error: 'webhook_url is invalid: only https URLs are accepted'
                invalid_phone_number:
                  value:
                    error: DNC provider marked the phone number as invalid
                    error_code: invalid_phone_number
                    charged: true
        '401':
          description: Missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestError'
              examples:
                missing_key:
                  value:
                    error: >-
                      Missing API key. Please provide it as: Authorization:
                      Bearer <YOUR_KEY>
        '403':
          description: Invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestError'
              examples:
                invalid_key:
                  value:
                    error: invalid API key
        '422':
          description: Unsupported country.
          headers:
            X-Meer-Correlation-Id:
              $ref: '#/components/headers/CorrelationId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestError'
              examples:
                unsupported_country:
                  value:
                    error: country not supported
                    country: CN
                    supported_countries:
                      - US
                      - GB
                      - DE
                      - IE
                      - BE
                      - NZ
                      - ES
                      - AU
        '429':
          description: >-
            Credit limit reached. Requests return 429 until the next billing
            period or a credit top-up.
          headers:
            X-Meer-Correlation-Id:
              $ref: '#/components/headers/CorrelationId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestError'
              examples:
                exhausted:
                  value:
                    error: >-
                      Rate limit exceeded. Please try again next month or
                      contact support.
        '500':
          description: >-
            Server error. `billing_error` means credits could not be settled;
            `charged` says whether you paid.
          headers:
            X-Meer-Correlation-Id:
              $ref: '#/components/headers/CorrelationId'
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/RequestError'
                  - $ref: '#/components/schemas/LookupError'
              examples:
                billing_error:
                  value:
                    error: Credit finalization failed
                    error_code: billing_error
                    charged: false
                unable_to_process:
                  value:
                    error: unable to process request
                usage_update_failed:
                  value:
                    error: Failed to update usage statistics
        '502':
          description: The upstream register failed. Synchronous only. Not charged.
          headers:
            X-Meer-Correlation-Id:
              $ref: '#/components/headers/CorrelationId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupError'
              examples:
                upstream_error:
                  value:
                    error: upstream provider could not process the request
                    error_code: upstream_error
                    charged: false
        '504':
          description: The upstream register timed out. Synchronous only. Not charged.
          headers:
            X-Meer-Correlation-Id:
              $ref: '#/components/headers/CorrelationId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupError'
              examples:
                upstream_timeout:
                  value:
                    error: upstream provider timed out
                    error_code: upstream_timeout
                    charged: false
      callbacks:
        lookupFinished:
          '{$request.query.webhook_url}':
            post:
              summary: Lookup result
              description: >-
                Sent when a webhook lookup finishes. Delivery is at least once,
                so deduplicate on `correlation_id`. Reply 2xx within 10 seconds.
                5xx, 408, 425 and 429 are retried with backoff (30 seconds to 1
                hour, up to 10 attempts); other statuses are not. Redirects are
                not followed.
              parameters:
                - name: X-Meer-Correlation-Id
                  in: header
                  required: true
                  schema:
                    type: string
                    format: uuid
                - name: X-Meer-Phone-Number
                  in: header
                  required: true
                  schema:
                    type: string
                - name: X-Meer-Country
                  in: header
                  required: true
                  schema:
                    type: string
                - name: X-Meer-Status
                  in: header
                  required: true
                  description: The HTTP status the synchronous lookup would have returned.
                  schema:
                    type: string
                    enum:
                      - '200'
                      - '400'
                      - '500'
                      - '502'
                - name: User-Agent
                  in: header
                  required: true
                  schema:
                    type: string
                    const: Meer-Webhooks/1.0
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      oneOf:
                        - $ref: '#/components/schemas/SucceededPush'
                        - $ref: '#/components/schemas/FailedPush'
                    examples:
                      succeeded:
                        value:
                          status: succeeded
                          error_code: null
                          correlation_id: 0f5d6c2e-6a1f-4c6e-9d6b-2b1f0c7e8a91
                          phone_number: '+61491570006'
                          country: AU
                          do_not_call: true
                          timestamp: '2026-09-28T04:01:05.123456+00:00'
                          dnc_list_source: https://www.donotcall.gov.au
                          cost:
                            credits_used_for_query: 2
                            total_credits_used: 5120
                            credit_limit: 25000
                      invalid_phone_number:
                        value:
                          status: failed
                          error_code: invalid_phone_number
                          error: DNC provider marked the phone number as invalid
                          charged: true
                          correlation_id: 0f5d6c2e-6a1f-4c6e-9d6b-2b1f0c7e8a91
                          phone_number: '+61491570006'
                          country: AU
                      lookup_expired:
                        value:
                          status: failed
                          error_code: lookup_expired
                          error: the lookup could not be completed
                          charged: false
                          correlation_id: 0f5d6c2e-6a1f-4c6e-9d6b-2b1f0c7e8a91
                          phone_number: '+61491570006'
                          country: AU
                      billing_error:
                        value:
                          status: failed
                          error_code: billing_error
                          error: Credit finalization failed
                          charged: false
                          correlation_id: 0f5d6c2e-6a1f-4c6e-9d6b-2b1f0c7e8a91
                          phone_number: '+61491570006'
                          country: AU
              responses:
                2XX:
                  description: Delivered. The body is ignored.
                4XX:
                  description: >-
                    A permanent failure and not retried, except 408, 425 and
                    429, which are retried with backoff.
                5XX:
                  description: >-
                    Retried with backoff from 30 seconds up to one hour, for up
                    to 10 attempts.
              method: post
              type: path
            path: '{$request.query.webhook_url}'
components:
  headers:
    CorrelationId:
      description: >-
        ID of this request and, in webhook mode, of the lookup. Quote it to
        support.
      schema:
        type: string
        format: uuid
    CreditCost:
      description: Credits charged for this lookup.
      schema:
        type: integer
    RateLimitLimit:
      description: Your credit limit for the billing period.
      schema:
        type: integer
    RateLimitRemaining:
      description: Credits left in the billing period.
      schema:
        type: integer
  schemas:
    Answer:
      type: object
      required:
        - do_not_call
        - timestamp
        - dnc_list_source
        - cost
      properties:
        do_not_call:
          type: boolean
          description: '`true` if the number is on the register.'
        timestamp:
          type: string
          format: date-time
          description: When the check ran.
        dnc_list_source:
          type:
            - string
            - 'null'
          description: >-
            The register that answered. Can be `null` when the number is not
            listed.
        cost:
          $ref: '#/components/schemas/Cost'
    Receipt:
      type: object
      required:
        - status
        - correlation_id
        - phone_number
        - country
      properties:
        status:
          allOf:
            - $ref: '#/components/schemas/Status'
          const: started
        correlation_id:
          type: string
          format: uuid
          description: >-
            Identifies the lookup; every push for it carries the same value.
            Quote it to support.
        phone_number:
          type: string
        country:
          type: string
    RequestError:
      type: object
      required:
        - error
      properties:
        error:
          type: string
        country:
          type: string
          description: '422 only: the country of the number.'
        supported_countries:
          type: array
          items:
            type: string
          description: 422 only.
    LookupError:
      type: object
      required:
        - error
        - error_code
        - charged
      properties:
        error:
          type: string
        error_code:
          $ref: '#/components/schemas/ErrorCode'
        charged:
          type: boolean
    SucceededPush:
      title: Succeeded
      allOf:
        - $ref: '#/components/schemas/PushIdentity'
        - $ref: '#/components/schemas/Answer'
        - type: object
          properties:
            status:
              allOf:
                - $ref: '#/components/schemas/Status'
              const: succeeded
            error_code:
              type: 'null'
    FailedPush:
      title: Failed
      allOf:
        - $ref: '#/components/schemas/PushIdentity'
        - $ref: '#/components/schemas/LookupError'
        - type: object
          properties:
            status:
              allOf:
                - $ref: '#/components/schemas/Status'
              const: failed
    Cost:
      type: object
      required:
        - credits_used_for_query
        - total_credits_used
        - credit_limit
      properties:
        credits_used_for_query:
          type: integer
          description: Credits this lookup cost.
        total_credits_used:
          type: integer
          description: Credits used in the billing period.
        credit_limit:
          type: integer
          description: Your credit limit for the billing period.
    Status:
      type: string
      enum:
        - started
        - succeeded
        - failed
    ErrorCode:
      type: string
      enum:
        - invalid_phone_number
        - upstream_timeout
        - upstream_error
        - lookup_expired
        - billing_error
      description: See [Webhooks](/api-reference/webhooks#error-codes) for the full table.
    PushIdentity:
      type: object
      required:
        - status
        - error_code
        - correlation_id
        - phone_number
        - country
      properties:
        correlation_id:
          type: string
          format: uuid
          description: The correlation_id from the receipt. Deduplicate on it.
        phone_number:
          type: string
        country:
          type: string
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: '`Authorization: Bearer <YOUR_API_KEY>`. The `Bearer` prefix is optional.'
      bearerFormat: API key

````