SignalWire Number Groups API

openapi: 3.2.0
info:
  title: SignalWire REST Number Groups 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: Manage number groups for organizing phone numbers.
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: Number Groups
  description: Manage number groups for organizing phone numbers.
  externalDocs:
    url: https://signalwire.com/docs/apis
    description: Developer documentation on SignalWire REST APIs
paths:
  /api/relay/rest/number_groups:
    get:
      operationId: list_number_groups
      summary: List number groups
      description: 'Returns a list of your Number Groups. The groups are returned sorted

        by creation date, with the most recent appearing first. The list is

        filterable by sending in any of the following parameters.


        #### Permissions


        The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Numbers_.


        [Learn more about API scopes](/docs/platform/your-signalwire-api-space).'
      parameters:
      - $ref: '#/components/parameters/ListNumberGroupsQuery.filter_name'
      - $ref: '#/components/parameters/ListNumberGroupsQuery.page_number'
      - $ref: '#/components/parameters/ListNumberGroupsQuery.page_size'
      - $ref: '#/components/parameters/ListNumberGroupsQuery.page_token'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberGroupListResponse'
        '401':
          description: Access is unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode401'
        '422':
          description: The request failed validation. See errors for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.ValidationError'
        '500':
          description: An internal server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode500'
      tags:
      - Number Groups
    post:
      operationId: create_number_group
      summary: Create number group
      description: 'Creates a new number group.


        #### Permissions


        The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Numbers_.


        [Learn more about API scopes](/docs/platform/your-signalwire-api-space).'
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberGroupResponse'
        '401':
          description: Access is unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode401'
        '422':
          description: The request failed validation. See errors for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.ValidationError'
        '500':
          description: An internal server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode500'
      tags:
      - Number Groups
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateNumberGroupRequest'
  /api/relay/rest/number_groups/{id}:
    get:
      operationId: retrieve_number_group
      summary: Get number group
      description: 'Retrieves the details of a number group.


        #### Permissions


        The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Numbers_.


        [Learn more about API scopes](/docs/platform/your-signalwire-api-space).'
      parameters:
      - $ref: '#/components/parameters/NumberGroupPathID'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberGroupResponse'
        '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 failed validation. See errors for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.ValidationError'
        '500':
          description: An internal server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode500'
      tags:
      - Number Groups
    put:
      operationId: update_number_group
      summary: Update number group
      description: 'Updates a number group.


        #### Permissions


        The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Numbers_.


        [Learn more about API scopes](/docs/platform/your-signalwire-api-space).'
      parameters:
      - $ref: '#/components/parameters/NumberGroupPathID'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberGroupResponse'
        '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 failed validation. See errors for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.ValidationError'
        '500':
          description: An internal server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode500'
      tags:
      - Number Groups
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNumberGroupRequest'
    delete:
      operationId: delete_number_group
      summary: Delete number group
      description: 'Deletes a number group.


        #### Permissions


        The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Numbers_.


        [Learn more about API scopes](/docs/platform/your-signalwire-api-space).'
      parameters:
      - $ref: '#/components/parameters/NumberGroupPathID'
      responses:
        '204':
          description: 'There is no content to send for this request, but the headers may be useful. '
        '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'
        '500':
          description: An internal server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode500'
      tags:
      - Number Groups
