TABLE OF CONTENTS

• API Setup
• Business Use Case
• Good to Know
• Preparations
• Authentication
• Endpoint
• Request
  • Parameters
• Response
• Examples
  • Postman example
• 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

Our PUT Personal Link API can be used to generate a single Personal Link survey record in your CustomerGauge platform, allowing you to utilise Personal Link campaigns for any method of survey delivery that isn't directly integrated with the CustomerGauge Platform. Examples could include during transactions, such as at the back of a support ticket, or an e-commerce purchase, etc. This API can use 'Multi-Object', or 'Survey' Inbound Mappings.

After a successful request, the data will be uploaded/updated in the system and a link will be returned that you can use to distribute to your customers.

Good to Know

Preparations

The same preparations needed to call the PUT Record APIs are needed to use this API.

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:

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.

Delivery Vector: Personal Link

This API ignores the Delivery Vector of your Inbound Mapping. When this API is called, it sets the Delivery Vector of the provided record to "Personal Link".

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.

Endpoint

Endpoint URL

https://imports.api.{{ apiRegion }}.customergauge.com/personal-link/

Request

Parameters

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

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

{
    "data": {
        "number_customergauge": 12345,
        "survey_link": "https://survey.{{ apiRegion }}.customergauge.com/r/987656abcdef",
        "survey_link_short": "https://cust.xx/987656abcdef"
    }
}

HTTP Status Code 400

An issue occurred - this usually means something is wrong while working with the Personal Link Campaigns.

Missing Campaign - Example Response Body

This error happens when the provided data does not match any of the Personal Link Campaign filters.

{
    "message": "Could not match any campaign filter."
}

Global Campaign Duplicate Rule - Example Response Body

This error happens when the provided data does not match any of the Personal Link Campaign filters.

{
    "message": "Record could not be imported because it duplicates with another record."
}

Duplicate record - Example Response Body

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

{
    "message": "Personal link record could not be created because it duplicates with another record."
}

HTTP Status Code 404

An issue occurred - this usually means that the Inbound Mapping can not be found.

Configuration not found - Example Response Body 

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

{
    "message": "The inbound mapping [$value] was not found."
}

HTTP Status Code 422

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

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

{
    "message": "The inbound mapping [abcdefgh-1234-5678-ijkl-mnopqrstuvwx] data type is invalid, only 'Multi-Object' or 'Survey Data' are allowed.",
    "errors": {
        "configuration": [
            "The inbound mapping [abcdefgh-1234-5678-ijkl-mnopqrstuvwx] data type is invalid, only 'Multi-Object' or 'Survey Data' are allowed."
        ]
    }
}

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

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

Not the API you're looking for?

Get an overview of our APIs here.