TABLE OF CONTENTS




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.






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.


Note: The Access Token is only valid for up to 1 hour. Save the Access Token temporarily when calling the API multiple times in a row, or obtain a fresh Access Token before calling the API.


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


Payload


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 401

The authentication was invalid - this usually means that you're not using a valid Bearer Access Token in the Authorization header.


Not authenticated - Example Response Body

{
   "message": "Unauthenticated."
}



HTTP Status Code 422

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


Configuration required - Example Response Body

This error happens when the configuration parameter is not provided, or not provided correctly in the body of the request.

{
    "message": "The configuration field is required.",
    "errors": {
        "configuration": [
            "The configuration field is required."
        ]
    }
}


Configuration not found - Example Response Body

This error happens when the provided configuration id does not exist in your system.

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


Record required - Example Response Body

This error happens when the configuration parameter is not provided, or not provided correctly in the body of the request.

{
    "message": "The record field is required.",
    "errors": {
        "record": [
            "The record field is required."
        ]
    }
}


Record must be an array - Example Response Body

This error happens when the record parameter is not provided correctly in the body of the request.

{
    "message": "The record must be an array.",
    "errors": {
        "record": [
            "The record must be an array."
        ]
    }
}


Record duplicated - Example Response Body

This error happens when the provided Contact already has received a survey invitation within your system's Duplication Rule.

{
    "message": "Record could not be imported because it duplicates with {{CG-ID}}.",
    "errors": {
        "duplicate": [
            "Record could not be imported because it duplicates with {{CG-ID}}."
        ]
    }
}


Email or Phone required - Example Response Body

This error happens when no Email and no Phone field is provided, or incorrectly mapped in the body of the request. Make sure that the provided data in the body matches the Inbound Mapping set up in your CustomerGauge platform.

{
    "message": "The Email field is required when Phone is not present. (and 1 more error)",
    "errors": {
        "Email": [
            "The Email field is required when Phone is not present."
        ],
        "Phone": [
            "The Phone field is required when Email is not present."
        ]
    }
}


Email invalid - Example Response Body

This error happens when the provided Email value is not a valid email address. This validation is always applicable for the "email" field.

{
    "message": "The Email field must be a valid email address.",
    "errors": {
        "Email": [
            "The Email field must be a valid email address."
        ]
    }
}


Field Required - Example Response Body

This error happens when a field is required but no value is provided. This is controlled by System Administrators in Field Settings and applies to all import processes.

{
    "message": "The {{field}} field is required.",
    "errors": {
        "{{field}}": [
            "The {{field}} field is required."
        ]
    }
}


Field invalid - Example Response Body

This error happens when a field does not follow the validation rules set up in your system, this typically occurs when a value is provided while "Restrict new values on upload" is turned on in your system. This is controlled by System Administrators in Field Settings and applies to all import processes .

{
    "message": "The {{field}} field is invalid.",
    "errors": {
        "{{field}}": [
            "The {{field}} field is invalid."
        ]
    }
}


Invalid date format - Example Response Body

This error happens when an invalid date is provided, while the field is configured to validate for Date format. This is controlled by System Administrators in Field Settings and applies to all import processes .

{
    "message": "The field {{field}} must be a valid date with format YYYY-MM-DD HH:MM:SS or YYYY-MM-DD.",
    "errors": {
        "{{field}}": [
            "The field {{field}} must be a valid date with format YYYY-MM-DD HH:MM:SS or YYYY-MM-DD."
        ]
    }
}


Invalid email format - Example Response Body

This error happens when an invalid email address is provided, while the field is configured to validate for Email format. This is controlled by System Administrators in Field Settings and applies to all import processes .

{
    "message": "The {{field}} must be a valid email address.",
    "errors": {
        "{{field}}": [
            "The {{field}} must be a valid email address."
        ]
    }
}


Invalid number - Example Response Body

This error happens when an invalid number is provided, while the field is configured to validate for Number format. This is controlled by System Administrators in Field Settings and applies to all import processes .

{
    "message": "The {{field}} must be a number.",
    "errors": {
        "{{field}}": [
            "The {{field}} must be a number."
        ]
    }
}


Invalid number - Example Response Body

This error happens when a value is provided with more than the configured amount of allowed characters, while the field is configured to validate for Text format. This is controlled by System Administrators in Field Settings and applies to all import processes .

{
    "message": "The {{field}} must not be greater than {{X}} characters.",
    "errors": {
        "{{field}}": [
            "The {{field}} must not be greater than {{X}} characters."
        ]
    }
}





Not the API you're looking for?

Get an overview of our APIs here.