Skip to content
Open Screeb

Search, summarize and aggregate the survey responses of your workspace from your backend.

Send your workspace API key as a Bearer token, as for the Screeb API.

Each endpoint accepts 30 requests per minute per API key.

The response API is accessible via the following endpoint: SEARCH - https://api.screeb.app/1.0/survey/:survey_ids/response

:survey_ids must be replaced by a list of survey IDs separated by a comma (,) or a wildcard (*) for selecting all organization surveys.

Terminal window
curl -X SEARCH https://api.screeb.app/1.0/survey/*/response \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <YOUR-API-KEY>" \
-d '{
"filters_bool": "AND",
"filters": [
{ "type": "response", "key": "completion", "operator": "eq", "value": "fully_completed" },
{ "type": "response", "key": "language", "operator": "in", "values": ["en", "fr"] }
],
"size": 100,
"offset": 0,
"range": {
"field": "created_at",
"start": "2020-01-01T00:00:00.000Z",
"end": "2023-12-31T00:00:00.000Z"
}
}'
Field Type Description
filters_bool String Supported: AND, OR. Either one or all filters must be valid.
filters List of Filters (optional) See below
size Int Number of returned elements (0 to 1000)
offset Int Offset of returned elements (0 to 100.000). For higher offset, please use a different range window (see below).
range Range See below
Field Type Description
type String Supported: response
key String Filtered entity: respondent_id, respondent_aliases, respondent_segments, channel_id, raw, language, completion
operator String Comparison operator: eq, neq, in, not_in, not_null, null, contains, not_contains, before, after, lt, gt. Available operators may vary upon requested data
value Any Value to pass as an argument
values List of any Values to pass as an argument

Fetch by screeb id:

{ "type": "response", "key": "respondent_id", "operator": "eq", "value": "9565ac03-df6f-49b9-b4ff-9e20e8cb6bbf" }

Fetch by user alias:

{ "type": "response", "key": "respondent_aliases", "operator": "eq", "value": "support@screeb.app" }
{ "type": "response", "key": "respondent_aliases", "operator": "contains", "value": "@apple.com" }

Fetch responses created by users part of segment 79ef68c0-2022-4b15-b48b-e95ba4cacf80:

{ "type": "response", "key": "respondent_segments", "operator": "in", "values": ["79ef68c0-2022-4b15-b48b-e95ba4cacf80"] }

Fetch responses created on iOS (here channel_id is b4ece0cd-4e11-4a9d-a58d-c2519ee98605):

{ "type": "response", "key": "channel_id", "operator": "eq", "value": "b4ece0cd-4e11-4a9d-a58d-c2519ee98605" }

Fetch by keyword:

{ "type": "response", "key": "raw", "operator": "contains", "value": "problem" }

Fetch by language (exclude English):

{ "type": "response", "key": "language", "operator": "not_in", "values": ["en"] }

Fetch by completion:

{ "type": "response", "key": "completion", "operator": "eq", "value": "not_started" }
{ "type": "response", "key": "completion", "operator": "in", "values": ["partially_completed", "fully_completed"] }

Fetch by hidden field ltv greater than 100$:

{ "type": "response.hidden_field", "key": "ltv", "operator": "gt", "value": "100" }
Field Type Description
field String Supported: created_at
start String in ISO 8601 format Date of creation of the first response
end String in ISO 8601 format Date of creation of the last response

hits.total.value contains the number of responses matching the criteria.

hits.responses is a list of responses.

{
"took": 282,
"hits": {
"total": {
"value": 123456
},
"responses": [
{
"id": "735f7cea-c84a-4d98-8a7f-e807a8763fc0", // unique response id
"doc_type": "response",
"org_id": "6c1e7576-ef59-4673-a107-0fc64e9bf6f3",
"channel_id": "92486e31-7e9c-44b6-8af4-4643ef3ee4b6",
"respondent_id": "8a85c1f9-0b7a-46e0-b262-47ab45bf5f9b", // screeb user id
"respondent_aliases": [
"8a85c1f9-0b7a-46e0-b262-47ab45bf5f9b", // screeb user id
"support@screeb.app" // customer user id
],
"survey_id": "a8d3950a-88d4-4662-8099-0ddeb3de98b4",
"scenario_id": "cf320d79-f8c6-43b6-ba4a-9faa57682507",
"language": "fr",
"locale": "fr-fr",
"question_id_path": "0d6496d0",
"question_correlation_id_path": "84338f3a",
"action_id_path": "53e0da62",
"action_correlation_id_path": "03a9ef5d",
"group_ids": [
"a84a92f6-9389-49e2-a011-b1bfa7fa5227"
],
"hidden_fields": [
{
"t": 0,
"v_s": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.6 Safari/605.1.15",
"key": "user_agent"
},
{
"t": 0,
"v_s": "other",
"key": "os"
},
{
"t": 0,
"v_s": "tablet",
"key": "support"
},
{
"t": 0,
"v_s": "desktop",
"key": "platform"
},
{
"t": 2,
"v_d": -120,
"key": "timezone"
},
{
"t": 0,
"v_s": "fr-FR",
"key": "locale"
},
{
"t": 0,
"v_s": "fr",
"key": "country"
},
{
"t": 1,
"v_b": true,
"key": "logged_in"
},
{
"t": 0,
"v_s": "Home page",
"key": "page_title"
}
],
"emotions": {
"fear": null,
"sadness": null,
"anger": null,
"joy": null
},
"answers": [ // a list of answers identified by question_id
{
"t": 0,
"v_s": "This feature didn't work on my computer", // user answer in its own language
"cta_type": "input", // question type
"key": "84338f3a-aad4-44eb-9d49-f6a894343867",
"question_id": "0d6496d0-7f3c-4ef3-bd71-b37b5a81e6d1",
"question_correlation_id": "84338f3a-aad4-44eb-9d49-f6a894343867",
"action_id": "53e0da62-e621-4ca0-9647-209a3bd4dde3",
"action_correlation_id": "03a9ef5d-b33b-4ffa-994b-2ca8c5edc241",
"answer_id": "521b7556-eff1-4bb8-bcb1-3d2281d5dfb6",
"tags": null,
"lang": null,
"translations": [], // translation of user input (if feature is activated)
"time": "2023-09-11T07:37:56.000444Z"
}
],
"completion": "fully_completed", // "not_started" or "partially_completed" or "fully_completed"
"active": false,
"end_reason": "completed", // is empty when response is active
"ended_at": "2023-09-11T07:37:56.167436Z", // is empty when response is active
"created_at": "2023-09-11T07:37:49.406943Z",
"updated_at": "2023-09-11T07:37:56.256519Z",
"last_answer_at": "2023-09-11T07:37:56.000444Z"
}
]
}
}

