Sinch Available Regions API

openapi: 3.2.0
info:
  title: Sinch Available Regions API
  version: '1.0'
  description: 'Operations tagged Available Regions across 2 of this provider''s published API definitions: sinch-numbers-api-openapi.yaml, original-sinch-numbers-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://numbers.api.sinch.com
  description: Global API
tags:
- name: Available Regions
  description: You can use the Available Regions API to list all of the regions that have numbers assigned to a project.
paths:
  /v1/projects/{projectId}/availableRegions:
    parameters:
    - $ref: '#/components/parameters/projectId'
    - name: types
      description: "Only return regions for which numbers are provided with the given types: `MOBILE`, `LOCAL` or `TOLL_FREE`.\n\n  - MOBILE: Numbers that belong to a specific range.\n  - LOCAL: Numbers that are assigned to a specific geographic region.\n  - TOLL_FREE: Number that are free of charge for the calling party but billed for all arriving calls.\n\nIf you want to see all results, do not add the `types` query parameter."
      in: query
      required: false
      schema:
        type: array
        items:
          $ref: '#/components/schemas/NumberType'
    get:
      summary: List available regions
      description: Lists all regions for numbers provided for the project ID.
      operationId: NumberService_ListAvailableRegions
      responses:
        '200':
          $ref: '#/components/responses/ListAvailableRegionsResponse'
        '400':
          description: 400 Invalid Argument error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument'
        '403':
          $ref: '#/components/responses/PermissionDenied'
        '404':
          description: 404 Not Found error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '500':
          description: 500 Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
      tags:
      - Available Regions
      x-codeSamples:
      - lang: Java
        source: "/**\n * Sinch Java Snippet\n *\n * <p>This snippet is available at https://github.com/sinch/sinch-sdk-java\n *\n * <p>See https://github.com/sinch/sinch-sdk-java/blob/main/examples/snippets/README.md for details\n */\npackage numbers.regions;\n\nimport com.sinch.sdk.SinchClient;\nimport com.sinch.sdk.domains.numbers.api.v1.AvailableRegionsService;\nimport com.sinch.sdk.domains.numbers.models.v1.regions.response.AvailableRegionsListResponse;\nimport com.sinch.sdk.models.Configuration;\nimport java.util.logging.Logger;\nimport utils.Settings;\n\npublic class List {\n\n  private static final Logger LOGGER = Logger.getLogger(List.class.getName());\n\n  public static void main(String[] args) {\n\n    String projectId = Settings.getProjectId().orElse(\"MY_PROJECT_ID\");\n    String keyId = Settings.getKeyId().orElse(\"MY_KEY_ID\");\n    String keySecret = Settings.getKeySecret().orElse(\"MY_KEY_SECRET\");\n\n    Configuration configuration =\n        Configuration.builder()\n            .setProjectId(projectId)\n            .setKeyId(keyId)\n            .setKeySecret(keySecret)\n            .build();\n\n    SinchClient client = new SinchClient(configuration);\n\n    AvailableRegionsService availableRegionsService = client.numbers().v1().regions();\n\n    LOGGER.info(\"List\");\n\n    AvailableRegionsListResponse response = availableRegionsService.list();\n\n    LOGGER.info(\"Available regions:\");\n\n    response.iterator().forEachRemaining(item -> LOGGER.info(String.format(\"- %s\", item)));\n  }\n}\n"
      - lang: Node.js
        source: "/**\n * Sinch Node.js Snippet\n * See: https://github.com/sinch/sinch-sdk-node/examples/snippets\n */\nimport { SinchClient } from '@sinch/sdk-core';\nimport * as dotenv from 'dotenv';\ndotenv.config();\n\nasync function main() {\n  const projectId = process.env.SINCH_PROJECT_ID ?? 'MY_PROJECT_ID';\n  const keyId = process.env.SINCH_KEY_ID ?? 'MY_KEY_ID';\n  const keySecret = process.env.SINCH_KEY_SECRET ?? 'MY_KEY_SECRET';\n\n  const sinch = new SinchClient({ projectId, keyId, keySecret });\n\n  try{\n    const response = await sinch.numbers.availableRegions.list({});\n    if (!response.availableRegions?.length) {\n      console.log('No regions are available with these criteria.');\n      return;\n    }\n    console.log(`✅ Found ${response.availableRegions.length} available regions.`);\n    response.availableRegions.forEach((region) => {\n      console.log(region);\n    });\n  } catch (err) {\n    console.error('❌ Failed to list available regions:');\n    console.error(err);\n  }\n}\n\nmain();\n"
      - lang: Python
        source: "\"\"\"\nSinch Python Snippet\n\nThis snippet is available at https://github.com/sinch/sinch-sdk-python/tree/main/examples/snippets\n\"\"\"\n\nimport os\nfrom dotenv import load_dotenv\nfrom sinch import SinchClient\n\nload_dotenv()\n\nsinch_client = SinchClient(\n    project_id=os.environ.get(\"SINCH_PROJECT_ID\") or \"MY_PROJECT_ID\",\n    key_id=os.environ.get(\"SINCH_KEY_ID\") or \"MY_KEY_ID\",\n    key_secret=os.environ.get(\"SINCH_KEY_SECRET\") or \"MY_KEY_SECRET\"\n)\n\navailable_regions = sinch_client.numbers.regions.list(\n    number_types=[\"MOBILE\"]\n)\n\nprint(\"Available regions:\\n\")\nfor region in available_regions.iterator():\n    print(region)\n"
      security:
      - Basic: []
      - OAuth2.0: []
    servers:
    - url: https://numbers.api.sinch.com
      description: Global API
  /v1/projects/{project_id}/availableRegions:
    get:
      operationId: listAvailableRegions
      summary: List Available Regions
      description: Returns a list of available regions and the types of phone numbers that can be provisioned in each region.
      tags:
      - Available Regions
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - name: types
        in: query
        description: Filter by number types
        schema:
          type: array
          items:
            type: string
            enum:
            - LOCAL
            - MOBILE
            - TOLL_FREE
      responses:
        '200':
          description: List of available regions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvailableRegionList'
        '401':
          description: Unauthorized
      security:
      - oAuth2: []
      - basicAuth: []
    servers:
    - url: https://numbers.api.sinch.com
      description: Global Production Server
