Dynamic Numbers (DNCS API)

Introduction

Advanced partner setups sometimes require the tracking of visitors and number replacements to be initiated server-side. By using the Dynamic Numbers API, partners can programmatically simulate the requests that normally come through the Kaisa JavaScript.

Overview

When a client takes an action such as clicking "call now"-button, you have to invoke this Kaisa service server-side and pass the result back to the client. For complete user journey tracking, please contact Helpdesk.

The Dynamic Numbers API is exposed as a simple web service using JSON request and response data. A JSON request object containing the necessary parameters is sent to Kaisa service using HTTP POST. A JSON response object is returned containing the response data. A signature of the request data must be calculated and sent along with the request.

Kaisa service will normally process requests within 50 ms (excluding the network round trip), but we still suggest you to implement a timeout in case there is a temporary bad network connectivity and handle potential error responses by falling back to display or dial the original phone number. A suggested time out, including network round trips, is 1500 ms.

This service also supports requests from native apps.

Request parameters (web)

All parameters are sent in JSON body using HTTP POST.

Note: The Fields are mandatory but not all values need to be populated (some can be sent empty, see description).


{
  "advId": "string","fullUrl": "string”,
  "trackingId": "string",
  "numbers": "string",
  "type": "web",
  "fullReferrer": "string",
  "parameters": 
    {
        "custnr": "string",
        "custname": "string",
        "custemail": "string",
        "...": "string"
    },
    "userAgent": "string",
    "requestIpAddress": "string",
    "sessionId": "string"
}

Request parameters (app)

All parameters are sent in JSON body using HTTP POST.

Note: The Fields are mandatory but not all values need to be populated (some can be sent empty, see description).


{
    "advId": "string",
    "fullUrl": "string", // can be empty
    "trackingId": "string",
    "numbers": "string",
    "type": "app",
    "fullReferrer": "string",
    "parameters":
    {
        "custnr": "string",
        "custname": "string",
        "custemail": "string",
        "...": "string"
    },
}

Validation rules for mandatory parameters:

custnr: max 45 characters
custname: max 60 characters
custemail: max 150 characters

Mandatory Parameters

'fullUrl' (needs to be included but can be empty)

'advId'

'trackingId' (needs to be included but can be empty)

'numbers'

'type'

'fullReferrer' (needs to be included but can be empty)

'sign'

'userAgent' and 'requestIpAddress' are mandatory for our IP block and spam mechanisms to work, otherwise we are unable to block or detect blacklisted requests.

API parameters

A short explanation of the mandatory parameters used:

advId Account name with Kaisa

fullUrl The URL of the website where the Dynamic Number will be displayed

trackingId Partner generated visitor ID (for example, a logged in visitor). Can be sent empty.

numbers The phone number(s) to be replaced

type either web or app

fullReferrer The referrer URL of the visitor (if set). Can be sent empty.

parameters See custom dimensions below

userAgent The visitors user agent (for User level tracking setup) Can be sent empty.

requestIpAddress The IP address of the visitor (can be sent empty but not recommended)

sessionId Kaisa generated session ID, can be appended to provide a continued session in Kaisa to a visitor. Can be sent empty.

Kaisa will use the IP address passed on and the userAgent to protect you against unwanted traffic. More on this here.

Custom dimensions

Typically the parameters object will, at least, contain information to identify the end customer (Name, ID and Email). The parameters object can also contain N number of custom dimensions defined jointly by Kaisa and the partner.

Some examples of commonly used custom dimensions are:

adId: the unique identifier for the ad
adUrl: the base64 encoded URL of the ad
adImage: the base64 encoded image URL of the ad
adPrice: the price of the vehicle
adKm: the mileage of the vehicle
adBrand: the brand of the vehicle

These are then sent by the partner to Kaisa in order to identify the specific ad a visitor is calling for. Other fields can be added or configured after discussing this with the Support & Activation team, and the naming of the above examples can be configured as well.

Responses

Response data is given as JSON:


{
    "success": "boolean",
    "error": "string",
    "numbers":
    [{
        "number_on_page": "string",
        "replace_with":
        {
            "e164": "string",
            "local": "string"
        }
    }],
    "sessionId": "string"
}

Example of a successful response:


{
    "success": true,
    "numbers":
    [{
        "number_on_page": "+493015981100",
        "replace_with":
        {
            "e164": "+493015981158",
            "local": "030 15 98 11 58"
        }
    }],
    "sessionId": "40846be9-88de-4120-bf8c-dfc2fd6c4c3"
}

Example of an error response:


{
    "success": false,
    "error": "Missing parameter: advId"
}

Response codes

The legacy default of this API is to return 200 OK for all response types, and the error is instead returned in the body of the response. If you want, you can override this and have the API return proper HTTP response codes, for example on errors. The full error is always sent back in the body of the response. To request proper response codes, please append the custom header X-HTTP-STATUSES (set as X-HTTP-STATUSES:1) to the request.

The response codes used are:

200 OK The request was successfully processed

400 Bad Request The request is missing information or contains bad information

403 Forbidden The request has not been processed, please see body for details

500 Internal Server Error The server failed to process the request, please see body

501 Not Implemented The server is missing configuration, please see body

Authorization Options

Signature

The signature (HMAC) is calculated by using the full body data together with a secret key Kaisa will share with you. Currently the signature method used is SHA1. The calculated signature can be either appended to the end of the query string or sent as a custom header.

Consider the following simplified JSON object {“advid”:”123”,”numbers”:”321”} where the HMAC-SHA1 signature is calculated using the key "kaisa" (for this example):

The signature can be passed either as a query parameter:

POST http://url/api?sign=a86cf5c29d18a6ddc785e3422e3ad4ed101278f3

{“advid”:”123”,”numbers”:”321”}

or as a custom header:

POST http://url/api

X-SIGN: a86cf5c29d18a6ddc785e3422e3ad4ed101278f3