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

Open SidemenuAPI Reference
API Reference
Close Sidemenu

Number Reservations

List multiple Number ReservationslistNumberReservations

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

Gets a paginated list of Phone Number Reservations

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/number_reservations?filter[phone_numbers.phone_number][]=%2B18665552368"
Parameters
In query
filter[status]
string
optional

Filter number reservations by status

filter[created_at][gt]
string
optional

Filter number reservations later than this value

filter[created_at][lt]
string
optional

Filter number reservations earlier than this value

filter[phone_numbers.phone_number]
string
optional

Filter number reservations having these phone numbers

filter[customer_reference]
string
optional

Filter number reservations via the customer reference set

Responses
200

Returns a list of number reservations

default

Unexpected error

Success Response
{
  "data": [
    {
      "created_at": "2018-01-01T00:00:00.000000Z",
      "customer_reference": "MY REF 001",
      "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
      "phone_numbers": [
        {
          "created_at": "2018-01-01T00:00:00.000000Z",
          "expired_at": "2018-01-01T00:00:00.000000Z",
          "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
          "phone_number": "+19705555098",
          "record_type": "reserved_phone_number",
          "status": "pending",
          "updated_at": "2018-01-01T00:00:00.000000Z"
        }
      ],
      "record_type": "number_reservation",
      "status": "pending",
      "updated_at": "2018-01-01T00:00:00.000000Z"
    }
  ],
  "meta": {
    "page_number": 2,
    "page_size": 25,
    "total_pages": 3,
    "total_results": 55
  }
}

Create a Phone Number ReservationcreateNumberReservations

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

Creates a Phone Number Reservation for multiple numbers

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{
    "phone_numbers": [{"phone_number": "+18665552368"}]
  }' \
  https://api.telnyx.com/v2/number_reservations
Parameters
In body
customer_reference
string
optional

A customer reference string for customer look ups

Example: "MY REF 001"
phone_numbers
array of
optional
phone_number
string (e164_phone_number)
Example: "+19705555098"
Responses
200

Number reservation has been created successfully

default

Unexpected error

Success Response
{
  "data": {
    "created_at": "2018-01-01T00:00:00.000000Z",
    "customer_reference": "MY REF 001",
    "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
    "phone_numbers": [
      {
        "created_at": "2018-01-01T00:00:00.000000Z",
        "expired_at": "2018-01-01T00:00:00.000000Z",
        "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
        "phone_number": "+19705555098",
        "record_type": "reserved_phone_number",
        "status": "pending",
        "updated_at": "2018-01-01T00:00:00.000000Z"
      }
    ],
    "record_type": "number_reservation",
    "status": "pending",
    "updated_at": "2018-01-01T00:00:00.000000Z"
  }
}

Get a Single Phone Number ReservationretrieveNumberReservation

get https://api.telnyx.com/v2/number_reservations/{number_reservation_id}

Gets a single Phone Number Reservation

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

The number reservation id

Responses
200

Number reservation was found

default

Unexpected error

Success Response
{
  "data": {
    "created_at": "2018-01-01T00:00:00.000000Z",
    "customer_reference": "MY REF 001",
    "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
    "phone_numbers": [
      {
        "created_at": "2018-01-01T00:00:00.000000Z",
        "expired_at": "2018-01-01T00:00:00.000000Z",
        "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
        "phone_number": "+19705555098",
        "record_type": "reserved_phone_number",
        "status": "pending",
        "updated_at": "2018-01-01T00:00:00.000000Z"
      }
    ],
    "record_type": "number_reservation",
    "status": "pending",
    "updated_at": "2018-01-01T00:00:00.000000Z"
  }
}

Extend a Phone Number ReservationextendNumberReservationExpiryTime

post https://api.telnyx.com/v2/number_reservations/{number_reservation_id}/actions/extend

Extends reservation expiry time on all phone numbers

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{}' \
  https://api.telnyx.com/v2/number_reservations/{number_reservation_id}/actions/extend
Parameters
In path
number_reservation_id
string
required

The number reservation id

Responses
200

Number reservation was found

default

Unexpected error

Success Response
{
  "data": {
    "created_at": "2018-01-01T00:00:00.000000Z",
    "customer_reference": "MY REF 001",
    "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
    "phone_numbers": [
      {
        "created_at": "2018-01-01T00:00:00.000000Z",
        "expired_at": "2018-01-01T00:00:00.000000Z",
        "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
        "phone_number": "+19705555098",
        "record_type": "reserved_phone_number",
        "status": "pending",
        "updated_at": "2018-01-01T00:00:00.000000Z"
      }
    ],
    "record_type": "number_reservation",
    "status": "pending",
    "updated_at": "2018-01-01T00:00:00.000000Z"
  }
}

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