API Connectors and API Calls (NEW)

We provide several API calls you can use to either send information to our platform, for example, participants and answers, or to get information from our platform, for example, answers. To be able to do this, you need to set up an API connector in the platform. With this connector, you can automatically get a new token every day that can be used to perform API calls.

IMPORTANT

If you are experiencing issues with API connectors and API calls, 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. 

IN THIS ARTICLE

  1. Set up an API connector
    1. How to get there
    2. Manage API connectors
  2. Documentation in postman
  3. Renew token automatically
  4. Available API calls
    1. Read: questions
    2. Add: answers
    3. Read: answers progress
    4. Read: answers
    5. Read: metrics
    6. Read: not delivered
    7. Read: unsubscribed
    8. Add: participant
    9. Read: participants progress
    10. Read: teams
    11. Read: users
    12. Add: user
    13. Assign user to team(s)
    14. Delete: user
  5. Frequently asked questions
    1. Where to find the touchpointuniqueid
    2. Where to find the tenantuniqueid
    3. Which language codes should I use?

1. Set up an API connector

1a. How to get there

Step 1: From the home screen of your Hello Customer account, click the Settings icon in the left navigation menu

Step 2: Open API connectors

  • Click on Integrations in the navigation on the left. The API connectors tab will open automatically

  • Click on the API connectors tile under Integrations

1b. Manage API connectors

As an administrator, you are able to set up at least 1 API connector in your environment. In case this is not sufficient, contact your customer success manager or support@hellocustomer.com.

When there is no API connector yet, you'll end up on an empty screen with a button the Create a new API connector. Once there is an API connector, you'll only have the button on the upper right corner to create a new one

To create an API connector, click the blue button to open a little wizard to set up an API connector. Some things to keep in mind:

  1. Give your connector a clear name.
  2. Activate the fixed IP if this is necessary. Once activated, you need to specify the IP range from which API calls can be performed. Only this IP address will be able to perform API calls. You can make use of an IP range, for example 152.23.251.23/28 (CIDR notation).
  3. Choose the privileges for your API connector. This specifies which API calls can be performed with the tokens generated via this API connector.
    1. read:questions - get all your questions from a touchpoint.
    2. add: answers - add answers from another source to a touchpoint in the Hello Customer platform and get the progress of this upload.
    3. read:answers - get answers from the Hello Customer platform.
    4. read:metrics - get a summary of the main metrics (NPS, CSAT and CES) of your touchpoint.
    5. read:participants - allows you to get a list of all survey emails that were not delivered and all people that unsubscribed from your survey.
    6. add:participants - add participants to a Hello Customer touchpoint and get the progress of this participant upload.
    7. read: teams - get all the teams part of your environment. This call returns all the unique ID's of your teams which can be used as input for other calls, for example in the read:metrics call to get the summary of the main metrics (NPS, CSAT and CES) for a specific team.
    8. read:users - get all the users part of you environment. This call returns all the unique ID's of the users, which can be used as input for other API calls, such as assign user to team(s)
    9. manage:users - this privilege enables you to add users to the platform, assign a user to one or more teams and to delete users.

You can edit an API connector with the pencil to for example add extra privileges. It's possible to delete the API connector when you do not need it anymore by clicking the trash can.


... back to top

2. Documentation in Postman

There is a public workspace on Postman where you can find all the API calls and information on how to use them. Access this workspace here.

... back to top

3. Renew token automatically

Once you have set up an API connector in the platform, you can automatically renew your token every day. To do this, you need the client ID and client secret provided in the platform.


Characteristics API call to ask for a new token:

  • Type: POST
  • URL: https://api-v4.hellocustomer.com/token
  • Body (x-www-form-urlencoded):
    • grant_type: client_credentials
    • client_id: client id from your API connector available in the platform
    • client_secret: client secret from your API connector available in the platform
    • audience: hellocustomer

You can renew your token every day at 00:00 UTC each day. The same token remains valid until the next day 00:00 UTC, but you can only request one token a day. Therefore, you need to cache your requested token for 24 hours and set up a process to renew the token every day after 00:00 UTC.

This is an example in Python how you can renew your token and cache it for 24 hours

— Config file "config.py" with some settings used by API client

CLIENT_ID = "put_your_client_id_generated_via_platform_here"
CLIENT_SECRET = "put_your_client_secret_generated_via_platform_here"
TOKEN_URL = "https://api-v4.hellocustomer.com/token"
API_BASE_URL = "https://api-v4.hellocustomer.com"
AUDIENCE = "hellocustomer"

— Main file "main.py" with an API client helper and example usage (get Questions for a touchpoint)

import requests
from datetime import datetime, timedelta
import config  # Assuming config.py is defined separately

