---
title: "Edit doc group recipients"
url: "https://docs.signnow.com/docs/doc-group-field-invite/operations/put-v2-document-groups-document_group_id-recipients"
type: "endpoint"
section: "doc-group-field-invite"
slug: "doc-group-field-invite/operations/put-v2-document-groups-document_group_id-recipients"
method: "PUT"
path: "/v2/document-groups/{document_group_id}/recipients"
operation_id: "put-v2-document-groups-document_group_id-recipients"
authorization: "bearer"
---

# Edit doc group recipients

`PUT /v2/document-groups/{document_group_id}/recipients`

This endpoint allows users to add or remove document group recipients. Users can edit recipients' emails, roles and role actions, signing order, CC recipients, and more. 

You cannot edit recipients for a document group with an active signature invite.

> To pre-fill recipients' information when sending an invite, `name` must match `role`.

**Recipients and roles in document groups**

- The same email address can have multiple roles in a document group — for example, if the recipient acts as "Agent" in one document and "Manager" in another.
- The API creates a separate entry for each role, so the same email address may appear multiple times in the response.

**Example:** If recipient@example.com is assigned as "Agent" in Document A and "Manager" in Document B, the response will contain two separate entries for recipient@example.com — one per role.

**Mapping tip:** When mapping recipients in your integration, group by email address rather than by role name.

## Authorization

bearer

## Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `document_group_id` | string | Yes | ID of the document group. |

## Request Body

**Schema**

