openapi: 3.1.0
info:
  title: Sinch Numbers API
  description: >-
    The Sinch Numbers API enables developers to programmatically search for,
    purchase, configure, and manage phone numbers across multiple countries.
    It supports local, national, mobile, and toll-free number types that can
    be used with Sinch SMS, Voice, and Conversation APIs. The API provides
    endpoints for listing available numbers by region and type, activating
    numbers, updating number configurations, and releasing numbers when they
    are no longer needed.
  version: '1.0'
  contact:
    name: Sinch Support
    url: https://www.sinch.com/contact-us/
  termsOfService: https://www.sinch.com/terms-of-service/
externalDocs:
  description: Sinch Numbers API Documentation
  url: https://developers.sinch.com/docs/numbers
servers:
  - url: https://numbers.api.sinch.com
    description: Global Production Server
tags:
  - name: Active Numbers
    description: >-
      Manage phone numbers that have been purchased and are active in your
      project, including updating configurations and releasing numbers.
  - name: Available Numbers
    description: >-
      Search for available phone numbers by country, type, and capabilities.
  - name: Available Regions
    description: >-
      List available regions and number types that can be provisioned.
security:
  - oAuth2: []
  - basicAuth: []
paths:
  /v1/projects/{project_id}/availableNumbers:
    get:
      operationId: listAvailableNumbers
      summary: List Available Numbers
      description: >-
        Searches for available phone numbers that can be purchased. Results
        can be filtered by country, type, capabilities, number pattern, and
        region.
      tags:
        - Available Numbers
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: regionCode
          in: query
          required: true
          description: The ISO 3166-1 alpha-2 country code
          schema:
            type: string
            minLength: 2
            maxLength: 2
        - name: type
          in: query
          required: true
          description: The number type to search for
          schema:
            type: string
            enum:
              - LOCAL
              - MOBILE
              - TOLL_FREE
        - name: numberPattern.pattern
          in: query
          description: Pattern to search for in the phone number
          schema:
            type: string
        - name: numberPattern.searchPattern
          in: query
          description: Where in the number to search for the pattern
          schema:
            type: string
            enum:
              - START
              - CONTAINS
              - END
        - name: capabilities
          in: query
          description: Filter by capabilities
          schema:
            type: array
            items:
              type: string
              enum:
                - SMS
                - VOICE
        - name: size
          in: query
          description: The maximum number of results to return
          schema:
            type: integer
            default: 30
            maximum: 100
      responses:
        '200':
          description: List of available numbers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvailableNumberList'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
  /v1/projects/{project_id}/availableNumbers/{phone_number}:
    get:
      operationId: getAvailableNumber
      summary: Get an Available Number
      description: >-
        Returns the details of a specific available phone number including
        its type, capabilities, and pricing.
      tags:
        - Available Numbers
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/PhoneNumber'
      responses:
        '200':
          description: Available number details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvailableNumber'
        '401':
          description: Unauthorized
        '404':
          description: Number not found
  /v1/projects/{project_id}/availableNumbers/{phone_number}:rent:
    post:
      operationId: rentNumber
      summary: Rent a Number
      description: >-
        Activates a phone number by renting it for use with Sinch services.
        The number will be assigned to your project and can be configured
        for SMS, Voice, or other services.
      tags:
        - Available Numbers
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/PhoneNumber'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RentNumberRequest'
      responses:
        '200':
          description: Number rented successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActiveNumber'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '404':
          description: Number not available
  /v1/projects/{project_id}/activeNumbers:
    get:
      operationId: listActiveNumbers
      summary: List Active Numbers
      description: >-
        Returns a list of all active phone numbers in the project with
        pagination support. Results can be filtered by country, type,
        and capabilities.
      tags:
        - Active Numbers
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: regionCode
          in: query
          required: true
          description: The ISO 3166-1 alpha-2 country code
          schema:
            type: string
        - name: type
          in: query
          required: true
          description: The number type
          schema:
            type: string
            enum:
              - LOCAL
              - MOBILE
              - TOLL_FREE
        - name: numberPattern.pattern
          in: query
          description: Pattern to search for
          schema:
            type: string
        - name: capabilities
          in: query
          description: Filter by capabilities
          schema:
            type: array
            items:
              type: string
              enum:
                - SMS
                - VOICE
        - name: pageSize
          in: query
          description: Number of results per page
          schema:
            type: integer
            default: 30
            maximum: 100
        - name: pageToken
          in: query
          description: Pagination token for the next page
          schema:
            type: string
      responses:
        '200':
          description: List of active numbers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActiveNumberList'
        '401':
          description: Unauthorized
  /v1/projects/{project_id}/activeNumbers/{phone_number}:
    get:
      operationId: getActiveNumber
      summary: Get an Active Number
      description: >-
        Returns the configuration and details of a specific active number.
      tags:
        - Active Numbers
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/PhoneNumber'
      responses:
        '200':
          description: Active number details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActiveNumber'
        '401':
          description: Unauthorized
        '404':
          description: Number not found
    patch:
      operationId: updateActiveNumber
      summary: Update an Active Number
      description: >-
        Updates the configuration of an active number including its display
        name, SMS and voice configurations, and callback URL.
      tags:
        - Active Numbers
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/PhoneNumber'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateActiveNumberRequest'
      responses:
        '200':
          description: Number updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActiveNumber'
        '401':
          description: Unauthorized
        '404':
          description: Number not found
  /v1/projects/{project_id}/activeNumbers/{phone_number}:release:
    post:
      operationId: releaseNumber
      summary: Release an Active Number
      description: >-
        Releases an active number, removing it from your project. The number
        will no longer be available for use with Sinch services.
      tags:
        - Active Numbers
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/PhoneNumber'
      responses:
        '200':
          description: Number released
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActiveNumber'
        '401':
          description: Unauthorized
        '404':
          description: Number not found
  /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
