---
title: Audit Log API
description: Access the complete tamper-evident activity history for your workspace
---

# 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](#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

```json
{
  "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 |

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

### TypeScript Example

```typescript
// Get all audit log entries for a specific document
const response = await fetch(
  "https://api.seal.nyc/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

```bash
# 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://api.seal.nyc/api/v1/audit-log?action=recipient.signed&created_after=${YESTERDAY}" \
  -H "Authorization: Bearer ak_your_api_key_here"
```

### Response

```json
{
  "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

```typescript
// 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://api.seal.nyc/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](/docs/api-reference/analytics)** - Aggregated metrics and trends
- **[Documents API](/docs/api-reference/documents)** - Manage documents
- **[Webhooks](/docs/webhooks)** - Real-time event notifications