Conversion rate API

Conversion rate tutorial

Document references:

Introduction

This tutorial will explain in just a few simple steps how you can set-up and use Infobip Conversion rate HTTP API.

Conversion rate service allows our you to measure conversion rate ratio between some steps in the your processes.

Processes that are most commonly tracked for conversion rate are:

After you have defined the process you want to track, you should create steps (tags) for which you would like to measure conversion rate. We highly recommend to have at least two steps in your process so we can calculate conversion rate ratio (i.e. START_TAG and END_TAG).

When some subscriber goes through your whole process and we have logged both start and end tags, we can consider that as a Converted user. Total conversion rate ratio is measured as total sum of end tags divided by total sum of start tags.

Note:
You can create as much tags as you want for one process. Also, you can measure conversion rate ratio between every two tags in your process. More details you can find here.

Base URL

You should submit all requests to the base URL. All the requests are submitted thorough HTTP POST, PUT or GET method. Although you can use HTTP protocol, we strongly recommend you to submit all requests to Infobip SMS API over HTTPS so the traffic is encrypted and the privacy is ensured.

Base URL: https://oneapi.infobip.com

Authorization

In order to use Infobip SMS API, you have to be authorized. You need to encode your username and password in base64 like this:

Authorization Description Example
Basic Authorization with username:password using Base64 encoding. Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Example:

Username: `Aladdin`
Password: `open sesame`

String: `Alladin:open sesame`
Base64 encoded string: `QWxhZGRpbjpvcGVuIHNlc2FtZQ==`

Content-Type

Infobip SMS API supports JSON and XML Content-Types that should be specified in the header. Depending which Content-Type you choose for the request, the same one will be applied in the response. If you don’t specify the Content-Type you will receive a General error.

Content-Type: application/json or application/xml.

Step-by-step guide

Setup the tracking process

Create one or more tracking processes using the API.

Endpoint: POST https://oneapi.infobip.com/1/conversion-rate/process

Request body parameters

Parameter Type Description
name String Required. Process name.
description String Required. Process description.

Response format

On success, response header HTTP status code will be 200 OK and messages will be returned in response body.

If you try to get received messages without authorization, you will get a response with HTTP status code 401 Unauthorized.

Response body parameters

Parameter Type Description
name String Tracking process name.
description String Tracking process description.
timeAdded Timestamp Tracking process creation time.
processType String Process type. (User defined process. or Default process type. or Tracking process type. or System process type.)
key String Process key that uniquely identifies the process.

Example: Setup the tracking process

JSON Request

POST 1/conversion-rate/process HTTP/1.1
Host: oneapi.infobip.com
Authorization: Basic xxxxxxxxxxxxxxx
Content-Type: application/json

{
    "name": "Sign-up tracking",
    "description": "My awesome Sign-up tracking"
}

JSON Response

HTTP/1.1 200 OK
Content-Type: application/json

{
 "key": "47A3614FB229EBEA88ED45E72BB07D3E",
 "name": "Sign-up tracking",
 "timeAdded": "2015-03-19T09:21:57.934+0100",
 "processType": "USER_DEFINED",
 "description": "My awesome Sign-up tracking"
}

Setup the tracking process steps (tags)

Create at least two process steps. For example, one for sign-up start, and another one for successful sign-up (or end) using the API.

Endpoint: POST https://oneapi.infobip.com/1/conversion-rate/process/{key}/tag

Path parameters

Parameter Type Description
key String Required. Process key you have received when tracking process was created.

Request body parameters

Parameter Type Description
name String Optional. Process step (tag) name.
description String Optional. Process step (tag) description.
processTagType String Process step (tag) type. (Start tag. or End tag or Undefined tag type)

Response format

On success, response header HTTP status code will be 200 OK and messages will be returned in response body.

If you try to get received messages without authorization, you will get a response with HTTP status code 401 Unauthorized.

Response body parameters

