CustomerSure API

Overview

This documentation describes the resources that make up the official CustomerSure API v1. If you have any problems or requests please contact support.

HTTP `Accept` Header

The 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

Schema

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.

User Agent Header

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

Parameters

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.

Date periods

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

Pagination

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.

Headers

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.

pagination

HTTP Redirects

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.

HTTP Verbs

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.

Authentication

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

Errors

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.

Attributes

message:

String A human readable version of the error message.

errors:

Array of validation errors, not always present

Validation error attributes

resource:

String URL to the resource presenting the error. For new resources, this will point to the collection URL, i.e. /feedback_requests/

field:

String The field presenting the error

error:

String A short code indicating the type of error. Possible values are:

required
invalid_format
wrong_length
invalid_value
forbidden_value
invalid_date
custom

In exceptional circumstances, the 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.

extra_info:

Extra info attributes

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 field
minimum 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 field
less_than the largest allowed value for a numeric field
must_be additional constraints on numeric fields. Possible values are even, odd and integer.
message a human friendly message for custom errors.

HTTP Status Code Summary


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.

Example error response


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

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.

Attributes

id:

integer The individual ID for the feedback request.

email:

string The customer's email address.

state:

string

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.

first_name:

string The customer's first name - used in the email.

surname:

string The customer's surname.

survey_id:

string The ID of the survey that the feedback request email links to.

email_template_id:

string The ID of the email template you would like the customer to receive.

reference:

string If the feedback request originates from an event in another system this field can contain the human friendly reference from that system. E.g. Order/Invoice/Ticket "#1234". The reference field can be used in the CustomerSure UI to link back to the original system.

machine_id:

string If the feedback requests originates from an event in another system this field can contain the Unique ID from that system. Order/Invoice/Ticket "#1234" may have an underlying ID of "345-457-346-234". The machine_id can be used in the CustomerSure UI to link back to the original system.

send_at:

string The time the feedback request email should be sent.

sent_at:

timestamp The time the email was sent

created_at:

timestamp

updated_at:

timestamp

not_sent_reason:

string If the email was not sent, this field shows why.

delivery_failure:

string The smtp delivery error if the email could not be delivered.

ignore_throttle:

string Default false. If you set this field to true, the organisation’s ‘over-survey protection’ settting will be ignored for this feedback request, and it will be sent regardless of how many feedback requests have already been delivered to this customer. Use with caution.

data:

array of data See #create feedback request for usage examples

reminders:

array of reminders See #create feedback request for usage examples

Data attributes

id:

integer

key:

string

value:

string

Reminders

id:

integer

send_at:

string The time the reminder should be sent.

sent_at:

timestamp The time the reminder was sent

email_template_id:

integer

text_message_template_id:

integer

not_sent_reason:

string If the reminder was not sent, this field shows why.

delivery_failure:

string The delivery error if the reminder could not be delivered.

Create a feedback request

Creates a new pending feedback request. At the send_at time an email will be sent to your customer asking them for feedback.

Parameters

email:

required (optional for SMS sends) The customer's email address.

send_at:

required The time in the future when you'd like the feedback request email to be sent.

survey_id:

required The ID for the survey you would like the customer to complete. You can get your survey IDs by editing your surveys in CustomerSure. On the survey edit screen the ID will be at the end of the URL. The call will fail if you pass a survey ID that you do not own.

email_template_id:

required (Ignored for SMS sends) The ID for the email template you would like this request to use. The easiest way to find your email template ID is by editing the template in CustomerSure. On the edit screen the ID will be at the end of the URL.

first_name:

optional The customer's first name. If set, we'll use this in the email to greet your customer.

surname:

optional The customer's surname. Useful to help you identify the customer when you look at the queue, or sent requests.

reference:

optional If the feedback request originates from an event in another system this field can contain the human friendly reference from that system, e.g. "#1234" to represent your ticket/order/invoice/etc.

machine_id:

optional If the feedback requests originates from an event in another system this field can contain the Unique ID from that system, e.g. "345-457-346-234" as the ID for your ticket/order/invoice/etc. You should omit this field if your IDs are the same as your references.

external_link:

optional If you only wish to log the feedback request in CustomerSure, without us sending it via SMS/email, set this option to 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.

data[]:

optional (Array)

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.

sms:

optional (Hash)

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.

reminders[]:

optional (Array)

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

Data attributes

key:

string Maximum 30 chars

value:

string Maximum 100 chars

SMS attributes

number:

required (string) The mobile number you would like the message to be sent to. This field cannot be left blank if you provide the sms key.

text_message_template_id:

required (Integer)

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.

Reminder attributes

