ARTICLE
CX: Triggering CX Surveys Using Our API
SURVEYMONKEY CX:SurveyMonkey CX is another SurveyMonkey product that helps increase customer loyalty. If you're interested in learning more, contact sales.
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:
POST /api/v1/surveys/PARAM/replies Headers: Content-Type: application/json Authorization:Token token=TOKEN { "person": { "email": "first @last.com", "first_name": "First", "last_name": "Last", "fields": { "Account Manager": ["Jane Doe"], "Products": ["Acme M500", "Acme B7500"] } }, "account": { "name": "Account Name" }, "facets": { "Job ID": "1234" }, "delay": 24 }
Successful response:
{ "Reply": { "id": 1, "facets": { "Job ID": "1234" } }, "person": { "id": 2, "first_name": "First", "last_name": "Last", "email": "first@last.com", "fields": { "Account Manager": ["Jane Doe"], "Products": ["Acme M500", "Acme B7500"] } }, "account": { "id": 3, "name": "Account Name" }, "run_at": "2000-01-01T00:00:00.000Z" }
| Element | Attribute | Description |
| 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:
POST /api/v1/surveys/PARAM/replies Headers: Content-Type: application/json Authorization:Token token=TOKEN { "replies": [ { "person": { "email": "first@person.com" } }, { "person": { "email": "second@person.com" } } ] } Successful response: { "replies": [ { "status": "ok", "reply": { "id": 1, } "person": { "id": 2, "email": "first@person.com" } }, { "status": "ok", "reply": { "id": 3, } "person": { "id": 4, "email": "second@person.com" } } ] }
You can also add facets to the POST request body as follow:
{ "replies": [ { "person": { "email": "sulema_mraz@example.net", "first_name": "Sulema", "last_name": "Mraz", "fields": { "company_name": "Lindgren, Kihn and Dickinson", "industry": "Hospitality", "departments": "Baby" } }, "facets": { "product": "Fantastic Wool Computer", "price": 91.74, "promotion_code": "StellarDiscount323014" }, "delay": 0 } ] }
Multiple recipients requests
Below is an example of a request body for a multiple-person request:
{ "replies": [ { "person": { "first_name": "Melvina", "last_name": "Ward", "email": "melvina_ward@example.org", "fields": { "company_name": "Schneider, Nolan and Rosenbaum", "industry": "Investment Banking", "departments": "Kids & Automotive" } }, "facets": { "product": "Sleek Paper Lamp", "price": 60.79, "promotion_code": "KillerPromotion909616" }, "delay": 0 }, { "person": { "first_name": "Augustus", "last_name": "Windler", "email": "augustus_windler@example.com", "fields": { "company_name": "Conn Group", "industry": "Food Production", "departments": "Beauty, Electronics & Kids" } }, "facets": { "product": "Mediocre Iron Pants", "price": 91.53, "promotion_code": "GoodSavings710289" }, "delay": 0 }, { "person": { "first_name": "Refugio", "last_name": "Senger", "email": "refugio_senger@example.org", "fields": { "company_name": "Orn, Bradtke and Mertz", "industry": "Online Media", "departments": "Music & Garden" } }, "facets": { "product": "Incredible Aluminum Chair", "price": 22.21, "promotion_code": "StellarSale637270" }, "delay": 0 } ] }
Error cases:
- 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