Messaging & SMS Billing API

Introduction #

This API describes the method calls for all Fonix Messaging.

All Fonix HTTP APIs are organized around REST.

Connection #

Calls to Fonix must be made through HTTPS.

Calls from Fonix to your servers can be made either through HTTPS or HTTP. When using HTTPS, your server certificate must be signed by a trusted certificate authority. We recommend all information transported over the web to be encryped, hence we recommend to use HTTPS.

All calls to and from Fonix are made through POST.

Authentication #

Authentication is made by providing the API key as a header in your request. The header name is X-API-KEY. Our support team will provide you with the key for you to use.

You can have multiple API keys active at any one time for multiple services with us. Your API keys carry many privileges, so be sure to keep them secret!

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.

All HTTP request to and from Fonix should be encoded in the default content type: application/x-www-form-urlencoded.

FONIX API Endpoint

#https://sonar.fonix.io/v2/
#NOTE: The underlying destination IP address for sonar.fonix.io changes over time.
#      Don't use fixed destination IPs with this domain.

#Example API Keys

# Test Key: test_BYZNk5YUBMLfowSOQTUuqq3t
# Live Key: live_WrxOqXQYwEPWVJDGgdfirZrk

#Example Request including the API key
curl -i https://sonar.fonix.io/v2/chargesms 
 -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t 
 -d ORIGINATOR=84988 
 -d NUMBERS=447111222333 
 -d BODY=Welcome%20Home

Message Referencing #

We support client-provided references for requests to us. This allows you to pass us up to 80 character of data in a field (REQUESTID) which we will provide back to you in the corresponding delivery report. More detail can be found in the parameters section under REQUESTID.

Example including requestid

curl -i https://sonar.fonix.io/v2/chargesms 
  -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t 
  -d ORIGINATOR=84988 
  -d NUMBERS=447111222333 
  -d BODY=This+MT+SMS+is+tagged 
  -d REQUESTID=F21B992Ex9257x936Ex3D2Fx7CDEB38F217C

Success and Errors #

An API call sent by you to us in this version (V2) is successful if and only if you receive a 200 OK HTTP response code in return.

Any other values in the HTTP response code indicate a failure and the request was rejected. Please do not retry the same request, as it would fail again if unchanged.

If the parameters in your request fail validation, you receive a 400 Bad Request error in response. Please check the result code in the JSON response for details of the failure.

If the key used in your request is incorrect or unauthorised, you receive a 401 Unauthorized error in response.

If your service has a maximum quota of bulk messages configured you receive a failcode: MAX_QUOTA_REACHED after that quota has been reached.

For all 400 BAD_REQUEST the failure reasons are included in the JSON response:

CHARGE SMS #

Request #

This Method call sends premium billed SMS messages to one or many phone numbers, charging the mobile phone account.

Charge SMS requests can never be concatenated. If the message body is too long, we will reject your request with "failcode": "TOO_MANY_CHARACTERS".

#CHARGE SMS request

curl -i https://sonar.fonix.io/v2/chargesms 
 -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t 
 -d ORIGINATOR=84988 
 -d NUMBERS=447111222333,447111222444 
 -d BODY=Welcome%20Home

Response #

Duplicate phone numbers in the same request are de-duped and in the response we inform you how many unique mobile phone numbers we found and which encoding we used (gsm/ucs2). We now also tell you the consumer price of the premium shortcode you originated the message from.

#CHARGE SMS response (success)
{
    "success": {
        "txguid": "7CDEB38F-4370-18FD-D7CE-329F21B99209",
        "numbers": "2",
        "encoding": "gsm",
        "price": 50
    }
}

#CHARGE SMS response (failure)
{
    "failure": {
        "parameter": "body",
        "failcode": "TOO_MANY_CHARACTERS"
    }
}

MO SMS #

Request #

Mobile originated (MO) messages are sent to your web server in an HTTPS POST request. If the user sent a long message arriving at our gateway in multiple MO SMS messages, by default we aggregate all of the messages and then send you the whole long message in a single request. This behaviour can be disabled on dedicated shortcodes upon request.

# MO SMS HTTPS POST example (to your application)
#
# POST /path/mosms HTTP/1.1
# Content‐Type: application/x-www-form‐urlencoded
# Connection: Keep-Alive
#
# IFVERSION=201001&MONUMBER=447111222333&OPERATOR=o2-uk&DESTINATION=84988
# &BODY=This%20is%20a%20mobile%20originated%20test%20message&RECEIVETIME=20130202102030
# &GUID=7CDEB38F-4370-18FD-D7CE-329F21B99209&PRICE=15

Response #

Your HTTP response code back to us should be: 200 OK

If you don’t respond with a 200, we will retry to deliver the MO message to your platform, which may cause you to interpret the retries as duplicates. We will retry to deliver the message to you for up to 24 hours.

MO BINARY #

Request #

For those cases where users manage to text in binary MO messages, we have created a dedicated MO BINARY request. The behaviour of it is similar to the MO SMS request, but to make your life easier we can direct MO BINARY requests to a separate listener on your side. There you can chose to decode and process them or just accept and ignore them.

Binary MO messages are often created unintentionally through grey-import handsets which don’t originate SMS messages in the standard way.

#MO BINARY HTTPS POST example (to your application)
#
# POST /path/mobinary HTTP/1.1
# Content‐Type: application/x-www-form‐urlencoded
# Connection: Keep-Alive
#
# IFVERSION=201001&MONUMBER=447111222333&OPERATOR=o2-uk&DESTINATION=84988
# &BINBODY=C024A3A5905E195B081180800991C6106DA620420620A22C4986166184289B526204
# F20620A28C26C49B6186289B0C3126205A04205A04D86D8608410A2D026C22C49B61
# &BINHEADER=050415810000&RECEIVETIME=20130202102030&GUID=7CDEB38F-4370-18FD-D7CE-329F21B99209

Response #

Your HTTP response code back to us should be: 200 OK