```json
{
  "type": "object",
  "required": [
    "recipients"
  ],
  "properties": {
    "cc": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "List of email addresses for CC recipients."
    },
    "order_type": {
      "enum": [
        "at_the_same_time",
        "recipient_order",
        "advanced_order",
        null
      ],
      "type": "string",
      "x-nullable": true,
      "description": "Recipient routing rule applied to all recipients in the invite. `at_the_same_time` - all at once; `recipient_order` - sequential by `order` parameter; `advanced_order` - advanced rules."
    },
    "recipients": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "name",
          "order",
          "documents"
        ],
        "properties": {
          "name": {
            "type": "string",
            "example": "Signer",
            "maxLength": 255,
            "description": "Recipient's name."
          },
          "email": {
            "type": "string",
            "example": "signer@email.com",
            "description": "Recipient's email address."
          },
          "order": {
            "type": "integer",
            "example": 1,
            "maximum": 27,
            "minimum": 1,
            "description": "Order of receiving the document group invite."
          },
          "documents": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "role",
                "action"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "example": "b12e4a885b513a6d9c4c2e7c2b7fa06a013aYYYY",
                  "description": "Document ID."
                },
                "role": {
                  "type": "string",
                  "example": "Signer",
                  "description": "Recipient's role name."
                },
                "action": {
                  "type": "string",
                  "example": "sign",
                  "description": "Allowed action with a document. Possible values:\u00a0`view`,\u00a0`sign`,`approve`."
                }
              }
            },
            "description": "List of documents, recipient roles, and allowed actions. Should contain at least one document."
          },
          "attributes": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string",
                "example": "{fullName} shared {documentName} for signing.",
                "description": "Invite email message. Supports {documentName} and {fullName} placeholders.",
                "x-stoplight": {
                  "id": "qan1mztdutmy8"
                }
              },
              "subject": {
                "type": "string",
                "example": "Review and sign {documentName}",
                "description": "Invite email subject. Supports {documentName} and {fullName} placeholders.",
                "x-stoplight": {
                  "id": "y9twpi8sfo304"
                }
              },
              "reminder": {
                "type": "object",
                "properties": {
                  "remind_after": {
                    "type": "integer",
                    "example": 5,
                    "description": "Send the reminder email to the recipient after the set amount of days. `remind_after` must be less than `expiration_days`.",
                    "x-stoplight": {
                      "id": "aooht17ng8icb"
                    }
                  },
                  "remind_before": {
                    "type": "integer",
                    "example": 5,
                    "description": "Send the reminder email to the recipient in a set amount of days before the invite expiration. `remind_before` must be less than `expiration_days`.",
                    "x-stoplight": {
                      "id": "9qctgsiy7rifo"
                    }
                  },
                  "remind_repeat": {
                    "type": "integer",
                    "example": 5,
                    "description": "Send the reminder email to the recipient every set amount of days. `remind_repeat` must be less than `expiration_days`.",
                    "x-stoplight": {
                      "id": "el656mcqf80tg"
                    }
                  }
                },
                "description": "Reminder email settings. Available for `sign` action.",
                "x-stoplight": {
                  "id": "b33n1k6zzi15v"
                }
              },
              "redirect_uri": {
                "type": "string",
                "example": "https://www.signnow.com/",
                "description": "The link that opens after the signing session has been completed.",
                "x-stoplight": {
                  "id": "2l6u9ewl8ll6b"
                }
              },
              "authentication": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "example": "phone",
                    "description": "Type of the recipient authentication. Can be `phone` or `password`.\u200b\u200b Required inside the `authentication` object.",
                    "x-stoplight": {
                      "id": "9ae1zmcvpw34e"
                    }
                  },
                  "phone": {
                    "type": "string",
                    "example": "+12345678",
                    "description": "The phone number for the recipient's authentication. Required with type `phone`.",
                    "x-stoplight": {
                      "id": "9b4drjivktdud"
                    }
                  },
                  "value": {
                    "type": "string",
                    "example": "123456",
                    "description": "The password to unlock the document group. \nRequired inside the `authentication` object with the `password` authentication type.",
                    "x-stoplight": {
                      "id": "hsd4byyqurb2o"
                    }
                  },
                  "method": {
                    "type": "string",
                    "example": "phone_call",
                    "description": "Phone authentication type. Required inside the `authentication` object with the `phone` authentication type. Allowed values: `sms`, `phone_call`.",
                    "x-stoplight": {
                      "id": "u31vc46s7v1xo"
                    }
                  },
                  "sms_message": {
                    "type": "string",
                    "example": "Enter the password {password} to unlock your document.",
                    "description": "Custom SMS message sent to the recipient, containing the {password} placeholder. Used with the `sms` method. Without this parameter, the signer receives a default SMS with an autogenerated password (unlock code): \u201cSignNow document invite unlock code: 123456.\u201d",
                    "x-stoplight": {
                      "id": "vgfizr1ipgdw5"
                    }
                  }
                },
                "description": "Recipient authentication settings. Available for recipients with `sign` and `approve` actions. Can not be used when `allow_forwarding`is set to true.",
                "x-stoplight": {
                  "id": "8lox972m304ir"
                }
              },
              "i_am_recipient": {
                "type": "boolean",
                "description": "Set to `true` if the document sender is also a recipient. Available for `sign` action.",
                "x-stoplight": {
                  "id": "p4g1cvn49ad71"
                }
              },
              "expiration_days": {
                "type": "integer",
                "example": 10,
                "maximum": 180,
                "minimum": 3,
                "description": "Days until the invite expires. Available for `sign`and `approve` actions.",
                "x-stoplight": {
                  "id": "u8ik63srv3nju"
                }
              },
              "redirect_target": {
                "type": "string",
                "example": "blank",
                "description": "Determines whether to open the redirect link in the new tab in the browser, or in the same tab after the signing session. Possible values: `blank` - opens the link in the new tab, `self` - opens the link in the same tab.",
                "x-stoplight": {
                  "id": "sp2u7ayk1z0na"
                }
              },
              "allow_forwarding": {
                "type": "boolean",
                "description": "Whether recipients are allowed to reassign the invite to a different email address. Available for `sign` action.",
                "x-stoplight": {
                  "id": "x3wlb3chmc6fa"
                }
              },
              "close_redirect_uri": {
                "type": "string",
                "example": "https://www.signnow.com/",
                "description": "The link that opens when a signer clicks\u00a0**Save Progress and Finish Later**\u00a0during a signing session or\u00a0**Close**\u00a0in view mode. Available for `sign ` action.",
                "x-stoplight": {
                  "id": "uo3cjzscn2a3b"
                }
              },
              "show_decline_button": {
                "type": "boolean",
                "description": "Whether to show the Decline button on signatue fields. Available for `sign` action.",
                "x-stoplight": {
                  "id": "0p20nxgun6f1z"
                }
              },
              "decline_redirect_uri": {
                "type": "string",
                "example": "https://www.signnow.com/",
                "description": "The URL that opens after the recipient declines the document. Available for `sign` action.",
                "x-stoplight": {
                  "id": "uy9r0yvhyzc9w"
                }
              }
            },
            "description": "Signature invite attributes.",
            "x-stoplight": {
              "id": "ayx0tk19n5dzs"
            }
          },
          "email_group": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "example": "29XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
                "description": "ID of the email group.",
                "x-stoplight": {
                  "id": "jt1ghuxp7tk2b"
                }
              }
            },
            "description": "Group of recipients, such as a [CRM Contact group](/docs/contact-groups/operations/post-v2-crm-groups). Use either `email` or `email_group`, but not both simultaneously.",
            "x-stoplight": {
              "id": "yukislphhrr6x"
            }
          }
        }
      },
      "description": "List of document group recipients. Should contain at least one recipient."
    },
    "general_reminder": {
      "type": "object",
      "properties": {
        "remind_after": {
          "type": "integer",
          "description": "Days after invite is sent before a reminder is delivered. Must be less than `general_expiration_days`."
        },
        "remind_before": {
          "type": "integer",
          "description": "Days before expiration when a reminder is delivered. Must be less than `general_expiration_days`."
        },
        "remind_repeat": {
          "type": "integer",
          "description": "Days between repeated reminders."
        }
      },
      "x-nullable": true,
      "description": "Default `reminder` applied to all recipients in the invite."
    },
    "general_expiration_days": {
      "type": "integer",
      "maximum": 180,
      "minimum": 1,
      "x-nullable": true,
      "description": "Default `expiration_days` applied to all recipients in the invite. Min: `1`, Max: `180`. Default: `30`."
    }
  },
  "x-examples": {
    "Example 1": {
      "cc": [
        "test@test.com",
        "test2@test.com"
      ],
      "order_type": "recipient_order",
      "recipients": [
        {
          "name": "Recipient 1",
          "email": "emailtest@test.test",
          "order": 1,
          "documents": [
            {
              "id": "b12e4a885b513a6d9c4c2e7c2b7fa06a013a7412",
              "role": "Actor name",
              "action": "sign"
            },
            {
              "id": "b12e4a885b513a6d9c4c2e7c2b7fa06a013a74aa",
              "role": "Viewer name",
              "action": "view"
            }
          ],
          "attributes": {
            "message": "test message",
            "subject": "test subject",
            "reminder": {
              "remind_after": 10,
              "remind_before": 10,
              "remind_repeat": 10
            },
            "signature": {
              "type": "eideasy"
            },
            "redirect_uri": "https://redirect-uri.com",
            "authentication": {
              "type": "type",
              "phone": "phone number",
              "value": "value for the paas protection",
              "method": "method name"
            },
            "i_am_recipient": true,
            "expiration_days": 10,
            "allow_forwarding": true,
            "close_redirect_uri": "https://close-redirect-uri.com",
            "show_decline_button": true,
            "decline_redirect_uri": "https://decline-redirect-uri.com"
          },
          "phone_invite": null
        }
      ],
      "general_reminder": {
        "remind_after": 3,
        "remind_before": 5,
        "remind_repeat": 7
      },
      "unmapped_documents": [
        {
          "id": "b12e4a885b513a6d9c4c2e7c2b7fa06a013a749f",
          "role": "Actor name",
          "action": "sign"
        }
      ],
      "general_expiration_days": 30,
      "allowed_unmapped_sign_documents": [
        {
          "id": "b12e4a885b513a6d9c4c2e7c2b7fa06a013a749f",
          "role": "Actor name",
          "recipient": "Recipient 1"
        }
      ]
    }
  }
}
```

