Sinch Phone Numbers API

openapi: 3.2.0
info:
  title: Sinch Phone Numbers API
  version: '1.0'
  description: 'Operations tagged Phone Numbers across 2 of this provider''s published API definitions: sinch-elastic-sip-trunking-api-openapi.yaml, original-sinch-elastic-sip-trunking-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://elastic-trunking.api.sinch.com
tags:
- name: Phone Numbers
  description: The `/phoneNumbers` endpoint has operations that allow you to assign and remove phone numbers from SIP trunks.
paths:
  /v1/projects/{projectId}/phoneNumbers:
    parameters:
    - $ref: '#/components/parameters/ProjectId'
    - $ref: '#/components/parameters/SipTrunkIdQuery'
    - $ref: '#/components/parameters/Page'
    - $ref: '#/components/parameters/Size'
    - $ref: '#/components/parameters/Sort'
    get:
      summary: Get all phone numbers
      description: Get all phone numbers. You can filter and sort the phone numbers returned with paging.
      operationId: GetPhoneNumbers
      tags:
      - Phone Numbers
      responses:
        '200':
          description: A successful response is an array containing phone numbers.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Pagination'
                - type: object
                  properties:
                    phoneNumbers:
                      type: array
                      items:
                        $ref: '#/components/schemas/Number'
      x-codeSamples:
      - 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 phoneNumbers = [];\n    for await (const entry of sinch.elasticSipTrunking.phoneNumbers.list({})) {\n      phoneNumbers.push(entry);\n    }\n    if (!phoneNumbers.length) {\n      console.log('No phone numbers found.');\n      return;\n    }\n    console.log(`✅ Found ${phoneNumbers.length} phone numbers.`);\n    phoneNumbers.forEach((number) => {\n      console.log(number);\n    });\n  } catch (err) {\n    console.error('❌ Failed to list phone numbers:');\n    console.error(err);\n  }\n}\n\nmain();\n"
      security:
      - Basic: []
      - OAuth2.0: []
    servers:
    - url: https://elastic-trunking.api.sinch.com
  /v1/projects/{projectId}/phoneNumbers/{phoneNumber}:
    parameters:
    - $ref: '#/components/parameters/ProjectId'
    - $ref: '#/components/parameters/PhoneNumber'
    get:
      summary: Find a specific phone number
      description: Search for an Elastic SIP Trunk-enabled phone number by the e.164 number.
      operationId: GetPhoneNumberByNumber
      tags:
      - Phone Numbers
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Number'
      x-codeSamples:
      - 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  // The phone number you want to search for.\n  const phoneNumber = process.env.PHONE_NUMBER ?? '+15552229999';\n\n  const sinch = new SinchClient({ projectId, keyId, keySecret });\n\n  try {\n    const response = await sinch.elasticSipTrunking.phoneNumbers.get({\n      phoneNumber,\n    });\n    console.log('✅ Successfully retrieved the phone number.');\n    console.log(JSON.stringify(response, null, 2));\n  } catch (err) {\n    console.error(`❌ Failed to retrieve the phone number ${phoneNumber}:`);\n    console.error(err);\n  }\n}\n\nmain();\n"
      security:
      - Basic: []
      - OAuth2.0: []
    servers:
    - url: https://elastic-trunking.api.sinch.com
  /v1/projects/{project_id}/trunks/{trunk_id}/phoneNumbers:
    get:
      operationId: listTrunkPhoneNumbers
      summary: List Phone Numbers for a Trunk
      description: Returns the list of phone numbers assigned to a specific SIP trunk.
      tags:
      - Phone Numbers
      parameters:
      - $ref: '#/components/parameters/ProjectId_2'
      - $ref: '#/components/parameters/TrunkId'
      responses:
        '200':
          description: List of phone numbers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrunkPhoneNumberList'
        '401':
          description: Unauthorized
      security:
      - oAuth2: []
      - basicAuth: []
    post:
      operationId: addPhoneNumberToTrunk
      summary: Add Phone Number to Trunk
      description: Assigns a phone number to a SIP trunk for inbound and outbound calling.
      tags:
      - Phone Numbers
      parameters:
      - $ref: '#/components/parameters/ProjectId_2'
      - $ref: '#/components/parameters/TrunkId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddPhoneNumberRequest'
      responses:
        '200':
          description: Phone number added
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
      security:
      - oAuth2: []
      - basicAuth: []
    servers:
    - url: https://elastic-trunking.api.sinch.com
      description: Global Production Server
  /v1/projects/{project_id}/trunks/{trunk_id}/phoneNumbers/{phone_number}:
    delete:
      operationId: removePhoneNumberFromTrunk
      summary: Remove Phone Number from Trunk
      description: Removes a phone number from a SIP trunk.
      tags:
      - Phone Numbers
      parameters:
      - $ref: '#/components/parameters/ProjectId_2'
      - $ref: '#/components/parameters/TrunkId'
      - name: phone_number
        in: path
        required: true
        description: The phone number in E.164 format
        schema:
          type: string
      responses:
        '200':
          description: Phone number removed
        '401':
          description: Unauthorized
        '404':
          description: Phone number not found
      security:
      - oAuth2: []
      - basicAuth: []
    servers:
    - url: https://elastic-trunking.api.sinch.com
      description: Global Production Server
