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.

Current Version

The current version of the API is version 1. We’re likely to release v2, v3 etc in future. To help 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’.


# 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

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 email your customers for feedback. Each feedback request specifies who we should email, at what time and what survey you'd like them to fill in. The API allows you to create, delete and update your feedback requests. You can retrieve individual feedback requests as well as list all the pending, or sent 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 Email templates let you override the feedback request email sent to the customer. This field holds the template ID, if you choose to use your own instead of the CustomerSure default.
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.
data:
array of data See #create feedback request for usage examples

Data attributes

id:
integer
key:
string
value:
string

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 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:
optional The ID for the email template you would like this request to use. You can get your email template IDs by editing the templates under settings in CustomerSure. On the edit screen the ID will be at the end of the URL. If this field is left blank, a sensible default email (writen by CustomerSure) will be used instead.
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.
data:
optional

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.

Data attributes

key:
string Maximum 30 chars
value:
string Maximum 100 chars

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":"2014-08-20T18:00:00+0100",
              "survey_id":1484,
              "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 2014" }]
            }' \
       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": null,
  "reference": "#1014",
  "machine_id": "8736245",
  "send_at": "2014-08-20T17:00:00Z",
  "sent_at": null,
  "created_at": "2014-08-19T16:30:14Z",
  "updated_at": "2014-08-19T16:30:14Z",
  "not_sent_reason":null,
  "delivery_failure":null
  "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 2014" }
  ]
}

Retrieve an existing feedback request

Retrieves the feedback request with the given ID.

Parameters

id:
required The ID of the desired feedback request.

Returns

The feedback request if a valid ID parameter was provided. Returns an error otherwise.

# DEFINITION
GET https://api.customersure.com/feedback_requests/:id

# EXAMPLE REQUEST
curl -H 'Accept: application/vnd.customersure.v1+json;' \
     -H 'Authorization: Token token="b7c2b8ccbc967726cbdadf46406a3912"' \
     https://api.customersure.com/feedback_requests/1
# EXAMPLE RESPONSE
Status: 200 OK
{
  "id": 1,
  "email": "john.smith@example.com",
  "state": "pending",
  "first_name": "John",
  "surname": "Smith",
  "survey_id": 1,
  "email_template_id": null,
  "reference": null,
  "machine_id": null,
  "send_at": "2014-08-07T09:00:00Z",
  "sent_at": null,
  "created_at": "2014-08-06T15:57:41Z",
  "updated_at": "2014-08-06T15:57:41Z",
  "not_sent_reason": null,
  "delivery_failure": null,
  "data":[]
}

Update a feedback request

Updates a pending feedback request. Updating a feedback request is only possible when it is in the queue, i.e. before it is sent.

Parameters

email:
optional The customer's email address.
send_at:
optional The time in the future when you'd like the feedback request email to be sent.
survey_id:
optional 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:
optional The ID for the email template you would like this request to use. You can get your email template IDs by editing the templates under settings in CustomerSure. On the edit screen the ID will be at the end of the URL. If this field is left blank, a sensible default email (writen by CustomerSure) will be used instead.
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.
data:
optional To update an existing data item you need to pass in the ID alongside the key and/or value that you'd like updated. New key/value pairs will added to the feedback request.

Data attributes

id:
integer Required to update an existing data item.
key:
string Maximum 30 chars.
value:
string Maximum 100 chars

Returns

The updated feedback request upon success. Returns an error otherwise.

# DEFINITION
PATCH https://api.customersure.com/feedback_requests/: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 '{"email":"kate@example.com"}' \
       https://api.customersure.com/feedback_requests/208073
# EXAMPLE RESPONSE
Status: 200 OK
{
  "id": 208073,
  "email": "kate@example.com",
  "state": "pending",
  "first_name": "John",
  "surname": "Smith",
  "survey_id": 1484,
  "email_template_id": null,
  "reference": "#1014",
  "machine_id": "8736245",
  "send_at": "2014-08-20T17:00:00Z",
  "sent_at": null,
  "created_at": "2014-08-19T16:30:14Z",
  "updated_at": "2014-08-19T16:30:14Z",
  "not_sent_reason":null,
  "delivery_failure":null,
  "data":[]
}

List feedback requests

You can list all feedback requests, filter by state or survey IDs. The feedback requests are returned sorted by send_at, in reverse chronological order.

Parameters

states:
optional (Array)

Only return feedback requests with the specified state(s). E.g. ?states[]=pending&states[]=sent.

Valid states: pending, sent, not_sent

survey_ids:
optional (Array)

Only return feedback requests with the specified surveys E.g. ?survey_ids[]=1234&survey_ids[]=5678.

page:
optional If there are more than 30 feedback requests, 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 feedback requests.

# DEFINITION
GET https://api.customersure.com/feedback_requests

