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

# List area codes

> Lists the area codes that can be requested on a pre-order, and the countries they belong to.

* **Credential:** none.
* **Events:** none.
* **Pages:** none. The whole list is returned in one response. `area_codes` is ordered by `country_code`, then by `area_code`, and `countries` by `country_code`.
* **Meaning:** the list contains the area codes that a pre-order can request. It does not say which lines are in stock, and a pre-order does not check its `preferred_area_codes` against it. See [How a pre-order works](/guides/pre-orders#how-a-pre-order-works).

## Errors

| Status | `error.code` | When |
| - | - | - |
| 400 | `validation_failed` | `country` is not 2 letters. |

The errors that every operation shares are in [Errors](/errors-and-rate-limits#errors).


## OpenAPI

````yaml GET /v1/area-codes
openapi: 3.0.0
info:
  title: iSnap API
  version: 2.45.0
  description: >-
    The iSnap API sends and receives iMessage, RCS and SMS on real phone lines,
    manages those lines, and reports events through webhooks. Every message is
    sent to a real recipient, with an `isnap_live_` key and with an
    `isnap_test_` key alike. Retry a `429` after `Retry-After` seconds. Retry a
    `500` or a `503` up to 2 times, with exponential backoff. Do not retry any
    other `4xx`: fix the request. Retry a write only on an operation that honors
    `Idempotency-Key`, with the key of the first attempt. Responses carry
    personal data: handles, names and message text.
servers:
  - url: https://api.isnap.ai
security:
  - bearerAuth: []
paths:
  /v1/area-codes:
    get:
      summary: List area codes
      description: >-
        Lists the area codes and the countries you can request in
        `preferred_area_codes` on `POST /v1/pre-orders`. Needs no credential.
        This is the list of what can be requested, not of the lines in stock,
        and a pre-order does not check its `preferred_area_codes` against it.
        `country` keeps the area codes of one country; `countries` is never
        filtered. Area codes are ordered by `country_code` then `area_code`, and
        countries by `country_code`. The whole list comes in one response.
      parameters:
        - schema:
            type: string
            pattern: ^[A-Za-z]{2}$
            description: >-
              Keep the area codes of one country: ISO 3166-1 alpha-2 code,
              case-insensitive. A country with no area code returns an empty
              `area_codes`. Omit it for every country.
            example: US
          required: false
          description: >-
            Keep the area codes of one country: ISO 3166-1 alpha-2 code,
            case-insensitive. A country with no area code returns an empty
            `area_codes`. Omit it for every country.
          name: country
          in: query
      responses:
        '200':
          description: The area codes and the countries that can be requested.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AreaCodesEnvelope'
        '400':
          description: >-
            Invalid request. `error.code` is `validation_failed` when a
            parameter, a header or the body does not match its schema:
            `error.issues` then lists each problem.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: >-
            Too many requests. `error.code` is `rate_limit_exceeded` when more
            than 100 requests came from the same network address in 60 seconds,
            whatever their API key or account: wait `error.retry_after` seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: >-
            Unexpected failure. `error.code` is `internal_error`. An operation
            that takes a JSON body also returns it when the body, sent as
            `application/json`, is not valid JSON. Quote `trace_id` when you
            report it to iSnap.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security: []
components:
  schemas:
    AreaCodesEnvelope:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
          description: Always `true` on a success response.
        data:
          $ref: '#/components/schemas/AreaCodes'
        trace_id:
          type: string
          description: >-
            Trace id of the request that produced this response: 32 lowercase
            hexadecimal characters. Quote it when you report a problem to iSnap.
        request_id:
          type: string
          description: >-
            Id of the request that produced this response: `req_` followed by 25
            letters or digits.
      required:
        - success
        - data
        - trace_id
        - request_id
    ErrorEnvelope:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - false
          description: Always `false` on an error response.
        data:
          nullable: true
          description: Always `null` on an error response.
        error:
          type: object
          properties:
            status:
              type: integer
              description: The HTTP status of the response.
            code:
              type: string
              description: >-
                Stable machine-readable code that names the refusal. Branch on
                this value.
            message:
              type: string
              description: >-
                Text for a person. It can change between versions: do not branch
                on it.
            retry_after:
              type: integer
              nullable: true
              description: >-
                Seconds to wait before the next attempt. Set on the `429`
                responses that know a delay, where the `Retry-After` header
                carries the same value. When it is above 60 seconds, do not wait
                in a request: schedule the call, or report the time. `null` on
                every other error.
            retry_at:
              type: string
              nullable: true
              description: >-
                ISO 8601 timestamp at which the refusal ends. Set only on `429
                rebind_cap_reached`. `null` on every other error.
            issues:
              type: array
              nullable: true
              items:
                type: object
                properties:
                  path:
                    type: array
                    items:
                      anyOf:
                        - type: string
                        - type: number
                    description: >-
                      Where the problem is: the field names and array indexes
                      that lead to it.
                  message:
                    type: string
                    description: Text for a person.
                  code:
                    type: string
                    description: >-
                      Kind of problem. On `validation_failed`, for example
                      `invalid_type`, `invalid_value`, `invalid_format`,
                      `invalid_union`, `invalid_key`, `invalid_element`,
                      `too_small`, `too_big`, `not_multiple_of`,
                      `unrecognized_keys` or `custom`. The list is open: read
                      `path` and `message`.
                  min:
                    type: integer
                    description: >-
                      Smallest accepted value. Present only on
                      `limit_out_of_bounds`, `mac_quantity_not_a_pack`,
                      `byop_reduction_strands_mac_sessions` and
                      `byop_reduction_strands_byod_lines`.
                  max:
                    type: integer
                    description: >-
                      Largest accepted value. Present only on
                      `limit_out_of_bounds` and
                      `mac_sessions_exceed_byop_lines`, and on the `too_big`
                      issue of an `Idempotency-Key` header longer than 255
                      characters.
                required:
                  - path
                  - message
                  - code
              description: >-
                Problems found in the request, one entry each. Set on most `400
                validation_failed` responses and on the refusals that name a
                field: a refused `handle` of `POST /v1/lookup` has `issues:
                null`. `null` on every other error.
          required:
            - status
            - code
            - message
            - retry_after
            - retry_at
            - issues
          description: >-
            What went wrong. The six fields are always present; `retry_after`,
            `retry_at` and `issues` are `null` when they do not apply.
        trace_id:
          type: string
          description: >-
            Trace id of the request that produced this response: 32 lowercase
            hexadecimal characters. Quote it when you report a problem to iSnap.
        request_id:
          type: string
          description: >-
            Id of the request that produced this response: `req_` followed by 25
            letters or digits.
      required:
        - success
        - data
        - error
        - trace_id
        - request_id
      description: The body of an error response.
    AreaCodes:
      type: object
      properties:
        area_codes:
          type: array
          items:
            $ref: '#/components/schemas/AreaCode'
          description: >-
            The area codes that can be requested, limited to one country when
            `country` is sent.
        countries:
          type: array
          items:
            $ref: '#/components/schemas/Country'
          description: >-
            The countries that can be requested. `country` does not filter this
            list.
      required:
        - area_codes
        - countries
      description: The area codes and the countries that can be requested on a pre-order.
    AreaCode:
      type: object
      properties:
        area_code:
          type: string
          description: The area code.
          example: '212'
        region:
          type: string
          description: The city and state this area code serves.
          example: New York, NY
        country_code:
          type: string
          description: ISO 3166-1 alpha-2 country of the area code.
          example: US
        purchase_zip:
          type: string
          nullable: true
          description: >-
            A ZIP code in the area this code serves. `null` when iSnap has none
            on record for this area code.
          example: '10019'
        alt_zips:
          type: array
          items:
            type: string
          description: >-
            Other ZIP codes in the same area. Empty when iSnap has none on
            record.
          example:
            - '10021'
            - '10023'
        shared_with:
          type: array
          items:
            type: string
          description: >-
            The other area codes of this list that cover the same area. When it
            is not empty, the number you get can carry any of them. An empty
            list does not guarantee this area code: an area code outside this
            list can cover the same area.
          example:
            - '646'
            - '917'
      required:
        - area_code
        - region
        - country_code
        - purchase_zip
        - alt_zips
        - shared_with
      description: One area code that can be requested on a pre-order.
    Country:
      type: object
      properties:
        country_code:
          type: string
          description: ISO 3166-1 alpha-2 code of the country.
          example: US
        name:
          type: string
          description: Name of the country.
          example: United States
        calling_code:
          type: string
          description: International calling code of the country, digits only.
          example: '1'
      required:
        - country_code
        - name
        - calling_code
      description: One country that can be requested on a pre-order.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        An API key created in the iSnap dashboard, or a trial key, sent as
        `Authorization: Bearer <key>`. An API key starts with `isnap_live_` or
        `isnap_test_`; both act on the same account, lines and billing. A trial
        key acts on its trial only.

````

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