This page describes the API that BlockSurvey's automation integrations (Zapier, Make and n8n) use to sign in, list your data, receive new survey responses and add contacts. You don't need to call it yourself: the integrations handle it for you. It is documented here for platform reviewers and developers.

Base URL

Each platform has its own base path. Replace {platform} with zapier, make or n8n.

https://webservice.blocksurvey.io/{platform}

All requests and responses use JSON, except the token endpoint, which also accepts form-encoded bodies.

Authentication (OAuth 2.0)

Integrations use the OAuth 2.0 authorization code grant. n8n uses PKCE (S256) as a public client with no client secret.

Authorization URL: https://blocksurvey.io/{platform}/authorize. The user signs in to BlockSurvey and clicks Allow. BlockSurvey then redirects to the platform's registered redirect URI with a code (valid for 5 minutes) and the original state.
Token URL: POST https://webservice.blocksurvey.io/{platform}/oauth/token

Exchange a code:

grant_type=authorization_code
code=...
redirect_uri=...
client_id=...
client_secret=...      (Zapier, Make)
code_verifier=...      (n8n, PKCE)

Refresh:

grant_type=refresh_token
refresh_token=...
client_id=...
client_secret=...      (Zapier, Make)

Response:

{
  "access_token": "...",
  "refresh_token": "...",
  "token_type": "Bearer",
  "expires_in": 7200
}

Access tokens last 2 hours. Send them on every API call:

Authorization: Bearer <access_token>

Users can disconnect an integration at any time in BlockSurvey under Settings → Integrations, which revokes its tokens.

Account

GET /me: the connected user. Used as the connection test and label.

{ "id": "...", "email": "[email protected]", "name": "Jane" }

Workspaces and surveys

GET /workspaces: workspaces the user belongs to.

[ { "id": "<workspaceId>", "name": "Acme / Marketing" } ]

GET /surveys?teamId=<workspaceId>: live surveys in a workspace.

[ { "id": "<surveyId>", "name": "Customer Feedback", "status": "live" } ]

Trigger: New Survey Response (REST hooks)

POST /hooks/responses: subscribe. BlockSurvey sends every new response of the survey to hookUrl.

{
  "teamId": "<workspaceId>",
  "surveyId": "<surveyId>",
  "hookUrl": "https://hooks.zapier.com/...",
  "zapName": "Optional automation name"
}

Response 201:

{ "id": "<hookId>", "teamId": "<workspaceId>", "surveyId": "<surveyId>" }

DELETE /hooks/responses/{hookId}?teamId=&surveyId=: unsubscribe. Idempotent: returns 200 even if the hook is already gone.

GET /hooks/responses/{hookId}?teamId=&surveyId=: check that a hook still exists. Returns { "id", "url", "active" }, or 404.

GET /responses/sample?teamId=&surveyId=: one sample item with the survey's real question titles, for building the automation.

A hook URL must belong to the platform that created it (for example hooks.zapier.com or hook.*.make.com; any HTTPS URL for self-hosted n8n). If the hook URL answers 410 Gone, BlockSurvey deletes the hook and stops sending.

Delivered payload

For each new response BlockSurvey sends a POST with a JSON body:

{
  "event_id": "<unique event id>",
  "event_type": "survey_response",
  "survey_response": {
    "response_id": "<responseId>",
    "answers": { "<questionId>": "answer", "submitted_at": "2026-10-01T11:00:00Z" },
    "definition": {
      "id": "<surveyId>",
      "title": "Customer Feedback",
      "fields": [ { "id": "<questionId>", "type": "radio", "title": "Which email provider do you use?" } ]
    }
  }
}

event_id is unique per delivery event; use survey_response.response_id to identify the response. The integrations turn this into one item keyed by question title, for example "Which email provider do you use?": "Gmail".

Action: Add or Update a Contact

GET /lists?teamId=<workspaceId>: contact lists in a workspace.

[ { "id": "<listId>", "name": "Newsletter", "total_records": 120 } ]

GET /lists/fields?teamId=&listId=: the list's fields. Email is always first and required.

[
  { "key": "email", "label": "Email", "required": true },
  { "key": "<columnId>", "label": "First Name", "required": false }
]

POST /contacts: add a contact, or update it if the email is already in the list.

{
  "teamId": "<workspaceId>",
  "listId": "<listId>",
  "email": "[email protected]",
  "fields": { "<columnId>": "Jane" }
}

Response 200:

{ "id": "<contactId>", "status": "created", "email": "[email protected]", "list_id": "<listId>" }

status is created, updated, or exists (already in the list, nothing to change).

Errors

400: missing or invalid parameters. OAuth errors use the standard { "error", "error_description" } format (for example invalid_grant).
401: missing, expired or revoked token (invalid_token), or wrong client credentials (invalid_client). Refresh the token or reconnect.
403: the user has no access to that workspace, or the hook belongs to another user or app.
404: workspace, survey, list or hook not found.
429: too many token requests; retry later.

Other errors return { "status": "error", "message": "..." }.

Support

Questions about the integrations: contact us through the chat on blocksurvey.io.

BlockSurvey Integrations API (Zapier, Make, n8n)