---
title: "Invite to sign"
url: "https://docs.signnow.com/docs/invite-to-sign"
type: "page"
section: "Documentation"
slug: "invite-to-sign"
---
# Invite to sign
# About Invite to sign
Using the SignNow API, you can invite people to sign one document or multiple documents as a document group. The SignNow API allows you to work with different types of invites.
## Types of paid signature invites and how they are charged
| Invite type | Description | Charging |
| --------------------------- | --------------------------- | -----|
| [**Document field invite**](/docs/document-field-invite/operations/post-field_invite)
[Document group field invite](/docs/doc-group-field-invite/operations/invite-to-sign-document-group) | An Invite to sign a document is sent via email. The document has fields that need to be completed. The invite is role-based: you can set up a multi-step process with different people processing a document at different steps. | Charging applies per invite sent. If multiple signers are included in one invite, it counts as a single invite. |
| [**Document freeform invite**](/docs/document-field-invite/operations/post-field_invite)
[Document group freeform invite](/docs/doc-group-freeform-invite/operations/post-v2-document-groups-document_group_id-free-form-invites) | An Invite to sign a document is sent via email. The document doesn’t have fields and signers can add their signature anywhere in the document. | **For a document**: You can add one signer per invite. Charging applies per invite sent. If you send a freeform invite to multiple signers, each invite is charged separately.
**For a document group**: You can add multiple signers in a single invite. Charging applies per invite sent. |
| [**Document invite via SMS**](/docs/document-field-invite/operations/post-field_invite)
[Document group invite via SMS](/docs/doc-group-field-invite/operations/invite-to-sign-document-group) | An Invite to sign a document or a document group is sent via SMS. The SMS contains a link to the document or document group. Different signers of one invite can receive it by email or SMS.
See also: [SMS invite guide](/docs/sms-invite) | Charging applies per invite sent. If multiple signers are included in one invite, it counts as a single invite. |
| [**Document signing link**](/docs/signing-link/operations/post-v2-document-group-document_group_id-signing-links)
[Document group signing link](/docs/signing-link/operations/post-v2-document-group-document_group_id-signing-links) | A link to the document that needs a signature is generated. | Charging applies when the last signer completes the signing process (if there is more than one signer). |
| [**Bulk invite**](/docs/template/operations/bulk-invite) | Invites to sign a document are sent to multiple signers simultaneously. The document is generated from a [template](/docs/template/operations/create-template). | Charging applies per invite sent (for each record in the CSV file, which contains signers' roles, emails, and document names).|
| [**Document embedded invite**](/docs/document-embedded-signing/operations/create-embedded-signing-invite)
[Document group embedded invite](/docs/doc-group-embedded-signing/operations/create-embedded-invite-document-group) | A link to sign a document is generated and you can embed it into your website.
See also: [Embedded signing guide](/docs/guides-embedded-signing) | Charging applies per invite sent (via a link or email), even if multiple signers are included in one invite. |
> Check your application's signature invite usage in the [API dashboard](https://app.signnow.com/webapp/api-dashboard/plan-usage/invite-logs).
In this guide, we will walk you through the process of sending your first [**document field invite**](/docs/document-field-invite/operations/post-field_invite) and a **[document group field invite](/docs/doc-group-field-invite/operations/invite-to-sign-document-group)** via the API.
## Send a document for signature
We will send the purchase agreement to three recipients with different roles:
- Buyer (can sign the agreement)
- Seller (can sign the agreement)
- Approver (can review and approve the agreement)
## Before you begin
Before creating your field invite to sign a document, make sure that you have the following data:
- **Document ID** or **template ID**: you can find it in the [SignNow UI](https://app.signnow.com/webapp/documents). Next to the document or template, click the three-dotted button and **click Copy ID**. Document ID and template ID are 40 characters long and consist of lower-case letters and digits. Example: c4aff212145b40888cd75e3c73c978484258c043.
- **Signer email address** or addresses: who needs to sign a document.
- **Role**: a unique role name that can be found in the response of the [Get document](/docs/document/operations/get-document) endpoint. Example:
Signer 1.
- **Role ID**: a unique role identifier that can be found in the response of the [Get document](/docs/document/operations/get-document) endpoint. Role ID is 40 characters long and consists of lower-case letters and digits. Example: 6e9580fa76ba4edca18fa6e680a36d10a6bab503. You need either a role or role ID but you can use both. If you use both, make sure that role and role ID correspond.
- **Order**: an integer that defines the order of signing in a document. The first recipient will have ‘order=1’, the second will have ‘order=2’, and so on. Several recipients can have the same order of signing. In this case, they will receive invites at the same time, and all of them need to sign the document before the invites for the next step are sent.
- **From**: an email address of the API account from which you sent an invite.
If you want to customize other settings of an invite, you may need more data. For more information, see [Send field invite request body](/docs/document-field-invite/operations/post-field_invite#request-body).
### Step 1. Authentication
Get a Basic Authorization Token from the [API Dashboard](/docs/account) and request a Bearer token. To get authorization for other requests, you’ll need to use your Bearer token.
For more information, see [Authentication](/docs/authentication).
```bash
curl -- POST \
--url https://api.signnow.com/oauth2/token \
--header 'Authorization: Basic {{basic_authorization_token}}' \
--header 'content-type: multipart/form-data' \
--header 'username=username@signnow.com' \
--header 'password=testpass' \
--header 'grant_type=password' \
--header 'scope=*'
```
### Step 2. Upload document
If you already have a document in your account, you can skip this step. Otherwise, you can upload one via the API and copy the document ID from the response. SignNow supports the following file formats: .pdf, .doc, .docx, .odt, .rtf, .png, .jpg, .jpeg, .gif, .bmp, .xml, .xls, .xlsx, .ppt, .pptx, .ps, and .eps.
> **Note**: You can send your Invite to sign a document only if you own the document.
For more information, see [Upload document](/docs/document/operations/upload-document).
```bash
curl --request POST \
--url https://api.signnow.com/document \
--header 'Authorization: Bearer {{access_token}}' \
--header 'content-type: multipart/form-data' \
--form 'file=@/path/to/your/document/Purchase_agreement.pdf'
```
### Step 3. Add roles and fields
Next, you need to add fields to your document.
In this example, we will add two text fields and two signature fields to the document: one text field and one signature field for the seller; one text field and one signature field for the buyer. We will set specific locations for the fields.
To create a field, you need to include the following data in the request:
- Coordinates of the field position on a page.
- Number of the page.
- Width and height of the field.
- Field label.
- Role that is associated with the field.
- Field type (signature, text, enumeration (dropdown), radio button, checkbox, initials, attachment, hyperlink, and stamp).
- Pre-filled text that appears in the field when the signer opens the document.
- Whether the field is required or not.
For more information, see [Edit document](/docs/request-payments/operations/put-document-document_id).
```bash
curl --request PUT \
--url https://api.signnow.com/document/{{document_id}} \
--header 'Authorization: Bearer {{access_token}}'\
--header 'Content-Type: application/json' \
--data '{
"fields": [
{
"type": "text",
"role": "Buyer",
"page_number": 0,
"x": 11,
"y": 691,
"width": 83,
"height": 11,
"required": true,
"name": "buyer_name",
"color": "000000",
"bold": false,
"italic": false,
"underline": false,
"align": "left",
"font": "Arial",
"max_lines": 0,
"max_chars": 0,
"arrangement": "none",
"size": 12,
"valign": "top",
"font_size": 8
},
{
"type": "signature",
"role": "Buyer",
"page_number": 0,
"x": 125,
"y": 708,
"width": 83,
"height": 11,
"required": true,
"name": "signature_buyer",
"allowed_types": [
"type",
"draw",
"upload"
]
},
{
"type": "text",
"role": "Seller",
"page_number": 0,
"x": 111,
"y": 648,
"width": 83,
"height": 11,
"required": true,
"name": "seller_name",
"color": "000000",
"bold": false,
"italic": false,
"underline": false,
"align": "left",
"font": "Arial",
"max_lines": 0,
"max_chars": 0,
"arrangement": "none",
"size": 12,
"valign": "top",
"font_size": 8
},
{
"type": "signature",
"role": "Seller",
"page_number": 0,
"x": 125,
"y": 664,
"width": 83,
"height": 11,
"required": true,
"name": "signature_seller",
"allowed_types": [
"type",
"draw",
"upload"
]
}
]
}'
```
### Step 4. Get roles
Make a [Get document](/docs/document/operations/get-document) request to retrieve existing roles in the document.
Role names and role IDs are listed in the `roles` array (for signers); `viewer_roles` for viewers, and `approver_roles` for approvers.
You need either a role or role ID but you can use both. If you use both, make sure that the role and role ID correspond.
```json
{
"roles": [
{
"unique_id": "XXXXebd3947e418fb7fac25909a9733c2d44927a",
"signing_order": "1",
"name": "Buyer"
},
{
"unique_id": "XXXXfc5a63b84784a634f5a7f45ddb3c0dcb5a18",
"signing_order": "2",
"name": "Seller"
}
],
"viewer_roles": [],
"approver_roles": [
{
"unique_id": "XXXXebd3947e418fb7fac25909a9733c2d44929a",
"signing_order": "3",
"name": "Approver"
}
]
}
```
> **Note**: All roles in the document must be assigned to recipients in the invite.
> The approver and viewer roles are displayed only when the document has been sent for signature.
### Step 5. Create and send an Invite to sign a document
In this example, we will send an invite to:
- Buyer (can fill out and sign the document)
- Seller (can fill out and sign the document)
- Approver (can review and approve/decline the document)
When sending an invite, assign actions to roles.
- Recipients in the `to` array can fill out and sign the document.
- Recipients in the `approvers` array can review and approve/decline the document.
- Recipients in the `viewers` array can review the document.
> The approver role requires the signing order to be enabled. If the approver declines the document, it will not proceed to the next recipient. The approver cannot be assigned to the same step as other recipients.
For request body details, see [Send field invite](/docs/document-field-invite/operations/post-field_invite#request-body).
```bash
curl --request POST \
--url https://api.signnow.com/document/{{document_id}}/invite \
--header 'Authorization: Bearer {{access_token}}'\
--header 'Content-Type: application/json' \
--data '{
"to": [
{
"email": "buyer@email.com",
"role": "Buyer",
"order": 1,
"prefill_signature_name": "Enter your name",
"force_new_signature": 1,
"reassign": "0",
"decline_by_signature": "0",
"reminder": {
"remind_after": 3,
"remind_repeat": 7
},
"expiration_days": 30,
"authentication_type": "password",
"password": "123456",
"subject": "Review and sign the agreement",
"message": "Hi, this is an invite to sign the purchase agreement.",
"redirect_uri": "https://example.com",
"decline_redirect_uri": "https://signnow.com",
"close_redirect_uri": "https://close-redirect-uri.com",
"redirect_target": "blank"
},
{
"email": "seller@email.com",
"role": "Seller",
"order": 2,
"prefill_signature_name": "Enter your name",
"force_new_signature": 1,
"reassign": "0",
"decline_by_signature": "0",
"reminder": {
"remind_after": 3,
"remind_repeat": 7
},
"expiration_days": 30,
"authentication_type": "password",
"password": "123457",
"subject": "Review and sign the agreement",
"message": "Hi, this is an invite to sign a purchase agreement.",
"redirect_uri": "https://example.com",
"decline_redirect_uri": "https://signnow.com",
"close_redirect_uri": "https://close-redirect-uri.com",
"redirect_target": "blank"
}
],
"from": "sender@email.com",
"cc": [
"cc_recipient1@email.com",
"cc_recipient2@email.com"
],
"approvers": [
{
"email": "approver@email.com",
"role": "Approver",
"order": 3,
"expiration_days": 30,
"authentication_type": "password",
"password": "123458",
"subject": "Review and approve the agreement",
"message": "Hi, this is an invite to review and approve the purchase agreement.",
"redirect_uri": "https://example.com",
"redirect_target": "blank"
}
]
}'
```
### Try out in Postman
[Access](https://www.postman.com/signnow-api/workspace/signnow-public-collection/collection/24778743-37617332-7338-4b63-8134-e1b80cda04b7) this flow in Postman, and feel free to use field-based invites to sign a document in your workflow.
## Send a document group for signature
Now, we will send a document group (containing the purchase agreement and invoice) to four recipients:
- Buyer (can `sign` the purchase agreement)
- Seller (can `sign` the purchase agreement)
- Approver (can review and `approve` the purchase agreement and invoice )
- Viewer (can `view` the purchase agreement)
We will start with creating a document group.
### Step 1. Create a document group
Use the [Create a document group](/docs/document-group/operations/create-document-group) request to organize documents in your SignNow account into a group.
In the example, we will add two documents to the group: the purchase agreement and the invoice. Add the document IDs to the request body.
```bash
curl --request POST \
--url https://api.signnow.com/documentgroup \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
"document_ids": [
"XXXXXX6dc7d3430ba89514667ce4f32da7b33f76",
"YYYY37a5dc3d47c4ba574a86b573a0562a07cc77"
],
"group_name": "Purchase agreement package"
}'
```
The response retrieves the document group ID.
> You can retrieve the document IDs in your SignNow account by clicking **More** **(...)** next to the document and selecting **Copy Id** in the dropdown. Alternatively, retrieve the document ID from the response when [uploading the document](/docs/document/operations/upload-document).
### Step 2. Add roles and fields to documents
Add fields to each document from the group and assign fields to roles using the [Edit document](/docs/request-payments/operations/put-document-document_id) request as described in [Step 3](/docs/invite-to-sign#step-3-add-roles-and-fields) for the document invite.
### Step 3. Get roles
You can assign roles to document recipients and define the action each role can perform in the document.
The available actions are:
- `sign`: The recipient can sign or fill out the document.
- `approve`: The recipient can review the document to approve or decline it.
- `view`: The recipient can only review the document without making changes.
Use the [Get doc group info](/docs/document-group/operations/get-document-group-info-v2) or [Get doc group recipients](/docs/doc-group-field-invite/operations/get-v2-document-groups-document_group_id-recipients) request to retrieve existing roles in the document group.
You can create new roles and assign action to each role in the next step.
### Step 4. Create and send an Invite to sign a document group
We will send the document group to four recipients using the [Invite to sign doc group](/docs/doc-group-field-invite/operations/invite-to-sign-document-group) request.
Among recipients are:
- Buyer (can `sign` the purchase agreement)
- Seller (can `sign` the purchase agreement)
- Approver (can review and `approve` the purchase agreement and invoice )
- Viewer (can `view` the purchase agreement)
Use the `invite_actions` array to define what action each recipient can perform with the document (`sign`, `approve`, `view`).
> **Note**: Recipients can also receive the document group invite by SMS, and you can combine email and SMS recipients in a single invite. For more information, see the [SMS invite guide](/docs/sms-invite).
For request body details, see [Invite to sign doc group](/docs/doc-group-field-invite/operations/invite-to-sign-document-group).
> The approver role requires the signing order to be enabled. If the approver declines the document, it will not proceed to the next recipient. The approver cannot be assigned to the same step as other recipients. Approve action must be assigned to all documents in the document group.
```bash
curl --location 'https://api.signnow.com/documentgroup/{{document_group_id}}/groupinvite' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"invite_steps": [
{
"order": 1,
"invite_emails": [
{
"email": "buyer@email.com",
"subject": "Review and sign documents",
"message": "Please reach out with any questions.",
"expiration_days": 30,
"reminder": {
"remind_after": 3,
"remind_repeat": 7,
"remind_before": 5
}
}
],
"invite_actions": [
{
"email": "buyer@email.com",
"role_name": "Buyer",
"action": "sign",
"document_id": "XXXXXX6dc7d3430ba89514667ce4f32da7b33f76",
"allow_reassign": "0",
"decline_by_signature": "0",
"redirect_uri": "https://example.com",
"decline_redirect_uri": "https://signnow.com",
"close_redirect_uri": "https://close-redirect-uri.com",
"redirect_target": "blank",
"allow_forwarding": false,
"i_am_recipient": false,
"show_decline_button": true,
"authentication": {
"type": "password",
"value": "1233456"
}
}
]
},
{
"order": 2,
"invite_emails": [
{
"email": "seller@email.com",
"subject": "Review and sign documents",
"message": "Please reach out with any questions.",
"expiration_days": 30,
"reminder": {
"remind_after": 3,
"remind_repeat": 7,
"remind_before": 5
}
}
],
"invite_actions": [
{
"email": "seller@email.com",
"role_name": "Seller",
"action": "sign",
"document_id": "XXXXXX6dc7d3430ba89514667ce4f32da7b33f76",
"allow_reassign": "0",
"decline_by_signature": "0",
"redirect_uri": "https://example.com",
"decline_redirect_uri": "https://signnow.com",
"close_redirect_uri": "https://close-redirect-uri.com",
"redirect_target": "blank",
"allow_forwarding": false,
"i_am_recipient": false,
"show_decline_button": true,
"authentication": {
"type": "password",
"value": "1233456"
}
}
]
},
{
"order": 3,
"invite_emails": [
{
"email": "approver@email.com",
"subject": "Review and approve documents",
"message": "Please reach out with any questions.",
"expiration_days": 30
}
],
"invite_actions": [
{
"email": "approver@email.com",
"role_name": "Approver",
"action": "approve",
"document_id": "XXXXXX6dc7d3430ba89514667ce4f32da7b33f76",
"authentication": {
"type": "password",
"value": "1233456"
}
},
{
"email": "approver@email.com",
"role_name": "Approver",
"action": "approve",
"document_id": "YYYY37a5dc3d47c4ba574a86b573a0562a07cc77",
"authentication": {
"type": "password",
"value": "1233456"
}
}
]
},
{
"order": 4,
"invite_emails": [
{
"email": "viewer@email.com",
"subject": "Review documents",
"message": "Please reach out with any questions."
}
],
"invite_actions": [
{
"email": "viewer@email.com",
"role_name": "Viewer",
"action": "view",
"document_id": "XXXXXX6dc7d3430ba89514667ce4f32da7b33f76"
}
]
}
],
"completion_emails": [],
"sign_as_merged": true,
"cc": [
"cc_recipient1@email.com",
"cc_recipient2@email.com"
],
"cc_subject": "Review documents",
"cc_message": "Please reach out with any questions."
}'
```
The successful request sends the document group to recipients in the defined order.
### Try out in Postman
[Access](https://www.postman.com/signnow-api/signnow-public-collection/folder/aq00hn5/document-group-invite?action=share&source=copy-link&creator=23914423&ctx=documentation) this flow in Postman, and feel free to use field-based invites to sign a document group in your workflow.
---
*Full page: https://docs.signnow.com/docs/invite-to-sign*