Number Lookup API

Look up phone number data

Lookup phone number data

Returns information about the provided phone number.

SecuritybearerAuth
Request
path Parameters
phone_number
required
string

The phone number to be looked up

Example: +18665552368
query Parameters
type
string

Specifies the type of number lookup to be performed

Enum: "carrier" "caller-name"
Responses
200

Successful response

Response Schema: application/json
object (NumberLookupRecord)
object (CallerName)
object (Carrier)
country_code
string

Region code that matches the specific country calling code

fraud
string

Unused

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

object (Portability)
record_type
string

Identifies the type of record

422

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

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
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_lookup/{phone_number}
Request samples 
import telnyx
telnyx.api_key = "YOUR_API_KEY"

lookup = telnyx.NumberLookup.retrieve("+18665552368")
lookup.type("carrier")
Response samples
application/json
{
  • "data": {
    • "caller_name": {
      • "caller_name": "TELNYX LLC",
      • "error_code": "10001"
      },
    • "carrier": {
      • "error_code": null,
      • "mobile_country_code": "US",
      • "mobile_network_code": 866,
      • "name": "Telnyx/4",
      • "type": "voip"
      },
    • "country_code": "US",
    • "fraud": null,
    • "national_format": "(0312) 945-7420",
    • "phone_number": "+13129457420",
    • "portability": {
      • "altspid": "073H",
      • "altspid_carrier_name": "Telnyx/4",
      • "altspid_carrier_type": "3",
      • "city": "WAUKEGAN",
      • "line_type": "voip",
      • "lrn": "2245701999",
      • "ocn": "073H",
      • "ported_date": "2017-10-20",
      • "ported_status": "Y",
      • "spid": "073H",
      • "spid_carrier_name": "Telnyx/4",
      • "spid_carrier_type": "3",
      • "state": "Illinois"
      },
    • "record_type": "number_lookup"
    }
}