Request body field reference
This table describes the JSON fields for submitting recipients to an API collector.
| Field | Type | Mandatory | Description |
|---|---|---|---|
medium | string | Yes | Delivery channel for this request: sms, email, or whatsapp (independent of the portal default tab) |
recipients | array | Yes | List of contacts to invite |
recipients[].email | string | Conditional | Required when medium is email. Optional for sms and whatsapp. Max 255 characters. An empty value is allowed; an invalid value rejects that recipient. |
recipients[].phone | string | Conditional | Required when medium is sms or whatsapp. Optional for email. Max 32 characters. sms requires a Saudi mobile (+966 + 9 digits). whatsapp and optional phones on email require international E.164 (e.g. +966…). An empty value is allowed; an invalid value rejects that recipient. |
recipients[].first_name | string | No | Optional given name (max 100 characters) |
recipients[].last_name | string | No | Optional family name (max 100 characters) |
recipients[].variables | object | No | Optional context variables (max 20 keys). Keys: a-z, 0-9, _, starting with a letter (e.g. request_number). Values: string, max 255 characters; longer values are rejected (422). Reserved keys (email, phone, name, h, collect, return, embed_preview, lang, locale, …) are rejected. |
Request limits
medium: required; one ofsms,email,whatsappper request.- Maximum recipients per request: 5000 items in
recipients. - Required per recipient: the contact field for
medium—emailforemail;phoneforsmsorwhatsapp. The other field is optional. Names are always optional.
Context variables
Context variables describe the case, not the person. Customer identity prefers phone, then email. Invite variables are stored on the invitation and copied onto the survey response when the customer submits.
Qualtrics users can treat this as embedded data; our name is context variables.
INFO
The API channel must be active in the app. Invite content (SMS / email / WhatsApp) and scheduling are configured in the collector settings in the portal, not in this request body.