**Example** (`Request for editing document group recipients`)

```json
{
  "cc": [
    "viewer1@email.com",
    "viewer2@email.com"
  ],
  "order_type": "recipient_order",
  "recipients": [
    {
      "name": "Recipient 1",
      "order": 1,
      "documents": [
        {
          "id": "XXXXXXXXXe954e92beafca9460ce5f83b87db885",
          "role": "Recipient 1",
          "action": "sign"
        },
        {
          "id": "XXXXXXXXX0354d22997abef44232d7fbc60683e6",
          "role": "Recipient 1",
          "action": "sign"
        }
      ],
      "attributes": {
        "message": "test message",
        "subject": "test subject",
        "reminder": {
          "remind_after": 5,
          "remind_before": 5,
          "remind_repeat": 5
        },
        "redirect_uri": "https://www.signnow.com/",
        "authentication": {
          "type": "password",
          "value": "1233456"
        },
        "i_am_recipient": false,
        "expiration_days": 10,
        "allow_forwarding": false,
        "close_redirect_uri": "https://www.signnow.com/",
        "show_decline_button": true,
        "decline_redirect_uri": "https://www.signnow.com/"
      }
    },
    {
      "name": "Recipient 2",
      "email": "signer2@email.com",
      "order": 1,
      "documents": [
        {
          "id": "XXXXXXXXXe954e92beafca9460ce5f83b87db885",
          "role": "Recipient 2",
          "action": "sign"
        },
        {
          "id": "XXXXXXXXX0354d22997abef44232d7fbc60683e6",
          "role": "Recipient 2",
          "action": "view"
        }
      ]
    }
  ],
  "general_reminder": {
    "remind_after": 3,
    "remind_before": 5,
    "remind_repeat": 7
  },
  "general_expiration_days": 30
}
```

