Telnyx Addresses API

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.

GitHub OpenAPI

Operations 6

GET /addresses List all addresses #
POST /addresses Creates an address #
POST /addresses/actions/validate Validate an address #
DELETE /addresses/{id} Deletes an address #
GET /addresses/{id} Retrieve an address #
POST /addresses/{id}/actions/accept_suggestions Accepts this address suggestion as a new emergency address for Operator Connect… #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/telnyx:telnyx-addresses-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

telnyx-addresses-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Telnyx Addresses API
  version: 2.0.0
  contact:
    email: support@telnyx.com
  x-endpoint-cost: light
  x-refined-note:
  - x-latency-category differs across the merged source definitions and was not carried
  description: 'Operations tagged Addresses across 3 of this provider''s published API definitions: telnyx-openapi.json, telnyx-openapi.yml, telnyx-openapi_2.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.telnyx.com/v2
  description: Version 2.0.0 of the Telnyx API
security:
- bearerAuth: []
tags:
- name: Addresses
  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.
paths:
  /addresses:
    get:
      description: Returns a paginated list of the addresses on your account, with support for filtering and sorting.
      summary: List all addresses
      operationId: FindAddresses
      tags:
      - Addresses
      x-endpoint-cost: medium
      parameters:
      - $ref: '#/components/parameters/PageConsolidated'
      - $ref: '#/components/parameters/FilterConsolidated'
      - $ref: '#/components/parameters/SortAddress'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Address'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Resource not found
    post:
      description: Creates a new address on your account from the provided details, for use with services that require a physical address such as emergency calling and regulatory compliance.
      summary: Creates an address
      operationId: CreateAddress
      tags:
      - Addresses
      x-endpoint-cost: medium
      parameters: []
      requestBody:
        description: Parameters that can be defined during address creation
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressCreate'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Address'
        '422':
          description: Bad request
    servers:
    - url: https://api.telnyx.com/v2
      description: Version 2.0.0 of the Telnyx API
  /addresses/actions/validate:
    post:
      description: Validates an address for emergency services.
      summary: Validate an address
      operationId: ValidateAddress
      tags:
      - Addresses
      parameters: []
      requestBody:
        description: Parameters that can be defined during address validation
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateAddressRequest'
      responses:
        '200':
          description: Action response
          content:
            application/json:
              schema:
                type: object
                title: Validate address action response
                properties:
                  data:
                    $ref: '#/components/schemas/ValidateAddressResult'
        '422':
          description: Bad request
    servers:
    - url: https://api.telnyx.com/v2
      description: Version 2.0.0 of the Telnyx API
  /addresses/{id}:
    delete:
      description: Permanently deletes the specified address from your account.
      summary: Deletes an address
      operationId: DeleteAddress
      tags:
      - Addresses
      parameters:
      - name: id
        in: path
        description: address ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Address'
        '401':
          description: Unauthorized
        '404':
          description: Resource not found
        '422':
          description: Bad request
    get:
      description: Retrieves the details of an existing address.
      summary: Retrieve an address
      operationId: GetAddress
      tags:
      - Addresses
      parameters:
      - name: id
        in: path
        description: address ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Address'
        '401':
          description: Unauthorized
        '404':
          description: Resource not found
        '422':
          description: Bad request
    servers:
    - url: https://api.telnyx.com/v2
      description: Version 2.0.0 of the Telnyx API
  /addresses/{id}/actions/accept_suggestions:
    post:
      summary: Accepts this address suggestion as a new emergency address for Operator Connect…
      operationId: acceptAddressSuggestions
      tags:
      - Addresses
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
        description: The UUID of the address that should be accepted.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcceptSuggestionsRequest'
            example:
              id: string
      responses:
        '200':
          description: This address suggestion has already been accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressSuggestionResponse'
              example:
                data:
                  accepted: false
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  record_type: address_suggestion
        '202':
          description: This address suggestion was accepted. The numbers associated to it will resume processing in the background.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressSuggestionResponse'
        '404':
          description: Address not found or not accessible by the user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundError'
              example:
                errors:
                - code: '10005'
                  title: Resource not found
                  detail: The requested resource or URL could not be found.
      description: Accept the validated address suggestion for this address, replacing the original values, and finish uploading the numbers associated with it to Microsoft for Operator Connect.
    servers:
    - url: https://api.telnyx.com/v2
      description: Version 2.0.0 of the Telnyx API
