Submitters

A submitter is an individual signer within a submission. Each submitter is assigned to a role defined in the template, has their own secure signing link, and progresses through an independent status lifecycle. You can track when they opened, signed, or declined the document, pre-fill their fields, and resend invitations.

Submitter object

The standard submitter object returned by list endpoints:

{
  "id": 301,
  "uuid": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
  "slug": "r7t2q9v4",
  "email": "jane@example.com",
  "name": "Jane Smith",
  "role": "Client",
  "status": "completed",
  "submission_id": 187,
  "opened_at": "2026-04-08T11:10:00.000Z",
  "sent_at": "2026-04-08T10:31:01.000Z",
  "completed_at": "2026-04-08T11:15:00.000Z"
}

Field	Type	Description
`id`	integer	Unique submitter identifier.
`uuid`	string	UUID for this submitter instance. Unique per submission (not the same as the template submitter UUID).
`slug`	string	URL-safe identifier used in the signing link (`/s/{slug}`).
`email`	string	Submitter’s email address (encrypted at rest).
`name`	string or null	Submitter’s full name (encrypted at rest).
`role`	string	The template submitter role this person is assigned to (e.g., “Client”, “Witness”).
`status`	string	Current status. See Status lifecycle.
`submission_id`	integer	ID of the parent submission.
`opened_at`	string or null	ISO 8601 timestamp when the submitter first opened the signing link.
`sent_at`	string or null	ISO 8601 timestamp when the invitation email was sent.
`completed_at`	string or null	ISO 8601 timestamp when the submitter completed and submitted their form.

Full submitter object

When retrieving a single submitter by ID, the response includes additional detail:

{
  "id": 301,
  "uuid": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
  "slug": "r7t2q9v4",
  "email": "jane@example.com",
  "name": "Jane Smith",
  "role": "Client",
  "status": "completed",
  "submission_id": 187,
  "phone": "+15551234567",
  "external_id": "cust-001",
  "opened_at": "2026-04-08T11:10:00.000Z",
  "sent_at": "2026-04-08T10:31:01.000Z",
  "completed_at": "2026-04-08T11:15:00.000Z",
  "declined_at": null,
  "values": {
    "full_name": "Jane Smith",
    "agreement_date": "2026-04-08",
    "payment_method": "Credit Card",
    "address_line_1": "123 Main St",
    "city": "Portland",
    "state": "OR",
    "zip_code": "97201"
  },
  "metadata": {
    "source": "website_checkout",
    "session_id": "sess_abc123"
  },
  "preferences": {
    "send_email": true,
    "sign_mode": "normal"
  },
  "documents": [
    {
      "id": 95,
      "name": "Service Agreement - Signed.pdf",
      "url": "/api/submissions/187/documents/95",
      "content_type": "application/pdf",
      "size": 284672
    }
  ],
  "submission_events": [
    {
      "event": "form.sent",
      "timestamp": "2026-04-08T10:31:01.000Z",
      "actor": "system",
      "ip_address": null
    },
    {
      "event": "form.viewed",
      "timestamp": "2026-04-08T11:10:00.000Z",
      "actor": "jane@example.com",
      "ip_address": "198.51.100.22"
    },
    {
      "event": "field.updated",
      "timestamp": "2026-04-08T11:12:00.000Z",
      "actor": "jane@example.com",
      "ip_address": "198.51.100.22"
    },
    {
      "event": "form.completed",
      "timestamp": "2026-04-08T11:15:00.000Z",
      "actor": "jane@example.com",
      "ip_address": "198.51.100.22"
    }
  ],
  "template": {
    "id": 42,
    "name": "Service Agreement",
    "slug": "qk7x9m2p",
    "external_id": "contract-sa-2026",
    "folder_name": "Legal Contracts"
  },
  "submission": {
    "id": 187,
    "slug": "n3k8p1w5",
    "source": "api",
    "status": "completed",
    "template_id": 42,
    "submitter_count": 2,
    "created_at": "2026-04-08T10:31:00.000Z",
    "updated_at": "2026-04-08T11:20:00.000Z",
    "completed_at": "2026-04-08T11:20:00.000Z",
    "expire_at": "2026-05-08T10:31:00.000Z",
    "archived_at": null
  }
}

