List responses of one widget
const url = 'https://api.getsitecontrol.com/v1/sites/1/widgets/1/responses?limit=50&order=oldest';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://api.getsitecontrol.com/v1/sites/1/widgets/1/responses?limit=50&order=oldest' \ --header 'Authorization: Bearer <token>'Form responses of one widget, oldest first (ascending id); order=newest
gives the latest first (descending id). Each holds the field values a
visitor sent, the contact (contact_id), the page, visitor parameters, geo,
UTM tags and device. Call it to read what visitors sent through a widget; one
response by id is get_response. For the latest responses across all the
site’s widgets in one call, use list_responses.
Responses of a deleted widget of the site are still returned by its id,
although the widget itself is no longer listed by list_widgets or found by
get_widget.
A page holds up to limit responses; while next_cursor is set, pass it as
cursor for the next page with the same order; with order=newest, also
with the same created_since and created_before. Both filter by the time a
response was sent. To keep a copy in sync, follow next_cursor instead.
Neither the cursor nor created_since guarantees completeness. The send time is set
when a response is received and the id when it is stored, so the two orders
agree only approximately. A response awaiting double opt-in or an e-mail
check appears later with its original id and send time. A deleted response
disappears without a trace. When completeness matters, re-read a window with
a margin of time and merge by id.
While a response is being completed it may briefly drop out of the list and
return 404 from get_response; retry the request.
contact_id is set asynchronously and may be null on a fresh response.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Widget id from list_widgets
Widget id from list_widgets
Query Parameters
Section titled “Query Parameters”Sent at or after this moment; without an offset, taken as UTC; a plain date means its start
Sent at or after this moment; without an offset, taken as UTC; a plain date means its start
Sent before this moment; without an offset, taken as UTC; a plain date means its start. A moment later than now is accepted and covers every response sent so far
Sent before this moment; without an offset, taken as UTC; a plain date means its start. A moment later than now is accepted and covers every response sent so far
next_cursor of the previous page, sent with the same order; omit for the first
next_cursor of the previous page, sent with the same order; omit for the first
Items per page
Items per page
Comma-separated fields to keep in each item, for example id,name; each item then carries only those fields and id. Omit for every field
Comma-separated fields to keep in each item, for example id,name; each item then carries only those fields and id. Omit for every field
Order of the items: oldest first (default) or newest first; asc and desc mean the same
Order of the items: oldest first (default) or newest first; asc and desc mean the same
Responses
Section titled “Responses”One page of a list; next_cursor is null on the last page.
object
object
Response number, when the widget numbers its responses
When the response was sent
Set asynchronously; may be null on a fresh response
Answers by field name, in the order of the widget’s current form. Options removed from the form since the response are left out.
object
object
Type of a form field, as the editor offers it (email, text, textarea,
hidden, select, radio, rating, nps and the ones below). tel: a plain phone
input; phone: one with a country selector; flag: a single checkbox;
checkbox: a group of checkboxes; reveal, scratch, wheel: games; the
answer is the drawn prize, its name is the prize code; other: any other
field, or one the widget’s current form no longer describes.
Visitor parameters as set on the site: arbitrary JSON that may hold personal data
Page the response was sent from, with its query string, which may hold e-mails or tokens
Query parameters of page_url, the last value of a repeated key; may hold e-mails or tokens
object
Previous page of the visit on the site, not the external source; with its query string
Page the visit came from, as the browser reported it on the visit’s first page: usually another site, with its query string; null for a direct visit
object
object
object
Fields are null when the site is not on a known platform
object
The site’s e-commerce platform, e.g. shopify; null elsewhere
The platform’s id of a signed-in customer
The platform’s order id, on an order status page
Empty unless the response could not be read; wording is not stable, do not parse
{ "items": [ { "fields": { "additionalProperty": { "type": "email" } } } ]}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
Authentication scheme: Bearer
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
widget_not_found: the site has no widget with this id, deleted or not
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
validation_failed: a malformed parameter, or created_since after created_before. invalid_cursor: the cursor is damaged or was issued for another order, or with order=newest for another widget, created_since or created_before
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
rate_limited: the key, account or heavy bucket is spent; this operation spends the heavy bucket shared with statistics and other heavy calls
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
Seconds until the bucket refills
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds