> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wolfia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Trust Center Analytics API: Engagement & Revenue

> Retrieve trust center engagement, document interactions, revenue attribution, and access-request data via the Wolfia API, for custom dashboards and BI tools.

## Overview

Retrieve engagement data, document interactions, revenue attribution, and access requests for your trust center. Use these endpoints to build custom dashboards, generate reports, or feed data into your BI tools.

All analytics endpoints accept optional date range filters and return data scoped to your organization.

## Common parameters

All analytics endpoints share these query parameters:

| Parameter    | Type    | Required | Description                                      |
| ------------ | ------- | -------- | ------------------------------------------------ |
| `start_date` | integer | No       | Start of date range (microsecond Unix timestamp) |
| `end_date`   | integer | No       | End of date range (microsecond Unix timestamp)   |

<Note>
  **Timestamps use microseconds.** Multiply Unix seconds by 1,000,000.

  ```python theme={null}
  from datetime import datetime
  start_date = int(datetime(2025, 1, 1).timestamp() * 1_000_000)
  ```
</Note>

## Portal overview

**URL:** `GET https://api.wolfia.com/v1/trustportal/analytics`

**Authentication:** API key required, Admin role (see [API overview](/how-to/api-overview))

Returns comprehensive analytics including access requests, portal views, document stats, and top documents and accounts.

### Request

```bash theme={null}
curl -X GET 'https://api.wolfia.com/v1/trustportal/analytics?start_date=1735689600000000&end_date=1738368000000000' \
  -H "X-API-Key: wolfia-api-YOUR_KEY_HERE"
```

### Query parameters

| Parameter    | Type | Required | Description                  |
| ------------ | ---- | -------- | ---------------------------- |
| `account_id` | UUID | No       | Filter to a specific account |

### Response (200 OK)

```json theme={null}
{
  "access_requests": {
    "total": 45,
    "approved": 38,
    "rejected": 1,
    "pending": 5,
    "revoked": 0,
    "auto_approved": 22,
    "approval_rate": 96.3,
    "avg_time_to_decision_ms": 12639.14
  },
  "portal_views": {
    "total_views": 1250
  },
  "document_metrics": {
    "total_interactions": 340
  },
  "top_documents": [
    {
      "document_id": "doc-uuid",
      "document_title": "SOC 2 Type II Report",
      "document_type": "file",
      "views": 210,
      "downloads": 85,
      "link_opens": 0,
      "total_interactions": 295
    }
  ],
  "top_accounts": [
    {
      "account_id": "account-uuid",
      "name": "Enterprise Corp",
      "domain": "enterprise.com",
      "logo_url": null,
      "total_views": 15,
      "total_document_interactions": 45,
      "revenue_associated": 100000.0
    }
  ],
  "time_period": {
    "start_date": 1735689600000000,
    "end_date": 1738368000000000
  }
}
```

## Document interactions

**URL:** `GET https://api.wolfia.com/v1/trustportal/analytics/documents`

**Authentication:** API key required, Expert or Admin role

Returns paginated document interaction metrics including views, downloads, and unique viewers.

### Request

```bash theme={null}
# All documents
curl -X GET 'https://api.wolfia.com/v1/trustportal/analytics/documents?page=1&page_size=20' \
  -H "X-API-Key: wolfia-api-YOUR_KEY_HERE"

# Filtered to a specific account
curl -X GET 'https://api.wolfia.com/v1/trustportal/analytics/documents?account_id=ACCOUNT_UUID_HERE&page=1&page_size=20' \
  -H "X-API-Key: wolfia-api-YOUR_KEY_HERE"
```

### Query parameters

| Parameter    | Type    | Required | Default | Description                   |
| ------------ | ------- | -------- | ------- | ----------------------------- |
| `account_id` | UUID    | No       | -       | Filter to a specific account  |
| `page`       | integer | No       | 1       | Page number (starting from 1) |
| `page_size`  | integer | No       | 20      | Items per page (1-100)        |

## Document interactions by revenue

**URL:** `GET https://api.wolfia.com/v1/trustportal/analytics/documents/by-revenue`

**Authentication:** API key required, Admin role

Returns document interactions sorted by revenue attribution. Requires a CRM integration (Salesforce or HubSpot).

