> ## Documentation Index > Fetch the complete documentation index at: https://docs.reconifyhq.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Reconify's API reference is read-only for customer data. Do not invent endpoints or authentication behavior beyond the OpenAPI contract. > The public OpenAPI document contains only the documented external /v2 contract. # Correlation IDs > Link evidence across services without changing operation identity. A correlation ID is an opaque value you attach to an event so Reconify can show you every other piece of evidence that came from the same business transaction, even when that transaction crossed several services and produced several operations. Reconify stores it as metadata. It never changes which operation an event belongs to. ## Three identities on one event Every event already carries `reference` and `entity_id`. `correlation_id` is a third, optional identity that answers a different question. Correlation is shared context; causation points to one earlier event. See [Causation IDs](/concepts/causation-ids) for the distinction. | Field | Question it answers | Example | | ---------------- | ------------------------------------------------------- | ------------ | | `reference` | Which operation does this evidence belong to? | `pay_9f2` | | `correlation_id` | Which cross-service transaction produced this evidence? | `chk_7Q2M0S` | | `entity_id` | Which target or participant does this event concern? | `ord_5512` | `reference` is local to one flow: the service that owns a payment names it, and every event for that payment repeats it. `correlation_id` is shared: every service touching the same checkout, order, or saga repeats the same value on whatever flow it happens to report. ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "flow": "payment_to_order", "type": "payment.succeeded", "reference": "pay_9f2", "correlation_id": "chk_7Q2M0S", "entity_id": "ord_5512", "amount": "150.00", "currency": "USD" } ``` ## What a correlation ID does not do The field adds a link, and it changes nothing about identity or evaluation. A correlation ID never merges operations. Two events that share a correlation ID but carry different references remain two separate operations, with separate flows, deadlines, and findings. Operation identity stays exactly what it was before you added the field: * Events are grouped into an operation by organization and `reference`. * Flow definitions, stages, SLAs, and deadlines are unchanged. * Findings are opened and resolved per operation, not per correlation ID. * Adding the field to a service that did not send it before changes nothing about existing monitoring. This is deliberate. Deadlines and findings depend on a single, stable operation identity, and a value propagated by many services is not a safe identity to evaluate against. ## Where it shows up One correlation ID reaches every operation that carries it: One correlation ID linking two separate operations, each with its own flow and its own events. Search in the dashboard returns two collections, bounded independently: * **Direct results** match the value you typed against events, operations, and issues, including a partial match on a correlation ID. * **Related activity** expands an exact match into the other evidence that shares a correlation ID, marked so you can tell it apart from what you searched for. Searching a `reference` also expands through the correlation ID its events carry. Provider evidence keeps the value too. When Reconify generates a terminal payment event from a tracked provider integration, it copies the correlation ID from the initiating `payment.initiated` event. If that event had none, the generated event has none. Related activity is a dashboard investigation surface. The public API has no search endpoint, and event reads return both optional identifiers. ## Value rules Four rules govern the value itself, and ingestion enforces all of them. | Rule | Detail | | --------------- | ------------------------------------------------------------------- | | Optional | A service with no value to propagate leaves the field off entirely. | | Length | 1 to 200 characters. | | Characters | Visible ASCII only, `!` through `~`. No spaces, tabs, or newlines. | | Rejected values | `null`, `""`, whitespace-padded, or containing control characters. | A value that fails these rules is rejected for that item with code `invalid_event` and `field: "correlation_id"`, while other items in the same batch are unaffected. See the [error catalog](/reference/api/errors). `correlation_id` is part of the event payload used for idempotency. Retrying a stored `id` with a correlation ID that was added, removed, or changed returns `idempotency_conflict` for that item, so the value belongs on the event before it is first sent. ## Keep the value opaque Reconify treats the value as an opaque string and never parses it, so the only requirement is that it stays safe to store and display: * Secrets, tokens, card data, email addresses, and other personal data stay out of it. * The same value in another organization is a different, unrelated value, because correlation never crosses tenants. * Correlation values never become metric labels. Next: [Trace a flow across services](/guides/trace-across-services) covers choosing a value, propagating it, and investigating with it.