SignalWire Verified Caller ID API

openapi: 3.2.0
info:
  title: SignalWire REST Verified Caller ID 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 verified caller IDs for phone numbers not purchased through SignalWire.
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: Verified Caller ID
  description: Manage verified caller IDs for phone numbers not purchased through SignalWire.
  externalDocs:
    url: https://signalwire.com/docs/apis
    description: Developer documentation on SignalWire REST APIs
paths:
  /api/relay/rest/verified_caller_ids:
    get:
      operationId: list_verified_caller_ids
      summary: List verified caller IDs
      description: 'Returns a list of your Verified Caller IDs. The caller IDs are returned sorted by creation date, with the most recent caller IDs 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: _Voice_.


        [Learn more about API scopes](/docs/platform/your-signalwire-api-space).'
      parameters:
      - name: filter_name
        in: query
        required: false
        description: String representing the name assigned to the caller ID. Will return all Verified Caller IDs containing this value as a substring.
        schema:
          type: string
        explode: false
      - name: filter_number
        in: query
        required: false
        description: String representing the number assigned to the caller ID. Will return all Verified Caller IDs containing this value as a substring.
        schema:
          type: string
        explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifiedCallerIDListResponse'
        '401':
          description: Access is unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode401'
        '500':
          description: An internal server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode500'
      tags:
      - Verified Caller ID
    post:
      operationId: create_verified_caller_id
      summary: Create verified caller ID
      description: 'Creates a new verified caller ID. A verification code will be sent to the phone number.


        #### Permissions


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


        [Learn more about API scopes](/docs/platform/your-signalwire-api-space).'
      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/VerifiedCallerIDResponse'
        '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:
      - Verified Caller ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVerifiedCallerIDRequest'
  /api/relay/rest/verified_caller_ids/{id}:
    get:
      operationId: retrieve_verified_caller_id
      summary: Get verified caller ID
      description: 'Retrieves the details of a verified caller ID.


        #### Permissions


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


        [Learn more about API scopes](/docs/platform/your-signalwire-api-space).'
      parameters:
      - $ref: '#/components/parameters/VerifiedCallerIDPathID'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifiedCallerIDResponse'
        '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:
      - Verified Caller ID
    put:
      operationId: update_verified_caller_id
      summary: Update verified caller ID
      description: 'Updates a verified caller ID.


        #### Permissions


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


        [Learn more about API scopes](/docs/platform/your-signalwire-api-space).'
      parameters:
      - $ref: '#/components/parameters/VerifiedCallerIDPathID'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifiedCallerIDResponse'
        '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:
      - Verified Caller ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateVerifiedCallerIDRequest'
    delete:
      operationId: delete_verified_caller_id
      summary: Delete verified caller ID
      description: 'Deletes a verified caller ID.


        #### Permissions


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


        [Learn more about API scopes](/docs/platform/your-signalwire-api-space).'
      parameters:
      - $ref: '#/components/parameters/VerifiedCallerIDPathID'
      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:
      - Verified Caller ID
  /api/relay/rest/verified_caller_ids/{id}/verification:
    post:
      operationId: redial_verification_call
      summary: Redial verification call
      description: 'Redials the verification call for a verified caller ID.


        #### Permissions


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


        [Learn more about API scopes](/docs/platform/your-signalwire-api-space).'
      parameters:
      - $ref: '#/components/parameters/VerifiedCallerIDPathID'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifiedCallerIDResponse'
        '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:
      - Verified Caller ID
    put:
      operationId: validate_verification_code
      summary: Validate verification code
      description: 'Validates the verification code for a verified caller ID.


        #### Permissions


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


        [Learn more about API scopes](/docs/platform/your-signalwire-api-space).'
      parameters:
      - $ref: '#/components/parameters/VerifiedCallerIDPathID'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifiedCallerIDResponse'
        '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:
      - Verified Caller ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyCallerIDRequest'