If you don’t respond with a 200 OK, we will retry to deliver the MO message to your platform, which may cause you to interpret the retries as duplicates. We will retry to deliver the message to you for up to 24 hours.

DR SMS #

Request #

Delivery reports for previously submitted MT messages are sent in an HTTPS POST request to your web server. DRs indicate either successful delivery or delivery failure. If the delivery failed, details about the failure reason are provided in the STATUSCODE and STATUSTEXT.

Delivery reports are useful to identify if the recipient of a CHARGE SMS message was successfully charged. Note: All delivered CHARGE SMS messages always mean the user was charged. However, in some cases undelivered messages are still charged.

We now also include the PRICE parameter which holds the consumer price of the premium shortcode you originated the MT message from.

When we forward your SMS request to the mobile operator, it can occasionally happen that we don’t receive an acknowledgement back from them. Our policy is not to retry the request in those cases, because the message may have been sent to the recepient handset correctly. Instead, we create a failure delivery report back to you with STATUSCODE=OPERATOR_TIMEOUT.

# DR SMS HTTPS POST example (to your application)
#
# POST /path/drsms HTTP/1.1
# Content‐Type: application/x-www-form‐urlencoded
# Connection: Keep-Alive
#
# IFVERSION=201001&OPERATOR=o2-uk&MONUMBER=447111222333&DESTINATION=84988
# &STATUSCODE=DELIVERED&STATUSTEXT=Delivered&STATUSTIME=20130202102030
# &PRICE=50&GUID=7CDEB38F-4370-18FD-D7CE-329F21B99209

Response #

Your HTTP response code back to us should be: 200 OK

If you don’t respond with a 200, we will retry to deliver the DR to your platform for up to 24 hours.

Parameters #

The following parameters are in use throughout the API:

• BODY: The body text of the message. It cannot be blank for SEND SMS and CHARGE SMS.
• NUMBERS: Contains the destination mobile numbers to which the MT SMS will be sent. The prefix 00 (as used in V1) is no longer required, however, all numbers must include the country prefix, e.g. 44 for the UK.The mobile operator code can be prefixed, i.e. NUMBERS=eeora-uk.447123456789To send the same MT SMS to multiple numbers you can separate them with commas: NUMBERS=447111122222,447333344444
  The maximum number of mobile numbers allowed in a batch is 100.
• ORIGINATOR: The message originator number or string. Note that CHARGE SMS only allows to send messages with numeric originators (short codes) that have been pre-registered with us.
• ORIGINATOR_TYPE: An optional parameter used in SEND SMS to specify the type of originator. Allowed values are:
  • alpha (default) up to 11 alphanumeric characters
  • msisdn a fully qualified mobile number

#A sample message sent from 447987654321:
 curl -i https://sonar.fonix.io/v2/sendsms 
  -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t 
  -d ORIGINATOR=447987654321 
  -d ORIGINATOR_TYPE=msisdn  
  -d NUMBERS=447111222333 
  -d BODY=Welcome%20Home

• REQUESTID: An optional field for you to store a unique string of up to 80 characters (0-9, a-z, A-Z) along with your request. If you use this field you must ensure that the value is eternally unique for your service.If you send us a new request with a previously used REQUESTID within seven days we will not process it again, but reply with the same information we used in our previous response. If you send us a request with a previously used REQUESTID after seven days, the message may be sent again, hence we recommend you should not retry requests for longer then seven days.The REQUESTID will also be passed back to you in the matching DR.
• PRICE: The consumer price of a premium MO or premium MT message in pence.
• TIMETOLIVE: Optionally sets the validity period of the MT SMS message in minutes. Once the message can no longer be delivered through retries inside this period, then a ‘Delivery Failed DR’ will be returned to you. Minimum value: 10 minutes, Maximum value: 4340 minutes, Default value: 4340 minutes.
• NORETRY: Optional, values YES/NO, default value NO. Our gateway manages the retry of premium SMS messages for those cases where the mobile network rejects the message because the recipient has insufficient funds. NORETRY=YES, suppresses the retrying at a later time (up to the end of TIMETOLIVE)
• BINHEADER: Only used with SEND BINARY SMS. Do not inlude the leading length-byte. This will be automatically added by us.
• BINBODY: Only used with SEND BINARY SMS.
• PUSHTITLE: Only used with SEND WAP PUSH. The text viewed by the recipient of the WAP push.
• PUSHLINK: Only used with SEND WAP PUSH. The target URL of the WAP push.
• ENCODING: Optional, values gsm/ucs2, default value based on BODY charset.
  Allows you to specify which encoding to use when sending the message. If set to gsm, non GSM character will be replaced by a question mark.
• DUMMY: Optional, values YES/NO, default value NO.
  Allowes you to run integration tests or check how many parts would be generated from your request. For more information on how to force DR parameters for DUMMY requests, refer to APPENDIX A.

Incoming parameters (MO and DR) #

The following information parameters appear in MO SMS, MO STOP and DR SMS only:

• IFVERSION: The API version in use.
• DESTINATION: The shortcode or long number to which the message was sent.
• MONUMBER: The mobile number of the user who sent you an MO or DR message. The format is MONUMBER=447111122222.
• OPERATOR: The mobile operator code of the user who sent you an MO or DR message.
• GUID: The unique identifier assigned by us for this message.
• RECEIVETIME: The date and time in UTC when we received the MO or DR from the mobile operator.
• DURATION: The duration in seconds it took to deliver the message or the duration it took to find out that it permanently failed to deliver.
• RETRYCOUNT: This parameter appears if a request is retried to be sent to you. It increases with every retry. The first attempt carries the value RETRYCOUNT=0.
• STATUSCODE: A code used in the DR to advise success or failure of your submitted MT request.
• STATUSTEXT: A description to provide more information about the status code.
• STATUSTIME: Timestamp when the DR was created

All DR contain a status code. The following values are defined for this:

• CHARGESTATUS: A simple true/false indicator in the DRs for CHARGE SMS indicating if the recipient was successfully charged or not. Useful for some circumstances on the Three-UK network it is possible that the message delivery failed, but the consumer was charged nevertheless.
• REQUESTID: If you submitted your MT SMS with your a unique request id, this DR field will contain it in return to help you identify the delivered message.
• PART: For DR this identifies which part of your concatenated (long) MT SMS was delivered or failed. For a concatenated (long) MO with the default behaviour disabled, this identifies which part of MO this is.
• TOTAL_PARTS: For DR this identifies how many parts you originally submitted in your concatenated (long) MT SMS. For a concatenated (long) MOwith the default behaviour disabled, this identifies how many parts there are in total.
• CSMS_REF: For a concatenated (long) MO with the default behaviour disabled, this provides a short identifier (value between 0 and 65535) which is the same for all parts. Together with the OADC, this is a near-uniqueness indicator between multiple concatenated MO messages. In V2 of this API, we will aggregate all parts and only send the whole (long) MO message to you once we receive all parts.
• AV: Adult Verification. If you receive MO messages on adult shortcodes (69xxx, 79xxx or 89xxx) then we may tell you whether the user is allowed to receive adult services or not with these values: AV=verified, AV=not_verified or AV=unknown.Adult Services must not be provided to users where the parameter is set to AV=not_verified, as in those cases the mobile operator has informed us specifically that this user is barred to receive such services.

Mobile Operator Codes #

The following list of mobile operator codes are used in this API version (V2) and all future versions:

unknown appears in cases where the MO message was sent to us via another operator or a bulk message was delivered to a user whos network we couldn’t identify.

Character Types

The following data types are in use throughout the API:

• Numeric: Characters 0-9
• Alphanumeric: Any character of UTF-8
• Hexadecimal: Characters 0-9 and a-f and A-F
• Mobile number: Characters 0-9, first character may be ‘+’
• Time: Timestamp as YYYYMMDDHHMMSS
• Version: Version as MNNBBB
• GUID: Characters 0-9 and a-f and A-F and ‘-‘
• REQUESTID: Characters 0-9 and a-z and A-Z
• Escaped Characters can be sent using UTF-8 byte notation: ? = %3F Below is a table with some of the most commonly escaped characters:

# Examples
#
# ORIGINATOR=84588
#
# BODY=Test+message
#
# BODY=C024A3A5905E195B081180800991C6106DA620420620A22C4986166184289B526204
#      F20620A28C26C49B6186289B0C3126205A04205A04D86D8608410A2D026C22C49B61
#
# NUMBERS=447111222333
#
# RECEIVETIME=20130202102030
#
# IFVERSION=201001
#
# GUID=7CDEB38F-4370-18FD-D7CE-329F21B99209

ADULT VERIFY #

Introduction #

Fonix allows clients the ability to look up the age verification status of a MSISDN. This call is used in order to validate a client is eligable to access age restricted content.

Asynchronous Request #

We ACK your request and then send the result in a separate AV REPORT to you.

• The mobile operator code must be submitted as a prefix to the MSISDN.
• The NETWORKRETRY parameter is mandatory. In most cases, please set it to NETWORKRETRY=NO
• The NUMBERS parameter can only contain one MSISDN

curl -i  https://sonar.fonix.io/v2/adultverify 
-H X-API-KEY:test_BYZNk5YUBMLfowS0QTUugg3t 
-d NUMBERS=eetmo-uk.447932111222 
-d NETWORKRETRY=NO

Asynchronous Response #

With the response we either acknowledge (ACK) or reject (NACK) your Adult Verify request.
The following parameters are returned:

Ack:

• txguid: the GUID from the original request
• numbers: the quantity of numbers sent through in the original request

Nack:

• parameter: which parameter failed the validation
• failcode: why the vaidation failed

# ACK:
 {
   "success": {
       "txguid": "7CDEB38F-4370-18FD-D7CE-329F21B99209",
       "numbers": "1"
   }
 }

# NACK:
 {
   "failure": {
       "parameter": "parameter name",
       "failcode": "FAILCODE"
   }
 }

Synchronous Request #

The response to your request will include the AV status.
If after 30 seconds we don’t get a response from the operator, we send a pending response to your call.
If you want to collect AV stauses in this cases, we can configure your service so that for each request we’ll send both a synchronous and an asynchronous response.

• The mobile operator code must be submitted as a prefix to the MSISDN.
• The NETWORKRETRY parameter is mandatory. In most cases, please set it to NETWORKRETRY=NO
• The NUMBERS parameter can only contain one MSISDN

curl -i  https://avsolo.fonix.io/v2/avsolo 
-H X-API-KEY:test_BYZNk5YUBMLfowS0QTUugg3t 
-d NUMBERS=eetmo-uk.447932111222 
-d NETWORKRETRY=NO

Synchronous Response #

With the response we either acknowledge (ACK) or reject (NACK) your Adult Verify request.
The following parameters are returned:

Ack (can be verified, not_verified, unknown or pending):

• ifversion: API version
• operator: mobile operator code of the operator from which we received the status information
• guid: the GUID from the original request

Nack:

• parameter: which parameter failed the validation
• failcode: why the vaidation failed

# ACK:
 {"verified":{
       "ifversion":"201001",
       "operator":"o2-uk",
       "guid":"f2e84610-534a-4e02-bfad-9ccbaa14e09a"
   }
 }

 {"not_verified":{
       "ifversion":"201001",
       "operator":"o2-uk",
       "guid":"f2e84610-534a-4e02-bfad-9ccbaa14e09a"
   }
 }

 {"unknown":{
       "ifversion":"201001",
       "operator":"o2-uk",
      "guid":"f2e84610-534a-4e02-bfad-9ccbaa14e09a"
   }
 }

 {"pending":{
       "ifversion":"201001",
       "operator":"o2-uk",
       "guid":"f2e84610-534a-4e02-bfad-9ccbaa14e09a"
   }
 }

