Skip to main content
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. 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.

​
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": "alice@example.com" },
      "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": "alice@example.com" },
      "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": "alice@example.com" },
      "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": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}

​
Response fields

FieldTypeDescription
iduuidEvent ID
timestampdatetimeWhen the event occurred
sourcestring"signer" or "admin"
eventstringEvent type identifier (see event reference below)
descriptionstringHuman-readable event description
actorobject | nullWho performed the action (see below)
ip_addressstring | nullSigner’s IP address (signer events only)
detailsobject | nullEvent-specific metadata
condensed_countintegerPresent 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": "alice@example.com" },
  "ip_address": "203.0.113.42"
}

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

​
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

EventDescriptionHas details
document_openedOpened the documentNo
document_viewedViewed the documentNo
document_savedSaved field valuesNo
document_finishedCompleted signingNo
document_signedSigned the documentNo
document_hiddenLeft the pageNo
document_visibleReturned to the pageNo
document_closedClosed the documentNo

​
Signature and verification

EventDescriptionHas details
signature_finalizedSignature finalizedNo
signing_declinedDeclined to signNo
terms_acceptedAccepted terms and conditionsNo
otp_verifiedVerified identity via OTPNo
certificate_downloadDownloaded the certificateNo

​
Field interactions

Field interactions are tracked as field_interaction events. The details object contains the specific action and field metadata.
ActionDescription
field_focusedSelected a field
field_completedCompleted a field for the first time
field_modifiedModified an existing field value
field_clearedCleared a field value
field_blurFinished editing a field
The details object for field interactions includes:
FieldTypeDescription
field_typestringType of field (signature, text, date, etc.)
actionstringThe specific action from the table above
interaction_countintegerNumber of times this field has been interacted with
value_lengthintegerLength of the field value (when applicable)
time_spent_msintegerTime spent on the field in milliseconds (when applicable)
EventDescriptionHas details
page_viewedViewed a specific pageYes — page_number
document_scrolledScrolled to a pageYes — page_number
navigation_actionNavigated the documentYes — action (next_page, prev_page, go_to_page)
zoom_changedChanged zoom levelNo
modal_interactionOpened or closed a dialogYes — modal_type, action

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