CX: Triggering CX Surveys Using Our API
You can programmatically trigger email invitations using our API. This option is frequently used as an integration point with Salesforce or other CRMs. A common use case is to trigger a follow up email after closing a customer support request.
To enable the API endpoint for your survey, navigate to Setup and click the Data Sources link:
Toggle the API option.
You’ll find the API endpoint and access token listed on the Summary page:
The API expects a POST request, with the provided Authorization token.
There are two valid formats for the body of the API request: a single recipient, or multiple recipients.
Single recipient request
For a single recipient, here is an example request body:
|person||This is the only required field. All other fields are optional.|
|first_name||If not existing customer matches the provided email, this value is assigned as teh person's first name.|
|last_name||If not existing customer matches the provided email, this value is assigned as teh person's last name.|
|fields||This hash can assign arbitrary values from your Custom Filters. The hash keys must match the nameof your Filter, and the values must be an array with names that match the existing value.|
|account||name||If name is provided, the Person record will be associated with an Account. An existing account with a match name will be used, or a new one will be created.|
|facets||This hash can assign arbitrary values from your Custom Attributes. They hash keys myst match the name of your Attribute The values must be a single string.|
|delay||This integer will delay the delivery of the email by the provided number of hours. Valid options are 0-720.|
- A successful response will include all the current data for the matching Person and Account.
- If a delay was set, the run_at attribute will report when delivery is estimated.
This API endpoint can also accept up to 100 records at once. Each element has the same options as the singleton example above. You must only wrap each in an array:
You can also add facets to the POST request body as follow:
Multiple recipients requests
Below is an example of a request body for a multiple-person request:
- Unprocessable requests will return with a 422 header code.
- Too many replies - if you send a request with too many person records. Default limit is 100
- Email Suppressed - You have disabled this customer from receiving emails
- Recipient opted out - The customer has opted out of further communications
- Email address bounced - The email address has been identified as a bounce
- Touch limit exceeded - If you have enabled the touch limit on your survey, this error message indicates the recipient has already received an email in the allotted period
- "Content header type not defined" - Add a header for it, as in Content-Type: application/json
- Capitalization and spacing must match the above examples