Skip to main content

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

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:
ParameterTypeRequiredDescription
slugstringYesThe submitter’s unique signing slug
Request Body:
FieldTypeRequiredDescription
emailstringYesEmail address of the new recipient
namestringNoFull 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:
StatusCan Delegate?Description
waitingYesSubmitter has not yet been sent an invitation
sentYesInvitation has been sent but not yet opened
openedYesSubmitter has opened the signing link
completedNoSubmitter has already completed signing
declinedNoSubmitter has declined to sign
expiredNoThe signing link has expired
Attempting to delegate a completed, declined, or expired submission returns a 422 Unprocessable Entity error.

​
Example Request

curl -X POST "https://spitshake.io/s/aB3kL9mNpQ/delegate" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "delegate@example.com",
    "name": "Sarah Johnson"
  }'

​
Example Responses

{
  "success": true,
  "message": "Document delegated to delegate@example.com",
  "submitter": {
    "id": 142,
    "email": "delegate@example.com",
    "name": "Sarah Johnson",
    "status": "sent"
  }
}

​
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: 
{
  "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: 
{
  "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: 
{
  "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"
    }
  }
}
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.

​
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.