Charging
Overview
The following page lists the different responses you can receive and how they are charged.
For the per credit cost please visit our pricing page - Here
Non HTTP 200 Response
HTTP Response | Charge? |
|---|---|
400 Bad Request | NO |
429 Too Many Requests | NO |
401 Unauthorised | NO |
500 Internal Server Error | NO |
404 Not Found | NO |
HTTP 200 Response - No additional features
error | telephone_number_type | live_status | cache | Charge? |
|---|---|---|---|---|
INTERNAL_ERROR | NO | |||
INSUFFICIENT_CREDIT | NO | |||
|
| NOT_APPLICABLE | NO | |
NONE | Any except MOBILE or BAD_FORMAT | NO_COVERAGE | NO | |
NONE | MOBILE | LIVE | PRIVATE
| NO
YES (1 Credit) |
HTTP 200 Response - Additional features requested
The following tables detail the charging when a request for one of the following additional features is requested:
Ported Date
Landline Status (UK and Ireland)
USA Status (Mobiles Only)
Ported Date: (get_ported_date: "YES")
error | telephone_number_type | live_status | is_ported | ported_date | cache | Charge? |
|---|---|---|---|---|---|---|
NONE | BAD_FORMAT | NOT_APPLICABLE | UNKNOWN | NOT_APPLICABLE | NO | |
NONE | Any except MOBILE or BAD_FORMAT | NO_COVERAGE | UNKNOWN | NOT_APPLICABLE | NO | |
NONE | MOBILE | LIVE or NOT_AVAILABLE_NETWORK_ONLY | YES | NOT_AVAILABLE | YES (1 Credit) | |
NONE | MOBILE | LIVE or NOT_AVAILABLE_NETWORK_ONLY | YES | Date Shown | PRIVATE GLOBAL NONE | YES (1 Credit) YES (1.5 Credits) YES (2 Credits) |
NONE | MOBILE | DEAD ABSENT_SUBSCRIBER NO_TELESERVICE_PROVISIONED INCONCLUSIVE | UNKNOWN | NOT_APPLICABLE | YES (1 Credit) |
Landline Status: ("get_landline_status":"YES")
error | telephone_number_type | live_status | cache | Charge? | |
|---|---|---|---|---|---|
NONE | BAD_FORMAT | NOT_APPLICABLE | NO | ||
NONE | LANDLINE | LIVE DEAD INCONCLUSIVE | PRIVATE GLOBAL NONE | NO YES (1 Credit) YES (2 Credits) | |
NONE | Any except LANDLINE or BAD_FORMAT or MOBILE | NO_COVERAGE | NO | ||
NONE | MOBILE | LIVE DEAD ABSENT_SUBSCRIBER NO_TELESERVICE_PROVISIONED NOT_AVAILABLE_NETWORK_ONLY INCONCLUSIVE | PRIVATE GLOBAL NONE | NO YES (0.5 Credits) YES (1 Credit) |
USA Status: ("usa_status": "YES")
error | telephone_number_type | country_name | live_status | cache | Charge? |
|---|---|---|---|---|---|
NONE | BAD_FORMAT | Any | NOT_APPLICABLE | NO | |
NONE | Any except BAD_FORMAT or MOBILE | United States of America | NOT_AVAILABLE_NETWORK_ONLY | PRIVATE GLOBAL NONE | NO YES (0.5 Credits) YES (1 Credit) |
NONE | Any except BAD_FORMAT or MOBILE | Any except United States of America | NO_COVERAGE | NO | |
NONE | MOBILE | Any except United States of America | LIVE DEAD ABSENT_SUBSCRIBER NO_TELESERVICE_PROVISIONED NOT_AVAILABLE_NETWORK_ONLY INCONCLUSIVE | PRIVATE GLOBAL NONE | NO YES (0.5 Credits) YES (1 Credit) |
NONE | MOBILE | United States of America | LIVE DEAD INCONCLUSIVE | PRIVATE GLOBAL NONE | NO YES (1 Credit) YES (2 Credits) |
Further Notes:
It is possible to be charged a combination of all of the above scenarios.
For example. If you check a USA Mobile number and request the USA Status and request the Ported Date then if the number is ported to a new network and the number is a USA mobile number then you will be charged 3 credits.
HTTP 200 Response - MNP endpoint used
If you are calling our MNP endpoint instead of our HLR then this is charged at half the price of a HLR Lookup.
https://api.hlrlookup.com/apiv2/mnperror | live_status | cache | Charge? |
|---|---|---|---|
INTERNAL_ERROR | NO | ||
INSUFFICIENT_CREDIT | NO | ||
NONE | NOT_APPLICABLE or NO_COVERAGE | NO | |
NONE | NOT_AVAILABLE NETWORK_ONLY | PRIVATE GLOBAL NONE | NO YES (0.25 Credits) YES (0.5 Credits) |
Using the MNP end point the only additional parameter that could incur an extra charge is the Ported Date and will be charged as follows:
Requesting the USA Status or the Landline Status will not work using the MNP endpoint.
error | live_status | is_ported | ported_date | cache | Charge? |
|---|---|---|---|---|---|
INTERNAL_ERROR | NO | ||||
INSUFFICIENT_CREDIT | NO | ||||
NONE | NOT_APPLICABLE or NO_COVERAGE | NO | |||
NONE | NOT_AVAILABLE NETWORK_ONLY | YES | NOT_AVAILABLE Number belongs to a country where a ported date check is not available | YES (0.5 Credits) | |
NONE | NOT_AVAILABLE NETWORK_ONLY | YES | Date shown | PRIVATE GLOBAL NONE | YES (1 Credit) YES (1.25 Credits) YES (1.5 Credits) |
Note - Ported dates are not cached at any time as it's important these are up to date. Therefore it's possible to retrieve network information from the Private or Global cache and be charged a reduced rate accordingly, however ported dates will always be charged as a half credit.