## Responses

### 200

Successfully updated document group recipients.

**Example** (`Example 1`)

```json
{
  "data": {
    "cc": [
      "test2@test.com",
      "test@test.com"
    ],
    "order_type": null,
    "recipients": [
      {
        "name": "Recipient 1",
        "email": "signer1@email.com",
        "order": 1,
        "documents": [
          {
            "id": "512293743e954e92beafca9460ce5f83b87db885",
            "role": "Recipient 1",
            "action": "sign"
          },
          {
            "id": "ec45e6daa0354d22997abef44232d7fbc60683e6",
            "role": "Recipient 1",
            "action": "sign"
          }
        ],
        "attributes": {
          "message": "test message",
          "subject": "test subject",
          "reminder": {
            "remind_after": 5,
            "remind_before": 5,
            "remind_repeat": 5
          },
          "redirect_uri": "https://www.signnow.com/",
          "authentication": {
            "type": "password",
            "phone": "+12345678",
            "value": "123456",
            "method": "phone_call"
          },
          "i_am_recipient": false,
          "expiration_days": 10,
          "allow_forwarding": false,
          "close_redirect_uri": "https://www.signnow.com/",
          "show_decline_button": true,
          "decline_redirect_uri": "https://www.signnow.com/"
        },
        "phone_invite": null
      },
      {
        "name": "Recipient 2",
        "email": "signer2@email.com",
        "order": 1,
        "documents": [
          {
            "id": "ec45e6daa0354d22997abef44232d7fbc60683e6",
            "role": "Recipient 2",
            "action": "sign"
          },
          {
            "id": "512293743e954e92beafca9460ce5f83b87db885",
            "role": "Recipient 2",
            "action": "view"
          }
        ],
        "attributes": {}
      }
    ],
    "general_reminder": {
      "remind_after": 3,
      "remind_before": 5,
      "remind_repeat": 7
    },
    "general_expiration_days": 30,
    "allowed_unmapped_sign_documents": []
  }
}
```

**Example** (`Successfully updated document group recipients`)

```json
{
  "data": {
    "cc": [
      "viewer1@email.com",
      "viewer2@email.com"
    ],
    "order_type": null,
    "recipients": [
      {
        "name": "Recipient 1",
        "email": "signer1@email.com",
        "order": 1,
        "documents": [
          {
            "id": "XXXXXXXXXe954e92beafca9460ce5f83b87db885",
            "role": "Recipient 1",
            "action": "sign"
          },
          {
            "id": "XXXXXXXXX0354d22997abef44232d7fbc60683e6",
            "role": "Recipient 1",
            "action": "sign"
          }
        ],
        "attributes": {
          "message": "test message 1",
          "subject": "test subject",
          "reminder": {
            "remind_after": 5,
            "remind_before": 5,
            "remind_repeat": 5
          },
          "redirect_uri": "https://www.signnow.com/",
          "authentication": {
            "type": "password",
            "value": "123456"
          },
          "i_am_recipient": false,
          "expiration_days": 10,
          "allow_forwarding": false,
          "close_redirect_uri": "https://www.signnow.com/",
          "show_decline_button": true,
          "decline_redirect_uri": "https://www.signnow.com/"
        }
      },
      {
        "name": "Recipient 2",
        "email": "signer2@email.com",
        "order": 1,
        "documents": [
          {
            "id": "XXXXXXXXXe954e92beafca9460ce5f83b87db885",
            "role": "Recipient 2",
            "action": "sign"
          },
          {
            "id": "XXXXXXXXX0354d22997abef44232d7fbc60683e6",
            "role": "Recipient 2",
            "action": "view"
          }
        ],
        "attributes": {},
        "phone_invite": null
      }
    ],
    "general_reminder": {
      "remind_after": 3,
      "remind_before": 5,
      "remind_repeat": 7
    },
    "general_expiration_days": 30,
    "allowed_unmapped_sign_documents": []
  }
}
```

### 400

Request with any of cases:

* incorrect Bearer token 
* expired token 
* empty header
* authorization = null
* authorization without value

