SignalWire SIP Addresses API

openapi: 3.2.0
info:
  title: SignalWire REST SIP Addresses API
  version: 1.0.0
  contact:
    name: SignalWire
    url: https://support.signalwire.com/portal/en/newticket?departmentId=1029313000000006907&layoutId=1029313000000074011
    email: support@signalwire.com
  license:
    name: MIT
    url: https://github.com/signalwire/docs/blob/main/LICENSE
  termsOfService: https://signalwire.com/legal/signalwire-cloud-agreement
  description: Endpoints related to creating & managing SIP Addresses — the SIP configuration (username, Domain, codecs, ciphers, encryption, IP authentication, registration password) for the resource that handles calls to it.
servers:
- url: https://{space_name}.signalwire.com
  description: SignalWire API
  variables:
    space_name:
      default: '{Your_Space_Name}'
      description: Your SignalWire Space name
security:
- SignalWireBasicAuth: []
tags:
- name: SIP Addresses
  description: Endpoints related to creating & managing SIP Addresses — the SIP configuration (username, Domain, codecs, ciphers, encryption, IP authentication, registration password) for the resource that handles calls to it.
  externalDocs:
    url: https://signalwire.com/docs/apis
    description: Developer documentation on SIP Addresses, Fabric API endpoints
paths:
  /api/fabric/sip_addresses:
    get:
      operationId: list_sip_addresses
      summary: List SIP addresses
      description: 'Returns a paginated list of SIP addresses in the authenticated project.


        #### Permissions


        The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Calling_, _Fax_, _Messaging_, or _Video_.


        Learn more about API scopes.'
      parameters:
      - $ref: '#/components/parameters/SipAddressListQuery.page_size'
      - $ref: '#/components/parameters/SipAddressListQuery.page_number'
      - $ref: '#/components/parameters/SipAddressListQuery.page_token'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SipAddressListResponse'
        '401':
          description: Access is unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode401'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode404'
        '422':
          description: The request contains invalid parameters. See errors for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SipAddressListStatusCode422'
        '500':
          description: An internal server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode500'
      tags:
      - SIP Addresses
    post:
      operationId: create_sip_address
      summary: Create SIP address
      description: 'Creates a SIP address, along with its username, encryption, codec, cipher, and IP authentication settings.


        #### Permissions


        The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Calling_, _Fax_, _Messaging_, or _Video_.


        Learn more about API scopes.'
      parameters: []
      responses:
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SipAddress'
        '401':
          description: Access is unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode401'
        '422':
          description: The request contains invalid parameters. See errors for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SipAddressCreateStatusCode422'
        '500':
          description: An internal server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode500'
      tags:
      - SIP Addresses
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SipAddressCreateRequest'
  /api/fabric/sip_addresses/{id}:
    get:
      operationId: get_sip_address
      summary: Get SIP address
      description: 'Returns a SIP address by ID.


        #### Permissions


        The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Calling_, _Fax_, _Messaging_, or _Video_.


        Learn more about API scopes.'
      parameters:
      - $ref: '#/components/parameters/SipAddressPathID'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SipAddress'
        '401':
          description: Access is unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode401'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode404'
        '500':
          description: An internal server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode500'
      tags:
      - SIP Addresses
    patch:
      operationId: update_sip_address
      summary: Update SIP address
      description: 'Updates a SIP address by ID. Partial update: any field omitted from the body keeps its current value.

        `calling_handler_resource_id` cannot be changed via this endpoint.


        #### Permissions


        The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Calling_, _Fax_, _Messaging_, or _Video_.


        Learn more about API scopes.'
      parameters:
      - $ref: '#/components/parameters/SipAddressPathID'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SipAddress'
        '400':
          description: The request is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode400'
        '401':
          description: Access is unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode401'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode404'
        '422':
          description: The request contains invalid parameters. See errors for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SipAddressUpdateStatusCode422'
        '500':
          description: An internal server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode500'
      tags:
      - SIP Addresses
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SipAddressUpdateRequest'
    delete:
      operationId: delete_sip_address
      summary: Delete SIP address
      description: 'Deletes a SIP address by ID, along with its SIP configuration. Calls and registrations to this

        address will stop working immediately.


        #### Permissions


        The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Calling_, _Fax_, _Messaging_, or _Video_.


        Learn more about API scopes.'
      parameters:
      - $ref: '#/components/parameters/SipAddressPathID'
      responses:
        '204':
          description: 'There is no content to send for this request, but the headers may be useful. '
        '401':
          description: Access is unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode401'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode404'
        '500':
          description: An internal server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode500'
      tags:
      - SIP Addresses
components:
  schemas:
    SipAddressCreateStatusCode422:
      type: object
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Types.StatusCodes.RestApiErrorItem'
          description: List of validation errors.
      unevaluatedProperties:
        not: {}
      description: The request contains invalid parameters. See errors for details.
      examples:
      - statusCode: 422
        errors:
        - type: validation_error
          code: missing_required_parameter
          message: Name is required
          attribute: name
          url: https://signalwire.com/docs/apis/error-codes#missing_required_parameter
    Types.StatusCodes.StatusCode401:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          enum:
          - Unauthorized
      unevaluatedProperties:
        not: {}
      description: Access is unauthorized.
    Ciphers:
      type: string
      enum:
      - AEAD_AES_256_GCM_8
      - AES_256_CM_HMAC_SHA1_80
      - AES_CM_128_HMAC_SHA1_80
      - AES_256_CM_HMAC_SHA1_32
      - AES_CM_128_HMAC_SHA1_32
    Types.StatusCodes.RestApiErrorItem:
      type: object
      required:
      - type
      - code
      - message
      - url
      properties:
        type:
          type: string
          description: The category of error.
          examples:
          - validation_error
        code:
          type: string
          description: A specific error code.
          examples:
          - invalid_parameter
        message:
          type: string
          description: A description of what caused the error.
          examples:
          - Name must be present
        attribute:
          anyOf:
          - type: string
          - type: 'null'
          description: The request parameter that caused the error, if applicable.
          examples:
          - name
        url:
          type: string
          description: A link to documentation about this error.
          examples:
          - https://signalwire.com/docs/apis/error-codes
      unevaluatedProperties:
        not: {}
      description: Details about a specific error.
    Types.StatusCodes.StatusCode400:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          enum:
          - Bad Request
      unevaluatedProperties:
        not: {}
      description: The request is invalid.
    SipAddressUpdateStatusCode422:
      type: object
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Types.StatusCodes.RestApiErrorItem'
          description: List of validation errors.
      unevaluatedProperties:
        not: {}
      description: The request contains invalid parameters. See errors for details.
      examples:
      - statusCode: 422
        errors:
        - type: validation_error
          code: invalid_parameter
          message: 'Encryption must be one of: required, optional, forbidden'
          attribute: encryption
          url: https://signalwire.com/docs/apis/error-codes#invalid_parameter
    Types.StatusCodes.StatusCode404:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          enum:
          - Not Found
      unevaluatedProperties:
        not: {}
      description: The server cannot find the requested resource.
    SipAddressListResponse:
      type: object
      required:
      - links
      - items_count
      - data
      properties:
        links:
          allOf:
          - $ref: '#/components/schemas/SipAddressPaginationResponse'
          description: Pagination links for the response.
        items_count:
          type: integer
          format: int32
          description: The number of SIP addresses in this page of results.
          examples:
          - 1
        data:
          type: array
          items:
            $ref: '#/components/schemas/SipAddress'
          description: An array of SIP address objects.
      unevaluatedProperties:
        not: {}
    SipAddressCodec:
      type: string
      enum:
      - OPUS
      - G722
      - PCMU
      - PCMA
      - G729
      - VP8
      - H264
    SipAddressPaginationResponse:
      type: object
      required:
      - self
      - first
      properties:
        self:
          type: string
          format: uri
          description: Link to the current page of results.
          examples:
          - https://example.signalwire.com/api/fabric/sip_addresses?page_number=0&page_size=50
        first:
          type: string
          format: uri
          description: Link to the first page of results.
          examples:
          - https://example.signalwire.com/api/fabric/sip_addresses?page_number=0&page_size=50
        next:
          type: string
          format: uri
          description: Link to the next page of results.
          examples:
          - https://example.signalwire.com/api/fabric/sip_addresses?page_number=1&page_size=50&page_token=PAbff61159-faab-48b3-959a-3021a8f5beca
        prev:
          type: string
          format: uri
          description: Link to the previous page of results.
          examples:
          - https://example.signalwire.com/api/fabric/sip_addresses?page_number=0&page_size=50&page_token=PAbff61159-faab-48b3-959a-3021a8f5beca
      unevaluatedProperties:
        not: {}
    SipAddressCreateRequest:
      type: object
      required:
      - name
      - calling_handler_resource_id
      properties:
        name:
          type: string
          maxLength: 50
          pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
          description: URL-safe name for the SIP address — lowercase letters, numbers, and hyphens only (no spaces or other special characters). Must be unique within the project and is used to build the address's SIP URI.
          examples:
          - sales-line
        user:
          type: string
          pattern: ^\S+$
          description: SIP username used to reach this address (no spaces). Defaults to `*`, which accepts any username. Together with the address's Domain, must be unique across your SignalWire account.
          examples:
          - agent
          default: '*'
        context_id:
          allOf:
          - $ref: '#/components/schemas/uuid'
          description: ID of the Domain this address should be grouped under. Must exist in your project. Defaults to your project's default Domain.
          examples:
          - 9c8b7a6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d
        calling_handler_resource_id:
          allOf:
          - $ref: '#/components/schemas/uuid'
          description: ID of the resource that handles inbound calls to this address. Must reference a resource in the caller's project.
          examples:
          - 1f2e3d4c-5b6a-7980-a1b2-c3d4e5f60718
        ip_auth_enabled:
          type: boolean
          description: Whether to enforce IP authentication for this address.
          examples:
          - true
          default: false
        ip_auth:
          type: array
          items:
            type: string
          maxItems: 256
          description: Whitelisted IP/CIDR entries. Required (at least one) when `ip_auth_enabled` is `true`. Maximum 256 entries.
          examples:
          - - 10.0.0.0/24
          default: []
        codecs:
          type: array
          items:
            $ref: '#/components/schemas/SipAddressCodec'
          minItems: 1
          description: Non-empty subset of enabled codecs.
          examples:
          - - OPUS
          default:
          - PCMU
          - PCMA
        ciphers:
          type: array
          items:
            $ref: '#/components/schemas/Ciphers'
          minItems: 1
          description: Non-empty subset of enabled SRTP ciphers.
          examples:
          - - AES_256_CM_HMAC_SHA1_80
          default:
          - AEAD_AES_256_GCM_8
          - AES_256_CM_HMAC_SHA1_80
          - AES_CM_128_HMAC_SHA1_80
          - AES_256_CM_HMAC_SHA1_32
          - AES_CM_128_HMAC_SHA1_32
        encryption:
          allOf:
          - $ref: '#/components/schemas/SipAddressEncryption'
          description: SRTP encryption requirement for calls to this address.
          examples:
          - required
          default: optional
        password:
          type: string
          description: Write-only SIP registration password. Never returned in any response.
          examples:
          - sup3r-s3cret
      unevaluatedProperties:
        not: {}
    SipAddressEncryption:
      type: string
      enum:
      - required
      - optional
      - forbidden
    SipAddressListStatusCode422:
      type: object
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Types.StatusCodes.RestApiErrorItem'
          description: List of validation errors.
      unevaluatedProperties:
        not: {}
      description: The request contains invalid parameters. See errors for details.
      examples:
      - statusCode: 422
        errors:
        - type: validation_error
          code: page_token_is_invalid
          message: Page token is invalid
          attribute: null
          url: https://signalwire.com/docs/apis/error-codes#page_token_is_invalid
    SipAddressUpdateRequest:
      type: object
      properties:
        name:
          type: string
          maxLength: 50
          pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
          description: URL-safe name for the SIP address — lowercase letters, numbers, and hyphens only (no spaces or other special characters). Must be unique within the project. Defaults to the current value when omitted.
          examples:
          - renamed-line
        user:
          type: string
          pattern: ^\S+$
          description: SIP username used to reach this address (no spaces). Together with the address's Domain, must be unique across your SignalWire account.
          examples:
          - agent
        context_id:
          allOf:
          - $ref: '#/components/schemas/uuid'
          description: ID of the Domain this address should be grouped under. Must exist in your project. Defaults to the address's current Domain when omitted.
          examples:
          - 9c8b7a6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d
        ip_auth_enabled:
          type: boolean
          description: Whether to enforce IP authentication for this address.
          examples:
          - true
        ip_auth:
          type: array
          items:
            type: string
          maxItems: 256
          description: Whitelisted IP/CIDR entries. Required (at least one) when `ip_auth_enabled` is `true`. Maximum 256 entries.
          examples:
          - - 10.0.0.0/24
        codecs:
          type: array
          items:
            $ref: '#/components/schemas/SipAddressCodec'
          minItems: 1
          description: Non-empty subset of enabled codecs.
          examples:
          - - OPUS
        ciphers:
          type: array
          items:
            $ref: '#/components/schemas/Ciphers'
          minItems: 1
          description: Non-empty subset of enabled SRTP ciphers.
          examples:
          - - AES_256_CM_HMAC_SHA1_80
        encryption:
          allOf:
          - $ref: '#/components/schemas/SipAddressEncryption'
          description: SRTP encryption requirement for calls to this address.
          examples:
          - required
        password:
          type: string
          description: Write-only SIP registration password. Never returned in any response.
          examples:
          - sup3r-s3cret
      unevaluatedProperties:
        not: {}
    Types.StatusCodes.StatusCode500:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          enum:
          - Internal Server Error
      unevaluatedProperties:
        not: {}
      description: An internal server error occurred.
    SipAddress:
      type: object
      required:
      - id
      - type
      - resource_id
      - name
      - display_name
      - context
      - uri
      - user
      - encryption
      - codecs
      - ciphers
      - ip_auth_enabled
      - ip_auth
      - calling_handler_resource_id
      - created_at
      - updated_at
      properties:
        id:
          allOf:
          - $ref: '#/components/schemas/uuid'
          description: Unique identifier for the SIP address.
          examples:
          - b3f1c0a2-0f6e-4a9d-9b2a-1c2d3e4f5a6b
        type:
          type: string
          enum:
          - sip_address
          description: The object type. Always `sip_address`.
          examples:
          - sip_address
        resource_id:
          allOf:
          - $ref: '#/components/schemas/uuid'
          description: ID of the resource this address belongs to.
          examples:
          - 8a7b6c5d-4e3f-2a1b-0c9d-8e7f6a5b4c3d
        name:
          type: string
          description: URL-safe name for the SIP address. Used to build its SIP URI.
          examples:
          - support-line
        display_name:
          type: string
          description: Human-friendly label for the SIP address. Defaults to `name`.
          examples:
          - support-line
        context:
          type: string
          description: The Domain this address is grouped under — for example, `public` for your project's default Domain.
          examples:
          - public
        uri:
          type: string
          description: Full SIP URI for this address.
          examples:
          - sip:my-space-support-line@sip.signalwire.com
        user:
          type: string
          description: SIP username used to reach this address. `*` accepts any username.
          examples:
          - '*'
        encryption:
          allOf:
          - $ref: '#/components/schemas/SipAddressEncryption'
          description: SRTP encryption requirement for calls to this address.
          examples:
          - optional
        codecs:
          type: array
          items:
            $ref: '#/components/schemas/SipAddressCodec'
          description: Enabled codecs for calls to this address.
          examples:
          - - PCMU
            - PCMA
        ciphers:
          type: array
          items:
            $ref: '#/components/schemas/Ciphers'
          description: Enabled SRTP ciphers for calls to this address.
          examples:
          - - AEAD_AES_256_GCM_8
            - AES_256_CM_HMAC_SHA1_80
            - AES_CM_128_HMAC_SHA1_80
            - AES_256_CM_HMAC_SHA1_32
            - AES_CM_128_HMAC_SHA1_32
        ip_auth_enabled:
          type: boolean
          description: Whether IP authentication is enforced for this address.
          examples:
          - false
        ip_auth:
          type: array
          items:
            type: string
          description: Whitelisted IP/CIDR entries used when `ip_auth_enabled` is `true`.
          examples:
          - []
        calling_handler_resource_id:
          allOf:
          - $ref: '#/components/schemas/uuid'
          description: ID of the resource that handles inbound calls to this address.
          examples:
          - 1f2e3d4c-5b6a-7980-a1b2-c3d4e5f60718
        created_at:
          type: string
          format: date-time
          description: Date and time when the SIP address was created.
          examples:
          - '2024-05-06T12:20:00Z'
        updated_at:
          type: string
          format: date-time
          description: Date and time when the SIP address was last updated.
          examples:
          - '2024-05-06T12:20:00Z'
      unevaluatedProperties:
        not: {}
    uuid:
      type: string
      format: uuid
      description: Universal Unique Identifier.
  parameters:
    SipAddressListQuery.page_number:
      name: page_number
      in: query
      required: false
      description: The page index, used together with `page_token`.
      schema:
        type: integer
        format: int32
        minimum: 0
        default: 0
      explode: false
    SipAddressListQuery.page_size:
      name: page_size
      in: query
      required: false
      description: The number of results per page.
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 1000
        default: 50
      explode: false
    SipAddressListQuery.page_token:
      name: page_token
      in: query
      required: false
      description: Opaque cursor token from a previous response's `links.next` or `links.prev`. Begins with `PA` or `PB`.
      schema:
        type: string
      explode: false
    SipAddressPathID:
      name: id
      in: path
      required: true
      description: Unique ID of a SIP Address.
      schema:
        $ref: '#/components/schemas/uuid'
  securitySchemes:
    SignalWireBasicAuth:
      type: http
      scheme: Basic
      description: 'SignalWire Basic Authentication using Project ID and API Token.


        The client sends HTTP requests with the Authorization header containing

        the word Basic followed by a space and a base64-encoded string of project_id:token.

        The project ID will be used as the username and the API token as the password.


        Example:

        ```

        Authorization: Basic base64(project_id:token)

        ```'
      x-fern-basic:
        username:
          name: project_id
          env: SIGNALWIRE_PROJECT_ID
        password:
          name: api_token
          env: SIGNALWIRE_API_TOKEN
    SignalWireBearerAuth:
      type: http
      scheme: Bearer
      description: 'SignalWire Bearer Token Authentication for subscriber endpoints.

        The client sends HTTP requests with the Authorization header containing

        the word Bearer followed by a space and the subscriber token.


        Example:

        ```

        Authorization: Bearer <subscriber_token>

        ```'