Manage public forms
Create a public form, configure its questions and document, publish its link, and sync the responses
In this guide, you create a public form: a hosted link where visitors answer questions and then sign a document. You configure the questions and the document, publish the link, and sync the responses to your system.
Each form owns its own template, which only the form uses. Every submission creates an ordinary sajn document from it.
Before you begin
- Get a bearer token for the workspace: an API key, or an OAuth access token. To create an API key, go to workspace settings in the sajn app, then Utvecklare (Developer) > API-nycklar (API keys). Store it in the
SAJN_API_KEYenvironment variable. - Make sure your workspace role has the permissions for the task:
MANAGE_FORMto create, edit, and publish forms,DELETE_FORMto delete them, andREAD_FORM_SUBMISSIONSto read responses. To publish, you also need permission to create documents and send them without approval, and the workspace must not require approval before sending.
An OAuth app requests the following scopes. An API key uses its user's workspace permissions instead.
| Scope | Access |
|---|---|
forms:read | Form configuration, the form's template, and statistics. |
forms:write | Creating and managing forms and their public links. |
forms:delete | Deleting forms and their submission records permanently. |
forms:submissions:read | Respondents' contact details and answers. |
documents:write | Editing and publishing, together with forms:write. |
templates:read | Creating a form from a template. |
Create and publish a form
Create a draft
Send a POST request to /api/v1/forms. To copy an existing template, send its templateId. To start with a blank document and one respondent party, send {}:
curl -X POST https://app.sajn.se/api/v1/forms \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: create-registration-form-1" \
-d '{ "templateId": "TEMPLATE_ID" }'Replace TEMPLATE_ID with the template to copy. The response is the form: its id, templateId (the form's own template), respondentPartyId, url, its settings, and publishIssues. The copy has new field and party IDs, and later changes to the source template don't affect it.
Configure the questions and settings
Send a PATCH request to /api/v1/forms/FORM_ID:
curl -X PATCH https://app.sajn.se/api/v1/forms/FORM_ID \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10" \
-H "Content-Type: application/json" \
-d '{
"name": "Registration",
"documentExpiresInDays": 30,
"maxSubmissions": 500,
"questions": [
{ "id": "name", "kind": "NAME", "required": true },
{ "id": "email", "kind": "EMAIL", "required": true },
{ "id": "notes", "kind": "TEXT", "label": "Additional information", "required": false, "multiline": true }
]
}'Replace FORM_ID with the form id. The request works as follows:
- Settings you leave out stay unchanged, and
nullclears a nullable setting. Forpassword, leaving it out keeps the password,nullremoves it, and a string replaces it. Responses showhasPassword, never the password. questionsreplaces the whole ordered list. The kinds areNAME,EMAIL,PHONE,FIELD,TEXT,HEADING, andPARAGRAPH. TheNAMEquestion is always required.- A
FIELDquestion writes its answer into the document, through akeyfrom the form'sslots. ATEXTanswer is stored on the submission only. redirectUrlmust be anhttporhttpsURL.
Saving settings doesn't publish the form, reopen a closed form, or change its sender.
Edit the template and the respondent
Read GET /api/v1/forms/FORM_ID/template for the template's settings, content blocks, and parties. Then change them with the form's template endpoints:
PATCH /api/v1/forms/FORM_ID/template: changenameandtemplateMeta, such assigningMode. The response is the template.PUT /api/v1/forms/FORM_ID/template/content: replacecontentwith the complete ordered list of content blocks. Include the IDs of blocks to keep, and leave out IDs for new blocks. Blocks you leave out are deleted, and existing blocks can't change type.PUT /api/v1/forms/FORM_ID/template/parties: replaceparties. Include the IDs of parties to keep, and leave out IDs for new parties. Properties you leave out on kept parties, including contact links and write-only PINs, stay unchanged, andnullclears a property. Parties you leave out are deleted. Like other parties, these nest their company incompany, withname,orgNumber, androle.PUT /api/v1/forms/FORM_ID/respondentwith{ "partyId": "PARTY_ID" }: choose whichSIGNERparty the visitor becomes.
Existing submissions don't change. An edit to a published form can close it when a readiness check finds a blocker, so read GET /api/v1/forms/FORM_ID afterward for publishIssues and the bindable slots.
Publish the form
curl -X POST https://app.sajn.se/api/v1/forms/FORM_ID/publish \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10"Publishing checks the document, the expiry, the capacity, the sender's permissions, the workspace policy, and access to the signing methods. You become the sender of every document the form creates. If the request reports blockers, fix them and publish again. Then share the form's url. Visitors answer and sign on the hosted pages; the API can't submit or sign on their behalf.
To stop new submissions and keep the URL for later, send a POST request to /api/v1/forms/FORM_ID/unpublish. To replace the link, for example after it leaked, send a POST request to /api/v1/forms/FORM_ID/rotate-token; the response is the form with the new url. The old link stops working, including printed QR codes, but signing links already sent keep working.
Sync the responses
Subscribe a webhook to form.submitted to hear about each submission; the event's data.object is the submission. To sync the submissions, page through the ones that changed since your last sync, oldest change first:
curl "https://app.sajn.se/api/v1/forms/FORM_ID/submissions?limit=100&updatedAfter=2026-10-01T00:00:00Z&orderBy=updatedAt&orderDirection=asc" \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10"The response has the submissions in data, plus hasMore and nextCursor. While hasMore is true, pass nextCursor as cursor with the same filters and sort. A submission can change while you page, so upsert each one by its ID.
updatedAfterfinds status changes since your last sync.submittedAfterfilters by submission time.statustakesSTARTED,SUBMITTED,COMPLETED, orEXPIRED.- Each submission has the respondent's contact details, the answers, timestamps, and the
documentIdof the document it created. Read the document's content and signing progress through the document endpoints. Submissions don't include IP addresses, user agents, or signing tokens.
Delete a form
DELETE /api/v1/forms/FORM_ID permanently removes the form, its template, and its submission records, and returns { "id": "FORM_ID", "deleted": true }. Export the responses you need first. Documents the form already created stay as ordinary documents.
Handle errors
400 VALIDATION_FAILED: a question or a setting is invalid. Readissuesfor the path.- An error from
publish: a readiness check failed. ReadGET /api/v1/forms/FORM_IDforpublishIssues, fix each one, and publish again. 403 PERMISSION_DENIEDor403 INSUFFICIENT_SCOPE: your role or token lacks a permission or scope from the preceding table.
For the error shape and every code, see Errors.
Next steps
Was this page helpful?
Last updated on