# NACK:
 {
   "failure": {
       "parameter": "parameter name",
       "failcode": "FAILCODE"
   }
 }

AV REPORT #

Request #

AV Reports for previously submitted Adult Verify requests are sent in an HTTPS POST request to your web server. They indicate whether the numbers you submitted were registered with the mobile operator as adult verified or not.

# AV REPORT HTTPS POST example (to your application)
#
# POST /path/chargereport HTTP/1.1
# Content‐Type: application/x-www-form‐urlencoded
# Connection: Keep-Alive
#
# eetmo-uk.447932111222
#
# IFVERSION=201001&OPERATOR=eetmo-uk&MONUMBER=447932111222&GUID=7CDEB38F-4370-18FD-D7CE-329F21B99209&AV=VERIFIED

Response #

Your HTTP response code back to us should be: 200 OK

If you don’t respond with a 200 OK, we will retry to deliver the Charge Report to your platform for up to 24 hours.

SENDSMS #

Request #

This Method call sends SMS messages to one or many phone numbers without charging the mobile phone account.

Typically you can fit 160 characters into the body of a single message. If your body is longer then we will spread and transport it across multiple SMS in a concatenated message.

Some special characters do take twice the space then others (see GSM for more information). If the body of your message contains non GSM characters, we will encode the entire message in UCS-2 before transmitting to the operator unless you force the encoding to use in the ENCODING parameter. If you want to check if your message body fits into a single SMS message, you could submit a DUMMY request first and look out for the response containing the smsparts parameter.

curl -i https://sonar.fonix.io/v2/sendsms 
 -H X-API-KEY:live_BYZNk5YUBMLfowSOQTUuqq3t 
 -d ORIGINATOR=84988 
 -d NUMBERS=447111222333 
 -d BODY=Welcome%20Home
 -d DUMMY=yes

Response #

The response body is structured follwoing JSON.

If your request was successfully accepted by us, you’ll soon get a success response from us wich will contain our GUID reference "txguid" of your request, how many unique mobile phone "numbers" we found (Duplicate phone numbers in the same request are de-duped), how many "smsparts" your message was split over and which "encoding" we used (gsm/ucs2).

If your request failed due to an empty or incorrect parameter, we tell you which "parameter" had the issue and the "failcode" of the error.
For more information about potential errors, please check the Errors section.

#SEND SMS response (success)
{
    "success": {
        "txguid": "7CDEB38F-4370-18FD-D7CE-329F21B99209",
        "numbers": "1",
        "smsparts": "1",
        "encoding": "gsm"
    }
}

#SEND SMS response (failure)
{
    "failure": {
        "parameter": "body",
        "failcode": "IS_EMPTY"
    }
}

SEND BINARY SMS #

Request #

To send a single or multi-part binary message to a handest the message has to be encoded in a particular way. We do this for you with this call. Depending on the length of the data, the binary message will be spread and transported across multiple SMS messages. Binary SMS messages don’t charge the mobile phone account.

#SEND BINARY SMS request

curl -i https://sonar.fonix.io/v2/sendbinsms 
 -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t 
 -d ORIGINATOR=84988 
 -d NUMBERS=447111222333,447111222444 
 -d BINBODY=C024A3A5905E195B081180800991C6106DA620420620A22C4986166184289B526204 
      F20620A28C26C49B6186289B0C3126205A04205A04D86D8608410A2D026C22C49B615905E1 
      95B081180800991C6106DA62042028C26C49B6186289B0E195B0811808009928C26C4910A2 
 -d BINHEADER=050415810000

Response #

Duplicate phone numbers in the same request are de-duped and in the response we inform you how many unique mobile phone numbers we found.

We also tell you how many SMS parts your message was split over.

#SEND BINARY SMS response (success)
{
    "success": {
        "txguid": "7CDEB38F-4370-18FD-D7CE-329F21B99209",
        "numbers": "2",
        "smsparts" "2"
    }
}

#SEND BINARY SMS response (failure)
{
    "failure": {
        "parameter": "originator",
        "failcode": "INVALID_CHARACTERS"
    }
}

SEND WAP PUSH #

Request #

To send a WAP push message to a handest the message has to be encoded in a particular way. We do this for you with this call. Depending on the length of the information in the link, the WAP push message will be spread and transported across multiple SMS messages. WAP push messages don’t charge the mobile phone account.

#SEND WAP PUSH request

curl -i https://sonar.fonix.io/v2/sendwappush 
 -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t 
 -d ORIGINATOR=84988 
 -d NUMBERS=447111222333,447111222444 
 -d PUSHTITLE=Welcome%20Home 
 -d PUSHLINK=http://www.google.com

Response #

Duplicate phone numbers in the same request are de-duped and in the response we inform you how many unique mobile phone numbers we found.

We also tell you how many SMS parts your message was split over.

#SEND WAP PUSH response (success)
{
    "success": {
        "txguid": "7CDEB38F-4370-18FD-D7CE-329F21B99209",
        "numbers": "1",
        "smsparts" "1"
    }
}

#SEND WAP PUSH response (failure)
{
    "failure": {
        "parameter": "body",
        "failcode": "IS_EMPTY"
    }
}

Example Messages #

MT billed example #

A billed text message to two O2 numbers 447111222333 and 447111222444, with the body text of “Welcome Home” originating from 84988.

curl -i https://sonar.fonix.io/v2/chargesms 
 -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t 
 -d NUMBERS=447111222333,447111222444 
 -d BODY=Welcome%20Home 
 -d ORIGINATOR=84988

Binary MT example #

A free text message to 447111222333 containing binary content and originating from HELLO.

curl -i https://sonar.fonix.io/v2/binarysms 
 -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t 
 -d REQUESTTYPE=5 
 -d NUMBERS=447111222333 
 -d BINHEADER=050415810000 
 -d BINBODY=024A3A5905E195[...]361B6182000 
 -d ORIGINATOR=HELLO

Concatenated MT example #

A free text message to 447111222333 with a poem of 242 characters and originating from POETRY. The message will be transmitted through two separate MT SMS messages and then re-assembled on the handset.

