HTTP integration (v2)

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 and Register-participants-for-survey API 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.

1. Login API

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. Register participants for survey

Call this API for creating survey links for the participants and optionally send the survey links through SMS/Email/Whatsapp/other-channels configured in your account. The API supports bulk registration of upto 1000 participants. Following is a example of such bulk API request.

curl --location --request POST 'https://zapi.api.zykrr.com/api/rest/{campaignId}/registerParticipantsForSurvey' \
    --header 'Content-Type: application/json' \
    --header 'Cookie: zykrr=login_token' \
    --data-raw '{
        "data": [
            {
                "participantInfo": {
                    "Name": "Diwakar",
                    "Email": "diwakar_singh_maurya@zykrr.com",
                    "Phone": "918800174323",
                    "CustomerId": "PA0123"
                },
                "transactionInfo": {
                    "d8827b50-86b9-4914-8262-8ba7345e77ef": ["Servicing"],
                    "1c57c42e-8546-479f-84ba-95c7dd62947e": ["INR 50"],
                    "85d93fd9-7966-42cf-be01-b824328e66ea": ["Dealer-Delhi01"]
                }
            },
            {
                "participantInfo": {
                    "Name": "Aalisha",
                    "Email": "aalisha_bhateja@zykrr.com",
                    "Phone": "919910366262",
                    "CustomerId": "PB0678"
                },
                "transactionInfo": {
                    "d8827b50-86b9-4914-8262-8ba7345e77ef": ["Repair"],
                    "1c57c42e-8546-479f-84ba-95c7dd62947e": ["INR 35"],
                    "85d93fd9-7966-42cf-be01-b824328e66ea": ["Dealer-Delhi05"]
                }
            }
        ],
        "templateId": {templateId},
        "scheduleDateTime": "2022-01-20T18:00:00+05:30",
        "scheduleRuleSetId": {scheduleRuleSetId},
        "autoCreateNewMCQOptions": false,
        "participantListName": "05-Oct-2021-Purchase"
}'

Description of the request body

  • data contains information related to participants and the events/transactions.

    • data[].participantInfo is information about the participant to whom the survey should be sent. This information is generally for identifying your customers, other related information which does not change often. Example: Name, Customer ID, membership id etc.

    • data[].transactionInfo is information about the event/transaction like purchase-value, store-name, product-type etc. The object-keys are metadata ids present inside your survey. Contact Zykrr support team to get these metadata ids and their type. The value’s data-type 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.

  • templateId (optional) is the id of the communication-template to be sent for this batch. A communication-template has information about the content and the channel (SMS/email/WhatsApp/etc) to be used for sending the survey to all participants. It can be overridden by scheduleRuleSetId. If not provided, the API returns the survey links only in response and does not send the survey links.

  • 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. It is ignored if templateId is not provided.

  • 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 Diwakar, template-1 is sent and template-2 for participant Aalisha.

  • 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. A value is considered invalid if it is not present in MCQ metadata options list already. If set to true it automatically updates the survey to include the new value in that particular metadata’s option.

  • participantListName (optional) A name for this batch of partcipants.

Response

{
    "surveyLinks": [
        "https://survey.zykrr.com/t/a1b2c3d4"
        "https://survey.zykrr.com/t/e5f6g7h8",
    ],
    "participantListId": "8535171e-d804-4557-bd3d-589ab876e7e8",
    "scheduleId": "bce9f5d6-0e1c-4d27-9749-5971dfcae0f0"
}

Description of response body

  • surveyLinks contains survey links for the participants in-order.
  • participantListId is an id generated for this batch of participants.
  • scheduleId is an id for the schedule. It is present only if templateId was passed.

Updated on 20 Jan 2022