You must provide either email_template_id or text_message_template_id, but not both.

send_at:

required The time in the future when you'd like the reminder to be sent.

email_template_id:

required for email feedback requests (Integer)

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.

text_message_template_id:

required for SMS feedback requests (Integer)

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.

Returns

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

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.

Attributes

id:

integer The individual ID for the feedback response.

reference:

string If the feedback was created via an event in another system this field will contain your (human friendly) reference used by that system. E.g. ticket/order/invoice "#6764"

machine_id:

string If the feedback originated from an an event in another system this field will contain the Unique ID from that system. Order/Invoice/Ticket "#1234" may have an underlying ID of "345-457-346-234".

fields:

hash The following keys and their values will be included:

name
first_name - Derived by splitting the name on whitespace (first token).
last_name - Derived by splitting the name on whitespace (other token[s]).
person_code - Your Unique ID for the person.
telephone_number
company_name
company_code - Your Unique ID for the company.
address_line_1
postcode

Any additional data assigned to the feedback that does not set these fields will also be included here as key/value pairs. These values can be set via the UI, file uploads or the data attribute when creating new feedback requests through this API.

answers:

array of answers

submitted_at:

timestamp

feedback_request:

hash Hash of the feedback request object if present or null.

survey:

hash Hash of the survey completed by the customer.

Answer attributes

question_id:

integer

question:

string The question text.

answer:

string The customer's answer.

type:

string The type of question asked. It will be one of:
Rating - Rating questions.
Text - Free text questions.
Dropdown - Select box questions.
Radio - Radio button questions.
Checkbox - Checkbox questions.

Survey attributes

id:

integer The ID of the survey completed.

name:

string Your name for the survey completed.

Retrieve an existing feedback response

Retrieves the feedback response with the given ID.

Parameters

id:

required The ID of the desired feedback response.

Returns

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",
    "first_name": "Kate",
    "last_name": "",
    "person_code": "member-123",
    "telephone_number": "01234 567 890",
    "address_line_1": "",
    "postcode": "NE4 8AW",
    "company_name": "Acme",
    "company_code": "company-789"
  },
  "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"
  }
}

List feedback responses

You can list all feedback responses. They are returned in reverse chronological order.

Parameters

page:

optional If there are more than 30 feedback responses, you can specify a page number.

per_page:

optional Specify your own page size - up to a maximum of 100.

created_since:

optional

Only return feedback responses created since the specified timestamp.

updated_since:

optional

Only return feedback responses updated since the specified timestamp.

email:

optional

Only return feedback responses left by the email address provided

survey_ids[]:

optional, Array

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

site_ids[]:

optional, Array

E.g. ?site_ids[]=1234&site_ids[]=5678

Only return feedback responses from the specified sites.

staff_ids[]:

optional, Array

E.g. ?staff_ids[]=89&staff_ids[]=76

Only return feedback responses relating to the specified staff members.

Returns

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",
      "first_name": "Kate",
      "last_name": "",
      "person_code": "member-123",
      "telephone_number": "01234 567 890",
      "address_line_1": "",
      "postcode": "NE4 8AW",
      "company_name": "Acme",
      "company_code": "company-789"
    },
    "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"
    }
  },
  { … },
  { … },
  { … }
]

Show rating question

Returns detailed scores and stats on the responses to a rating question.

Parameters

from_time:

optional Override the start time for the query. E.g. ?from_time=2015-01-01T00:00Z (Defaults to midnight 30 days ago)

to_time:

optional Override the end time for the query. E.g. ?to_time?2015-01-31T23:59Z (Defaults to now)

period:

optional Specify a relative date/time period. Overrides from_time/to_time. See date periods for full documentation.

company_name:

optional Only retrieve scores for the given company name. This is a wildcard search, so, for example company_name=cyber will match “Cyberdyne Systems”

survey_ids[]:

optional An array of survey IDs. We will only return scores from the surveys you specify. Survey IDs can be found in the survey view/edit URLS when logged in or simply contact support and we’ll get them to you immediately. E.g. ?survey_ids[]=234&survey_ids[]=456

site_ids:

optional An array of site IDs. We will only return scores for the sites you specify. Site IDs can be found in site view/edit URLS when logged in, or by contacting support. E.g. ?site_ids[]=789

staff_ids:

optional An array of staff IDs. We will only return scores for the staff you specify. E.g. ?staff_ids[]=789

Returns

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
}

Metrics

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.

Retrieve your response rate

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.

Parameters

from_time:

optional Override the start time for the query. E.g. ?from_time=2015-01-01T00:00Z (Defaults to midnight, 32 days ago)

to_time:

optional Override the end time for the query. E.g. ?to_time=2015-01-31T23:59Z (Defaults to midnight, 2 days ago)

survey_ids[]:

optional (Array) Only consider feedback requests for the specified surveys E.g. ?survey_ids[]=1234&survey_ids[]=5678

site_ids:

optional (Array) Only consider feedback requests for the specified sites E.g. ?site_ids[]=4321&site_ids[]=8765

Returns

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
}

Retrieve your Net Promoter Score

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.

Parameters

from_time:

optional Override the start time for the query. E.g. ?from_time=2015-01-01T00:00Z (Defaults to midnight 30 days ago)

to_time:

optional Override the end time for the query. E.g. ?to_time?2015-01-31T23:59Z (Defaults to now)

period:

optional Specify a relative date/time period. Overrides from_time/to_time. See date periods for full documentation.

company_name:

optional Only retrieve NPS for the given company name. This is a wildcard search, so, for example company_name=cyber will match “Cyberdyne Systems”

survey_ids[]:

optional An array of survey IDs. We will only return NPS data from the surveys you specify. Survey IDs can be found in the survey view/edit URLS when logged in or simply contact support and we’ll get them to you immediately. E.g. ?survey_ids[]=234&survey_ids[]=456

site_ids:

optional An array of site IDs. We will only return NPS data for the sites you specify. Site IDs can be found in site view/edit URLS when logged in, or by contacting support. E.g. ?site_ids[]=789

staff_ids:

optional An array of staff IDs. We will only return NPS data for the staff you specify. E.g. ?staff_ids[]=789

Returns

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
}

Retrieve your CSAT Score

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.

Parameters

from_time:

optional Override the start time for the query. E.g. ?from_time=2015-01-01T00:00Z (Defaults to midnight 30 days ago)

to_time:

optional Override the end time for the query. E.g. ?to_time?2015-01-31T23:59Z (Defaults to now)

period:

optional Specify a relative date/time period. Overrides from_time/to_time. See date periods for full documentation.

company_name:

optional Only retrieve CSAT for the given company name. This is a wildcard search, so, for example company_name=cyber will match “Cyberdyne Systems”

survey_ids[]:

optional An array of survey IDs. We will only return CSAT data from the surveys you specify. Survey IDs can be found in the survey view/edit URLS when logged in or simply contact support and we’ll get them to you immediately. E.g. ?survey_ids[]=789&survey_ids[]=234

site_ids:

optional An array of site IDs. We will only return CSAT data for the sites you specify. Site IDs can be found in site view/edit URLS when logged in, or by contacting support. E.g. ?site_ids[]=156

staff_ids:

optional An array of staff IDs. We will only return NPS data for the staff you specify. E.g. ?staff_ids[]=789

Returns

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
}

Sites

Site are your geographical business units. Examples of sites include individual hotels, restaurants, clinics, branches, holiday parks, shops or offices.

Attributes

id:

string Our unique identifier for the site.

site_code:

string Your unique identifier for the site.

name:

string The name of the site.

city:

string The name of the city where the site resides.

region:

string Region can be the county, state, or your own region name that you’d like to report on, such as "North East". It’s best to use region consistently across all your sites.

site_type:

string Classify your sites into different types, i.e. 'Store', 'Office'

Create a site

Creates a new site.

Parameters

site_code:

required Your unique identifier for the site.

name:

required The site name.

city:

optional - but recommended The name of the city where the site resides.

region:

required County/State or your own defined region.

site_type:

optional What type of site this is

Returns

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

Retrieve an existing site

Retrieves the site with the given id.

Parameters

id:

required The unique id of the desired site.

Returns

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

Update a site

Updates a site record.

Parameters

site_code:

option Your unique identifier for the site.

name:

optional The site name.

city:

optional The name of the city where the site resides.

region:

optional County/State or your own defined region.

site_type:

optional What type of site this is

Returns

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

List sites

You can list all sites. The site are returned sorted by name.

Parameters

page:

optional If there are more than 30 sites, you can specify a page number.

per_page:

optional Specify your own page size - up to a maximum of 100.

Returns

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

Staff are the people in your business.

Attributes

id:

string Our unique identifier for this staff member.

code:

string Your unique identifier for this person

first_name:

string This person’s given name.

surname:

string This person’s family name.

email:

string This person’s email address

time_zone:

string The time zone this person lives/works in.

deactivated_at:

datetime If you have deactivated this person’s CustomerSure account, this will be the date and time of that deactivation.

team_id:

string If you have placed this staff member in a team, this is the ID of that team

Retrieve an existing staff member

Retrieves the staff member with the given id.

Parameters

id:

required The unique id of the desired staff member.

Returns

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

List staff

You can list all staff, and search for a staff member by email or code.

Parameters

page:

optional If there are more than 30 staff, you can specify a page number.

per_page:

optional Specify your own page size - up to a maximum of 100.

email:

optional Search for staff matching the email address you provide.

code:

optional Search for staff matching the third-party code you provide. This code is your reference for this staff member from your own systems.

Returns

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

Surveys

Attributes

id:

integer The individual ID for the survey.

name:

string The name of the survey.

locale:

string The language the survey is in.
Possible locales are: en en-US fr de it es es-MX nl sv da ja ar zh-CN no he id th fi.

questions:

array of questions

Question attributes

id:

integer

question:

string The question text.

anwer_type:

string The type of question asked. It will be one of:
Rating - Rating questions.
Text - Free text questions.
Dropdown - Select box questions.
Radio - Radio button questions.
Checkbox - Checkbox questions.

List surveys

You can list all surveys. The surveys are returned sorted by name.

Parameters

page:

optional If there are more than 30 surveys, you can specify a page number.

per_page:

optional Specify your own page size - up to a maximum of 100.

Returns

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

Email Templates

Attributes

id:

integer The individual ID for the email template.

name:

string The name of the email template.

from_name:

string The name used in the email from header, i.e. Jane Smith in
"Jane Smith <jane@example.com>"

from_email:

string The email address used in the from header. i.e. jane@example.com

subject:

string The subject line of the email template.

body:

text The body text of the email template.

locale:

string The language the email template is in.
Possible locales are: en en-US fr de it es es-MX nl sv da ja ar zh-CN no he id th fi.

archived:

boolean Whether the email template has been archived in the CustomerSure UI; meaning it will not be selectable for future sends.

List email templates

You can list all email templates. The email templates are returned sorted by name.

Parameters

page:

optional If there are more than 30 email templates, you can specify a page number.

per_page:

optional Specify your own page size - up to a maximum of 100.

Returns

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
  },
  { … },
  { … },
  { … }
]

Text Message Templates

Attributes

id:

integer The individual ID for the text message template.

name:

string The name of the text message template.

body:

string The body of the text message template.

locale:

string The language the text message template is in.
Possible locales are: en en-US fr de it es es-MX nl sv da ja ar zh-CN no he id th fi.

archived:

boolean Whether the text message template has been archived in the CustomerSure UI; meaning it will not be selectable for future sends.

List text message templates

You can list all text message templates. The text message templates are returned sorted by name.

Parameters

page:

optional If there are more than 30 text message templates, you can specify a page number.

per_page:

optional Specify your own page size - up to a maximum of 100.

Returns

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
  },
  { … },
  { … },
  { … }
]

Widget Javascript API

Introduction

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.

Installing the widget

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>

Widget API

Once installed, the widget has the following public API

Toggle Widget

CustomerSureSurveyWidget.toggleWidget();

Toggle the widget’s state: If it is visible, hide it, if it is hidden, show it.

Pass Parameters

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:

Customer 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
`name`	The customer’s name
`email`	The customer’s email address
`telephone_number`	The customer’s phone number
`company_name`	The customer’s company name
`postcode`	The customer’s postcode

Segmentation metadata

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.

Unique metadata

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
`reference`	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.
`machine_id`	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. `INV-2090` could have a GUID of `a87ee488-645c-432a-817f-6690152da8c9`.


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

REST API

Widget JS API

Overview

HTTP Accept Header

Schema

User Agent Header

Parameters

Date periods

Pagination

Headers

HTTP Redirects

HTTP Verbs

Authentication

Errors

Attributes

Validation error attributes

HTTP Status Code Summary

Example error response

Feedback Requests

Attributes

Data attributes

Reminders

Create a feedback request

Parameters

Data attributes

SMS attributes

Reminder attributes

Returns

Feedback Responses

Attributes

Answer attributes

Survey attributes

Retrieve an existing feedback response

Parameters

Returns

List feedback responses

Parameters

Returns

Show rating question

Parameters

Returns

Metrics

Retrieve your response rate

Parameters

Returns

Retrieve your Net Promoter Score

Parameters

Returns

Retrieve your CSAT Score

Parameters

Returns

Sites

Attributes

Create a site

Parameters

Returns

Retrieve an existing site

Parameters

Returns

Update a site

Parameters

Returns

List sites

Parameters

Returns

Staff

Attributes

Retrieve an existing staff member

Parameters

Returns

List staff

Parameters

Returns

Surveys

Attributes

Question attributes

List surveys

Parameters

Returns

Email Templates

HTTP `Accept` Header