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

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

Update a reassign request

Request

PUT https://api.cm.com/sign/v1/reassignrequests/{id}

URL Parameter

Request body

{
    "state": "approved",
    "newInvitee": {
        "message": "Please sign this reassigned Sign invite"
    }
}

Parameters

* declineReason is required when state is set to declined