Skip to Content

Create a new document

You're viewing API version 2026-09, which is deprecated and stops working on October 1, 2027. To move your integration, see Upgrading to 2026-10.
POST
/api/v1/documents

Create a new document in DRAFT status. You can optionally include parties, metadata, and responsible user during creation.

Document Types:

  • SIGNABLE (default) - Standard signing document
  • ACCEPTABLE - Document that requires acceptance rather than signature
  • ARCHIVE_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:

  1. Contact-based (recommended): Provide contactId to reference existing contacts - automatically inherits all contact details
  2. Manual: Provide name and email to manually specify party details

Note: The legacy signers field is also accepted as input for backwards compatibility, but is deprecated and will stop working in API v2. Use parties going forward. If both are provided, parties takes 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, or NONE
  • requiredSignature - Signature type: DRAWING, BANKID (Swedish BankID), CLICK_TO_SIGN, MANUAL, or a national eID scheme. eID schemes are switched on market by market — call GET /api/v1/helpers/signature-methods for the set your account can actually use rather than hard-coding a list
  • twoStepVerification - identity gate passed BEFORE the document opens: NONE (default), PIN_BEFORE_SIGNING, SMS_BEFORE_SIGNING, EMAIL_BEFORE_SIGNING, or an eID gate such as BANKID_BEFORE_SIGNING — call GET /api/v1/helpers/two-step-verifications for the live list

Complete Workflow with Templates:

  1. Create template (manually in dashboard) with FORM fields containing keys (e.g., "name", "phone", "email")
  2. Create document from template (this endpoint) - include parties with their deliveryMethod and requiredSignature settings
  3. Fill form fields using key-based updates: PATCH /api/v1/documents/{docId}/fields/key:name
  4. Add more parties if needed: POST /api/v1/documents/{docId}/parties
  5. 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.

Authorization

headerAuthorizationBearer <token>

Personal API key, e.g. Authorization: Bearer sajn_sk_.... Not scope-limited — acts as the issuing user.

Header Parameters

authorization*string

Bearer token for API authentication

Idempotency-Key?string

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.

Lengthlength <= 255

Request Body

Body

application/json
  1. body
name*string

Document name/title

Length1 <= length
externalId?|

Your external reference ID for tracking this document

expiresAt?|

Expiration date for the document

Formatdate-time
type?string

Document type: SIGNABLE (default), ACCEPTABLE, or ARCHIVE_IMPORTED

Value in"SIGNABLE""ACCEPTABLE""ARCHIVE_IMPORTED"
templateId?|

Template ID to create document from. Template fields and template parties are copied by default.

responsibleUserId?string

User 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.

Default[]
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.

Default[]
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.

Response Body

200

application/json
  1. response
documentId*string

Unique identifier for the created document

externalId?|

Your external reference ID

expiresAt?|

Document expiration date

Formatdate-time
signers*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.

Example Request
curl -X POST 'https://app.sajn.se/api/v1/documents' \  -H 'authorization: string' \  -H 'Content-Type: application/json' \  -d '{  "name": "string",  "signers": [],  "parties": []}'
Example Response
{  "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?