curl -i https://sonar.fonix.io/v2/sendsms 
 -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t 
 -d REQUESTTYPE=19 
 -d NUMBERS=447111222333 
 -d BODY=Why+were+you+born+when+the+snow+was+falling%3F+ 
 You+should+have+come+to+the+cuckoo%27s+calling+Or+when+ 
 grapes+are+green+in+the+cluster%2C+Or%2C+at+least%2C+ 
 when+lithe+swallows+muster+For+their+far+off+flying+ 
 From+summer+dying.+%28Christina+Rossetti%2C+1865%29 
 -d ORIGINATOR=POETRY

OPERATOR LOOKUP #

Request #

The HLR/Operator lookup call provides the network and country for a particular MSISND submitted. This call has international coverage and will take the MSISDN for all major mobile networks in all countries.

By submitting a MSISDN this function will return the associated country and operator for the specified MSISDN.

The method call is synchronous, i.e. we directly reply with the requested information to you in the HTTP response.

# Example API Request including the API key
  curl -i  http://sonar.fonix.io/v2/operator_lookup?NUMBER=447932111222 
  -H X-API-KEY:test_BYZNk5YUBMLfowS0QTUugg3t

Response #

The HTTP response provides the following information to the user:

• mcc: mobile country code
• mnc: mobile network code
• operator: The mobile operator

   {
   "success":
       {"mcc":"234",
         "mnc":"15",
         "operator":"voda-uk"}
   }

Parameters #

The following parameters are in use throughout the API:

• NUMBERS: Contains one and only one mobile numbers for which the information is requested. The mobile operator code must be prefixed for the ADULT VERIFY call, i.e. NUMBERS=eeora-uk.447123456789
• ENCRYPTEDNUMBER: Contains one and only one encrypted mobile number. This is a long hash value you may receive from us via Fpay where the mobile number has to remain anonyous but you still require information about the adult verification status. Please note: The entire hash value should be used, including any %2F and %3D characters contained in the string.
• IFVERSION: The API version in use.
• AV: The adult verification status. This can be either VERIFIED, NOT_VERIFIED or UNKNOWN
• GUID: The unique identifier assigned by us for this request.
• NETWORKRETRY: This parameter controls our fail-over checking behaviour. If set to YES, then we check for AV status on other networks as well as the one specified. This can lead to unexpected results as Vodafone could flag a mobile number ported to a different network as VERIFIED, when in reality it is not verified. Therefore please specify NETWORKRETRY=NO for all requests.

# Example ENCRYPTEDMSISDN:
#   pcRBEbPss0xfscq6XLoWNA8ULssQL4UuM9eGdSkmGdcfUO%2Fu0koOav04GPDxb0yjAufzOyMuvi98JFCEMiHw3vkvIyFVmMpNciKWLLU9k1U%3D

KYC API #

Introduction #

The Fonix KYC API allows merchants to validate the customer’s personal data associated to a MSISDN.

# REQUEST:
curl -i https://kycsolo.fonix.io/v2/kyc 
-H X-API-KEY:SERVICE_API_KEY  
-d NUMBER=447400000000 
-d NAME=TestName 
-d SURNAME=TestSurname 
-d HOUSE_NUMBER=1 
-d POSTCODE=TESTPOSTCODE 
-d DOB=13-01-1900
-d REQUESTID=requestid1 
-d DUMMY=YES

# RESPONSE
{
   "completed":{
       "ifversion":"201001",
       "statuscode":"OK",
       "statustext":"Successfully checked",
       "guid":"r-1-requestid1",
       "requestid":"requestid1",
       "status_time":"20210608140636",
       "first_name_match":true,
       "last_name_match":true,
       "full_name_match":true,
       "postcode_match":true,
       "house_match":true,
       "full_address_match":true,
       "birthday_match":true,
       "is_stolen":false,
       "contract_type":"PAYG"
   }
 }

Call Details #

Request Parameters #

All the parameters marked with * are mandatory.

• REQUESTID *: string of up to 50 characters (0-9, a-z, A-Z) used to identfy a request that must be eternally unique for your service.For 7 days any subsequent request with the same REQUESTID and customer details will not be forwarded to the Networks and a response with the result of the first request would be returned instead.

• NUMBER *: The mobile number of the customer in international format, i.e. NUMBER=447400000000 for the UK.
• NAME *: First name (varchar 255).
• SURNAME *: Surname (varchar 255).
• POSTCODE *: Postcode of the customer’s billing address (varchar 255).
• DOB *: Date of Birthday with format DD-MM-YYYY.
• HOUSE_NUMBER: House Number (varchar 255).
• HOUSE_NAME: House Name (varchar 255).
• DUMMY: Optional, values YES/NO, default value NO.

Response #

The KYC response is in JSON format.
If any of the parameters fail the validation a failure response with the offending parameter and a failcode is returned.
I.e. {"failure":{"parameter":"DOB","failcode":"INVALID"}}

If more than MAX CONCURRENT REQUESTS are sent at the same time a failure response with status code WINDOW_EXCEEDED is returned.
I.e. {"failure":{"ifversion":"201001","statuscode":"WINDOW_EXCEEDED","statustext":"Too many requests made to the server in parallel"}}

If the request takes more than 70 seconds to be processed a pending response is returned.
I.e. {"pending":{"ifversion":"201001","statuscode":"PENDING","statustext":"The request is still processing","guid":"r-1-test","requestid":"test"}}

To have access to the API, each case must be approved by the mobile operators.
The API will only be available for approved services. Each service has to be allowed access to the API, if the service has not been set to allow access to the API, you will get the following response:
{"failure":{"parameter":"METHOD","failcode":"NOT_AUTHORIZED"}}
Please contact us to request access to the KYC API.

Every time a request is processed and there is a final status, a completed response is returned (HTTP status code 200).