components:
  securitySchemes:
    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.
  parameters:
    ProjectId:
      name: project_id
      in: path
      required: true
      description: The unique project identifier
      schema:
        type: string
    PhoneNumber:
      name: phone_number
      in: path
      required: true
      description: The phone number in E.164 format
      schema:
        type: string
  schemas:
    AvailableNumber:
      type: object
      properties:
        phoneNumber:
          type: string
          description: The phone number in E.164 format
        regionCode:
          type: string
          description: The ISO 3166-1 alpha-2 country code
        type:
          type: string
          description: The number type
        capability:
          type: array
          description: The number capabilities
          items:
            type: string
        setupPrice:
          $ref: '#/components/schemas/Money'
        monthlyPrice:
          $ref: '#/components/schemas/Money'
        paymentIntervalMonths:
          type: integer
          description: The billing interval in months
    AvailableNumberList:
      type: object
      properties:
        availableNumbers:
          type: array
          description: List of available numbers
          items:
            $ref: '#/components/schemas/AvailableNumber'
    ActiveNumber:
      type: object
      properties:
        phoneNumber:
          type: string
          description: The phone number in E.164 format
        projectId:
          type: string
          description: The project ID
        displayName:
          type: string
          description: A display name for the number
        regionCode:
          type: string
          description: The ISO 3166-1 alpha-2 country code
        type:
          type: string
          description: The number type
        capability:
          type: array
          description: The number capabilities
          items:
            type: string
        money:
          $ref: '#/components/schemas/Money'
        paymentIntervalMonths:
          type: integer
          description: The billing interval in months
        nextChargeDate:
          type: string
          format: date-time
          description: The next billing date
        expireAt:
          type: string
          format: date-time
          description: When the number rental expires
        smsConfiguration:
          $ref: '#/components/schemas/SmsConfiguration'
        voiceConfiguration:
          $ref: '#/components/schemas/VoiceConfiguration'
        callbackUrl:
          type: string
          format: uri
          description: The callback URL for the number
    ActiveNumberList:
      type: object
      properties:
        activeNumbers:
          type: array
          description: List of active numbers
          items:
            $ref: '#/components/schemas/ActiveNumber'
        nextPageToken:
          type: string
          description: Pagination token for the next page
        totalSize:
          type: integer
          description: Total number of active numbers
    RentNumberRequest:
      type: object
      properties:
        smsConfiguration:
          $ref: '#/components/schemas/SmsConfiguration'
        voiceConfiguration:
          $ref: '#/components/schemas/VoiceConfiguration'
        callbackUrl:
          type: string
          format: uri
          description: Callback URL for the number
    UpdateActiveNumberRequest:
      type: object
      properties:
        displayName:
          type: string
          description: Updated display name
        smsConfiguration:
          $ref: '#/components/schemas/SmsConfiguration'
        voiceConfiguration:
          $ref: '#/components/schemas/VoiceConfiguration'
        callbackUrl:
          type: string
          format: uri
          description: Updated callback URL
    SmsConfiguration:
      type: object
      properties:
        servicePlanId:
          type: string
          description: The SMS service plan ID to associate
        campaignId:
          type: string
          description: The campaign ID for 10DLC
        scheduledProvisioning:
          type: object
          description: Scheduled provisioning details
          properties:
            servicePlanId:
              type: string
              description: Target service plan ID
            campaignId:
              type: string
              description: Target campaign ID
            status:
              type: string
              description: Provisioning status
    VoiceConfiguration:
      type: object
      properties:
        appId:
          type: string
          description: The Voice API app ID to associate
        scheduledVoiceProvisioning:
          type: object
          description: Scheduled voice provisioning details
          properties:
            appId:
              type: string
              description: Target app ID
            status:
              type: string
              description: Provisioning status
    Money:
      type: object
      properties:
        currencyCode:
          type: string
          description: The ISO 4217 currency code
        amount:
          type: string
          description: The monetary amount as a string
    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