Create a new document
2026-09, which is deprecated and stops working on October 1, 2027. To move your integration, see Upgrading to 2026-10.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. Template fields and template parties are automatically copied unless parties are explicitly provided in the request.
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
Note: The legacy
signersfield is also accepted as input for backwards compatibility, but is deprecated and will stop working in API v2. Usepartiesgoing forward. If both are provided,partiestakes precedence.
Party Examples:
{ "parties": [ { "contactId": "contact-123", "role": "SIGNER", "signingOrder": 1, "deliveryMethod": "EMAIL", "requiredSignature": "BANKID" }, { "name": "John Doe", "email": "john@example.com", "role": "SIGNER", "signingOrder": 2, "deliveryMethod": "SMS", "requiredSignature": "DRAWING" } ]}Per-Party Settings:
deliveryMethod- How to notify:EMAIL(default),SMS, orNONErequiredSignature- Signature type:DRAWING,BANKID(Swedish BankID),CLICK_TO_SIGN,MANUAL, or a national eID scheme. eID schemes are switched on market by market — callGET /api/v1/helpers/signature-methodsfor the set your account can actually use rather than hard-coding a listtwoStepVerification- identity gate passed BEFORE the document opens:NONE(default),PIN_BEFORE_SIGNING,SMS_BEFORE_SIGNING,EMAIL_BEFORE_SIGNING, or an eID gate such asBANKID_BEFORE_SIGNING— callGET /api/v1/helpers/two-step-verificationsfor the live list
Complete Workflow with Templates:
- Create template (manually in dashboard) with FORM fields containing keys (e.g., "name", "phone", "email")
- Create document from template (this endpoint) - include parties with their
deliveryMethodandrequiredSignaturesettings - Fill form fields using key-based updates:
PATCH /api/v1/documents/{docId}/fields/key:name - Add more parties if needed:
POST /api/v1/documents/{docId}/parties - Send for signing:
POST /api/v1/documents/{docId}/send
Note: Each party can have their own deliveryMethod (EMAIL, SMS, NONE) and requiredSignature (DRAWING, BANKID, CLICK_TO_SIGN) configured when adding them.
Example workflow:
# Step 1: Create document from template with partiesPOST /api/v1/documents{ "name": "Employment Contract", "templateId": "template-id-with-form-fields", "parties": [ { "type": "contact", "contactId": "contact-456", "role": "SIGNER", "deliveryMethod": "EMAIL", "requiredSignature": "BANKID" } ]}# Step 2: Fill form fields using keysPATCH /api/v1/documents/{docId}/fields/key:name{ "fieldMeta": {"type": "input", "value": "Andreas"}}PATCH /api/v1/documents/{docId}/fields/key:phone{ "fieldMeta": {"type": "input", "value": "0767767712"}}# Step 3: Send for signingPOST /api/v1/documents/{docId}/send{}Response: Returns the created document ID, party IDs, tokens, and signing URLs for all added parties. The legacy signers field is also included in the response (same content as parties) for backwards compatibility, but is deprecated.
AuthorizationBearer <token>Personal API key, e.g. Authorization: Bearer sajn_sk_.... Not scope-limited — acts as the issuing user.
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. Template fields and template parties are copied by default.
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
signers*array<|>[DEPRECATED — use parties instead, will be removed in API v2] Array of signers to add to the document during creation. If both signers and parties are provided, parties takes precedence.
[]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.
[]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
documentId*stringUnique identifier for the created document
externalId?|Your external reference ID
expiresAt?|Document expiration date
date-timesigners*array<>[DEPRECATED — use parties instead, will be removed in API v2] Array of created parties. Same content as parties.
parties*array<>Array of created parties. Use GET /documents/:id/parties/:partyId to retrieve signing URLs.
curl -X POST 'https://app.sajn.se/api/v1/documents' \ -H 'authorization: string' \ -H 'Content-Type: application/json' \ -d '{ "name": "string", "signers": [], "parties": []}'{ "documentId": "string", "externalId": "string", "expiresAt": "2019-08-24T14:15:22Z", "signers": [ { "signerId": "string", "name": "string", "email": "user@example.com", "role": "SIGNER", "signingOrder": 0, "type": "INDIVIDUAL", "companyName": "string", "companyRole": "string", "companyOrgNumber": "string", "country": "string", "contactId": "string" } ], "parties": [ { "signerId": "string", "name": "string", "email": "user@example.com", "role": "SIGNER", "signingOrder": 0, "type": "INDIVIDUAL", "companyName": "string", "companyRole": "string", "companyOrgNumber": "string", "country": "string", "contactId": "string" } ]}Was this page helpful?