Parameter Type Description
name String Process step (tag) name.
description String Process step (tag) description.
processTagType String Process step (tag) type. (Start tag. or End tag or Undefined tag type)
key String Process tag key that uniquely identifies tag.

Example: Setup the tracking process tag examples

Add start process tag

JSON Request

POST /conversion-rate/process/47A3614FB229EBEA88ED45E72BB07D3E/tag HTTP/1.1
Host: oneapi.infobip.com
Authorization: Basic xxxxxxxxxxxxxxx
Content-Type: application/json

{
    "name": "START",
    "description": "Signup start",
    "processTagType": "START_TAG"
}

JSON Response

HTTP/1.1 200 OK
Content-Type: application/json

{
     "key": "742CEC5DEF6025218E5A0407B029D02D",
     "name": "START",
     "description": "Signup start",
     "processTagType": "START_TAG"
}

Add end process tag

JSON Request

POST /conversion-rate/process/47A3614FB229EBEA88ED45E72BB07D3E/tag HTTP/1.1
Host: oneapi.infobip.com
Authorization: Basic xxxxxxxxxxxxxxx
Content-Type: application/json

{
    "name": "END",
    "description": "Successful signup",
    "processTagType": "END_TAG"
}

JSON Response

HTTP/1.1 200 OK
Content-Type: application/json

{
     "key": "AC175A3A7D4AE68FE358C053630ED926",
     "name": "END",
     "description": "Successful signup",
     "processTagType": "END_TAG"
}  

Add new conversion rate log

After you have created tracking process and steps (tags) in the process, you are ready to log your tags on our platform using API.

Endpoint POST https://oneapi.infobip.com/1/conversion-rate/process/{key}/log

Path parameters

Parameter Type Description
key String Required. Process key.

Body parameters

Parameter Type Description
processTagKey String Optional. Process tag key you have received when tag was created.
processLogKey String Optional. Process log key.
countryCode String Optional. Country code.
osType String Optional. OS type. (Unknown or Windows or Linux or Windows failover cluster or Android or IOS or Windows Phone)

Response format

On success, response header HTTP status code will be 200 OK and messages will be returned in response body.

If you try to get received messages without authorization, you will get a response with HTTP status code 401 Unauthorized.

Response body parameters

Parameter Type Description
timeAdded Timestamp Process creation time.
processTagKey String Process tag key you have received when tag was created.
addCount int Add count.
countryCode String Country code.
osType String OS type. (Unknown or Windows or Linux or Windows failover cluster or Android or IOS or Windows Phone)
processKey String Process key.
tag String Tag.
key String Specific log key.
accountKey String Account key.

Example: Add new conversion rate log

JSON Request

POST 1/conversion-rate/process/{key}/log HTTP/1.1
Host: oneapi.infobip.com
Authorization: Basic xxxxxxxxxxxxxxx
Content-Type: application/json

{
    "processLogKey": "7c32d5fc-6870-4c33-8222-44d477b0671c",
    "processTagKey": "AC175A3A7D4AE68FE358C053630ED926",
    "countryCode": "US",
    "osType": "ANDROID"
}

JSON Response

HTTP/1.1 200 OK
Content-Type: application/json

{
     "processKey": "95578456D6F794703FB6C9418AF6AA97",
     "accountKey": "3C3EFB2D307CA4FEFB2B5282E51E36EE",
     "key": "7c32d5fc-6870-4c33-8222-44d477b0671c",
     "tag": null,
     "processTagKey": "AC175A3A7D4AE68FE358C053630ED926",
     "timeAdded": "2014-10-10T15:54:59.443+0200",
     "countryCode": "US",
     "osType": "ANDROID",
     "addCount": 1
}

Send SMS messages that triggers a tracking process

This use-case will explain you how you can use our SMS message to start a tracking process using API.

Let’s say you have a tracking process that has to be initiated by sending an SMS message. For example, you want to promote your web app with SMS and deliver a promo code to your users. Later you want to track how many users actually entered your promotional code in your web app.

