surveys

POST `/v1/surveys/{survey_id}/responses`

Record one person's answers to one survey.

Authentication

Send an API key as a bearer token. The key must carry the org.read permission; a key without it is refused with 403, not 404.

Where your organisation id goes

This endpoint takes org_id as a field in the JSON body.

Your organisation id is on the API keys screen in your dashboard, beside the key itself. It is the same id in every call you make.

Try it

Replace anything in angle brackets with your own values, and the key placeholder with a key from your dashboard.

curl -X POST https://api.zinndigital.com/v1/surveys/{survey_id}/responses \
  -H "Authorization: Bearer zdk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "answers": <SurveyAnswer[]> }'

Signed in? The API console in your dashboard fills in your real organisation id and your own key, and runs the request against the live API so you can see the actual response. Open this endpoint in the API console

Details

Stored in our own organisation-scoped table FIRST and unconditionally, then mirrored to the behavioural backend so the analytics join resolves. The two copies have opposite error policies deliberately: losing the customer's answer is unacceptable, losing the vendor's copy of an answer we already hold costs a join. ⛔ The survey is re-fetched and re-checked against the store — a client sends an id, and a client is a thing a person can edit. Answering an archived or stopped survey is refused. A SECOND answer from the same person returns `200` with `duplicate: true` rather than a conflict: the unique constraint exists to stop a doubled count, and the commonest way it fires is a retry after a dropped connection. Requires `org.read`.

Parameters

Name	Type	Required	What it is
`survey_id (path)`	`string`	Yes	—

Request body

Name	Type	Required	What it is
`org_id`	`string`	No	—
`distinct_id`	`string`	No	The browser's analytics distinct id. ⛔ Without it the mirrored event attaches to a person who does not exist, and the join looks healthy and is empty.
`path`	`string`	No	—
`answers`	`SurveyAnswer[]`	Yes	—

Response

Name	Type	Required	What it is
`recorded`	`boolean`	Yes	—
`duplicate`	`boolean`	Yes	True when this person had already answered. ⛔ Reported as a success, not a conflict — the commonest cause is a retry after a dropped connection, and telling the customer it fail…
`id`	`string`	No	—

Errors this endpoint can return

401 · 403 · 404 · 422