Telnyx Addresses API

openapi: 3.1.0
info:
  contact:
    email: support@telnyx.com
  description: Telnyx provides global communications and connectivity APIs for developers — including SIP trunking, programmable voice, SMS, MMS, WhatsApp Business Messaging, Call Control, Fax, Wireless (IoT & eSIM), Phone Numbers (DID provisioning & porting), Emergency Services, and Network APIs for private interconnects and edge connectivity. Build, scale, and manage voice, messaging, and data networks with Telnyx's carrier-grade global infrastructure and API-first platform.
  title: Telnyx Access Tokens Addresses API
  version: 2.0.0
  x-endpoint-cost: light
servers:
- description: Version 2.0.0 of the Telnyx API
  url: https://api.telnyx.com/v2
security:
- bearerAuth: []
tags:
- description: Operations to work with Address records. Address records are emergency-validated addresses meant to be associated with phone numbers. They are validated for emergency usage purposes at creation time, although you may validate them separately with a custom workflow using the ValidateAddress operation separately. Address records are not usable for physical orders, such as for Telnyx SIM cards, please use UserAddress for that. It is not possible to entirely skip emergency service validation for Address records; if an emergency provider for a phone number rejects the address then it cannot be used on a phone number. To prevent records from getting out of sync, Address records are immutable and cannot be altered once created. If you realize you need to alter an address, a new record must be created with the differing address.
  name: Addresses
paths:
  /addresses:
    get:
      description: Returns a list of your addresses.
      operationId: FindAddresses
      parameters:
      - $ref: '#/components/parameters/PageConsolidated'
      - $ref: '#/components/parameters/FilterConsolidated'
      - $ref: '#/components/parameters/SortAddress'
      responses:
        '200':
          $ref: '#/components/responses/GetAllAddressResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Resource not found
      summary: List all addresses
      tags:
      - Addresses
      x-endpoint-cost: medium
      x-latency-category: responsive
    post:
      description: Creates an address.
      operationId: CreateAddress
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressCreate'
        description: Parameters that can be defined during address creation
        required: true
      responses:
        '200':
          $ref: '#/components/responses/AddressResponse'
        '422':
          description: Bad request
      summary: Creates an address
      tags:
      - Addresses
      x-endpoint-cost: medium
      x-latency-category: responsive
  /addresses/actions/validate:
    post:
      description: Validates an address for emergency services.
      operationId: ValidateAddress
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateAddressRequest'
        description: Parameters that can be defined during address validation
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ValidateAddressResponse'
        '422':
          description: Bad request
      summary: Validate an address
      tags:
      - Addresses
      x-latency-category: responsive
  /addresses/{id}:
    delete:
      description: Deletes an existing address.
      operationId: DeleteAddress
      parameters:
      - description: address ID
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/AddressResponse'
        '401':
          description: Unauthorized
        '404':
          description: Resource not found
        '422':
          description: Bad request
      summary: Deletes an address
      tags:
      - Addresses
      x-latency-category: responsive
    get:
      description: Retrieves the details of an existing address.
      operationId: GetAddress
      parameters:
      - description: address ID
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/AddressResponse'
        '401':
          description: Unauthorized
        '404':
          description: Resource not found
        '422':
          description: Bad request
      summary: Retrieve an address
      tags:
      - Addresses
      x-latency-category: responsive
  /addresses/{id}/actions/accept_suggestions:
    post:
      operationId: acceptAddressSuggestions
      parameters:
      - description: The UUID of the address that should be accepted.
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcceptSuggestionsRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressSuggestionResponse'
          description: This address suggestion has already been accepted.
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressSuggestionResponse'
          description: This address suggestion was accepted. The numbers associated to it will resume processing in the background.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundError'
          description: Address not found or not accessible by the user.
      summary: Accepts this address suggestion as a new emergency address for Operator Connect and finishes the uploads of the numbers associated with it to Microsoft.
      tags:
      - Addresses
      x-latency-category: responsive
