Reassign signing responsibility
Introduction
Sometimes an invitee receives an invite that was meant for someone else in their organisation. In order to prevent the dossier being declined and then resent, an invitee can request their signing responsibility to be reassigned to somebody else.
Allow reassignment
If you would like to allow an invitee the ability to reassign their signing responsibility, you can do so by including a reassignable
option to the dossier object, when creating a dossier. If this field is not provided, the dossier will not be reassignable.
This is part of the POST
request to /dossiers
. To see the full request, refer to the Create dossier request.
POST https://api.cm.com/sign/v1/dossiers
Request body
{
"name": "Example contract",
// Other dossier fields omitted for visibility
"reassignable": true
}
Invitee requests reassignment
Once the invitee opens the reassignable dossier's invite, they will have an "Actions" button in the top right of their invite, this opens a dropdown, that includes the "Reassign" option.
Clicking the "Reassign" button, will in turn open a modal that requires the invitee to fill in all the necessary details for the new invitee to be able to sign the dossier including identification and authentication. For example, if the dossier is sent via email and requires OTP SMS identification, name, email address, and phone number will be mandatory for the new invitee.
The invitee will always be required to state a reason for requesting a reassignment of their signing responsibility.
Approve or decline the request
After the invitee has requested reassignment, the dossier owner will receive an email notification detailing the request along with a link to open and view the request. Dossier owners have the option to opt out of this notification, for more information, refer to Opt out of reassigned notification.
The dossier owner will also be able to see the reassign request from the Sign dashboard in the Pending Tasks page.
Opening the reassignment request will display all the relevant information about the dossier, original invitee, and potential new invitee. It will also give the option to approve or decline the request. Declining a reassignment request will always require a decline reason.
Approving or declining the request can also be done via the API, check Update a reassign request endpoint.
Dossiers sent on behalf of a team
If a reassignment has been requested on a dossier sent on behalf of a team, every user in that team will have access to the reassignment request from their Pending Tasks page in the Sign dashboard.
In this case, only the dossier owner will receive the email notification of the requested reassignment, the other users will only see the request from their dashboard.
Anyone from the team, whether it's a regular user, or admin of the team, will be able to approve or decline the reassign request.
Opt out of reassigned notifications
By default, dossier owners receive all available notifications, including a notification when a reassignment has been requested. However, it is possible to modify which notifications the dossier owner will receive during the dossier creation call in the optional notifications
field.
Request body
{
"name": "Example contract",
// other dossier fields
"owners": [
{
"name": "John Doe",
"email": "[email protected]",
"notifications": [
"signed",
"reviewed",
"declined",
"completed",
"expired",
"invite.expired",
"invite.undelivered",
"reassigned"
]
}
],
"reassignable": true
}
To only receive specific notifications, list only the notifications the owner would like to receive in the notifications
field. By default, all notifications are enabled.
Webhook Event
Customers also have the option to receive a webhook whenever a reassign request is created or updated. For information on events and creating and managing them, refer to Events.
If a customer has a dossier.invitee.reassignRequest.state.updated
webhook, whenever a reassign request is created, approved, or declined, they will receive a POST
request to their desired url, with the following request body structure.
{
"id": "302935b2-8a22-4e25-bffb-fccda8963bd4",
"type": "dossier.invitee.reassignRequest.state.updated",
"dossier": {
"id": "24a8375d-8e9e-4fe1-9f38-f5a863cd26bb",
"state": "pending"
},
"reassignRequest": {
"id": "6f8d0a9d-b85c-4c3f-9e69-5699f1e00f49",
"state": "declined",
"originalInvitee": {
"id": "6f8d0a9d-b85c-4c3f-9e69-5699f1e00f49",
"state": null
}
},
"created": "2024-01-01T00:00:00+00:00"
}
Reassign Request Endpoints
Headers
All endpoints make use of the JWT authentication. For more information, refer to Authentication.
Content-Type: application/json
Authorization: Bearer GENERATED_TOKEN_HERE
Get all reassign requests
Request
URL
GET https://api.cm.com/sign/v1/reassignrequests
Response
[
{
"id": "6f8d0a9d-b85c-4c3f-9e69-5699f1e00f49",
"url": "https://www.cm.com/app/sign/reassign/review/cFoU7JAiY3xZAAGdd43j64K6eNtLTmn8W89iwdew09qsQnaiZF6UzAFriB8ZaUfE0CtVr7UZXCcIjVRqZl7yBWIyUNAnX1NpAqgD",
// Other fields omitted for visibility
"declineReason": null,
"createdAt": "2024-01-01T00:00:00+00:00"
},
{
"id": "ab8c6991-7b99-46d6-8893-33445d6bee9e",
"url": "https://www.cm.com/app/sign/reassign/review/RdWdtgSUxuQr7YkejfAT2O9LvL9R3R9pFl4OxfCjb5o5M2R66NfCe0b5nxf2EC7RvI2IpJ7vdwzReTF1owCGFpqmP6geRdxzB70j",
// Other fields omitted for visibility
"declineReason": null,
"createdAt": "2024-01-01T00:00:00+00:00"
}
]
To view all properties and their descriptions, refer to Get a reassign request response.
Get a reassign request
Request
GET https://api.cm.com/sign/v1/reassignrequests/{id}
URL Parameter
Property | Type | Example | Description |
---|---|---|---|
id | string | "6f8d0a9d-b85c-4c3f-9e69-5699f1e00f49" | The unique GUID of the reassign request. Can be retrieved from the /reassignrequests endpoint or from the webhook event. |
Response
{
"id": "6f8d0a9d-b85c-4c3f-9e69-5699f1e00f49",
"url": "https://www.cm.com/app/sign/reassign/review/cFoU7JAiY3xZAAGdd43j64K6eNtLTmn8W89iwdew09qsQnaiZF6UzAFriB8ZaUfE0CtVr7UZXCcIjVRqZl7yBWIyUNAnX1NpAqgD",
"state": "pending",
"dossier": {
"id": "6f8d0a9d-b85c-4c3f-9e69-5699f1e00f49",
"name": "Example contract",
"owner": "John Doe"
},
"originalInvitee": {
"id": "6f8d0a9d-b85c-4c3f-9e69-5699f1e00f49",
"name": "Jane Doe",
"email": "[email protected]",
"phoneNumber": null,
"authenticationMethods": [],
"identificationMethod": null,
"identificationMethods": [],
"notifications": [
"completed",
"declined",
"invite",
"reviewed",
"signed"
],
"reference": null,
"readOnly": true,
"state": "reassigned",
"stateComment": null,
"stateChanged": "2024-01-01T00:00:00+00:00",
"position": 1,
"locale": "en-US",
"redirectUrl": null
},
"newInvitee": {
"name": "Josh Doe",
"email": "[email protected]",
"phoneNumber": null,
"message": "Please sign Josh"
},
"reason": "Josh needs to sign this.",
"declineReason": null,
"createdAt": "2024-01-01T00:00:00+00:00"
}
Parameters
Property | Type | Description |
---|---|---|
id | string | Unique GUID of the reassign request. |
url | string | Url of the reassign request that anybody can open to approve or decline the request. |
state | string | Possible values are pending , approved , and declined . |
dossier | object | Contains the name , id , and owner of the dossier that the reassign request belongs to. If the dossier was sent on behalf of a team, owner will be the team's name, otherwise, it will be the dossier owner's name. |
originalInvitee | object | Contains all the values of a regular invitee object. For a list of objects included, refer to the 200 response of the Update Invitee API Reference. |
newInvitee | object | Contains name , email , phoneNumber , and message to be used for the new invitee. |
reason | string | The reason the original invitee has requested a reassignment. |
declineReason | string | The reason the dossier owner or team user has declined the reassign request. Will not be null when state is declined . |
createdAt | string | The date the reassignment was requested. |
Update a reassign request
Request
PUT https://api.cm.com/sign/v1/reassignrequests/{id}
URL Parameter
Property | Type | Example | Description |
---|---|---|---|
token | string | "6f8d0a9d-b85c-4c3f-9e69-5699f1e00f49" | The unique GUID of the reassign request. |
Request body
{
"state": "approved",
"newInvitee": {
"message": "Please sign this reassigned Sign invite"
}
}
Parameters
Property | Required | Type | Example | Description |
---|---|---|---|---|
state | Yes | string | "approved" | Possible values are approved and declined describing the outcome of the reassignment request. |
newInvitee | No | object | "message": "Please sign" | Can contain the message property. The value of the message field will be the new custom message sent to the new invitee. The message must be a string of up to 1000 characters |
declineReason | No* | string | "You need to sign this yourself" | Specifies the reason for declining the reassignment request to the original invitee, will replace the custom message and send a new invite. |
* declineReason
is required when state
is set to declined
Updated 5 months ago