### Request

```bash theme={null}
curl -X GET 'https://api.wolfia.com/v1/trustportal/analytics/documents/by-revenue?page=1&page_size=20' \
  -H "X-API-Key: wolfia-api-YOUR_KEY_HERE"
```

## Document detail analytics

**URL:** `GET https://api.wolfia.com/v1/trustportal/analytics/documents/{document_id}`

**Authentication:** API key required, Admin role

Returns detailed analytics for a specific document including recent activity and top accounts.

### Request

```bash theme={null}
curl -X GET 'https://api.wolfia.com/v1/trustportal/analytics/documents/DOC_UUID_HERE' \
  -H "X-API-Key: wolfia-api-YOUR_KEY_HERE"
```

### Query parameters

| Parameter        | Type    | Required | Default | Description                        |
| ---------------- | ------- | -------- | ------- | ---------------------------------- |
| `activity_limit` | integer | No       | 20      | Max recent activity events (1-100) |
| `account_limit`  | integer | No       | 10      | Max top accounts (1-50)            |

## Active accounts

**URL:** `GET https://api.wolfia.com/v1/trustportal/analytics/accounts`

**Authentication:** API key required, Admin role

Returns paginated accounts with their interaction metrics (views, downloads, access requests).

### Request

```bash theme={null}
curl -X GET 'https://api.wolfia.com/v1/trustportal/analytics/accounts?page=1&page_size=20' \
  -H "X-API-Key: wolfia-api-YOUR_KEY_HERE"
```

### Query parameters

| Parameter   | Type    | Required | Default | Description            |
| ----------- | ------- | -------- | ------- | ---------------------- |
| `page`      | integer | No       | 1       | Page number            |
| `page_size` | integer | No       | 20      | Items per page (1-100) |

## Revenue metrics

**URL:** `GET https://api.wolfia.com/v1/trustportal/analytics/revenue`

**Authentication:** API key required, Admin role

Returns revenue attribution metrics showing the trust center's impact on sales pipeline. Requires a CRM integration.

### Request

```bash theme={null}
curl -X GET 'https://api.wolfia.com/v1/trustportal/analytics/revenue?start_date=1735689600000000' \
  -H "X-API-Key: wolfia-api-YOUR_KEY_HERE"
```

## Account revenue metrics

**URL:** `GET https://api.wolfia.com/v1/trustportal/analytics/revenue/{account_id}`

**Authentication:** API key required, Admin role

Returns revenue metrics for a specific account including opportunities and deal stages.

### Request

```bash theme={null}
curl -X GET 'https://api.wolfia.com/v1/trustportal/analytics/revenue/ACCOUNT_UUID_HERE' \
  -H "X-API-Key: wolfia-api-YOUR_KEY_HERE"
```

## Top won deals

**URL:** `GET https://api.wolfia.com/v1/trustportal/analytics/top-won-deals`

**Authentication:** API key required, Admin role

Returns top accounts ranked by won deal revenue. Requires a CRM integration.

### Request

```bash theme={null}
curl -X GET 'https://api.wolfia.com/v1/trustportal/analytics/top-won-deals?page=1&page_size=20' \
  -H "X-API-Key: wolfia-api-YOUR_KEY_HERE"
```

### Query parameters

| Parameter   | Type    | Required | Default | Description            |
| ----------- | ------- | -------- | ------- | ---------------------- |
| `page`      | integer | No       | 1       | Page number            |
| `page_size` | integer | No       | 20      | Items per page (1-100) |

## Top open deals

**URL:** `GET https://api.wolfia.com/v1/trustportal/analytics/top-open-deals`

**Authentication:** API key required, Admin role

Returns top accounts ranked by open deal pipeline revenue. Requires a CRM integration.

### Request

```bash theme={null}
curl -X GET 'https://api.wolfia.com/v1/trustportal/analytics/top-open-deals?page=1&page_size=20' \
  -H "X-API-Key: wolfia-api-YOUR_KEY_HERE"
```

## Access requests

**URL:** `GET https://api.wolfia.com/v1/trustportal/access`

**Authentication:** API key required, Admin role

Returns a paginated list of access requests submitted to your trust portal.

### Request

