This is the API V2 documentation. To switch out of beta revert back to our API V1.

Open SidemenuAPI Reference
API Reference
Close Sidemenu

Addresses

List all addressesfindAddresss

get https://api.telnyx.com/v2/addresses

Returns a list of your addresses.

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/addresses?page[number]=1&page[size]=20"
Parameters
In query
page[number]
integer (1)
optional

The page number to load

Default: 1
page[size]
integer (1 - 250)
optional

The size of the page

Default: 20
filter[street_address][contains]
string
optional

If present, addresses with street_address containing the given value will be returned. Matching is not case-sensitive. Requires at least three characters.

Default: "null"
filter[address_book][eq]
string
optional

If present, only returns results with the address_book flag set to the given value.

Default: "null"
sort
string
optional

Specifies the sort order for results. By default sorting direction is ascending. To have the results sorted in descending order add the - prefix.

That is:

  • street_address: sorts the result by the street_address field in ascending order.
  • -street_address: sorts the result by the street_address field in descending order.

If not given, results are sorted by created_at in descending order.

Default: "created_at"
Example: "street_address"
Options: [ "created_at", "first_name", "last_name", "business_name", "street_address" ]
Responses
200

Successful response

400

Bad request

401

Unauthorized

404

Resource not found

Success Response
{
  "data": [
    {
      "address_book": false,
      "administrative_area": "IL",
      "borough": "Guadalajara",
      "business_name": "Toy-O'Kon",
      "country_code": "us",
      "created_at": "2018-02-02T22:25:27.521Z",
      "extended_address": "Suite 123",
      "first_name": "Alfred",
      "id": "1293384261075731499",
      "last_name": "Foster",
      "locality": "Chicago",
      "neighborhood": "Ciudad de los deportes",
      "phone_number": "+12125559000",
      "postal_code": 2904,
      "record_type": "address",
      "street_address": "457 Flatley Stream",
      "updated_at": "2018-02-02T22:25:27.521Z"
    }
  ],
  "meta": {
    "page_number": 2,
    "page_size": 25,
    "total_pages": 3,
    "total_results": 55
  }
}

Creates an addressCreateAddress

post https://api.telnyx.com/v2/addresses

Creates an address.

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"address_book":true,"administrative_area":"IL"}' \
  https://api.telnyx.com/v2/addresses
Parameters
In body
address_book
boolean
optional

Indicates whether or not the address should be considered part of your list of addresses that appear for regular use.

Default: true
administrative_area
string
optional

The locality of the address. For US addresses, this corresponds to the state of the address.

Example: "IL"
borough
string
optional

The borough of the address. This field is not used for addresses in the US but is used for some international addresses.

Example: "Guadalajara"
business_name
string
optional

The business name associated with the address. An address must have either a first last name or a business name.

Example: "Toy-O'Kon"
country_code
string
optional

The two-character (ISO 3166-1 alpha-2) country code of the address.

Example: "us"
extended_address
string
optional

Additional street address information about the address such as, but not limited to, unit number or apartment number.

Example: "Suite 123"
first_name
string
optional

The first name associated with the address. An address must have either a first last name or a business name.

Example: "Alfred"
last_name
string
optional

The last name associated with the address. An address must have either a first last name or a business name.

Example: "Foster"
locality
string
optional

The locality of the address. For US addresses, this corresponds to the city of the address.

Example: "Chicago"
neighborhood
string
optional

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"
phone_number
string
optional

The phone number associated with the address.

Example: "+12125559000"
postal_code
string
optional

The postal code of the address.

Example: 2904
street_address
string
optional

The primary street address information about the address.

Example: "457 Flatley Stream"
Responses
200

Successful response

422

Bad request

Success Response
{
  "data": {
    "address_book": false,
    "administrative_area": "IL",
    "borough": "Guadalajara",
    "business_name": "Toy-O'Kon",
    "country_code": "us",
    "created_at": "2018-02-02T22:25:27.521Z",
    "extended_address": "Suite 123",
    "first_name": "Alfred",
    "id": "1293384261075731499",
    "last_name": "Foster",
    "locality": "Chicago",
    "neighborhood": "Ciudad de los deportes",
    "phone_number": "+12125559000",
    "postal_code": 2904,
    "record_type": "address",
    "street_address": "457 Flatley Stream",
    "updated_at": "2018-02-02T22:25:27.521Z"
  }
}

Retrieve an addressgetAddress

get https://api.telnyx.com/v2/addresses/{id}

Retrieves the details of an existing address.

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/addresses/{id}"
Parameters
In path
id
string
required

address ID

Responses
200

Successful response

401

Unauthorized

404

Resource not found

422

Bad request

Success Response
{
  "data": {
    "address_book": false,
    "administrative_area": "IL",
    "borough": "Guadalajara",
    "business_name": "Toy-O'Kon",
    "country_code": "us",
    "created_at": "2018-02-02T22:25:27.521Z",
    "extended_address": "Suite 123",
    "first_name": "Alfred",
    "id": "1293384261075731499",
    "last_name": "Foster",
    "locality": "Chicago",
    "neighborhood": "Ciudad de los deportes",
    "phone_number": "+12125559000",
    "postal_code": 2904,
    "record_type": "address",
    "street_address": "457 Flatley Stream",
    "updated_at": "2018-02-02T22:25:27.521Z"
  }
}

Deletes an addressDeleteAddress

delete https://api.telnyx.com/v2/addresses/{id}

Deletes an existing address.

curl -X DELETE \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  "https://api.telnyx.com/v2/addresses/{id}"
Parameters
In path
id
string
required

address ID

Responses
200

Successful response

401

Unauthorized

404

Resource not found

422

Bad request

Success Response
{
  "data": {
    "address_book": false,
    "administrative_area": "IL",
    "borough": "Guadalajara",
    "business_name": "Toy-O'Kon",
    "country_code": "us",
    "created_at": "2018-02-02T22:25:27.521Z",
    "extended_address": "Suite 123",
    "first_name": "Alfred",
    "id": "1293384261075731499",
    "last_name": "Foster",
    "locality": "Chicago",
    "neighborhood": "Ciudad de los deportes",
    "phone_number": "+12125559000",
    "postal_code": 2904,
    "record_type": "address",
    "street_address": "457 Flatley Stream",
    "updated_at": "2018-02-02T22:25:27.521Z"
  }
}
Previous: Overview
Next: Billing

Was this section helpful?was-this-page-helpful