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

application/json

• Schema
• Example (from schema)

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

{
  "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"
    }
  }
}

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

application/json

• Schema
• Example (from schema)

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

]

{
  "errors": [
    {
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}

default: Unexpected error

application/json

• Schema
• Example (from schema)

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

]

{
  "errors": [
    {
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}

Loading...