Manage templates
Create a template with content, default parties, settings, and tags through the API, and keep it up to date
In this guide, you build a template through the API: its content, its default parties, the settings that documents inherit, and a tag. Then you list, copy, and delete templates.
To create documents from a template and fill in its fields, see Create documents from templates. Most teams build templates in the sajn editor; use this guide when your code owns the template.
Before you begin
- Store your API key in the
SAJN_API_KEYenvironment variable. To create a key, go to workspace settings in the sajn app, then Utvecklare (Developer) > API-nycklar (API keys). - Read Fields that parties fill in for the FORM block format. Template content uses the same format as document content.
Build a template
Create the template with its content
Send a POST request to /api/v1/templates with a name and the content blocks in initialContent:
curl -X POST https://app.sajn.se/api/v1/templates \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10" \
-H "Content-Type: application/json" \
-d '{
"name": "Employment contract",
"initialContent": [
{ "type": "HTML", "position": 0,
"fieldMeta": { "type": "HTML", "content": "<h1>Employment contract</h1><p>The terms of employment follow.</p>" } },
{ "type": "FORM", "position": 1,
"fieldMeta": {
"type": "FORM",
"columns": 2,
"fields": [
{ "id": "employee-name", "key": "employee-name", "row": 0, "column": 0,
"fieldMeta": { "type": "INPUT", "label": "Name", "required": true } },
{ "id": "start-date", "key": "start-date", "row": 0, "column": 1,
"fieldMeta": { "type": "DATEPICKER", "label": "Start date", "required": true } }
]
} }
]
}'The response is the template:
{
"id": "cm4k2xc1r0004abcd3456qrst",
"name": "Employment contract",
"workspaceId": "cm4k2xy7b0000abcd0000wsxx",
"organizationId": "cm4k2xz0a0000abcd0000orgx",
"createdBy": { "id": "cm4k2xw3c0000abcd0000usrx", "email": "dana@example.com", "name": "Dana Lund" },
"isGlobal": false,
"templateMeta": {
"signingMode": "PARALLEL",
"forceReadFullDocument": false,
"showChatToSigners": true,
"language": "sv",
"value": null,
"signableAfterExpired": false,
"sendPlainTextEmailOnly": null,
"allowDelegation": true,
"reminderIntervalDays": 3,
"responsibleUserId": "cm4k2xw3c0000abcd0000usrx",
"openVerification": null,
"internalRecipients": [],
"visibility": "EVERYONE",
"selectedUserIds": [],
"nationalIdDisplayMode": null,
"sameDeviceSigning": false,
"documentCategoryId": null
},
"parties": [],
"tags": [],
"content": null,
"createdAt": "2026-10-01T09:00:00.000Z",
"updatedAt": "2026-10-01T09:00:00.000Z",
"deletedAt": null
}Every template endpoint returns the template in this shape. content is null unless you get the template with expand=content. Store the template id. The subfield keys, employee-name and start-date, are the keys your code fills in on every document created from the template.
Add the default parties
Add a placeholder party for each person who signs. A template party has a name, a role, and its signing settings. Documents created from the template get a copy of each party, which you then update with the real person:
curl -X POST https://app.sajn.se/api/v1/templates/TEMPLATE_ID/parties \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10" \
-H "Content-Type: application/json" \
-d '{
"name": "Employee",
"role": "SIGNER",
"signingOrder": 1,
"delivery": ["EMAIL"],
"signatureMethod": "SE_BANKID"
}'Replace TEMPLATE_ID with the template id. For a party who's the same on every document, such as your HR manager, send contactId instead of name.
For a party who signs for a company, send company with name and orgNumber, and optionally role, such as { "name": "Example AB", "orgNumber": "5566778899", "role": "CEO" }. Template parties and document parties nest the company the same way, and company is null for a private individual.
Set the defaults for new documents
templateMeta holds the settings that every document created from the template starts with:
curl -X PATCH https://app.sajn.se/api/v1/templates/TEMPLATE_ID \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10" \
-H "Content-Type: application/json" \
-d '{
"templateMeta": {
"signingMode": "SEQUENTIAL",
"language": "en",
"reminderIntervalDays": 3,
"forceReadFullDocument": true,
"internalRecipients": ["hr@example.com"]
}
}'templateMeta takes the same settings as documentMeta on a document, plus visibility and selectedUserIds, which control who can see documents created from the template. For every property, see Update a template.
Tag the template
Add a tag that has TEMPLATE in its availableFor list:
curl -X POST https://app.sajn.se/api/v1/templates/TEMPLATE_ID/tags \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10" \
-H "Content-Type: application/json" \
-d '{ "tagId": "TAG_ID" }'Replace TAG_ID with the tag's ID. For more information, see Organize documents with tags.
Create a document from it
The template is ready. To create a document, fill in its values, and send it, see Create documents from templates.
Find, copy, and delete templates
- List templates with
GET /api/v1/templates. Filter by name withquery, and by tag withtagId. The response has the templates indata; to get the next page, passnextCursorascursorwhilehasMoreistrue. For more information, see Pagination. - Get one template with its
partiesandtagswithGET /api/v1/templates/TEMPLATE_ID. To include its content blocks incontent, addexpand=content. - Copy a template with all its content and parties with
POST /api/v1/templates/TEMPLATE_ID/duplicate. Use a copy to change a template without affecting the original. - Delete a template with
DELETE /api/v1/templates/TEMPLATE_ID. The template moves to the trash, and the response is the template withdeletedAtset. sajn deletes it permanently after 90 days. Documents created from it aren't affected. - List the documents created from a template with
GET /api/v1/documents?templateId=TEMPLATE_ID.
Change content and parties
The template content and party endpoints work like their document counterparts:
| Task | Endpoint |
|---|---|
| Add content blocks | POST /api/v1/templates/TEMPLATE_ID/content |
| Replace a content block | PATCH /api/v1/templates/TEMPLATE_ID/content/CONTENT_ID |
| Find the block that holds a key | GET /api/v1/templates/TEMPLATE_ID/content?key=KEY |
| Move boxes on a PDF | PATCH /api/v1/templates/TEMPLATE_ID/content/CONTENT_ID/placed-fields |
| Delete a content block | DELETE /api/v1/templates/TEMPLATE_ID/content/CONTENT_ID |
| Change a party | PATCH /api/v1/templates/TEMPLATE_ID/parties/PARTY_ID |
| Remove a party | DELETE /api/v1/templates/TEMPLATE_ID/parties/PARTY_ID |
A content block update replaces the block's fieldMeta, so send the whole object. To change one FORM subfield, find its block by key, then send the block's whole fieldMeta with the subfield changed. A content block DELETE returns { "id": "CONTENT_ID", "deleted": true }; to keep the block, read it first. For the block formats, see HTML content, Fields that parties fill in, and Place fields on a PDF.
Handle errors
400 VALIDATION_FAILED: a content block or a party is invalid. For example, a role ofACCEPTORfails; sendSIGNER. Readissuesfor the path.409 INVALID_STATE: the template is locked against edits.404 NOT_FOUND: the template, the content block, or the party doesn't exist in the workspace.
For the error shape and every code, see Errors.
Next steps
Was this page helpful?
Last updated on