Create a new document
Create a new document in DRAFT status. You can optionally include parties, metadata, and responsible user during creation.
Document Types:
SIGNABLE(default) - Standard signing documentACCEPTABLE- Document that requires acceptance rather than signatureARCHIVE_IMPORTED- Imported from external archive
Template Support: Use templateId to create a document from a template. The template's fields and parties are copied. If you also send parties, they replace the template's parties, and signature and initials boxes placed on the PDF for the template's parties are removed.
CRM Link: Use integrationLink to link the document to a CRM record (currently HubSpot deals). When the workspace has a field mapping configured for the integration, mapped custom fields and product-table rows are prefilled from the record, and signing status is written back to it. Explicit customFields in the request take precedence over prefilled values.
Responsible User: Use responsibleUserId to assign a specific team member as responsible for the document. Defaults to the creating user if not specified.
Adding Parties: Two approaches are supported:
- Contact-based (recommended): Provide
contactIdto reference existing contacts - automatically inherits all contact details - Manual: Provide
nameandemailto manually specify party details
Party Examples:
{ "parties": [ { "contactId": "contact-123", "role": "SIGNER", "signingOrder": 1, "delivery": ["EMAIL"], "signatureMethod": "SE_BANKID" }, { "name": "John Doe", "email": "john@example.com", "role": "SIGNER", "signingOrder": 2, "delivery": ["SMS"], "signatureMethod": "DRAWING" } ]}Per-Party Settings:
delivery- How the party gets the invitation:["EMAIL"](default),["SMS"],["IN_APP"]to sign in person on your device, or[]to send nothing and share the signing URL yourselfsignatureMethod- How the party signs:DRAWING,SE_BANKID(Swedish BankID),CLICK_TO_SIGN,MANUAL, or a national eID scheme. eID schemes are switched on market by market, so callGET /api/v1/helpers/signature-methodsfor the set your account can usesignVerification- Verification the party passes before signing:PIN,SMS,EMAIL, or an eID such asSE_BANKID. null (default) means none. CallGET /api/v1/helpers/two-step-verificationsfor the live list
Complete Workflow with Templates:
- Create a template in the dashboard, and give each value you fill in a key, such as "name" or "phone".
- Create, fill in, and send in one request (this endpoint): send
templateId, theparties, the values infieldValues, andsend: true. If the template has signature boxes placed for its parties, fill those parties in withtemplatePartyIdso the boxes stay. To list a template's keys, create a draft and callGET /api/v1/documents/{docId}/field-values. - Show the document in your app, if you embed signing: create an embed session with
POST /api/v1/embed-sessionsfor the party's ID. Find the party in the response by therefyou gave it.
Each party has its own delivery and signatureMethod. A party with delivery: [] gets no invitation.
Example:
POST /api/v1/documents{ "name": "Employment Contract", "templateId": "template-id-with-form-fields", "parties": [ { "templatePartyId": "template-party-id", "ref": "employee", "name": "Alex Andersson", "email": "alex@example.com", "role": "SIGNER", "delivery": [], "signatureMethod": "SE_BANKID" } ], "fieldValues": [ {"key": "name", "value": "Alex Andersson"}, {"key": "phone", "value": "+46700000000"} ], "send": true}To fill in values or add parties after creation, use PATCH /api/v1/documents/{docId}/field-values and POST /api/v1/documents/{docId}/parties, then send with POST /api/v1/documents/{docId}/send.
Response: Returns the created document in the same shape as GET /api/v1/documents/{id}, without fields. Each party carries the ref you gave it. To get a party's signing URL, call GET /api/v1/documents/{id}/parties/{partyId}.
AuthorizationBearer <token>API key, e.g. Authorization: Bearer sajn_svc_.... Not scope-limited: acts with its owner's workspace role.
Sajn-Version?stringAPI version for this request. Without it, the request uses the organization's default version; an organization without a default is pinned to the latest version by its first request.
"2026-09""2026-10"Sajn-Workspace?stringID of the workspace this request acts in, from GET /api/v1/workspaces. Without it, an API key acts in its default workspace. The token's user must be a member of the workspace; an OAuth token only accepts the workspace it was granted for. A workspace that doesn't exist or can't be reached returns 403 WORKSPACE_ACCESS_DENIED.
Idempotency-Key?stringMakes retries safe. A retry with the same key and the same request replays the stored response for 24 hours (header Idempotent-Replayed: true); the same key with a different request returns 400.
length <= 255Body
application/json- body
name*stringDocument name/title
1 <= lengthexternalId?|Your external reference ID for tracking this document
expiresAt?|Expiration date for the document
date-timetype?stringDocument type: SIGNABLE (default), ACCEPTABLE, or ARCHIVE_IMPORTED
"SIGNABLE""ACCEPTABLE""ARCHIVE_IMPORTED"templateId?|Template ID to create document from. The template's fields and parties are copied. If you also send parties, they replace the template's parties, and signature and initials boxes placed for the template's parties are removed, unless a party names a templatePartyId: then the template's parties and their boxes are kept, and the parties you send fill them in or are added.
responsibleUserId?stringUser ID of the person responsible for this document. Must be a member of your organization. Defaults to the creating user.
documentMeta?Document metadata including subject, message, signing order, etc.
documentStyle?Document styling configuration including orientation, padding, background, and layout
parties?array<>Array of parties to add to the document during creation. Provide either contactId to reference existing contacts, or name and email to manually specify party details.
content?array<>Content blocks to create with the document, in the same shape as POST /api/v1/documents/{id}/content. A block names a party by its ref or its ID.
items <= 100fieldValues?array<>Values to fill in by key, in the same shape as values in PATCH /api/v1/documents/{id}/field-values. sajn writes them after parties and content, and before send. If a key matches no value, or a value doesn't fit its field, sajn creates nothing and returns the problems in issues.
items <= 100send?booleanIf true, sends the document for signing after it is created, the same way as POST /api/v1/documents/{id}/send. If the send fails, the document stays a draft and the error names its ID.
customFields?array<>Custom field values for the document
integrationLink?Link the document to a CRM record. Prefills mapped custom fields and product tables from the record (configured under Integrations) and enables status write-back to it.
200
application/json- response
id*stringUnique document identifier
externalId*|Your external reference ID for this document
expiresAt*|Date and time when the document expires
date-timename*stringDocument name/title
status*stringDocument status
"DRAFT""PENDING_APPROVAL""PENDING""COMPLETED""EXPIRED""CANCELLED""REJECTED""IMPORTED"documentMeta*|Document metadata including subject, message, signing order, etc.
createdAt*stringDate and time when the document was created
date-timeupdatedAt*stringDate and time when the document was last updated
date-timecompletedAt*|Date and time when all signers completed signing
date-timedeletedAt*|Date and time when the document moved to the trash, or null when it isn't in the trash
date-timetemplateId*|ID of the template the document was created from, or null
folderId*|ID of the folder that holds the document, or null at the top level
responsibleUserId*|ID of the workspace member responsible for the document
parties*array<>Array of document parties (signers and other participants).
tags*array<>customFields*array<>content*array<>|Content blocks in position order when you pass expand=content, and null otherwise. See the content endpoints for the per-type shapes.
productTables*array<>Every product table on the document, resolved: each row carries the recipient's final selected state and quantity, and the totals count the selected rows only. Empty when the document has no product table.
approvalRequestId*|ID of the document's approval request, or null when it has none. To read it, call GET /api/v1/approval-requests/{id}.
bundleId*|ID of the bundle the document was sent in, or null. Every document in a bundle also fires its own events, so this is the key that groups them. To read the bundle, call GET /api/v1/bundles/{id}.
curl -X POST 'https://app.sajn.se/api/v1/documents' \ -H 'Content-Type: application/json' \ -d '{ "name": "Anställningsavtal – Kai Lindqvist", "externalId": "HR-2026-0142", "templateId": "cm4k2x9p10008abcd1234efgh", "expiresAt": "2026-10-28T22:00:00.000Z", "documentMeta": { "subject": "Ditt anställningsavtal från Exempelbolaget AB", "message": "Hej Kai! Här är ditt anställningsavtal. Signera det med BankID senast den 28 oktober." }, "parties": [ { "ref": "employee", "name": "Kai Lindqvist", "email": "kai@example.com", "role": "SIGNER", "signatureMethod": "SE_BANKID" } ], "fieldValues": [ { "key": "befattning", "value": "Rekryterare" } ], "customFields": [ { "customFieldId": "cm4k2x9p10016abcd1234efgh", "value": "2026-11-01" } ]}'{ "id": "cm4k2x9p10003abcd1234efgh", "externalId": "HR-2026-0142", "expiresAt": "2026-10-28T22:00:00.000Z", "name": "Anställningsavtal – Kai Lindqvist", "status": "DRAFT", "documentMeta": { "subject": "Ditt anställningsavtal från Exempelbolaget AB", "message": "Hej Kai! Här är ditt anställningsavtal. Signera det med BankID senast den 28 oktober.", "signingMode": "PARALLEL", "forceReadFullDocument": false, "showChatToSigners": false, "language": "sv", "value": "540000", "redirectUrl": null, "redirectEnabled": true, "internalRecipients": [ "hr@example.com" ], "signableAfterExpired": false, "sendPlainTextEmailOnly": false, "reminderIntervalDays": 3, "allowDelegation": false, "openVerification": "PIN", "aiChatEnabled": false, "nationalIdDisplayMode": "FULL", "sameDeviceSigning": false, "documentCategoryId": "cm4k2x9p10017abcd1234efgh" }, "createdAt": "2026-09-28T09:12:00.000Z", "updatedAt": "2026-09-28T09:12:00.000Z", "completedAt": null, "deletedAt": null, "templateId": "cm4k2x9p10008abcd1234efgh", "folderId": "cm4k2x9p10011abcd1234efgh", "responsibleUserId": "cm4k2x9p10002abcd1234efgh", "parties": [ { "id": "cm4k2x9p10004abcd1234efgh", "documentId": "cm4k2x9p10003abcd1234efgh", "email": "kai@example.com", "name": "Kai Lindqvist", "phone": "+46701740605", "type": "INDIVIDUAL", "company": null, "externalId": "HR-2026-0142", "contactId": "cm4k2x9p10006abcd1234efgh", "nationalId": "191212121212", "country": "SE", "role": "SIGNER", "signingOrder": 1, "signedAt": null, "readStatus": "NOT_OPENED", "signingStatus": "NOT_SIGNED", "delivery": [ "EMAIL" ], "signatureMethod": "SE_BANKID", "signVerification": "PIN", "openVerification": "PIN", "sendStatus": "NOT_SENT", "identityVerified": false, "identityMismatch": false, "createdAt": "2026-09-28T09:12:00.000Z", "ref": "employee" } ], "tags": [ { "id": "cm4k2x9p10010abcd1234efgh", "name": "Anställning", "color": "#16A34A" } ], "customFields": [ { "id": "cm4k2x9p10016abcd1234efgh", "name": "Startdatum", "type": "TEXT", "value": "2026-11-01" } ], "content": [ { "id": "cm4k2x9p10009abcd1234efgh", "documentId": "cm4k2x9p10003abcd1234efgh", "templateId": null, "type": "TEXT", "position": 0, "fieldMeta": { "type": "TEXT", "content": "<p>Anställningen gäller tills vidare från och med den 1 november 2026, med sex månaders provanställning.</p>" }, "createdAt": "2026-09-28T09:12:00.000Z", "updatedAt": "2026-09-28T09:12:00.000Z" } ], "productTables": [ { "fieldId": "cm4k2x9p10009abcd1234efgh", "name": "Anställningsavtal – Kai Lindqvist", "currency": "SEK", "language": "sv", "allowSelection": false, "selectionPartyId": "cm4k2x9p10004abcd1234efgh", "selectionRequired": false, "sections": [ { "id": "cm4k2x9p10037abcd1234efgh", "name": "Utbildningar", "pickOne": false } ], "rows": [ { "id": "cm4k2x9p10036abcd1234efgh", "sku": "UTB-INTRO", "name": "Introduktionsutbildning", "description": "Introduktionsutbildning.", "unit": "st", "price": 4500, "vat": 25, "billing": "ONE_TIME", "discount": { "type": "PERCENT", "value": 1 }, "optional": false, "selected": false, "quantity": 1, "lineTotal": 1, "lineNet": 1, "lineVat": 1, "sectionId": "cm4k2x9p10037abcd1234efgh", "productType": "GOODS" } ], "totals": { "subtotal": 4500, "discountAmount": 1, "vatAmount": 1125, "total": 1, "rotDeduction": 1, "rutDeduction": 1, "payable": 5625, "byBilling": { "ONE_TIME": { "subtotal": 4500, "vatAmount": 1125, "total": 1 }, "MONTHLY": { "subtotal": 4500, "vatAmount": 1125, "total": 1 }, "QUARTERLY": { "subtotal": 4500, "vatAmount": 1125, "total": 1 }, "YEARLY": { "subtotal": 4500, "vatAmount": 1125, "total": 1 } } } } ], "approvalRequestId": "cm4k2x9p10003abcd1234efgh", "bundleId": "cm4k2x9p10044abcd1234efgh"}Was this page helpful?