# COMPLETED RESPONSE EXAMPLE

 {
   "completed":{
       "ifversion":"201001",
       "statuscode":"OK",
       "statustext":"Successfully checked",
       "guid":"r-1-requestid",
       "requestid":"requestid",
       "status_time":"202106081801213",
       "first_name_match":true,
       "last_name_match":false,
       "full_name_match":false,
       "postcode_match":true,
       "house_match":"unknown",
       "full_address_match":"unknown",
       "birthday_match":true,
       "is_stolen":false,
       "contract_type":"PAYM"
   }
 }

Response Parameters #

All the fields ending in _match and is_stolen can have three possible values: true, false or “unknown”.
They will be set to “unknown” if the MNO doesn’t have the information to perform the check, true or false if the information held by the operator matches or not the one passed in the request.

• ifversion : Fonix API VERSION.
• statuscode : Code used to report the status of the request.
• statustext : A short description associated to the statuscode.
• guid : Unique identifier at Fonix’s side build from the REQUESTID
• requestid : The REQUESTID sent in the request
• status_time : Date and time when the request reached the final status (YYYYMMDDHHMMSS).
• first_name_match : Possible values (true|false|”unknown”).
• last_name_match : Possible values (true|false|”unknown”).
• full_name_match : Possible values (true|false|”unknown”).
• postcode_match : Possible values (true|false|”unknown”).
• house_match : Possible values (true|false|”unknown”).
• full_address_match : Possible values (true|false|”unknown”).
• birthday_match : Possible values (true|false|”unknown”).
• is_stolen : Possible values (true|false|”unknown”).
• contract_type : Possible values (“PAYG”|”PAYM”|”Business”|”unknown”).

Parameters Validation Failures #

When one or more parameters don’t pass the validation Fonix KYC API returns a failure response in the format {"failure":{"parameter":"DOB","failcode":"INVALID"}}.
The parameter field will specify the name of the passed parameter that didn’t pass the validation.
The failcode field will be set to one of the following codes:

Statuscodes #

SMPP API #

Introduction #

The Fonix SMPP API is closely aligned with the Short Message Peer to Peer Protocol Specification v3.4 (SMPP). We only made a few modifications to enrich the information we exchange with your platform.

Connection #

In SMPP connections are made by your client to our server for both sending MT messages and picking up MO and DR messages.

SMPP is transported via TCP and Fonix uses the following ports to connect:

• 5443 for SSL encrypted connections. We serve a duly signed certificate on this connection to authenticate our SMPP server’s identity. We strongly encourage all our SMPP clients to use SSL connections to secure your SMS messages during transport.
• 5000 for unencrypted connections

We support TRANSMITTER, RECEIVER and TRANSCEIVER binds. We can provide you with multiple sessions (binds) for your connection.

Authentication #

Authentication in SMPP is made through custom credentials which we provide to you separately.

Versioning #

We only support SMPP V3.4 (Document Version:- 12-Oct-1999 Issue 1.2)

Flow Control #

The SMPP protocol is very efficient in data transport and also supports asynchronous transport where multiple requests can be issued without waiting. Requests are acknowledged in a skew order by the other end. The number of unacknowledged requests is called a window and the maximum size set by the sending party is called window size.

We support a receiving window size for MT messages of 100. Any unacknowledged requests above this level will be rejected with the RTHROTTLED error code.

Our default sending window size for MO and DR messages is 30, but can be configured to suit your needs.

Custom TLV parameters #

To transport additional information not covered in the standard scope of SMPP we utilise custom defined Tag Length Value (TLV) parameters. Currently the following parameters are defined

NOTE: The message GUID assigned by Fonix is transported in different tags to you for different message types:

