HTTP integration (v1)

This API is deprecated. Kindly use HTTP integration v2 API.

Introduction

This document describes Zykrr platform’s HTTP APIs using which you can send survey to your customers. The API parameters are indicated like this {parameter} and will be provided by Zykrr support team separately in an email.
In Zykrr platform, a customer/person providing feedback is called “participant”. Whenever there is an event/transaction for a participant that qualifies for feedback as per your business logic, you must call Login, Create-participants and Distribute-survey-links API sequentially to send the survey.
As an example here we have taken a case of automobile-seller wanting to integrate with Zykrr feedback platform for taking feedback on showroom-visit and purchase experience.

Before performing any read/write operations in Zykrr platform, you must have a login token. Login with your username and password through this API and acquire a login token. Below is a curl request for login. Replace your_username and your_password as per your account.

curl --location --request POST 'https://accounts.zykrr.com/api/login' \
    --header 'username: {your_username}' \
    --header 'password: {your_password}'

Response:

{"token":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJkbiI6InVpZD1aeWtyciBEZW1vLG91PXVzZXJzLGRjPXp5a3JyIiwiZ3JvdXBzIjpbXSwiaWF0IjoxNjAwMzQ5MTM3LCJleHAiOjE2MDA0MzU1Mzd9.Wdh2lESM_6LKyioKgfuiXXmwC55Q-
hBjlUjeB2LCvB2Ddtck_tGT0r5bQkMgc4Jj5h-SmMoZeUNzt9T5onmS0e4UtpsqScea0SqiSQTLHi1DRTnMCR1_zyy-T1tb6TFBPxHT-lvjLWN23O1XBjkFaq-d2pzscpMeK2IVBpbkLTKOg97knuoC46nnmo5gGI70fTl0DSksGtLwaDmF0ZUr_i88KJEXdi
eMptvjgfr-Hdx7ctHFaG_oweUO-aFnJDJw7jLwuz6B1-XfWkjZOd41w7SfwSfygwYNchfEFbUfwL6HrmcEs9lrLPkW-uyGoxzfDU1KyoJjkcSt7kTslckI5K3nXmQ9R6kUAeD-ZryqllAUm3vgRwuEXoN034KKPBwecp754eJ9lHqeDEHpPwXJ7a1e9vcOO8q
W1B4QaRLlWeFwScxWYMCgHO5gbGh1_NzjsJ3dmFd5QSbdLJVxIh10ira8MLQXFxhOZ_LpR-F9VKn6kOlAXG-8f1I6wTCIL6oBIIrmrQu5USlc1yNSkmDP8Ra6WYwyz9Is5SI8c14sROjf4dd-OoeFSiwqFdQDdXOqIQT-_euBnEDy3nJG7c2OD5mu7pYgxGfC
UGvTUTqY03V3Tb6VwSg_tMS4K8NKLvW9HKkT3q4tNcexlVNQS8jdSqkSBJzkZbJR0FokinhjSbc"}

The value of key token in the JSON response is the login token. We will refer it as login_token in rest of the documentation. It is valid for only 24 hours. Call this API again after 24 hours to get a new token.

2. Create participants

Every participant must be registered before they can receive a survey. Call this API for registering participants in Zykrr platform. Once participant-id is obtained using this API, we can then send feedback link to that participant using Distribute-survey-links described in next section.
The API supports bulk creation of participants too. Putting multiple objects in userInfo will create multiple participants in single call and return the participant-ids in that order. Following is a example of such bulk API request.

curl --location --request POST 'https://zapi.api.zykrr.com/api/rest/{organizationId}/participantsV2' \
    --header 'Content-Type: application/json' \
    --header 'Cookie: zykrr=login_token' \
    --data-raw '{
        "userInfo": [
            {
                "data": {
                    "Name": "Diwakar",
                    "Email": "diwakar_singh_maurya@zykrr.com",
                    "Phone": "918800174323",
                    "CustomerId": "PA0123"
                },
                "where": {
                    "CustomerId": "PA0123"
                }
            },
            {
                "data": {
                    "Name": "Aalisha",
                    "Email": "aalisha_bhateja@zykrr.com",
                    "Phone": "919910366262",
                    "CustomerId": "PB0678"
                },
                "where": {
                    "CustomerId": "PB0678"
                }
            }

        ]}'

Description of the request body

userInfo[].data contains a participant’s information. This information is generally for identifying your customers, other releated information which does not change often and is not releated to the event/transaction for which we want to send the survey. Example: Name, Customer ID, membership id.
userInfo[].where contains a participant’s identification information. Through this, Zykrr platform uniquely identifies the customer and creates/updates their details. If a participant already exists matching the information provided in userInfo[].where, their information is updated with corresponding userInfo[].data otherwise they are created within Zykrr system with that information.

