--- title: "Edit doc group recipients" method: PUT path: "/v2/document-groups/{document_group_id}/recipients" --- # Edit doc group recipients `PUT /v2/document-groups/{document_group_id}/recipients` ## Request - Base URL: `https://api.signnow.com` - URL: `https://api.signnow.com/v2/document-groups/{document_group_id}/recipients` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) This endpoint allows API 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. ## Request body - object - `cc` string[]: List of email addresses for CC recipients. - `order_type` string: 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` object[], required: List of document group recipients. Should contain at least one recipient. - `name` string, required: Recipient's name. - `email` string: Recipient's email address. - `order` integer, required: Order of receiving the document group invite. - `documents` object[], required: List of documents, recipient roles, and allowed actions. Should contain at least one document. - `id` string, required: Document ID. - `role` string, required: Recipient's role name. - `action` string, required: Allowed action with a document. Possible values: `view`, `sign`,`approve`. - `attributes` object: Signature invite attributes. - `message` string: Invite email message. Supports {documentName} and {fullName} placeholders. - `subject` string: Invite email subject. Supports {documentName} and {fullName} placeholders. - `reminder` object: Reminder email settings. Available for `sign` action. - `remind_after` integer: Send the reminder email to the recipient after the set amount of days. `remind_after` must be less than `expiration_days`. - `remind_before` integer: 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`. - `remind_repeat` integer: Send the reminder email to the recipient every set amount of days. `remind_repeat` must be less than `expiration_days`. - `redirect_uri` string: The link that opens after the signing session has been completed. - `authentication` object: Recipient authentication settings. Available for recipients with `sign` and `approve` actions. Can not be used when `allow_forwarding`is set to true. - `type` string: Type of the recipient authentication. Can be `phone` or `password`.​​ Required inside the `authentication` object. - `phone` string: The phone number for the recipient's authentication. Required with type `phone`. - `value` string: The password to unlock the document group. Required inside the `authentication` object with the `password` authentication type. - `method` string: Phone authentication type. Required inside the `authentication` object with the `phone` authentication type. Allowed values: `sms`, `phone_call`. - `sms_message` string: 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): “SignNow document invite unlock code: 123456.” - `i_am_recipient` boolean: Set to `true` if the document sender is also a recipient. Available for `sign` action. - `expiration_days` integer: Days until the invite expires. Available for `sign`and `approve` actions. - `redirect_target` string: 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. - `allow_forwarding` boolean: Whether recipients are allowed to reassign the invite to a different email address. Available for `sign` action. - `close_redirect_uri` string: The link that opens when a signer clicks **Save Progress and Finish Later** during a signing session or **Close** in view mode. Available for `sign ` action. - `show_decline_button` boolean: Whether to show the Decline button on signatue fields. Available for `sign` action. - `decline_redirect_uri` string: The URL that opens after the recipient declines the document. Available for `sign` action. - `email_group` object: 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. - `id` string: ID of the email group. - `general_reminder` object: Default `reminder` applied to all recipients in the invite. - `remind_after` integer: Days after invite is sent before a reminder is delivered. Must be less than `general_expiration_days`. - `remind_before` integer: Days before expiration when a reminder is delivered. Must be less than `general_expiration_days`. - `remind_repeat` integer: Days between repeated reminders. - `general_expiration_days` integer: Default `expiration_days` applied to all recipients in the invite. Min: `1`, Max: `180`. Default: `30`. ## Response `200` Successfully updated document group recipients. - object - `data` object: Recipients of the document group, CC recipients, and documents not yet assigned to a recipient. - `cc` string[]: Email addresses of CC recipients. - `order_type` string: 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` object[]: Recipients of the document group invite. - `name` string: Name of the recipient. - `email` string: Email address of the recipient. - `order` integer: Position of the recipient in the signing order. - `documents` object[]: Documents the recipient receives, with the role and action for each. - `id` string: ID of the document. - `role` string: Name of the recipient role in the document. - `action` string: Action the recipient must perform in the document: `sign`, `view`, or `approve`. - `attributes` object: Invite settings of the recipient. - `message` string: Message of the invite email. - `subject` string: Subject of the invite email. - `reminder` object: Reminder settings of the invite. - `remind_after` integer: Number of days after the invite is sent before the first reminder. - `remind_before` integer: Number of days before expiration to send a reminder. - `remind_repeat` integer: Number of days between repeated reminders. - `redirect_uri` string: URL the recipient is redirected to after completing the signing session. - `authentication` object: Authentication settings of the recipient. - `type` string: Authentication type of the recipient, for example `password` or `phone`. - `phone` string: Phone number used to authenticate the recipient. `null` if not set. - `value` string: Password the recipient must enter to open the documents. - `method` string: Delivery method of the password for `phone` authentication: `sms` or `phone_call`. `null` if not set. - `i_am_recipient` boolean: `true` if the sender is also a recipient. - `expiration_days` integer: Number of days before the invite expires. - `allow_forwarding` boolean: `true` if the recipient can reassign the invite to another email address. - `close_redirect_uri` string: URL the recipient is redirected to after selecting **Save Progress and Finish Later**. - `show_decline_button` boolean: `true` if the **Decline** button is shown on signature fields. - `decline_redirect_uri` string: URL the recipient is redirected to after declining the documents. - `email_group` object: Email group of the recipient. `id` is `null` if the recipient is not a group. - `id` string: ID of the email group. `null` if the invite was sent to a single recipient. - `phone_invite` string: Phone number for an SMS invite. `null` for email invites. - `general_reminder` object: Default `reminder` applied to all recipients in the invite. - `remind_after` integer: Days after invite is sent before a reminder is delivered. - `remind_before` integer: Days before expiration when a reminder is delivered. - `remind_repeat` integer: Days between repeated reminders. - `general_expiration_days` integer: Default `expiration_days` applied to all recipients in the invite. - `allowed_unmapped_sign_documents` object[]: Documents with `sign` actions that are allowed to stay unassigned to a recipient. ## Other responses - `400`: * Wrong, expired, or missing token. * 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. - `403`: Access to DocumentGroup is denied. - `404`: Document group is not found. --- [API](https://skmtc.dev/signnow/apis/signnow-api.md) - [All operations](https://skmtc.dev/signnow/apis/signnow-api/llms.txt) - [OpenAPI document](https://skmtc.dev/signnow/apis/signnow-api/revisions/1c9c30a6142b?raw)