Create Form Submission (v1)

Method & Path

POST /api/v1/workspace/:workspaceId/forms/submissions

Description

Create a form submission and generate a unique token plus a short link. Omit clientId for an open link (anyone with the link can fill the form; not tied to a client in the system). With clientId, the submission is tied to that client. The response includes shortLinkCode; the client app builds the full URL as {baseUrl}/links/{shortLinkCode}.

Authentication

Required: Workspace or Staff token.

Path Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	Workspace ID

Request Body

{
  "templateId": "template ObjectId",
  "clientId": "client ObjectId",
  "sendVia": "sms"
}

Open link example (no client):

{
  "templateId": "template ObjectId"
}

Field	Type	Required	Description
templateId	string	Yes	Form template ID
clientId	string	No	Client ID; omit for open link
sendVia	string	No	sms or whatsapp (audit)

Response 201 Created

{
  "id": "...",
  "workspaceId": "...",
  "formTemplateId": "...",
  "clientId": "...",
  "token": "...",
  "shortLinkCode": "Ab12Cd34Ef",
  "status": "pending",
  "answers": [],
  "sentAt": "2024-01-01T00:00:00.000Z",
  "completedAt": null,
  "sentVia": null,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

Use shortLinkCode to build the public short link: {clientAppBaseUrl}/links/{shortLinkCode}.

For open submissions, clientId in the response is null.

Common Errors

• 400: Invalid template or client ID
• 401: Unauthorized
• 404: Template not found, or client not found when clientId was sent
• 500: Server error