Account  |   Register  |   Pricing  |   Asterisk  |   HTTP API   |   ENUM   |   Code  |   Batch Client   |   Networks  |   Status  |   About  |   Contact

Number Portability Lookup HLR ENUM API

Introduction to the ENUM API

    Our ENUM (DNS) API allows you to integrate our number portability lookup service into a wider range of applications and services using a standard ENUM/NAPTR protocol.

    We also have an HTTP API which may be better suited to web applications.

Connectivity to the service

    Connectivity to the API is provided by via a TXT or NAPTR query to the following server: (port 53)

Performing an HLR Lookup with username and password

    In order to perform an HLR query on a mobile numbers, send the mobile number (reversed dotted) followed by your username, password, and finally the .hlr suffix

    Example Request:

    To HLR query +447784123456 as a TXT record if your username is "user" and your password is "pass":

    dig TXT

    or if you need a NAPTR formatted response:

    dig NAPTR

Custom Authentication

    If your service does not support sending the username and password as part of your query, contact us to request a custom port on our server. We'll need to know the IP addresses you'll be connecting from, and your account manager will provide you a port number to use.

    Your lookup request will then simply contain the reverse-dotted MSISDN nubmer and the .hlr suffix. Your username and password will no longer be part of the query. Any queries made on your custom port will be counted against your account balance as if your username and password had been supplied, so it will be locked to the IP addresses you specify for security of your account.

    Example Request with Custom Authentication enabled:

    To lookup +447784123456 if you were assigned custom port 53049:

    dig -p 53049 TXT

    or for NAPTR:

    dig -p 53049 NAPTR

Number Formatting

    Numbers should be specified in the standard E.164 international format. i.e. Country Code, and National Significant Number without National prefixing if any exist. The leading '+' symbol is not required by our service.

    For use with the ENUM service the number is reversed and dotted, eg 447784123456 becomes

Response Format

    The response is sent as a TXT record (or NAPTR, depending on your request), with the HLR response represented as data parameters in key=value pairs separated by semi-colons.

    Example Response: 60 IN TXT "status=OK\;mcc=234\;mnc=15\;imsi=23415\;

    (or if you requested NAPTR): 60 IN	NAPTR	10 100 "u" "E2U+pstn:tel" 
      "!^(.*)$!tel:\\1\;status=OK\;mcc=234\;mnc=15\;imsi=23415\;msc=447785\;!" .

Errors which could prevent your HLR lookup being run

    If there is a problem that prevents our system from running your HLR lookup the status parameter will indicate ERR and you'll receive one of these errors strings in the error parameter:

    FAIL Invalid password
    FAIL Insufficient credit
    FAIL No numbers specified
    FAIL Request too long

    Example Error Response 60 IN TXT "status=ERR\;error=FAIL Invalid password\;"

    or the same as a NAPTR record: 60 IN NAPTR	10 100 "u" "E2U+pstn:tel" 
      "!^(.*)$!tel:\\1\;status=ERR\;error=FAIL Invalid password\;!" .

Error messages from the remote HLR

    If your lookup was transmitted successfully over SS7 but received an error response from the remote HLR, the error response will be formatted as "ERR" and the GSM cause code, as follows:

    CodeMessageDescription / Possible Cause
    ERR1Unknown Subscriber there is no directory number for the mobile subscriber (GSM 09.02)
    ERR5Unidentified Subscriber MAP response from MSC/VLR returned a negative response (GSM 03.07)
    ERR6Absent Subscriber (SM) IMSI record is marked as detached (GSM 09.02), or MS is subject to roaming restrictions (GSM 09.02)
    ERR9Illegal Subscriber mobile station failed authentication
    ERR11Teleservice Not Provisioned the recipient mobile station has no SMS subscription (GSM 09.02)
    ERR12Illegal Equipment mobile station was black-listed
    ERR13Call Barred rejected due to barring of the mobile station (see GSM 09.02, description of the Barring supplementary service, GSM 02.04 and 03.11, and description of Operator Determined Barring, GSM 02.41 and 03.15).
    ERR21Facility not SupportedSMS is not provisioned in the VPLMN (GSM 09.02).
    ERR27Absent Subscriber VLR has no IMSI record, or if the record is marked "Subscriber Data Not Confirmed by HLR" (GSM 03.07)
    ERR31Subscriber Busy for MT SMS rejected because of congestion encountered at the remote MSC
    ERR33Message Waiting List Full rejected because the mobile station is out of storage
    ERR36Lookup Failure network or protocol failure, or invalid numbering plan prefix

    Example Error Response 60 IN TXT "status=ERR\;error=ERR1\;"
    This error indicates that the number queried was not a known number (unknown subscriber)

Description of data fields contained in response

    GSM / Worldwide HLR Query Response fields:

    • status - OK or ERR
    • error - error detail if status is ERROR
    • msisdn - the number queried
    • mcc - the mobile country code of this subscriber's network operator
    • mnc - the mobile network code of this subscriber's network operator
    • imsi - the subscriber's international mobile subscriber id
    • msc - the prefix (up to 5 digits)of the serving mobile switching centre

      The MSC prefix is only returned if requested if enabled by default on yoru account. Your account manager can update this setting for you. Adding the serving MSC address prefix to your HLR request will incease the cost to 1.2 credits for that HLR query. Be aware that we will only return the prefix of the MSC (up to 5 digits) and not the full MSC address in order to reduce the possibility of clients engaging in messaging fraud, and this is not negotiable.

    North American Number Lookup Response fields:

    • msisdn - the number queried
    • ocn - the carrier's OCN Code
    • carrier - the carrier's name
    • numbertype - the type of number (eg MOBILE, PCS, WIRELESS) for mobile, (LANDLINE, CLEC, RBOC) for landline

Checking your account balance

    To query the balance of your account change the .hlr suffix on your request to .balance

    The response will give your remaining account balance in the balance parameter.

    This balance is the number of HLR lookups that can be performed before your account balance is exhausted.

    Example Request:

    dig user.pass.balance TXT

    Example Response

    user.pass.balance. 60	IN	TXT	"status=OK\;balance=994506\;"

For Further Assistance

    For further assistance with the API, please [ Contact us ]

    For an instant-setup account to try our API - [ click here ]

Usage of this API implies agreement with our terms and conditions for use [ View Terms]

© 2016 Comcetera Ltd. is a product of Comcetera™ Ltd
Comcetera Ltd is Registered in England, Company 6058188 at Unit 13 Freeland Business Park, Poole BH16 6FH.