* Document is not in DocumentGroup
* One of the roles doesn't exist
* The same role can't be used twice
* Recipients must be an array
* Name parameter is required
* Email field must be a valid email
* Order must be an integer
* Documents must be not null
* Incorrect document id provided
* Incorrect action of the document
* Recipients must be not empty
* Role must be a string
* The name field must be a maximum 255 symbols length
* The order field must be from 1 to 127
* Action parameter is required
* Action must be a string
* Name must be a string
* Email must be a string
* Documents must be an array
* Order parameter is required
* Document id must be not blank
* Document id must be a string
* Document role must be not blank
* The same name can't be used twice with the same order. Wrong recipient name: test; First order: 1; Second order: 1
* For viewers allowed only attribute.message, attribute.subject and attribute.i_am_recipient .
* At the same time, only one recipient can have attribute.i_am_recipient = true.
* Forbidden to use attribute.allow_forwarding with attribute.authentication at the same time.
* The type field in attributes.authentication should be of type string.
* The type field in attributes.authentication should be phone or password.
* The type field in attributes.authentication must be not null.
* The value field in attributes.authentication must be a maximum 5000 symbols length.
* The value field in attributes.authentication should be of type string.
* The value field in attributes.authentication should not be empty string.
* 4-byte characters in attributes.authentication.value are not supported.
* The phone field in attributes.authentication should be of type string.
* The phone field in attributes.authentication should have a valid phone format for U.S. and Canada.
* The phone field in attributes.authentication should not be empty string.
* The phone field in attributes.authentication is required when type is phone.
* The method field in attributes.authentication should be of type string.
* The method field in attributes.authentication should be sms or phone_call.
* The method field is required when authentication.type = phone.
* The phone field in attributes.authentication should not be empty string.
* The remind_after must be less than attributes.expiration_days.
* The remind_before must be less than attributes.expiration_days.
* The remind_repeat must be less than attributes.expiration_days.
* The remind_after field in attributes.reminder attribute must be an integer.
* The remind_repeat field in attributes.reminder attribute must be an integer.
* The remind_before field in attributes.reminder attribute must be an integer.
* The remind_after field in attributes.reminder cannot be less than 0.
* The remind_repeat field in attributes.reminder cannot be less than 0.
* The remind_before field in attributes.reminder cannot be less than 0.
* The remind_after field in attributes.reminder should be less then or equal 179.
* The remind_repeat field in attributes.reminder should be less then or equal 179.
* The remind_before field in attributes.reminder should be less then or equal 179.
* The attributes.type:password is allowed to use only with attributes.value.
* The attributes.type:phone isnt allowed to use withattributes.value`.
* The i_am_recipient field in attributes should be used with owners email`.
* The `cc` emails are not valid.



**Example** (`Example 1`)

```json
{
  "errors": [
    {
      "code": 13020025,
      "message": "recipients must be not empty"
    }
  ]
}
```

**Example** (`cc emails not valid`)

```json
{
  "errors": [
    {
      "code": 13020043,
      "message": "The `cc` field must contain valid emails."
    }
  ]
}
```

**Example** (`Authorization issues`)

```json
{
  "code": 1537,
  "message": "invalid_token"
}
```

**Example** (`Name must be a string`)

```json
{
  "errors": [
    {
      "code": 13020013,
      "message": "name must be a string"
    }
  ]
}
```

**Example** (`Role must be a string`)

```json
{
  "errors": [
    {
      "code": 13020010,
      "message": "role must be a string"
    }
  ]
}
```

**Example** (`Email must be a string`)

```json
{
  "errors": [
    {
      "code": 13020015,
      "message": "email must be a string"
    }
  ]
}
```

**Example** (`Action must be a string`)

```json
{
  "errors": [
    {
      "code": 13020011,
      "message": "action must be a string"
    }
  ]
}
```

**Example** (`Order must be an integer`)

```json
{
  "errors": [
    {
      "code": 13020019,
      "message": "order must be an integer"
    }
  ]
}
```

**Example** (`Documents must be an array`)

```json
{
  "errors": [
    {
      "code": 13020016,
      "message": "documents must be an array"
    }
  ]
}
```

**Example** (`Documents must be not null`)

```json
{
  "errors": [
    {
      "code": 13020023,
      "message": "documents must be not null"
    }
  ]
}
```

**Example** (`Name parameter is required`)

```json
{
  "errors": [
    {
      "code": 13020014,
      "message": "'name' parameter is required"
    }
  ]
}
```

**Example** (`Order parameter is required`)

```json
{
  "errors": [
    {
      "code": 13020018,
      "message": "'order' parameter is required"
    }
  ]
}
```

**Example** (`Recipients must be an array`)