The response summary API is accessible via the following endpoint: SEARCH - https://api.screeb.app/1.0/survey/:survey_ids/response/summary

Terminal window
curl -X SEARCH https://api.screeb.app/1.0/survey/*/response/summary \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <YOUR-API-KEY>" \
-d '{
"filters_bool": "AND",
"filters": [
{ "type": "response", "key": "completion", "operator": "eq", "value": "fully_completed" },
{ "type": "response", "key": "language", "operator": "in", "values": ["en", "fr"] }
],
"range": {
"field": "created_at",
"start": "2020-01-01T00:00:00.000Z",
"end": "2023-12-31T00:00:00.000Z"
}
}'

Output:

{
"ces_avg": 3,
"ces_details": {
"1": 79,
"2": 68,
"3": 71,
"4": 59,
"5": 62,
"6": 59,
"7": 67
},
"csat_avg": 3,
"csat_details": {
"1": 71,
"2": 75,
"3": 94,
"4": 83,
"5": 283
},
"nps_details": {
"1": 45,
"2": 50,
"3": 52,
"4": 59,
"5": 56,
"6": 50,
"7": 48,
"8": 65,
"9": 39,
"10": 46
},
"nps_groups": {
"detractor": 312,
"neutral": 113,
"promotor": 85,
"total": 510
},
"nps_score": 0,
"completion": {
"fully_completed": 1155,
"not_started": 1900,
"partially_completed": 972
},
"end_reasons": {
"closed": 2710,
"completed": 1155,
"expired": 157,
"interrupted": 4
},
"languages": {
"en": 4027
},
"supports": {
"desktop": 1714,
"mobile": 2313
}
}

The response aggregation API is accessible via the following endpoint: SEARCH - https://api.screeb.app/1.0/survey/:survey_ids/response/aggregation

The hits.total.value field described above might not be sufficient for grouping data per completion status, user platform…

A group_by argument can be added to the request. Eg:

{
"filters_bool": "AND",
"filters": [
// any filters described previously
{ "type": "response", "key": "channel_id", "operator": "eq", "value": "b4ece0cd-4e11-4a9d-a58d-c2519ee98605" }
],
"range": {
"field": "created_at",
"start": "2020-01-01T00:00:00.000Z",
"end": "2023-12-31T00:00:00.000Z"
},
"group_by": [
{ "field": "completion" } // <- count responses by completion status
]
}

The group_by argument supports multiple rules. The order matters. Eg:

{
"filters_bool": "AND",
"filters": [
// any filters described previously
{ "type": "response", "key": "channel_id", "operator": "eq", "value": "b4ece0cd-4e11-4a9d-a58d-c2519ee98605" }
],
"range": {
"field": "created_at",
"start": "2020-01-01T00:00:00.000Z",
"end": "2023-12-31T00:00:00.000Z"
},
"group_by": [
// count responses by completion status and per month
{ "field": "completion" },
{
"field": "created_at",
"date_histogram_min_interval": "month",
"date_histogram_buckets": 20
}
]
}

Here is the full list of aggregation:

Group by date:

{
"field": "created_at", // either created_at, ended_at or last_activity_at
"date_histogram_min_interval": "day", // month, day or hour
"date_histogram_buckets": 10 // number points in the timeseries (1 to 100) - eg: 10 points in a 1 month interval will group per 3 days
}

Group by completion status:

{
"field": "completion"
}

Group by survey_id:

(should be used with a wildcard request: https://api.screeb.app/1.0/survey/*/response)

{
"field": "survey_id"
}

Group by response end reason:

{
"field": "end_reason"
}

Group by hidden field:

{
"field": "hidden_field",
"hidden_field_key": "country"
}

Group by answer:

{
"field": "answer",
"question_id": "23c4d464-699b-4fc6-851b-c3e7da6af853" // <- the correlation id of the question
}

If you have any questions or additional requirements, feel free to open an issue or contact support@screeb.app.