API Overview

Benefits of API:

• Completely automated upload of respondents: this way you can get your team to set up an automatic push for the upload of respondents. You can even set up a delay in the sending of an email so that customers don’t receive your email in the middle of the night.   
• Pull different kinds of data out of the platform again, such as list of unsubscribed people, list of emails that were not delivered,…

What is API?
An API (Application Programming Interface) is a set of functions and procedures that allow the creation of applications which access the features or data of an operating system, application, or other service, such as Hello Customer. Basically, it is a set of pre-defined "calls" which enables software (such as a CRM-platform) to download or upload information to Hello Customer.

IN THIS ARTICLE:
The steps to set up an automatic connection via API

1. Authorization
2. General
3. Date format
4. Language ID’s
5. Validation messages
6. Adding respondents
7. API call 1 - Adding one respondent at a time
8. API call 2 - Adding multiple respondents
9. API call 3 - Get responses
10. API call 4 - Get NPS
11. API call 5 - Add answer

IMPORTANT
To enhance security we set a throttle on the API-call. The amount of calls cannot exceed 1 call per second.
We also only allow HTTPS-calls with TLS 1.2 protocol

If you are experiencing issues with connecting to the API, please contact support@hellocustomer.com. Make sure you include what call you are using and if possible, include the body. Do not send the Authorization details along, as this would be considered a security breach. 

1. Authorization

When submitting a request to our servers, you’re required to submit credentials using the following format:

Authorization: basic your-token

Your token has to be created in the Hello Customer platform. More information on how to create this token can be found this article.

Example: Authorization: basic ZGVtb0BoZWxsb2N1c3RvbWVyLmNvbTpFRTZBQTg1NjVGMjkzOTdGM0NEQzIyQkYxNUJBNjc2Mw==

NOTE:
Some services or software (Azure Data Factory, Postman,...) will ask for a username and passwords when selecting basic authorization, if this is the case you need to manually add it to the header as a key:

back to top...

---

2. General

CampaignUniqueID: 

This is a unique number which identifies your touchpoint. This main purpose of this identifier is to route the respondents to your specific touchpoint. 

The campaignuniqueID can be retrieved in the application when you go to Touchpoint Settings. In the container of the General Settings you will find the unique identifier of your touchpoint:

Mandatory data: 

When adding respondents, whether you are using an API connector, FTP connection or even when you upload an XLSX file manually, we can make a distinction between two types of data. The first category is the mandatory data. The minimum set of data we need to send you surveys involves

• Email:
  • Email addresses are particularly mandatory when using Email Touchpoints. The email could be used to launch a survey to a respondent but also to send/receive reports, send reminders or autoresponders.
  • Even though it is now possible to launch a survey when visiting a website or by clicking an URL, we always ask to provide an email address because without one, it will be rather difficult to follow up on your customer. 
• Language:
  • Providing the right language is also important to send out the right survey to the right customer. There is nothing more silly then receiving a survey in a language you don't understand or fully master. By doing so, respondents will receive the correct version of the survey based on their native language. Autoresponders will also be set accordingly. Languages can also be used as a filter to compare types of customers from different regions.

Key values:

The other category is metadata. Metadata is data that describes other data by giving extra context or information regarding this piece of data.

Metadata can be:

• Contextual: by describing the context of the interaction between the customer and your company.
  • Examples: 
    • The city the customer bought the article;
    • The storetype where the customer has bought the article.
• Transactional: by providing extra information regarding the actual transaction with your company.
  • Examples:
    • The number of items purchased in a store;
    • The type of product the customer has purchased;
    • The payment method used by the customer to make the purchase.
• Customer related: by describing the specific characteristics of your respondent.
  • Examples:
  • The gender or age of the customer;
  • The segment in which the customer is located;
  • The status of the customer (Bronze, Gold, Silver).

back to top...

3. Date format

4. Language ID’s

Language ID’s can be submitted as following:

back to top...

5. Validation messages

In order to facilitate potential issues when running an API, this list of validation messages can be of guidance:

a. 200/201: Success

•  The creation of the API call has been successful and is working fine.

b. 401: Authorisation failure

• The authorisation of the call failed. This might be caused by the following causes:
  • API token has expired
  • API token does not contain the right API call permissions
  • API token does not contain this touchpoint/CampaignUniqueID
  • API token has not been provided in the API call

c. 400: Bad request

• For all API's:
  • The JSON model is not correct
  • The LanguageUniqueId is not part of this touchpoint
  • The Guid of the language is empty or the format is incorrect
  • The format of the Guid of the language is not valid
• Add respondents API:
  • The format of the Guid of the language is not valid
  • Language with ID: {model.LanguageUniqueId} not found
  • Touchpoint with ID: {campaignUniqueID} not found
  • The model of the respondent is invalid
  • The respondent email {model.Respondent.Email} is invalid
• Add answers API
  • The format of the Guid of the question item is not valid
  • The questionItemUniqueId is empty or the format is incorrect
  • The questionItemUniqueId of an answer is not correct