The response of this API is as follows. The values in the JSON array are ids of the created/updated participants in same order they were sent in userInfo. These participant-ids are used in next Distribute-survey-links API.

["2f1235d2-d750-4fa3-ba43-33f6915c5962","6a033e78-ecfb-42ac-827a-aa300e535109"]

3. Distribute survey links

This API receives metadata about the event/transaction and sends the survey link to the participants through email/SMS/WhatsApp/etc.

In the following example request we are scheduling the survey to be sent at 6PM IST on 20 Jan 2022 to the 2 participants. prefilledAnswers contains information about the event/transaction and used by Zykrr platform for rich analytics later.

curl --location --request POST 'https://zapi.api.zykrr.com/api/rest/{campaignId}/generateTokenForParticipantAndSendSMSorEmail' \
    --header 'Content-Type: application/json' \
    --header 'Cookie: zykrr=login_token' \
    --data-raw '{
        "participantIds": [
             "2f1235d2-d750-4fa3-ba43-33f6915c5962",
             "6a033e78-ecfb-42ac-827a-aa300e535109"
        ],
        "templateId": {templateId},
        "prefilledAnswers": [{
            "d8827b50-86b9-4914-8262-8ba7345e77ef": ["Servicing"],
            "1c57c42e-8546-479f-84ba-95c7dd62947e": ["INR 50"],
            "85d93fd9-7966-42cf-be01-b824328e66ea": ["Dealer-Delhi01"]
        }, {
            "d8827b50-86b9-4914-8262-8ba7345e77ef": ["Repair"],
            "1c57c42e-8546-479f-84ba-95c7dd62947e": ["INR 35"],
            "85d93fd9-7966-42cf-be01-b824328e66ea": ["Dealer-Delhi05"]
        }],
        "participantListName": "05-Oct-2021-Purchase",
        "autoCreateNewMCQOptions": false,
        "participantNotAddedBeforeDays": 30,
        "scheduleDateTime": "2022-01-20T18:00:00+05:30",
        "scheduleRuleSetId": {scheduleRuleSetId}
}'

Description of the request body

participantIds is an array of participant ids obtained from create-participant api, to whom the survey should be sent.
templateId is the id of the communication-template to be sent for this batch. A communication-template has information about the content and the channel to be used for sending the survey all participants (SMS/email/WhatsApp/etc). It can be overridden by scheduleRuleSetId.
prefilledAnswers is an array containing objects corresponding to each participant id in participantIds. The object is metadata for the particular participant related to this event/transaction. The object-keys are metadata ids present inside your survey. Contact Zykrr support team to get these metadata ids and their type. The value passed against the metadata ids should be according to table below :-

Metadata type Data type

RATING integer

MULTIPLE_CHOICE array of strings

OPENEND string

If value of some metadata is undefined/unknown for a participant, then don’t include that metadata-id in the object.
participantListName (optional) A name for this batch of partcipants.
autoCreateNewMCQOptions (optional) The default value is true. It tells whether the system should throw error if it sees an invalid value for metadata of type MULTIPLE_CHOICE. When set to false and an invalid value is received, it throws error. If set to true it automatically updates the survey to include the new value in that particular metadata’s option.
participantNotAddedBeforeDays (optional) It is an integer value that instructs the Zykrr platform not to send survey to those participants to whom the survey was triggered within specified days. Time is calculated from current server time. If not provided, survey is sent to all participants specified in participantIds.
Example: Sending 30 as its value will filter out those participants to whom the same survey was triggered within last 30 days. It will not send survey to them and send to rest of the participants.
scheduleDateTime (optional) The date-time in ISO format at which the survey should be sent. This date-time should be within next 7 days. If no value is provided, the survey is sent immediately.
scheduleRuleSetId (optional) The id of the schedule-rule-set created in survey distribution module of Zykrr platform. A schedule-rule-set is a set of rules over participant’s metadata that tell Zykrr platform which content-templates should be picked for a participant. If none of the rules of schedule-rule-set match, content-template with templateId is picked.
Example: Let’s assume your schedule-rule-set is made of following 2 rules.
- If shopping-value >= 50 send template-1
- If shopping-value < 50 send template-2
Then for participant 2f1235d2-d750-4fa3-ba43-33f6915c5962 template-1 is sent and template-2 for 6a033e78-ecfb-42ac-827a-aa300e535109.

Metadata type	Data type
RATING	integer
MULTIPLE_CHOICE	array of strings
OPENEND	string

Updated on 20 Jan 2022