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[customer_reference][eq]
string
optional

Filter addresses via the customer reference set. Matching is not case-sensitive.

filter[customer_reference][contains]
string
optional

If present, addresses with customer_reference containing the given value will be returned. Matching is not case-sensitive.

filter[used_as_emergency]
string
optional

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.

Default: "null"
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",
      "customer_reference": "MY REF 001",
      "extended_address": "#504",
      "first_name": "Alfred",
      "id": "1293384261075731499",
      "last_name": "Foster",
      "locality": "Chicago",
      "neighborhood": "Ciudad de los deportes",
      "phone_number": "+12125559000",
      "postal_code": "60654",
      "record_type": "address",
      "street_address": "311 W Superior Street",
      "updated_at": "2018-02-02T22:25:27.521Z",
      "validate_address": true
    }
  ],
  "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 '{
    "first_name":"Alfred",
    "last_name":"Foster",
    "business_name":"Company",
    "country_code":"US",
    "locality":"Chicago",
    "street_address":"311 W Superior Street",
    "postal_code":"60654",
    "administrative_area":"IL"
  }' \
  https://api.telnyx.com/v2/addresses
Parameters
In body (application/json)
business_name
string
required

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
required

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

Example: "US"
first_name
string
required

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
required

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

Example: "Foster"
locality
string
required

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

Example: "Chicago"
street_address
string
required

The primary street address information about the address.

Example: "311 W Superior Street"
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"
customer_reference
string
optional

A customer reference string for customer look ups.

Example: "MY REF 001"
extended_address
string
optional

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

Example: "#504"
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: "60654"
validate_address
boolean
optional

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.

Default: true
Example: true
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",
    "customer_reference": "MY REF 001",
    "extended_address": "#504",
    "first_name": "Alfred",
    "id": "1293384261075731499",
    "last_name": "Foster",
    "locality": "Chicago",
    "neighborhood": "Ciudad de los deportes",
    "phone_number": "+12125559000",
    "postal_code": "60654",
    "record_type": "address",
    "street_address": "311 W Superior Street",
    "updated_at": "2018-02-02T22:25:27.521Z",
    "validate_address": true
  }
}

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",
    "customer_reference": "MY REF 001",
    "extended_address": "#504",
    "first_name": "Alfred",
    "id": "1293384261075731499",
    "last_name": "Foster",
    "locality": "Chicago",
    "neighborhood": "Ciudad de los deportes",
    "phone_number": "+12125559000",
    "postal_code": "60654",
    "record_type": "address",
    "street_address": "311 W Superior Street",
    "updated_at": "2018-02-02T22:25:27.521Z",
    "validate_address": true
  }
}

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",
    "customer_reference": "MY REF 001",
    "extended_address": "#504",
    "first_name": "Alfred",
    "id": "1293384261075731499",
    "last_name": "Foster",
    "locality": "Chicago",
    "neighborhood": "Ciudad de los deportes",
    "phone_number": "+12125559000",
    "postal_code": "60654",
    "record_type": "address",
    "street_address": "311 W Superior Street",
    "updated_at": "2018-02-02T22:25:27.521Z",
    "validate_address": true
  }
}

Validate an addressvalidateAddress

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

Validates an address for emergency services.

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{
    "administrative_area":"IL",
    "country_code":"US",
    "locality":"Chicago",
    "postal_code":"60654",
    "street_address":"311 W Superior Street"
  }' \
  https://api.telnyx.com/v2/addresses/actions/validate
Parameters
In body (application/json)
administrative_area
string
required

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

Example: "IL"
country_code
string
required

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

Example: "US"
locality
string
required

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

Example: "Chicago"
postal_code
string
required

The postal code of the address.

Example: "60654"
street_address
string
required

The primary street address information about the address.

Example: "311 W Superior Street"
extended_address
string
optional

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

Example: "#504"
Responses
200

Action response

422

Bad request

Success Response
{
  "data": {
    "errors": [
      {
        "code": "string",
        "detail": "string",
        "meta": {},
        "source": {
          "parameter": "string",
          "pointer": "string"
        },
        "title": "string"
      }
    ],
    "record_type": "address_validation",
    "result": "valid",
    "suggested": {
      "administrative_area": "IL",
      "country_code": "US",
      "extended_address": "#504",
      "locality": "Chicago",
      "postal_code": "60654",
      "street_address": "311 W Superior Street"
    }
  }
}
Previous: Overview
Next: Billing

Was this section helpful?