Genialcloud Sales Signal

Survey Signal Developer Guide

Integrate Survey Signal delivery into external systems using the dedicated bearer-token API for single-recipient and bulk survey sending.

Overview

Survey Signal exposes a dedicated external delivery API so another system can trigger survey email sends without entering the Survey Signal UI. The calling system provides the target survey ID plus recipient data, and Survey Signal creates the unique recipient link and sends the email immediately.

Security model

The external Survey Signal API uses an admin-generated bearer token. The token is managed in Survey Signal App Control and should be shared only with approved developers or systems.

Default behavior

The API sends the survey immediately. No manual step inside Survey Signal is required after the API request succeeds.

Authentication

All external Survey Signal API requests must include the admin-generated bearer token.

Authorization: Bearer <survey_signal_api_key>

Single Send Endpoint

POST /api/external/survey-signal/send
Content-Type: application/json
Authorization: Bearer <survey_signal_api_key>

{
  "survey_id": 123,
  "name": "Mario Rossi",
  "email": "mario.rossi@example.com",
  "internal_reference": "TCK-2026-00451",
  "theme_key": "corporate"
}

Use internal_reference when the calling system needs to keep an internal ticket, case, or CRM reference linked to that specific send. Use theme_key only when a caller needs to override the survey default for that one send. When omitted, Survey Signal uses the theme configured on the survey itself.

Bulk Send Endpoint

POST /api/external/survey-signal/send/bulk
Content-Type: application/json
Authorization: Bearer <survey_signal_api_key>

{
  "survey_id": 123,
  "theme_key": "dark",
  "skip_existing": true,
  "recipients": [
    {
      "name": "Mario Rossi",
      "email": "mario.rossi@example.com",
      "internal_reference": "TCK-2026-00451"
    },
    {
      "name": "Anna Bianchi",
      "email": "anna.bianchi@example.com",
      "internal_reference": "CASE-1182"
    }
  ]
}

Bulk send creates one unique Survey Signal send per valid recipient. Existing recipients can be skipped automatically when skip_existing is set to true.

Response Behavior

If the survey exists and is sendable, Survey Signal sends the email immediately.
If the survey is still draft, the first API send promotes it automatically to published.
If the survey is closed, the API rejects the request.
Survey language, sender email, intro copy, and thank-you copy are taken from the survey configuration.
Each recipient receives a unique tokenized survey link and is tracked independently in Survey Signal analytics.

Expected Success Payloads

{
  "ok": true,
  "survey_id": 123,
  "send_id": 456,
  "delivery_status": "sent",
  "public_url": "https://survey.example.com/survey/public/...",
  "internal_reference": "TCK-2026-00451",
  "theme_key": "corporate"
}

{
  "ok": true,
  "survey_id": 123,
  "total_rows": 2,
  "sent_rows": 2,
  "failed_rows": 0,
  "invalid_rows": 0,
  "duplicate_rows": 0,
  "skipped_existing_rows": 0,
  "results": [
    {
      "name": "Mario Rossi",
      "email": "mario.rossi@example.com",
      "internal_reference": "TCK-2026-00451",
      "status": "sent",
      "send_id": 456,
      "public_url": "https://survey.example.com/survey/public/..."
    }
  ]
}

Integration Notes

The integration should store the Survey ID from the Survey Signal builder.
Use internal_reference for ticket numbers, case IDs, order references, or CRM references that must stay linked to the specific survey send internally.
The API key should be treated like any other production secret and never exposed in frontend code.
When a survey theme override is not needed, omit theme_key and let Survey Signal use the survey default.
Bulk integrations should inspect the returned per-recipient results to capture invalid, duplicate, skipped, or failed recipients.