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 - Request bounced emails
  10. API call 4 - Request unsubscribed emails
  11. API call 5 - Get responses
  12. API call 6 - Get NPS
  13. API call 7 - Add answers

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==


2. General

CampaignUniqueID

This is a unique number which identifies your touchpoint. This main purpose of this identifier is to route the repondents 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, wether you are using an API connector, FTP connection or even when you upload an XLSX file manually, we can make a disctinction between two types of data. The first category is the mandatory data. The minimum set of data we need to send ou surveys involves:

  • firstName, lastName:
    • We always ask to send the firstname and family name to enable the customisation of the survey. As we live in an era where mass emailings are no longer considered as UX friendly, we therefore ask to incorporate these data as mandatory.
  • 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 allways 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

When requesting results within a certain time frame you can submit date parameters (startDate and endDate) using the following format: yyyyMMddHHmmss.
For instance, 15/12/2018 at 3pm would be 20181215150000.

back to top...

4. Language ID’s

Language ID’s can be submitted as following:

1B5C1275-4F92-422F-B1FC-799BF8E30598 Dutch
901AF5BC-06CB-4DE0-B523-135ECFDC882A French
DF88D743-1B99-44EF-B47F-260C78030EE7 English
B913ECA5-638C-4B5C-80FD-4BC9E3B29587 German
3D74560A-9AED-420C-99B8-B6BA8BB92202 Italian
EB89AF5E-C996-47DB-AB22-60AA13A2DBF8 Spanish
D9E0CFDF-034A-4D43-92F9-6AB246A9AA37 Czech
EFCA8E5D-9394-4A19-B805-F6E41AF76921 Danish
90B0555C-F6B0-47F3-A68D-D3A1498D9C09 Estonian
5D82F48C-A6CE-400D-971D-85C2C8677665 Irish
0B086FBC-CFD5-4284-8800-1959D2ECB5EA Croatian
98CF0FB8-234B-49B2-8A6C-23B99B154D52 Latvian
E5366029-C68F-4F8D-93DF-33B9439F9216 Lithuanian
CABFA802-7BB1-46C0-8ACD-2EE75C11C249 Hungarian
D917F99B-D6B7-418C-BC35-77FBA939BBD7 Malti
3AF8680C-3F2B-40F7-8ED3-2783B993CD86 Norsk
0C801A28-7504-4B54-AA8E-3B327A5191B0 Polish
D949E8C8-5E9E-421D-8103-6AA45083578D Portuguese
73EE0C78-C21E-4C0E-97FB-3039B0D0877A Romanian
55C30D14-3ACF-4828-8F95-30B0DC2318B6 Slovac
FB5A68D1-23EB-46D3-B266-F364D2BA56ED Slovenian
A6F3B85B-817D-484F-88CC-2F5249293525 Finnish
F7818F3A-7481-4B3D-BB53-2C4EFF8B5B66 Swedish
B2C03D11-701B-486C-88C0-E019A8461823 Turkish
80CEBA7C-77AE-4A08-ABE9-B9C5CD3F9084 Greek
28526D05-EAF5-4869-9E46-1423921A7CCF Bulgarian
9B576FE6-BA6D-40F4-B779-0101D8B79F7D Russian
C11106F9-E9B0-4AF3-BFE8-EF1497A9FFD0 Chinese


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. For all APIs:

  • 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

b. Add Respondent:

  • 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

c. Add Answers:

  • 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

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 200 from our server, 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 - Request bounced emails

Send a GET request to:

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

  • Make sure to submit your authorization credentials in the header of the GET envelope.
  • This call is only available for email-based touchpoints
  • 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:

	[
{
"dateCreated": "2015-12-13T16:51:55.993",
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@johnscompany.com",
"custom_UniqueID":"8754864354",
"reason_Bounced": "550 #5.1.0 Address rejected. ",
"keyValues": {
"shop": "happy fashion amsterdam",
"pieces": "4"
}
},
{
"dateCreated": "2015-12-13T16:51:20.687",
"firstName": "Jessica",
"lastName": "Day",
"email": "jessica.day@hotmail.com",
"custom_UniqueID":"8754864354",
"reason_Bounced": "550 Requested action not taken: mailbox unavailable ",
"keyValues": {
"shop": "happy fashion amsterdam",
"pieces": "2"
}
}
]

back to top...

10. API-Call 4 - Request unsubscribed emails

Send a GET request to:

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

  • Make sure to submit your authorization credentials in the header of the GET envelope.
  • This call is only available for email-based touchpoints
  • If you use this request, the start date and end date cannot be more than 31 days apart.

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

	[
{
"dateCreated": "2015-12-13T16:51:43.663",
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@johnscompany.com",
"custom_UniqueID":"8754864354",
"type": "Hello Customer",
"keyValues": {
"shop": "happy fashion ghent",
"pieces": "3"
}
},
{
"dateCreated": "2015-12-13T16:50:45.827",
"firstName": "Jessica",
"lastName": "Day",
"email": "jessica.day@hotmail.com",
"custom_UniqueID":"8754864354",
"type": "Hello Customer",
"keyValues": {
"shop": "happy fashion antwerp",
"pieces": "3"
}
}
]

back to top...

11. API-Call 5 - 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...

12. API-Call 6 - 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...

13. API-Call 7 - 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:




languageUniqueId
The languageId for the respondent and answer. 
Language must be a valid GUID and must be available in your touchpoint
metadata List of key value pairs for your metadata
respondent firstName, lastName, email and phone of the participant
companyUniqueId Your company unique id, must be a valid GUID
Answers list of answers
questionItemUniqueID null or numeric value if the question is asking for a score
score the unique id of the question, 
must be a valid GUID and must be used in your touchpoint
boolean null, true or false if question is Yes/No
options null or list of values if the question is a multiple choice question
campaign_uniqueId your touchpointuniqueid, must be a valid GUID

Still need help? Contact Us Contact Us