> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spitshake.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Signer Delegation

> Allow signers to delegate their signing responsibility to another person.

# Signer Delegation

Signer delegation allows a recipient to reassign their signing responsibility to another person. This is useful when the original recipient is unavailable, has left the organization, or needs someone else to review and sign on their behalf.

When a signer delegates, the original submitter record is updated with the new recipient's details, an invitation email is sent to the new recipient, and the delegation is recorded in the audit trail.

## How It Works

1. The original signer opens their signing link (`/s/:slug`).
2. Instead of signing, they choose to delegate and provide the new recipient's email and (optionally) name.
3. The system updates the submitter record, resets the signing progress, and sends a fresh invitation email to the new recipient.
4. The new recipient receives the signing link and completes the document.
5. The delegation is recorded in the audit trail and triggers a webhook event.

## API Endpoint

### POST /s/:slug/delegate

Delegate a signing responsibility to another person. This endpoint is called from the signing page context (not the admin API).

**URL Parameters:**

| Parameter | Type   | Required | Description                         |
| --------- | ------ | -------- | ----------------------------------- |
| `slug`    | string | Yes      | The submitter's unique signing slug |

**Request Body:**

| Field   | Type   | Required | Description                                                                    |
| ------- | ------ | -------- | ------------------------------------------------------------------------------ |
| `email` | string | Yes      | Email address of the new recipient                                             |
| `name`  | string | No       | Full name of the new recipient. Defaults to the email address if not provided. |

### Status Restrictions

Delegation is only allowed when the submitter's current status is one of:

| Status      | Can Delegate? | Description                                   |
| ----------- | ------------- | --------------------------------------------- |
| `waiting`   | Yes           | Submitter has not yet been sent an invitation |
| `sent`      | Yes           | Invitation has been sent but not yet opened   |
| `opened`    | Yes           | Submitter has opened the signing link         |
| `completed` | No            | Submitter has already completed signing       |
| `declined`  | No            | Submitter has declined to sign                |
| `expired`   | No            | The signing link has expired                  |

Attempting to delegate a completed, declined, or expired submission returns a `422 Unprocessable Entity` error.

### Example Request

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://spitshake.io/s/aB3kL9mNpQ/delegate" \
    -H "Content-Type: application/json" \
    -d '{
      "email": "delegate@example.com",
      "name": "Sarah Johnson"
    }'
  ```
</RequestExample>

### Example Responses

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "success": true,
    "message": "Document delegated to delegate@example.com",
    "submitter": {
      "id": 142,
      "email": "delegate@example.com",
      "name": "Sarah Johnson",
      "status": "sent"
    }
  }
  ```

  ```json 400 — Missing Email theme={null}
  {
    "error": "Email is required"
  }
  ```

  ```json 422 — Invalid Status theme={null}
  {
    "error": "Cannot delegate a completed submission"
  }
  ```

  ```json 404 — Invalid Slug theme={null}
  {
    "error": "Record not found"
  }
  ```
</ResponseExample>

## What Happens During Delegation

When a delegation request succeeds, the system performs these steps:

1. **Updates the submitter record** with the new email and name. The status is reset to `sent`, and the `sent_at` timestamp is refreshed. The `opened_at` timestamp is cleared.
2. **Records the delegation in the submission audit log** with a `form_delegated` event containing the original and new recipient details, plus the delegator's IP address.
3. **Creates an immutable audit entry** in the `submission_audit_entries` table with event type `form.delegated`.
4. **Dispatches a `form.delegated` webhook** to all configured webhook endpoints.
5. **Sends an invitation email** to the new recipient with the signing link.

## Audit Trail

Every delegation creates two audit records:

### Submission Audit Log Entry

The `form_delegated` event is appended to the submission's `audit_log` JSON array:

```json theme={null}
{
  "event": "form_delegated",
  "from_email": "original@example.com",
  "from_name": "John Smith",
  "to_email": "delegate@example.com",
  "to_name": "Sarah Johnson",
  "delegated_by_ip": "203.0.113.42",
  "timestamp": "2026-04-09T14:22:18.000Z"
}
```

### Immutable Audit Entry

A tamper-proof record is written to the `submission_audit_entries` table:

```json theme={null}
{
  "id": 4817,
  "submission_id": 89,
  "submitter_id": 142,
  "event_type": "form.delegated",
  "ip_address": "203.0.113.42",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
  "metadata": {
    "from_email": "original@example.com",
    "from_name": "John Smith",
    "to_email": "delegate@example.com",
    "to_name": "Sarah Johnson"
  },
  "chain_hash": "a1b2c3d4e5f6...sha256hash",
  "created_at": "2026-04-09T14:22:18.000Z"
}
```

## Webhook Event

When a delegation occurs, a `form.delegated` webhook event is dispatched to all configured webhook endpoints. The payload follows the standard webhook format:

```json theme={null}
{
  "event_type": "form.delegated",
  "timestamp": "2026-04-09T14:22:18.000Z",
  "data": {
    "id": 142,
    "submission_id": 89,
    "email": "delegate@example.com",
    "name": "Sarah Johnson",
    "role": "Recipient",
    "status": "sent",
    "sent_at": "2026-04-09T14:22:18.000Z",
    "opened_at": null,
    "completed_at": null,
    "declined_at": null,
    "metadata": {
      "from_email": "original@example.com",
      "from_name": "John Smith"
    }
  }
}
```

<Note>
  The webhook payload includes the **new** submitter details (after delegation). The original signer's information is available in the `metadata.from_email` and `metadata.from_name` fields.
</Note>

## Security Considerations

* The delegation endpoint does not require API token authentication -- it is accessed from the signing page context using the submitter's unique slug.
* The signing slug serves as the authorization mechanism. Only someone with access to the signing URL can delegate.
* Delegation is a one-way operation. Once delegated, the original signer loses access (their signing link now belongs to the new recipient).
* All delegations are recorded in the immutable audit trail with chain hashing, making them tamper-evident.
* The delegator's IP address is captured for forensic purposes.