Open SidemenuAPI Reference
API Reference
Close Sidemenu

Number Orders

List number orderslistNumberOrders

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

Get a paginated list of number orders.

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_orders?filter[phone_numbers.phone_number][]=%2B18665552368"
Parameters
In query
filter[status]
string
optional

Filter number orders by status.

filter[created_at][gt]
string
optional

Filter number orders later than this value.

filter[created_at][lt]
string
optional

Filter number orders earlier than this value.

filter[phone_numbers_count]
string
optional

Filter number order with this amount of numbers

filter[customer_reference]
string
optional

Filter number orders via the customer reference set.

filter[requirements_met]
boolean
optional

Filter number orders by requirements met.

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
Responses
200

Successful response with a list of number orders.

default

Unexpected error

Success Response
{
  "data": [
    {
      "billing_group_id": "abc85f64-5717-4562-b3fc-2c9600",
      "connection_id": "346789098765567",
      "created_at": "2018-01-01T00:00:00.000000Z",
      "customer_reference": "MY REF 001",
      "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
      "messaging_profile_id": "abc85f64-5717-4562-b3fc-2c9600",
      "phone_numbers_count": 1,
      "record_type": "number_order",
      "requirements_met": true,
      "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 ordercreateNumberOrder

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

Creates a phone number order.

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_orders
Parameters
In body (application/json)
billing_group_id
string
optional

Identifies the billing group associated with the phone number.

Example: "abc85f64-5717-4562-b3fc-2c9600"
connection_id
string
optional

Identifies the connection associated with this phone number.

Example: "346789098765567"
customer_reference
string
optional

A customer reference string for customer look ups.

Example: "MY REF 001"
messaging_profile_id
string
optional

Identifies the messaging profile associated with the phone number.

Example: "abc85f64-5717-4562-b3fc-2c9600"
phone_numbers
array of
optional
phone_number
string (e164_phone_number)
Example: "+19705555098"
regulatory_requirements
array of
Responses
200

Successful response with details about a number order.

default

Unexpected error

Success Response
{
  "data": {
    "billing_group_id": "abc85f64-5717-4562-b3fc-2c9600",
    "connection_id": "346789098765567",
    "created_at": "2018-01-01T00:00:00.000000Z",
    "customer_reference": "MY REF 001",
    "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
    "messaging_profile_id": "abc85f64-5717-4562-b3fc-2c9600",
    "phone_numbers_count": 1,
    "record_type": "number_order",
    "requirements_met": true,
    "status": "pending",
    "updated_at": "2018-01-01T00:00:00.000000Z",
    "phone_numbers": [
      {
        "id": "dc8e4d67-33a0-4cbb-af74-7b58f05bd494",
        "phone_number": "+19705555098",
        "record_type": "number_order_phone_number",
        "regulatory_group_id": "dc8e4d67-33a0-4cbb-af74-7b58f05bd494",
        "regulatory_requirements": [
          {}
        ],
        "requirements_met": true,
        "status": "pending"
      }
    ]
  }
}
Expected Webhooks
number Order Status Update
{
  "data": {
    "event_type": "number_order.complete",
    "id": "string",
    "occurred_at": "string",
    "payload": {
      "billing_group_id": "abc85f64-5717-4562-b3fc-2c9600",
      "connection_id": "346789098765567",
      "created_at": "2018-01-01T00:00:00.000000Z",
      "customer_reference": "MY REF 001",
      "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
      "messaging_profile_id": "abc85f64-5717-4562-b3fc-2c9600",
      "phone_numbers_count": 1,
      "record_type": "number_order",
      "requirements_met": true,
      "status": "pending",
      "updated_at": "2018-01-01T00:00:00.000000Z"
    },
    "record_type": "event"
  }
}

Retrieve a number orderretrieveNumberOrder

get https://api.telnyx.com/v2/number_orders/{number_order_id}

Get an existing phone number order.

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_orders/{number_order_id}"
Parameters
In path
number_order_id
string
required

The number order ID.

Responses
200

Successful response with details about a number order.

default

Unexpected error

Success Response
{
  "data": {
    "billing_group_id": "abc85f64-5717-4562-b3fc-2c9600",
    "connection_id": "346789098765567",
    "created_at": "2018-01-01T00:00:00.000000Z",
    "customer_reference": "MY REF 001",
    "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
    "messaging_profile_id": "abc85f64-5717-4562-b3fc-2c9600",
    "phone_numbers_count": 1,
    "record_type": "number_order",
    "requirements_met": true,
    "status": "pending",
    "updated_at": "2018-01-01T00:00:00.000000Z",
    "phone_numbers": [
      {
        "id": "dc8e4d67-33a0-4cbb-af74-7b58f05bd494",
        "phone_number": "+19705555098",
        "record_type": "number_order_phone_number",
        "regulatory_group_id": "dc8e4d67-33a0-4cbb-af74-7b58f05bd494",
        "regulatory_requirements": [
          {}
        ],
        "requirements_met": true,
        "status": "pending"
      }
    ]
  }
}

Update a number orderupdateNumberOrder

patch https://api.telnyx.com/v2/number_orders/{number_order_id}

Updates a phone number order.

curl -X PATCH \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"customer_reference": "MY REF"}' \
  https://api.telnyx.com/v2/number_orders/{number_order_id}
Parameters
In path
number_order_id
string
required

The number order ID.

In body (application/json)
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"
regulatory_requirements
array of
Responses
200

Successful response with details about a number order.

default

Unexpected error

Success Response
{
  "data": {
    "billing_group_id": "abc85f64-5717-4562-b3fc-2c9600",
    "connection_id": "346789098765567",
    "created_at": "2018-01-01T00:00:00.000000Z",
    "customer_reference": "MY REF 001",
    "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
    "messaging_profile_id": "abc85f64-5717-4562-b3fc-2c9600",
    "phone_numbers_count": 1,
    "record_type": "number_order",
    "requirements_met": true,
    "status": "pending",
    "updated_at": "2018-01-01T00:00:00.000000Z",
    "phone_numbers": [
      {
        "id": "dc8e4d67-33a0-4cbb-af74-7b58f05bd494",
        "phone_number": "+19705555098",
        "record_type": "number_order_phone_number",
        "regulatory_group_id": "dc8e4d67-33a0-4cbb-af74-7b58f05bd494",
        "regulatory_requirements": [
          {}
        ],
        "requirements_met": true,
        "status": "pending"
      }
    ]
  }
}

List sub number orderslistSubNumberOrders

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

Get a paginated list of sub number orders.

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/sub_number_orders?filter[user_id]=d70873cd-7c98-401a-81b6-b1ae08246995&filter[order_request_id]=12ade33a-21c0-473b-b055-b3c836e1c293"
Parameters
In query
filter[user_id]
string (uuid)
optional

User ID of the user who owns the sub number order

Example: "d70873cd-7c98-401a-81b6-b1ae08246995"
filter[order_request_id]
string (uuid)
optional

ID of the number order the sub number order belongs to

Example: "12ade33a-21c0-473b-b055-b3c836e1c293"
filter[country_code]
string
optional

ISO alpha-2 country code.

Example: "US"
filter[phone_number_type]
string
optional

Phone Number Type

Example: "local"
filter[phone_numbers_count]
integer
optional

Amount of numbers in the sub number order

Example: 1
Responses
200

Successful response with a list of sub number orders.

default

Unexpected error

Success Response
{
  "data": [
    {
      "country_code": "US",
      "created_at": "2018-01-01T00:00:00.000000Z",
      "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
      "order_request_id": "12ade33a-21c0-473b-b055-b3c836e1c293",
      "phone_number_type": "local",
      "phone_numbers_count": 1,
      "record_type": "sub_number_order",
      "regulatory_requirements": [
        {
          "field_type": "address",
          "record_type": "phone_number_regulatory_requirement",
          "requirement_id": "8ffb3622-7c6b-4ccc-b65f-7a3dc0099576"
        }
      ],
      "requirements_met": true,
      "updated_at": "2018-01-01T00:00:00.000000Z",
      "user_id": "d70873cd-7c98-401a-81b6-b1ae08246995"
    }
  ],
  "meta": {
    "page_number": 2,
    "page_size": 25,
    "total_pages": 3,
    "total_results": 55
  }
}

Retrieve a sub number orderretrieveSubNumberOrder

get https://api.telnyx.com/v2/sub_number_orders/{sub_number_order_id}

Get an existing sub number order.

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/sub_number_orders/{sub_number_order_id}?filter[include_phone_numbers]="
Parameters
In path
sub_number_order_id
string
required

The sub number order ID.

In query
filter[include_phone_numbers]
boolean
optional

Include the first 50 phone number objects in the results

Default: false
Responses
200

Successful response with details about a sub number order.

default

Unexpected error

Success Response
{
  "data": {
    "country_code": "US",
    "created_at": "2018-01-01T00:00:00.000000Z",
    "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
    "order_request_id": "12ade33a-21c0-473b-b055-b3c836e1c293",
    "phone_number_type": "local",
    "phone_numbers_count": 1,
    "record_type": "sub_number_order",
    "regulatory_requirements": [
      {
        "field_type": "address",
        "record_type": "phone_number_regulatory_requirement",
        "requirement_id": "8ffb3622-7c6b-4ccc-b65f-7a3dc0099576"
      }
    ],
    "requirements_met": true,
    "updated_at": "2018-01-01T00:00:00.000000Z",
    "user_id": "d70873cd-7c98-401a-81b6-b1ae08246995"
  }
}

Update a sub number orderupdateSubNumberOrder

patch https://api.telnyx.com/v2/sub_number_orders/{sub_number_order_id}

Updates a sub number order.

curl -X PATCH \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"regulatory_requirements":"array"}' \
  https://api.telnyx.com/v2/sub_number_orders/{sub_number_order_id}
Parameters
In path
sub_number_order_id
string
required

The sub number order ID.

In body (application/json)
regulatory_requirements
array of
optional
field_value
string

The value of the requirement, this could be an id to a resource or a string value.

Example: "45f45a04-b4be-4592-95b1-9306b9db2b21"
requirement_id
string (uuid)

Unique id for a requirement.

Example: "8ffb3622-7c6b-4ccc-b65f-7a3dc0099576"
Responses
200

Successful response with details about a sub number order.

default

Unexpected error

Success Response
{
  "data": {
    "country_code": "US",
    "created_at": "2018-01-01T00:00:00.000000Z",
    "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
    "order_request_id": "12ade33a-21c0-473b-b055-b3c836e1c293",
    "phone_number_type": "local",
    "phone_numbers_count": 1,
    "record_type": "sub_number_order",
    "regulatory_requirements": [
      {
        "field_type": "address",
        "record_type": "phone_number_regulatory_requirement",
        "requirement_id": "8ffb3622-7c6b-4ccc-b65f-7a3dc0099576"
      }
    ],
    "requirements_met": true,
    "updated_at": "2018-01-01T00:00:00.000000Z",
    "user_id": "d70873cd-7c98-401a-81b6-b1ae08246995"
  }
}

Retrieve a list of phone numbers associated to ordersretrieveNumberOrderPhoneNumbers

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

Get a list of phone numbers associated to orders.

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_order_phone_numbers"
Parameters
Responses
200

Successful response with a list of number order phone numbers.

default

Unexpected error

Success Response
{
  "data": [
    {
      "country_code": "US",
      "id": "dc8e4d67-33a0-4cbb-af74-7b58f05bd494",
      "order_request_id": "dc8e4d67-33a0-4cbb-af74-7b58f05bd495",
      "phone_number": "+19705555098",
      "phone_number_type": "local",
      "record_type": "number_order_phone_number",
      "regulatory_requirements": [
        {}
      ],
      "requirements_met": true,
      "status": "pending",
      "sub_number_order_id": "dc8e4d67-33a0-4cbb-af74-7b58f05bd496"
    }
  ],
  "meta": {
    "page_number": 2,
    "page_size": 25,
    "total_pages": 3,
    "total_results": 55
  }
}

Retrieve a number order phone number.retrieveNumberOrderPhoneNumber

get https://api.telnyx.com/v2/number_order_phone_numbers/{number_order_phone_number_id}

Get an existing number order phone number.

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_order_phone_numbers/{number_order_phone_number_id}"
Parameters
In path
number_order_phone_number_id
string
required

The number order phone number ID.

Responses
200

Successful response with details about a number order phone number.

default

Unexpected error

Success Response
{
  "data": {
    "country_code": "US",
    "id": "dc8e4d67-33a0-4cbb-af74-7b58f05bd494",
    "order_request_id": "dc8e4d67-33a0-4cbb-af74-7b58f05bd495",
    "phone_number": "+19705555098",
    "phone_number_type": "local",
    "record_type": "number_order_phone_number",
    "regulatory_requirements": [
      {}
    ],
    "requirements_met": true,
    "status": "pending",
    "sub_number_order_id": "dc8e4d67-33a0-4cbb-af74-7b58f05bd496"
  }
}

Update a number order phone number.updateNumberOrderPhoneNumber

patch https://api.telnyx.com/v2/number_order_phone_numbers/{number_order_phone_number_id}

Updates a number order phone number.

curl -X PATCH \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"regulatory_requirements":"array"}' \
  https://api.telnyx.com/v2/number_order_phone_numbers/{number_order_phone_number_id}
