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

{
    "success": false,
    "msg": "The request exceeds the results per request limit."
}

Redirecting to https://asknicely-tenant-files.amazonaws.com/download/.../responses_1625713191.json