---
title: "Record a Claim with Evidence"
description: "Record a public identifier or company relationship with its supporting source."
canonical: https://y2.dev/docs/ontology/how-to/record-evidence/
---

Ontology & Fusion

# Record a Claim with Evidence

Record a public identifier or company relationship with its supporting source.

You need an owner, admin, or member role in a workspace with FININT, Cyber, or Explorer access. Use a public page that supports the identifier or relationship.

## Record an identifier in the app

1. Open a company from **FININT → Markets → Companies**.
2. In **Entity ledger**, select **Open ledger subject** if no subject exists.
3. Open **Record an identifier with its source**.
4. Select the identifier kind.
5. Enter the value from the source page.
6. Enter a namespace if the kind requires one.
7. Enter the source URL, collection method, and an excerpt of up to 500 characters.
8. Select a supported verification state and confidence from 0 to 100.
9. Select **Record claim**.

The saved identifier appears with its verification state. Y2 records the identifier, observation, and claim in one transaction. Repeating an identifier adds a correction that retains the earlier evidence.

| Kind          | Required namespace                              |
| ------------- | ----------------------------------------------- |
| `handle`      | Platform or host, such as `github.com`          |
| `external-id` | `sec-cik`, `lei`, `wikidata`, or `attack-group` |
| `ticker`      | Exchange MIC, such as `XNAS`                    |

Y2 stores canonical values, including lowercase domains, ten-digit CIKs, and uppercase tickers. See [designator kinds](https://y2.dev/docs/ontology/reference/vocabulary#designator-kinds).

## Set a display label

1. Record a **Published name** with its source.
2. Select **Use as label** beside the name.

Y2 adds a separate `preferred-label` claim and an analyst note that cites the source. The label claim is graded `analytic`.

## Record a supply or ownership tie in the app

1. Open **Record a supply or ownership tie**.
2. Search the shared catalog for the other company.
3. Select its role: supplier, customer, parent, or subsidiary.
4. Cite the public page that states the relationship.
5. Select a supported verification state and confidence.
6. Select **Record tie**.

Y2 opens a subject for the other company if needed. For a supplier, the `supplies` claim runs from that supplier to the selected company.

The company's **Cyber-market exposure** panel can use the saved relationship. Events appear only when supporting data is available within the selected period and coverage limits. See [Fusion response](https://y2.dev/docs/ontology/reference/fusion).

## Record through the API

Use a workspace-bound key with `ledger:write`. Use `ledger:read` to inspect the saved records.

1. [Open a subject](https://y2.dev/docs/api/reference/ontology-ledger/openLedgerSubjectV2), or use an existing subject ID.
2. Create an observation payload with the source URL, retrieval time, excerpt, method, and source grade.
3. Append the observation and retain its returned `data.id`.
4. Append a designator and retain its returned `data.id`.
5. Append a `designated-by` claim from the subject to the designator, citing the observation in `evidenceRefs`.

Use the [record payload reference](https://y2.dev/docs/api/ontology-ledger#append-a-record) for each JSON file. To submit a prepared file:

```
curl --fail --silent --show-error "https://api.y2.dev/api/v2/ledger/records" \
  --header "Authorization: Bearer $Y2_API_KEY" \
  --header "Idempotency-Key: $Y2_REQUEST_ID" \
  --json @record.json
```

Set `Y2_REQUEST_ID` to a unique identifier for that request. Reuse it only when retrying the same payload. An existing designator returns `200` with `created: false`. A repeated claim requires `supersedes` with the current claim ID.

## Choose the verification state

Select a state supported by the evidence.

| Evidence                                       | State           |
| ---------------------------------------------- | --------------- |
| One public page supports the link              | `located`       |
| The subject's own page states the link         | `self-asserted` |
| Two retrieved pages identify the link          | `cross-linked`  |
| Further independent evidence supports the link | `corroborated`  |
| Only analyst notes support the claim           | `analytic`      |
| A string appears without a supported link      | `mentioned`     |

`cross-linked` and `corroborated` require retrievals from at least two different page URLs. `analytic` requires that all cited observations are analyst notes.

A public profile does not establish control

A profile can support a handle designation without showing who controls the account. Record `controls` only when a source supports that separate claim.

## Related pages

- [Correct a claim](https://y2.dev/docs/ontology/how-to/correct-a-claim)
- [Vocabulary](https://y2.dev/docs/ontology/reference/vocabulary)
- [Record rules](https://y2.dev/docs/ontology/reference/ledger-format#rules)