Number Reservations API

Number reservations API

List number reservations

Gets a paginated list of phone number reservations.

SecuritybearerAuth
Request
query Parameters
filter[status]
string

Filter number reservations by status.

filter[created_at][gt]
string

Filter number reservations later than this value.

filter[created_at][lt]
string

Filter number reservations earlier than this value.

filter[phone_numbers.phone_number]
string

Filter number reservations having these phone numbers.

filter[customer_reference]
string

Filter number reservations via the customer reference set.

page[number]
integer >= 1
Default: 1

The page number to load

page[size]
integer [ 1 .. 250 ]
Default: 20

The size of the page

Responses
200

Successful response with a list of number reservations.

Response Schema: application/json
Array of objects (NumberReservation)
object (PaginationMeta)
default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
get/number_reservations
Request samples 
import telnyx
telnyx.api_key = "YOUR_API_KEY"

telnyx.NumberReservation.list(filter={"phone_numbers.phone_number": ["+18665552368"]})
Response samples
application/json
{
  • "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",
          • "errors": "",
          • "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 number reservation

Creates a Phone Number Reservation for multiple numbers.

SecuritybearerAuth
Request
Request Body schema: application/json
required
customer_reference
string

A customer reference string for customer look ups.

Array of objects (ReservedPhoneNumber)
Responses
200

Successful response with details about a number reservation.

Response Schema: application/json
object (NumberReservation)
created_at
string <datetime>

An ISO 8901 datetime string denoting when the numbers reservation was created.

customer_reference
string

A customer reference string for customer look ups.

id
string <uuid>
Array of objects (ReservedPhoneNumber)
record_type
string
status
string

The status of the entire reservation.

Enum: "pending" "success" "failure"
updated_at
string <datetime>

An ISO 8901 datetime string for when the number reservation was updated.

default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
post/number_reservations
Request samples
application/json
{
  • "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"
}
Response samples
application/json
{
  • "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",
        • "errors": "",
        • "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"
    }
}

Retrieve a number reservation

Gets a single phone number reservation.

SecuritybearerAuth
Request
path Parameters
number_reservation_id
required
string

The number reservation ID.

Responses
200

Successful response with details about a number reservation.

Response Schema: application/json
object (NumberReservation)
created_at
string <datetime>

An ISO 8901 datetime string denoting when the numbers reservation was created.

customer_reference
string

A customer reference string for customer look ups.

id
string <uuid>
Array of objects (ReservedPhoneNumber)
record_type
string
status
string

The status of the entire reservation.

Enum: "pending" "success" "failure"
updated_at
string <datetime>

An ISO 8901 datetime string for when the number reservation was updated.

default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
get/number_reservations/{number_reservation_id}
Request samples 
import telnyx
telnyx.api_key = "YOUR_API_KEY"

telnyx.NumberReservation.retrieve("uuid")
Response samples
application/json
{
  • "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",
        • "errors": "",
        • "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 number reservation

Extends reservation expiry time on all phone numbers.

SecuritybearerAuth
Request
path Parameters
number_reservation_id
required
string

The number reservation ID.

Responses
200

Successful response with details about a number reservation.

Response Schema: application/json
object (NumberReservation)
created_at
string <datetime>

An ISO 8901 datetime string denoting when the numbers reservation was created.

customer_reference
string

A customer reference string for customer look ups.

id
string <uuid>
Array of objects (ReservedPhoneNumber)
record_type
string
status
string

The status of the entire reservation.

Enum: "pending" "success" "failure"
updated_at
string <datetime>

An ISO 8901 datetime string for when the number reservation was updated.

default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
post/number_reservations/{number_reservation_id}/actions/extend
Request samples 
import telnyx
telnyx.api_key = "YOUR_API_KEY"

number_reservation = telnyx.NumberReservation.retrieve("uuid")
number_reservation.extend()
Response samples
application/json
{
  • "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",
        • "errors": "",
        • "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"
    }
}