Skip to main content

List all numbers

GET 
/origination/numbers

Returns a list of your numbers. Append .csv to the request URL to retrieve results in CSV format.

Request​

Query Parameters

    filter_tag string

    Optional filtering parameter. If present, only numbers that have been tagged 　with the string given will be returned. Returns exact matches only.

    filter_number_val string

    Optional filtering parameter. If present, only numbers that at least partially match the value given in their number will be returned. Requires at least three digits. Non-numerical characters should not be present in the filter and will result in no values being returned.

    filter_status integer

    Possible values: [1, 2, 3, 4, 5]

    Optional filtering parameter. If present, only numbers that have the same status as specified will be returned.

    filter_emergency_status string

    Possible values: [disabled, active, provisioning, deprovisioning]

    Optional filtering parameter. If present, only numbers that have the same emergency_status as specified will be returned.

    filter_connection_name string

    Optional filtering parameter. If present, only numbers that have a connection that at least partially matches the string given will be returned. Matching is not case-sensitive. Requires at least three characters. Numbers without a connection will not be returned.

    filter_usage_payment_method string

    Possible values: [pay-per-minute, channel]

    Optional filtering parameter. If present, only numbers that have the usage_payment_method that at matches the string given will be returned. Matching is case-sensitive and only specified values are allowed.

    filter_billing_group_id string

    Optional filtering parameter. If present, only numbers with a billing_group_id matching the string given will be returned. To search for only numbers that do not have a billing_group_id, specify the literal value "null".

    order_by string

    Possible values: [order_date, phone_number, connection, usage_payment_method]

    Specify an ordering for the results. Optional parameter. If present, must be of a set number of values: "order_date", "phone_number", "connection", or "usage_payment_method". Other values are invalid and will result in the call failing. "order_date" will order numbers with the most recent purchases first, then older ones at the end. "phone_number" will sort by the phone number values. "connection" will order by the connection name with numbers not having a connection assigned yet at the end. "usage_payment_method" will put numbers with "pay-per-minute" first.

    sort_direction string

    Possible values: [reverse]

    The sort_direction specifies in which way the ordering of the connections is applied. If not present, ordering will be performed as described under the order_by parameter. You may invert this ordering by specifying "reverse" as the sort_direction. This parameter is optional.

    page integer

    Default value: 1

    Page number of results to load

    per_page integer

    Possible values: <= 1000

    Default value: 100

    Number of results per page

Responses​

200: Number response

Schema

  • Array [

    • id stringrequired
    connection_id stringrequired
    number_val_e164 stringrequired
    ignore_tech_prefix booleanrequired

    Default value: true

    DEPRECATED - Use enable_tech_prefix on API requests

    enable_tech_prefix booleanrequired
    translated_number stringrequired
    forwards_to stringrequired

    the number that this number should be forwarded to; when this is set, forwarding_type must also be set

    forwarding_type stringrequired

    sets when this number should have its calls forwarded; valid values are 'always' and 'on-failure'

    tag_list string[]required
    status integerrequired

    Default value: 1

    Purchase Pending = 1, Purchase Failed = 2, Port Pending = 3, Active = 4, Deleted = 5, Port Failed = 6, Emergency Only = 7, Ported Out = 8, Port Out Pending = 9

    purchase_failure_reason stringrequired

    reason(s) why the last attempt to purchase this number failed

    e911_enabled boolean
    e911_address_id string
    emergency_status string

    Possible values: [disabled, active, provisioning, deprovisioning]

    Default value: disabled

    address_id string

    use this property to reference an Address record if required for a number record

    usage_payment_method stringrequired

    Possible values: [pay-per-minute, channel]

    Default value: pay-per-minute

    setting for whether a number is billed per minute or uses your concurrent channels

    enable_rtp_auto_adjust booleanrequired

    Default value: true

    When RTP Auto-Adjust is enabled, the destination RTP address port will be automatically changed to match the source of the incoming RTP packets.

    cnam_listing_enabled booleanrequired

    Enable CNAM listings for this number. Requires cnam_listing_details to also be filled in.

    cnam_listing_details stringrequired

    The CNAM listing details for this number. Must be alphanumeric characters or spaces with a maximum length of 15. Requires cnam_listing_enabled to also be set.

    external_pin string

    External PINs are used to ensure that phone numbers on your account cannot be ported to another carrier without your consent. This has an account level default but may also be specified per phone number. External PINs must be 4 numeric digits ('3456').

    t38_fax_gateway_enabled boolean
    accept_any_rtp_packets_enabled boolean
    number_val stringrequired

    DEPRECATION WARNING! Please use number_val_e164 or contact [email protected] if you depend on this key.

    inbound_call_recording_enabled booleanrequired

    When enabled, any inbound call to this number will be recorded.

    inbound_call_recording_format stringrequired

    Possible values: [wav, mp3]

    Default value: wav

    The audio file format for calls being recorded.

    inbound_call_recording_channels string

    Possible values: [single, dual]

    Default value: single

    When using 'dual' channels, final audio file will be stereo recorded with the first leg on channel A, and the rest on channel B.

    billing_group_id string

    The ID of the Billing Group to which the number is assigned. Defaults to null (for no group assigned).

  • ]

401: Unauthorized

422: Unprocessable entity. Can be caused by invalid values for ordering or filtering. Check message field in response for details.

Request samples

curl -L 'https://api.telnyx.com/origination/numbers' \
-H 'Accept: application/json'

Response samples

[
  {
    "id": "string",
    "connection_id": "string",
    "number_val_e164": "string",
    "ignore_tech_prefix": true,
    "enable_tech_prefix": false,
    "translated_number": "string",
    "forwards_to": "string",
    "forwarding_type": "string",
    "tag_list": [
      "string"
    ],
    "status": 1,
    "purchase_failure_reason": "string",
    "e911_enabled": false,
    "e911_address_id": "string",
    "emergency_status": "disabled",
    "address_id": "string",
    "usage_payment_method": "pay-per-minute",
    "enable_rtp_auto_adjust": true,
    "cnam_listing_enabled": false,
    "cnam_listing_details": "string",
    "external_pin": "string",
    "t38_fax_gateway_enabled": false,
    "accept_any_rtp_packets_enabled": false,
    "number_val": "string",
    "inbound_call_recording_enabled": false,
    "inbound_call_recording_format": "wav",
    "inbound_call_recording_channels": "single",
    "billing_group_id": "string"
  }
]