Invitations

Invite customers from your own systems. The same rules as invitations sent from the business portal.

POST/invitationsinvitations:write

GET/invitationsinvitations:read

GET/invitations/{id}invitations:read

DELETE/invitations/{id}invitations:write

Create an invitation

Field	Type	Description
namerequired	string	Customer first name
email or phonerequired	string	Where to send it: email for channel email, phone for WhatsApp
channel	string	email or whatsapp (default email)
reference	string	Your order number, used for proof and to avoid duplicates
products	array	SKUs to ask about (must be in your catalogue)
send_at	datetime	Schedule for later, up to 90 days (default: your timing settings)
language	string	Language of the invitation, e.g. en or ms
business	string	Which business, if your key can use more than one

Rules

Same rules as the business portal: your plan's monthly invitation limit, quiet hours (a night-time send moves to the morning), unsubscribes and at most one invitation per customer every 30 days.
One invitation per order reference; a repeat gets 409.
Channels: email, or WhatsApp through your own connected WhatsApp Business number. There is no SMS.
Send an Idempotency-Key header (for example your order number) so a retry never invites twice. The same key with the same request returns the first answer for 24 hours.
Only scheduled invitations can be cancelled (DELETE).

Invite every customer. Filtering to happy customers breaks our rules and can suspend invitations.

curl -X POST "https://api.proofwell.io/v1/invitations" \
  -H "Authorization: Bearer $PROOFWELL_KEY" \
  -H "Idempotency-Key: order-48213" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Aisha",
    "email": "aisha@example.com",
    "channel": "email",
    "reference": "#48213",
    "products": [
      "HB-250"
    ],
    "business": "biz_example-coffee"
  }'

Example response (example values)

{
  "id": "inv_48213",
  "business_id": "biz_example-coffee",
  "status": "scheduled",
  "channel": "email",
  "name": "Aisha",
  "contact": "a***@example.com",
  "reference": "#48213",
  "kind": "product",
  "send_at": "2026-09-30T02:00:00.000Z",
  "sent_at": null,
  "review_id": null,
  "created_at": "2026-09-24T02:00:00.000Z"
}