class APIClient:
    token_cache = {}
    token_expiration_cache = {}

    def __init__(self, config):
        self.client_id = config.CLIENT_ID
        self.client_secret = config.CLIENT_SECRET
        self.token = None
        self.expires_at = None

        self.token_url = config.TOKEN_URL
        self.api_base_url = config.API_BASE_URL

    def get_auth_token(self):
        if self.token and self.expires_at and datetime.utcnow() < self.expires_at:
            self.token = self.token_cache[self.client_id]
            self.expires_at = self.token_expiration_cache[self.client_id]
        else:
            payload = {
                "grant_type": "client_credentials",
                "client_id": self.client_id,
                "client_secret": self.client_secret,
                "audience": config.AUDIENCE
            }

            response = requests.post(self.token_url, data=payload)
            if response.status_code == 200:
                token_data = response.json()
                self.token = token_data.get("access_token")
                expires_in = token_data.get("expires_in")
                self.expires_at = datetime.utcnow() + timedelta(seconds=expires_in)

                # Cache the token and its expiration time
                self.token_cache[self.client_id] = self.token
                self.token_expiration_cache[self.client_id] = self.expires_at
            else:
                raise Exception("Failed to obtain Auth0 token")

    def refresh_auth_token(self, refresh_token):
        payload = {
            "grant_type": "refresh_token",
            "refresh_token": refresh_token,
            "client_id": self.client_id,
            "client_secret": self.client_secret,
        }

        response = requests.post(self.token_url, data=payload)
        if response.status_code == 200:
            token_data = response.json()
            self.token = token_data.get("access_token")
            expires_in = token_data.get("expires_in")
            self.expires_at = datetime.utcnow() + timedelta(seconds=expires_in)

            # Cache the refreshed token and its expiration time
            self.token_cache[self.client_id] = self.token
            self.token_expiration_cache[self.client_id] = self.expires_at
        else:
            raise Exception("Failed to refresh Auth0 token")

    def get_questions(self, tenantId, touchpointId):
        api_url = f"{self.api_base_url}/core/v4.0/EN/tenant/{tenantId}/touchpoint/{touchpointId}/questions"

        self.get_auth_token()
        auth_token = self.token

        headers = {"Authorization": f"Bearer {auth_token}"}

        response = requests.get(api_url, headers=headers)
        if response.status_code == 200:
            return response.json()
        elif response.status_code == 401:
            # Token expired, refresh the token and retry the request
            refresh_token = self.token
            self.refresh_auth_token(refresh_token)

            headers = {"Authorization": f"Bearer {self.token}"}
            response = requests.get(api_url, headers=headers)

            if response.status_code == 200:
                return response.json()
            else:
                raise Exception("Failed to retrieve questions after token refresh")
        else:
            raise Exception("Failed to retrieve questions")

# Example usage: questions = client.get_questions(tenantuniqueid, touchpointuniqueid)
client = APIClient(config)
questions = client.get_questions("bfec2cbb-fa3f-4e0f-a64a-eda5d8b3393a","f4b4c5d5-a22b-4f61-9d61-1f2bb57a829f")
print(questions)

... back to top

4. Available API calls

Following API calls can be performed with an API connector that has the correct privileges.

4a. Read: questions

General description: This API call will return all the questions in all languages for your touchpoints, including the question unique id's you need to use in the API call Add: Answers.


API information

  • Type: GET
  • URL: https://api-v4.hellocustomer.com/tenant/{tenantuniqueid}/touchpoint/{touchpointuniqueid}/questions
  • Authorization: token that was generated for today

Response

The response consists of all questions available in the touchpoint in all languages. The same question in several languages have the same question unique id. This id can be used as input for the add answers API to add answers to a specific question.


Examples of the returned JSON

  • Touchpoint with 1 metric question (CSAT) in 1 language:
[
    {
        "questionUniqueId": "f35636e8-aea8-4a86-b225-08db3b6c8706",
        "questionType": "CSAT",
        "language": "EN",
        "questionText": "How satisfied are you with $$$_TeamName_$$$",
        "isMandatory": true,
        "openFeedbackQuestionText": "Can you explain why you gave this score?",
        "isOpenFeedbackMandatory": true,
        "isActive": true,
        "scoreLabels": [
            {
                "score": 1,
                "text": "very unsatisfied"
            },
            {
                "score": 5,
                "text": "very satisfied"
            }
        ],
        "multipleChoiceOptions": null
    }
]
  • Touchpoint with 2 questions (NPS and a custom question) in 5 languages
