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

# Look up numbers

> Checks up to 100 numbers against the mobile network without messaging them. Returns validity, country, network, porting and roaming for each number.



## OpenAPI

````yaml openapi-sms.yaml POST /api/v1/Account/{auth_id}/Sms/Lookup/
openapi: 3.0.3
info:
  title: Vobiz Messaging API
  description: >
    Send and receive SMS, MMS and RCS messages, buy messaging numbers, register
    for

    US 10DLC and toll-free, run broadcasts, manage conversations, opt-outs and
    webhooks.


    **Base URL:** `https://api.vobiz.ai/api/v1/Account/{auth_id}/Sms`, where
    `{auth_id}` is your

    account Auth ID. Paths in descriptions, such as `POST /Message/`, are
    relative to it.

    Coverage (`/api/v1/sms/coverage`) and `/api/v1/sms/numbers/countries` are
    not account data

    and keep their `https://api.vobiz.ai/api/v1/sms` URLs.


    **Authentication:** every request needs the `X-Auth-ID` and `X-Auth-Token`
    headers. The

    `{auth_id}` in the path must be the account those credentials belong to,
    otherwise the

    request returns `403`. Field names in this API are camelCase.


    The earlier URLs under `https://api.vobiz.ai/api/v1/sms` (for example `POST
    /api/v1/sms/messages`)

    still work.
  version: '1.0'
  contact:
    email: support@vobiz.ai
    url: https://www.vobiz.ai
servers:
  - url: https://api.vobiz.ai
    description: Production
security:
  - AuthID: []
    AuthToken: []
tags:
  - name: Messages
    description: Send messages and inspect their delivery state.
  - name: Numbers
    description: >-
      Messaging-capable numbers on your account, inventory search, purchase and
      release.
  - name: Number lookup
    description: >-
      Check whether numbers exist and are reachable on the mobile network, and
      which network serves them.
  - name: Coverage
    description: Where you can send, per country.
  - name: Conversations
    description: Two-way threads between one of your numbers and a contact.
  - name: Opt-outs
    description: Numbers that must not receive messages on a channel.
  - name: Webhooks
    description: Subscriptions that deliver message and broadcast events to your server.
  - name: Broadcasts
    description: Bulk sends from an uploaded recipient list.
  - name: RCS Senders
    description: RCS sender (agent) identities and their message templates.
  - name: 10DLC Brands
    description: US 10DLC brand registration.
  - name: 10DLC Campaigns
    description: US 10DLC campaigns, toll-free verification and supporting documents.
paths:
  /api/v1/Account/{auth_id}/Sms/Lookup/:
    parameters:
      - $ref: '#/components/parameters/AuthId'
    post:
      tags:
        - Number lookup
      summary: Look up numbers
      description: >-
        Checks up to 100 numbers against the mobile network (an HLR lookup)
        without messaging them. For each number it returns whether it is valid
        and reachable, its country, the network that serves it, and whether it
        was ported or is roaming. Use it to clean a list before a broadcast or
        to validate a number at sign-up.


        Results come back in the order you sent the numbers, one per distinct
        input. An input that cannot be read as a phone number gets `valid:
        false` and a `reason`, and is not sent to the network. A result for the
        same number from the last 24 hours is reused (`cached: true`) unless you
        set `fresh`. Numbers sent to the network count toward a daily limit of
        1000 per account (UTC day); cached results and unreadable inputs do not.
        Every looked-up number is recorded in `GET /Lookup/History/`.
      operationId: lookup-numbers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LookupRequest'
            example:
              numbers:
                - '+14155550123'
                - '12345'
              defaultCountry: US
      responses:
        '200':
          description: One result per distinct input.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupResponse'
              example:
                results:
                  - input: '+14155550123'
                    number: '+14155550123'
                    valid: false
                    status:
                      group: REJECTED
                      name: REJECTED_ROUTE_NOT_AVAILABLE
                      description: Route not available
                    error: null
                    country:
                      iso: US
                      name: United States
                      dialCode: '1'
                    network: null
                    originalNetwork: null
                    ported: false
                    portedNetwork: null
                    roaming: false
                    roamingNetwork: null
                    cached: false
                    checkedAt: '2026-10-12T10:30:00Z'
                  - input: '12345'
                    number: ''
                    valid: false
                    reason: too short
                    status: null
                    error: null
                    country: null
                    network: null
                    originalNetwork: null
                    ported: false
                    portedNetwork: null
                    roaming: false
                    roamingNetwork: null
                    cached: false
                    checkedAt: '2026-10-12T10:30:00Z'
        '400':
          description: >-
            The body is not a JSON object (or is larger than 256 KB), or
            `numbers` is missing or empty.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                body:
                  value:
                    error: invalid request body
                numbers:
                  value:
                    error: numbers is required
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          description: >-
            More than 100 numbers, an unsupported `defaultCountry`, or the
            request was rejected by the network.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                tooMany:
                  value:
                    error: 'too many numbers: at most 100 per request'
                country:
                  value:
                    error: unsupported defaultCountry
        '429':
          description: >-
            The request would go over the daily lookup limit, or the lookup
            service is busy. Nothing was looked up; retry later, or with fewer
            numbers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                daily:
                  value:
                    error: >-
                      daily number lookup limit reached: 995 of 1000 used today
                      (UTC), this request needs 10 more
                busy:
                  value:
                    error: number lookup is busy, try again shortly
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          description: The lookup couldn't be completed. Retry later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: number lookup failed, try again later
        '503':
          description: Number lookup is temporarily unavailable. Retry later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: number lookup is not available yet
