---
title: "Documents, doc groups, and templates"
url: "https://docs.signnow.com/docs/entities"
type: "page"
section: "Documentation"
slug: "entities"
---
# Documents, doc groups, and templates
## About documents, document groups, and templates
In SignNow, you can work with the following entities:
- [Document](/docs/reference): a file with one or more pages that can contain fields.
- [Document group](/docs/reference) (DG): a set of documents sent to signers simultaneously.
- [Document template](/docs/reference): a template that is used to generate multiple documents. Use [bulk invite](/docs/template/operations/bulk-invite) to send invites with uniform documents to multiple signers simultaneously.
- [Document group template](/docs/reference) (DGT): a template that is used to generate multiple document groups.
## Work with documents, document groups, and templates
### Step 1. Upload document
There are three ways to upload a document:
- [Upload](/docs/document/operations/upload-document) a document from your computer.
```bash
curl --request POST \
--url https://api.signnow.com/document \
--header 'Authorization: Bearer {{access_token}}' \
--form file=@/path/to/your/file.pdf
```
- [Upload](/docs/document/operations/post-v2-documents-url) a document from a URL.
```bash
curl --request POST \
--url https://api.signnow.com/v2/documents/url \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
"url": "https://file.com"
}'
```
- [Upload](/docs/document/operations/upload-document-with-text-tags) a document with text tags. This way, your document will contain fields immediately after upload. Otherwise, you need to add fields with a separate request.
```bash
curl --request POST \
--url https://api.signnow.com/document/fieldextract \
--header 'Authorization: Bearer {{access_token}}' \
--form file= \
--form Tags= \
--form 'Tags[]:tag_name='
```
If you are trying to upload a document using Postman Web, you might encounter the **Must upload one file** error.
To fix the error
1. On the bottom right, click **Auto-select agent**.
2. Turn off **Auto select**.
3. Select **Desktop Agent**.
4. Download the Desktop Agent.
5. Open your default Download directory and start the Agent by opening the file.
6. Send the upload document request again.
### Step 2. Add fields
This step is optional. You can send invites for the documents without fields using a [freeform invite](/docs/document-field-invite/operations/post-field_invite). To send documents with fields, use a [field invite](/docs/document-field-invite/operations/post-field_invite).
Use the [Edit document](/docs/request-payments/operations/put-document-document_id) request to add fields. In this example, text and signature fields are added to a document. You can also add fields to a template.
```bash
curl --request PUT \
--url https://api.signnow.com/document/{{document_id}} \
--header 'Authorization: Bearer {{access_token}}' \
--data '{
"fields": [
{
"type": "text",
"required": true,
"role": "Signer 1",
"x": 350,
"y": 170,
"height": 25,
"width": 100,
"page_number": 0
},
{
"type": "signature",
"required": true,
"role": "Signer 1",
"x": 350,
"y": 210,
"height": 25,
"width": 100,
"page_number": 0
}
]
}'
```
### Step 3. Create template from document
Create a template when the same document goes to many signers. You prepare the fields and roles once, then generate a fresh document for each signer instead of uploading the file and placing fields every time.
Use the [Create template](/docs/template/operations/create-template) request to create a template from a document.
In the payload, use the ID of the document from which the template is generated. The ID can be found in the [Upload document](/docs/document/operations/upload-document) response.
```bash
curl --request POST \
--url https://api.signnow.com/template \
--header 'Authorization: Bearer {{access_token}}' \
--data '{
"document_name": "Non-disclosure Agreement",
"document_id": "3e7a1c85d0b24f69ae53c81b7d40f92c6ba85e13"
}'
```
### Step 4. Generate document from template
Use the [Create document from template](/docs/template/operations/get-template-copy) request to generate a document from the template. `document_name` in the payload is optional. If not added, the document name will be the same as the template name.
```bash
curl --request POST \
--url https://api.signnow.com/template/{{template_id}}/copy \
--header 'Authorization: Bearer {{access_token}}' \
--data '{
"document_name": "Non-disclosure Agreement HR"
}'
```
### Step 5. Send the document for signature
Templates are masters for generating copies: recipients sign a document generated from the template. Send the document generated in **Step 4**, or the one you uploaded in **Step 1**. To reach many signers from a single template at once, use [Bulk invite](/docs/template/operations/bulk-invite), which generates a document per signer.
> **Note**: The generated document keeps the template's fields, positions, and role names, but its document ID, field IDs, and role IDs are all newly generated and differ from the template's. Because role names are preserved, addressing recipients by `role` avoids a lookup. Build the invite from the ID returned in **Step 4**, and if you prefer `role_id`, take the current IDs from the [Get document](/docs/document/operations/get-document) response for the generated document, not the template.
Use the [Create field invite](/docs/document-field-invite/operations/post-field_invite) request to invite recipients by email. For signing order, reminders, expiration, and recipient authentication, see [Send a document for signature](/docs/invite-to-sign#send-a-document-for-signature).
```bash
curl --request POST \
--url https://api.signnow.com/document/{{document_id}}/invite \
--header 'Authorization: Bearer {{access_token}}' \
--data '{
"to": [
{
"email": "signer@email.com",
"role": "Signer 1",
"order": 1
}
],
"from": "sender@email.com",
"subject": "Please sign the Non-disclosure Agreement",
"message": "Review the agreement and add your signature."
}'
```
> **Note**: `subject` and `message` are optional. Customizing them requires a paid API plan, an API free trial, or a Site License. Without one, the request fails with `Upgrade your subscription plan to personalize invite subject and message.` (code `65582`). Remove both fields to send the invite with the default subject and message. See [API errors](/docs/api-errors).
### Step 6. Create document group
To [create](/docs/document-group/operations/create-document-group) a document group, you need the IDs of all the documents that should be a part of the group. The `group_name` attribute is required.
Every document in the group must:
- be owned by the account creating the group
- not be a template
- not already belong to another document group
- have no active or fulfilled invites
> **Note**: The last condition means you cannot group the document you already sent in **Step 5**. Start the document group track from documents that have not been sent.
```bash
curl --request POST \
--url https://api.signnow.com/documentgroup \
--header 'Authorization: Bearer {{access_token}}' \
--data '{
"document_ids": [
"8b0d47e9c2a5416fb93e05d18c7a2f64e0d3b915",
"c19f6a03e58d47b2814ca7de06f395b8d271ea40"
],
"group_name": "Non-disclosure agreements"
}'
```
### Step 7. Create document group template
A document group template does the same for a set of documents: prepare the group once, then generate a copy of the whole set for each signer.
To [create](/docs/document-group-template/operations/post-v2-document-groups-document_group_uid-document-group-template) a document group template, you need the document group ID, which can be found in the [Create document group](/docs/document-group/operations/create-document-group) response.
`name` in the payload is required and must contain a name for the template. `folder_id` is optional and, if used, must contain the ID of the Templates folder or its subfolder. By default, the document group template is saved to the Templates folder.
```bash
curl --request POST \
--url https://api.signnow.com/v2/document-groups/{{document_group_id}}/document-group-template \
--header 'Authorization: Bearer {{access_token}}' \
--data '{
"name": "Non-disclosure agreements",
"folder_id": "5d82b0f4a91c48e7b60d3ac295f17e84c0b6d321"
}'
```
By creating a document group template, you also generate document templates from each document in the group.
### Step 8. Create document group from template
To [create](/docs/document-group-template/operations/post-v2-document-group-templates-unique_id-document-group) a document group from a document group template, you need the template ID. You can find it in the [Get document group templates](/docs/document-group-template/operations/get-user-documentgroup-templates) response or your SignNow account:
1. Open the folder that contains the template.
2. Next to the document group template, click .
3. Scroll down the options, click **Copy Id**, and click .
`group_name` in the payload is required and must contain a name for the document group.
```bash
curl --request POST \
--url https://api.signnow.com/v2/document-group-templates/{{dgt_id}}/document-group \
--header 'Authorization: Bearer {{access_token}}' \
--data '{
"group_name": "Non-disclosure Agreements US",
"client_timestamp": "4562325644",
"folder_id": "6e13d9a75c0b42f8ae94b12d7c58e03f9a41b6d2"
}'
```
### Step 9. Send the document group for signature
Document group templates work the same way: generate a document group from the template, then send that group. The documents inside the generated group have new IDs, different from the ones in the template, so take them from the **Step 8** response or from [Get document group info](/docs/document-group/operations/get-document-group-info-v2).
Use the [Create group invite](/docs/doc-group-field-invite/operations/invite-to-sign-document-group) request. For signing order, SMS delivery, reminders, expiration, and recipient authentication, see [Send a document group for signature](/docs/invite-to-sign#send-a-document-group-for-signature).
```bash
curl --request POST \
--url https://api.signnow.com/documentgroup/{{document_group_id}}/groupinvite \
--header 'Authorization: Bearer {{access_token}}' \
--data '{
"invite_steps": [
{
"order": 1,
"invite_emails": [
{
"email": "signer@email.com",
"subject": "Please sign the Non-disclosure Agreements",
"message": "Review the documents and add your signature."
}
],
"invite_actions": [
{
"email": "signer@email.com",
"role_name": "Signer 1",
"action": "sign",
"document_id": "0a5c9e14b7d3428fa6c81e2d5b09f3746ce8d215"
}
]
}
]
}'
```
> **Note**: As with the field invite in **Step 5**, custom `subject` and `message` values require a paid API plan, an API free trial, or a Site License. Remove both fields to use the defaults.
## Other ways to send
- [Embedded signing](/docs/guides-embedded-signing): recipients sign inside your own site or app instead of on the SignNow site. [Sign PDFs in WordPress](/docs/sign-pdfs-in-wordpress) walks through the full document group template to embedded signing sequence.
- [Bulk invite](/docs/template/operations/bulk-invite): generate a document per signer from one template and send them all at once.
- [Freeform invite](/docs/document-field-invite/operations/post-field_invite): send a document that has no fields, and let the recipient place their signature.
## Document group history events
Retrieve the full history for a specific document group using [`GET /documentgroup/{{document_group_id}}/historyfull`](/docs/document-group/operations/get-documentgroup-document_group_id-historyfull).
The response contains information about all events that occurred to the document group.
**View the complete list of document group events:
**
| **Event name** | **Meaning** |
| --- | --- |
| `document_group_created` | The document group was created. |
| `document_group_user_logged_in` | A user logged in during interaction with the document group. |
| `document_group_viewed` | The document group was viewed. |
| `document_group_approved` | The document group was approved. |
| `document_group_signed` | The document group was signed. |
| `document_group_sign_owner_attachment_sent` | The completed document group was sent to the owner as an attachment. |
| `document_group_sign_signer_attachment_sent` | The completed document group was sent to the signer as an attachment. |
| `document_group_downloaded` | The document group was downloaded. |
| `document_group_invite_sent` | The document group invite was sent. |
| `document_group_invite_resend` | The document group invite was resent. |
| `document_group_invite_completed` | The document group invite was completed. |
| `document_group_invite_cancelled` | The document group invite was cancelled. |
| `document_group_invite_full_declined` | The document group invite was declined by all recipients. |
| `document_group_invite_approver_full_declined` | The document group invite was declined by all approvers. |
| `document_group_fieldinvite_declined` | The document group field invite was declined. |
| `document_group_freeform_invite_sent` | A freeform invite for the document group was sent. |
| `document_group_freeform_invite_resend` | A freeform invite for the document group was resent. |
| `document_group_freeform_invite_cancelled` | A freeform invite for the document group was cancelled. |
| `document_group_freeform_invite_signed_by_user` | A recipient signed a freeform invite for the document group. |
| `document_group_freeform_invite_completed` | A freeform invite for the document group was completed. |
| `document_group_freeform_sign_owner_attachment_sent` | The document group signed in a freeform invite was sent to the owner. |
| `document_group_freeform_sign_signer_attachment_sent` | The document group signed in a freeform invite was sent to the signer. |
| `document_group_authentication_success` | A document group signer successfully passed authentication. |
| `document_group_authentication_failure` | A document group signer failed to pass authentication. |
| `document_group_approver_authentication_success` | A document group approver successfully passed authentication. |
| `document_group_approver_authentication_failure` | A document group approver failed to pass authentication. |
| `document_group_correction_start` | A correction process started for the document group. |
| `document_group_correction_finish` | A correction process finished for the document group. |
## Try out in Postman
[Access](https://www.postman.com/signnow-api/signnow-public-collection/collection/xjaao4f/signnow-documents-docgroups-and-templates-test-collection) this flow in Postman, and feel free to use documents, document groups, and templates in your workflows.
---
*Full page: https://docs.signnow.com/docs/entities*