components:
  parameters:
    ListNumberGroupsQuery.page_number:
      name: page_number
      in: query
      required: false
      description: The page number to retrieve.
      schema:
        type: integer
        format: int32
        default: 0
      explode: false
    ListNumberGroupsQuery.filter_name:
      name: filter_name
      in: query
      required: false
      description: Filter by name. Returns all number groups containing this value as a substring.
      schema:
        type: string
        maxLength: 255
      explode: false
    ListNumberGroupsQuery.page_token:
      name: page_token
      in: query
      required: false
      description: Token for cursor-based pagination.
      schema:
        type: string
      explode: false
    NumberGroupPathID:
      name: id
      in: path
      required: true
      description: Unique ID of the number group.
      schema:
        $ref: '#/components/schemas/uuid'
    ListNumberGroupsQuery.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
  schemas:
    Types.StatusCodes.StatusCode401:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          enum:
          - Unauthorized
      unevaluatedProperties:
        not: {}
      description: Access is unauthorized.
    uuid:
      type: string
      format: uuid
      description: Universal Unique Identifier.
    Types.StatusCodes.StatusCode404:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          enum:
          - Not Found
      unevaluatedProperties:
        not: {}
      description: The server cannot find the requested resource.
    NumberGroupListResponse:
      type: object
      required:
      - links
      - data
      properties:
        links:
          allOf:
          - $ref: '#/components/schemas/PaginationLinks'
          description: Pagination links.
        data:
          type: array
          items:
            $ref: '#/components/schemas/NumberGroup'
          description: List of number groups.
      unevaluatedProperties:
        not: {}
      description: Response containing a list of number groups.
    Types.StatusCodes.ValidationError:
      type: object
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Types.StatusCodes.SpaceApiErrorItem'
          description: List of validation errors.
      unevaluatedProperties:
        not: {}
      description: The request failed validation. See errors for details.
    CreateNumberGroupRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: The name given to the number group. Helps to distinguish different groups within your project.
          examples:
          - My Number Group
        sticky_sender:
          type: boolean
          description: Whether the number group uses the same 'From' number for outbound requests to a number, or chooses a random one.
          examples:
          - false
          default: false
      unevaluatedProperties:
        not: {}
      description: Request body for creating a number group.
    UpdateNumberGroupRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: The name given to the number group. Helps to distinguish different groups within your project.
          examples:
          - My Number Group
        sticky_sender:
          type: boolean
          description: Whether the number group uses the same 'From' number for outbound requests to a number, or chooses a random one.
          examples:
          - false
      unevaluatedProperties:
        not: {}
      description: Request body for updating a number group.
    Types.StatusCodes.SpaceApiErrorItem:
      type: object
      required:
      - detail
      - status
      - title
      - code
      properties:
        detail:
          type: string
          description: A description of what caused the error.
          examples:
          - Label can't be blank
        status:
          type: string
          description: The HTTP status code.
          examples:
          - '422'
        title:
          type: string
          description: A short summary of the error type.
          examples:
          - Invalid Attribute
        code:
          type: string
          description: The error code.
          examples:
          - '422'
      unevaluatedProperties:
        not: {}
      description: Details about a specific validation error.
    Types.StatusCodes.StatusCode500:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          enum:
          - Internal Server Error
      unevaluatedProperties:
        not: {}
      description: An internal server error occurred.
    NumberGroupResponse:
      type: object
      required:
      - id
      - name
      - sticky_sender
      - phone_number_count
      properties:
        id:
          allOf:
          - $ref: '#/components/schemas/uuid'
          description: The unique identifier of the Number Group on SignalWire. This can be used to update or delete the group programmatically.
          examples:
          - 3fa85f64-5717-4562-b3fc-2c963f66afa6
        name:
          type: string
          description: The name given to the number group. Helps to distinguish different groups within your project.
          examples:
          - My Number Group
        sticky_sender:
          type: boolean
          description: Whether the number group uses the same 'From' number for outbound requests to a number, or chooses a random one.
          examples:
          - false
        phone_number_count:
          type: integer
          format: int32
          description: The number of phone numbers within the group.
          examples:
          - 4
      unevaluatedProperties:
        not: {}
      description: Response containing a single number group.
    NumberGroup:
      type: object
      required:
      - id
      - name
      - sticky_sender
      - phone_number_count
      properties:
        id:
          allOf:
          - $ref: '#/components/schemas/uuid'
          description: The unique identifier of the Number Group on SignalWire. This can be used to update or delete the group programmatically.
          examples:
          - 3fa85f64-5717-4562-b3fc-2c963f66afa6
        name:
          type: string
          description: The name given to the number group. Helps to distinguish different groups within your project.
          examples:
          - My Number Group
        sticky_sender:
          type: boolean
          description: Whether the number group uses the same 'From' number for outbound requests to a number, or chooses a random one.
          examples:
          - false
        phone_number_count:
          type: integer
          format: int32
          description: The number of phone numbers within the group.
          examples:
          - 4
      unevaluatedProperties:
        not: {}
      description: Number group model.
    Types.StatusCodes.StatusCode400:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          enum:
          - Bad Request
      unevaluatedProperties:
        not: {}
      description: The request is invalid.
    PaginationLinks:
      type: object
      required:
      - self
      - first
      properties:
        self:
          type: string
          description: Link to the current page.
        first:
          type: string
          description: Link to the first page.
        next:
          type: string
          description: Link to the next page. Only present when there are more results.
        prev:
          type: string
          description: Link to the previous page. Only present when not on the first page.
      unevaluatedProperties:
        not: {}
      description: Pagination links for list responses.
  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>

        ```'