Change Log

Get Responses

Use the Get Responses API to retrieve the detailed response each of your contacts has provided for your survey. You can request up to 50,000 responses per call and perform multiple requests to retrieve all responses to update your contact database. If you are using a combination of metrics in the leading question of your surveys, the question_type will indicate if the response was to a NPS, CSAT or 5STAR survey.

API calls may be redirected to a temporary file stored on S3 depending on the number of responses you request. Your application will need to be able to follow redirects.

How to use the API

API Endpoint

Make a GET request to
https://DEMO.asknice.ly/api/v1/responses/sort_direction/pagesize/pagenumber/since_time/format/filter/sort_by/end_time?includestatustime=yes
Add filters[]=custom_field_c and values[]=Custom%20Value to your request parameter to filter on multiple fields. See the example how to filter by multiple properties below. The number of filters and values must be the same, and they need to match in order and make sure the first filter matches the first value, and so on. Incorrect matches will result in no data being returned.

Arguments

Argument Example Required Description
sort_direction desc Optional Default is asc (ascending)
pagesize 50 Required Default is 50,000 per request; maximum is 50,000 per request
pagenumber 1 Required Current page starting at 1, being the first page.
since_time 0 Required Pass in a unix timestamp to set the 'after date' from which you want to get all responses for
format json Optional Leave blank or set to json to get data in json format
csv to get data in csv format
filter Optional Leave blank or answered for all survey responses
raw for all surveys sent, this includes surveys sent and have not been responded to. published for only customer testimonials
sort_by responded Optional Leave blank or sent to sort by survey sent date
responded to sort by survey response date
end_time 0 Optional Leave blank to default the date to now or pass in a unix timestamp to set the 'before date' up to which you want to get all responses for.
includestatustime Optional Include this optional query parameter to also retrieve the unix timestamp based case_closed_time for your responses.

Limits

The maximum results per request is 50,000.

Examples

Example for last 5 response results from AskNicely in JSON format

Request 
curl -X GET \
    https://DEMO.asknice.ly/api/v1/responses/desc/5/1/0/json \
    --header "X-apikey: " \
    --location
Response 
{
    "success": true,
    "total": "10395",
    "totalpages": "2079",
    "pagenumber": "1",
    "pagesize": "5",
    "since_time": "0",
    "end_time": "1642981569",
    "data": [
        {
            "response_id": "54120",
            "person_id": "54121",
            "contact_id": "54121",
            "name": "Aiman Shakeel",
            "email": "3d2c555c.39829842@example.com",
            "answer": "8",
            "answerlabel": "8",
            "data": null,
            "comment": "",
            "note": null,
            "status": "",
            "dontcontact": null,
            "sent": "1614192119",
            "opened": "1614192119",
            "responded": "1614192119",
            "lastemailed": "1614192119",
            "created": "1614192119",
            "segment": null,
            "question_type": "nps",
            "published": "",
            "publishedname": "",
            ...
        },
        ...
        {
            "response_id": "54109",
            "person_id": "54110",
            "contact_id": "54110",
            "name": "Safeer Jaffer",
            "email": "8437e1fd.a7f7659e@example.com",
            "answer": "8",
            "answerlabel": "8",
            "data": null,
            "comment": "",
            "note": null,
            "status": "",
            "dontcontact": null,
            "sent": "1615088928",
            "opened": "1615088928",
            "responded": "1615088928",
            "lastemailed": "1615088928",
            "created": "1615088928",
            "segment": null,
            "question_type": "nps",
            "published": "",
            "publishedname": "",
            ...
        }
    ]
}

Example for last 5 response results from AskNicely in JSON format including case_closed_time

Request 
curl -X GET \
    "https://DEMO.asknice.ly/api/v1/responses/desc/5/1/0/json?includestatustime=yes" \
    --header "X-apikey: " \
    --location
Response 
{
    "success": true,
    "total": "10395",
    "totalpages": "2079",
    "pagenumber": "1",
    "pagesize": "5",
    "since_time": "0",
    "end_time": "1642981569",
    "data": [
        {
            "response_id": "54120",
            "person_id": "54121",
            "contact_id": "54121",
            "name": "Aiman Shakeel",
            "email": "3d2c555c.39829842@example.com",
            "answer": "8",
            "answerlabel": "8",
            "data": null,
            "comment": "",
            "note": null,
            "status": "Closed",
            "case_closed_time" : "1677805059",
            ...
        },
        ...
        {
            "response_id": "54109",
            "person_id": "54110",
            "contact_id": "54110",
            "name": "Safeer Jaffer",
            "email": "8437e1fd.a7f7659e@example.com",
            "answer": "8",
            "answerlabel": "8",
            "data": null,
            "comment": "",
            "note": null,
            "status": "",
            "case_closed_time" : null,
            ...
        }
    ]
}

