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.

Interface
YOU <–{MO – HTTPS:POST or HTTP:POST}— FONIX
YOU ———{MT – HTTPS:POST}———> FONIX
YOU <–{DR – HTTPS:POST or HTTP:POST}— FONIX

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.

HTTP CODE Description
200 OK – Everything worked as expected.
400 BAD_REQUEST – Check the response body for details.
403 NOT_AUTHORORIZED – No valid API key provided.
500 INTERNAL_SERVER_ERROR – An unexpected error occured at the FONIX platform

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

failcode Description
OUT_OF_RANGE A request parameter value can’t be accepted
IS_EMPTY A mandatory request parameter is empty
TOO_MANY_NUMBERS Too many numbers. Max 100
INVALID_NUMBER Number is incorretly formatted
TOO_MANY_CHARACTERS A request parameter is too long
INVALID_CHARACTERS A request parameter has invalid chars
MAX_QUOTA_REACHED Contact us to reset your quota

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.

Your HTTP response codes Description
200 You have accepted the MO message
4xx, 5xx You have not accepted the MO message. Fonix retries

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.

Your HTTP response codes Description
200 You have accepted the MO message
4xx, 5xx You have not accepted the MO message. Fonix retries

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.

Your HTTP response codes Description
200 You have accepted the MO message.
4xx, 5xx You have not accepted the MO message. Fonix retries.

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 gms, 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:

DR status codes Description
DELIVERED (MT message successfully delivered)
INSUFFICIENT_FUNDS (User didn’t have enough money)
INVALID_MSISDN (Mobile number not accepted by operator)
INVALID_OPERATOR_SERVICE (Request type not accepted by operator)
INVALID_ORIGINATOR (Originator not accepted by operator)
MAX_SPEND_MSISDN (Daily user spend limit exceeded)
OPERATOR_REJECTED (Request not accepted by operator)
OPERATOR_TIMEOUT (Request not acknowledged by operator)
PERMANENT_OPERATOR_ERROR (Request permanently failed by operator)
PERMANENTLY_BARRED (User is permanently barred from request type)
SMSC_ERROR (Operator SMSC encountered a processing error)
TEMPORARY_BARRED (User is temprorarely barred from request type)
TEMPORARY_OPERATOR_ERROR (Request temprorarely failed by operator)
UNKNOWN_MSISDN (Mobile number not known to operator)
UNREACHABLE_MSISDN (User mobile is switched off or absent)
UNROUTABLE (We can’t process the request due to a missing route)
UNKNOWN_ERROR (Something went wrong, – the request failed)
  • 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:

Operator Code Operator
three-uk Three UK
eeora-uk EE (Orange) UK
eetmo-uk EE (T-Mobile) UK
voda-uk Vodafone UK
o2-uk O2 UK
virgin-uk Virgin Media UK
unknown Operator unknown

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:
Character Encoding
£ %C2%A3
%E2%82%AC
space %20
? %3F
+ %2B
& %26
/ %2F
|%5C
= %3D
# 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 #

URL https://kycsolo.fonix.io/v2/kyc
METHOD POST
TYPE Synchronous
MAX Concurrent Requests 5
MAX Response Time 70 seconds

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:

FAILCODE DESCRIPTION
INVALID generic format check failure
INVALID_CHARACTERS one or more characters in the parameter value are not accepted
IS_EMPTY a mandatory parameter has not been sent or sent as empty
TOO_MANY_CHARACTERS string over the maximum allowed length
OUT_OF_RANGE unexpected value for multi value field
COUNTRY_NOT_SUPPORTED when the country the msisdn belongs to is not supported

Statuscodes #

STATUSCODE STATUSTEXT Note
OK Successfully checked The request was checked with the provider
WINDOW_EXCEEDED Too many requests made to the server in parallel
PENDING The request is still processing
DUPLICATE_REQUEST_ID Duplicate Request Id with different parameters, discarded
SERVICE_UNREACHABLE Service Unreachable Issue starting the connection with the provider
REQUEST_TIMEOUT Request might be processed The request was sent to the provider but no response was received
SENDING_ERROR Temporary Sending Error Connectivity issues with the provider
REQUEST_FAILURE Operator Error Invalid provider response
UNKNOWN_MSISDN Mobile number not known to operator
INVALID_MSISDN Mobile number not accepted by operator
TEMPORARY_OPERATOR_ERROR Request temporarily failed by operator
OPERATOR_NOT_AUTHORISED Operator access not authorised
OPTED_OUT_SUBSCRIBER Subscriber opted out of service
UNREGISTERED_USER Subscriber is unregistered prepay
USER_DATA_UNAVAILABLE Subscriber data unavailable
OPERATOR_NOT_SUPPORTED Service not available for MNO or MVNO
TEMPORARY_ERROR Temporary error
UNKNOWN_ERROR Unknown Error

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

TLV Tag Used in Description
0x1600 MO, MT and DR connection, the mobile operator code identifying the network of the mobile user
0x1620 MO sonar_guid, the unique identifier assigned by us for this message
0x1630 MO av, an optional identifier for adult verification
0x1640 MO and DR price, the consumer price in pence

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:

Type of Originator TON NPI
Shortcode (PSMS) 3 9
Alphanumeric (Bulk) 5 0
MSISDN (Bulk) 1 1

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:

Operator Code Operator
three-uk Three UK
eeora-uk EE (Orange) UK
eetmo-uk EE (T-Mobile) UK
voda-uk Vodafone UK
o2-uk O2 UK
virgin-uk Virgin Media UK
UNKNOWN Operator unknown

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:

Msisdn Prefix Operator Code
4400 o2-uk
4401 voda-uk
4402 eetmo-uk
4403 eeora-uk
4404 virgin-uk
4405 three-uk

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:

Msisdn Suffix CHARGESTATUS STATUSCODE STATUSTEXT
00000001 true if premium DELIVERED OK
00000002 false INVALID_MSISDN Destination Address Error
00000003 false OPERATOR_REJECTED Invalid state or parameters
00000004 false SMSC_ERROR Operator System Error
00000005 false INSUFFICIENT_FUNDS Temporary Error
00000006 false UNKNOWN_MSISDN UnknownSubscriber
00000007 false TEMPORARY_OPERATOR_ERROR Temporary network/roaming issue
00000008 false UNREACHABLE_MSISDN Mobile not reachable or temporary busy
00000009 false INVALID_OPERATOR_SERVICE Service not supported from mobile or operator
00000010 false PERMANENT_OPERATOR_ERROR Permanent Error (network/parameters
00000011 false TEMPORARY_BARRED Temporary Barred
00000012 false PERMANENTLY_BARRED Permanently Barred
00000013 false UNKNOWN_ERROR Unknown Error
00000014 false MAX_SPEND_MSISDN Spend Limit Reached
00000015 false OPERATOR_TIMEOUT Operator has not acknowledged. Message might have been sent
00000016 false UNROUTABLE Unable to route the message

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.

Msisdn Suffix AV STATUS
00000001 verified
00000002 not_verified
00000003 unknown
00000004 pending

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

Powered by BetterDocs

How we work with brands