SignalWire E911 Addresses API

openapi: 3.2.0
info:
  title: SignalWire REST E911 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: Manage E911 addresses for regulatory compliance and phone number provisioning.
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: E911 Addresses
  description: Manage E911 addresses for regulatory compliance and phone number provisioning.
  externalDocs:
    url: https://signalwire.com/docs/apis
    description: Developer documentation on SignalWire REST APIs
paths:
  /api/relay/rest/addresses:
    get:
      operationId: list_addresses
      summary: List E911 addresses
      description: 'Returns a list of your Addresses. The addresses are returned sorted by creation date, with the most recent appearing first.


        #### 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/ListAddressesQuery.filter_label'
      - $ref: '#/components/parameters/ListAddressesQuery.page_number'
      - $ref: '#/components/parameters/ListAddressesQuery.page_size'
      - $ref: '#/components/parameters/ListAddressesQuery.page_token'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressListResponse'
        '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:
      - E911 Addresses
    post:
      operationId: create_address
      summary: Create E911 address
      description: 'To create a new Address, make a POST request to the Address resource.


        When `emergency_enabled=true` and the address is in the US (`country` = `US`), the address is validated against the carrier. A valid or auto-corrected address is stored (`validated: true`). An address the carrier cannot validate — or a correctable address when `auto_correct_address=false` — is rejected with a `422` whose body includes an `errors` array and a `candidates` array of suggested addresses (each with `street_number`, `street_name`, `city`, `state`, `postal_code`). Carrier validation applies to US addresses only: a non-US address is stored normally, with `emergency_enabled` returned as `false`. Requests without `emergency_enabled` are stored without carrier validation.


        #### 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/AddressResponse'
        '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. When carrier validation rejected the address

            and the carrier returned alternatives, a `candidates` array is included alongside `errors`; the key is

            omitted when the carrier returned none.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressValidationError'
        '500':
          description: An internal server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode500'
      tags:
      - E911 Addresses
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAddressRequest'
  /api/relay/rest/addresses/{id}:
    get:
      operationId: get_address
      summary: Get E911 address
      description: 'Retrieves the details of an Address that has been previously created.

        Use the unique ID that was returned from your previous request to identify the specific instance.


        #### 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/AddressPathID'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressResponse'
        '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:
      - E911 Addresses
    put:
      operationId: update_address
      summary: Update E911 address
      description: 'Updates an Address that has been previously created.


        When `emergency_enabled=true` and the address is in the US (`country` = `US`), the address is validated against the carrier. A valid or auto-corrected address is stored (`validated: true`). An address the carrier cannot validate — or a correctable address when `auto_correct_address=false` — is rejected with a `422` whose body includes an `errors` array and a `candidates` array of suggested addresses (each with `street_number`, `street_name`, `city`, `state`, `postal_code`). Carrier validation applies to US addresses only: a non-US address is stored normally, with `emergency_enabled` returned as `false`. Requests without `emergency_enabled` are stored without carrier validation.


        #### 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/AddressPathID'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressResponse'
        '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. When carrier validation rejected the address

            and the carrier returned alternatives, a `candidates` array is included alongside `errors`; the key is

            omitted when the carrier returned none.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressValidationError'
        '500':
          description: An internal server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode500'
      tags:
      - E911 Addresses
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAddressRequest'
    delete:
      operationId: delete_address
      summary: Delete E911 address
      description: 'Permanently deletes an Address. It cannot be undone.


        #### 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/AddressPathID'
      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:
      - E911 Addresses