Parameters
In path
number_order_phone_number_id
string
required

The number order phone number ID.

In body (application/json)
regulatory_requirements
array of
optional
field_value
string

The value of the requirement, this could be an id to a resource or a string value.

Example: "45f45a04-b4be-4592-95b1-9306b9db2b21"
requirement_id
string (uuid)

Unique id for a requirement.

Example: "8ffb3622-7c6b-4ccc-b65f-7a3dc0099576"
Responses
200

Successful response with details about a number order phone number.

default

Unexpected error

Success Response
{
  "data": {
    "country_code": "US",
    "id": "dc8e4d67-33a0-4cbb-af74-7b58f05bd494",
    "order_request_id": "dc8e4d67-33a0-4cbb-af74-7b58f05bd495",
    "phone_number": "+19705555098",
    "phone_number_type": "local",
    "record_type": "number_order_phone_number",
    "regulatory_requirements": [
      {}
    ],
    "requirements_met": true,
    "status": "pending",
    "sub_number_order_id": "dc8e4d67-33a0-4cbb-af74-7b58f05bd496"
  }
}

Retrieve all commentslistComments

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

Retrieve all comments

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/comments?filter[comment_record_type]=sub_number_order&filter[comment_record_id]=8ffb3622-7c6b-4ccc-b65f-7a3dc0099576"
Parameters
In query
filter[comment_record_type]
string
required

