Core Concepts
Understanding these building blocks will help you navigate the API and design your integration correctly.
Organizations
An organization (org) is the top-level container for all Zined resources. Every user, workspace, document, and template belongs to an org.
- You receive your org ID when you sign up. It never changes.
- Users can be members of multiple orgs. Their role within each org (admin or member) is independent.
- API resources are always scoped to one org at a time, identified by the
x-org-idheader.
Workspaces
A workspace is a sub-division inside an organization for grouping documents and controlling team access. Think of workspaces as project folders: a legal team, an HR department, and a sales team might each have their own workspace.
- Documents, templates, and bulk-send batches all belong to exactly one workspace.
- Users must be explicitly added to a workspace to interact with its resources, even if they are org admins.
- Workspace membership carries a role (
owner,admin,member,viewer) that determines what operations a user can perform.
Passing the workspace
Document and template endpoints require the target workspace to be passed as a request header:
x-workspace-id: <workspace-uuid>
This is separate from x-org-id. Both headers may be required on the same request.
Documents
A document is a PDF that has been uploaded to Zined and is moving through a signing workflow. Documents have a status that reflects where they are in the lifecycle:
| Status | Description |
|---|---|
draft | Uploaded, recipients not yet configured or flow not yet started |
pending | Sent to recipients, awaiting signatures |
completed | All required signatures collected |
declined | A recipient declined to sign |
expired | The document expiry date was reached before completion |
voided | Cancelled by the document owner |
Document types
| Type | Description |
|---|---|
| Send for signature | Sent to one or more external recipients for signing |
| Self-sign | Created and signed by the same user — no external recipients |
File size limits
Uploaded PDFs must be ≤ 20 MB.
Recipients
A recipient is a person assigned to sign or review a document. Each recipient has:
name— display name shown in emails and the signing UIemail— where invitation and reminder emails are sentorder— integer used whensigningStrategyissequential(recipients sign one after another in ascending order order)
Signing strategies
| Strategy | Description |
|---|---|
sequential | Recipients are notified and can sign only after the previous recipient(s) in the order have signed |
parallel | All recipients are notified simultaneously and can sign in any order |
Templates
A template is a reusable document blueprint. You upload a PDF once, place fields (signature boxes, text inputs, date fields, etc.) and define recipient roles (e.g. "Customer", "Witness"). When you create a document from a template, you map real recipients to those roles.
Templates are a subscription-gated feature.
Fields
Fields are the interactive elements placed on a document page. Common field types include:
| Type | Description |
|---|---|
signature | Drawn or typed signature |
initials | Short initials block |
text | Free-text input |
date | Date picker |
checkbox | Boolean checkbox |
Each field has a normalized bounding box (x, y, width, height as fractions of the page dimensions, page index) so coordinates are resolution-independent.
Audit Log
Zined can automatically append a tamper-evident audit trail page to completed documents. The audit log records:
- Who viewed, signed, or declined — with timestamps and IP addresses
- Any authentication steps (e.g. email OTP) used before signing
Enable it per document by setting appendAuditLog: true when creating or uploading.
Authorization model
Access control in Zined has two layers:
- Org-level role —
adminormember. Admins can invite users, manage org settings, and view all org PATs. - Workspace-level role —
owner,admin,member, orviewer. Controls create/read/delete permissions on documents and templates within a workspace.
The API enforces these roles automatically. Attempting a forbidden action returns 403 Forbidden.