```json
{
  "errors": [
    {
      "code": 13020002,
      "message": "Recipients must be an array"
    }
  ]
}
```

**Example** (`Action parameter is required`)

```json
{
  "errors": [
    {
      "code": 13020012,
      "message": "'action' parameter is required"
    }
  ]
}
```

**Example** (`Document id must be a string`)

```json
{
  "errors": [
    {
      "code": 13020021,
      "message": "document id must be an string"
    }
  ]
}
```

**Example** (`Recipients must be not empty`)

```json
{
  "errors": [
    {
      "code": 13020025,
      "message": "recipients must be not empty"
    }
  ]
}
```

**Example** (`Document id must be not blank`)

```json
{
  "errors": [
    {
      "code": 13020020,
      "message": "document id must be not blank"
    }
  ]
}
```

**Example** (`Incorrect document id provided`)

```json
{
  "errors": [
    {
      "code": 13020009,
      "message": "Invalid id provided, value: 03XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX given"
    }
  ]
}
```

**Example** (`One of the roles doesn't exist`)

```json
{
  "errors": [
    {
      "code": 13020006,
      "message": "One of the roles doesn't exist"
    }
  ]
}
```

**Example** (`Document role must be not blank`)

```json
{
  "errors": [
    {
      "code": 13020022,
      "message": "document role must be not blank"
    }
  ]
}
```

**Example** (`Document is not in DocumentGroup`)

```json
{
  "errors": [
    {
      "code": 13020026,
      "message": "Document is not in DocumentGroup"
    }
  ]
}
```

**Example** (`Incorrect action of the document`)

```json
{
  "errors": [
    {
      "code": 13020024,
      "message": "action must be one of the following: sign, view"
    }
  ]
}
```

**Example** (`Email field must be a valid email`)

```json
{
  "errors": [
    {
      "code": 13020003,
      "message": "The `email` field must be a valid email."
    }
  ]
}
```

**Example** (`The same role can't be used twice`)

```json
{
  "errors": [
    {
      "code": 13020007,
      "message": "The same role can't be used twice"
    }
  ]
}
```

**Example** (`The order field must be from 1 to 127`)

```json
{
  "errors": [
    {
      "code": 13020005,
      "message": "The `order` field must be from 1 to 127"
    }
  ]
}
```

**Example** (`The name field must be a maximum 255 symbols length`)

```json
{
  "errors": [
    {
      "code": 13020004,
      "message": "The `name` field must be a maximum 255 symbols length"
    }
  ]
}
```

**Example** (`The type field in attributes.authentication must be not null.`)

```json
{
  "errors": [
    {
      "code": 13020070,
      "message": "The `type` field in `attributes.authentication` must be not null."
    }
  ]
}
```

**Example** (`The method field is required when authentication.type = phone.`)

```json
{
  "errors": [
    {
      "code": 13020082,
      "message": "The `method` field is required when `authentication.type` = `phone`."
    }
  ]
}
```

**Example** (` The remind_after must be less than attributes.expiration_days.`)

```json
{
  "errors": [
    {
      "code": 13020087,
      "message": "The `remind_after` must be less than `attributes.expiration_days`."
    }
  ]
}
```

**Example** (`The remind_before must be less than attributes.expiration_days.`)

```json
{
  "errors": [
    {
      "code": 13020087,
      "message": "The `remind_before` must be less than `attributes.expiration_days`."
    }
  ]
}
```

**Example** (` The remind_repeat must be less than attributes.expiration_days.`)

```json
{
  "errors": [
    {
      "code": 13020087,
      "message": "The `remind_repeat` must be less than `attributes.expiration_days`."
    }
  ]
}
```