Record type that the comment relates to i.e number_order, sub_number_order or number_order_phone_number

Example: "sub_number_order"
filter[comment_record_id]
string
required

ID of the record the comments relate to

Example: "8ffb3622-7c6b-4ccc-b65f-7a3dc0099576"
Responses
200

An array of Comment Responses

default

Unexpected error

Success Response
{
  "data": [
    {
      "body": "Hi there, ....",
      "comment_record_id": "8ffb3622-7c6b-4ccc-b65f-7a3dc0099576",
      "comment_record_type": "sub_number_order",
      "commenter": "user@company.com",
      "commenter_type": "user",
      "created_at": "2018-01-01T00:00:00.000000Z",
      "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
      "read_at": null,
      "updated_at": "2018-01-01T00:00:00.000000Z"
    }
  ],
  "meta": {
    "page_number": 2,
    "page_size": 25,
    "total_pages": 3,
    "total_results": 55
  }
}

Create a commentcreateComment

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

Create a comment

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"body":"Hi there, ....","comment_record_id":"8ffb3622-7c6b-4ccc-b65f-7a3dc0099576"}' \
  https://api.telnyx.com/v2/comments
Parameters
In body (application/json)
body
string
optional
Example: "Hi there, ...."
comment_record_id
string (uuid)
optional
Example: "8ffb3622-7c6b-4ccc-b65f-7a3dc0099576"
comment_record_type
string
optional
Example: "sub_number_order"
Options: [ "number_order", "sub_number_order", "number_order_phone_number" ]
Responses
200

A Comment Response

default

Unexpected error

Success Response
{
  "data": {
    "body": "Hi there, ....",
    "comment_record_id": "8ffb3622-7c6b-4ccc-b65f-7a3dc0099576",
    "comment_record_type": "sub_number_order",
    "commenter": "user@company.com",
    "commenter_type": "user",
    "created_at": "2018-01-01T00:00:00.000000Z",
    "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
    "read_at": null,
    "updated_at": "2018-01-01T00:00:00.000000Z"
  }
}

Was this section helpful?