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

# List KYC Records

> Sealed KYC records your sources delivered, in every state

Lists the sealed KYC records of your instance, newest delivery first. A record is one KYC file a [KYC source](https://docs.trusset.org/endpoints/customers/list-kyc-sources.md) delivered for one wallet. This list shows the clear header of each record and where it stands. The file itself is never part of a response here: it is ciphertext until your [local tool](https://docs.trusset.org/tools/kyc-courier/overview.md) opens it. See [Sealed KYC records](https://docs.trusset.org/endpoints/customers/introduction.md#sealed-kyc-records).

| `status` | Meaning |
| - | - |
| `RECEIVED` | Delivered and waiting. Trusset holds the ciphertext until your tool opens it |
| `OPENED` | Your tool decrypted and filed the record and proved it with [Open KYC Record](https://docs.trusset.org/endpoints/customers/open-kyc-record.md). Trusset deleted the ciphertext. The record waits for your decision |
| `APPROVED` | You approved the record. While it is valid, its wallet can be listed on the whitelists bound to the source |
| `REJECTED` | You or your tool rejected the record. `rejectReason` says why |
| `REVOKED` | The source revoked the record. `revokeReason` says why |
| `EXPIRED` | `validUntil` passed while the record was `RECEIVED`, `OPENED` or `APPROVED` |
| `UNCLAIMED` | The record stayed `RECEIVED` for 30 days and was never opened |
| `SUPERSEDED` | A later record from the same source for the same wallet was approved |

A record reads `EXPIRED` from the moment `validUntil` passes. `expiredAt` and the `customer.kyc_record_expired` event follow when the expiry is recorded, shortly after.

`action` names the next step that is yours:

| `action` | Next step |
| - | - |
| `OPEN` | Open the record with your tool: `trusset-kyc open` |
| `APPROVE` | Decide on the opened record with [Approve KYC Record](https://docs.trusset.org/endpoints/customers/approve-kyc-record.md) or [Reject KYC Record](https://docs.trusset.org/endpoints/customers/reject-kyc-record.md) |
| `ADMIT` | The record is approved and its wallet is not listed on at least one bound whitelist. Call [Approve KYC Record](https://docs.trusset.org/endpoints/customers/approve-kyc-record.md) again for the transaction |
| `REMOVE` | The record is revoked or expired and its wallet is still listed on a bound whitelist with no other approved, valid record behind it. Build the removal with [Build Record Removal](https://docs.trusset.org/endpoints/customers/build-kyc-record-removal.md) |
| `null` | Nothing is waiting on you |

## Query Parameters

**status** `string`

Only records in this status, in any letter case. One value.

**walletAddress** `string`

Only records for this wallet, `0x` followed by 40 hex characters.

**sourceId** `string`

Only records this source delivered.

**customerId** `string`

Only the records of this customer: records linked to the customer record, and records for its primary wallet or any of its linked wallets, including records that are not linked to a customer yet.

**actionable** `boolean`

`true` returns only the records whose `action` is set: records waiting to be opened, decided, listed on a bound whitelist, or removed from one. It combines with the other filters. Follow `nextCursor` as usual. A page can hold fewer than `limit` records while more follow.

**limit** `integer` (default: 50)

Records per page, from 1 to 100. A larger value reads as 100, and a value that is not a positive number as 50.

**cursor** `string`

The `nextCursor` of the previous page.

## Response Fields

**data** `object`

**records** `array`

**id** `string`

The record ID. The other record endpoints take it as `recordId`.

**envelopeId** `string`

The ID the source gave the envelope, 32 hex characters.

**sourceId** `string`

The source that delivered it.

**sourceName** `string`

The source's name.

**sourceStatus** `string`

The source's status: `ACTIVE`, `PAUSED` or `REVOKED`. A record of a removed source (`REVOKED`) can still be decided, but it no longer admits its wallet to a whitelist, so its `action` is never `ADMIT`.

**walletAddress** `string`

The wallet the record is about, checksummed.

**profileKey** `string`

The verification profile the source verified under.

**status** `string`

See the table above.

**recordDigest** `string`

SHA-256 of the signed record document, 64 hex characters. Your tool checks the decrypted record against it.

**recipientKeyId** `string`

The record key the envelope is sealed to.

**verifiedAt** `string`

When the source verified the investor, as stated in the header. ISO 8601.

**validUntil** `string`

Until when the source vouches for the record.

**issuedAt** `string`

When the source sealed the envelope.

**receivedAt** `string`

When Trusset received it.

**openedAt** `string`

When your tool proved the opening, or `null`.

**approvedAt** `string`

When you approved it, or `null`.

**rejectedAt** `string`

When it was rejected, or `null`.

**rejectReason** `string`

The reason code sent with the rejection, or `null`.

**revokedAt** `string`

When the source revoked it, or `null`.

**revokeReason** `string`

`EXPIRED`, `WITHDRAWN`, `SUPERSEDED`, `INVALID` or `OTHER`, as the source stated, or `null`.

**expiredAt** `string`

When the expiry or the 30-day lapse was recorded, or `null`.

**customerId** `string`

The customer record that holds the wallet, or `null` when none does yet.

**sealedBytes** `integer`

Size of the sealed envelope in bytes: the encapsulated key plus the ciphertext.

**held** `boolean`

`true` while Trusset still stores the ciphertext.

**lists** `array`

One entry per whitelist bound to the record's source: `{ listId, name, address, listed }`. `listed` is what the whitelist's record holds for the wallet, which follows confirmed transactions and rescans. It is `null` when the whitelist record is missing.

**action** `string`

See the table above.

**nextCursor** `string`

Send it as `cursor` for the next page. `null` on the last page.

```bash cURL theme={null}
curl "https://api.trusset.org/customers/api/kyc-records?status=OPENED&limit=20" \
  -H "X-API-Key: trusset_your_key_here"
```

```typescript TypeScript theme={null}
const base = 'https://api.trusset.org/customers/api/kyc-records';
const headers = { 'X-API-Key': 'trusset_your_key_here' };

const waiting = [];
let cursor: string | null = null;
do {
  const query = new URLSearchParams({ status: 'OPENED', limit: '100' });
  if (cursor) query.set('cursor', cursor);
  const res = await fetch(`${base}?${query}`, { headers });
  const { data } = await res.json();
  waiting.push(...data.records);
  cursor = data.nextCursor;
} while (cursor);
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "records": [
      {
        "id": "cmhw3k9t20007l80c5q2x7m4d",
        "envelopeId": "75aa6ca04ca5ab4223136c3bea128de0",
        "sourceId": "cmhw2a6r10003l80c9d4h1n8v",
        "sourceName": "Hanse Haftungsdach GmbH",
        "walletAddress": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
        "profileKey": "PROFESSIONAL",
        "status": "OPENED",
        "recordDigest": "565dd632e69c3630319efbd08052d5fd1dfbdd5b1123b31e227502261fae5b9d",
        "recipientKeyId": "b9619d9be69ed903",
        "verifiedAt": "2026-11-10T00:00:00.000Z",
        "validUntil": "2027-11-10T23:59:59.999Z",
        "issuedAt": "2026-11-12T09:14:07.512Z",
        "receivedAt": "2026-11-12T09:14:09.204Z",
        "openedAt": "2026-11-12T09:40:31.870Z",
        "approvedAt": null,
        "rejectedAt": null,
        "rejectReason": null,
        "revokedAt": null,
        "revokeReason": null,
        "expiredAt": null,
        "customerId": "cmhw3m2p40009l80c1r6t8y3b",
        "sealedBytes": 240964,
        "held": false,
        "lists": [
          {
            "listId": "cmv2k8q1d0004l70a3n6p2w9e",
            "name": "Depositors Q4",
            "address": "0x7d31e6b09a4c25f8e1b73d0a6c94e2f58b1a0c37",
            "listed": false
          }
        ],
        "action": "APPROVE"
      }
    ],
    "nextCursor": null
  },
  "error": null,
  "metadata": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2026-11-12T09:45:00.000Z"
  }
}
```

## Error Codes

| Code | HTTP | Cause |
| - | - | - |
| `VALIDATION_ERROR` | `400` | `status` is not one of the eight statuses, `walletAddress` is not a wallet address, or `sourceId`, `customerId` or `cursor` is not valid. `details.field` names the parameter |
| `RATE_LIMIT_EXCEEDED` | `429` | Your instance went over its budget of 240 KYC record reads per minute. See [Rate limits](https://docs.trusset.org/endpoints/customers/introduction.md#rate-limits) |
| `LIST_KYC_RECORDS_FAILED` | `500` | The records could not be read |


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