components:
  schemas:
    postal_code:
      description: The postal code of the address.
      example: '78701'
      type: string
    neighborhood:
      description: The neighborhood of the address. This field is not used for addresses in the US but is used for some international addresses.
      example: Ciudad de los deportes
      type: string
    ValidateAddressField:
      properties:
        administrative_area:
          $ref: '#/components/schemas/administrative_area'
        country_code:
          $ref: '#/components/schemas/country_code'
        extended_address:
          $ref: '#/components/schemas/extended_address'
        locality:
          $ref: '#/components/schemas/locality'
        postal_code:
          $ref: '#/components/schemas/postal_code'
        street_address:
          $ref: '#/components/schemas/street_address'
      type: object
    ValidateAddressResult:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/Error'
          type: array
        record_type:
          description: Identifies the type of the resource.
          example: address_validation
          type: string
        result:
          description: Indicates whether an address is valid or invalid.
          enum:
          - valid
          - invalid
          example: valid
          type: string
        suggested:
          $ref: '#/components/schemas/ValidateAddressField'
          additionalProperties: true
          description: Provides normalized address when available.
          type: object
      required:
      - result
      - suggested
      title: Validate address action result
      type: object
    locality:
      description: The locality of the address. For US addresses, this corresponds to the city of the address.
      example: Austin
      type: string
    Error:
      example:
        code: '20207'
        description: The street address provided is invalid.
        source:
          pointer: /street_address
        title: Invalid street address
      properties:
        code:
          type: string
          x-format: int64
        description:
          type: string
        meta:
          additionalProperties: true
          type: object
        source:
          properties:
            parameter:
              description: Indicates which query parameter caused the error.
              type: string
            pointer:
              description: JSON pointer (RFC6901) to the offending entity.
              format: json-pointer
              type: string
          type: object
        title:
          type: string
      required:
      - code
      - title
      type: object
    administrative_area:
      description: The locality of the address. For US addresses, this corresponds to the state of the address.
      example: TX
      type: string
    customer_reference:
      description: A customer reference string for customer look ups.
      example: MY REF 001
      type: string
    first_name:
      description: The first name associated with the address. An address must have either a first last name or a business name.
      example: Alfred
      type: string
    AddressCreate:
      properties:
        address_book:
          $ref: '#/components/schemas/address_book'
        administrative_area:
          $ref: '#/components/schemas/administrative_area'
        borough:
          $ref: '#/components/schemas/borough'
        business_name:
          $ref: '#/components/schemas/business_name'
        country_code:
          $ref: '#/components/schemas/country_code'
        customer_reference:
          $ref: '#/components/schemas/customer_reference'
        extended_address:
          $ref: '#/components/schemas/extended_address'
        first_name:
          $ref: '#/components/schemas/first_name'
        last_name:
          $ref: '#/components/schemas/last_name'
        locality:
          $ref: '#/components/schemas/locality'
        neighborhood:
          $ref: '#/components/schemas/neighborhood'
        phone_number:
          $ref: '#/components/schemas/phone_number'
        postal_code:
          $ref: '#/components/schemas/postal_code'
        street_address:
          $ref: '#/components/schemas/street_address'
        validate_address:
          $ref: '#/components/schemas/validate_address'
      required:
      - first_name
      - last_name
      - business_name
      - street_address
      - locality
      - country_code
      type: object
    ValidateAddressRequest:
      properties:
        administrative_area:
          $ref: '#/components/schemas/administrative_area'
        country_code:
          $ref: '#/components/schemas/country_code'
        extended_address:
          $ref: '#/components/schemas/extended_address'
        locality:
          $ref: '#/components/schemas/locality'
        postal_code:
          $ref: '#/components/schemas/postal_code'
        street_address:
          $ref: '#/components/schemas/street_address'
      required:
      - country_code
      - street_address
      - postal_code
      type: object
    AcceptSuggestionsRequest:
      properties:
        id:
          description: The ID of the address.
          type: string
      type: object
    street_address:
      description: The primary street address information about the address.
      example: 600 Congress Avenue
      type: string
    ResourceNotFoundError:
      properties:
        errors:
          items:
            properties:
              code:
                description: Error code identifying the error type.
                type: string
              detail:
                description: A human-readable explanation of the error.
                type: string
              meta:
                properties:
                  url:
                    description: A URL to the detailed documentation for the error.
                    format: uri
                    type: string
                type: object
              title:
                description: A short, human-readable summary of the problem.
                type: string
            type: object
          type: array
      type: object
    Address:
      properties:
        address_book:
          $ref: '#/components/schemas/address_book'
        administrative_area:
          $ref: '#/components/schemas/administrative_area'
        borough:
          $ref: '#/components/schemas/borough'
        business_name:
          $ref: '#/components/schemas/business_name'
        country_code:
          $ref: '#/components/schemas/country_code'
        created_at:
          description: ISO 8601 formatted date indicating when the resource was created.
          example: '2018-02-02T22:25:27.521Z'
          type: string
        customer_reference:
          $ref: '#/components/schemas/customer_reference'
        extended_address:
          $ref: '#/components/schemas/extended_address'
        first_name:
          $ref: '#/components/schemas/first_name'
        id:
          description: Uniquely identifies the address.
          example: '1293384261075731499'
          type: string
          x-format: int64
        last_name:
          $ref: '#/components/schemas/last_name'
        locality:
          $ref: '#/components/schemas/locality'
        neighborhood:
          $ref: '#/components/schemas/neighborhood'
        phone_number:
          $ref: '#/components/schemas/phone_number'
        postal_code:
          $ref: '#/components/schemas/postal_code'
        record_type:
          description: Identifies the type of the resource.
          example: address
          type: string
        street_address:
          $ref: '#/components/schemas/street_address'
        updated_at:
          description: ISO 8601 formatted date indicating when the resource was updated.
          example: '2018-02-02T22:25:27.521Z'
          type: string
        validate_address:
          $ref: '#/components/schemas/validate_address'
      title: Address
      type: object
    AddressSuggestionResponse:
      properties:
        data:
          properties:
            accepted:
              description: Indicates if the address suggestions are accepted.
              type: boolean
            id:
              description: The UUID of the location.
              format: uuid
              type: string
            record_type:
              enum:
              - address_suggestion
              type: string
          type: object
      type: object
    address_book:
      default: true
      description: Indicates whether or not the address should be considered part of your list of addresses that appear for regular use.
      example: false
      type: boolean
    last_name:
      description: The last name associated with the address. An address must have either a first last name or a business name.
      example: Foster
      type: string
    phone_number:
      description: The phone number associated with the address.
      example: '+12125559000'
      type: string
    country_code:
      description: The two-character (ISO 3166-1 alpha-2) country code of the address.
      example: US
      type: string
    extended_address:
      description: Additional street address information about the address such as, but not limited to, unit number or apartment number.
      example: 14th Floor
      type: string
    PaginationMeta:
      properties:
        page_number:
          example: 2
          type: integer
        page_size:
          example: 25
          type: integer
        total_pages:
          example: 3
          type: integer
        total_results:
          example: 55
          type: integer
      type: object
    business_name:
      description: The business name associated with the address. An address must have either a first last name or a business name.
      example: Toy-O'Kon
      type: string
    validate_address:
      default: true
      description: Indicates whether or not the address should be validated for emergency use upon creation or not. This should be left with the default value of `true` unless you have used the `/addresses/actions/validate` endpoint to validate the address separately prior to creation. If an address is not validated for emergency use upon creation and it is not valid, it will not be able to be used for emergency services.
      example: true
      type: boolean
    borough:
      description: The borough of the address. This field is not used for addresses in the US but is used for some international addresses.
      example: Guadalajara
      type: string
  responses:
    GetAllAddressResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                items:
                  $ref: '#/components/schemas/Address'
                type: array
              meta:
                $ref: '#/components/schemas/PaginationMeta'
            type: object
      description: Successful response
    ValidateAddressResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                $ref: '#/components/schemas/ValidateAddressResult'
            title: Validate address action response
            type: object
      description: Action response
    AddressResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                $ref: '#/components/schemas/Address'
            type: object
      description: Successful response
  parameters:
    PageConsolidated:
      description: 'Consolidated page parameter (deepObject style). Originally: page[number], page[size]'
      explode: true
      in: query
      name: page
      schema:
        properties:
          number:
            default: 1
            description: The page number to load
            minimum: 1
            type: integer
          size:
            default: 20
            description: The size of the page
            maximum: 250
            minimum: 1
            type: integer
        type: object
      style: deepObject
    SortAddress:
      description: "Specifies the sort order for results. By default sorting direction is ascending. To have the results sorted in descending order add the <code> -</code> prefix.<br/><br/>\nThat is: <ul>\n  <li>\n    <code>street_address</code>: sorts the result by the\n    <code>street_address</code> field in ascending order.\n  </li>\n\n  <li>\n    <code>-street_address</code>: sorts the result by the\n    <code>street_address</code> field in descending order.\n  </li>\n</ul> <br/> If not given, results are sorted by <code>created_at</code> in descending order."
      in: query
      name: sort
      required: false
      schema:
        default: created_at
        enum:
        - created_at
        - first_name
        - last_name
        - business_name
        - street_address
        example: street_address
        type: string
    FilterConsolidated:
      description: 'Consolidated filter parameter (deepObject style). Originally: filter[customer_reference][eq], filter[customer_reference][contains], filter[used_as_emergency], filter[street_address][contains], filter[address_book][eq]'
      explode: true
      in: query
      name: filter
      schema:
        properties:
          address_book:
            properties:
              eq:
                description: If present, only returns results with the <code>address_book</code> flag equal to the given value.
                type: string
            type: object
          customer_reference:
            oneOf:
            - description: If present, addresses with <code>customer_reference</code> containing the given value will be returned. Matching is not case-sensitive.
              type: string
            - properties:
                contains:
                  description: Partial match for customer_reference. Matching is not case-sensitive.
                  type: string
                eq:
                  description: Exact match for customer_reference.
                  type: string
              type: object
          street_address:
            properties:
              contains:
                description: If present, addresses with <code>street_address</code> containing the given value will be returned. Matching is not case-sensitive. Requires at least three characters.
                type: string
            type: object
          used_as_emergency:
            description: 'If set as ''true'', only addresses used as the emergency address for at least one active phone-number will be returned. When set to ''false'', the opposite happens: only addresses not used as the emergency address from phone-numbers will be returned.'
            type: string
        type: object
      style: deepObject
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http
    branded-calling_bearerAuth:
      description: API key passed as a Bearer token in the Authorization header
      scheme: bearer
      type: http
    oauthClientAuth:
      description: OAuth 2.0 authentication for Telnyx API and MCP integrations
      flows:
        authorizationCode:
          authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
          refreshUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
          tokenUrl: https://api.telnyx.com/v2/oauth/token
        clientCredentials:
          scopes:
            admin: Administrative access to Telnyx resources
          tokenUrl: https://api.telnyx.com/v2/oauth/token
      type: oauth2
    outbound-voice-profiles_bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http
    pronunciation-dicts_bearerAuth:
      description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
      scheme: bearer
      type: http
    stored-payment-transactions_bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http