d. 429: Too many requests

• Too many requests are following up on each other and there is less than 1 second between each API call.

back to top...

6. Adding respondents

When uploading respondents to Hello Customer - with the POST request - certain data is required and other data is optional. Required data for a touchpoint are email address and language. Without it, we cannot send the correct email to a respondent. 

Optional data can be split up into personal data and metadata. The first can be anonymised for users of the platform, the latter is relevant data that can be used to segment your feedback in later phases.

Personal data, that can optionally be anonymised is:

• firstName
• lastName
• phoneNumber
• custom_UniqueID

To make sure personal data is anonymised, use the above fields respectively

If certain metadata is set to "mandatory" in the touchpoint settings and this metadata is not added in the call, an error will occur and the data will not be sent to the platform.

back to top...

7. API-Call 1 - Adding one respondent at a time

Send a POST request to:

https://api.hellocustomer.com/V1.0/EN/Campaign/{Campaign_UniqueID}/Respondent/Add

• Make sure to submit your authorization credentials in the header of the POST envelope.
• This call is only available for email-based touchpoints
• Only use this request to add one respondent at a time. If you want to send 2 or more respondents, please see call 2 - Adding multiple respondents.
• If you use this request, the time between 2 requests needs to be at least 1 second.

The body of the POST envelope must be a JSON object:

{
   "firstName":"John",
   "lastName":"Doe",
   "email":"JohnDoe@mycompany.com",
   "phoneNumber":"+32486697306",
   "custom_UniqueID":"8754864354",
   "campaign_UniqueID":"c8dc5f94-a9e8-4743-8744-e66a73a7e724",
   "language_UniqueID":"1b5c1275-4f92-422f-b1fc-799bf8e30598",
   "keyValues":{
      "Winkel":"Brugge",
      "Leeftijd":"35",
      "Gemeente":"Damme"
   }
}

If you get a response 201 from our server and a body containing the json you send, the respondent was successfully added.

You can find your campaign’s unique ID (or Touchpoint ID) on the Touchpoint's settings overview page under "general configuration".

back to top...

8. API-Call 2 - Adding multiple respondents

Send a POST request to:

https://api.hellocustomer.com/V1.0/EN/campaign/{campaignUniqueID}/respondent/addmultipletocache

• Make sure to submit your authorization credentials in the header of the POST envelope.
• This call is only available for email-based touchpoints
• If you use this request, the time between 2 requests needs to be at least 1 second.

The body of the POST envelope must be a JSON object:

[
   {
      "firstName":"John",
      "lastName":"Doe",
      "email":"john.doe@johnscompany.com",
      "custom_UniqueID":"8754864354",
      "language_UniqueID":"1b5c1275-4f92-422f-b1fc-799bf8e30598",
      "campaign_UniqueID":"c8dc5f94-a9e8-4743-8744-e66a73a7e724",
      "keyValues":{
         "key1":"value1",
         "Key2":"value2"
      }
   },
   {
      "firstName":"Jessica",
      "lastName":"Day",
      "email":"jessica.day@hotmail.com",
      "custom_UniqueID":"8754864354",
      "language_UniqueID":"1b5c1275-4f92-422f-b1fc-799bf8e30598",
      "campaign_UniqueID":"c8dc5f94-a9e8-4743-8744-e66a73a7e724",
      "keyValues":{
         "key1":"value1",
         "Key2":"value2"
      }
   }
]

If you get a response 200 from our server, the respondent was successfully added.

back to top...

9. API-Call 3 - Get responses

Send a GET request to:

https://api.hellocustomer.com/V1.0/EN/campaign/{campaignuniqueID}/answers/getall/{startDate}/{endDate}

• Make sure to submit your authorization credentials in the header of the GET envelope.
• If you use this request, the start date and end date cannot be more than 31 days apart.

The response of the GET envelope is a JSON object:

[
   {
      "firstName":"John",
      "lastName":"Doe",
      "privateIp":"84.198.158.58",
      "publicIp":"84.198.158.58:58554",
      "email":"john.doe@gmail.com",
      "phoneNumber":"0491623685",
      "campaign_UniqueID":"1e82dea5-f254-4735-ba06-cfcccc756828",
      "language_UniqueID":"1b5c1275-4f92-422f-b1fc-799bf8e30598",
      "respondent_UniqueID":"0670a979-bd0e-4f0b-a919-13a385dec322",
      "survey_UniqueID":"535503b5-960a-4178-8ac5-d89a886b8085",
      "hasBeenContacted":false,
      "hasBeenForwarded":false,
      "dateSurveyed":"2020-09-29T13:36:25Z",
      "dateAnswer":"2020-09-29T13:42:37Z",
      "custom_UniqueID":"",
      "keyValues":{
         
      },
      "answerQuestions":[
         {
            "answer_Date":"2020-09-29T13:42:37Z",
            "answer_Value":6,
            "survey_UniqueID":"535503b5-960a-4178-8ac5-d89a886b8085",
            "question_UniqueID":"9895902c-5138-4feb-9af9-d38093b7f54e",
            "question_SiblingUniqueID":"1f6cb28d-a553-4acc-beca-0b69d9a4ddd0",
            "question_Text":"In welke mate ben je het eens of oneens met volgende stelling:\n$_CompanyName_$ zorgde ervoor dat mijn probleem makkelijk behandeld kon worden.",
            "question_SortOrder":1,
            "question_HasScoreAnswer":true,
            "question_HasNpsValueAnswer":false,
            "question_HasTextAnswer":false,
            "question_HasBooleanAnswer":false,
            "question_HasCesScoreAnswer":true,
            "question_HasCsatScoreAnswer":false,
            "question_HasMultipleChoiceAnswer":false,
            "uniqueID":"64b41b3e-256c-4e70-a6bf-6a0b5786f8ba"
         },
         {
            "answer_Text":"Het is heel vriendelijk personeel",
            "answer_Date":"2020-09-29T13:42:37Z",
            "survey_UniqueID":"535503b5-960a-4178-8ac5-d89a886b8085",
            "question_UniqueID":"eb33bd3a-6eb0-4c9a-9121-08aee26851de",
            "question_SiblingUniqueID":"224dc951-3a62-4760-aa62-327d263b8261",
            "question_Text":"<has yet to be completed>",
            "question_SortOrder":2,
            "question_HasScoreAnswer":false,
            "question_HasNpsValueAnswer":false,
            "question_HasTextAnswer":true,
            "question_HasBooleanAnswer":false,
            "question_HasCesScoreAnswer":false,
            "question_HasCsatScoreAnswer":false,
            "question_HasMultipleChoiceAnswer":false,
            "prediction":{
               "items":[
                  {
                     "polarity":"Positive",
                     "paths":[
                        {
                           "order":0,
                           "path":"Personnel>Friendliness"
                        }
                     ]
                  }
               ]
            },
            "uniqueID":"25dac7c4-1d08-4302-8740-3dea0f89cab5"
         }
      ],
      "answerTags":[
         
      ],
      "forwardedMessages":[
         
      ],
      "repliedMessages":[
         
      ],
      "notes":[
         
      ],
      "hasBeenDisabledForReview":false,
      "uniqueID":"36e2cd3f-8ae9-449a-90d0-5270b9e4ceb9"
   }
]

Each question has its own ID per language. Pay attention to use all ID’s when requesting responses from multiple languages.

back to top...

10. API-Call 4 - Get NPS

Send a POST request to:

https://api.hellocustomer.com/V1.0/EN/campaign/{campaignuniqueID}/analysis/nps/getnpsscore/{startDate}/{endDate}

• Make sure to submit your authorization credentials in the header of the POST envelope.
• If you use this request, the time between 2 requests needs to be at least 1 second.

To request the NPS value of a specific department or store, submit the following JSON object within the body of your POST envelope:

[
   {
      "key":"store",
      "filterValues":[
         "Antwerpen"
      ]
   }
]

In this example, the key is "shop" and the specific store is "happyfashion brussels", submitted as an array with 1 value.  

The returned object will be a JSON object like this:

{
   "nps":31,
   "detractors":5.26,
   "passive":57.9,
   "promoters":36.84,
   "date":"2015-12-16T14:45:31.3778294+00:00",
   "uniqueID":"47890417-0442-48a4-b981-4bdd5b41bf0d"
}

back to top...

11. API-Call 5 - Add Answer

Send a POST request to:

https://api.hellocustomer.com/V1.0/EN/campaign/{campaignUniqueID}/answers/add

• Make sure to submit your authorization credentials in the header of the POST envelope.
• If you use this request, the time between 2 requests needs to be at least 1 second.

The body of the POST envelope must be a JSON object:

{
   "cultureInfo":"FR",
   "languageUniqueId":"1B5C1275-4F92-422F-B1FC-799BF8E30598",
   "metadata":{
      "number of pieces":"8",
      "shop":"1"
   },
   "respondent":{
      "UniqueID":null,
      "FirstName":"Jef",
      "LastName":"Tester",
      "Email":"jef@hellocustomer.com",
      "Phone":null
   },
   "CompanyUniqueID":"ec28d381-4883-4731-9462-74c3dc82aff1",
   "answers":[
      {
         "QuestionItemUniqueID":"CFD52369-B323-4CF3-BA11-9ACD0983B01D",
         "Score":3,
         "Text":null,
         "Boolean":null,
         "Options":null
      },
      {
         "QuestionItemUniqueID":"8DEA4E28-9E0C-4E4F-92B0-04F50FEB74CB",
         "Score":null,
         "Text":"J’aime bien américain préparé.",
         "Boolean":null,
         "Options":null
      }
   ],
   "campaign_UniqueID":"f30f55f0-a770-4096-aa9f-8bc2a2aff25f"
}

If you get a response 200 from our server, the answer was successfully added.

Some extra information regarding the JSON object above:

back to top...