# System claim topics API reference

Source: https://docs.settlemint.com/docs/api-reference/reference/system-claim-topics
Read the claim topics registered for the active system, including each topic's claim data shape and its authorised trusted issuers, through the DALP Platform API.



A claim topic defines a kind of verifiable claim, such as a Know Your Customer result or an accredited-investor attestation, and the data shape that claim carries. DALP compliance checks reference these topics when they decide whether a transfer or other gated operation may proceed. An auditor or compliance integration needs an authoritative view of which claim topics the active system recognises and exactly what data shape each one enforces. These endpoints provide that system-scoped view.

This surface is read-only. It lists and reads the claim topics that the active system resolves. It does not register, edit, or remove them. To create, change, or remove a topic, see [Configure trusted issuers and claim topics](/docs/developers/compliance/configure-trusted-issuers).

## How the system resolves topics [#how-the-system-resolves-topics]

A claim topic can be registered on the system's own registry or inherited from a parent registry that sits above it. These endpoints resolve the registry chain for the active system and return the topics it reads. When the same numeric topic id appears at more than one level, the registration closest to the system wins. Each topic record reports an `isGlobal` flag: `true` means the topic was inherited from a parent registry rather than registered locally.

| You want to                                                  | Use                                                                                  |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| Read the claim topics the active system recognises           | These system claim topic endpoints                                                   |
| Audit every topic scheme the whole platform recognises       | [Directory topic schemes API](/docs/api-reference/reference/directory-topic-schemes) |
| Inspect the trusted issuers authorised for the active system | [System trusted issuers API](/docs/api-reference/reference/system-trusted-issuers)   |

## Authentication [#authentication]

Set the standard request headers before calling these endpoints. Server integrations authenticate with the `X-Api-Key` header shown in the examples; browser or RPC integrations use an authenticated user session. Every read is bound to the organization and system in context, as described in [Organization and system scope](/docs/api-reference/reference/organization-system-scope). For base URL and credential setup, see [Getting started](/docs/api-reference/reference/getting-started).

## Endpoints [#endpoints]

| Endpoint                                 | Use it for                                                         |
| ---------------------------------------- | ------------------------------------------------------------------ |
| `GET /api/v2/system/claim-topics`        | List the claim topics the active system recognises.                |
| `GET /api/v2/system/claim-topics/{name}` | Read one claim topic by name, with its authorised trusted issuers. |

The list response uses the collection envelope with `data`, `meta`, and pagination `links`. The read response uses the single-resource envelope with `data` and `links.self`.

## List claim topics [#list-claim-topics]

`GET /api/v2/system/claim-topics` returns the claim topics the active system resolves, ordered by `topicId`. The list supports pagination, sorting by `topicId` or `name`, and global search with `filter[q]`, which matches across the topic name, signature, and id in one query.

```bash
curl --globoff "https://your-platform.example.com/api/v2/system/claim-topics?sort=name" \
  -H "x-api-key: YOUR_API_KEY"
```

Example response:

```json
{
  "data": [
    {
      "id": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F307831",
      "topicId": "1",
      "name": "Know Your Customer",
      "signature": "(string)",
      "registry": {
        "id": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F"
      },
      "isGlobal": false
    }
  ],
  "meta": {
    "total": 1,
    "facets": {
      "source": [{ "value": "system", "count": 1 }]
    }
  },
  "links": {
    "self": "/v2/system/claim-topics?page[offset]=0&page[limit]=50",
    "first": "/v2/system/claim-topics?page[offset]=0&page[limit]=50",
    "prev": null,
    "next": null,
    "last": "/v2/system/claim-topics?page[offset]=0&page[limit]=50"
  }
}
```

The list returns 50 topics per page by default, up to 200. Use `page[offset]` and `page[limit]` to page through larger registries.

### List item fields [#list-item-fields]

| Field       | Type    | Description                                                                                      |
| ----------- | ------- | ------------------------------------------------------------------------------------------------ |
| `id`        | string  | Synthetic identifier for the row, combining the registry address and the topic id.               |
| `topicId`   | string  | Numeric topic id as a decimal string, matching the on-chain value.                               |
| `name`      | string  | Human-readable topic name, such as `Know Your Customer`.                                         |
| `signature` | string  | ABI type list that defines the claim's data shape, such as `(string)` or `(uint256,bool)`.       |
| `registry`  | object  | The topic scheme registry that holds the topic, as `{ "id": "0x..." }`.                          |
| `isGlobal`  | boolean | `true` when the topic was inherited from a parent registry rather than registered on the system. |

The `signature` is the contract that claims for this topic must satisfy. The `meta.facets.source` breakdown counts how many returned topics are registered on the system itself against how many are inherited from a parent registry. A reviewer reads that breakdown to see how much of the topic set is local against inherited.

## Read one claim topic [#read-one-claim-topic]

`GET /api/v2/system/claim-topics/{name}` returns a single topic by name, resolved across the system's registry chain with the system's own registration preferred over a parent's. The response adds the trusted issuers currently authorised to attest claims for that topic.

```bash
curl "https://your-platform.example.com/api/v2/system/claim-topics/knowYourCustomer" \
  -H "x-api-key: YOUR_API_KEY"
```

Example response:

```json
{
  "data": {
    "id": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F307831",
    "topicId": "1",
    "name": "knowYourCustomer",
    "signature": "(string)",
    "trustedIssuers": [
      {
        "id": "0x2546BcD3c84621e976D8185a91A922aE77ECEc30",
        "addedAt": "2026-04-01T12:00:00.000Z",
        "revokedAt": "1970-01-01T00:00:00.000Z"
      }
    ]
  },
  "links": {
    "self": "/v2/system/claim-topics/knowYourCustomer"
  }
}
```

The `{name}` path segment is the topic name, and the lookup matches the registered name exactly. The read returns only the trusted issuers that are currently authorised: each entry carries the issuer identity address in `id` and the `addedAt` time it gained authority. The `revokedAt` field is present for shape stability and reports the epoch time `1970-01-01T00:00:00.000Z`, because revoked issuers are excluded from this list rather than returned with a revocation time.

### Read fields [#read-fields]

| Field            | Type   | Description                                                                          |
| ---------------- | ------ | ------------------------------------------------------------------------------------ |
| `id`             | string | Synthetic identifier for the topic, combining the registry address and the topic id. |
| `topicId`        | string | Numeric topic id as a decimal string.                                                |
| `name`           | string | Human-readable topic name.                                                           |
| `signature`      | string | ABI type list that defines the claim's data shape.                                   |
| `trustedIssuers` | array  | The issuer identities currently authorised to attest claims for this topic.          |

Use this read to answer a single compliance question: for a given topic, what claim shape does it enforce, and who may sign claims against it right now?

## Errors [#errors]

| Code        | Status | Meaning                                                                                                                                                                                 |
| ----------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DALP-0242` | 404    | No topic is registered under the requested name on the system's registry chain. Confirm the name, and if the topic was created recently, allow the indexer to catch up before retrying. |

The read reflects the indexed registry, so a topic registered moments ago can return `DALP-0242` until indexing catches up. See the [Platform API error reference](/docs/api-reference/errors/platform-api-error-reference) for the full error catalogue.

## When to use it [#when-to-use-it]

Use these endpoints when you need to:

* Produce an audit list of every claim topic the active system recognises, with the source breakdown of local against inherited topics.
* Confirm the exact claim signature a topic enforces before relying on claims that use it.
* Read which trusted issuers may currently sign claims for one topic.

To configure topics or trusted issuers rather than read them, see [Configure trusted issuers and claim topics](/docs/developers/compliance/configure-trusted-issuers).