components:
  schemas:
    AddressCreate:
      type: object
      required:
      - first_name
      - last_name
      - business_name
      - street_address
      - locality
      - country_code
      properties:
        customer_reference:
          $ref: '#/components/schemas/customer_reference'
        first_name:
          $ref: '#/components/schemas/first_name'
        last_name:
          $ref: '#/components/schemas/last_name'
        business_name:
          $ref: '#/components/schemas/business_name'
        phone_number:
          $ref: '#/components/schemas/phone_number'
        street_address:
          $ref: '#/components/schemas/street_address'
        extended_address:
          $ref: '#/components/schemas/extended_address'
        locality:
          $ref: '#/components/schemas/locality'
        administrative_area:
          $ref: '#/components/schemas/administrative_area'
        neighborhood:
          $ref: '#/components/schemas/neighborhood'
        borough:
          $ref: '#/components/schemas/borough'
        postal_code:
          $ref: '#/components/schemas/postal_code'
        country_code:
          $ref: '#/components/schemas/country_code'
        address_book:
          $ref: '#/components/schemas/address_book'
        validate_address:
          $ref: '#/components/schemas/validate_address'
    postal_code:
      type: string
      description: The postal code of the address.
      example: '78701'
    last_name:
      type: string
      description: The last name associated with the address. An address must have either a first last name or a business name.
      example: Foster
    neighborhood:
      type: string
      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
    locality:
      type: string
      description: The locality of the address. For US addresses, this corresponds to the city of the address.
      example: Austin
    ResourceNotFoundError:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                description: Error code identifying the error type.
              detail:
                type: string
                description: A human-readable explanation of the error.
              meta:
                type: object
                properties:
                  url:
                    type: string
                    format: uri
                    description: A URL to the detailed documentation for the error.
              title:
                type: string
                description: A short, human-readable summary of the problem.
    customer_reference:
      type: string
      description: A customer reference string for customer look ups.
      example: MY REF 001
    first_name:
      type: string
      description: The first name associated with the address. An address must have either a first last name or a business name.
      example: Alfred
    extended_address:
      type: string
      description: Additional street address information about the address such as, but not limited to, unit number or apartment number.
      example: 14th Floor
    ValidateAddressField:
      type: object
      properties:
        street_address:
          $ref: '#/components/schemas/street_address'
        extended_address:
          $ref: '#/components/schemas/extended_address'
        locality:
          $ref: '#/components/schemas/locality'
        administrative_area:
          $ref: '#/components/schemas/administrative_area'
        postal_code:
          $ref: '#/components/schemas/postal_code'
        country_code:
          $ref: '#/components/schemas/country_code'
    address_book:
      type: boolean
      description: Indicates whether or not the address should be considered part of your list of addresses that appear for regular use.
      example: false
      default: true
    AcceptSuggestionsRequest:
      type: object
      properties:
        id:
          type: string
          description: The ID of the address.
    business_name:
      type: string
      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
    phone_number:
      type: string
      description: The phone number associated with the address.
      example: '+12125559000'
    borough:
      type: string
      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
    AddressSuggestionResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            accepted:
              type: boolean
              description: Indicates if the address suggestions are accepted.
            id:
              type: string
              format: uuid
              description: The UUID of the location.
            record_type:
              type: string
              enum:
              - address_suggestion
    ValidateAddressRequest:
      type: object
      required:
      - country_code
      - street_address
      - postal_code
      properties:
        street_address:
          $ref: '#/components/schemas/street_address'
        extended_address:
          $ref: '#/components/schemas/extended_address'
        locality:
          $ref: '#/components/schemas/locality'
        administrative_area:
          $ref: '#/components/schemas/administrative_area'
        postal_code:
          $ref: '#/components/schemas/postal_code'
        country_code:
          $ref: '#/components/schemas/country_code'
    Address:
      type: object
      title: Address
      properties:
        id:
          type: string
          description: Uniquely identifies the address.
          example: '1293384261075731499'
          x-format: int64
        record_type:
          type: string
          description: Identifies the type of the resource.
          example: address
        customer_reference:
          $ref: '#/components/schemas/customer_reference'
        first_name:
          $ref: '#/components/schemas/first_name'
        last_name:
          $ref: '#/components/schemas/last_name'
        business_name:
          $ref: '#/components/schemas/business_name'
        phone_number:
          $ref: '#/components/schemas/phone_number'
        street_address:
          $ref: '#/components/schemas/street_address'
        extended_address:
          $ref: '#/components/schemas/extended_address'
        locality:
          $ref: '#/components/schemas/locality'
        administrative_area:
          $ref: '#/components/schemas/administrative_area'
        neighborhood:
          $ref: '#/components/schemas/neighborhood'
        borough:
          $ref: '#/components/schemas/borough'
        postal_code:
          $ref: '#/components/schemas/postal_code'
        country_code:
          $ref: '#/components/schemas/country_code'
        address_book:
          $ref: '#/components/schemas/address_book'
        validate_address:
          $ref: '#/components/schemas/validate_address'
        created_at:
          type: string
          description: ISO 8601 formatted date indicating when the resource was created.
          example: '2018-02-02T22:25:27.521Z'
        updated_at:
          type: string
          description: ISO 8601 formatted date indicating when the resource was updated.
          example: '2018-02-02T22:25:27.521Z'
    Error:
      required:
      - code
      - title
      properties:
        code:
          type: string
          x-format: int64
        title:
          type: string
        description:
          type: string
        source:
          type: object
          properties:
            pointer:
              description: JSON pointer (RFC6901) to the offending entity.
              type: string
              format: json-pointer
            parameter:
              description: Indicates which query parameter caused the error.
              type: string
        meta:
          type: object
          additionalProperties: true
      example:
        title: Invalid street address
        source:
          pointer: /street_address
        code: '20207'
        description: The street address provided is invalid.
      type: object
    validate_address:
      type: boolean
      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
      default: true
    country_code:
      type: string
      description: The two-character (ISO 3166-1 alpha-2) country code of the address.
      example: US
    street_address:
      type: string
      description: The primary street address information about the address.
      example: 600 Congress Avenue
    ValidateAddressResult:
      type: object
      title: Validate address action result
      properties:
        result:
          type: string
          description: Indicates whether an address is valid or invalid.
          enum:
          - valid
          - invalid
          example: valid
        suggested:
          type: object
          description: Provides normalized address when available.
          $ref: '#/components/schemas/ValidateAddressField'
          additionalProperties: true
        record_type:
          type: string
          description: Identifies the type of the resource.
          example: address_validation
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
      required:
      - result
      - suggested
    administrative_area:
      type: string
      description: The locality of the address. For US addresses, this corresponds to the state of the address.
      example: TX
    PaginationMeta:
      type: object
      properties:
        total_pages:
          type: integer
          example: 3
        total_results:
          type: integer
          example: 55
        page_number:
          type: integer
          example: 2
        page_size:
          type: integer
          example: 25
    Errors:
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error_2'
      type: object
    ValidateAddressField_2:
      type: object
      properties:
        street_address:
          $ref: '#/components/schemas/street_address'
        extended_address:
          $ref: '#/components/schemas/extended_address'
        locality:
          $ref: '#/components/schemas/locality'
        administrative_area:
          $ref: '#/components/schemas/administrative_area'
        postal_code:
          $ref: '#/components/schemas/postal_code'
        country_code:
          $ref: '#/components/schemas/country_code'
        borough:
          $ref: '#/components/schemas/borough'
        neighborhood:
          $ref: '#/components/schemas/neighborhood'
        latitude:
          type:
          - number
          - 'null'
          description: Latitude of the suggested address, when available.
        longitude:
          type:
          - number
          - 'null'
          description: Longitude of the suggested address, when available.
    Error_2:
      required:
      - code
      - title
      properties:
        code:
          type: string
          x-format: int64
        title:
          type: string
        detail:
          type: string
          description: A human-readable explanation of the error.
        description:
          type: string
        source:
          type: object
          properties:
            pointer:
              description: JSON pointer (RFC6901) to the offending entity.
              type: string
              format: json-pointer
            parameter:
              description: Indicates which query parameter caused the error.
              type: string
        meta:
          type: object
          additionalProperties: true
      example:
        title: Invalid street address
        source:
          pointer: /street_address
        code: '20207'
        description: The street address provided is invalid.
      type: object
    validate_address_2:
      type: boolean
      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. In an address record, this flag indicates whether emergency validation was performed at creation: `true` means the record passed emergency validation before it was created; `false` means validation was skipped during this creation request, and the address may have been validated separately. This flag is not a current validity status; emergency use still requires a valid address.'
      example: true
      default: true
  parameters:
    FilterConsolidated:
      name: filter
      in: query
      style: deepObject
      explode: true
      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]'
      schema:
        type: object
        properties:
          street_address:
            type: object
            properties:
              contains:
                type: string
                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.
          address_book:
            type: object
            properties:
              eq:
                type: string
                description: If present, only returns results with the <code>address_book</code> flag equal to the given value.
          customer_reference:
            oneOf:
            - type: string
              description: If present, addresses with <code>customer_reference</code> containing the given value will be returned. Matching is not case-sensitive.
            - type: object
              properties:
                eq:
                  type: string
                  description: Exact match for customer_reference.
                contains:
                  type: string
                  description: Partial match for customer_reference. Matching is not case-sensitive.
          used_as_emergency:
            type: string
            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.'
    SortAddress:
      name: sort
      in: query
      required: false
      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."
      schema:
        type: string
        enum:
        - created_at
        - first_name
        - last_name
        - business_name
        - street_address
        example: street_address
        default: created_at
    PageConsolidated:
      name: page
      in: query
      style: deepObject
      explode: true
      description: 'Consolidated page parameter (deepObject style). Originally: page[number], page[size]'
      schema:
        type: object
        properties:
          number:
            type: integer
            minimum: 1
            default: 1
            description: The page number to load
          size:
            type: integer
            minimum: 1
            maximum: 250
            default: 20
            description: The size of the page
  responses:
    AddressResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                $ref: '#/components/schemas/Address'
            type: object
      description: Successful response
    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
    UnprocessableEntity:
      description: 'Unprocessable entity. The request could not be processed: supplied parameters were invalid, the address failed validation for emergency use at creation (when `validate_address` is `true`, the default), or the address is in use by an active phone number order (delete). Check the `errors` array for details; when the validation service can suggest corrections for an invalid address, each offending field''s error entry carries the suggested value.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
          example:
            errors:
            - code: '10015'
              title: Bad Request
              detail: The street address provided is invalid.
              source:
                pointer: /street_address
              meta:
                url: https://developers.telnyx.com/docs/overview/errors/10015
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'Telnyx API key supplied as `Authorization: Bearer <token>`. In production, auth may be validated by the API gateway and forwarded via Telnyx auth headers.'
    Payment:
      type: apiKey
      in: header
      name: Authorization
      description: 'Machine Payment Protocol credential used on paid retries, sent as `Authorization: Payment ...`. Obtained by paying a challenge returned in the `WWW-Authenticate` header of a 402 response. This is not a Telnyx API key; initial challenge requests use standard bearer authentication instead.'
    agent-memory_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key
    bearerAuth:
      type: http
      scheme: bearer
    branded-calling_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
    collections_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Collections and results are automatically scoped to the authenticated user's organization.
    number-reputation_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
    oauthClientAuth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
        authorizationCode:
          authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
          tokenUrl: https://api.telnyx.com/v2/oauth/token
          refreshUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
      description: OAuth 2.0 authentication for Telnyx API and MCP integrations
    outbound-voice-profiles_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    pronunciation-dicts_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
    rcs-registration_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
    stored-payment-transactions_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    transcriptions-search_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Results are automatically scoped to the authenticated user's organization.
    web-search_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key
    pay-connectors_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key, not the processor bearer token.
    telnyxApiKey:
      type: http
      scheme: bearer
      description: Management-only Telnyx account credential.
x-refined-from:
- telnyx-openapi.json
- telnyx-openapi.yml
- telnyx-openapi_2.json
x-service-info:
  categories:
  - communication
  - developer-tools
  docs:
    apiReference: https://developers.telnyx.com
    homepage: https://telnyx.com
    llms: https://telnyx.com/llms.txt