This documentation describes the resources that make up the official CustomerSure API v1. If you have any problems or requests please contact support.
Accept
HeaderThe current version of the API is version 1. We’re likely to release v2, v3 etc in future.
To ensure your client code remains stable you MUST explicitly specify
the version on every API request via the HTTP Accept
header.
# The Accept header must look like this:
Accept: application/vnd.customersure.v1+json
All API access is over HTTPS
, and accessed from the api.customersure.com
domain. All data is sent and received as JSON.
Blank fields are included as null
instead of being omitted.
All timestamps are returned in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ
. You can supply timestamps
in any timezone using this format, but we will always return times in UTC. Omitting the timezone specifier
from an otherwise-correct ISO 8601 date will result in us assuming UTC.
All API requests MUST include a valid User-Agent header. Requests with no User-Agent header will be rejected. Please use the same company name as you use for your CustomerSure account for the User-Agent header value. This allows us to contact you if there are problems.
# Valid User-Agent header:
User-Agent: Acme Ltd
# If you do not a User-Agent header you will receive a 403 response:
HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8
{"message":"Missing or invalid User Agent string"}
For GET requests, any optional parameters should be passed in the HTTP query string.
For POST, PATCH, PUT, and DELETE requests, parameters not included in the URL should be encoded as JSON with a Content-Type of ‘application/json’.
Parameters can be either scalar values or arrays. We indicate this per-parameter for each endpoint.
To pass an array parameter you must append square
brackets to the parameter name, for example: ?survey_ids[]=123
or ?survey_ids[]=123&survey_ids[]=456
for multiple values.
Rather than passing an explicit from_time
and to_time
, you can instead pass a period
parameter, which will set the from/to times for you.
If you pass both from/to times and period
, the
times you passed will be ignored, and we will use those calculated
by the period
parameter.
Available date periods are:
Period name | Description |
---|---|
7-days | 7-day rolling window, ending 11:59 today. |
30-days | 30-day rolling window, ending 11:59 today. |
3-months | 3-calendar-month rolling window, ending 11:59 today. |
6-months | 6-calendar-month rolling window, ending 11:59 today. |
12-months | 12-calendar-month rolling window, ending 11:59 today. |
current_week | Start of this calendar week to the end of today |
current_month | Start of this calendar month to the end of today |
current_quarter | Start of the current quarter (i.e. 1st Jan, 1st April, 1st July, 1st Oct) to the end of today |
current_year | Start of the current year to the end of today |
last_week | Previous calendar week |
last_month | Previous calendar month |
last_quarter | Previous calendar quarter (i.e. Jan 1st-March 31st, April 1st-June 30th etc) |
last_year | Previous calendar year |
yesterday | From 00:00 to 23:59 yesterday |
day_before_yesterday | From 00:00 to 23:59, the day before yesterday |
week_before_last | Two calendar weeks ago |
month_before_last | Two calendar months ago |
year_before_last | Two calendar years ago |
# Example GET request with params:
curl -H 'Accept: application/vnd.customersure.v1+json;' \
-H 'Authorization: Token token="ec76c296df321768ba4cc41a445bfb6f"' \
https://api.customersure.com/feedback_requests?state=pending
All requests that return multiple resources are paginated. The default number of items per page is 30 but the
documentation for each method will specify if that differs. Indexing starts from page 1 and you can request
further pages with the ?page
parameter. Some methods let you specify a
?per_page
parameter too. The default maximum allowed is 100, again, each method documentation will
specify if this differs. If you do not specify a page you will receive page 1.
Pagination data is included in the response headers. The Link
header contains URLs for
some/all of the following rel values: first, prev, next and last. Here is an example (with line-breaks for
readability) of the Link header content after requesting page two of a collection:
<https://api.customersure.com/feedback_requests?page=1&per_page=30>; rel="first",
<https://api.customersure.com/feedback_requests?page=1&per_page=30>; rel="prev",
<https://api.customersure.com/feedback_requests?page=3&per_page=30>; rel="next",
<https://api.customersure.com/feedback_requests?page=3&per_page=30>; rel="last"
You should use these links for traversing a collection rather than crafting your own. It's not gurarnteed that all collections methods will use a integer for the page number in future.
For convinince, you'll also receive X-Total-Pages
and X-Total-Count
headers.
The API uses HTTP redirection where appropriate. You should assume that any request may result in a redirection. Receiving an HTTP redirection is not an error and clients should follow that redirect. Redirect responses will have a Location header field which contains the URI to follow. A redirection status code will be used in accordance with the HTTP 1.1 spec.
The API uses the appropriate HTTP verbs as follows:
Verb | Description |
---|---|
GET | Used for retrieving resources. |
POST | Used for creating resources or performing custom actions. |
PATCH | Used for updating resources with partial JSON data. A PATCH request may accept one or more of the attributes to update the resource. |
PUT | Used for replacing resources or collections. |
DELETE | Used for deleting resources. |
The API uses token based authentication. To get your API token simply email us at support and we’ll issue it to you.
You must set the token in the Authorization header in every API request. If you fail to provide a valid
token you will receive a 401 Unauthorized
response.
# The Authorization header must look like this
Authorization: Token token=1234567890
# Request with an invalid token
$ curl -H 'Accept: application/vnd.customersure.v1+json;' -H 'Authorization: Token token="fake"' https://api.customersure.com/feedback_requests -I
# Response
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Token realm="Application"
Content-Type: application/json; charset=utf-8
The API returns conventional HTTP response codes where possible to indicate success or failure of an API request.
We will return a JSON-formatted response body containing more information about the error. This response will contain a message attribute containing this information.
Where the error concerns a resource (i.e. a validation error, rather than something like an authentication or syntax error), we will return an errors array containing all the errors reported by that resource.
/feedback_requests/
required
invalid_format
wrong_length
invalid_value
forbidden_value
invalid_date
custom
custom
code may be missing extra_info
to help you.
This should not occur, and if you observe it, please notify us.
We will consider it a bug and update the API accordingly.
An object containing more information about the error. For instance, a regular expression explaining allowed formats in the case of a format error, or maximum/minimum values in the case of string length/number size/date validity errors.
If you cannot recover from the error automatically, we encourage you to make use of this information to craft helpful error messages to allow your users to manually recover from the error.
This object may be blank, for instance if the error is required
, we have no extra info to supply –
you must provide a value for that field!
Possible keys in this array include:
valid_format
a regular expression for valid formats for this field.disallowed_values
a list of forbidden values for this field.allowed_values
a list of valid values for this fieldminimum
the smallest allowed length for a string.maximum
the longest allowed length for a string.exactly
the only allowed length for a string.greater_than
the smallest allowed value for a numeric fieldless_than
the largest allowed value for a numeric fieldmust_be
additional constraints on numeric fields. Possible values are even
, odd
and integer
.message
a human friendly message for custom
errors.
200 OK - Everything worked as expected.
201 Created - Request fulfilled and the new resource has been created.
204 No Content - Used as a response to a successful delete request.
301 Moved Permanently - This and all future requests should be directed to URI in the Location header field.
307 Temporary Redirect - Repeat request to the URI in the Location header field. Continue using the original URI for future requests.
400 Bad Request - The request cannot be fulfilled due to malformed JSON
401 Unauthorized - No valid API key provided in Authorization header.
403 Forbidden - You'll see this if you send us unpermitted parameters.
404 Not found - The requested resource does not exist.
500, 502, 503, 504 Server errors - something went wrong at our end.
422 Unprocessable Entity
{ "message" : "Validation error", "errors" : [{ "resource" : "/feedback_requests/33", "field" : "state", "error" : "invalid_value", "extra_info" : { "allowed_values" : ["sent", "pending", "not_sent"] } }, { "resource" : "/feedback_requests/33", "field" : "machine_id", "error" : "wrong_length", "extra_info" : { "maximum" : "36" } }] }
Feedback requests make it easy for you to contact your customers for feedback. Each feedback request specifies who we should contact, at what time and what survey you'd like them to fill in. The API allows you to schedule feedback requests.
The current state of the request. It will be one of:
pending
- The email is scheduled for sending.
sent
- The email has been sent.
not_sent
- The email was not sent.
Creates a new pending
feedback request. At the send_at
time an email
will be sent to your customer asking them for feedback.
true
. You can retrieve a unique link to the feedback request, and take care of
contacting the customer via another channel. The feedback request will have its state set to sent
and sent_at
set to the current time.
You can set additional data on feedback requests. Data is automatically stored against any responses that comes in from the feedback request. A number of useful cases are covered with this feature.
Link feedback to a staff member who dealt with the customer
Pass in a staff_code
and ensure at least one staff member set up in CustomerSure has that
staff_code
set against them. If the staff member is in a team, that will also be set for you.
Link feedback to a location/site in your company
Pass in a site_code
and ensure at least one site in CustomerSure has that
site_code
set against it.
Link feedback to a custom segment
Use a key that matches one of the segments defined in CustomerSure. Each value will be stored
as an option for that segment. The values do not need to be pre-defined in CustomerSure
like staff and sites.
Attach other information to feedback
Any other key/value pairs passed in the data array will be saved as information against the feedback.
If you use the API to retreive your feedback, the values will be returned in the fields
attribute.
If you wish to send the feedback request via a text message, rather than an email, simply provide the 2 required sms attributes.
Before any text messages can sent from your account, we need to enable this feature for you. You may schedule text message before that point, but they will not be sent.
If you wish to schedule reminders for when a customer does not reply to the original feedback request you can do that via this option. See reminder attributes
The ID for the text message template that you would like to send. You can get your template IDs by editing the templates under Feedback Requests in CustomerSure. On the edit screen the ID will be at the end of the URL. This field cannot be left blank if you provide the sms key.
You must provide either email_template_id or text_message_template_id, but not both.
The ID for the email template that you would like to send. You can get your template IDs by editing the templates under Feedback Requests in CustomerSure. On the edit screen the ID will be at the end of the URL.
The ID for the text message template that you would like to send. You can get your template IDs by editing the templates under Feedback Requests in CustomerSure. On the edit screen the ID will be at the end of the URL.
The created feedback request is returned if successful. Otherwise, this call returns an error.
# DEFINITION POST https://api.customersure.com/feedback_requests # EXAMPLE REQUEST curl -i -H 'Accept: application/vnd.customersure.v1+json;' \ -H 'Authorization: Token token="ec76c296df321768ba4cc41a445bfb6f"' \ -H 'Content-Type: application/json' \ -X POST \ -d '{ "email":"john.smith@example.com", "send_at":"2023-08-20T18:00:00+0100", "survey_id":1484, "email_template_id":10, "first_name":"John", "surname":"Smith", "reference":"#1041", "machine_id":"8736245", "data":[ { "key":"staff_code", "value":"luke" }, { "key":"site_code", "value":"newcastle" }, { "key":"category", "value":"api-support" }, { "key":"ticket_date", "value":"20th Aug 2023" }], "reminders":[ { "email_template_id": 11, "send_at":"2023-08-27T18:00:00+0100" }, { "email_template_id": 12, "send_at":"2023-09-01T18:00:00+0100" }] }' \ https://api.customersure.com/feedback_requests
# EXAMPLE RESPONSE Status: 201 Created { "id": 208073, "email": "john.smith@example.com", "state": "pending", "first_name": "John", "surname": "Smith", "survey_id": 1484, "email_template_id": 10, "reference": "#1014", "machine_id": "8736245", "send_at": "2023-08-20T17:00:00Z", "sent_at": null, "created_at": "2023-08-19T16:30:14Z", "updated_at": "2023-08-19T16:30:14Z", "not_sent_reason":null, "delivery_failure":null, "ignore_throttle":false, "link":"https://yourdomain.customersure.com/surveys/…", "data":[ { "id":256777, "key":"staff_code", "value":"luke" }, { "id":256778, "key":"site_code", "value":"newcastle" }, { "id":256779, "key":"category", "value":"api-support" }, { "id":256779, "key":"ticket_date", "value":"20th Aug 2023" } ], "reminders":[ { "id":60845536, "email_template_id": 11, "send_at":"2023-08-27T18:00:00+0100", "sent_at":null, "text_message_template_id":null, "not_sent_reason":null, "delivery_failure":null }, { "id":60845537, "email_template_id": 12, "send_at":"2023-09-01T18:00:00+0100", "sent_at":null, "text_message_template_id":null, "not_sent_reason":null, "delivery_failure":null } ] }
Feedback responses are created every time a customer completes your survey. You can use these API calls to retreive your feedback. Currently this resource is read only.
name
, email
, telephone_number
,
and company_name
alongside any other data you set against the feedback through a feedback request.
Rating
- Rating questions.Text
- Free text questions.Dropdown
- Select box questions.Radio
- Radio button questions.Checkbox
- Checkbox questions.Retrieves the feedback response with the given ID.
The feedback response if a valid ID parameter was provided. Returns an error otherwise.
# DEFINITION GET https://api.customersure.com/feedback_responses/:id # EXAMPLE REQUEST curl -H 'Accept: application/vnd.customersure.v1+json;' \ -H 'Authorization: Token token="b7c2b8ccbc967726cbdadf46406a3912"' \ https://api.customersure.com/feedback_responses/1
# EXAMPLE RESPONSE Status: 200 OK { "id": 16163, "reference": null, "machine_id": null, "fields":{ "email": "kate@example.com", "name": "Kate", "telephone_number": "01234 567 890", "company_name": "Acme" }, "answers":[ { "question_id": 12345, "question": "How satisfied were you with the support you received?", "answer":"10", "type":"Rating" }, { "question_id": 12346, "question": "How would you rate our speed of response?", "answer": "10", "type": "Rating" }, { "question_id": 12347, "question":"How friendly and helpful were we?", "answer":"10", "type":"Rating" }, { "question_id": 12348, "question":"How would you describe our performance overall?", "answer":"CustomerSure is fantastic quickly solved my problem.", "type":"Text" }, { "question_id": 12349, "question": "Is there anything else you'd like to tell us?", "answer":"Keep up the great attitude to your customers", "type":"Text" } ], "submitted_at":"2023-07-08T23:45:19Z", "feedback_request": { "id": 1234, "email": "kate@example.com", "state": "sent", "first_name": "Kate", "surname": "", "survey_id": 277, "email_template_id": null, "reference": null, "machine_id": null, "send_at": "2023-07-08T23:45:19Z", "sent_at": "2023-07-08T23:45:20Z", "created_at": "2023-07-07T23:45:19Z", "updated_at": "2023-07-08T23:45:20Z", "deletion_requested_at": null, "not_sent_reason": null, "delivery_failure": null }, "survey": { "id": 277, "name": "Post call survey" } }
You can list all feedback responses. They are returned in reverse chronological order.
Only return feedback responses created since the specified timestamp.
Only return feedback responses updated since the specified timestamp.
Only return feedback responses left by the email address provided
E.g. ?survey_ids[]=1234&survey_ids[]=5678
Only return feedback responses from the specified surveys. Please note that your survey ID
(i.e. 20112
, 8941
) is not the code used in your public survey URL (i.e. AKknWccEFf7
).
E.g. ?site_ids[]=1234&site_ids[]=5678
Only return feedback responses from the specified sites.
E.g. ?staff_ids[]=89&staff_ids[]=76
Only return feedback responses relating to the specified staff members.
A paginated collection of feedback responses.
# DEFINITION GET https://api.customersure.com/feedback_responses # EXAMPLE REQUEST curl -H 'Accept: application/vnd.customersure.v1+json;' \ -H 'Authorization: Token token="ec76c296df321768ba4cc41a445bfb6f"' \ https://api.customersure.com/feedback_responses
# EXAMPLE RESPONSE Status: 200 OK Link: <https://api.customersure.com/feedback_responses?page=1>; rel="first", <https://api.customersure.com/feedback_responses?page=1>; rel="last" X-Total-Pages: 1 X-Total-Count: 4 [ { "id": 63148, "reference": null, "machine_id": null, "fields":{ "email": "kate@example.com", "name": "Kate", "telephone_number": "01234 667 890", "company_name": "Acme" }, "answers":[ { "question_id": 12345, "question": "How satisfied are you with our service?", "answer": "10", "type": "Rating" }, { "question_id": 12346, "question": "How helpful was the customer service agent?", "answer": "10", "type": "Rating" }, { "question_id": 12347, "question": "Is there anything we could do to improve?", "answer": "Send me fewer marketing emails – I'm already a happy customer.", "type": "Text" } ], "submitted_at":"2023-08-08T23:45:19Z", "updated_at":"2023-09-01T11:00:01Z", "feedback_request": null, "survey": { "id": 2166, "name": "Post call survey" } }, { … }, { … }, { … } ]
Returns detailed scores and stats on the responses to a rating question.
?from_time=2015-01-01T00:00Z
(Defaults to midnight 30 days ago)
?to_time?2015-01-31T23:59Z
(Defaults to now)
company_name=cyber
will match “Cyberdyne Systems”
?survey_ids[]=234&survey_ids[]=456
?site_ids[]=789
?staff_ids[]=789
An object including various scores and statistics about the response to this question.
The standardised score
allows you to compare questions which use different scales on a standardised 0-100 scale.
The object will only include the average_rating
key if the question uses a numeric scale (i.e. a scale where we can calculate an average)
# DEFINITION POST https://api.customersure.com/rating_questions/:id # EXAMPLE REQUEST curl -i -H 'Accept: application/vnd.customersure.v1+json;' \ -H 'Authorization: Token token="ec76c296df321768ba4cc41a445bfb6f"' \ -H 'Content-Type: application/json' \ -X GET \ https://api.customersure.com/rating_questions/1
# EXAMPLE RESPONSE Status: 200 OK { "question_text": "How are you feeling about our service?", "standardised_score": "70.58823529", "average_rating": "7", "very_negative_count": 444, "negative_count": 87, "neutral_count": 138, "positive_count": 207, "very_positive_count": 1266, "total_number_of_ratings": 2142 }
You can access key metrics from your CustomerSure account through these endpoints. Currently you can retrieve your response rate, CSAT and Net Promoter® results. We build our API based on customer demand, so if there’s something missing that you’d like to see, please contact support and we’ll add it for you.
Your response rate is calculated from the 'Feedback Requests' you send and the 'Feedback Responses' submitted in reply to them. By default, the data is from a 30 day time period. It's the 30 days prior to yesterday. We don't want to include requests sent today or yesterday because those customers may not have had the chance to reply yet. If you prefer, you can override the time period in your API call.
?from_time=2015-01-01T00:00Z
(Defaults to midnight, 32 days ago)
?to_time=2015-01-31T23:59Z
(Defaults to midnight, 2 days ago)
?survey_ids[]=1234&survey_ids[]=5678
?site_ids[]=4321&site_ids[]=8765
Your response rate data.
# DEFINITION GET https://api.customersure.com/response_rate # EXAMPLE REQUEST curl -H 'Accept: application/vnd.customersure.v1+json;' \ -H 'Authorization: Token token="b7c2b8ccbc967726cbdadf46406a3912"' \ https://api.customersure.com/response_rate
# EXAMPLE RESPONSE Status: 200 OK { "response_rate_percent": 50, "sent_count": 100, "delivered_count": 50, "reply_count": 25 }
Your NPS® is calculated from the ratings left against all your NPS questions across all your surveys. You can set a timeframe, or limit it to certain survey(s) if you have more than one.
?from_time=2015-01-01T00:00Z
(Defaults to midnight 30 days ago)
?to_time?2015-01-31T23:59Z
(Defaults to now)
company_name=cyber
will match “Cyberdyne Systems”
?survey_ids[]=234&survey_ids[]=456
?site_ids[]=789
?staff_ids[]=789
Your NPS data.
Net Promoter, Net Promoter Score, and NPS are trademarks of Satmetrix Systems, Inc., Bain & Company, Inc., and Fred Reichheld.
# DEFINITION GET https://api.customersure.com/nps # EXAMPLE REQUEST curl -H 'Accept: application/vnd.customersure.v1+json;' \ -H 'Authorization: Token token="b7c2b8ccbc967726cbdadf46406a3912"' \ https://api.customersure.com/nps
# EXAMPLE RESPONSE Status: 200 OK { "net_promoter_score": 70, "promoter_count": 75, "passive_count": 20, "detractor_count": 5, "total_number_of_ratings": 12 }
Your CSAT is calculated from the ratings left against all your CSAT questions across all your surveys. You can set a timeframe, or limit it to certain survey(s) if you have more than one.
?from_time=2015-01-01T00:00Z
(Defaults to midnight 30 days ago)
?to_time?2015-01-31T23:59Z
(Defaults to now)
company_name=cyber
will match “Cyberdyne Systems”
?survey_ids[]=789&survey_ids[]=234
?site_ids[]=156
?staff_ids[]=789
Your CSAT data.
# DEFINITION GET https://api.customersure.com/csat # EXAMPLE REQUEST curl -H 'Accept: application/vnd.customersure.v1+json;' \ -H 'Authorization: Token token="b7c2b8ccbc967726cbdadf46406a3912"' \ https://api.customersure.com/csat
# EXAMPLE RESPONSE Status: 200 OK { "csat": 90, "very_negative_count": 1, "negative_count": 0, "neutral_count": 0, "positive_count": 2, "very_positive_count": 7, "total_number_of_ratings": 10 }
Site are your geographical business units. Examples of sites include individual hotels, restaurants, clinics, branches, holiday parks, shops or offices.
Creates a new site.
The created site is returned if successful. Otherwise, this call returns an error.
# DEFINITION POST https://api.customersure.com/sites # EXAMPLE REQUEST curl -i -H 'Accept: application/vnd.customersure.v1+json;' \ -H 'Authorization: Token token="ec76c296df321768ba4cc41a445bfb6f"' \ -H 'Content-Type: application/json' \ -X POST \ -d '{ "site_code":"hq", "name":"Head Office", "city": "Newcastle", "region":"Tyne and Wear" }' \ https://api.customersure.com/sites
# EXAMPLE RESPONSE Status: 201 Created { "id": "111", "site_code": "hq", "name": "Head Office", "city": "Newcastle", "region": "Tyne and Wear", "site_type": "Office" }
Retrieves the site with the given id.
The site if a valid id parameter was provided. Returns an error otherwise.
# DEFINITION GET https://api.customersure.com/sites/:id # EXAMPLE REQUEST curl -H 'Accept: application/vnd.customersure.v1+json;' \ -H 'Authorization: Token token="b7c2b8ccbc967726cbdadf46406a3912"' \ https://api.customersure.com/sites/hq
# EXAMPLE RESPONSE Status: 200 OK { "id": "222", "site_code": "hq", "name": "Head Office", "city": "Newcastle", "region": "Tyne and Wear", "site_type": "Office" }
Updates a site record.
The updated site upon success. Returns an error otherwise.
# DEFINITION PATCH https://api.customersure.com/sites/:id # EXAMPLE REQUEST curl -i -H 'Accept: application/vnd.customersure.v1+json;' \ -H 'Authorization: Token token="04da26bec3b93233fd00e3876685f181"' \ -H 'Content-Type: application/json' \ -X PATCH \ -d '{"name":"Main Office"}' \ https://api.customersure.com/sites/hq
# EXAMPLE RESPONSE Status: 200 OK { "id": "111", "site_code": "hq", "name": "Main Office", "city": "Newcastle", "region": "Tyne and Wear", "site_type": "Office" }
You can list all sites. The site are returned sorted by name.
A paginated collection of sites.
# DEFINITION GET https://api.customersure.com/sites # EXAMPLE REQUEST curl -H 'Accept: application/vnd.customersure.v1+json;' \ -H 'Authorization: Token token="ec76c296df321768ba4cc41a445bfb6f"' \ https://api.customersure.com/sites
# EXAMPLE RESPONSE Status: 200 OK Link: <https://api.customersure.com/sites?page=1>; rel="first", <https://api.customersure.com/sites?page=1>; rel="last" X-Total-Pages: 1 X-Total-Count: 4 [ { "id": "333", "site_code": "hq", "name": "Head Office", "city": "Newcastle", "region": "Tyne and Wear" }, { … }, { … }, { … } ]
Staff are the people in your business.
Retrieves the staff member with the given id.
The staff member if a valid id parameter was provided. Returns an error otherwise.
# DEFINITION GET https://api.customersure.com/staff/:id # EXAMPLE REQUEST curl -H 'Accept: application/vnd.customersure.v1+json;' \ -H 'Authorization: Token token="b7c2b8ccbc967726cbdadf46406a3912"' \ https://api.customersure.com/staff/98723
# EXAMPLE RESPONSE Status: 200 OK { "id": "98723", "code": "rod-magnusson", "first_name": "Rod", "surname": "Magnusson", "email": "rod.magnusson@example.com", "time_zone": "London", "deactivated_at": "null", "team_id": "null" }
You can list all staff, and search for a staff member by email or code.
A paginated collection of staff.
# DEFINITION GET https://api.customersure.com/staff # EXAMPLE REQUEST curl -H 'Accept: application/vnd.customersure.v1+json;' \ -H 'Authorization: Token token="ec76c296df321768ba4cc41a445bfb6f"' \ https://api.customersure.com/staff
# EXAMPLE RESPONSE Status: 200 OK Link: <https://api.customersure.com/staff?page=1>; rel="first", <https://api.customersure.com/staff?page=1>; rel="last" X-Total-Pages: 1 X-Total-Count: 4 [ { "id": "98723", "code": "rod-magnusson", "first_name": "Rod", "surname": "Magnusson", "email": "rod.magnusson@example.com", "time_zone": "London", "deactivated_at": "null", "team_id": "null" }, { … }, { … }, { … } ]
en en-US fr de it es es-MX nl sv da ja ar zh-CN no he id th fi
.
Rating
- Rating questions.Text
- Free text questions.Dropdown
- Select box questions.Radio
- Radio button questions.Checkbox
- Checkbox questions.You can list all surveys. The surveys are returned sorted by name.
A paginated collection of surveys.
# DEFINITION GET https://api.customersure.com/surveys # EXAMPLE REQUEST curl -H 'Accept: application/vnd.customersure.v1+json;' \ -H 'Authorization: Token token="ec76c296df321768ba4cc41a445bfb6f"' \ https://api.customersure.com/surveys
# EXAMPLE RESPONSE Status: 200 OK Link: <https://api.customersure.com/surveys?page=1>; rel="first", <https://api.customersure.com/surveys?page=1>; rel="last" X-Total-Pages: 1 X-Total-Count: 4 [ { "id": "1", "name": "Head Office", "locale": "en", "questions":[ { "id": 12345, "question": "How satisfied were you with the support you received?", "answer_type":"Rating" }, { "id": 12346, "question": "Any comments?", "answer_type":"Text" }, ] }, { … }, { … }, { … } ]
en en-US fr de it es es-MX nl sv da ja ar zh-CN no he id th fi
.
You can list all email templates. The email templates are returned sorted by name.
A paginated collection of email templates.
# DEFINITION GET https://api.customersure.com/email_templates # EXAMPLE REQUEST curl -H 'Accept: application/vnd.customersure.v1+json;' \ -H 'Authorization: Token token="ec76c296df321768ba4cc41a445bfb6f"' \ https://api.customersure.com/email_templates
# EXAMPLE RESPONSE Status: 200 OK Link: <https://api.customersure.com/email_templates?page=1>; rel="first", <https://api.customersure.com/email_templates?page=1>; rel="last" X-Total-Pages: 1 X-Total-Count: 4 [ { "id": 123456, "name": "Post Sale Feedback Email", "body":"Hi {{name/there}},\r\n\r\n We’d be really grateful if you’d answer a few questions…", "subject":"{{name/Hi}}, how did we do?", "from_name":"Kate Jones", "from_email":"kate@acme.co.uk", "locale":"en", "archived":false }, { … }, { … }, { … } ]
en en-US fr de it es es-MX nl sv da ja ar zh-CN no he id th fi
.
You can list all text message templates. The text message templates are returned sorted by name.
A paginated collection of text message templates.
# DEFINITION GET https://api.customersure.com/text_message_templates # EXAMPLE REQUEST curl -H 'Accept: application/vnd.customersure.v1+json;' \ -H 'Authorization: Token token="ec76c296df321768ba4cc41a445bfb6f"' \ https://api.customersure.com/text_message_templates
# EXAMPLE RESPONSE Status: 200 OK Link: <https://api.customersure.com/text_message_templates?page=1>; rel="first", <https://api.customersure.com/text_message_templates?page=1>; rel="last" X-Total-Pages: 1 X-Total-Count: 4 [ { "id":123456, "name":"Post Sale SMS Template", "body":"Hi, we’d love to hear about your recent experience through a quick, 3 question survey: {{link-to-survey}}", "locale":"en", "archived":false }, { … }, { … }, { … } ]
Any survey can be displayed in a website or app by selecting the ‘Make a website widget’ option for that survey.
Widgets can be used without any customisation. We provide two completely ‘pre-built’ widgets, which will display an on-page trigger, which when clicked or tapped will display the survey in a modal popover. This popover will adapt responsively to all screen sizes.
It is possible to customise both how the survey is triggered, and how the survey appears in response to this trigger.
For most use cases it makes sense to only customise how the survey is triggered, for example, by swapping our pre-built trigger icon for a native trigger element in your site, or by showing the survey in response to scripted events. When setting up a survey widget, we provide a preset for this scenario.
It is also possible to customise how the survey popover displays. Because this is uncommon, we do not provide a preset for it, but please contact our support team if you would like to do so.
To install the survey widget on a page, add the code snippet provided when you create the widget.
<script src="https://link-to-survey_widget.js"></script>
<div data-customersure-survey-widget
data-widget-params='{"org": "your-subdomain", "survey": "survey-url-code"}'>
</div>
<script>CustomerSureSurveyWidget.init();</script>
Once installed, the widget has the following public API
CustomerSureSurveyWidget.toggleWidget();
Toggle the widget’s state: If it is visible, hide it, if it is hidden, show it.
data-survey-params='{…json object…}'
To pass extra data into the widget, provide a json object to the data-survey-params
attribute.
This attribute must be set before the call to init
. It is not re-parsed when it is
mutated.
This object can be used to set three types of extra data:
Data about the customer. If these fields are set to be visible on the survey, they will be pre-populated with the values you supply, and the customer can change them.
If these fields are not visible on the survey, the value you supply will be set as a hidden field, and the customer will be unable to change it.
Key | Value which will be set on the survey |
---|---|
|
The customer’s name |
|
The customer’s email address |
|
The customer’s phone number |
|
The customer’s company name |
|
The customer’s postcode |
Metadata which applies to many different survey reponses. Used to segment reports within CustomerSure, for example producing a league table of NPS by Site, or CSAT by account type.
CustomerSure has two built in segment keys, staff_code
and site_code
, all
other segments are custom per-account.
If a selection question (i.e. checkboxes, radio buttons or select menu) is set up to ask the customer about this segment, it will be prepopulated with the value you supply; otherwise your value will be stored in a hidden field.
Metadata which applies only to this survey response, for example customer reference, invoice reference.
Any key-value pairs you pass in data-survey-params
that do not match a customer field or segment key
will be stored as unique metadata. This will only appear when the customer’s response to the survey
is being viewed within CustomerSure.
CustomerSure has two special-purpose unique metadata keys, reference
and machine_id
.
These two keys are used to provide hyperlinks from items of feedback in CustomerSure to records in other
business systems, i.e. CRM or ecommerce records.
Key | Purpose |
---|---|
|
The unique reference for this customer/transaction in another cloud-based system i.e. CUST1919, INV-2090, ACCOUNT 420. This should be the 'human readable' version of the reference. |
|
The machine-readable unique id for this customer/transaction/etc in another cloud-based system.
This usually appears in URLs as a database primary key or a GUID, and is not usually intended
to be read by humans, i.e. |
<script src="https://link-to-survey_widget.js"></script>
<div data-customersure-survey-widget
data-widget-params='{"org": "…", "survey": "…"}'>
data-survey-params='{"name": "Mariner"}'>
</div>
<script>CustomerSureSurveyWidget.toggleWidget();</script>