components:
  schemas:
    VerifyCallerIDRequest:
      type: object
      required:
      - verification_code
      properties:
        verification_code:
          type: string
          description: The verification code received via call or SMS.
          examples:
          - '123456'
      unevaluatedProperties:
        not: {}
      description: Request body for verifying a caller ID.
    Types.StatusCodes.StatusCode401:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          enum:
          - Unauthorized
      unevaluatedProperties:
        not: {}
      description: Access is unauthorized.
    VerifiedCallerID:
      type: object
      required:
      - id
      - number
      - verified
      properties:
        type:
          type: string
          description: The type of the returned object, this should be verified_caller_id.
          examples:
          - verified_caller_id
        id:
          allOf:
          - $ref: '#/components/schemas/uuid'
          description: The unique identifier of the Verified Caller ID on SignalWire.
          examples:
          - 3fa85f64-5717-4562-b3fc-2c963f66afa6
        number:
          type: string
          description: String representing the phone number for the caller ID. This must be a valid, routeable phone number in E.164 format.
          examples:
          - '+15551234567'
        name:
          type: string
          description: String representing the name portion of the caller ID. If not provided, the default will be the formatted number that has been provided.
          examples:
          - C-3P0
        extension:
          type: string
          description: String representing the extension of the phone number for the caller ID. This is only used when placing the verification call.
          examples:
          - '1234'
        verified:
          type: boolean
          description: A boolean representing whether the number has been verified or not.
          examples:
          - false
        verified_at:
          type: string
          format: date-time
          description: Nullable DateTime field representing the date and time that the number was verified. If the number has not been verified, it will be null.
        status:
          type: string
          enum:
          - Verified
          - Awaiting Verification
          description: The verification status for the caller ID.
          examples:
          - Awaiting Verification
      unevaluatedProperties:
        not: {}
      description: Verified caller ID model.
    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.
    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.
    UpdateVerifiedCallerIDRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          maxLength: 200
          description: The name portion of the caller ID.
          examples:
          - C-3P0
      unevaluatedProperties:
        not: {}
      description: Request body for updating a verified caller ID.
    VerifiedCallerIDResponse:
      type: object
      required:
      - id
      - number
      - verified
      properties:
        type:
          type: string
          description: The type of the returned object, this should be verified_caller_id.
          examples:
          - verified_caller_id
        id:
          allOf:
          - $ref: '#/components/schemas/uuid'
          description: The unique identifier of the Verified Caller ID on SignalWire.
          examples:
          - 3fa85f64-5717-4562-b3fc-2c963f66afa6
        number:
          type: string
          description: String representing the phone number for the caller ID. This must be a valid, routeable phone number in E.164 format.
          examples:
          - '+15551234567'
        name:
          type: string
          description: String representing the name portion of the caller ID. If not provided, the default will be the formatted number that has been provided.
          examples:
          - C-3P0
        extension:
          type: string
          description: String representing the extension of the phone number for the caller ID. This is only used when placing the verification call.
          examples:
          - '1234'
        verified:
          type: boolean
          description: A boolean representing whether the number has been verified or not.
          examples:
          - false
        verified_at:
          type: string
          format: date-time
          description: Nullable DateTime field representing the date and time that the number was verified. If the number has not been verified, it will be null.
        status:
          type: string
          enum:
          - Verified
          - Awaiting Verification
          description: The verification status for the caller ID.
          examples:
          - Awaiting Verification
      unevaluatedProperties:
        not: {}
      description: Response containing a single verified caller ID.
    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.
    CreateVerifiedCallerIDRequest:
      type: object
      required:
      - number
      properties:
        number:
          type: string
          description: String representing the phone number for the caller ID. This must be a valid, routeable phone number in [E.164 format](https://en.wikipedia.org/wiki/E.164) that is able to receive a voice phone call for verification.
          examples:
          - '+15551234567'
        name:
          type: string
          maxLength: 200
          description: The name portion of the caller ID. If not provided, the default will be the formatted number.
          examples:
          - C-3P0
        extension:
          type: string
          description: The extension of the phone number for the caller ID. This is only used when placing the verification call.
          examples:
          - '1234'
      unevaluatedProperties:
        not: {}
      description: Request body for creating a verified caller ID.
    Types.StatusCodes.StatusCode500:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          enum:
          - Internal Server Error
      unevaluatedProperties:
        not: {}
      description: An internal server error occurred.
    VerifiedCallerIDListResponse:
      type: object
      properties:
        links:
          allOf:
          - $ref: '#/components/schemas/PaginationLinks'
          description: Pagination links.
        data:
          type: array
          items:
            $ref: '#/components/schemas/VerifiedCallerID'
          description: List of verified caller IDs.
      unevaluatedProperties:
        not: {}
      description: Response containing a list of verified caller IDs.
    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.
  parameters:
    VerifiedCallerIDPathID:
      name: id
      in: path
      required: true
      description: Unique ID of the verified caller ID.
      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>

        ```'