REST API

Base URL

https://app.surveytale.com/api/v1

Authentication

All Management API endpoints require an API key.

Include it in the request header:

x-api-key: YOUR_API_KEY

Test Example

curl -X GET "https://app.surveytale.com/api/v1/management/me" \
  -H "x-api-key: YOUR_API_KEY"

Returns authenticated user or environment info.

Health Check

GET /health
Confirms service availability. Returns 200 OK If operational.

Endpoints Overview

1. Account

GET /management/me
Returns the environment details linked to your API key.

2. Surveys

List Surveys

GET /management/surveys
Fetch all surveys in the connected environment.

Create Survey

POST /management/surveys
Create a new survey.

Example

curl -X POST "https://app.surveytale.com/api/v1/management/surveys" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Feedback Survey",
    "type": "link",
    "questions": [
      {
        "type": "openText",
        "headline": { "default": "How was your experience?" },
        "required": true
      }
    ]
  }'

Get a Single Survey

GET /management/surveys/{surveyId}

Update a Survey

PUT /management/surveys/{surveyId}

Delete a Survey

DELETE /management/surveys/{surveyId}

Generate Single-Use Links

GET /management/surveys/{surveyId}/singleUse

3. Responses

List Responses

GET /management/responses?surveyId={surveyId}

Create Response

POST /management/responses
Submit a new response programmatically.

Get a Single Response

GET /management/responses/{responseId}

Update Response

PUT /management/responses/{responseId}

Delete Response

DELETE /management/responses/{responseId}

Example

curl -X POST "https://app.surveytale.com/api/v1/management/responses" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "surveyId": "abc123",
    "data": {
      "q1": "Yes",
      "q2": "It was excellent"
    }
  }'

4. Webhooks

List Webhooks

GET /webhooks

Create Webhook

POST /webhooks
Register a webhook to receive live events.

Body Example

{
  "url": "https://hooks.zapier.com/hooks/standard/123/xyz",
  "name": "Zapier Integration",
  "surveyIds": [],
  "triggers": ["responseCreated", "responseUpdated", "responseFinished"]
}

Example cURL

curl -X POST "https://app.surveytale.com/api/v1/webhooks" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url":"https://hooks.zapier.com/hooks/standard/123/xyz",
    "triggers":["responseCreated","responseUpdated","responseFinished"]
  }'

Get a Webhook

GET /webhooks/{webhookId}

Delete a Webhook

DELETE /webhooks/{webhookId}

Webhook Payload Format

Webhook events deliver arrays of objects:

[
  {
    "event": "responseCreated",
    "webhookId": "wh_123",
    "data": {
      "id": "resp_001",
      "surveyId": "abc123",
      "finished": true,
      "data": { "q1": "Yes" },
      "meta": { "url": "https://app.surveytale.com/s/abc123" },
      "createdAt": "2025-10-21T18:00:00Z",
      "updatedAt": "2025-10-21T18:05:00Z"
    }
  }
]

Available triggers:

• responseCreated

• responseUpdated

• responseFinished

5. Public Client API

These endpoints are for front-end interactions and do not require an API key.

Create Display

POST /client/{environmentId}/displays

Update Display

PUT /client/{environmentId}/displays/{displayId}

Create Response

POST /client/{environmentId}/responses

Example

curl -X POST "https://app.surveytale.com/api/v1/client/env_123/responses" \
  -H "Content-Type: application/json" \
  -d '{
    "surveyId": "abc123",
    "data": { "q1": "Very satisfied" }
  }'

Update Response

PUT /client/{environmentId}/responses/{responseId}

Get Environment State

GET /client/{environmentId}/environments/state

Headers

• x-api-key: required for management endpoints

• Content-Type: application/json for POST/PUT requests

Status Codes