# EXAMPLE REQUEST
curl -H 'Accept: application/vnd.customersure.v1+json;' \
     -H 'Authorization: Token token="ec76c296df321768ba4cc41a445bfb6f"' \
     https://api.customersure.com/feedback_requests
# EXAMPLE RESPONSE
Status: 200 OK
Link: <https://api.customersure.com/feedback_requests?page=1>; rel="first", <https://api.customersure.com/feedback_requests?page=1>; rel="last"
X-Total-Pages: 1
X-Total-Count: 4
[
  {
    "id": 1,
    "email": "john.smith@example.com",
    "state": "pending",
    "first_name": "John",
    "surname": "Smith",
    "survey_id": 1,
    "email_template_id": null,
    "reference": null,
    "machine_id": null,
    "send_at": "2014-08-07T09:00:00Z",
    "sent_at": null,
    "created_at": "2014-08-06T15:57:41Z",
    "updated_at": "2014-08-06T15:57:41Z",
    "not_sent_reason": null,
    "delivery_failure": null,
    "data": []
  },
  { … },
  { … },
  { … }
]

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".
survey_id:
integer The ID of the survey that the customer completed.
fields:
hash Key/value pairs including the customer’s name, email and telephone_number, alongside and any data you set against the feedback through a feedback request.
answers:
array of answers
submitted_at:
timestamp
feedback_request:
hash Hash of the feedback request object if present or null.

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.

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,
  "survey_id": 277,
  "fields":{
    "email": "kate@example.com",
    "name": "Kate",
    "telephone_number": 01234 567 890
  },
  "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":"2014-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": "2014-07-08T23:45:19Z",
    "sent_at": "2014-07-08T23:45:20Z",
    "created_at": "2014-07-07T23:45:19Z",
    "updated_at": "2014-07-08T23:45:20Z",
    "deletion_requested_at": null,
    "not_sent_reason": null,
    "delivery_failure": null
  }
}

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.
updated_since:
optional

Only return feedback responses updated since the specified timestamp.

Note that creation of a feedback response will set its updated_at field to the time of creation, so specifying this parameter will return responses both created and updated since your timestamp.

email:
optional

Only return feedback responses left by the email address provided

survey_ids:
optional

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

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,
    "survey_id": 2166,
    "fields":{
      "email": "kate@example.com",
      "name": "Kate",
      "telephone_number": "01234 667 890"
    },
    "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":"2014-08-08T23:45:19Z",
    "updated_at":"2014-09-01T11:00:01Z",
    "feedback_request": null
  },
  { … },
  { … },
  { … }
]

Metrics

You can access key metrics from your CustomerSure account through these endpoints. Currently you can retrieve your response rate and Net Promoter® results. We’re building our API based on customer demand, so if there’s something missing that you’d like to see, please contact support and we’ll look into adding 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

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 through the optional parameters.

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)
question_ids:
optional An array of NPS question IDs. This is useful if you have multiple surveys asking the NPS question but you only want data from one or some of them, instead of all of them (the default). To get your NPS question IDs please contact support and we’ll get them to you immediately. E.g. ?question_ids[]=234&question_ids[]=456

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
}

Sites

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

Attributes

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.
country_code:
string A two-letter code for the country where the site resides. See ISO3166-1

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:
optional - but recommended County/State or your own defined region.
Note: Currently region is required if you specify country_code.
country_code:
optional - but recommended The two-letter country code for the country where the site resides. E.g. US or GB

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",
              "country_code":"UK"
            }' \
       https://api.customersure.com/sites
# EXAMPLE RESPONSE
Status: 201 Created
{
  "site_code": "hq",
  "name": "Head Office",
  "city": "Newcastle",
  "region": "Tyne and Wear",
  "country_code": "UK"
}

Retrieve an existing site

Retrieves the site with the given site_code.

Parameters

site_code:
required The unique site_code of the desired site.

Returns

The site if a valid site_code parameter was provided. Returns an error otherwise.

# DEFINITION
GET https://api.customersure.com/sites/:site_code

# 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
{
  "site_code": "hq",
  "name": "Head Office",
  "city": "Newcastle",
  "region": "Tyne and Wear",
  "country_code": "UK"
}

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. (note: Currently region is required if you specify a country_code.)
country_code:
optional The two-letter country code for the country where the site resides. E.g. US or GB

Returns

The updated site upon success. Returns an error otherwise.

# DEFINITION
PATCH https://api.customersure.com/sites/:site_code

# 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
{
  "site_code": "hq",
  "name": "Main Office",
  "city": "Newcastle",
  "region": "Tyne and Wear",
  "country_code": "UK"
}

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
[
  {
    "site_code": "hq",
    "name": "Head Office",
    "city": "Newcastle",
    "region": "Tyne and Wear",
    "country_code": "UK"
  },
  { … },
  { … },
  { … }
]