API Documentation - SurveyMill

What this API does

Instead of uploading contacts via the website, this API allows you to send a survey to contacts one at a time, programmatically. At the moment you cannot have contacts uploaded via the website and trigger sending via the API. To use the API you will need to be able to send an HTTP POST request and set a custom header.

Enabling the API on your Account

By default, we hide the API options to keep things simple for everyone. To turn on the API, follow these steps:

Go to the Account page.
Tick the “Yes, I would like to use the API to send surveys” checkbox.
Click on the blue box and make a note of your API key, you will need this later.

Switching a survey to use the API

You can now choose whether you want a Survey to use web uploads or the API on a survey by survey basis. To start sending a survey via the API, follow the two steps below.

Once enabled, you will be able to see additional information when editing a survey. To allow you to add contacts to a survey using the API, you need to remove any existing contacts from the survey and tick the “Use the API to integrate this survey with your software” checkbox underneath the contact upload box. Your API key (same as on the Account page) and survey ID for this survey will be shown. You will need both of these items to send to the API.
When you are ready to start sending via the API, click the “Activate API Survey” button at the bottom of the Edit Survey page (It will have replaced the “Start Survey” button).

Sending to the API

Construct a HTTP POST request in the following form. Values in braces should be replaced {with your own values}.

  POST HTTPS://app.surveymill.co.uk/api/survey/{Survey ID}
     Custom Header:
         Name: ApiKey
         Value: {Api Key}
     Body:
       Encoding: URL Form Encoded
       Fields:
         Name: {Contact Name}
         Number: {UK Contact Number}

After inserting your own Survey ID, Api Key, Contact Name and Contact Number an example post request using cURL might look like this:

curl -X POST -H "ApiKey: live_8a6d4e6f721dae78a6d4e6f721dae7901ac7865" -d "Name=Joe%20Bloggs&Number=447700900461" "https://app.surveymill.co.uk/api/survey/2543"

Responses and Errors

The API will send back a HTTP response code and a JSON formatted body containing a description. This is in the following format:

{
  "message": "Survey Not Started"
}

HTTP response codes, messages and troubleshooting hints.

200 – Success

Everything is fine, we will send out the survey shortly.

400 – Invalid Mobile Number

The mobile number you sent us doesn’t look like a real number, double check it.

400 – Survey has not been created for API use

You missed step 1 of the “Switching a survey to use the API” above.

400 – Numbers outside of the UK are not currently supported

Sorry, we are UK only for the moment, get in touch with us if you need to send overseas.

401 – No API key

You missed off, or have given the wrong name to, the custom ApiKey header in the Sending to the API section above.

401 – Invalid API key

The API key you sent us doesn’t match the one on your Account Page, double check it.

402 – Not Enough Credit

You haven’t got enough credit on your account to send this survey. Time to top-up.

403 – Unauthorised Survey

The request is fine, but you don’t have permissions to send to this survey. Is your Survey ID correct?

404 – Survey Not Found

We couldn’t find this survey. Is your Survey ID correct?

406 – Survey Not Started

The request is fine, but you missed step 2 of the “Switching a survey to use the API” above.

409 – Duplicate recipient on survey

You have already sent this survey to this recipient, we don’t support sending the survey multiple times.

500 – Send Failure

Something went wrong on our end. Get in touch and let us know what you were trying.

GET’ing your results

Construct a HTTP GET request in the following form. Values in braces should be replaced {with your own values}.

  GET https://app.surveymill.co.uk/api/response/{Survey ID}
     Custom Header:
         Name: ApiKey
         Value: {Api Key}

After inserting your own Survey ID and Api Key an example GET request using cURL might look like this:

curl -X GET -H "ApiKey: live_8a6d4e6f721dae78a6d4e6f721dae7901ac7865" "HTTPS://app.surveymill.co.uk/api/response/174"

You can also filter results by providing a From Reply Date an example GET request using cURL might look like this

curl -X GET -H "ApiKey: live_8a6d4e6f721dae78a6d4e6f721dae7901ac7865" "https://app.surveymill.co.uk/api/response/174?fromDate=2000-03-31"

Date format must conform to ISO 8601 as shown below:

2000-03-31