API Documentatie

Quick start

1. API-sleutel aanmaken — Ga in Feedback Analytics naar je workspace → Instellingen → sectie "API-sleutels" en klik op "Nieuwe sleutel". Bewaar de sleutel (begint met fa_); hij wordt maar één keer getoond.
2. Workspace- en tabel-ID vinden — Open je datatable in de app. In de adresbalk zie je: /…/datatable/[table_id]/table. Het eerste deel van het pad is je workspace-link; de workspace_id is de interne ID (zie hieronder).
3. Eerste request — Stuur een GET met header X-API-Key: fa_... naar https://feedback-analytics.com/api/v1/workspaces/WORKSPACE_ID/tables om je tabellen op te halen. Gebruik de id uit de response als table_id voor de andere endpoints.

Voor Postman of Insomnia: importeer de OpenAPI-specificatie (JSON). Gebruik in Postman/Insomnia de optie "Import" → "Link" en plak: /api/v1/openapi (met hetzelfde domein als deze pagina, bijv. https://feedback-analytics.com/api/v1/openapi).

Responses (formulierantwoorden)

Haal formulierresponses op: lijst met paginering, filter en sort, of één response op ID. Elke response bevat antwoorden, score, koppeling aan formulier en datatable (row_id). Wanneer iemand het formulier via een e-maillink heeft ingevuld, krijg je respondent_email (het e-mailadres van de respondent) en email_id. Met include_table_data=true krijg je de datatable-rij zoals die was op het moment van invullen. Ideaal voor rapportages, CRM-sync of eigen dashboards.

Lijst responses

Voor vertaalde formulieren met reporting_label per antwoord: /api/v2/workspaces/{workspace_id}/responses

Eén response ophalen

Optionele queryparams: include_table_data=true, include_actionlist_data=true. Response komt in data (geen paginering).

Queryparameters

• page, limit — Paginering (standaard 1, 50; max limit 1000).
• sort — Bijv. createdAt:desc of score:asc.
• filter — Filter op velden (form_id, score, etc.), zelfde syntax als bij datatables.
• start_date, end_date — Datumbereik (ISO 8601) op aanmaakdatum.
• form_id — Alleen responses van dit formulier.
• include_table_data=true — Voegt table_data toe (datatable-rij op moment van invullen).
• include_actionlist_data=true — Voegt actionlist_data toe (getriggerde actielijsten).

Response-schema (per response)

{
  "id": "response-id",
  "score": 42,
  "version": 1,
  "createdAt": "2025-01-15T10:30:00.000Z",
  "form": { "id": "...", "name": "Enquête naam" },
  "answers": [
    { "id": "q1", "title": "Vraag 1", "type": "single_choice", "value": { "id": "...", "value": "Optie A" } }
  ],
  "email_id": "..." | null,
  "respondent_email": "respondent@voorbeeld.nl" | null,
  "row_id": "..." | null,
  "table_data": { "row_id": "...", "email": "...", "_captured_at": "..." } | undefined,
  "actionlist_data": [{ "actionlist_id": "...", "triggered_score": 3, "triggers": [...] }] | undefined
}

respondent_email — E-mailadres van de respondent (ontvanger van de formulierlink). Alleen aanwezig als de response via een e-maillink is gestart. Handig om invullers te koppelen aan je CRM of datatable.

De lijst staat in data; meta (total, page, limit, filtered_total) en links (self, next, prev) voor paginering.

Voorbeelden

Lijst (met respondent- en tabeldata):

curl -H "X-API-Key: fa_xxx" \
  "https://feedback-analytics.com/api/v1/workspaces/WORKSPACE_ID/responses?page=1&limit=20&form_id=FORM_ID&include_table_data=true&sort=createdAt:desc"

Eén response op ID:

curl -H "X-API-Key: fa_xxx" \
  "https://feedback-analytics.com/api/v1/workspaces/WORKSPACE_ID/responses/RESPONSE_ID?include_table_data=true"

E-mail events (historie)

Haal de historie van e-mail-events op: verzendingen, opens, clicks, bounces, etc. gekoppeld aan email_id, row_id, form_id en flow_id. Handig voor rapportages of sync met je CRM.

Endpoint

Queryparameters

• page, limit — Paginering (standaard 1, 50; max limit 1000).
• sort — Bijv. createdAt:desc.
• filter — Filter op velden (zelfde syntax als bij responses/datatables).
• start_date, end_date — Datumbereik (ISO 8601).
• type — Eventtype (bijv. open, click, bounce).
• email_id — Alleen events voor deze e-mail.
• recipient — Filter op ontvanger.

Response-schema (per event)

{
  "id": "event-id",
  "email_id": "email-id",
  "email": "ontvanger@voorbeeld.nl",
  "row_id": "datatable-entry-id of leeg",
  "form_id": "form-id of leeg",
  "flow_id": "flow-id of leeg",
  "event_type": "open | click | bounce | ...",
  "createdAt": "2025-01-15T10:30:00.000Z"
}

De lijst staat in data; meta en links voor paginering.

Voorbeeld

curl -H "X-API-Key: fa_xxx" \
  "https://feedback-analytics.com/api/v1/workspaces/WORKSPACE_ID/emails/events?page=1&limit=20&sort=createdAt:desc"

Authenticatie

Stuur bij elk request de header X-API-Key met je API-sleutel. Sleutels beginnen met fa_. Je API-sleutel heeft toegang tot één of meerdere workspaces; je mag alleen resources van die workspaces opvragen.

Maak een API-sleutel aan in Workspace instellingen → API-sleutels (na inloggen). Bewaar je sleutel veilig en deel deze nooit in frontend-code of publieke repos.

Overzicht endpoints

Responses, datatabellen en (waar van toepassing) e-mail events. Alle endpoints vereisen de header X-API-Key.

Datatabellen

Beheer rijen in je datatabellen: lijst tabellen, velden ophalen, rijen lezen met filter en sort, één rij of meerdere rijen toevoegen/bijwerken (upsert op data.id), of verwijderen.

Queryparameters (GET-rijen)

Bij GET .../tables/{table_id} (rijen ophalen) kun je de volgende queryparameters gebruiken.

• page, limit — Paginering (standaard page=1, limit=50, max limit=1000).
• filter — Filter op velden, bijv. email=test@example.com of row_id=abc123. Meerdere filters met komma. Ondersteunde operatoren: =, !=, ~ (bevat), in (bijv. status=[active,pending]).
• sort — Sortering, bijv. createdAt:desc of email:asc. Meerdere met komma.
• start_date, end_date — Datumbereik (ISO 8601) op createdAt.
• include_metadata=true — Voegt created_at en updated_at toe aan elke rij.

Voorbeelden (datatables)

curl -X POST "https://feedback-analytics.com/api/v1/workspaces/WORKSPACE_ID/tables/TABLE_ID/entries" \
  -H "X-API-Key: fa_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "id": "klant-001",
      "email": "jan@voorbeeld.nl",
      "naam": "Jan Jansen"
    }
  }'

curl -H "X-API-Key: fa_xxx" \
  "https://feedback-analytics.com/api/v1/workspaces/WORKSPACE_ID/tables/TABLE_ID/entries?page=1&limit=20&filter=email~@voorbeeld.nl"

curl -X PATCH "https://feedback-analytics.com/api/v1/workspaces/WORKSPACE_ID/tables/TABLE_ID/entries/ROW_ID" \
  -H "X-API-Key: fa_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "naam": "Jan de Vries" } }'

curl -X DELETE "https://feedback-analytics.com/api/v1/workspaces/WORKSPACE_ID/tables/TABLE_ID/entries/ROW_ID" \
  -H "X-API-Key: fa_xxx"

Foutcodes

Bij een fout retourneert de API JSON met error, message en optioneel details.

• 401 Unauthorized — Ontbrekende of ongeldige API-key.
• 403 Forbidden — Geen toegang tot deze workspace.
• 404 Not Found — Workspace, tabel, rij of response niet gevonden.
• 400 Bad Request — Ongeldige body of query (bijv. ontbrekende data of data.id).
• 429 Too Many Requests — Rate limit overschreden (headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset).