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.
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