components:
  schemas:
    AvailableRegion:
      type: object
      properties:
        regionCode:
          $ref: '#/components/schemas/RegionCode'
        regionName:
          type: string
          example: United States
          description: 'Display name of the region. Examples: United States, United Kingdom or Sweden.'
          readOnly: true
        types:
          type: array
          example:
          - MOBILE
          items:
            $ref: '#/components/schemas/NumberType'
          description: 'A list of the different number types available. Examples: `MOBILE` or `LOCAL`.'
          readOnly: true
      description: A region for which numbers are provided.
      title: Available Region
    NumberType:
      type: string
      enum:
      - MOBILE
      - LOCAL
      - TOLL_FREE
      x-enumDescriptions:
        MOBILE: Numbers that belong to a specific range.
        LOCAL: Numbers that are assigned to a specific geographic region.
        TOLL_FREE: Numbers that are free of charge for the calling party but billed for all arriving calls.
      description: The number type.
      title: Type
    FieldViolation:
      type: object
      properties:
        field:
          type: string
        description:
          type: string
    InvalidArgument:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              enum:
              - 400
              x-enumDescriptions:
                '400': The HTTP status code for invalid arguments.
            message:
              type: string
            status:
              type: string
              enum:
              - INVALID_ARGUMENT
              x-enumDescriptions:
                INVALID_ARGUMENT: The request contained invalid arguments.
            details:
              type: array
              items:
                $ref: '#/components/schemas/BadRequest'
    InternalError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              enum:
              - 500
              x-enumDescriptions:
                '500': The HTTP status code for an internal server error.
            message:
              type: string
            status:
              type: string
              enum:
              - INTERNAL
              - UNKNOWN
              x-enumDescriptions:
                INTERNAL: An internal server error.
                UNKNOWN: Some unknown error.
            details:
              type: array
              items:
                type: object
    BadRequest:
      type: object
      properties:
        type:
          type: string
          enum:
          - BadRequest
          x-enumDescriptions:
            BadRequest: The request was malformed in some way.
        fieldViolations:
          type: array
          items:
            $ref: '#/components/schemas/FieldViolation'
    ListAvailableRegionsResponse:
      type: object
      properties:
        availableRegions:
          type: array
          items:
            $ref: '#/components/schemas/AvailableRegion'
          title: List of regions for which numbers are provided.
      description: Response message to list regions for which numbers are provided.
      title: List Available Regions Response
    NotFound:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              enum:
              - 404
              x-enumDescriptions:
                '404': The HTTP status code for a resource not found.
            message:
              type: string
            status:
              type: string
              enum:
              - NOT_FOUND
              x-enumDescriptions:
                NOT_FOUND: The request resource could not be found.
            details:
              type: array
              items:
                $ref: '#/components/schemas/NotFoundErrorDetails'
    RegionCode:
      type: string
      example: US
      description: 'ISO 3166-1 alpha-2 country code of the phone number. Example: US, GB or SE.'
      title: Region Code
    NotFoundErrorDetails:
      type: object
      properties:
        type:
          type: string
        resourceType:
          type: string
          description: The type of the resource that was not found.
        resourceName:
          type: string
          description: The name of the resource that was not found.
        owner:
          type: string
          description: The owner of the resource that was not found.
        description:
          type: string
          description: A description of the error.
    AvailableRegionList:
      type: object
      properties:
        availableRegions:
          type: array
          description: List of available regions
          items:
            type: object
            properties:
              regionCode:
                type: string
                description: The ISO 3166-1 alpha-2 country code
              regionName:
                type: string
                description: The region name
              types:
                type: array
                description: Available number types in this region
                items:
                  type: string
  responses:
    PermissionDenied:
      description: 'PERMISSION_DENIED: improper credentials. Be sure your projectId, username and password are correct.'
      content:
        application/json:
          schema: {}
          example:
            error:
              code: 403
              message: ''
              status: PERMISSION_DENIED
              details: []
    ListAvailableRegionsResponse:
      description: A successful response, or an [Error](https://developers.sinch.com/docs/numbers/api-reference/error-codes/status-codes/).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ListAvailableRegionsResponse'
  parameters:
    projectId:
      name: projectId
      description: Found on your [Sinch Customer Dashboard](https://dashboard.sinch.com/settings/project-management). Settings > Projects.
      in: path
      required: true
      schema:
        type: string
        example: YOUR_projectId
    ProjectId:
      name: project_id
      in: path
      required: true
      description: The unique project identifier
      schema:
        type: string
  securitySchemes:
    Basic:
      type: http
      scheme: basic
      description: Your key ID and Key secret serve as the username and password, respectively. Both can be found in the [Sinch Customer Dashboard](https://dashboard.sinch.com/settings/access-keys). For more information about basic authentication in the Numbers API, click [here](https://developers.sinch.com/docs/numbers/api-reference/authentication/basic).
    OAuth2.0:
      type: oauth2
      description: The username and password are your Key ID and Key Secret from the [Access keys section](https://dashboard.sinch.com/settings/access-keys) in the Sinch Customer Dashboard. Exchange these for a bearer token (access token). Learn how [here](https://developers.sinch.com/docs/numbers/api-reference/authentication/oauth).
      flows:
        clientCredentials:
          tokenUrl: https://auth.sinch.com/oauth2/token
          scopes: {}
    oAuth2:
      type: oauth2
      description: OAuth 2.0 client credentials flow.
      flows:
        clientCredentials:
          tokenUrl: https://auth.sinch.com/oauth2/token
          scopes: {}
    basicAuth:
      type: http
      scheme: basic
      description: Key ID as username and key secret as password.
externalDocs:
  description: Sinch Numbers API Documentation
  url: https://developers.sinch.com/docs/numbers
x-refined-from:
- sinch-numbers-api-openapi.yaml
- original-sinch-numbers-openapi.yml
x-explorer-enabled: false
x-samples-languages:
- curl
- java
- csharp
- node
- php
x-original-swagger-version: '2.0'