Recipients

A recipient is a person invited to fill out a form. Each recipient gets a unique link and optionally pre-filled answers.

Create a recipient

Phone normalization

• International input may include spaces, parentheses, and hyphens, but must include +.
• National input uses the workspace default phone country.
• Successful phone writes store and return E.164, for example +12025550100.
• Invalid phone input returns details.field, details.code, and an optional import row or signer index.
• Existing legacy phone values are not bulk rewritten. Reads and unrelated edits that omit phone can continue to return the stored legacy value until that phone field is successfully rewritten.
• Delivery resolves legacy stored values transiently when possible; it does not silently mutate the recipient record.

The API accepts formatted phone input for recipient creates and phone edits. After a successful phone write, recipient responses expose the stored canonical E.164 value (or null). A response for an untouched legacy row may still expose its pre-existing stored format.

Pre-filling answers

The prefill field accepts a map of question IDs or exact question text to values. The API saves these as Response records immediately — the recipient will see the answers pre-populated when they open the link.

If multiple questions have the same exact text, a text-key prefill applies to all matching questions. If two keys resolve to the same question, the request is rejected.

curl -X POST https://app.formalingo.com/api/v1/forms/FORM_ID/recipients \
-H "Authorization: Bearer af_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
  "label": "John Doe",
  "email": "john@acme.com",
  "expires_at": "2026-03-31T23:59:59Z",
  "prefill": {
    "question-uuid-1": "John Doe",
    "Company": "Acme Corp",
    "Email": "john@acme.com"
  }
}'

{
  "success": true,
  "data": {
    "id": "recipient-uuid",
    "form_id": "form-uuid",
    "label": "John Doe",
    "email": "john@acme.com",
    "token": "abc123",
    "status": "not_started",
    "is_active": true,
    "is_anonymous": false,
    "has_password": false,
    "link": "https://www.formalingo.com/f/abc123",
    "response_count": 3,
    "visit_count": 0,
    "total_questions": 5,
    "created_at": "2026-02-25T10:00:00.000Z"
  }
}

The recipient link

The link field in the response is the URL the recipient uses to fill out the form. Share this via email, embed it in your application, or use it for redirects.