Skip to main content
POST
Create a new document

Authorizations

Authorization
string
header
required

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

Headers

Sajn-Version
enum<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.

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

Maximum string length: 255

Body

application/json

Body

name
string
required

Document name/title

Minimum string length: 1
externalId
string | null

Your external reference ID for tracking this document

expiresAt
string<date-time> | null

Expiration date for the document

type
enum<string>

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

Available options:
SIGNABLE,
ACCEPTABLE,
ARCHIVE_IMPORTED
templateId
string | null

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
object

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

documentStyle
object

Document styling configuration including orientation, padding, background, and layout

parties
object[]

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
object[]

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.

Maximum array length: 100
fieldValues
object[]

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.

Maximum array length: 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
object[]

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

id
string
required

Unique document identifier

externalId
string | null
required

Your external reference ID for this document

expiresAt
string<date-time> | null
required

Date and time when the document expires

name
string
required

Document name/title

status
enum<string>
required

Document status

Available options:
DRAFT,
PENDING_APPROVAL,
PENDING,
COMPLETED,
EXPIRED,
CANCELLED,
REJECTED,
IMPORTED
documentMeta
object | null
required

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

createdAt
string<date-time>
required

Date and time when the document was created

updatedAt
string<date-time>
required

Date and time when the document was last updated

completedAt
string<date-time> | null
required

Date and time when all signers completed signing

deletedAt
string<date-time> | null
required

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

templateId
string | null
required

ID of the template the document was created from, or null

folderId
string | null
required

ID of the folder that holds the document, or null at the top level

responsibleUserId
string | null
required

ID of the workspace member responsible for the document

parties
object[]
required

Array of document parties (signers and other participants).

tags
object[]
required
customFields
object[]
required
content
object[] | null
required

Content blocks in position order when you pass expand=content, and null otherwise. See the content endpoints for the per-type shapes.

productTables
object[]
required

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
string | null
required

ID of the document's approval request, or null when it has none. To read it, call GET /api/v1/approval-requests/{id}.

bundleId
string | null
required

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