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

# Credential Activity

### Description

Returns what people did with your credentials: views, shares, downloads and clicks. Each event is one row, oldest first. Use it to build your own engagement reports.

You can ask for up to 31 days at a time. For a longer period, make one call for each month.

You can also call it with `GET` and send the parameters in the query string, for example `?from=2026-03-01&to=2026-03-31&event=view,share`.

### Headers

**Authorization** `string` *required*

Your API key: `Bearer YOUR_API_KEY`. Create a key in the Studio under **Settings → Developers**.

### Body Parameters

**from** `string` *required*

First day, as `YYYY-MM-DD` (UTC). The day is included.

**to** `string` *required*

Last day, as `YYYY-MM-DD` (UTC). The day is included. It must not be before `from`, and the range can be 31 days at most.

**event** `array[string]`

The kinds of event to return. Default: all of them.

* `view`: someone opened the credential's page.
* `share`: someone shared the credential, for example to LinkedIn.
* `download`: someone downloaded the credential as a PDF.
* `click`: any other click, such as verify, add to wallet or the group's link. It also counts the recipient opening the credential email.

You can also send them as one string, separated by commas: `"view,share"`.

**group\_key** `string`

Only events of credentials in this group.

**credential\_key** `string`

Only events of this credential (its `document_id`). If you also send `group_key`, the credential must be in that group.

**page** `number` (default: 1)

Page number. Starts at `1`.

**page\_size** `number` (default: 100)

How many events on each page. From 1 to 500.

### Success Response Fields

**success** `boolean`

`true` when the request worked.

**from** `string`

First day of the range, as `YYYY-MM-DD`.

**to** `string`

Last day of the range, as `YYYY-MM-DD`.

**page** `number`

The page number of this response.

**page\_size** `number`

The page size used.

**total** `number`

Number of events in the range, on all pages.

**events** `array[object]`

The events on this page, oldest first.

**event**

**time** `string`

When it happened, in UTC, such as `2026-03-16T08:12:45Z`.

**event** `string`

`view`, `share`, `download` or `click`.

**channel** `string`

More detail about the event. For a view, where the visitor came from, such as `linkedin`, or `direct` when not known. For a share, where it was shared, such as `addtolinkedin`. For a download, `pdf`. For a click, what was clicked, such as `verify`. When the recipient opened the credential email, `email-open`.

**credential** `string`

ID of the credential (`document_id`).

**group\_key** `string | null`

Key of the credential's group.

**recipient** `object | null`

The recipient's `name` and `email`.

**country** `string | null`

For a view, the visitor's country code, such as `GB`, when known. `null` for other events.

**device** `string | null`

For a view, the visitor's device, such as `iPhone` or `Mac`, when known. `null` for other events.

The visitor's IP address and city are never returned.

### Responses

```json 200 Success theme={null}
{
  "success": true,
  "from": "2026-03-01",
  "to": "2026-03-31",
  "page": 1,
  "page_size": 100,
  "total": 3,
  "events": [
    {
      "time": "2026-03-16T08:12:45Z",
      "event": "view",
      "channel": "linkedin",
      "credential": "6f1c2a8e-3b4d-4e5f-9a7b-1c2d3e4f5a6b",
      "group_key": "Kq7Zp2LmX9aB",
      "recipient": { "name": "Jane Doe", "email": "jane.doe@example.com" },
      "country": "GB",
      "device": "iPhone"
    },
    {
      "time": "2026-03-16T08:14:02Z",
      "event": "share",
      "channel": "addtolinkedin",
      "credential": "6f1c2a8e-3b4d-4e5f-9a7b-1c2d3e4f5a6b",
      "group_key": "Kq7Zp2LmX9aB",
      "recipient": { "name": "Jane Doe", "email": "jane.doe@example.com" },
      "country": null,
      "device": null
    },
    {
      "time": "2026-03-18T15:40:19Z",
      "event": "download",
      "channel": "pdf",
      "credential": "6f1c2a8e-3b4d-4e5f-9a7b-1c2d3e4f5a6b",
      "group_key": "Kq7Zp2LmX9aB",
      "recipient": { "name": "Jane Doe", "email": "jane.doe@example.com" },
      "country": null,
      "device": null
    }
  ]
}
```

```json 400 Bad date theme={null}
{
  "success": false,
  "error": "from and to are required, as dates in YYYY-MM-DD format",
  "error_code": "invalid_date"
}
```

```json 400 Range too long theme={null}
{
  "success": false,
  "error": "Date range is more than 31 days",
  "error_code": "range_too_large"
}
```

```json 400 Bad event theme={null}
{
  "success": false,
  "error": "event must be a list of: view, share, download, click",
  "error_code": "invalid_event"
}
```

```json 400 Bad page theme={null}
{
  "success": false,
  "error": "page must be 1 or more and page_size from 1 to 500",
  "error_code": "invalid_page"
}
```

```json 404 Group not found theme={null}
{
  "success": false,
  "error": "Group Not Found",
  "error_code": "group_not_found"
}
```

```json 404 Credential not found theme={null}
{
  "success": false,
  "error": "Credential Not Found",
  "error_code": "credential_not_found"
}
```

```json 403 Invalid key theme={null}
{
  "detail": "Invalid token or organization not found"
}
```

```bash theme={null}
curl -X POST "https://api.thehyperstack.com/v1/credentials/activity" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "2026-03-01",
    "to": "2026-03-31",
    "event": ["view", "share", "download"],
    "group_key": "Kq7Zp2LmX9aB",
    "page": 1,
    "page_size": 100
  }'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.