Skip to Content
Documents

Create a new document

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

  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

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 yourself
  • signatureMethod - 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 call GET /api/v1/helpers/signature-methods for the set your account can use
  • signVerification - Verification the party passes before signing: PIN, SMS, EMAIL, or an eID such as SE_BANKID. null (default) means none. Call GET /api/v1/helpers/two-step-verifications for the live list

Complete Workflow with Templates:

  1. Create a template in the dashboard, and give each value you fill in a key, such as "name" or "phone".
  2. Create, fill in, and send in one request (this endpoint): send templateId, the parties, the values in fieldValues, and send: true. If the template has signature boxes placed for its parties, fill those parties in with templatePartyId so the boxes stay. To list a template's keys, create a draft and call GET /api/v1/documents/{docId}/field-values.
  3. Show the document in your app, if you embed signing: create an embed session with POST /api/v1/embed-sessions for the party's ID. Find the party in the response by the ref you 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}.

Authorization

headerAuthorizationBearer <token>

API key, e.g. Authorization: Bearer sajn_svc_.... Not scope-limited: acts with its owner's workspace role.

Header Parameters

Sajn-Version?string

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.

Value in"2026-09""2026-10"
Sajn-Workspace?string

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.

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

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.

Itemsitems <= 100
fieldValues?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.

Itemsitems <= 100
send?boolean

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

Response Body

200

application/json
  1. response
id*string

Unique document identifier

externalId*|

Your external reference ID for this document

expiresAt*|

Date and time when the document expires

Formatdate-time
name*string

Document name/title

status*string

Document status

Value in"DRAFT""PENDING_APPROVAL""PENDING""COMPLETED""EXPIRED""CANCELLED""REJECTED""IMPORTED"
documentMeta*|

Document metadata including subject, message, signing order, etc.

createdAt*string

Date and time when the document was created

Formatdate-time
updatedAt*string

Date and time when the document was last updated

Formatdate-time
completedAt*|

Date and time when all signers completed signing

Formatdate-time
deletedAt*|

Date and time when the document moved to the trash, or null when it isn't in the trash

Formatdate-time
templateId*|

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

Example Request
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"    }  ]}'
Example Response
{  "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?