REST API

When you need to show responses on your own website or pull them into your system on a schedule, you use the REST API. It returns JSON, authenticates with an API key, and supports the same filters you know from the results table.

Get started free →Pricing

What the API can do

  • List the forms in a workspace and fetch a single form including its structure.
  • List submissions with filters: by form, status, date range, full text, plus sorting.
  • Fetch a single submission.
  • Update a submission status.
  • Submit a form programmatically — useful for migrations or a custom front end.

Fetching submissions

Authenticated with the Authorization header (an x-api-key header also works):

curl "https://gatherino.com/api/v1/submissions?formId=FORM_ID&limit=50" \
  -H "Authorization: Bearer gk_your_key"

# response
{ "items": [ { "id": "…", "status": "NEW", "createdAt": "…",
               "data": { "field_1778…": "Jan Vondráček" } } ],
  "total": 672, "page": 1, "limit": 50, "totalPages": 14 }

Getting started

  1. 1

    Create an API key

    In Settings → API keys. The key is shown only once, so store it immediately.

  2. 2

    Make your first call

    Try listing forms to confirm the key works and to grab the form ID.

  3. 3

    Map field IDs to labels

    The form detail returns each field’s ID and label — build a lookup from that. Field IDs are stable, so fetching once is enough.

  4. 4

    Handle pagination

    The maximum is 100 submissions per request. For more data, walk the pages until you reach the last one.

The API key belongs on your server, never in browser JavaScript — anyone could read it there and download all your responses. If you publish responses, only expose fields meant for publication, never personal data.

FAQ

How does the API authenticate?

With an API key: either an Authorization: Bearer <key> header or an x-api-key header. An invalid key returns 401.

How many submissions per request?

Up to 100. The response includes total and totalPages so you can walk through further pages.

Why are the data keys like field_1778…?

Those are the form’s field IDs. Fetch their labels from the form detail and keep the mapping on your side.

Does the API handle diacritics?

Yes, everything is UTF-8, so Czech and other languages work without issues.

Related

API documentationWebhooksResponse management

Try Gatherino for free

Free plan: 3 forms and 100 responses a month. No credit card, EU-hosted data.

Get started free →