Audit Log API

The Audit Log API provides read access to your workspace's immutable activity history. Every significant event — document creation, signing, recipient changes, member activity, and setting changes — is recorded in chronological order.

Use the audit log for compliance reporting, security investigations, and integration with your own SIEM or logging infrastructure.

The Audit Log Entry Object

Attributes

Attribute	Type	Description
`id`	string	Unique audit log entry ID
`action`	string	The action performed (see Action Types below)
`actor_type`	string	Who performed it: `user`, `recipient`, or `system`
`actor_name`	string	Display name of the actor (optional)
`actor_email`	string	Email of the actor (optional)
`resource_type`	string	Type of resource affected: `document`, `recipient`, `member`, etc.
`resource_id`	string	ID of the affected resource (optional)
`document_id`	string	Document ID if the event is document-related (optional)
`ip_address`	string	IP address of the actor
`source`	string	Where the action originated: `web`, `api`, or `system`
`created_at`	string	ISO 8601 timestamp of the event

Example Object

{
  "id": "log_abc123",
  "action": "document.sent",
  "actor_type": "user",
  "actor_name": "Alice Johnson",
  "actor_email": "alice@example.com",
  "resource_type": "document",
  "resource_id": "jd7k8l9m0n1p2q3r4s5t6u7v",
  "document_id": "jd7k8l9m0n1p2q3r4s5t6u7v",
  "ip_address": "203.0.113.42",
  "source": "web",
  "created_at": "2024-01-27T10:31:00Z"
}

Action Types

Document Actions

Action	Description
`document.created`	New document uploaded
`document.updated`	Document metadata changed
`document.deleted`	Document permanently deleted
`document.sent`	Document sent to recipients for signing
`document.viewed`	Document opened
`document.completed`	All required signatures collected
`document.cancelled`	Document voided by sender
`document.expired`	Document expired before completion
`document.ownership_transferred`	Document reassigned to a new owner

Recipient Actions

Action	Description
`recipient.added`	Recipient added to a document
`recipient.updated`	Recipient details changed
`recipient.removed`	Recipient removed from a document
`recipient.viewed`	Recipient opened the signing link
`recipient.signed`	Recipient completed signing
`recipient.declined`	Recipient declined to sign
`recipient.esign_consent`	Recipient accepted ESIGN consent
`recipient.esign_opt_out`	Recipient declined ESIGN consent
`recipient.expired`	Recipient's signing deadline passed

Member & Organization Actions

Action	Description
`member.invited`	User invited to workspace
`member.joined`	User accepted invitation
`member.removed`	User removed from workspace
`member.role_changed`	Member role updated
`organization.updated`	Workspace settings changed

List Audit Log

Retrieve a paginated, filterable list of audit log entries for your workspace.

Endpoint

GET /api/v1/audit-log

Required Scope

seal:audit:read

Query Parameters

Parameter	Type	Description
`limit`	number	Number of results (max 100, default 20)
`cursor`	string	Pagination cursor from previous response
`document_id`	string	Filter entries related to a specific document
`action`	string	Filter by exact action name (e.g., `document.sent`)
`created_after`	number	Unix timestamp (ms) — only return entries after this
`created_before`	number	Unix timestamp (ms) — only return entries before this

Entries are returned in reverse chronological order (newest first).

TypeScript Example

// Get all audit log entries for a specific document
const response = await fetch(
  "https://seal.convex.site/api/v1/audit-log?document_id=jd7k8l9m0n1p2q3r4s5t6u7v&limit=50",
  {
    headers: {
      Authorization: "Bearer ak_your_api_key_here",
    },
  },
);

const { entries, has_more, next_cursor } = await response.json();

cURL Example

# Get signing events from the last 24 hours
YESTERDAY=$(date -u -d '1 day ago' +%s000 2>/dev/null || date -u -v-1d +%s000)

curl -X GET "https://seal.convex.site/api/v1/audit-log?action=recipient.signed&created_after=${YESTERDAY}" \
  -H "Authorization: Bearer ak_your_api_key_here"

Response

{
  "entries": [
    {
      "id": "log_xyz789",
      "action": "recipient.signed",
      "actor_type": "recipient",
      "actor_name": "John Doe",
      "actor_email": "john@example.com",
      "resource_type": "recipient",
      "resource_id": "rec_abc123",
      "document_id": "jd7k8l9m0n1p2q3r4s5t6u7v",
      "ip_address": "198.51.100.10",
      "source": "web",
      "created_at": "2024-01-27T11:00:00Z"
    },
    {
      "id": "log_def456",
      "action": "document.sent",
      "actor_type": "user",
      "actor_name": "Alice Johnson",
      "actor_email": "alice@example.com",
      "resource_type": "document",
      "resource_id": "jd7k8l9m0n1p2q3r4s5t6u7v",
      "document_id": "jd7k8l9m0n1p2q3r4s5t6u7v",
      "ip_address": "203.0.113.42",
      "source": "api",
      "created_at": "2024-01-27T10:31:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Compliance Export Example

// Export all audit log entries for a date range to a SIEM
async function exportAuditLog(fromMs: number, toMs: number) {
  const entries = [];
  let cursor: string | undefined;

  do {
    const params = new URLSearchParams({
      limit: "100",
      created_after: String(fromMs),
      created_before: String(toMs),
      ...(cursor ? { cursor } : {}),
    });

    const response = await fetch(
      `https://seal.convex.site/api/v1/audit-log?${params}`,
      { headers: { Authorization: "Bearer ak_your_api_key_here" } },
    );

    const data = await response.json();
    entries.push(...data.entries);
    cursor = data.has_more ? data.next_cursor : undefined;
  } while (cursor);

  return entries;
}

Next Steps

Analytics API - Aggregated metrics and trends
Documents API - Manage documents
Webhooks - Real-time event notifications

Audit Log API

On this page