[
    {
        "questionUniqueId": "2a37785a-746a-493c-f5ea-08db61b7ab24",
        "questionType": "NPS",
        "language": "ES",
        "questionText": "¿Qué probabilidad hay de que recomiendes Happy Fashion a tus amigos y conocidos? ",
        "isMandatory": true,
        "openFeedbackQuestionText": "¿Puedes explicarnos por qué has elegido esa puntuación?",
        "isOpenFeedbackMandatory": true,
        "isActive": true,
        "scoreLabels": [
            {
                "score": 0,
                "text": "Absolutamente no"
            },
            {
                "score": 10,
                "text": "Absolutamente"
            }
        ],
        "multipleChoiceOptions": null
    },
    {
        "questionUniqueId": "2a37785a-746a-493c-f5ea-08db61b7ab24",
        "questionType": "NPS",
        "language": "DE",
        "questionText": "Wie wahrscheinlich ist es, dass Sie Happy Fashion Freunden oder Bekannten empfehlen würden?",
        "isMandatory": true,
        "openFeedbackQuestionText": "Können Sie uns mitteilen, warum Sie uns diese Bewertung geben?",
        "isOpenFeedbackMandatory": true,
        "isActive": true,
        "scoreLabels": [
            {
                "score": 0,
                "text": "Überhaupt nicht"
            },
            {
                "score": 10,
                "text": "Ja"
            }
        ],
        "multipleChoiceOptions": null
    },
    {
        "questionUniqueId": "2a37785a-746a-493c-f5ea-08db61b7ab24",
        "questionType": "NPS",
        "language": "FR",
        "questionText": "Dans quelle mesure conseilleriez-vous Happy Fashion à vos amis, connaissances et collègues?",
        "isMandatory": true,
        "openFeedbackQuestionText": "Pouvez-vous nous expliquer le score que vous nous attribuez?",
        "isOpenFeedbackMandatory": true,
        "isActive": true,
        "scoreLabels": [
            {
                "score": 0,
                "text": "Pas du tout"
            },
            {
                "score": 10,
                "text": "Certainement"
            }
        ],
        "multipleChoiceOptions": null
    },
    {
        "questionUniqueId": "2a37785a-746a-493c-f5ea-08db61b7ab24",
        "questionType": "NPS",
        "language": "EN",
        "questionText": "How likely is it that you would recommend Happy Fashion to a friend or colleague?",
        "isMandatory": true,
        "openFeedbackQuestionText": "What's the most important reason for your score?",
        "isOpenFeedbackMandatory": true,
        "isActive": true,
        "scoreLabels": [
            {
                "score": 0,
                "text": "Not at all likely"
            },
            {
                "score": 10,
                "text": "Very Likely"
            }
        ],
        "multipleChoiceOptions": null
    },
    {
        "questionUniqueId": "1d539157-f135-4494-f5eb-08db61b7ab24",
        "questionType": "Text",
        "language": "DE",
        "questionText": "Custom question DE",
        "isMandatory": false,
        "openFeedbackQuestionText": null,
        "isOpenFeedbackMandatory": null,
        "isActive": true,
        "scoreLabels": null,
        "multipleChoiceOptions": null
    },
    {
        "questionUniqueId": "1d539157-f135-4494-f5eb-08db61b7ab24",
        "questionType": "Text",
        "language": "ES",
        "questionText": "Custom question ES",
        "isMandatory": false,
        "openFeedbackQuestionText": null,
        "isOpenFeedbackMandatory": null,
        "isActive": true,
        "scoreLabels": null,
        "multipleChoiceOptions": null
    },
    {
        "questionUniqueId": "1d539157-f135-4494-f5eb-08db61b7ab24",
        "questionType": "Text",
        "language": "EN",
        "questionText": "Custom question EN",
        "isMandatory": false,
        "openFeedbackQuestionText": null,
        "isOpenFeedbackMandatory": null,
        "isActive": true,
        "scoreLabels": null,
        "multipleChoiceOptions": null
    },
    {
        "questionUniqueId": "1d539157-f135-4494-f5eb-08db61b7ab24",
        "questionType": "Text",
        "language": "FR",
        "questionText": "Custom question FR",
        "isMandatory": false,
        "openFeedbackQuestionText": null,
        "isOpenFeedbackMandatory": null,
        "isActive": true,
        "scoreLabels": null,
        "multipleChoiceOptions": null
    }
]

... back to top

4b. Add: answers

General description: Using this API call, you are able to add answers for several questions in your touchpoint. You can also include metadata and participant information like names and email addresses.


API information

  • Type: POST
  • URL: https://api-v4.hellocustomer.com/tenant/{tenantUniqueId}/Answer/AddAnswerBatch
  • Authorization: token that was generated for today

Body:

Add following information in the body:

    • General information
      • tenantuniqueid
      • touchpointuniqueid
    • SurveyAnswers
      • Provide a surveyAnswerUniqueId for each individual survey (= set of answers on all questions of the touchpoint for 1 person). This should be a guid and must be unique for each individual set of answers. You can easily generate random guids on this website.
      • Language code
      • Participant information (optional)
        • firstName
        • lastName
        • emailAddress
        • phoneNumber
        • customerId
      • Metadata: provide a key and a value. You can add whatever you want as metadata
      • Date: the answer date. The uploaded answer(s) will be shown in the platform on this date
      • Per answer on a question: questionuniqueid and the answer (score and / or text). The read: questions API call will give you more information on the id's you need. An example of each type of question is shown in the body below, but these are the general rules:
        • For CSAT, NPS, and CES, specify the "score" and "text".
        • For 0-10 questions, use the "score".
        • For multiple choice questions, use "multipleChoice", where you put all the selected options between the [].
        • For yes-or-no questions, use "yesNo", where true stands for "yes" and false is equal to "no".
        • For a custom question, you only need to add the "text".
      • You can add more than 1 survey answer at a time

IMPORTANT

Per environment, there is a limit of uploading 100k surveys per day. If you would need to upload more answers, you can spread the upload over a few days or contact support@hellocustomer.com for more information.

This is an example of the body that includes participant information, metadata and answers to all types of questions:

{
  "touchpointUniqueId": "29f817b0-81ff-4a0c-bb04-3f1112ceeea4",
  "surveyAnswers": [
    {
      "surveyAnswerUniqueId": "d172ebd8-bc92-4514-a746-d06b3283b02b",
      "languageCode": "EN",
      "participantInfo": {
        "firstName": "John",
        "lastName": "Doe",
        "emailAddress": "john@hellocustomer.com",
        "phoneNumber": "0472540278",
        "customerId": "123456"
      },
      "metaData": {
        "additionalProp1": "value 1",
        "additionalProp2": "value 2",
        "additionalProp3": "value 3"
      },
      "date": "2023-08-17",
      "answers": [
        {
          "questionItemUniqueId": "a60a98ab-9ab3-416f-3da6-08db837ffd28",
          "score": 0,
          "text": "helemaal niet"
        },
        {
          "questionItemUniqueId": "f3b5e687-5494-4f65-3063-08db8385f12b",
          "score": 3,
          "text": "It was a bit difficult to make a reservation with the app. It's not very intuitive"
        },
        {
          "questionItemUniqueId": "375e3654-7ce1-4a43-425d-08db837c7c87",
          "score": 5,
          "text": ""
        },
        {
          "questionItemUniqueId": "91f6f659-87a5-4c6a-425e-08db837c7c87",
          "score": 6,
        },
        {
          "questionItemUniqueId": "65dad4a2-ec64-4cb1-3066-08db8385f12b",
          "multipleChoice": [
             "Option 1",
             "Option 2"
           ]
        },
        {
          "questionItemUniqueId": "23b8e320-978d-458d-3da7-08db837ffd28",
          "yesNo": false
        },
        {
          "questionItemUniqueId": "4a655562-4c45-4039-3da9-08db837ffd28",
          "text": "anything"
        }
      ]
    }
  ]
}

Response

In case the API call succeeds, it will return a batch id. This id can be used to follow up on the progress of the answer upload. For this, use the API call read: answer progress.

... back to top

4c. Read: answer progress

General description: With the read: answer progress API call, it is possible to follow-up on your add: answers API call. You need the batch id that is returned after performing the add: answers API call to be able to do this API call. You can perform this API call with every API connector that has the privilege to add answers.


API information

  • Type: GET
  • URL: https://api-v4.hellocustomer.com/tenant/{tenantUniqueId}/Answer/batch/{batchUniqueId}/progress
  • Authorization: token that was generated for today

Response

In the response, you'll get an overview of:

  • Amount of processed answers (combination of all answers for 1 survey)
  • Amount of answers that are still processing
  • Invalid answers
  • Total answers in the batch
  • Errors: specification of why the invalid answers are invalid. Possible reasons why an answer is invalid (not exhaustive):
    • Language is missing or not part of the touchpoint
    • Answer on a mandatory question is missing
    • Value for a mandatory metadata key is missing
    • Date of the answer is in the future
    • Value of the answer does not fit the question (for example: score 11 on a NPS question)

Example:

{
    "processed": 0,
    "processing": 1,
    "invalid": 0,
    "total": 1,
    "errors": []
}

... back to top

4d. Read: answers

General description: With the read: answers API call, it is possible to extract the answers from the Hello Customer platform for a specific touchpoint.

API information
  • Type: POST
  • URL: https://api-v4.hellocustomer.com/tenant/{tenantUniqueId}/answer/touchpoint/{touchpointUniqueId}/getanswers
  • Authorization: token that was generated for today

Body

In the body, you need to specify the date range for which you want to retrieve the answers. The start and end date can not be more than 31 days apart. You can also specify the language in which you want to retrieve the ISAAC analysis: FR for French or EN for English.

{
    "StartDate" : "2023-06-01 00:00:00",
    "EndDate" : "2023-06-29 12:28:59",
    "LanguageCode" : "EN"
}
Response

Below, you can find an example, but in general, in the response you will get per participant:

  • Participant information:
    • A unique id per participant so you can historically link all answers of the same person
    • Personal information about the participant: first name, last name, email address, phone number and customer id. If some participant information is not available, this will return NULL.
  • Survey information
    • Touchpointuniqueid to link the answer to the correct survey.
    • Date answered: date the survey was filled out.
    • Date surveyed: date the respondent received the survey invitation. For Ask Anywhere, Website and In-App touchpoints, the survey date will be the same as the answer date.
    • Touchpointuniqueid.
  • Metadata: all the keys and values linked to this participant. This also includes the language in which the participant filled out the survey.
  • Conversation information (only available for answers since 1/1/2023)
    • Status
    • Tags
    • Summary
  • Answers
    • Survey answer unique ID: a unique ID for the whole survey, so the total set of questions a participant filled out at the date the survey was answered.
    • Predictions: ISAAC analysis per relevant question. In other words: open text questions linked to a metric. The language code refers to the one you included in the request body and shows in which language the paths are shown. You can choose between English (EN) and French (FR).
    • Answers on all questions of the survey. The answers are shown per question. The question unique ID is the same ID you find in the read:questions API call. You'll notice that some of them have the same question unique ID. That's the case for NPS, CSAT and CES questions, since the score and open text feedback are seen as an indivisible group of questions.
    • Sort order: the order in which the questions were presented to the participant.
    • Special cases: if you add questions to collect metadata to your survey (the team picker, date picker and / or profile question), these questions will be added in the answers object, but with answer "null".
      • For team and date picker questions, the answers will be included in the metadata.
      • The answers on the profile question are included in the participant info.

An example of a response with multiple questions:

[
    {
        "participantInfo": {
            "uniqueId": "d325a00d-6ec4-4ad8-65df-08dbfd49037b",
            "languageCode": "english",
            "firstName": "John",
            "lastName": "Doe",
            "emailAddress": "john.doe@example.com",
            "phoneNumber": "+32123456789",
            "customerId": null
        },
        "touchpointUniqueId": "e3446880-846f-4869-9529-c37a9b09c713",
        "dateAnswered": "2023-12-18T13:32:12",
        "dateSurveyed": "2023-12-18T13:32:12",
        "metadata": {
            "date": "12/11/2023 11:00:00 pm",
            "language": "en",
            "team": "team 1"
        },
        "status": "ToDo",
        "tags": null,
        "summary": null,
        "surveyAnswerUniqueId": "323ef28d-29c5-458b-a061-10110550f12f",
        "predictions": [
            {
                "path": "Overall Experience>Overall Experience",
                "isPositive": true,
                "isNegative": false,
                "isNeutral": false,
                "metric": "nps",
                "text": "very satisfied",
                "languageCode": "en"
            },
            {
                "path": "Overall Experience>Overall Experience",
                "isPositive": true,
                "isNegative": false,
                "isNeutral": null,
                "metric": "ces20",
                "text": "very easy",
                "languageCode": "en"
            }
        ],
        "answers": [
            {
                "answer": "10",
                "question": "How likely is it that you would recommend Happy fashion to a friend or colleague?",
                "question_unique_id": "38fef658-02f4-444d-d858-08dbfd6c49f3",
                "sort_order": 1
            },
            {
                "answer": "very satisfied",
                "question": "What's the most important reason for your score?",
                "question_unique_id": "38fef658-02f4-444d-d858-08dbfd6c49f3",
                "sort_order": 2
            },
            {
                "answer": "7",
                "question": "To what extent do you agree or disagree with following statement: Happy fashion made it easy for me to handle my issue.",
                "question_unique_id": "b5759dba-3d75-4fd8-67fb-08dbfd6c530e",
                "sort_order": 3
            },
            {
                "answer": "very easy",
                "question": "What is the most important reason for your score?",
                "question_unique_id": "b5759dba-3d75-4fd8-67fb-08dbfd6c530e",
                "sort_order": 4
            },
            {
                "answer": "5",
                "question": "To what extent are you satisfied with your recent experience with Happy fashion?",
                "question_unique_id": "6fa06bc3-461a-4f58-a59e-08dbfd6ce354",
                "sort_order": 5
            },
            {
                "answer": null,
                "question": "What's the most important reason for your score?",
                "question_unique_id": "6fa06bc3-461a-4f58-a59e-08dbfd6ce354",
                "sort_order": 6
            },
            {
                "answer": "9",
                "question": "On a scale of 0-10, how happy are you with the staff at Happy fashion?",
                "question_unique_id": "9e12d974-e23f-4ae4-a59f-08dbfd6ce354",
                "sort_order": 7
            },
            {
                "answer": "true",
                "question": "Are you planning to come back to Happy fashion in the future?",
                "question_unique_id": "52235dda-4433-45f2-a5a0-08dbfd6ce354",
                "sort_order": 9
            },
            {
                "answer": null,
                "question": "Which shop of Happy fashion did you visit?"
                "question_unique_id": "8adc8e72-1365-42a9-d85a-08dbfd6c49f3",
                "sort_order": 11
            },
            {
                "answer": null,
                "question": "On which date did you visit the Happy fashion shop?",
                "question_unique_id": "84a78e27-ea05-48cc-a5a1-08dbfd6ce354",
                "sort_order": 12
            },
            {
                "answer": "Accessories;Clothes",
                "question": "What kind of products did you buy?",
                "question_unique_id": "70ec28bb-5ccb-49b5-a5a2-08dbfd6ce354",
                "sort_order": 13
            },
            {
                "answer": "Via social media",
                "question": "How did you get to know us?",
                "question_unique_id": "e43d1e8d-18c0-4375-a5a3-08dbfd6ce354",
                "sort_order": 14
            }
            {
                "answer": "I really like the shop! Keep up the good work",
                "question": "Is there anything else you want to mention?"
                "question_unique_id": "b99e086a-64b8-4f64-d85b-08dbfd6c49f3",
                "sort_order": 15
            },
        ]
    }
]

... back to top

4e. Read: metrics

General description: With the read: metrics API call, you get a summary of the main metrics (NPS, CSAT and CES) for a specific touchpoint.

API information
  • Type: POST
  • URL: https://api-v4.hellocustomer.com/tenant/{tenantUniqueId}/touchpoint/{touchpointUniqueId}/Metrics
  • Authorization: token that was generated for today

Body
In the body, you can specify the date range for which you want to retrieve the metric summary. You can specify the start and end date, but it's not obliged. If no dates are specified, the call will return a summary of the metrics with all answers included. 
{
    "StartDate" : "2023-06-01 00:00:00",
    "EndDate" : "2023-06-29 12:28:59"
}

Response