components:
  schemas:
    Pagination:
      type: object
      readOnly: true
      properties:
        totalItems:
          type: integer
          readOnly: true
          format: int32
          description: Total size of the result.
          example: 10000
        pageNumber:
          readOnly: true
          type: string
          description: The token to be used for listing the next page
          example: '1'
        size:
          type: integer
          readOnly: true
          format: int32
          description: The number of items per page. default is 1000
          example: 2000
    PhoneNumber:
      type: string
      description: A phone number in [E.164](https://community.sinch.com/t5/Glossary/E-164/ta-p/7537) format, including the leading '+'.
      example: '+15551239898'
    Number:
      type: object
      properties:
        id:
          type: string
          readOnly: true
          description: The ID of the phone number.
          example: 01ARZ3NDEKTSV4RRFFQ69G5FAV
        sipTrunkId:
          type: string
          readOnly: true
          example: 5RTRZ3NDEKTSV4RRFFQ69G5EWS
          description: The ID of the SIP trunk to which the phone number is assigned.
        phoneNumber:
          description: A Sinch phone number on your account and configured for Elastic SIP Trunking.
          allOf:
          - $ref: '#/components/schemas/PhoneNumber'
          example: '+15552229999'
        countryCode:
          readOnly: true
          type: string
          description: The country code of the phone number in ISO 3166-1 alpha-2 format.
          example: US
        createTime:
          type: string
          description: The date and time that the number was assigned to the SIP trunk.
          format: date-time
          readOnly: true
          example: '2022-01-01T00:00:00Z'
        updateTime:
          type: string
          description: The date and time that the phone number was last modified.
          format: date-time
          readOnly: true
          example: '2022-01-01T00:00:00Z'
      description: A Sinch phone number assigned to a SIP trunk. This must be a number you own and configured for Elastic SIP Trunking.
    AddPhoneNumberRequest:
      type: object
      required:
      - phoneNumber
      properties:
        phoneNumber:
          type: string
          description: The phone number in E.164 format to assign
    TrunkPhoneNumberList:
      type: object
      properties:
        phoneNumbers:
          type: array
          description: List of phone numbers
          items:
            type: object
            properties:
              phoneNumber:
                type: string
                description: The phone number in E.164 format
              trunkId:
                type: string
                description: The trunk ID
  parameters:
    PhoneNumber:
      name: phoneNumber
      in: path
      description: The phone number you want to search for. Must be in E.164 format.
      required: true
      schema:
        type: string
        example: '+12225559999'
    SipTrunkIdQuery:
      name: sipTrunkId
      in: query
      description: The ID of the SIP trunk to search for.
      required: false
      schema:
        minimum: 0
        type: integer
        format: int64
    Sort:
      name: sort
      in: query
      description: An array setting the sorting criteria in the format of `property,(ascending/descending)`
      schema:
        type: array
        items:
          type: string
    Page:
      in: query
      name: page
      description: The page you want to fetch, can set to 1 for first page, or omitted for first page
      schema:
        type: integer
        default: 1
    ProjectId:
      name: projectId
      in: path
      required: true
      description: The `projectId` is a required parameter you must include when making any API calls. You can find your project ID on your [Build dashboard](https://dashboard.sinch.com).
      schema:
        type: string
        example: 3acb7ae1-cf3d-4112-ba5e-3a9d8c71cd47
    Size:
      in: query
      name: size
      description: The size of each page to fetch
      schema:
        type: integer
        default: 500
        minimum: 1
        maximum: 500
    TrunkId:
      name: trunk_id
      in: path
      required: true
      description: The unique SIP trunk identifier
      schema:
        type: string
    ProjectId_2:
      name: project_id
      in: path
      required: true
      description: The unique project identifier
      schema:
        type: string
  securitySchemes:
    Basic:
      type: http
      description: To use basic authentication, use your Access Key ID as your username and your Access Key Secret as your password. To read about more basic authentication, see the [Basic Authentication](https://developers.sinch.com/docs/est/api-reference/est#basic) section.
      scheme: basic
    OAuth2.0:
      type: oauth2
      description: To use OAuth 2.0 authentication, use your Access Key ID and Access Key Secret to obtain your bearer token. For detailed instructions on how to do this, see the [OAuth Authentication](https://developers.sinch.com/docs/est/api-reference/est#oauth) section.
      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 Elastic SIP Trunking API Documentation
  url: https://developers.sinch.com/docs/est
x-refined-from:
- sinch-elastic-sip-trunking-api-openapi.yaml
- original-sinch-elastic-sip-trunking-openapi.yml
x-explorer-enabled: false
x-samples-languages:
- curl
- java
- csharp
- node
- php
x-original-swagger-version: '2.0'