Send survey responses

HTTP status codes and JSON examples for Send surveys via API (POST /api/v1/collectors/api/{collector_uuid}).

All responses use a standard JSON envelope:

• Success: { "success": true, "data": { … } } -optional message
• Error: { "success": false, "message": "…", "errors": { … } } -optional errors

INFO

message and errors text follow the request locale (Accept-Language: ar or en). Examples below use English strings as returned by the API.

1. HTTP status codes

Code	When	Typical message
200	Recipients accepted and send jobs queued	(no required message on success)
401	Missing or invalid X-External-Access-Token	External access token is invalid or missing.
403	Valid token but no access to the survey	You do not have access to this API collector.
404	Unknown collector_uuid	Distribution channel not found.
422	Request validation failed (medium, recipients, Saudi SMS rules, max 5000 recipients)	The given data was invalid.
409	Business rules -entire request fails (nothing queued): inactive collector, unpublished survey, content not ready, duplicate/conflicting recipient	Varies by cause (see examples)

TIP

Unlike export links, send does not return per-recipient results in one call. The request either fully succeeds (200) or fully fails (409 / 422 / …).

2. Example responses

200 -Success (queued)

HTTP 200

{
  "success": true,
  "data": {
    "queued": true,
    "medium": "sms",
    "recipient_count": 2,
    "scheduled_for": "2026-06-03T18:10:14+00:00",
    "jobs_dispatched": 2
  }
}

data field	Description
queued	true when the request is accepted
medium	sms, email, or whatsapp from the request
recipient_count	Number of recipients accepted
scheduled_for	Scheduled send time (ISO 8601) per collector settings
jobs_dispatched	Number of send jobs queued

409 -Duplicate recipient (active invite)

HTTP 409

{
  "success": false,
  "message": "One or more recipients already have an active invitation on this collector.",
  "errors": {
    "recipients.0": [
      "One or more recipients already have an active invitation on this collector."
    ]
  }
}

409 -Same email, different phone

HTTP 409

{
  "success": false,
  "message": "This email is already linked to a different phone number on this collector.",
  "errors": {
    "recipients.0": [
      "This email is already linked to a different phone number on this collector."
    ]
  }
}

409 -Same phone, different email

HTTP 409

{
  "success": false,
  "message": "This phone number is already linked to a different email on this collector.",
  "errors": {
    "recipients.0": [
      "This phone number is already linked to a different email on this collector."
    ]
  }
}

409 -Inactive collector or unpublished survey

HTTP 409 -inactive collector

{
  "success": false,
  "message": "This API collector is inactive."
}

HTTP 409 -unpublished survey

{
  "success": false,
  "message": "This survey has no published version yet."
}

422 -Validation error

HTTP 422 -missing medium

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "medium": [
      "The medium field is required."
    ]
  }
}

HTTP 422 -SMS recipient missing phone

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "recipients.0": [
      "Enter a valid Saudi mobile number (+966 followed by 9 digits)."
    ]
  }
}

401 / 403 / 404

HTTP 401

{
  "success": false,
  "message": "External access token is invalid or missing."
}

HTTP 403

{
  "success": false,
  "message": "You do not have access to this API collector."
}

HTTP 404

{
  "success": false,
  "message": "Distribution channel not found."
}

---

← Request fields · JavaScript & PHP examples →