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:
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:
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}.
Authorizations
Personal API key, e.g. Authorization: Bearer sajn_sk_.... Not scope-limited — acts as the issuing user.
Headers
API 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 ID 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.
Makes 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.
255Body
Body
Document name/title
1Your external reference ID for tracking this document
Expiration date for the document
Document type: SIGNABLE (default), ACCEPTABLE, or ARCHIVE_IMPORTED
SIGNABLE, ACCEPTABLE, ARCHIVE_IMPORTED 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.
User ID of the person responsible for this document. Must be a member of your organization. Defaults to the creating user.
Document metadata including subject, message, signing order, etc.
Document styling configuration including orientation, padding, background, and layout
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 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.
100Values 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.
100If 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.
Custom field values for the document
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.
Response
200
Unique document identifier
Your external reference ID for this document
Date and time when the document expires
Document name/title
Document status
DRAFT, PENDING_APPROVAL, PENDING, COMPLETED, EXPIRED, CANCELLED, REJECTED, IMPORTED Document metadata including subject, message, signing order, etc.
Date and time when the document was created
Date and time when the document was last updated
Date and time when all signers completed signing
Date and time when the document moved to the trash, or null when it isn't in the trash
ID of the template the document was created from, or null
ID of the folder that holds the document, or null at the top level
ID of the workspace member responsible for the document
Array of document parties (signers and other participants).
Content blocks in position order when you pass expand=content, and null otherwise. See the content endpoints for the per-type shapes.
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.
ID of the document's approval request, or null when it has none. To read it, call GET /api/v1/approval-requests/{id}.
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}.

