Skip to main content

Lookup phone number data

GET 
/number_lookup/:phone_number

Returns information about the provided phone number.

Request ​

Path Parameters

    phone_number stringrequired

    The phone number to be looked up

Query Parameters

    type string

    Possible values: [carrier, caller-name]

    Specifies the type of number lookup to be performed

Responses ​

200: Successful response

Schema

    data

    object

    record_type string

    Identifies the type of record

    country_code string

    Region code that matches the specific country calling code

    national_format string

    Hyphen-separated national number, preceded by the national destination code (NDC), with a 0 prefix, if an NDC is found

    phone_number string

    E164-formatted phone number

    fraud string

    Unused

    carrier

    object

    mobile_country_code string

    Region code that matches the specific country calling code if the requested phone number type is mobile

    mobile_network_code string

    National destination code (NDC), with a 0 prefix, if an NDC is found and the requested phone number type is mobile

    name string

    SPID (Service Provider ID) name, if the requested phone number has been ported; otherwise, the name of carrier who owns the phone number block

    type string

    Possible values: [fixed line, mobile, voip, fixed line or mobile, toll free, premium rate, shared cost, personal number, pager, uan, voicemail, unknown]

    A phone number type that identifies the type of service associated with the requested phone number

    error_code string

    Unused

    normalized_carrier string

    If known to Telnyx and applicable, the primary network carrier.

    caller_name

    object

    caller_name string

    The name of the requested phone number's owner as per the CNAM database

    error_code string

    A caller-name lookup specific error code, expressed as a stringified 5-digit integer

    portability

    object

    lrn string

    Local Routing Number, if assigned to the requested phone number

    ported_status string

    Possible values: [Y, N, ``]

    Indicates whether or not the requested phone number has been ported

    ported_date string

    ISO-formatted date when the requested phone number has been ported

    ocn string

    Operating Company Name (OCN) as per the Local Exchange Routing Guide (LERG) database

    line_type string

    Type of number

    spid string

    SPID (Service Provider ID)

    spid_carrier_name string

    Service provider name

    spid_carrier_type string

    Service provider type

    altspid string

    Alternative SPID (Service Provider ID). Often used when a carrier is using a number from another carrier

    altspid_carrier_name string

    Alternative service provider name

    altspid_carrier_type string

    Alternative service provider type

    city string

    City name extracted from the locality in the Local Exchange Routing Guide (LERG) database

    state string

422: Unprocessable entity. Check the 'detail' field in response for details.

Schema

    errors

    Error[]

  • Array [

    • code intrequired
    title stringrequired
    detail string

    source

    object

    pointer json-pointer

    JSON pointer (RFC6901) to the offending entity.

    parameter string

    Indicates which query parameter caused the error.

    meta object

  • ]

default: Unexpected error

Schema

    errors

    Error[]

  • Array [

    • code intrequired
    title stringrequired
    detail string

    source

    object

    pointer json-pointer

    JSON pointer (RFC6901) to the offending entity.

    parameter string

    Indicates which query parameter caused the error.

    meta object

  • ]

Request samples

curl -L 'https://api.telnyx.com/v2/number_lookup/:phone_number' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>'

Response samples

{
  "data": {
    "record_type": "number_lookup",
    "country_code": "US",
    "national_format": "(0312) 945-7420",
    "phone_number": "+13129457420",
    "fraud": null,
    "carrier": {
      "mobile_country_code": "US",
      "mobile_network_code": "0866",
      "name": "Telnyx/4",
      "type": "voip",
      "error_code": null,
      "normalized_carrier": "AT&T"
    },
    "caller_name": {
      "caller_name": "TELNYX LLC",
      "error_code": "10001"
    },
    "portability": {
      "lrn": "2245701999",
      "ported_status": "Y",
      "ported_date": "2017-10-20",
      "ocn": "073H",
      "line_type": "voip",
      "spid": "073H",
      "spid_carrier_name": "Telnyx/4",
      "spid_carrier_type": "3",
      "altspid": "073H",
      "altspid_carrier_name": "Telnyx/4",
      "altspid_carrier_type": "3",
      "city": "WAUKEGAN",
      "state": "Illinois"
    }
  }
}