components:
  schemas:
    Types.StatusCodes.StatusCode401:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          enum:
          - Unauthorized
      unevaluatedProperties:
        not: {}
      description: Access is unauthorized.
    Types.StatusCodes.StatusCode400:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          enum:
          - Bad Request
      unevaluatedProperties:
        not: {}
      description: The request is invalid.
    AddressCandidate:
      type: object
      required:
      - street_number
      - street_name
      - city
      - state
      - postal_code
      properties:
        street_number:
          anyOf:
          - type: string
          - type: 'null'
          description: The number portion of the suggested street address.
          examples:
          - '1640'
        street_name:
          anyOf:
          - type: string
          - type: 'null'
          description: The name portion of the suggested street address.
          examples:
          - Riverside Drive
        city:
          anyOf:
          - type: string
          - type: 'null'
          description: The city portion of the suggested street address.
          examples:
          - Alexandria
        state:
          anyOf:
          - type: string
          - type: 'null'
          description: The state of the suggested street address.
          examples:
          - CA
        postal_code:
          anyOf:
          - type: string
          - type: 'null'
          description: The postal code of the suggested street address.
          examples:
          - '91905'
      unevaluatedProperties:
        not: {}
      description: A carrier-suggested alternative to the submitted address.
    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.StatusCode500:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          enum:
          - Internal Server Error
      unevaluatedProperties:
        not: {}
      description: An internal server error occurred.
    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.
    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.
    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.
    Address:
      type: object
      required:
      - id
      - label
      - country
      - first_name
      - last_name
      - street_number
      - street_name
      - address_type
      - address_number
      - city
      - state
      - postal_code
      - zip_code
      - emergency_enabled
      - validated
      - validated_at
      properties:
        id:
          allOf:
          - $ref: '#/components/schemas/uuid'
          description: The unique identifier of the Address on SignalWire.
          examples:
          - 3fa85f64-5717-4562-b3fc-2c963f66afa6
        label:
          type: string
          description: A friendly name given to the address to help distinguish and search for different addresses within your project.
          examples:
          - My Address
        country:
          type: string
          description: The ISO 3166 Alpha 2 country code.
          examples:
          - US
        first_name:
          type: string
          description: First name of the occupant associated with this address.
          examples:
          - Emmett
        last_name:
          type: string
          description: Last name of the occupant associated with this address.
          examples:
          - Brown
        street_number:
          type: string
          description: The number portion of the street address.
          examples:
          - '1640'
        street_name:
          type: string
          description: The name portion of the street address.
          examples:
          - Riverside Drive
        address_type:
          anyOf:
          - $ref: '#/components/schemas/AddressType'
          - type: 'null'
          description: If the address is divided into multiple sub-addresses, this identifies how the address is divided.
          examples:
          - Apartment
        address_number:
          anyOf:
          - type: string
          - type: 'null'
          description: If the address is divided into multiple sub-addresses, this identifies the particular sub-address.
          examples:
          - '42'
        city:
          type: string
          description: The city portion of the street address.
          examples:
          - Alexandria
        state:
          type: string
          description: The state/province/region of the street address. In the USA and Canada, use the two-letter abbreviated form.
          examples:
          - CA
        postal_code:
          type: string
          description: The postal code of the street address.
          examples:
          - '91905'
        zip_code:
          type: string
          description: The postal code of the street address. Alias for postal_code for backwards compatibility.
          examples:
          - '91905'
        emergency_enabled:
          type: boolean
          description: Whether E911 emergency calling is enabled for this address (carrier-validated when created/updated with `emergency_enabled=true` for a US address).
          examples:
          - false
        validated:
          type: boolean
          description: Whether the address was validated by the carrier (true when the carrier returned a valid or auto-corrected match).
          examples:
          - false
        validated_at:
          anyOf:
          - type: string
          - type: 'null'
          description: The RFC 3339 / ISO 8601 timestamp of the last successful carrier validation, or null if never validated.
          examples:
          - null
      unevaluatedProperties:
        not: {}
      description: Address model representing a physical address for regulatory compliance.
    AddressListResponse:
      type: object
      required:
      - links
      - data
      properties:
        links:
          allOf:
          - $ref: '#/components/schemas/PaginationLinks'
          description: Pagination links.
        data:
          type: array
          items:
            $ref: '#/components/schemas/Address'
          description: List of addresses.
      unevaluatedProperties:
        not: {}
      description: Response containing a list of addresses.
    AddressResponse:
      type: object
      required:
      - id
      - label
      - country
      - first_name
      - last_name
      - street_number
      - street_name
      - address_type
      - address_number
      - city
      - state
      - postal_code
      - zip_code
      - emergency_enabled
      - validated
      - validated_at
      properties:
        id:
          allOf:
          - $ref: '#/components/schemas/uuid'
          description: The unique identifier of the Address on SignalWire.
          examples:
          - 3fa85f64-5717-4562-b3fc-2c963f66afa6
        label:
          type: string
          description: A friendly name given to the address to help distinguish and search for different addresses within your project.
          examples:
          - My Address
        country:
          type: string
          description: The ISO 3166 Alpha 2 country code.
          examples:
          - US
        first_name:
          type: string
          description: First name of the occupant associated with this address.
          examples:
          - Emmett
        last_name:
          type: string
          description: Last name of the occupant associated with this address.
          examples:
          - Brown
        street_number:
          type: string
          description: The number portion of the street address.
          examples:
          - '1640'
        street_name:
          type: string
          description: The name portion of the street address.
          examples:
          - Riverside Drive
        address_type:
          anyOf:
          - $ref: '#/components/schemas/AddressType'
          - type: 'null'
          description: If the address is divided into multiple sub-addresses, this identifies how the address is divided.
          examples:
          - Apartment
        address_number:
          anyOf:
          - type: string
          - type: 'null'
          description: If the address is divided into multiple sub-addresses, this identifies the particular sub-address.
          examples:
          - '42'
        city:
          type: string
          description: The city portion of the street address.
          examples:
          - Alexandria
        state:
          type: string
          description: The state/province/region of the street address. In the USA and Canada, use the two-letter abbreviated form.
          examples:
          - CA
        postal_code:
          type: string
          description: The postal code of the street address.
          examples:
          - '91905'
        zip_code:
          type: string
          description: The postal code of the street address. Alias for postal_code for backwards compatibility.
          examples:
          - '91905'
        emergency_enabled:
          type: boolean
          description: Whether E911 emergency calling is enabled for this address (carrier-validated when created/updated with `emergency_enabled=true` for a US address).
          examples:
          - false
        validated:
          type: boolean
          description: Whether the address was validated by the carrier (true when the carrier returned a valid or auto-corrected match).
          examples:
          - false
        validated_at:
          anyOf:
          - type: string
          - type: 'null'
          description: The RFC 3339 / ISO 8601 timestamp of the last successful carrier validation, or null if never validated.
          examples:
          - null
      unevaluatedProperties:
        not: {}
      description: Response containing a single address.
    UpdateAddressRequest:
      type: object
      required:
      - label
      - country
      - first_name
      - last_name
      - street_number
      - street_name
      - city
      - state
      - postal_code
      properties:
        label:
          type: string
          maxLength: 250
          description: A friendly name given to the address to help distinguish and search for different addresses within your project. When the address is assigned to a phone number for E911, this label is also sent to the carrier as the caller name. The emergency network limits that field to 32 characters, so longer labels are truncated to the first 32 characters before being sent. Truncation affects only the name shown to the dispatcher, never the address used to route the call.
          examples:
          - My Address
        country:
          type: string
          description: The ISO 3166 Alpha 2 country code.
          examples:
          - US
        first_name:
          type: string
          maxLength: 250
          description: First name of the occupant associated with this address.
          examples:
          - Emmett
        last_name:
          type: string
          maxLength: 250
          description: Last name of the occupant associated with this address.
          examples:
          - Brown
        street_number:
          type: string
          maxLength: 250
          description: The number portion of the street address.
          examples:
          - '1640'
        street_name:
          type: string
          maxLength: 250
          description: The name portion of the street address.
          examples:
          - Riverside Drive
        address_type:
          allOf:
          - $ref: '#/components/schemas/AddressType'
          description: 'If the address is divided into multiple sub-addresses, this identifies how the address is divided. Possible values are: Apartment, Basement, Building, Department, Floor, Office, Penthouse, Suite, Trailer, Unit.'
          examples:
          - Apartment
        address_number:
          type: string
          description: If the address is divided into multiple sub-addresses, this identifies the particular sub-address.
          examples:
          - '42'
        city:
          type: string
          maxLength: 250
          description: The city portion of the street address.
          examples:
          - Alexandria
        state:
          type: string
          description: The state/province/region of the street address. In the USA and Canada, use the two-letter abbreviated form.
          examples:
          - CA
        postal_code:
          type: string
          maxLength: 250
          description: The postal code of the street address.
          examples:
          - '91905'
        emergency_enabled:
          type: boolean
          description: 'Applies to US addresses only. When `true` and `country` is `US`, the address is validated against

            the carrier before it is stored. For any other `country` the flag is ignored and the response

            returns `emergency_enabled: false`. Defaults to `false`, which stores the address without carrier

            validation.'
          examples:
          - true
          default: false
        auto_correct_address:
          type: boolean
          description: When the carrier suggests a corrected version of the address, `true` (the default) stores the corrected address; `false` rejects the request with the suggestion returned as candidates.
          examples:
          - true
          default: true
      unevaluatedProperties:
        not: {}
      description: Request body for updating an address.
    AddressValidationError:
      type: object
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Types.StatusCodes.SpaceApiErrorItem'
          description: List of validation errors.
        candidates:
          type: array
          items:
            $ref: '#/components/schemas/AddressCandidate'
          description: Alternative addresses suggested by the carrier. Omitted when the carrier returned no alternatives.
      unevaluatedProperties:
        not: {}
      description: 'The request failed validation. See `errors` for details. When carrier validation rejected the address

        and the carrier returned alternatives, a `candidates` array is included alongside `errors`; the key is

        omitted when the carrier returned none.'
    CreateAddressRequest:
      type: object
      required:
      - label
      - country
      - first_name
      - last_name
      - street_number
      - street_name
      - city
      - state
      - postal_code
      properties:
        label:
          type: string
          maxLength: 250
          description: A friendly name given to the address to help distinguish and search for different addresses within your project. When the address is assigned to a phone number for E911, this label is also sent to the carrier as the caller name. The emergency network limits that field to 32 characters, so longer labels are truncated to the first 32 characters before being sent. Truncation affects only the name shown to the dispatcher, never the address used to route the call.
          examples:
          - My Address
        country:
          type: string
          description: The ISO 3166 Alpha 2 country code.
          examples:
          - US
        first_name:
          type: string
          maxLength: 250
          description: First name of the occupant associated with this address.
          examples:
          - Emmett
        last_name:
          type: string
          maxLength: 250
          description: Last name of the occupant associated with this address.
          examples:
          - Brown
        street_number:
          type: string
          maxLength: 250
          description: The number portion of the street address.
          examples:
          - '1640'
        street_name:
          type: string
          maxLength: 250
          description: The name portion of the street address.
          examples:
          - Riverside Drive
        address_type:
          allOf:
          - $ref: '#/components/schemas/AddressType'
          description: 'If the address is divided into multiple sub-addresses, this identifies how the address is divided. Possible values are: Apartment, Basement, Building, Department, Floor, Office, Penthouse, Suite, Trailer, Unit.'
          examples:
          - Apartment
        address_number:
          type: string
          description: If the address is divided into multiple sub-addresses, this identifies the particular sub-address.
          examples:
          - '42'
        city:
          type: string
          maxLength: 250
          description: The city portion of the street address.
          examples:
          - Alexandria
        state:
          type: string
          description: The state/province/region of the street address. In the USA and Canada, use the two-letter abbreviated form.
          examples:
          - CA
        postal_code:
          type: string
          maxLength: 250
          description: The postal code of the street address.
          examples:
          - '91905'
        emergency_enabled:
          type: boolean
          description: 'Applies to US addresses only. When `true` and `country` is `US`, the address is validated against

            the carrier before it is stored. For any other `country` the flag is ignored and the response

            returns `emergency_enabled: false`. Defaults to `false`, which stores the address without carrier

            validation.'
          examples:
          - true
          default: false
        auto_correct_address:
          type: boolean
          description: When the carrier suggests a corrected version of the address, `true` (the default) stores the corrected address; `false` rejects the request with the suggestion returned as candidates.
          examples:
          - true
          default: true
      unevaluatedProperties:
        not: {}
      description: Request body for creating an address.
    AddressType:
      type: string
      enum:
      - Apartment
      - Basement
      - Building
      - Department
      - Floor
      - Office
      - Penthouse
      - Suite
      - Trailer
      - Unit
      description: Address type for sub-addresses.
  parameters:
    ListAddressesQuery.filter_label:
      name: filter_label
      in: query
      required: false
      description: Filter addresses by label (partial match).
      schema:
        type: string
      explode: false
    AddressPathID:
      name: id
      in: path
      required: true
      description: Unique ID of the address.
      schema:
        $ref: '#/components/schemas/uuid'
    ListAddressesQuery.page_size:
      name: page_size
      in: query
      required: false
      description: The number of items per page (1-1000).
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 1000
        default: 50
      explode: false
    ListAddressesQuery.page_token:
      name: page_token
      in: query
      required: false
      description: Token for cursor-based pagination. Required when page_number > 0.
      schema:
        type: string
      explode: false
    ListAddressesQuery.page_number:
      name: page_number
      in: query
      required

# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/signalwire/refs/heads/main/openapi/signalwire-e911-addresses-api-openapi.yml