Additional fields in the detail response

Field	Type	Description
`phone`	string or null	Submitter’s phone number in E.164 format (encrypted at rest).
`external_id`	string or null	Your custom identifier for mapping this submitter to an external system (e.g., CRM contact ID).
`declined_at`	string or null	ISO 8601 timestamp when the submitter declined to sign, or null.
`values`	object	Key-value map of the submitter’s field entries. Keys match the field `key` from the template schema. Includes both pre-filled and signer-entered values.
`metadata`	object	Custom key-value pairs attached to this submitter (encrypted at rest).
`preferences`	object	Submitter-level preferences including `send_email` and `sign_mode`.
`documents`	array	Documents associated with this submitter’s completed form.
`submission_events`	array	Audit trail of events specific to this submitter. Each event includes `event`, `timestamp`, `actor`, and `ip_address`.
`template`	object	Summary of the template this submission was created from.
`submission`	object	Summary of the parent submission.

Status lifecycle

Each submitter progresses through a series of statuses independently from other submitters in the same submission.

waiting(0) → sent(1) → opened(2) → completed(3)
                                  → declined(4)
waiting(0) → expired(5)

Status	Code	Description
`waiting`	0	The submitter’s turn has not arrived yet (in sequential signing) or the invitation has not been sent.
`sent`	1	The invitation email has been sent. The submitter has not yet opened the signing link.
`opened`	2	The submitter has opened the signing link at least once.
`completed`	3	The submitter has filled all required fields and submitted the form.
`declined`	4	The submitter explicitly declined to sign the document.
`expired`	5	The submission’s `expire_at` timestamp passed before this submitter completed.

In sequential signing order, submitters start in waiting status and move to sent only when the previous submitter completes. In parallel signing, all submitters are sent invitations immediately and skip the waiting state.

Status transitions

The status only moves forward — a submitter cannot go back to a previous status. The possible transitions are:

From	To	Trigger
`waiting`	`sent`	Previous submitter completed (sequential) or submission created (parallel).
`sent`	`opened`	Submitter clicks the signing link for the first time.
`opened`	`completed`	Submitter fills all required fields and submits the form.
`opened`	`declined`	Submitter clicks the decline button and confirms.
`waiting`	`expired`	Submission `expire_at` reached.
`sent`	`expired`	Submission `expire_at` reached.
`opened`	`expired`	Submission `expire_at` reached.

Listing submitters

Retrieve all submitters across your account, optionally filtered by submission, status, or external ID.

curl "$DOCUTRUST_URL/api/submitters?limit=25&status=completed" \
  -H "X-Auth-Token: $DOCUTRUST_TOKEN"

Filter parameters

Parameter	Type	Description
`submission_id`	integer	Filter by parent submission.
`status`	string	Filter by status: `waiting`, `sent`, `opened`, `completed`, `declined`, `expired`.
`external_id`	string	Filter by your custom external ID.
`email`	string	Filter by submitter email address.
`after`	integer	Cursor for pagination (return items after this ID).
`before`	integer	Cursor for pagination (return items before this ID).
`limit`	integer	Items per page (1-100, default 10).

Response:

{
  "data": [
    {
      "id": 301,
      "uuid": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
      "slug": "r7t2q9v4",
      "email": "jane@example.com",
      "name": "Jane Smith",
      "role": "Client",
      "status": "completed",
      "submission_id": 187,
      "opened_at": "2026-04-08T11:10:00.000Z",
      "sent_at": "2026-04-08T10:31:01.000Z",
      "completed_at": "2026-04-08T11:15:00.000Z"
    },
    {
      "id": 302,
      "uuid": "a8b7c6d5-e4f3-2109-abcd-987654321098",
      "slug": "k5m9n3p7",
      "email": "bob@acmecorp.com",
      "name": "Bob Johnson",
      "role": "Company Representative",
      "status": "completed",
      "submission_id": 187,
      "opened_at": "2026-04-08T11:17:00.000Z",
      "sent_at": "2026-04-08T10:31:01.000Z",
      "completed_at": "2026-04-08T11:20:00.000Z"
    },
    {
      "id": 295,
      "uuid": "c9d8e7f6-a5b4-3210-cdef-ba9876543210",
      "slug": "p4q8r2s6",
      "email": "carol@example.com",
      "name": "Carol Williams",
      "role": "Client",
      "status": "sent",
      "submission_id": 185,
      "opened_at": null,
      "sent_at": "2026-04-07T14:00:01.000Z",
      "completed_at": null
    }
  ],
  "pagination": {
    "count": 3,
    "next": 295,
    "prev": null
  }
}

