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. 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": "[email protected]",
"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 parties
POST /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 keys
PATCH /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 signing
POST /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.
Authorizations
Personal API key, e.g. Authorization: Bearer sajn_sk_.... Not scope-limited — acts as the issuing user.
Headers
Bearer token for API authentication
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
1[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.
- Option 1
- Option 2
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.
- Option 1
- Option 2
Your 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. Template fields and template parties are copied by default.
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
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 identifier for the created document
[DEPRECATED — use parties instead, will be removed in API v2] Array of created parties. Same content as parties.
Array of created parties. Use GET /documents/:id/parties/:partyId to retrieve signing URLs.
Your external reference ID
Document expiration date