**Example** (`The attributes.type:phone isnt allowed to use withattributes.value`.`)

```json
{
  "errors": [
    {
      "code": 13020098,
      "message": "The `attributes.type`:`phone` isn`t allowed to use with `attributes.value`."
    }
  ]
}
```

**Example** (`The remind_after field in attributes.reminder cannot be less than 0.`)

```json
{
  "errors": [
    {
      "code": 13020091,
      "message": "The `remind_after` field in `attributes.reminder` cannot be less than 0."
    }
  ]
}
```

**Example** (`The remind_before field in attributes.reminder cannot be less than 0.`)

```json
{
  "errors": [
    {
      "code": 13020093,
      "message": "The `remind_before` field in `attributes.reminder` cannot be less than 0."
    }
  ]
}
```

**Example** (`The remind_repeat field in attributes.reminder cannot be less than 0.`)

```json
{
  "errors": [
    {
      "code": 13020092,
      "message": "The `remind_repeat` field in `attributes.reminder` cannot be less than 0."
    }
  ]
}
```

**Example** (`The type field in attributes.authentication should be of type string.`)

```json
{
  "errors": [
    {
      "code": 13020068,
      "message": "The `type` field in `attributes.authentication` should be of type string."
    }
  ]
}
```

**Example** (`The phone field in attributes.authentication should be of type string.`)

```json
{
  "errors": [
    {
      "code": 13020075,
      "message": "The `phone` field in `attributes.authentication` should be of type string."
    }
  ]
}
```

**Example** (`The value field in attributes.authentication should be of type string.`)

```json
{
  "errors": [
    {
      "code": 13020073,
      "message": "The `value` field in `attributes.authentication` should be of type string."
    }
  ]
}
```

**Example** (`4-byte characters in attributes.authentication.value are not supported.`)

```json
{
  "errors": [
    {
      "code": 13020072,
      "message": "4-byte characters in `attributes.authentication.value` are not supported."
    }
  ]
}
```

**Example** (`The method field in attributes.authentication should be of type string.`)

```json
{
  "errors": [
    {
      "code": 13020080,
      "message": "The `method` field in `attributes.authentication` should be of type string."
    }
  ]
}
```

**Example** (`The phone field in attributes.authentication should not be empty string`)

```json
{
  "errors": [
    {
      "code": 13020083,
      "message": "The `phone` field in `attributes.authentication` should not be empty string."
    }
  ]
}
```

**Example** (`The phone field in attributes.authentication should not be empty string.`)

```json
{}
```

**Example** (`The type field in attributes.authentication should be phone or password.`)

```json
{
  "errors": [
    {
      "code": 13020069,
      "message": "The `type` field in `attributes.authentication` should be `phone` or `password`."
    }
  ]
}
```

**Example** (`The value field in attributes.authentication should not be empty string.`)

```json
{
  "errors": [
    {
      "code": 13020074,
      "message": "The `value` field in `attributes.authentication` should not be empty string."
    }
  ]
}
```

**Example** (`The i_am_recipient field in attributes should be used with owners email`.`)

```json
{
  "errors": [
    {
      "code": 13020099,
      "message": "The `i_am_recipient` field in `attributes` should be used with owners email`."
    }
  ]
}
```

**Example** (`The attributes.type:password is allowed to use only with attributes.value.`)

```json
{
  "errors": [
    {
      "code": 13020097,
      "message": "The `attributes.type`:`password` is allowed to use only with `attributes.value`."
    }
  ]
}
```

**Example** (`The method field in attributes.authentication should be sms or phone_call.`)

```json
{
  "errors": [
    {
      "code": 13020081,
      "message": "The `method` field in `attributes.authentication` should be `sms` or `phone_call`."
    }
  ]
}
```

**Example** (`The remind_after field in attributes.reminder attribute must be an integer.`)

```json
{
  "errors": [
    {
      "code": 13020088,
      "message": "The `remind_after` field in `attributes.reminder` attribute must be an integer."
    }
  ]
}
```

**Example** (`The phone field in attributes.authentication is required when type is phone.`)

```json
{
  "errors": [
    {
      "code": 13020078,
      "message": "The `phone` field in `attributes.authentication` is required when `type` is `phone`."
    }
  ]
}
```

**Example** (`The remind_before field in attributes.reminder attribute must be an integer.`)

```json
{
  "errors": [
    {
      "code": 13020090,
      "message": "The `remind_before` field in `attributes.reminder` attribute must be an integer."
    }
  ]
}
```

**Example** (`The remind_repeat field in attributes.reminder attribute must be an integer.`)

```json
{
  "errors": [
    {
      "code": 13020089,
      "message": "The `remind_repeat` field in `attributes.reminder` attribute must be an integer."
    }
  ]
}
```

**Example** (`At the same time, only one recipient can have attribute.i_am_recipient = true.`)

```json
{
  "errors": [
    {
      "code": 13020085,
      "message": "At the same time, only one recipient can have `attribute.i_am_recipient` = `true`."
    }
  ]
}
```

**Example** (`The remind_after field in attributes.reminder should be less then or equal 179.`)

```json
{
  "errors": [
    {
      "code": 13020094,
      "message": "The `remind_after` field in `attributes.reminder` should be less then or equal 179."
    }
  ]
}
```

**Example** (`The remind_before field in attributes.reminder should be less then or equal 179.`)

```json
{
  "errors": [
    {
      "code": 13020096,
      "message": "The `remind_before` field in `attributes.reminder` should be less then or equal 179."
    }
  ]
}
```

**Example** (`The remind_repeat field in attributes.reminder should be less then or equal 179.`)

```json
{
  "errors": [
    {
      "code": 13020095,
      "message": "The `remind_repeat` field in `attributes.reminder` should be less then or equal 179."
    }
  ]
}
```

**Example** (` The value field in attributes.authentication must be a maximum 5000 symbols length.`)

```json
{
  "errors": [
    {
      "code": 13020071,
      "message": "The `value` field in `attributes.authentication` must be a maximum 5000 symbols length."
    }
  ]
}
```

**Example** (`For viewers allowed only attribute.message, attribute.subject and attribute.i_am_recipient.`)

```json
{
  "errors": [
    {
      "code": 13020084,
      "message": "For viewers allowed only `attribute.message`, `attribute.subject` and `attribute.i_am_recipient`."
    }
  ]
}
```

**Example** (`Forbidden to use attribute.allow_forwarding with attribute.authentication at the same time.`)

```json
{
  "errors": [
    {
      "code": 13020086,
      "message": "Forbidden to use `attribute.allow_forwarding` with `attribute.authentication` at the same time."
    }
  ]
}
```

**Example** (`The phone field in attributes.authentication should have a valid phone format for U.S. and Canada.`)

```json
{
  "errors": [
    {
      "code": 13020076,
      "message": "The `phone` field in `attributes.authentication` should have a valid phone format for U.S. and Canada."
    }
  ]
}
```

**Example** (`The same name can't be used twice with the same order. Wrong recipient name: test; First order: 1; Second order: 1`)

