Charging

v1 / v2

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


NONE


BAD_FORMAT

NOT_APPLICABLE

no other live_status available for BAD_FORMAT

NO

NONE

Any except MOBILE or BAD_FORMAT

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)

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

Number belongs to a country where a ported date check is 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

<Country identified as UK or Ireland>

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/mnp

error

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.