In the response you will get a summary per metric. In case a specific metric is not available in the touchpoint, the metric will get "null" as output.
  • Example for a touchpoint with all three metrics:
{
    "nps": {
        "promoters": {
            "responses": 7.0,
            "percentage": 77.7777
        },
        "passives": {
            "responses": 1.0,
            "percentage": 11.1111
        },
        "detractors": {
            "responses": 1.0,
            "percentage": 11.1111
        },
        "totalResponses": 9,
        "score": 66.6667
    },
    "ces": {
        "agree": {
            "responses": 6.0,
            "percentage": 66.6666
        },
        "disagree": {
            "responses": 3.0,
            "percentage": 33.3333
        },
        "totalResponses": 9,
        "score": 4.888889
    },
    "csat": {
        "unsatisfied": {
            "responses": 1.0,
            "percentage": 11.1111
        },
        "neutral": {
            "responses": 2.0,
            "percentage": 22.2222
        },
        "satisfied": {
            "responses": 6.0,
            "percentage": 66.6666
        },
        "totalResponses": 9,
        "score": 66.6667
    }
}
  • Example for a touchpoint with only one metric:
{
    "nps": null,
    "ces": null,
    "csat": {
        "unsatisfied": {
            "responses": 0.0,
            "percentage": 0.0
        },
        "neutral": {
            "responses": 0.0,
            "percentage": 0.0
        },
        "satisfied": {
            "responses": 2.0,
            "percentage": 100.0
        },
        "totalResponses": 2,
        "score": 100.0
    }
}

... back to top

4f. Read: not delivered

General description: With the read: not delivered API call, you get a list of all the invitation emails that did not reach your respondents.

API information
  • Type: POST
  • URL: https://api-v4.hellocustomer.com/tenant/{tenantUniqueId}/participant/getundelivered
  • Authorization: token that was generated for today

Body
In the body, you can specify:
  • A specific touchpoint for which you want to get this information (touchpointUniqueId), this is not mandatory. If not specified, you get a list of all undelivered emails for your whole environment.
  • The date range for which you want to retrieve the emails that were not delivered.
{  
  "touchpointUniqueId": "{{touchpointUniqueId}}",
  "startDate": "2023-08-11 08:19:41",
  "endDate": "2023-09-11 08:19:41"
}
Response
In the response you will get per invitation email that was not delivered:
  • the reason why the email was not delivered
  • the date the participant was added to the platform
  • the participant information: first name, last name and email address
[
    {
        "exclusionReason": "Bounced",
        "date_Uploaded": "2023-09-12 08:32:57",
        "firstName": "osborne",
        "lastName": "roberts",
        "emailAddress": "thisemaildoesnotexist@gmail.com"
    },
    {
        "exclusionReason": "Bounced",
        "date_Uploaded": "2023-09-04 14:54:24",
        "firstName": "a",
        "lastName": "k",
        "emailAddress": "john.doe@hellocustomer.com"
    }
]

... back to top

4g. Read: unsubscribed

General description: With the read: unsubscribed API call, you get a list of all the people that unsubscribed from your surveys.

API information
  • Type: POST
  • URL: https://api-v4.hellocustomer.com/tenant/{tenantUniqueId}/participant/getunsubscribed
  • Authorization: token that was generated for today

Body
In the body, you can specify:
  • A specific touchpoint for which you want to get this information (touchpointUniqueId). This is not mandatory. If not specified, you get a list of all unsubscribed emails for your whole environment.
  • The date range for which you want to retrieve the people that unsubscribed.
{  
  "touchpointUniqueId": "{{touchpointUniqueId}}",
  "startDate": "2023-08-11 08:19:41",
  "endDate": "2023-09-11 08:19:41"
}
Response
In the response you will get per invitation email that was not delivered:
  • the date the participant unsubscribed from your surveys
  • the participant information: first name, last name and email address
[
    {
        "exclusionReason": "Unsubscribed",
        "date_Unsubscribed": "2023-08-24 11:25:17",
        "firstName": null,
        "lastName": null,
        "emailAddress": "john+unsubscribed@hellocustomer.com"
    }
]

... back to top

4h. Add: participant

General description: With the add: participant API call, you can add participants in an automated way to your touchpoint so they receive the survey invitation.

API information
  • Type: POST
  • URL: https://api-v4.hellocustomer.com/tenant/{tenantUniqueId}/Participant/AddParticipantBatch
  • Authorization: token that was generated for today

Body
In the body, you can add all the needed information:
  • Touchpoint unique ID: to add the participants to the correct touchpoint so they receive the correct survey.
  • One or multiple participants. Per participant, fill out:
    • Language code: use the ISO language code to define in which language the participant should receive the e-mail invitation. Make sure the language is part of the touchpoint to which you add the participant. This is mandatory.
    • Personal information about the participant. Only email address is a mandatory field.
    • Extra metadata you know about the participant and you want to use to personalize the survey and / or filter on customer groups in the platform.

IMPORTANT

Per environment, there is a limit of uploading 200k participants per day. If you would need to upload more participants, you can spread the upload over a few days or contact support@hellocustomer.com for more information.

This is an example of a body where you add two participants to a touchpoint:

{
  "touchpointUniqueId": "adeb80a4-d437-4308-a0cb-867bf68e9ed5",
  "participants": [
    {
      "languageCode": "NL",
      "firstName": "John",
      "lastName": "Day",
      "emailAddress": "john.day@hellocustomer.com",
      "phoneNumber": "0456232141",
      "customerId": "xyz123",
      "metaData": {
        "shop": "Gent"
                  }
    },
    {
      "languageCode": "NL",
      "emailAddress": "jessica.doe@hellocustomer.com",
      "phoneNumber": "0498765432",
      "customerId": "xyz124",
      "metaData": {
        "shop": "Antwerpen"
                  }
    }
  ]
}
Response
In the response you will get a batchuniqueid which you can use to perform the API call Read: participants progress to follow up on the progress of your participant upload.