Filter by submission

Retrieve all submitters for a specific submission:

curl "$DOCUTRUST_URL/api/submitters?submission_id=187" \
  -H "X-Auth-Token: $DOCUTRUST_TOKEN"

Filter by external ID

Find a submitter by your custom identifier:

curl "$DOCUTRUST_URL/api/submitters?external_id=cust-001" \
  -H "X-Auth-Token: $DOCUTRUST_TOKEN"

Retrieving a submitter

Get the full detail for a single submitter:

curl "$DOCUTRUST_URL/api/submitters/301" \
  -H "X-Auth-Token: $DOCUTRUST_TOKEN"

This returns the full submitter object with values, metadata, preferences, events, and nested template/submission data.

Updating a submitter

Update a submitter’s details before they have completed their form. You can change their name, email, phone, external ID, metadata, and pre-filled values.

curl -X PUT "$DOCUTRUST_URL/api/submitters/301" \
  -H "X-Auth-Token: $DOCUTRUST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane M. Smith",
    "email": "jane.smith@newdomain.com",
    "phone": "+15559876543",
    "external_id": "cust-001-updated",
    "metadata": {
      "source": "website_checkout",
      "session_id": "sess_abc123",
      "updated_by": "admin"
    },
    "values": {
      "full_name": "Jane M. Smith",
      "address_line_1": "456 Oak Ave"
    }
  }'

const response = await fetch(`${process.env.DOCUTRUST_URL}/api/submitters/301`, {
  method: "PUT",
  headers: {
    "X-Auth-Token": process.env.DOCUTRUST_TOKEN,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Jane M. Smith",
    email: "jane.smith@newdomain.com",
    phone: "+15559876543",
    external_id: "cust-001-updated",
    metadata: {
      source: "website_checkout",
      session_id: "sess_abc123",
      updated_by: "admin",
    },
    values: {
      full_name: "Jane M. Smith",
      address_line_1: "456 Oak Ave",
    },
  }),
});

const submitter = await response.json();

import requests
import os

url = f"{os.environ['DOCUTRUST_URL']}/api/submitters/301"
headers = {
    "X-Auth-Token": os.environ["DOCUTRUST_TOKEN"],
    "Content-Type": "application/json",
}
payload = {
    "name": "Jane M. Smith",
    "email": "jane.smith@newdomain.com",
    "phone": "+15559876543",
    "external_id": "cust-001-updated",
    "metadata": {
        "source": "website_checkout",
        "session_id": "sess_abc123",
        "updated_by": "admin",
    },
    "values": {
        "full_name": "Jane M. Smith",
        "address_line_1": "456 Oak Ave",
    },
}

response = requests.put(url, headers=headers, json=payload)
submitter = response.json()

Response:

{
  "id": 301,
  "uuid": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
  "slug": "r7t2q9v4",
  "email": "jane.smith@newdomain.com",
  "name": "Jane M. Smith",
  "role": "Client",
  "status": "sent",
  "submission_id": 187,
  "phone": "+15559876543",
  "external_id": "cust-001-updated",
  "opened_at": null,
  "sent_at": "2026-04-08T10:31:01.000Z",
  "completed_at": null,
  "declined_at": null,
  "values": {
    "full_name": "Jane M. Smith",
    "agreement_date": "2026-04-08",
    "payment_method": "Credit Card",
    "address_line_1": "456 Oak Ave",
    "city": "Portland",
    "state": "OR",
    "zip_code": "97201"
  },
  "metadata": {
    "source": "website_checkout",
    "session_id": "sess_abc123",
    "updated_by": "admin"
  },
  "preferences": {
    "send_email": true,
    "sign_mode": "normal"
  }
}

Updatable fields

