Trigger tracked survey invitations from another system.

Overview

API triggers create queued invitation batches for a specific survey. Each invited recipient receives a tracked survey link, and responses submitted through that link are attributed to the invitation. Optional metadata is stored as hidden response data and appears in authenticated Results tables.

API triggers are plan-gated. Workspace owners, admins, and editors manage them from a survey's Invitations page under the API trigger tab.

For a task-oriented walkthrough with backend language examples, read the API trigger guide. If you are setting this up inside Survey.is, the survey Invitations page includes the token controls and the exact endpoint for that survey.

Trigger Tokens

1. Open a survey in Survey.is.
2. Open Invitations, then the API trigger tab.
3. Create a trigger token and copy the secret immediately. Survey.is stores only a SHA-256 hash and will not show the raw secret again.
4. Set a token name, cooldown seconds, default subject, default message, and default reminder days.

Use a separate token for each external workflow when you need different defaults, cooldowns, or rotation behavior.

Request

POST https://survey.is/api/invitation-trigger

Authentication

Send the trigger secret as a bearer token:

Authorization: Bearer sit_...

The endpoint also accepts token or secret in the query string or request body for integrations that cannot set headers, but the Authorization header is preferred.

JSON Fields

• email: single recipient email address. Required unless emails is sent.
• emails: array of recipient email addresses or recipient objects.
• name: optional recipient name for a single-recipient request.
• metadata: optional object stored with invitation attribution and later shown as hidden metadata in Results after a response is submitted.
• subject and message: optional email content. If omitted, Survey.is uses the defaults saved on the trigger token.
• reminder_days: optional reminder timing. Omit it to use the token default, or send 0 to disable reminders for that request.
• send_in_seconds: optional relative delay before the invitation becomes due.
• send_at: optional exact send time. Use now or a UTC date/time string.

Use only one timing field per request: either send_in_seconds or send_at. Omit both to queue immediately.

Examples

Single Recipient

curl -X POST 'https://survey.is/api/invitation-trigger' \
  -H 'Authorization: Bearer sit_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "person@example.com",
    "name": "Pat",
    "reminder_days": 3,
    "metadata": {
      "source_id": "evt_12345",
      "customer_tier": "starter"
    }
  }'

Multiple Recipients

curl -X POST 'https://survey.is/api/invitation-trigger' \
  -H 'Authorization: Bearer sit_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "emails": [
      { "email": "alex@example.com", "name": "Alex" },
      { "email": "sam@example.com", "name": "Sam" }
    ],
    "send_at": "2026-05-18 14:00:00 UTC",
    "metadata": {
      "campaign": "post-demo"
    }
  }'

Responses

Successful requests return HTTP 200 with the queued batch summary:

{
  "ok": true,
  "message": "Invitation queued.",
  "batch": {
    "uuid": "batch-uuid",
    "scheduled_at": "2026-05-18 14:00:00",
    "status": "queued"
  }
}

Common error responses include:

• 400: invalid request, missing token, invalid recipient, unsupported timing, or disabled survey/workspace state.
• 405: method other than POST.
• 429: token cooldown or flood protection blocked the request.
• 503: invitation tables or dependencies are not ready.

Operational Notes

• Queued emails are sent by the Survey.is invitation worker. Due invitations wait while a survey is draft or closed and become eligible after the survey is active.
• Invitation links append an invitation token to the public survey URL. Do not log or expose those URLs more broadly than necessary.
• Trigger secrets are shown once. Rotate by deleting the old token and creating a new one.
• Message templates support {{recipient_name}}, {{workspace_name}}, {{survey_title}}, and {{survey_link}}.
• Use metadata for stable identifiers from the triggering system, not for secrets, passwords, payment card data, or sensitive regulated data.