```json
{
  "errors": [
    {
      "code": 13020027,
      "message": "The same name can't be used twice with the same order. Wrong recipient name: `test`; First order: `1`; Second order: `1`"
    }
  ]
}
```

### 403

Access to DocumentGroup is denied

**Example** (`Example 1`)

```json
{
  "errors": [
    {
      "code": 13020008,
      "message": "Access to DocumentGroup is denied"
    }
  ]
}
```

**Example** (`Access to DocumentGroup is denied`)

```json
{
  "errors": [
    {
      "code": 13020008,
      "message": "Access to DocumentGroup is denied"
    }
  ]
}
```

### 404

Document Group is not found

**Example** (`Example 1`)

```json
{
  "errors": [
    {
      "code": 0,
      "message": "Document group `b1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX` not found"
    }
  ]
}
```

**Example** (`Doc group not found or incorrect UID`)

```json
{
  "errors": [
    {
      "code": 0,
      "message": "Document group `b1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX` not found"
    }
  ]
}
```

## Code Examples

> Replace `$SIGNNOW_ACCESS_TOKEN` and any `{placeholder}` values before running.

### cURL

```bash
curl -X PUT \
  "https://api.signnow.com/v2/document-groups/{document_group_id}/recipients" \
  -H "Authorization: Bearer $SIGNNOW_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cc": ["viewer1@email.com", "viewer2@email.com"], "order_type": "recipient_order", "recipients": [{"name": "Recipient 1", "order": 1, "documents": [{"id": "XXXXXXXXXe954e92beafca9460ce5f83b87db885", "role": "Recipient 1", "action": "sign"}, {"id": "XXXXXXXXX0354d22997abef44232d7fbc60683e6", "role": "Recipient 1", "action": "sign"}], "attributes": {"message": "test message", "subject": "test subject", "reminder": {"remind_after": 5, "remind_before": 5, "remind_repeat": 5}, "redirect_uri": "https://www.signnow.com/", "authentication": {"type": "password", "value": "1233456"}, "i_am_recipient": false, "expiration_days": 10, "allow_forwarding": false, "close_redirect_uri": "https://www.signnow.com/", "show_decline_button": true, "decline_redirect_uri": "https://www.signnow.com/"}}, {"name": "Recipient 2", "email": "signer2@email.com", "order": 1, "documents": [{"id": "XXXXXXXXXe954e92beafca9460ce5f83b87db885", "role": "Recipient 2", "action": "sign"}, {"id": "XXXXXXXXX0354d22997abef44232d7fbc60683e6", "role": "Recipient 2", "action": "view"}]}], "general_reminder": {"remind_after": 3, "remind_before": 5, "remind_repeat": 7}, "general_expiration_days": 30}'
```

---
*Full reference: https://docs.signnow.com/docs/doc-group-field-invite/operations/put-v2-document-groups-document_group_id-recipients*