Submit Public Form by Token (v1)

Method & Path

PATCH /api/v1/workspace/public/form/:token

Actual path: /v1/workspace/public/form/:token

Description

Submit form answers by token. Marks the submission as completed. No authentication required.

For open submissions (created without a clientId), each successful submit keeps the completed row as its own record, creates a new pending submission for the same template, and updates the same short link to point at the new token so the shared URL can be filled again. The JSON may include nextFillToken (the new public form token). Client-linked submissions do not rotate; resubmitting the same token still returns 409 if already completed.

Authentication

None - Public endpoint.

Path Parameters

Parameter	Type	Required	Description
token	string	Yes	Form submission token

Request Body

{
  "answers": [
    { "questionId": "q_1", "value": "نص الإجابة" },
    { "questionId": "q_2", "value": "option_value" },
    { "questionId": "q_3", "value": ["opt1", "opt2"] }
  ]
}

For single_choice and text, value is a string. For multiple_choice, value is an array of strings.

Response 200 OK

Returns the same shape as Get Public Form by Token with submission.status set to completed and submission.answers updated. form.completionHandoffWhatsAppPhone is included when set so the client can offer a WhatsApp handoff with prefilled Q&A.

Field	Type	Description
nextFillToken	string	Optional. Only for open (no-client) submissions: token the short link now targets for the next respondent. Omitted or null for client-specific links.

Common Errors

• 400: Token required
• 404: Form not found or link expired
• 409: Form already submitted
• 500: Server error