... back to top

4i. Read: participants progress

General description: With the read: participants progress API call, it is possible to follow-up on the participants you added via the add: participants API call. You need the batch id that is returned after performing the add: participants API call to be able to do this API call. You can perform this API call with every API connector that has the privilege to add participants.


API information

  • Type: GET
  • URL: https://api-v4.hellocustomer.com/tenant/{tenantUniqueId}/Participant/batch/{batchUniqueId}/progress
  • Authorization: token that was generated for today

Response

In the response, you'll get an overview of:

  • Amount of processed participants
  • Amount of participants that are still processing
  • Invalid participants
  • Total participants in the batch
  • Errors: specification of why the invalid participants are invalid. Possible reasons why a participant is invalid (not exhaustive):
    • Language is missing or not part of the touchpoint
    • E-mail address is missing
    • Value for a mandatory metadata key is missing

Example:

{
    "processed": 10,
    "processing": 0,
    "invalid": 1,
    "total": 11,
    "errors": [
        {
            "surveyAnswerUniqueId": "5ee8b65d-a8d7-4ef4-a910-d588a8000625",
            "errorMessages": [
                "Language Italiano is not connected to this touchpoint (NPS Happy Fashion)"
            ]
        }
    ]
}

... back to top

4j. Read: teams

General description: With the read: teams API call, it is possible to retrieve all the teams present in your environment, including aliases and the whole structure per root team. To learn more about teams, read this article. The team unique ID's you retrieve with this API call, can be used as input for other API calls, for example, to get the metric summary for a specific team.


API information

  • Type: GET
  • URL: https://api-v4.hellocustomer.com/tenant/{tenantUniqueId}/team/tree
  • Authorization: token that was generated for today

Response

The response includes:

  • All the root teams. The root team is the team that is directly linked to your touchpoint.
  • The whole team structure, which includes all children of the root team, their children, and so on.
  • Per team:
    • Team unique ID: this can be used as input for other API calls, for example, to get the metric summary for a specific team.
    • Name: the name of the team
    • Alias: the alias you defined for the team. If defined, this alias is shown everywhere in the platform instead of the team name
    • Parent unique ID: the team unique ID of the team that is directly above this team in the tree structure
    • Children: the teams with all their information that are directly below this team in the tree structure

Example:

[
    {
        "teamUniqueId": "b3410181-6f1f-4a1c-a137-04da39964870",
        "name": "Root team - Name",
        "alias": "Root team - Alias",
        "parentUniqueId": null,
        "children": [
            {
                "teamUniqueId": "83856627-23be-42e1-a6ca-6e306d98cba2",
                "name": "Subteam 1",
                "alias": "Alias of subteam 1",
                "parentUniqueId": "b3410181-6f1f-4a1c-a137-04da39964870",
                "children": [
                    {
                        "teamUniqueId": "d6470c71-fd68-4262-80b2-e322590f5c7f",
                        "name": "Child 1 of subteam 1",
                        "alias": null,
                        "parentUniqueId": "83856627-23be-42e1-a6ca-6e306d98cba2",
                        "children": []
                    },
                    {
                        "teamUniqueId": "f62f838e-cb9e-4f75-b73c-88b2ace9b8ab",
                        "name": "Child 2 of subteam 1",
                        "alias": null,
                        "parentUniqueId": "83856627-23be-42e1-a6ca-6e306d98cba2",
                        "children": []
                    }
                ]
            },
            {
                "teamUniqueId": "27bdb8ed-de87-411d-b506-815727afda8d",
                "name": "Subteam 2",
                "alias": "",
                "parentUniqueId": "b3410181-6f1f-4a1c-a137-04da39964870",
                "children": [     
                    {
                        "teamUniqueId": "decd0b6f-8b3b-4944-b2ea-b5cb84c40076",
                        "name": "Child 1 of subteam 2",
                        "alias": "",
                        "parentUniqueId": "27bdb8ed-de87-411d-b506-815727afda8d",
                        "children": []
                    }
                ]
            },
            {
                "teamUniqueId": "51ae9a98-34db-4f4b-89c4-383c58c73268",
                "name": "Subteam 3",
                "alias": null,
                "parentUniqueId": "b3410181-6f1f-4a1c-a137-04da39964870",
                "children": []
            }
        ]
    }
]

... back to top

4k. Read: users

General description: With the read: users API call, it is possible to retrieve all the users present in your environment The user unique ID's you retrieve with this API call, can be used as input for other API calls, for example, to assign a user to a specific team or delete the user.


API information

  • Type: GET
  • URL: https://api-v4.hellocustomer.com/tenant/{tenantUniqueId}/user
  • Authorization: token that was generated for today

Response