components:
  parameters:
    AuthId:
      name: auth_id
      in: path
      required: true
      description: Your account Auth ID. It must match the `X-Auth-ID` header.
      schema:
        type: string
        example: MA_XXXXXXXX
  schemas:
    LookupRequest:
      type: object
      description: Numbers to check against the mobile network.
      required:
        - numbers
      properties:
        numbers:
          type: array
          minItems: 1
          maxItems: 100
          description: >-
            Numbers to check, in E.164 format (`+14155550123`) or national
            format read with `defaultCountry`. At most 100 per request. A
            missing or empty array returns `400` with `numbers is required`;
            more than 100 returns `422` with `too many numbers: at most 100 per
            request`. Duplicates (the same E.164 number, or the same invalid
            text) are checked once.
          items:
            type: string
          example:
            - '+14155550123'
            - (415) 555-0124
        defaultCountry:
          type: string
          default: US
          description: >-
            ISO 3166-1 alpha-2 country code, matched case-insensitively, used to
            read numbers written without a `+` country code. Defaults to `US`. A
            code outside the list returns `422` with `unsupported
            defaultCountry`.
          enum:
            - US
            - CA
            - GB
            - IN
            - AU
            - NZ
            - IE
            - DE
            - FR
            - ES
            - IT
            - NL
            - BE
            - CH
            - AT
            - SE
            - 'NO'
            - DK
            - FI
            - PL
            - PT
            - BR
            - MX
            - AR
            - CO
            - CL
            - SG
            - MY
            - ID
            - PH
            - TH
            - VN
            - JP
            - KR
            - CN
            - HK
            - AE
            - SA
            - QA
            - IL
            - TR
            - ZA
            - NG
            - KE
            - EG
            - PK
            - BD
            - LK
            - NP
        fresh:
          type: boolean
          default: false
          description: >-
            `true` skips the cache and asks the network again. By default a
            result for the same number from the last 24 hours is reused and
            returned with `cached: true`.
    LookupResponse:
      type: object
      description: One result per distinct input, in the order you sent them.
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/LookupResult'
    Error:
      type: object
      description: >-
        The body of every error response: a flat object with one `error` string
        that explains what went wrong. Use the HTTP status code to decide how to
        handle the error, and log `error` for diagnosis.
      required:
        - error
      properties:
        error:
          type: string
          example: 'recipient has opted out: +14155550123'
          description: >-
            Human-readable explanation of the error, for example `phoneNumber is
            required` or `recipient has opted out: +14155550123`. Branch on the
            HTTP status code rather than on this text.
    LookupResult:
      type: object
      description: >-
        The result of checking one number. Inputs that could not be read as a
        phone number, or that got no answer, have `valid: false`, a `reason` and
        `null` for the network fields.
      properties:
        input:
          type: string
          description: The value you sent, trimmed.
          example: '+14155550123'
        number:
          type: string
          description: >-
            The number in E.164 format. An empty string when `input` could not
            be read as a phone number.
          example: '+14155550123'
        valid:
          type: boolean
          description: >-
            `true` when the number exists and is reachable: the status group is
            `DELIVERED`, or the network reported neither a status nor an error.
            `false` for a permanent error, any other status group, or an input
            that was not looked up.
        reason:
          type: string
          description: Why the number was not looked up. Present only for those inputs.
          enum:
            - missing phone number
            - contains letters or symbols
            - too short
            - too long
            - not a valid US/Canada number
            - not a valid Indian mobile number
            - no result for this number
        status:
          allOf:
            - $ref: '#/components/schemas/LookupStatus'
          nullable: true
          description: >-
            The network status. `null` when the network returned none or the
            number was not looked up.
        error:
          allOf:
            - $ref: '#/components/schemas/LookupFailure'
          nullable: true
          description: The network error. `null` when there was none.
        country:
          allOf:
            - $ref: '#/components/schemas/LookupCountry'
          nullable: true
          description: The number's country. `null` when it is unknown.
        network:
          allOf:
            - $ref: '#/components/schemas/LookupNetwork'
          nullable: true
          description: The network that serves the number now. `null` when it is unknown.
        originalNetwork:
          allOf:
            - $ref: '#/components/schemas/LookupNetworkName'
          nullable: true
          description: >-
            The network the number was originally issued by. `null` when it is
            unknown.
        ported:
          type: boolean
          description: '`true` when the number was moved to another network.'
        portedNetwork:
          allOf:
            - $ref: '#/components/schemas/LookupNetworkName'
          nullable: true
          description: >-
            The network the number was ported to. `null` unless `ported` is
            `true` and the network is known.
        roaming:
          type: boolean
          description: '`true` when the handset is roaming on another network.'
        roamingNetwork:
          allOf:
            - $ref: '#/components/schemas/LookupNetworkName'
          nullable: true
          description: >-
            The network the handset is roaming on. `null` unless `roaming` is
            `true` and the network is known.
        cached:
          type: boolean
          description: >-
            `true` when the result was reused from a lookup of the same number
            in the last 24 hours instead of asking the network again.
        checkedAt:
          type: string
          format: date-time
          description: >-
            When the network was asked, in RFC 3339 UTC. For a cached result,
            the time of the original lookup.
          example: '2026-10-12T10:30:00Z'
    GatewayError:
      type: object
      description: >-
        Error body returned by the Vobiz API gateway for authentication (`401`)
        and account-mismatch (`403`) failures, before the request reaches the
        messaging service. Unlike `Error`, `error` is an object.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: integer
              example: 401
              description: The HTTP status code, repeated.
            message:
              type: string
              example: Invalid authentication credentials
              description: Human-readable explanation of the failure.
    LookupStatus:
      type: object
      description: The network's answer for the number.
      properties:
        group:
          type: string
          description: >-
            Status group, upper-case, for example `DELIVERED` (the number is
            reachable), `UNDELIVERABLE`, `REJECTED`, `PENDING` or `EXPIRED`.
            `valid` is `true` only for `DELIVERED`.
          example: REJECTED
        name:
          type: string
          description: >-
            Detailed status name within the group, for example
            `REJECTED_ROUTE_NOT_AVAILABLE`.
          example: REJECTED_ROUTE_NOT_AVAILABLE
        description:
          type: string
          description: Human-readable explanation of the status.
          example: Route not available
    LookupFailure:
      type: object
      description: The network error for the number. `null` when there was none.
      properties:
        name:
          type: string
          description: Error name reported by the network.
        description:
          type: string
          description: Human-readable explanation of the error.
        permanent:
          type: boolean
          description: >-
            `true` when the error is permanent, for example a number that does
            not exist. A permanent error makes `valid` `false`.
    LookupCountry:
      type: object
      description: The country the number belongs to.
      properties:
        iso:
          type: string
          description: >-
            ISO 3166-1 alpha-2 country code. An empty string when the country
            could only be named, not matched to a code.
          example: US
        name:
          type: string
          description: Country name.
          example: United States
        dialCode:
          type: string
          description: Country calling code, without `+`.
          example: '1'
    LookupNetwork:
      type: object
      description: >-
        The network that serves the number now (the ported network when the
        number was ported).
      properties:
        name:
          type: string
          description: >-
            Network (carrier) name. An empty string when only the MCC/MNC is
            known.
          example: Example Mobile
        mccMnc:
          type: string
          description: >-
            Mobile country code and mobile network code of the serving network,
            for example `310260`.
          example: '310260'
    LookupNetworkName:
      type: object
      description: A network (carrier), by name.
      properties:
        name:
          type: string
          description: Network (carrier) name.
          example: Example Mobile
  responses:
    Unauthorized:
      description: >-
        Missing or invalid `X-Auth-ID` / `X-Auth-Token`. The API gateway answers
        before the request reaches the messaging service, so `error` is an
        object with `code` and `message`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GatewayError'
          examples:
            missing:
              summary: No credentials
              value:
                error:
                  code: 401
                  message: >-
                    Authentication required: provide either Authorization header
                    or X-Auth-ID and X-Auth-Token headers
            invalid:
              summary: Wrong Auth Token
              value:
                error:
                  code: 401
                  message: Invalid authentication credentials
    Forbidden:
      description: >-
        The `{auth_id}` in the path is not the account that the `X-Auth-ID` /
        `X-Auth-Token` credentials belong to. The API gateway answers, so
        `error` is an object with `code` and `message`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GatewayError'
          example:
            error:
              code: 403
              message: 'Access denied: account ID mismatch'
    ServerError:
      description: Unexpected error. Retry with the same idempotency key where one applies.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: internal error
  securitySchemes:
    AuthID:
      type: apiKey
      in: header
      name: X-Auth-ID
      description: Your Vobiz account Auth ID (`MA_XXXXXXXX`).
    AuthToken:
      type: apiKey
      in: header
      name: X-Auth-Token
      description: Your Vobiz account Auth Token.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.