First, you have to send an SMS message that will start process tracking. Afterward, when user enters the promotional code in your web app, you have to add new conversion log on our platform for the end tag.

Endpoint: POST https://oneapi.infobip.com/1/smsmessaging/outbound/{senderAddress}/requests

Request parameters

Header field Description
Authorization Required. Basic + Base64(username:password).
Content-type Required. The content type of the request body: application/json

Path parameters

Parameter Type Description
senderAddress String Required. Sender address.

Body parameters

Parameter Type Description
senderAddress String Optional. Represents sender ID and it can be alphanumeric or numeric.
trackInfo TrackInfo Optional. Conversion rate and tracking configuration.
address String[] Required. Array of message destination addresses. If you want to send a message to one destination, a single String is supported instead of an Array. Destination addresses must be in international format (Example: 41793026727).
message String Optional. Text of the message that will be sent.

TrackInfo

Parameter Type Description
urlTrackInfo UrlTrackInfo Optional. Configuration for url tracking.
initTagInfo InitTagInfo Optional. Configuration for initialization tag.

InitTagInfo

Parameter Type Description
processKey String Optional. Process key.
tag String Optional. Tag name.

Response format

On success, response header HTTP status code will be 200 OK and messages will be returned in response body.

If you try to get received messages without authorization, you will get a response with HTTP status code 401 Unauthorized.

Response body parameters

SendSMSResult

Parameter Type Description
resourceReference ResourceReference Optional. The resource URL.
clientCorrelator String Optional. An identifier that uniquely identifies the request.
sendMessageResults SendMessageResult[] Optional. Array of send message request results, one per every message.
urlProcessTrackingKey String Optional. URL tracking process key.

ResourceReference

Parameter Type Description
resourceURL String Contains URL that uniquely identifies a successful request to the OneAPI server.

SendMessageResult

Parameter Type Description
messageStatus String Message status. Indicates whether the message is successfully sent, not sent, delivered, not delivered, waiting for delivery, or any other possible status
senderAddress String Represents sender ID and it can be alphanumeric or numeric. Alphanumeric sender ID length should be between 3 and 11 characters (Example: CompanyName). Numeric sender ID length should be between 3 and 14 characters.
destinationAddress String[] Array of message destination addresses. If you want to send a message to one destination, a single String is supported instead of an Array. Destination addresses must be in international format (Example: 41793026727).
processLogKey String Process log key.
price decimal Message price.
messageId String Message id .
errorMessageId String Error message ID.

Example: Send SMS messages that triggers a tracking process

Send messages

JSON Request

POST 1/smsmessaging/outbound/senderAddress/requests HTTP/1.1
Host: oneapi.infobip.com
Authorization: Basic xxxxxxxxxxxxxxx
Content-Type: application/json

{
  "senderAddress": "INFOSMS",
  "trackInfo": {
    "initTagInfo": {
      "processKey": "95578456D6F794703FB6C9418AF6AA97",
      "tag": "START"
      }
  },
  "address": [
    "385981234567"
  ],
  "message": "We invite you to use our fancy app using this promo code 12345."
}

JSON Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "resourceReference": {
       "resourceURL": "https://oneapi.infobip.com/1/smsmessaging/outbound/{senderAddress}/requests/14129485255681170/deliveryInfos"
   },
   "clientCorrelator": "14129485255681170",
   "sendMessageResults": [
       {
           "messageStatus": "MessageAccepted",
           "messageId": "a715c699-188b-416b-aa8e-78f0e5383412",
           "senderAddress": "INFOSMS",
           "destinationAddress": "385981234567",
           "price": 0,
           "errorMessageId": null,
           "conversionTrackFlag": null,
           "conversionTrackKey": null,
           "processLogKey": "7c32d5fc-6870-4c33-8222-44d477b0671c"
       }
   ],
   "urlTrackingProcessKey": null
}   

Conversion rate and statistics

After you have successfully logged your tags on our platform, you can easily get conversion rate for your process and steps in it.

Available API methods for getting conversion rate and statistics are:

Here we will show you a few examples how you can get your conversion rates.

Get average conversion rate for tags

Endpoint: GEThttps://oneapi.infobip.com/1/conversion-rate/process/{key}/statistics/average-conversion-rate

Path parameters

Parameter Type Description
key String Required. Process key.

Query parameters

Parameter Type Description
start-tag String Optional. Start tag.
end-tag String Optional. End tag.
from Date Optional. From date.
to Date Optional. To date.
end-tag-from String Optional. End tag from.
end-tag-to String Optional. End tag to.

Response format

On success, response header HTTP status code will be 200 OK and messages will be returned in response body.

If you try to get received messages without authorization, you will get a response with HTTP status code 401 Unauthorized.

Response body parameters

ConversionRates

Parameter Type Description
startTag String Start tag.
startTagTimeFrame TimeFrame Time frame for start tag.
endTag String Optional. End tag.
endTagTimeFrame TimeFrame Time frame for end tag.
conversionRateStats ConversionRateStats Conversion rate statistic.
averageConversionTime AverageConversionRate Average conversion time.

TimeFrame

Parameter Type Description
from Timestamp From.
to Timestamp To.

ConversionRateStats

Parameter Type Description
startCount long Start count.
endCount long End count.
conversionRate double Conversion rate.

TimeStats

Parameter Type Description
time long Time.
timeUnit String Time units. Possible values: [‘seconds’ or ‘minutes’ or ‘hours’ or ‘days’].

Example: Get average conversion rate for tags

Get conversion rate for tags

*JSON Request

GET 1/conversion-rate/process/{key}/statistics/average-conversion-rate HTTP/1.1
Host: oneapi.infobip.com
Authorization: Basic xxxxxxxxxxxxxxx
Content-Type: application/json

JSON Response

HTTP/1.1 200 OK
Content-Type: application/json

{
 "startTag": "START",
 "endTag": "END",
 "startTagTimeFrame": {
   "from": "2014-09-10T15:55:09.647+0200",
   "to": "2014-10-10T15:55:09.647+0200"
 },
 "endTagTimeFrame": {
   "from": "2014-09-10T15:55:09.647+0200",
   "to": "2014-10-10T15:55:09.647+0200"
 },
 "conversionRateStats": {
   "startCount": 1,
   "endCount": 1,
   "conversionRate": 1
 },
 "averageConversionTime": {
   "time": 774,
   "timeUnit": "SECONDS"
 }
}

Get conversion rate by date

Endpoint:GEThttps://oneapi.infobip.com/1/conversion-rate/process/{key}/statistics/conversion-rate

Path parameters

Parameter Type Description
key String Required. Process key.

Query parameters

Parameter Type Description
start-tag String Optional. Start tag.
end-tag String Optional. End tag.
from Date Optional. From date.
to Date Optional. To date.

Response format

On success, response header HTTP status code will be 200 OK and messages will be returned in response body.

If you try to get received messages without authorization, you will get a response with HTTP status code 401 Unauthorized.

Response body parameters

Parameter Type Description
conversionRates ConversionRates Array of conversion rates.
granulation String Granulation. Possible values: Granulation by days.

Example: Get conversion rate by date

JSON Request

GET 1/conversion-rate/process/{key}/statistics/conversion-rate HTTP/1.1
Host: oneapi.infobip.com
Authorization: Basic xxxxxxxxxxxxxxx
Content-Type: application/json

JSON Response

HTTP/1.1 200 OK
Content-Type: application/json

{
 "conversionRates": [
   {
     "startTimeFrame": {
       "from": "2014-10-10T02:00:00.000+0200",
       "to": "2014-10-11T02:00:00.000+0200"
     },
     "endTimeFrame": null,
     "conversionRateStats": {
       "startCount": 1,
       "endCount": 1,
       "conversionRate": 1
     }
   }
 ],
 "granulation": "DAY"
}