• sonar_guid (TLV 0x1620) for MO messages sent to you
• message_id (defined in SMPP V3.4) for ACKs to your MT requests
• receipted_message_id (defined in (SMPP V3.4) for DR messages sent to you

NOTE: The TLV paramters should be formated as c-var-octet strings and be null terminated. For example the TLV to tell us that your MT message should go to Vodafone would be 16000008766f64612d756b00.

NOTE: Please don’t send the sonar_guid, av or price tags to us in your MT request. We just ignore those values in message processing.

# Example c-var-octet strings for the operator TLV field:
#   1600000974687265652d756b00   = three-uk
#   160000096565746d6f2d756b00   = eetmo-uk
#   1600000965656f72612d756b00   = eeora-uk
#   16000008766f64612d756b00     = voda-uk 
#   160000066f322d756b00         = o2-uk 
#   1600000a76697267696e2d756b00 = virgin-uk

Sending Premium and Bulk SMS #

Our API accepts both bulk and premium SMS through the same connection. MT Premium and MT Bulk are distinguished through the TON and NPI properties of the originator. Setting the right TON and NPI is very important to avoid unintentionally billing or not billing a user.

Here are the settings to use:

To send a premium message, the originator can only ever be a shortcode. To send a bulk message, the originator can be any string of alphanumeric characters or a fully formatted phone number.

# Extract for premium SMS:
#   {source_addr,"84988"}
#   {source_addr_ton,3},
#   {source_addr_npi,9},

# Extract for bulk SMS:
#   {source_addr,"Fonix"}
#   {source_addr_ton,5},
#   {source_addr_npi,0},

# Extract for bulk SMS from MSISDN:
#   {source_addr,"447987654321"}
#   {source_addr_ton,1},
#   {source_addr_npi,1},

Sending parameters (MT) #

Here is some guidance on the specific use of SMPP parameters to compose your MT messages:

• destination_addr: Contains the MSISDN destination mobile number to which the MT SMS will be sent in the format 447111222333.
• source_addr: Contains the originator from which the MT SMS will appear.
• short_message: The body text of the message must be encoded in either UTF-8, UTF-16 or Binary depending on the value specified in data_coding.
• data_coding: The type of character encoding used in short_message:
  • {data_coding,0}: UTF-8
  • {data_coding,8}: UTF-16
  • {data_coding,4}: Binary
• validity_period: Optionally sets the validity period of the MT SMS message in minutes. Once the message can no longer be delivered through retries inside this period, then a ‘Delivery Failed DR’ will be returned to you. Minimum value: 10 minutes, Maximum value: 4320 minutes, Default value: 4320 minutes.
• esm_class: The esm_class is typically 0, but can be set to 0x40 to indicate a user data header in the message
• sm_default_msg_id: should be set to 0
• replace_if_present_flag: should be set to 0
• registered_delivery: should be set to 1
• priority_flag: should be set to 0
• protocol_id: should be set to 0
• dest_addr_npi: should be set to 1
• dest_addr_ton: should be set to 1
• schedule_delivery_time: should be empty
• service_type: should be empty

#SUBMIT_SM MT message example:
#  [{short_message,"hello world"},
#  {sm_default_msg_id,0},
#  {data_coding,0},
#  {replace_if_present_flag,0},
#  {registered_delivery,1},
#  {validity_period,""},
#  {schedule_delivery_time,""},
#  {priority_flag,0},
#  {protocol_id,0},
#  {esm_class,0},
#  {destination_addr,"447111222333"},
#  {dest_addr_npi,1},
#  {dest_addr_ton,1},
#  {source_addr,"12345"},
#  {source_addr_npi,0},
#  {source_addr_ton,5},
#  {service_type,""}]

Incoming parameters (MO and DR) #

The short_message parameter of MO messages is encoded in UTF-8 or (very rarely) in UTF-16 depending on how we receive the message from the handset. MO messages with Binary encoding are discarded.

Concatenated (long) MO messages can be assembled by Fonix and then transmitted as one long message using the message_payload parameter (you need to let us know to enable this). If the message_payload parameter is used, then the short_message parameter will be empty (sm_length=0).

Please also note the custom TLV parameters included in MO messages.

If you receive MO messages on adult shortcodes (69xxx, 79xxx or 89xxx) then we may tell you whether the user is allowed to receive adult services or not with these values: {av,"verified"} or {av,"not_verified"} or {av,"unknown"}.

#DELIVER_SM MO message example:
#  [{short_message,"Hello"},
#  {sm_default_msg_id,0},
#  {data_coding,0},
#  {replace_if_present_flag,0},
#  {registered_delivery,0},
#  {validity_period,[]},
#  {schedule_delivery_time,[]},
#  {priority_flag,0},
#  {protocol_id,0},
#  {esm_class,0},
#  {destination_addr,"71234"},
#  {dest_addr_npi,9},
#  {dest_addr_ton,3},
#  {source_addr,"447111222333"},
#  {source_addr_npi,1},
#  {source_addr_ton,1},
#  {service_type,[]},
#  {sonar_guid,"e9e26d88-029d-4464-a5fa-b221e71a7159"},
#  {connection,"o2-uk"}]

#DELIVER_SM Concatenated (long) MO message example (if enabled):
#  [{short_message,[]},
#  {sm_default_msg_id,0},
#  {data_coding,0},
#  {replace_if_present_flag,0},
#  {registered_delivery,0},
#  {validity_period,[]},
#  {schedule_delivery_time,[]},
#  {priority_flag,0},
#  {protocol_id,0},
#  {esm_class,0},
#  {destination_addr,"71234"},
#  {dest_addr_npi,9},
#  {dest_addr_ton,3},
#  {source_addr,"447111222333"},
#  {source_addr_npi,1},
#  {source_addr_ton,1},
#  {service_type,[]},
#  {sonar_guid,"0e1d4e59-7915-4ebf-852c-12d1b71db974"},
#  {connection,"o2-uk"},
#  {message_payload,"Why were you born when the snow was falling? 
#  You should have come to the cuckoo's calling, 
#  Or when grapes are green in the cluster, 
#  Or, at least, when lithe swallows muster 
#  For their far off flying From summer dying."}]

The short_message parameter of DR messages is always encoded in UTF-8 and contains the following structure:

id:GUID sub:001 dlvrd:001 submit date:YYMMDDhhmm done date:YYMMDDhhmm stat:STATUS err:ERR text:TEXT

• stat contains the delivery status of the corresponding MT message. Allowed values are:
  • stat:DELIVRD
  • stat:UNDELIV
  • stat:DELETED
  • stat:EXPIRED
  • stat:UNKNOWN

  The corresponding MT message is successfully delivered only if stat:DELIVRD

• err can be a positive or negative number or an alphanumeric string. It will not contain spaces.
• text contains the first twenty characters of the corresponding mt message (Empty if the MT message was a binary).

#DELIVER_SM DR message example:
#  [{short_message,"id:5822fcc6-6da6-4107-90da-33f00cefa12d sub:001
#  dlvrd:001 submit date: 1403181055 done date:1403181055 stat:DELIVRD
#  err:000 text:hello world"},
#  {data_coding,0},
#  {esm_class,4},
#  {source_addr_ton,1},
#  {source_addr_npi,1},
#  {source_addr,"447111222333"},
#  {destination_addr,"12345"},
#  {dest_addr_npi,0},
#  {dest_addr_ton,5},
#  {protocol_id,0},
#  {service_type,""},
#  {priority_flag,0},
#  {schedule_delivery_time,""},
#  {replace_if_present,0},
#  {sm_default_message_id,0},
#  {validity_period,""},
#  {receipted_message_id,"5822fcc6-6da6-4107-90da-33f00cefa12d"},
#  {connection,"o2-uk"}]

Increasingly consumers send MO messages longer then 160 chracters, which are then concatenated by the handset and sent in message parts to our gateway. At Fonix, we have developed a mechanism to aggregate all message parts and send them to you in one long MO message we originate

We concatenate a maximum of 20 message parts into one long MO message.

Mobile Operator Codes #

The following list of values are used in the connection parameter:

APPENDIX A #

Every requests supports a DUMMY parameter that allows you to send test requests to our system.
If you send requests with a TEST API Key (i.e. an API key starting with test_) then you can omit the DUMMY parameter but your requests will still be handled as DUMMY.

DUMMY requests are not forwarded to the Mobile Operators.

DUMMY requests allow you to test our interface. We advise to do full end to end tests before creating a new live service.

The response sent to a DUMMY request depends on the MSISDN you submit in the request. Below you can find more details for each type of request together with related examples.

In each type of request OPERATOR will be set basing on the first 4 digit of the MSISDN according to the following table:

For any other msisdn prefix it will be set basing on a number ranges lookup.

DUMMY SMS Requests & WAP PUSH #

# SEND SMS request
curl -i https://sonar.fonix.io/v2/sendsms 
 -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t 
 -d ORIGINATOR=84988 
 -d NUMBERS=440200000001 
 -d BODY=Welcome%20Home

# SEND SMS response
# {"success":{"txguid":"0ec3c023-21fb-4d2c-a942-18e1ab17815a",
#  "numbers":"1","smsparts":"1","encoding":"gsm"}}

# DR SMS HTTPS POST example (to your application)
#
# POST /path/drsms HTTP/1.1
# Content‐Type: application/x-www-form‐urlencoded
# Connection: Keep-Alive
#
# IFVERSION=201001&OPERATOR=eetmo-uk&RETRYCOUNT=0&MONUMBER=440200000001
# &DESTINATION=84988&STATUSTIME=20160301114836&STATUSTEXT=OK
# &STATUSCODE=DELIVERED&CHARGESTATUS=false
# &GUID=0ec3c023-21fb-4d2c-a942-18e1ab17815a&PRICE=10&DURATION=0

# CHARGE SMS request
curl -i https://sonar.fonix.io/v2/chargesms 
 -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t 
 -d ORIGINATOR=84988 
 -d NUMBERS=440200000004 
 -d BODY=Welcome%20Home

# CHARGE SMS response
# {"success":{"txguid":"680f3176-cd7e-484d-aef9-7c46e95187ef",
#  "numbers":"1","smsparts":"1","encoding":"gsm","price":10}}

# DR SMS HTTPS POST example (to your application)
#
# POST /path/drsms HTTP/1.1
# Content‐Type: application/x-www-form‐urlencoded
# Connection: Keep-Alive
#
# IFVERSION=201001&OPERATOR=eetmo-uk&RETRYCOUNT=0&MONUMBER=440200000004
# &DESTINATION=84988&STATUSTIME=20160301110820
# &STATUSTEXT=Operator+System+Error&STATUSCODE=SMSC_ERROR
# &CHARGESTATUS=false&GUID=680f3176-cd7e-484d-aef9-7c46e95187ef
# &PRICE=10&DURATION=0

When submitting a valid DUMMY SMS or WAP request the system generates a response and a DR without submitting the request to network operators. You will get an error in the response if one ore more parameters are not valid.

We don’t perform duplicate checks on DUMMY requests and we try to deliver DRs only once.

You can force the OPERATOR, CHARGESTATUS (only for CHARGE SMS requests), STATUSCODE and STATUSTEXT of the DR that we’ll send back to you through the NUMBERS parameter that you pass in the request to us.

OPERATOR will be set by the first 4 digit of the MSISDN according to the above table.

CHARGESTATUS, STATUSCODE and STATUSTEXT can be controlled using the last 8 digit of the MSISDN:

DUMMY ADULT VERIFY #

# Sync Request
curl -i  https://avsolo.fonix.io/v2/avsolo 
-H X-API-KEY:test_BYZNk5YUBMLfowS0QTUugg3t 
-d NUMBERS=eetmo-uk.440000000001 
-d NETWORKRETRY=YES

# Sync Response
# {"verified":{"ifversion":"201001","operator":"o2-uk",
#  "guid":"5917d9ad-8c13-42a2-8a42-fd1d65cf2728"}}

# Sync Request
curl -i  https://avsolo.fonix.io/v2/avsolo 
-H X-API-KEY:test_BYZNk5YUBMLfowS0QTUugg3t 
-d NUMBERS=eetmo-uk.440000000001 
-d NETWORKRETRY=NO

# Sync Response
# {"unknown":{"ifversion":"201001","operator":"eetmo-uk",
#  "guid":"938323a6-5147-43e7-b552-247ca9e62108"}}

# Async Request
curl -i  https://sonar.fonix.io/v2/adultverify 
-H X-API-KEY:test_BYZNk5YUBMLfowS0QTUugg3t 
-d NUMBERS=three-uk.440100000002 
-d NETWORKRETRY=YES

# Async Response
# {"success":{"txguid":"3f8b527c-e27a-4a56-9cab-b3bb3ff7b885",
#  "numbers":"1"}}

# AV REPORT HTTPS POST (to your application)
#
# POST /path/chargereport HTTP/1.1
# Content‐Type: application/x-www-form‐urlencoded
# Connection: Keep-Alive
#
# IFVERSION=201001&OPERATOR=voda-uk&GUID=3f8b527c-e27a-4a56-9cab-b3bb3ff7b885&AV=NOT_VERIFIED

DUMMY requests can be sent to both synchronous and asynchronous APIs.

The synchronous response and the AV report depend on the MSISDN submitted.

OPERATOR will be set by the first 4 digit of the MSISDN according to the above table.

The AV status is fixed based on the last 8 digit of the MSISDN submitted according to the following table.

If NETWORKRETRY=NO and the operator submitted doesn’t match the one set by the first 4 digit of the submitted MSISDN then the AV status will always be unknown.

DUMMY OPERATOR LOOKUP #

# Request
  curl -i http://sonar.fonix.io/v2/operator_lookup?NUMBER=440500000002 
  -H X-API-KEY:test_BYZNk5YUBMLfowS0QTUugg3t

# Response
{
   "success":
       {"mcc":"234",
         "mnc":"20",
         "operator":"three-uk"}
   }

DUMMY requests receive responses depending on the MSISDN submitted. OPERATOR is set based on the first 4 digit of the MSISDN according to the above table.

Document Version #

v2.9