Example for last 3 response results from AskNicely in CSV format

Request 
curl -X GET \
    https://DEMO.asknice.ly/api/v1/responses/desc/3/1/0/csv \
    --header "X-apikey: " \
    --location
Response 
response_id, person_id, contact_id, name, email, answer, sent, opened, responded, created, segment, question_type, survey_template
3, 123, 456, John Doe, johndoe@asknice.ly, 10, 1562641317, 1562641317, 1562641317, 1552610049, new, nps, Default
2, 433, 643, Jane Smith, janesmith@asknice.ly, 9, 1562641316, 1562641316, 1562641320, 1552610049, 1524789143, new, nps, Default
1, 674, 542, Steve Rogers, srogers@asknice.ly, 10, 1562641251, 1562641252, 1562641257, 1523828237, 1523828195, new, nps, Default

Example for last 5 published testimonials

Request 
curl -X GET \
    https://DEMO.asknice.ly/api/v1/responses/desc/5/1/0/json/published \
    --header "X-apikey: " \
    --location
Response 
{
    "success": true,
    "total": "2",
    "totalpages": "1",
    "pagenumber": "1",
    "pagesize": "5",
    "since_time": "0",
    "end_time": "1625783435",
    "data": [
        {
            "response_id": "455",
            "person_id": "3",
            "contact_id": "3",
            "name": "John Doe",
            "email": "johndoe@example.com",
            "answer": "10",
            "answerlabel": "10",
            "comment": "I love this gym!",
            "sent": "1619849044",
            "created": "1619849044",
            "question_type": "nps",
            "published": "approved",
            "publishedname": "John Doe",
            ...
        },
        {
            "response_id": "644",
            "person_id": "2",
            "contact_id": "2",
            "name": "Jane Smith",
            "email": "janesmith@example.com",
            "answer": "10",
            "answerlabel": "10",
            "comment": "The gym is so clean!",
            "sent": "1619849042",
            "created": "1619849042",
            "question_type": "nps",
            "published": "approved",
            "publishedname": "John Smith",
            ...
        }
    ]
}

Example for last 5 response results from AskNicely in JSON format using filters and values parameters

Request 
curl -X GET \
    "https://DEMO.asknice.ly/api/v1/responses/desc/5/1/0/json?filters[]=city_c&filters[]=country_c&values[]=Abbotsford&values[]=Canada" \
    --header "X-apikey: " \
    --location
Response 
{
    "success": true,
    "total": "323",
    "totalpages": "65",
    "pagenumber": "1",
    "pagesize": "5",
    "since_time": "0",
    "end_time": "1642981569",
    "data": [
        {
            "response_id": "54120",
            "person_id": "54121",
            "contact_id": "54121",
            "name": "Aiman Shakeel",
            "email": "3d2c555c.39829842@example.com",
            "answer": "8",
            "answerlabel": "8",
            "data": null,
            "comment": "",
            "note": null,
            "status": "",
            "dontcontact": null,
            "sent": "1614192119",
            "opened": "1614192119",
            "responded": "1614192119",
            "lastemailed": "1614192119",
            "created": "1614192119",
            "segment": null,
            "question_type": "nps",
            "published": "",
            "publishedname": "",
            "city_c": "Abbotsford",
            "country_c": "Canada",
            ...
        },
        ...
        {
            "response_id": "54109",
            "person_id": "54110",
            "contact_id": "54110",
            "name": "Safeer Jaffer",
            "email": "8437e1fd.a7f7659e@example.com",
            "answer": "8",
            "answerlabel": "8",
            "data": null,
            "comment": "",
            "note": null,
            "status": "",
            "dontcontact": null,
            "sent": "1615088928",
            "opened": "1615088928",
            "responded": "1615088928",
            "lastemailed": "1615088928",
            "created": "1615088928",
            "segment": null,
            "question_type": "nps",
            "published": "",
            "publishedname": "",
            "city_c": "Abbotsford",
            "country_c": "Canada",
            ...
        }
    ]
}

Errors

401 (Unauthorized)

Invalid API key. Please check if the API key you are using is correct or valid. 
{
    "success": false,
    "msg": "Could not find user with API key \"invalid_api_key\""
}

400 (Bad Request)

An error 400 with a message is returned when the request exceeds the limit. 
{
    "success": false,
    "msg": "The request exceeds the results per request limit."
}

Redirects

302 (Found)

Not setting your requests to follow redirection will return this response. 
Redirecting to https://asknicely-tenant-files.amazonaws.com/download/.../responses_1625713191.json
For curl requests, set the --location or -L option to avoid this redirection message.