API Setup


Choose your Host Region to have the documentation adapt to your use case.


Host Region
LabelValue
EUeu
USus
AUau






Business Use Case

Our PUT Records API has a wide variety of applications. The API allows you to create or update a single record into any of the following objects while also sending a survey:

  • Account
  • Contact
  • Survey (no update supported)


After a successful request, the data will be uploaded/updated in the system and a survey will be sent to the contact referenced.






Good to Know


Changes to Import Configurations

If a change happens to the implementation of the API (for example a field name change), that should be reflected in the used Inbound Mapping as well. Ignoring to do so will cause the API to silently fail for the fields involved.


Required Fields

The following fields are required in your Inbound Mapping:


Required FieldsDescription
Email or Phone

The contact reference which is going to receive the survey. It can be either email or phone number.


Please note: The telephone field needs to be in a valid phone number format.
We strongly recommend to add only numbers, but the field is restricted to the following characters when importing: numbers, space, parenthesis, dash and plus. Example: +55 (62) 01234-56789


Touchpoints

When importing Touchpoints, only Touchpoints that exist in your CustomerGauge system will be accepted. Touchpoints can be managed in System Settings by System Administrators.






Preparations


An Inbound Mapping reference is required to make requests to this API, all your mapping references can be found in Data → Rest APIs → Inbound Mapping.




Setting New Inbound Mapping


1. Go to Data → Rest APIs.


2. Select Inbound Mapping in the menu.


3. Click on +New Mapping button.


4. On Data type choose Multi-object and fill the Configuration name field.



5. On Field Mapping choose all the fields you want to import into the system and their Field Heading.



6. Click on the Save button to finish the mapping creation.






Authentication

OAuth2 Authentication is used to connect to this API. Once you've created your Connected App, you can acquire a Bearer Access Token by calling our OAuth2/Token API:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded"
-d "grant_type=client_credentials&client_id={{ Client ID }}&client_secret={{ Client Secret }}"
https://auth.{{ apiRegion }}.customergauge.com/oauth2/token

The acquired Bearer Access Token is used in the Authorization header in your API request.


If you can not use OAuth2 Authentication, you can use our Incoming Webhook functionality.






Endpoint

Endpoint URL

https://imports.api.{{ apiRegion }}.customergauge.com/records/







Request


Parameters


Use these parameters in the API request to pass the relevant information to the API.


ParameterDescriptionRulesExample Values
configuration

Configuration reference for data type and mapping.


You can find it in Data → Rest APIs → Inbound Mapping, under the Reference column.

  • Required
9dd58237-c913-4073-9c76-07da0b49ff50
record[]An array for all the fields to be imported.

The values in the array must be the same set up in the API mapping referenced in the configuration parameter.
  • Required
record[Email]
record[Account Name]



Supported Formats


JSON (raw request body)

Data can be passed to this API using the JSON format in the body of the request.


Example parameters:

{
"configuration": "53505294-0b20-2509-b15d-c8e377701d66",
"record": {
"Account Name": "ACME",
"First Name": "Joe",
"Last Name": "Doe",
"Email": "joe.doe@example.com"
}
}


x-www-form-urlencoded (body)

Data can be passed to this API using the x-www-form-urlencoded format in the body of the request.


Example parameters:

configuration: "12305294-0b20-4009-b95d-c8123301d66"
record[Account Name]: "ACME"
record[First Name]: "Joe"
record[Last Name]: "Doe"
record[Email]: "joe.doe@example.com"






Response


HTTP Status Code 200

OK - everything worked as expected.

Example Response Body
An empty Response Body will be returned when successful.


HTTP Status Code 422

An issue occurred - this usually means one of the required fields is missing.


Example Response Body

{
"message": "The given data was invalid.",
"errors": {
"configuration": [
"The configuration field is required."
]
}
}






Examples


Postman example

Download Postman example


After importing the Postman example, make sure to change the Host Region and Authentication accordingly.






Not the API you're looking for?

Get an overview of our APIs here.