```bash theme={null}
# All access requests
curl -X GET 'https://api.wolfia.com/v1/trustportal/access?status_filter=PENDING&limit=100' \
  -H "X-API-Key: wolfia-api-YOUR_KEY_HERE"

# Filtered to a specific account, sorted by company name
curl -X GET 'https://api.wolfia.com/v1/trustportal/access?account_id=ACCOUNT_UUID_HERE&sort_by=company_name&sort_order=asc' \
  -H "X-API-Key: wolfia-api-YOUR_KEY_HERE"
```

### Query parameters

| Parameter       | Type            | Required | Default        | Description                                                                                            |
| --------------- | --------------- | -------- | -------------- | ------------------------------------------------------------------------------------------------------ |
| `limit`         | integer (1-100) | No       | 10             | Page size                                                                                              |
| `offset`        | integer         | No       | 0              | Pagination offset                                                                                      |
| `status_filter` | string          | No       | all            | `PENDING` for pending only, `PROCESSED` for non-pending                                                |
| `search`        | string          | No       | -              | Search by name, email, or company                                                                      |
| `account_id`    | UUID            | No       | -              | Filter to a specific account                                                                           |
| `sort_by`       | string          | No       | `requested_at` | Sort field: `contact_name`, `email`, `company_name`, `reason`, `status`, `requested_at`, `approved_at` |
| `sort_order`    | string          | No       | `desc`         | Sort direction: `asc` or `desc`                                                                        |

### Response (200 OK)

```json theme={null}
{
  "access_requests": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "contact_name": "Jane Doe",
      "email": "jane@acme.com",
      "company_name": "Acme Corp",
      "reason": "SECURITY_REVIEW",
      "status": "PENDING",
      "requested_at": 1735689600000000,
      "approved_at": null,
      "auto_approved": false
    }
  ],
  "total_count": 42,
  "limit": 100,
  "offset": 0,
  "sort_by": "requested_at",
  "sort_order": "desc"
}
```

## Integration example

```python theme={null}
import os
from datetime import datetime, timedelta

import requests

API_KEY = os.environ['WOLFIA_API_KEY']
BASE_URL = 'https://api.wolfia.com/v1'


def get_weekly_analytics():
    """Fetch trust portal analytics for the last 7 days."""
    headers = {'X-API-Key': API_KEY}

    end = datetime.now()
    start = end - timedelta(days=7)
    params = {
        'start_date': int(start.timestamp() * 1_000_000),
        'end_date': int(end.timestamp() * 1_000_000),
    }

    overview = requests.get(
        f'{BASE_URL}/trustportal/analytics',
        headers=headers,
        params=params,
        timeout=30,
    )
    overview.raise_for_status()

    documents = requests.get(
        f'{BASE_URL}/trustportal/analytics/documents',
        headers=headers,
        params={**params, 'page_size': 10},
        timeout=30,
    )
    documents.raise_for_status()

    return {
        'overview': overview.json(),
        'documents': documents.json(),
        'period': f"{start.strftime('%b %d')} - {end.strftime('%b %d, %Y')}",
    }


if __name__ == '__main__':
    data = get_weekly_analytics()
    print(f"Portal views: {data['overview']['portal_views']['total_views']}")
    print(f"Total access requests: {data['overview']['access_requests']['total']}")
```

## Error responses

| Status | Meaning                                 | Solution                                                      |
| ------ | --------------------------------------- | ------------------------------------------------------------- |
| 400    | Invalid ID format                       | Ensure `account_id` is a valid UUID                           |
| 401    | Invalid API key                         | Verify your API key is correct                                |
| 403    | Insufficient permissions or missing CRM | Ensure Admin role. For revenue endpoints, connect a CRM first |
| 404    | Resource not found                      | Verify the resource ID exists                                 |
| 422    | Invalid parameters                      | Check timestamps are in microseconds and IDs are valid UUIDs  |
| 500    | Server error                            | Retry with exponential backoff                                |

## Next steps

<CardGroup cols={2}>
  <Card title="Trust portal updates" icon="megaphone" href="/how-to/api-trust-portal-updates">
    Create and manage trust center update notifications
  </Card>

  <Card title="API overview" icon="code" href="/how-to/api-overview">
    Learn about API authentication and best practices
  </Card>
</CardGroup>