# Get a person

`GET /v1/persons/{id}`

One person by canonical or retired identifier. A retired identifier resolves
to the surviving identity and the response carries `resolution` with the
merge decision; after a reversal the identifier resolves to itself again.
With `known_at` before the merge decision, the retired identifier is still its
own identity and `resolution.status` is `canonical`. Roles are filtered to
those effective at `valid_at`. `403 not-entitled` (`restriction: competition`)
when the caller's `entities` grant names competitions and the person is linked to
none of them (memberships at teams that entered or played in a granted
competition, or fixtures of it they officiated); unknown identifiers are `404`.

Parameters:
- `id` (path, string, required): Canonical or retired person identifier (`psn_<digits>`); another kind's prefix or an undecodable body is a 400 naming `id`.
- `valid_at` (query, timestamp, optional): Business-effective instant (UTC); default is the request time.
- `known_at` (query, timestamp, optional): Knowledge cutoff (UTC); the answer reflects only what OddsFinder had recorded by this instant. Default is the request time. Must not be in the future.
- `include` (query, enum, optional): Optional blocks to add to a single-entity read. `provenance` names, for each field whose value is chosen among several sources, the source report it was taken from as known at `known_at`; it needs the `read:sources` scope (`403 not-entitled`, `restriction: scope` otherwise), and a field is `withheld` when its source holds no display right. One of: `provenance`.

Returns `200`: The person as known at the cutoff.
The body is [the person object](obj-Person.md).

Errors: `400` Malformed parameter or cursor (`invalid-request`).; `401` Missing or invalid credential (`unauthenticated`).; `403` Operation not permitted (`forbidden`) or restricted by grants/rights (`not-entitled`).; `404` Unknown identifier at the requested cutoff (`not-found`).; `422` Well-formed but unanswerable (`invalid-range`, `unsupported-historical-capability`).; `429` The per-minute rate limit is used up (`rate-limited`) or a daily allowance is exhausted (`quota-exceeded`). Failed requests (403, 404, other 4xx, 5xx) use up the per-minute rate limit too.; `500` Unexpected failure (`internal-error`); `request_id` identifies the server-side record.; `503` A service this operation depends on, or the access check, is temporarily unavailable (`unavailable`, `policy-unavailable`).

Example request (200 · After reversal):

```bash
curl https://api.example.com/v1/persons/psn_5 \
  -H "X-API-Key: $ODDSFINDER_API_KEY"
```

Example response (200):

```json
{
  "id": "psn_5",
  "name": "L. Ferri",
  "name_status": "known",
  "full_name": null,
  "first_name": null,
  "last_name": null,
  "aliases": [],
  "association_code": null,
  "born_on": null,
  "height_cm": null,
  "weight_kg": null,
  "birth_country_code": null,
  "position": null,
  "detailed_position": null,
  "preferred_foot": null,
  "birth_place": null,
  "contract_until": null,
  "roles": [],
  "resolution": {
    "requested_id": "psn_5",
    "canonical_id": "psn_5",
    "status": "canonical",
    "decision_id": "dec_2",
    "decided_at": "2026-09-20T10:00:00Z"
  },
  "knowledge": {
    "known_at": "2026-10-04T09:00:00Z",
    "as_requested": false
  }
}
```