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 UserAddresses 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 for working with UserAddress records. UserAddress records are stored addresses that users can use for non-emergency-calling purposes, such as for shipping addresses for orders of wireless SIMs (or other physical items). They cannot be used for emergency calling and are distinct from Address records, which are used on phone numbers.
  name: UserAddresses
paths:
  /user_addresses:
    get:
      description: Returns a list of your user addresses.
      operationId: FindUserAddress
      parameters:
      - $ref: '#/components/parameters/user-addresses_PageConsolidated'
      - $ref: '#/components/parameters/user-addresses_FilterConsolidated'
      - $ref: '#/components/parameters/SortUserAddress'
      responses:
        '200':
          $ref: '#/components/responses/GetAllUserAddressResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Resource not found
      summary: List all user addresses
      tags:
      - UserAddresses
      x-endpoint-cost: medium
      x-latency-category: responsive
    post:
      description: Creates a user address.
      operationId: CreateUserAddress
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserAddressCreate'
        description: Parameters that can be defined during user address creation
        required: true
      responses:
        '200':
          $ref: '#/components/responses/UserAddressResponse'
        '422':
          description: Bad request
      summary: Creates a user address
      tags:
      - UserAddresses
      x-endpoint-cost: medium
      x-latency-category: responsive
  /user_addresses/{id}:
    get:
      description: Retrieves the details of an existing user address.
      operationId: GetUserAddress
      parameters:
      - description: user address ID
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/UserAddressResponse'
        '401':
          description: Unauthorized
        '404':
          description: Resource not found
        '422':
          description: Bad request
      summary: Retrieve a user address
      tags:
      - UserAddresses
      x-latency-category: responsive
components:
  parameters:
    SortUserAddress:
      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
    user-addresses_FilterConsolidated:
      description: 'Consolidated filter parameter (deepObject style). Originally: filter[customer_reference][eq], filter[customer_reference][contains], filter[street_address][contains]'
      examples:
        combined_filters:
          description: Use multiple filters together
          summary: Combined filters
          value:
            customer_reference:
              contains: REF
            street_address:
              contains: Avenue
        customer_reference_contains:
          description: Find user addresses containing part of customer reference
          summary: Filter by partial customer reference
          value:
            customer_reference:
              contains: REF
        customer_reference_eq:
          description: Find user addresses with exact customer reference match
          summary: Filter by exact customer reference
          value:
            customer_reference:
              eq: MY REF 001
        street_address_contains:
          description: Find user addresses containing part of street address
          summary: Filter by street address
          value:
            street_address:
              contains: Congress
      explode: true
      in: query
      name: filter
      schema:
        properties:
          customer_reference:
            description: Filter user addresses via the customer reference. Supports both exact matching (eq) and partial matching (contains). Matching is not case-sensitive.
            properties:
              contains:
                description: If present, user addresses with <code>customer_reference</code> containing the given value will be returned. Matching is not case-sensitive.
                type: string
              eq:
                description: Filter user addresses via exact customer reference match. Matching is not case-sensitive.
                type: string
            type: object
          street_address:
            description: Filter user addresses via street address. Supports partial matching (contains). Matching is not case-sensitive.
            properties:
              contains:
                description: If present, user 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
        type: object
      style: deepObject
    user-addresses_PageConsolidated:
      description: 'Consolidated page parameter (deepObject style). Originally: page[size], page[number]'
      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
  schemas:
    user-addresses_borough:
      description: The borough of the user address. This field is not used for addresses in the US but is used for some international addresses.
      example: Guadalajara
      type: string
    skip_address_verification:
      default: false
      description: An optional boolean value specifying if verification of the address should be skipped or not. UserAddresses are generally used for shipping addresses, and failure to validate your shipping address will likely result in a failure to deliver SIM cards or other items ordered from Telnyx. Do not use this parameter unless you are sure that the address is correct even though it cannot be validated. If this is set to any value other than true, verification of the address will be attempted, and the user address will not be allowed if verification fails. If verification fails but suggested values are available that might make the address correct, they will be present in the response as well. If this value is set to true, then the verification will not be attempted. Defaults to false (verification will be performed).
      type: boolean
    user-addresses_phone_number:
      description: The phone number associated with the user address.
      example: '+12125559000'
      type: string
    user-addresses_first_name:
      description: The first name associated with the user address.
      example: Alfred
      type: string
    customer_reference:
      description: A customer reference string for customer look ups.
      example: MY REF 001
      type: string
    user-addresses_postal_code:
      description: The postal code of the user address.
      example: '78701'
      type: string
    UserAddressCreate:
      properties:
        administrative_area:
          $ref: '#/components/schemas/user-addresses_administrative_area'
        borough:
          $ref: '#/components/schemas/user-addresses_borough'
        business_name:
          $ref: '#/components/schemas/user-addresses_business_name'
        country_code:
          $ref: '#/components/schemas/user-addresses_country_code'
        customer_reference:
          $ref: '#/components/schemas/customer_reference'
        extended_address:
          $ref: '#/components/schemas/user-addresses_extended_address'
        first_name:
          $ref: '#/components/schemas/user-addresses_first_name'
        last_name:
          $ref: '#/components/schemas/user-addresses_last_name'
        locality:
          $ref: '#/components/schemas/user-addresses_locality'
        neighborhood:
          $ref: '#/components/schemas/user-addresses_neighborhood'
        phone_number:
          $ref: '#/components/schemas/user-addresses_phone_number'
        postal_code:
          $ref: '#/components/schemas/user-addresses_postal_code'
        skip_address_verification:
          $ref: '#/components/schemas/skip_address_verification'
        street_address:
          $ref: '#/components/schemas/user-addresses_street_address'
      required:
      - first_name
      - last_name
      - business_name
      - street_address
      - locality
      - country_code
      type: object
    user-addresses_street_address:
      description: The primary street address information about the user address.
      example: 600 Congress Avenue
      type: string
    UserAddress:
      properties:
        administrative_area:
          $ref: '#/components/schemas/user-addresses_administrative_area'
        borough:
          $ref: '#/components/schemas/user-addresses_borough'
        business_name:
          $ref: '#/components/schemas/user-addresses_business_name'
        country_code:
          $ref: '#/components/schemas/user-addresses_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/user-addresses_extended_address'
        first_name:
          $ref: '#/components/schemas/user-addresses_first_name'
        id:
          description: Uniquely identifies the user address.
          example: c3527e69-dc5a-4b3e-8f44-99d209f83c1d
          format: uuid
          type: string
        last_name:
          $ref: '#/components/schemas/user-addresses_last_name'
        locality:
          $ref: '#/components/schemas/user-addresses_locality'
        neighborhood:
          $ref: '#/components/schemas/user-addresses_neighborhood'
        phone_number:
          $ref: '#/components/schemas/user-addresses_phone_number'
        postal_code:
          $ref: '#/components/schemas/user-addresses_postal_code'
        record_type:
          description: Identifies the type of the resource.
          example: user_address
          type: string
        street_address:
          $ref: '#/components/schemas/user-addresses_street_address'
        updated_at:
          description: ISO 8601 formatted date indicating when the resource was updated.
          example: '2018-02-02T22:25:27.521Z'
          type: string
      title: UserAddress
      type: object
    user-addresses_country_code:
      description: The two-character (ISO 3166-1 alpha-2) country code of the user address.
      example: US
      type: string
    user-addresses_business_name:
      description: The business name associated with the user address.
      example: Toy-O'Kon
      type: string
    user-addresses_neighborhood:
      description: The neighborhood of the user 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
    user-addresses_administrative_area:
      description: The locality of the user address. For US addresses, this corresponds to the state of the address.
      example: TX
      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
    user-addresses_last_name:
      description: The last name associated with the user address.
      example: Foster
      type: string
    user-addresses_locality:
      description: The locality of the user address. For US addresses, this corresponds to the city of the address.
      example: Austin
      type: string
    user-addresses_extended_address:
      description: Additional street address information about the user address such as, but not limited to, unit number or apartment number.
      example: 14th Floor
      type: string
  responses:
    UserAddressResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                $ref: '#/components/schemas/UserAddress'
            type: object
      description: Successful response
    GetAllUserAddressResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                items:
                  $ref: '#/components/schemas/UserAddress'
                type: array
              meta:
                $ref: '#/components/schemas/PaginationMeta'
            type: object
      description: Successful response
  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