API documentation

How it works

1. Your system already knows the customer (phone or email) after a visit, order, or appointment.
2. Your server (never a public browser bundle) sends POST /api/v1/trigger-voice with API credentials stored as environment variables.
3. SurvX creates a short-lived feedback URL. Send now, or pass delayMinutes / scheduledAt so SMS/email goes later. One credit is deducted only after delivery succeeds.
4. The customer opens the link and records voice. Results appear in the SurvX dashboard under Voices.

Prerequisites

• An active API key for the same branch you send in business_unit — generate it in the dashboard under Integration → API Keys.
• Available invite credits for that channel (SMS or email) on the branch.
• SMS: an active DLT Feedback template selected in Business settings. DLT variable slots are ~30 characters; SurvX keeps the feedback URL short (no www).
• Email: no DLT template. A valid email is enough (demo: customer@example.com).

Authentication

Send both headers on every request. The key is bound to one business unit; the body must use that same unit.

Endpoint

Production base URL: https://api.survx.co

Request body

JSON object. Fields are validated before any message is sent.

msg_template values

• basic — voice note, star rating, written comment, photo/video.
• t1 — hold-to-record voice plus a single overall rating.
• t2 — custom question groups configured for the branch.

Code samples

Replace YOUR_API_KEY, YOUR_API_SECRET, ABC12, and the sample mobile/email with values from your dashboard and your customer. Placeholders never send a real invite (401).

curl -sS -X POST "https://api.survx.co/api/v1/trigger-voice" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -d '{"channel":"sms","mobile":"9000012345","msg_template":"basic","business_unit":"ABC12"}'

Email channel

Use channel: "email" and email instead of mobile.

{
  "channel": "email",
  "email": "customer@example.com",
  "msg_template": "basic",
  "business_unit": "ABC12"
}

Delay and schedule

Same as dashboard Outreach → When to send. Call the API from your server when the visit ends; SurvX waits, then sends SMS/email. Credits and daily limits apply at send time. The feedback URL stays inactive until then. If many invites are due at once, SurvX sends them at the branch pace and retries for up to 24 hours.

• delayMinutes — wait this many minutes (dashboard presets: 5, 15, 30, 60, 120, 360, 1440).
• scheduledAt — ISO UTC clock time, must be in the future, max 30 days. If both are sent, scheduledAt wins.
• Success is still HTTP 201 with scheduled: true and deliveredVia: null.

curl -sS -X POST "https://api.survx.co/api/v1/trigger-voice" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -d '{"channel":"sms","mobile":"9000012345","msg_template":"basic","business_unit":"ABC12","delayMinutes":30}'

curl -sS -X POST "https://api.survx.co/api/v1/trigger-voice" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -d '{"channel":"email","email":"customer@example.com","msg_template":"basic","business_unit":"ABC12","scheduledAt":"2026-09-12T18:30:00.000Z"}'

Success — 201 Created

Immediate send: HTTP 201 and deliveredVia is sms or email. Delayed/scheduled send: also 201, with scheduled: true, scheduledAt, and deliveredVia: null until the worker sends the message (checks every 15 seconds).

{
  "ok": true,
  "scheduled": false,
  "business_unit": "ABC12",
  "channel": "sms",
  "msg_template": "basic",
  "feedbackUrl": "https://survx.co/?V=XXXXX",
  "broadcastId": "0000000000000000001",
  "linkId": "0000000000000000002",
  "expiresAt": "2026-08-30T12:00:00.000Z",
  "deliveredVia": "sms"
}

{
  "ok": true,
  "scheduled": true,
  "scheduledAt": "2026-09-10T18:30:00.000Z",
  "business_unit": "ABC12",
  "channel": "sms",
  "msg_template": "basic",
  "feedbackUrl": "https://survx.co/?V=XXXXX",
  "broadcastId": "0000000000000000001",
  "linkId": "0000000000000000002",
  "expiresAt": "2026-09-17T18:30:00.000Z",
  "deliveredVia": null
}

Error format

Failures return JSON { "error": string, "code"?: string }. Do not retry blindly on 400 / 401 / 403.

{
  "error": "business_unit does not match the business unit scoped to this API key",
  "code": "BU_MISMATCH"
}

Limits and billing

• Per-branch pacing: a short burst, then about one SMS/email every 1–5 seconds (configurable). Faster calls return 429 with SEND_RATE_LIMITED and retryAfterSeconds.
• Per-branch daily quota: default 2000 SMS and 2000 emails per rolling 24 hours. Over the quota you receive 429 with DAILY_RATE_LIMIT_EXCEEDED.
• Edge rate limit: 300 requests per minute per client IP and API key (429 when exceeded).
• One invite credit is charged only after delivery succeeds.
• Typical pattern: after checkout or discharge, your backend calls SurvX once per customer — not on every page view.

Need access? Request a demo and generate live keys in the dashboard.