Identity claim events API reference

When an auditor reviews a registered identity, one question decides whether they can trust its current claims: how did those claims get here? The identity claim events endpoint answers it. It lists every claim lifecycle event recorded for one identity contract, in order, so a reviewer can trace each claim from the moment it was added through any change, removal, or revocation. Each event carries the claim topic, the claim id, the block and transaction that recorded it, and the addresses that emitted and sent it.

The endpoint is read-only. It reports the indexed history that the identity already produced on chain. It does not issue, change, or revoke claims. To issue a claim, use POST /api/v2/system/identity-claims. To revoke a claim, use POST /api/v2/system/identity-claim-revocations. For authentication and base URL setup, see Getting started.

Endpoint

The endpoint uses the collection envelope: data holds the page of events, meta carries the total count and facet breakdowns, and links carries pagination links. The active organization and system context bound every read, as described in Organization and system scope.

The {identityAddress} path parameter is the on-chain identity contract address whose history you want. The identity must be registered in the active system's identity registry. A request for an identity the registry does not track returns a not-found error rather than an empty list, so an empty page always means the identity exists and has no matching events. To find the identity addresses registered in your system, list them with Registered identities, where the id field of each row is the identity contract address you pass here.

curl --globoff \
  "https://your-platform.example.com/api/v2/system/identities/0x71C7656EC7ab88b098defB751B7401B5f6d8976F/claim-events" \
  -H "x-api-key: YOUR_API_KEY"

{
  "data": [
    {
      "id": "0xabc123...-0",
      "eventName": "ClaimAdded",
      "topic": "1",
      "claimId": "0xbb...",
      "blockNumber": "12345678",
      "blockTimestamp": "2024-01-15T10:30:00.000Z",
      "transactionHash": "0xabc123...",
      "emitter": { "id": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F" },
      "sender": { "id": "0x2546BcD3c84621e976D8185a91A922aE77ECEc30" },
      "values": [
        { "id": "val-0", "name": "topic", "value": "1" },
        { "id": "val-1", "name": "issuer", "value": "0x2546bcd3c84621e976d8185a91a922ae77ecec30" }
      ]
    }
  ],
  "meta": {
    "total": 1,
    "facets": {
      "topic": [{ "value": "1", "count": 1 }],
      "eventName": [{ "value": "ClaimAdded", "count": 1 }]
    }
  },
  "links": {
    "self": "/v2/system/identities/0x71c7656ec7ab88b098defb751b7401b5f6d8976f/claim-events?sort=-blockTimestamp&page[offset]=0&page[limit]=50",
    "first": "/v2/system/identities/0x71c7656ec7ab88b098defb751b7401b5f6d8976f/claim-events?sort=-blockTimestamp&page[offset]=0&page[limit]=50",
    "prev": null,
    "next": null,
    "last": "/v2/system/identities/0x71c7656ec7ab88b098defb751b7401b5f6d8976f/claim-events?sort=-blockTimestamp&page[offset]=0&page[limit]=50"
  }
}

Event types

Each event names the lifecycle change the identity recorded. The eventName field carries one of these values, and you can filter on it.

Read the events as an ordered trail rather than a current state. A topic that shows a ClaimAdded followed later by a ClaimRevoked means the claim was issued and then revoked, which is exactly the kind of sequence an audit needs to see. For the current trust posture of an identity, including active, revoked, and untrusted claim totals, see Registered identities.

Event fields

Each row describes one claim lifecycle event.

Decoded values

The values array holds the decoded arguments the event carried, as ordered name and value pairs. An entry appears only when the underlying event recorded that argument, so a given event may include some or all of the following names:

Use the issuer value to confirm which issuer stands behind a claim and the signature and data values to reconcile a claim against the issuer's records during an audit.

Query controls

The {identityAddress} in the path scopes every read to one identity, so it is not a filter. The meta.facets block reports counts for the topic and eventName values across the current filtered set, so an interface can show option badges without a second call. The counts reflect the active filters.

Who can read claim events

Reading the claim events list requires an authenticated session in the active system context. The same data backs the Console identity detail view, so an operator can confirm an identity's claim history there before calling the endpoint from an integration.

Related pages

• Compliance API route map
• Registered identities
• Identity recovery API
• Claims and identity