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. Date format
  3. Language ID’s
  4. Adding respondents
  5. API call 1 - Adding one respondent at a time
  6. API call 2 - Adding multiple respondents
  7. API call 3 - Request bounced emails
  8. API call 4 - Request unsubscribed emails
  9. API call 5 - Request responses
  10. API call 6 - Get NPS

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

back to top...

2. 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...

3. 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...

4. 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...

5. 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...

6. 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...

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

8. 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...

9. API-Call 5 - Request 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:

[
{
"lastName": "Doe",
"privateIp": "94.224.57.136",
"publicIp": "94.224.57.136:45886",
"email": "john.doe@johnscompany.com",
"custom_UniqueID":"8754864354",
"campaign_UniqueID": "24ef78b1-c0c5-4396-aa03-56fe428c4282",
"language_UniqueID": "1b5c1275-4f92-422f-b1fc-799bf8e30598",
"survey_UniqueID": "7fd2ba87-867b-48f8-9a10-63a90d7fc0e6",
"hasBeenContacted": false,
"hasBeenForwarded": false,
"dateSurveyed": "2015-12-13T17:08:32.997",
"dateAnswer": "2015-12-13T22:10:39.703",
"uniqueID": "47890417-0442-48a4-b981-4bdd5b41bf0d",
"keyValues": {
"pieces": "3",
"shop": "happy fashion antwerp"
},
"answerQuestions": [
{
"answer_Date": "2015-12-13T22:10:39.547",
"answer_Value": 7,
"survey_UniqueID": "7fd2ba87-867b-48f8-9a10-63a90d7fc0e6",
"question_UniqueID": "a315f5f2-4d73-4aa5-a287-4c0256a050f1",
"question_SiblingUniqueID": "fc040396-e41b-4808-bc0b-adb2a7462f7d",
"question_Text": "Hoe tevreden ben je over je laatste bezoek bij Happy Fashion?",
"question_SortOrder": 1,
"question_HasScoreAnswer": true,
"question_HasNpsValueAnswer": true,
"question_HasTextAnswer": false,
"question_HasBooleanAnswer": false,
"uniqueID": "49805ba2-da9f-4d33-ad4e-f091c37758a3"
},
{
"answer_Text": "Verkoopsters in Halle zijn veel veel vriendelijker en behulpzamer! Echt aangenaam
om er te winkelen. Je bent daar geen nummertje. In Sint Niklaas al meermaals een onvriendelijke verkoopster
gehad. Groot verschil tussen beide winkels.",
"answer_Date": "2015-12-13T22:10:39.703",
"survey_UniqueID": "7fd2ba87-867b-48f8-9a10-63a90d7fc0e6",
"question_UniqueID": "acbf07a7-945b-4309-97c1-c937c20002c1",
"question_SiblingUniqueID": "69c9cebc-f3df-4d3b-984a-dfad6a7c6afe",
"question_Text": "Kan je ons vertellen waarom je ons deze score geeft?",
"question_SortOrder": 2,
"question_HasScoreAnswer": false,
"question_HasNpsValueAnswer": false,
"question_HasTextAnswer": true,
"question_HasBooleanAnswer": false,
"uniqueID": "05896080-08b6-4e6a-a971-854190bb8fe5"
}
],
"forwardedMessages": [ ],
"repliedMessages": [ ]
}
]

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

Still need help? Contact Us Contact Us