mirror of
https://github.com/documenso/documenso.git
synced 2026-08-15 02:53:32 +10:00
docs(api): complete document object reference and note externalId tagging
This commit is contained in:
ephraimduncan
@@ -28,35 +28,62 @@ Each document contains one or more PDF files, a list of recipients, and the fiel
|
|||||||
|
|
||||||
A document object contains the following properties:
|
A document object contains the following properties:
|
||||||
|
|
||||||
| Property | Type | Description |
|
| Property | Type | Description |
|
||||||
| --------------- | -------------- | -------------------------------------------------------------- |
|
| ------------------- | -------------- | -------------------------------------------------------------------------------------------- |
|
||||||
| `id` | string | Unique identifier (e.g., `envelope_abc123`) |
|
| `id` | string | Unique identifier (e.g., `envelope_abc123`) |
|
||||||
| `type` | string | `DOCUMENT` or `TEMPLATE` |
|
| `secondaryId` | string | Legacy identifier in prefixed form (`document_123` for documents, `template_123` for templates) |
|
||||||
| `status` | string | Current status: `DRAFT`, `PENDING`, `COMPLETED`, `REJECTED`, or `CANCELLED` |
|
| `internalVersion` | number | Internal envelope schema version |
|
||||||
| `title` | string | Document title |
|
| `type` | string | `DOCUMENT` or `TEMPLATE` |
|
||||||
| `source` | string | How the document was created: `DOCUMENT`, `TEMPLATE`, `TEMPLATE_DIRECT_LINK` |
|
| `status` | string | Current status: `DRAFT`, `PENDING`, `COMPLETED`, `REJECTED`, or `CANCELLED` |
|
||||||
| `visibility` | string | Who can view: `EVERYONE`, `ADMIN`, `MANAGER_AND_ABOVE` |
|
| `title` | string | Document title |
|
||||||
| `externalId` | string \| null | Your custom identifier for the document |
|
| `source` | string | How the document was created: `DOCUMENT`, `TEMPLATE`, `TEMPLATE_DIRECT_LINK` |
|
||||||
| `createdAt` | string | ISO 8601 timestamp |
|
| `visibility` | string | Who can view: `EVERYONE`, `ADMIN`, `MANAGER_AND_ABOVE` |
|
||||||
| `updatedAt` | string | ISO 8601 timestamp |
|
| `templateType` | string | Template visibility: `PUBLIC`, `PRIVATE`, or `ORGANISATION` (only meaningful for templates) |
|
||||||
| `completedAt` | string \| null | Timestamp when all recipients completed signing |
|
| `externalId` | string \| null | Your custom identifier for the document |
|
||||||
| `deletedAt` | string \| null | Timestamp if soft-deleted |
|
| `userId` | number | ID of the user who owns the document |
|
||||||
| `recipients` | array | List of recipients and their signing status |
|
| `teamId` | number | ID of the team the document belongs to |
|
||||||
| `fields` | array | Signature and form fields on the document |
|
| `folderId` | string \| null | ID of the folder containing the document |
|
||||||
| `envelopeItems` | array | PDF files attached to the document |
|
| `templateId` | number \| null | Legacy ID of the template this document was created from |
|
||||||
| `documentMeta` | object | Email settings, redirect URL, signing options |
|
| `authOptions` | object \| null | Access and action authentication requirements |
|
||||||
|
| `formValues` | object \| null | Pre-filled form values |
|
||||||
|
| `publicTitle` | string | Public title shown on profile and direct-link pages |
|
||||||
|
| `publicDescription` | string | Public description shown on profile and direct-link pages |
|
||||||
|
| `createdAt` | string | ISO 8601 timestamp |
|
||||||
|
| `updatedAt` | string | ISO 8601 timestamp |
|
||||||
|
| `completedAt` | string \| null | Timestamp when all recipients completed signing |
|
||||||
|
| `deletedAt` | string \| null | Timestamp if soft-deleted |
|
||||||
|
| `recipients` | array | List of recipients and their signing status |
|
||||||
|
| `fields` | array | Signature and form fields on the document |
|
||||||
|
| `envelopeItems` | array | PDF files attached to the document |
|
||||||
|
| `directLink` | object \| null | Direct-link signing configuration (`id`, `token`, `enabled`, `directTemplateRecipientId`) |
|
||||||
|
| `team` | object | Owning team (`id`, `url`) |
|
||||||
|
| `user` | object | Document owner (`id`, `name`, `email`) |
|
||||||
|
| `documentMeta` | object | Email settings, redirect URL, signing options |
|
||||||
|
|
||||||
|
Documents created through the API have `source: "DOCUMENT"` — there is no separate `API` source value. To tag documents created by your integration, set `externalId` when creating them.
|
||||||
|
|
||||||
### Example Document Object
|
### Example Document Object
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"id": "envelope_abc123xyz",
|
"id": "envelope_abc123xyz",
|
||||||
|
"secondaryId": "document_123",
|
||||||
|
"internalVersion": 2,
|
||||||
"type": "DOCUMENT",
|
"type": "DOCUMENT",
|
||||||
"status": "PENDING",
|
"status": "PENDING",
|
||||||
"source": "DOCUMENT",
|
"source": "DOCUMENT",
|
||||||
"visibility": "EVERYONE",
|
"visibility": "EVERYONE",
|
||||||
|
"templateType": "PRIVATE",
|
||||||
"title": "Service Agreement",
|
"title": "Service Agreement",
|
||||||
"externalId": "contract-2025-001",
|
"externalId": "contract-2025-001",
|
||||||
|
"userId": 1,
|
||||||
|
"teamId": 1,
|
||||||
|
"folderId": null,
|
||||||
|
"templateId": null,
|
||||||
|
"authOptions": null,
|
||||||
|
"formValues": null,
|
||||||
|
"publicTitle": "",
|
||||||
|
"publicDescription": "",
|
||||||
"createdAt": "2025-01-15T10:30:00.000Z",
|
"createdAt": "2025-01-15T10:30:00.000Z",
|
||||||
"updatedAt": "2025-01-15T10:35:00.000Z",
|
"updatedAt": "2025-01-15T10:35:00.000Z",
|
||||||
"completedAt": null,
|
"completedAt": null,
|
||||||
@@ -74,22 +101,40 @@ A document object contains the following properties:
|
|||||||
"fields": [
|
"fields": [
|
||||||
{
|
{
|
||||||
"id": 123,
|
"id": 123,
|
||||||
|
"secondaryId": "field_abc123",
|
||||||
"type": "SIGNATURE",
|
"type": "SIGNATURE",
|
||||||
|
"recipientId": 1,
|
||||||
|
"envelopeId": "envelope_abc123xyz",
|
||||||
|
"envelopeItemId": "envelope_item_xyz",
|
||||||
"page": 1,
|
"page": 1,
|
||||||
"positionX": "10",
|
"positionX": "10",
|
||||||
"positionY": "80",
|
"positionY": "80",
|
||||||
"width": "30",
|
"width": "30",
|
||||||
"height": "5",
|
"height": "5",
|
||||||
"recipientId": 1
|
"customText": "",
|
||||||
|
"inserted": false,
|
||||||
|
"fieldMeta": null
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"envelopeItems": [
|
"envelopeItems": [
|
||||||
{
|
{
|
||||||
"id": "envelope_item_xyz",
|
"id": "envelope_item_xyz",
|
||||||
|
"envelopeId": "envelope_abc123xyz",
|
||||||
|
"documentDataId": "doc_data_abc123",
|
||||||
"title": "contract.pdf",
|
"title": "contract.pdf",
|
||||||
"order": 1
|
"order": 1
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
|
"directLink": null,
|
||||||
|
"team": {
|
||||||
|
"id": 1,
|
||||||
|
"url": "your-team"
|
||||||
|
},
|
||||||
|
"user": {
|
||||||
|
"id": 1,
|
||||||
|
"name": "Jane Smith",
|
||||||
|
"email": "jane@example.com"
|
||||||
|
},
|
||||||
"documentMeta": {
|
"documentMeta": {
|
||||||
"subject": "Please sign this document",
|
"subject": "Please sign this document",
|
||||||
"message": "Hi, please review and sign this agreement.",
|
"message": "Hi, please review and sign this agreement.",
|
||||||
|
|||||||
Reference in New Issue
Block a user