Phone Number Validation

GET 
/phone_numbers

Query for and validate phone numbers.

Request

Query Parameters

api_key string
API Key
Your unique identifier that allows access to our APIs.
Begins ak_. Available from your dashboard
Example: ak_test
query stringrequired

Specifies the phone number to validate. Phone number must include a country code in acceptable format. For instance, UK phone numbers should be suffixed +44, 44 or 0044.

current_carrier string

Possible values: [true]

When set to true the current network of the phone number will be retrieved and populated.

Note that this operation is potentially slow depending on the network and local conditions.

Tags string
A comma separated list of tags to query over.
Useful if you want to specify the circumstances in which the request was made.
If multiple tags are specified, the response will only comprise of requests for which all the tags are satisfied - i.e. searching "foo,bar" will only query requests which tagged both "foo" and "bar".
Example: foo,bar

Responses

200

Success

application/json

Schema

Schema

code int32required

Possible values: [2000]

message stringrequired

Possible values: [Success]

result object required

oneOf

Phone Number Object

valid booleanrequired

Possible values: [true]

national_format stringrequired

Phone number formatted to local standard

international_format stringrequired

Phone number formatted to international standard

iso_country stringrequired

Country code in 3 letter ISO format

iso_country_2 stringrequired

Country code in 2 letter ISO format

country stringrequired

Full country name

current_carrier objectnullablerequired

Representation of current phone carrier information like network code, name, country, network type

network_code Network Codenullablerequired

The Mobile Country Code for the carrier.

name Namenullablerequired

The full name of the carrier that number is associated with.

country Country ISO Alpha-2 Codenullablerequired

Country that number is associated with. In ISO 3166-1 alpha-2 format.

network_type Network Typenullablerequired

Possible values: [mobile, landline, landline_premium, landline_tollfree, virtual, unknown, pager, mobile_or_landline, shared_cost, uan, voicemail]

Type of network that number is associated with.

original_carrier objectnullablerequired

Representation of original phone carrier information like network code, name, country, network type

network_code Network Codenullablerequired

The Mobile Country Code for the carrier.

name Namenullablerequired

The full name of the carrier that number is associated with.

country Country ISO Alpha-2 Codenullablerequired

Country that number is associated with. In ISO 3166-1 alpha-2 format.

network_type Network Typenullablerequired

Possible values: [mobile, landline, landline_premium, landline_tollfree, virtual, unknown, pager, mobile_or_landline, shared_cost, uan, voicemail]

Type of network that number is associated with.

Invalid Phone Number Object

valid booleanrequired

Possible values: [false]

national_format stringnullablerequired

Possible values: [null]

Phone number formatted to local standard

international_format stringnullablerequired

Possible values: [null]

Phone number formatted to international standard

iso_country stringnullablerequired

Possible values: [null]

Country code in 3 letter ISO format

iso_country_2 stringnullablerequired

Possible values: [null]

Country code in 2 letter ISO format

country stringnullablerequired

Possible values: [null]

Full country name

current_carrier stringnullable

Possible values: [null]

Representation of current phone carrier information like network code, name, country, network type

original_carrier stringnullable

Possible values: [null]

Representation of original phone carrier information like network code, name, country, network type

Example (from schema)

{
  "result": {
    "valid": true,
    "national_format": "020 7112 8019",
    "international_format": "+44 20 7112 8019",
    "iso_country": "GBR",
    "iso_country_2": "GB",
    "country": "United Kingdom",
    "current_carrier": {
      "network_code": null,
      "name": "Invomo Ltd",
      "country": "GB",
      "network_type": "landline"
    },
    "original_carrier": {
      "network_code": null,
      "name": "Invomo Ltd",
      "country": "GB",
      "network_type": "landline"
    }
  },
  "code": 2000,
  "message": "Success"
}

Valid Phone Number

{
  "result": {
    "valid": true,
    "national_format": "020 7112 8019",
    "international_format": "+44 20 7112 8019",
    "iso_country": "GBR",
    "iso_country_2": "GB",
    "country": "United Kingdom",
    "current_carrier": {
      "network_code": null,
      "name": "Invomo Ltd",
      "country": "GB",
      "network_type": "landline"
    },
    "original_carrier": {
      "network_code": null,
      "name": "Invomo Ltd",
      "country": "GB",
      "network_type": "landline"
    }
  },
  "code": 2000,
  "message": "Success"
}

400

Bad Request

application/json

Schema

Schema

code int32required

API Response Code. Non 2xxx code indicates a failure. This code will provide a more specific reason when a failure occurs and facilitates debugging.

message stringrequired

Human readable error message supplied with every error response.

errors object[]
Array [
message stringrequired
Indicates location of error in request query or URL parameter
path stringrequired
Indicates location of error in request query or URL parameter
errorCode string
]

Example (from schema)

{
  "code": 0,
  "message": "string",
  "errors": [
    {
      "message": "should have required property 'type'",
      "path": ".query.type",
      "errorCode": "required.openapi.validation"
    }
  ]
}

401

Unauthorized

application/json

Schema

Schema

code int32required

API Response Code. Non 2xxx code indicates a failure. This code will provide a more specific reason when a failure occurs and facilitates debugging.

message stringrequired

Human readable error message supplied with every error response.

Example (from schema)

{
  "code": 0,
  "message": "string"
}

429

Rate Limit Timeout

application/json

Schema

Schema

code int32required

API Response Code. Non 2xxx code indicates a failure. This code will provide a more specific reason when a failure occurs and facilitates debugging.

message stringrequired

Human readable error message supplied with every error response.

errors object[]
Array [
message stringrequired
Indicates location of error in request query or URL parameter
path stringrequired
Indicates location of error in request query or URL parameter
errorCode string
]

Example (from schema)

{
  "code": 0,
  "message": "string",
  "errors": [
    {
      "message": "should have required property 'type'",
      "path": ".query.type",
      "errorCode": "required.openapi.validation"
    }
  ]
}

Loading...