Add Users to Workflow - SigningHub-APIGuide

Business applications can use this service API to add recipients to a workflow. This call will only add a recipient to the workflow. That is, no fields currently on the document will be automatically assigned to the new recipient(s), nor will this create any new fields.

Note the recipient(s) will be added as the last person in the workflow. Hence further work may be required to remove a current recipient(s) already present in the workflow.

At least one user must exist in a workflow before fields (input and signature) can be added to the document.

Note the input accepts one or more users in a single call.

In this specific call the user is a known natural person. However, the same rules apply to Groups and Placeholders. In either of these cases the recipient becomes a Group of users whereby any member of the group can sign the document, or a Placeholder. The latter case is used when you do not know the identity of the intended signatory.

Note SigningHub workflow signing order starts at "1". Hence, adding a user to workflow with no current recipient(s) begins a new signing order count. The "signing_order" parameter is mandatory if the workflow type is "custom".

Important, using this API call may affect the workflow type. If there are current recipients in a sequential workflow and a new one is added with the same signing order as a current recipient, then that part of the workflow changes automatically from sequential to parallel. Hence, the workflow overall is now of type custom as opposed to purely sequential. Adding a recipient with the same signing order as two or parallel recipients does not change the workflow. There are merely, three or more recipients at that particular point of the workflow; all in parallel order.

Note, while XML type document preparation, only supported role types are "SIGNER", "REVIEWER" and "CARBON_COPY"

https://api.signinghub.com/v3/packages/{package_id}/workflow/users
HTTP Verb		POST
Content-Type		application/json
Accept		application/json
Authorization		Bearer {access_token}
Request Body		`[` `{` `"user_email":` `"chris@ascertia.com",` `"user_name":` `"Chris",` `"role":` `"SIGNER",` `"email_notification":` `true,` `"signing_order": 1` `}, { "user_email": "craig@ascertia.com", "user_name": "Craig", "role": "SIGNER", "email_notification": false, }` ]
Status Code	Message	Response Body
200	OK
400	Bad Request	`{` `"Message":` `"Recipient role is not supported for an XML type document"` `}`
401	Unauthorized	`{` `"Message":` `"Request authorization denied"` `}`
		`{` `"Message":` `"User authentication required"` `}`
403	Forbidden	`{` `"Message":` `"Document does not belong to user"` `}`
		`{` `"Message":` `"You are not allowed to perform this action on locked workflow"` `}`
		`{` `"Message":` `"Document is no longer in draft state"` `}`
		`{` `"Message":` `"Account is disabled"` `}`
		`{` `"Message":` `"You are not allowed to perform the requested operation"` `}`
404	Not Found	`{` `"Message":` `"Document not found"` `}`
		`{` `"Message":` `"Group or contact not found"` `}`
500	Internal Server Error	`{` `"Message":` `"An internal server error occurred while processing the request"` `}`

The detail of each item provided in the request and response is provided below:

Item Details
Names	Description
Request Parameters
access_token	The access token obtained as a result of successful authentication. If "scope" parameter was used in authentication request, then this service requires the access token to be obtained using the credentials of an Enterprise admin whose enterprise role has the application integration privileges.
package_id	SigningHub package ID, which the recipients are to be added to.
user_email	Email address of the user to be added in the workflow.
user_name	Name of the recipient to be added in the workflow.
role	Role of the recipient in the workflow. Possible values are "SIGNER", "REVIEWER", "EDITOR","CARBON_COPY" or "INPERSON_HOST". However, while XML type document preparation, only supported role types are "SIGNER", "REVIEWER" and "CARBON_COPY"
email_notification (optional)	If set as true, SigningHub will send notifications to the user via email as per the document owner and user notification settings. A value of false means no notifications will be sent to user throughout the workflow.
signing_order (optional)	Order of the recipient in the workflow. This signing order is mandatory when workflow type is "CUSTOM".
Response Parameters
Message	The service specific error message returned by the API. This message provides useful information about why the service has returned an error response.