Organize documents with tags
Create tags, add them to documents, and filter the document list by tag
In this guide, you create a tag, add it to a document, and list the documents that have it. Tags are shared across the workspace, so a tag you create through the API also appears in the sajn app.
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). - Have a document to tag. For more information, see Create a document.
Tag a document
Create the tag
Send a POST request to /api/v1/tags with a name and the resources the tag is for in availableFor: one or more of DOCUMENT, TEMPLATE, and CONTACT. color is an optional hex color:
curl -X POST https://app.sajn.se/api/v1/tags \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10" \
-H "Content-Type: application/json" \
-d '{
"name": "Employment",
"color": "#22C55E",
"availableFor": ["DOCUMENT", "TEMPLATE"]
}'The response is the tag:
{
"id": "cm4k2xj5y0010abcd5791opqr",
"name": "Employment",
"color": "#22C55E",
"availableFor": ["DOCUMENT", "TEMPLATE"],
"createdAt": "2026-10-01T09:00:00.000Z",
"updatedAt": "2026-10-01T09:00:00.000Z"
}sajn doesn't stop you from creating two tags with the same name. To reuse an existing tag instead, find its ID with List all tags.
Add the tag to a document
POST /api/v1/documents doesn't take tags. After you create the document, add each tag:
curl -X POST https://app.sajn.se/api/v1/documents/DOCUMENT_ID/tags \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10" \
-H "Content-Type: application/json" \
-d '{ "tagId": "TAG_ID" }'Replace the following:
DOCUMENT_ID: the document ID.TAG_ID: the tagidfrom the previous step.
The response is the document, in the same shape as Get a document by ID without content, and its tags array lists the tag. To tag a template, send the same request to /api/v1/templates/TEMPLATE_ID/tags, which returns the template.
List the documents with the tag
Filter the document list with tagId:
curl "https://app.sajn.se/api/v1/documents?tagId=TAG_ID&limit=50" \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10"To filter by several tags, send a comma-separated list, such as tagId=TAG_ID_1,TAG_ID_2, or repeat the parameter. The list includes documents that have any of the tags.
The response returns the documents in data, each with its tags and parties. When hasMore is true, pass nextCursor as cursor to get the next page. For more information, see Pagination.
Rename a tag or remove it from a document
To change a tag's name or color, send a PATCH request. The change shows on every document that has the tag:
curl -X PATCH https://app.sajn.se/api/v1/tags/TAG_ID \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10" \
-H "Content-Type: application/json" \
-d '{ "name": "Employment contracts", "color": "#16A34A" }'To remove a tag from a document, send a DELETE request:
curl -X DELETE https://app.sajn.se/api/v1/documents/DOCUMENT_ID/tags/TAG_ID \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10"The response is the document, without the tag in tags.
Choose a tagging scheme
We recommend a small set of tags that everyone applies the same way, such as one tag per document type (Employment, NDA, Vendor) or per department (HR, Legal, Sales). For structured values, such as a cost center or a contract value, use custom fields instead. For a hierarchy, use folders.
Handle errors
400 VALIDATION_FAILED:nameoravailableForis missing, oravailableForhas an unknown value.404 NOT_FOUND: the document or the tag doesn't exist in the workspace.409 ALREADY_EXISTS: the document already has the tag. Read the document'stagsfirst, or treat the error as success.
For the error shape and every code, see Errors.
Next steps
Was this page helpful?
Last updated on