Field	Type	Notes
`name`	string	Update the submitter’s display name.
`email`	string	Change the email address. If the invitation has been sent, use resend to send to the new address.
`phone`	string	Phone number in E.164 format.
`external_id`	string	Your custom identifier.
`metadata`	object	Replaces the entire metadata object. Merge existing values client-side if you want to preserve them.
`values`	object	Merges with existing values. Only the keys you provide are updated; other pre-filled values are preserved.

You cannot update a submitter whose status is completed, declined, or expired. The API returns a 422 Unprocessable Entity error for updates to finalized submitters.

Resending invitations

If a submitter has not received or has lost their invitation email, resend it:

curl -X POST "$DOCUTRUST_URL/api/submitters/301/resend" \
  -H "X-Auth-Token: $DOCUTRUST_TOKEN"

await fetch(`${process.env.DOCUTRUST_URL}/api/submitters/301/resend`, {
  method: "POST",
  headers: { "X-Auth-Token": process.env.DOCUTRUST_TOKEN },
});

import requests
import os

url = f"{os.environ['DOCUTRUST_URL']}/api/submitters/301/resend"
headers = {"X-Auth-Token": os.environ["DOCUTRUST_TOKEN"]}
response = requests.post(url, headers=headers)

Response:

{
  "message": "Invitation resent successfully",
  "submitter_id": 301,
  "email": "jane@example.com",
  "sent_at": "2026-04-08T14:00:00.000Z"
}

Resending updates the sent_at timestamp. You can only resend to submitters in sent or opened status. Submitters in waiting status have not yet reached their turn in sequential signing.

External ID mapping

The external_id field lets you associate a submitter with a record in your own system — a CRM contact, a user account, an order ID, or any other identifier.

Setting external IDs at creation

{
  "submitters": [
    {
      "role": "Client",
      "email": "jane@example.com",
      "external_id": "crm_contact_12345"
    }
  ]
}

Looking up by external ID

curl "$DOCUTRUST_URL/api/submitters?external_id=crm_contact_12345" \
  -H "X-Auth-Token: $DOCUTRUST_TOKEN"

This returns all submitters with the matching external ID across all submissions. Use this to check if a specific contact has any pending or completed signing requests.

Common patterns

Use case	External ID format	Example
CRM integration	CRM contact ID	`crm_contact_12345`
User account mapping	Your app’s user ID	`user_98765`
Order processing	Order or invoice number	`order_2026-0042`
HR onboarding	Employee ID	`emp_HR-2026-001`
Multi-system tracking	Composite key	`salesforce:0015000000ABC123`

Signing links

Each submitter has a unique signing link constructed from their slug:

https://spitshake.io/s/{slug}

For example, submitter with slug r7t2q9v4 signs at https://spitshake.io/s/r7t2q9v4.

When to use direct links

Embedded flows: Generate the signing URL server-side and redirect the user, or embed it in an iframe.
Custom emails: If you handle email delivery yourself (with send_email: false), include this link in your email templates.
In-app signing: Open the signing link in a modal or new tab within your application.

For production embedded signing, consider using JWT bearer tokens with the DocuTrust JavaScript SDK instead of raw signing links. JWTs provide scoped access control and do not expose permanent signing URLs.

Getting Started

Core Guides

Embedding

Features

Security & Compliance

Legal

Submitter object

Full submitter object

Additional fields in the detail response

Status lifecycle

Status transitions

Listing submitters

Filter parameters

Filter by submission

Filter by external ID

Retrieving a submitter

Updating a submitter

Updatable fields

Resending invitations

External ID mapping

Setting external IDs at creation

Looking up by external ID

Common patterns

Signing links

When to use direct links

​Submitter object

​Full submitter object

​Additional fields in the detail response

​Status lifecycle

​Status transitions

​Listing submitters

​Filter parameters

​Filter by submission

​Filter by external ID

​Retrieving a submitter

​Updating a submitter

​Updatable fields

​Resending invitations

​External ID mapping

​Setting external IDs at creation

​Looking up by external ID

​Common patterns

​Signing links

​When to use direct links

Submitter object

Full submitter object

Additional fields in the detail response

Status lifecycle

Status transitions

Listing submitters

Filter parameters

Filter by submission

Filter by external ID

Retrieving a submitter

Updating a submitter

Updatable fields

Resending invitations

External ID mapping

Setting external IDs at creation

Looking up by external ID

Common patterns

Signing links

When to use direct links