TABLE OF CONTENTS

• API Setup
• Business Use Case
• Good to Know
• Authentication
• Endpoint
• Request
  • Payload
    • Fields supported in the Record object
    • Supported Formats
• Response
• Not the API you're looking for?

API Setup

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

Business Use Case

The PATCH Update Single Record API allows you to update a survey record for any of the supported fields. It can be used to enrich a survey record with more information and also to improve your data quality by fixing any values that may have been wrongly added to the survey record during an upload.

After a successful request, the data will be updated in the system instantly.

Good to Know

Field names

This API works based on the fields' technical name. In order to correctly map your data to the correct field make sure to check the Field Settings feature, it will display the technical name for each of your fields.

In the image below, for example, the field technical name for Touchpoint is touchpoint and for Distributor it is segment_x.

Required Fields

The following fields are required in your request body:

Authentication

OAuth2 Authentication is used to connect to this API. Once you've created your Authentication, 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/{{CG ID}}

Request

Payload

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

Fields supported in the Record object

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:

{
    "entity": "survey",
    "record": {
        "account": "ACME",
        "segment_a": "John Doe",
        "division": "LATAM",
        "contact": "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:

entity: "survey"
record[account]: "ACME"
record[segment_a]: "John Doe"
record[division]: "LATAM"
record[contact]: "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."
}

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

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

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."
        ]
    }
}

This error happens when the Email or Phone provided does not match any contacts in the platform. Make sure that the contact is already added to the platform.

{
    "message": "The contact must be a valid contact.",
    "errors": {
        "Email": "The contact must be a valid contact."
    }
}

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