The response includes all users within your environment and per user

  • The Unique ID for the user, which can serve as input for other API calls, such as assigning a user to a team or deleting that user.
  • All personal information about the user.
    • First name
    • Last name
    • E-mail address
    • Title
    • Phone number split in the country code and the phone number itself
    • Language code: the platform language of this user. They can adapt this language themselves in their profile.
  • Is administrator: indicates whether this user is an administrator (true) or not (false)
  • The last login date represents the last time this user entered the platform
  • Teams: the unique ID's of all teams the user is linked to. Use the read:teams API call to link the unique ID to the team name and alias. For administrators, this will be empty, since administrators are not linked to a specific team, but can see everything.

Example:

[
    {
        "uniqueId": "b0dc633d-80b8-494d-b3ea-04596548fcbf",
        "firstName": "John",
        "lastName": "Doe",
        "emailAddress": "john.doe@hellocustomer.com",
        "title": "Support agent",
        "phoneCountryCode": "032",
        "phoneNumber": "45623214",
        "isAdministrator": false,
        "languageCode": "EN",
        "lastLoginDate": "2024-03-19T15:51:11.443",
        "teams": [
            "47980219-e7a2-4286-03db-08dc2effc495"
        ]
    },
    {
        "uniqueId": "66afddee-e52e-4676-bcdf-ecf2f1f9a8ef",
        "firstName": "Janneke",
        "lastName": "Jansen",
        "emailAddress": "janneke.jansen@hellocustomer.com",
        "title": "",
        "phoneCountryCode": "",
        "phoneNumber": "",
        "isAdministrator": true,
        "languageCode": "NL",
        "lastLoginDate": null,
        "teams": []
    }
]

... back to top

4l. Add: user

General description: With the add: user API call, you can add a user to your environment.


API information
  • Type: POST
  • URL: https://api-v4.hellocustomer.com/tenant/{tenantUniqueId}/User
  • Authorization: token that was generated for today

Body
In the body, you can add all the needed information:
  • Mandatory fields:
    • First name
    • Last name
    • E-mail address
    • Is administrator: true (if this person can be an administrator) or false
    • Language code: all languages available as platform language can be chosen (DE, EN, ES, FR, IT, NL and PT)
  • Optional fields:
    • Phone code: first part of the phone number which specifies the country. For Belgium this is 032
    • Phone number: the rest of the phone number
    • Title

This is an example of a body to add a user to your environment

{
  "firstName": "Jessice",
  "lastName": "Day",
  "emailAddress": "jessica.day@hellocustomer.com",
  "isAdministrator": false,
  "phoneCode": "032",
  "phoneNumber": "45623214",
  "title": "CCO",
  "languageCode": "EN"
}

... back to top

4m. Assign user to team(s)

General description: With this call, you can assign a user to one or more teams.

  • Use the read:users API call to get the unique ID of the user you want to assign to one or more teams.
  • Use the read:teams API call to get the unique ID's of the teams you want to add the user to.

API information
  • Type: PUT
  • URL: https://api-v4.hellocustomer.com/tenant/{tenantUniqueId}/User/{userUniqueId}/teams
  • Authorization: token that was generated for today

Body

In the body, specify one or more teams to which you want to add the user.

INFO

  • If a user is already part of a team, and you want to change the team, only include the new team you want to add the user to in the body.
  • If a user is already part of a team, and you want to add the user to an extra team, both include the current team and the new team you want to add the user to in the body.
  • This is an example body to add a user to one team
{
  "teams": [
    "228c4366-0a93-40f0-c0fb-08dc2f6cecc4"
  ]
}
  • This is an example body to add a user to three teams
{
  "teams": [
    "228c4366-0a93-40f0-c0fb-08dc2f6cecc4",
    "6a9ad8c4-8b52-4616-8f2d-4c3bdb739592",
    "e1d61e0e-a09a-42db-8465-669bcfcd57c0"
  ]
}

... back to top

4n. Delete: user

General description: With the delete: user API call you can delete a user from your environment. This user won't have any access anymore to the platform after you performed this API call. Use the read:users API call to get the unique ID of the user you want to delete.


API information

  • Type: DELETE
  • URL: https://api-v4.hellocustomer.com/tenant/{tenantUniqueId}/user/{userUniqueId}
  • Authorization: token that was generated for today

... back to top

5. Frequently asked questions

5a. Where to find the touchpointuniqueid?

Most API calls will perform an action linked to a specific touchpoint. Therefore, you need the touchpointuniqueid.

You can find this in 'Touchpoints' in the 'Touchpoint settings' panel. Use the duplicate icon to easy copy the touchpoint unique id.

5b. Where to find the tenantuniqueid?

For almost all API calls you will need the tenantuniqueid. This id represents the specific Hello Customer environment of your company.

You can find this in 'Touchpoints' in the 'Touchpoint settings' panel. Use the duplicate icon to easy copy the touchpoint unique id.

5c. Which language codes should I use?

As input for the different API calls, you can use the ISO standard language codes.

Language Language code
Arabic AR
Bulgarian BG
Czech CS
Danish DA
German DE
Greek EL
English EN
Spanish ES
Estonian ET
Finnish FI
French FR
Irish GA
Croatian HR
Hungarian HU
Italian IT
Lithuanian LT
Latvian LV
Maltese MT
Dutch NL
Norwegian NO
Polish PL
Portuguese PT
Romanian RO
Russian RU
Slovaki SK
Slovenian SL
Swedish SV
Turkish TR
Chinese ZH
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us