Audit Trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include Signing Request ID: <id> near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

• Compliance and legal evidence — prove who signed what, when, and from where
• Debugging signer issues — see exactly what a recipient did during their signing session
• Internal reporting — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

• Signer events — document views, field interactions, signing, declining, certificate downloads
• Admin events — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer’s IP address.

Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the Audit Trail tab. You’ll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

Authentication on the completion certificate

Every signer row on the completion certificate carries an Authentication: line that reads Email Link or Email Link + One-Time Code. For a code signer, the line ends with (code verified <time>), the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or Mixed (see signers) when the signers differ. The code time can precede the Viewed time printed above it, because the signer enters the code before the document loads.

Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

GET /signing-requests/{id}/audit

curl

curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"

Node.js

const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);

Python

import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]

Example response

{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "[e-mail]" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "[e-mail]" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "[e-mail]" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "[e-mail]" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}

Response fields

Field	Type	Description
id	uuid	Event ID
timestamp	datetime	When the event occurred
source	string	"signer" or "admin"
event	string	Event type identifier (see event reference below)
description	string	Human-readable event description
actor	object | null	Who performed the action (see below)
ip_address	string | null	Signer’s IP address (signer events only)
details	object | null	Event-specific metadata
condensed_count	integer	Present when consecutive identical events from the same actor are grouped

Understanding event sources

The source field tells you whether an event came from a signer or an admin, and the actor field has a different shape for each.

Signer events

Events with source: "signer" are actions taken by recipients during the signing flow. The actor object contains the signer’s name and email. The ip_address field is populated.

{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "[e-mail]" },
  "ip_address": "203.0.113.42"
}

Organization seal events (organization_seal_*) use source: "signer" with actor and ip_address set to null. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and details holds the seal’s data.

Admin events

Events with source: "admin" are actions taken via the dashboard or API. The actor object contains a type field ("api_key" or "user") and optionally a user_id. The ip_address field is null.

{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}

{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}

Three admin actions write these descriptions:

• Cancel from the dashboard: Signing Request Cancellation requested
• Delete from the dashboard: Signing Request Deletion requested
• Certificate retry: Certificate regeneration requested

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. “Requested” records the request; it does not confirm completion. Rows written before API v1.40.3 keep the old wording (Signing Request Cancelled / Signing Request Deleted).

Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the Webhooks guide for setup instructions.

Event reference

Document lifecycle

Event	Description	Has details
document_opened	Opened the document	No
document_viewed	Viewed the document	No
document_saved	Saved field values	No
document_finished	Completed signing	Yes: otp_code_id (code signers only)
document_signed	Signed the document	No
document_hidden	Left the page	No
document_visible	Returned to the page	No
document_closed	Closed the document	No

Signature and verification

Event	Description	Has details
signature_finalized	Signature finalized	No
signing_declined	Declined to sign	No
terms_accepted	Accepted terms and conditions	No
otp_verified	Entered the one-time code sent by email	Yes: channel, otp_code_id
certificate_download	Downloaded the certificate	No

Two events identify the verified one-time code by its record ID (otp_code_id) in details; the code itself is not included:

• otp_verified: {"channel": "email", "otp_code_id": "<uuid>"}
• document_finished: {"otp_code_id": "<uuid>"}, present when the finishing session was linked to a verified code

Field interactions

Field interactions are tracked as field_interaction events. The details object contains the specific action and field metadata.

Action	Description
field_focused	Selected a field
field_completed	Completed a field for the first time
field_modified	Modified an existing field value
field_cleared	Cleared a field value
field_blur	Finished editing a field

The details object for field interactions includes:

Field	Type	Description
field_type	string	Type of field (signature, text, date, etc.)
action	string	The specific action from the table above
interaction_count	integer	Number of times this field has been interacted with
value_length	integer	Length of the field value (when applicable)
time_spent_ms	integer	Time spent on the field in milliseconds (when applicable)

Navigation

Event	Description	Has details
page_viewed	Viewed a specific page	Yes — page_number
document_scrolled	Scrolled to a page	Yes — page_number
navigation_action	Navigated the document	Yes — action (next_page, prev_page, go_to_page)
zoom_changed	Changed zoom level	No
modal_interaction	Opened or closed a dialog	Yes — modal_type, action

Organization seals

Firma.dev records these events for an organization seal on the request when it is applied, paused, swapped, or repinned.

Event	Description	Has details
organization_seal_applied	organization seal applied	Yes: seal_id, seal_name, display_name, authority_name, company_name, signatory_name, signatory_title_attested, version, order, trigger (at_send or completion)
organization_seal_paused	organization seal paused	Yes: reason (seal_revoked_stop_pending or seal_integrity_mismatch), seal_id, seal_name, order
organization_seal_swapped	organization seal swapped	Yes: from_seal_id, from_name, to_seal_id, to_name, order
organization_seal_repinned	organization seal repinned	Yes: prior_pinned_seal_id, new_seal_id

Admin activity

Admin events use event: "activity" with a human-readable description field that describes the action taken (e.g., “Created signing request via API”, “Sent signing request”, “Cancelled signing request”).