> ## Documentation Index
> Fetch the complete documentation index at: https://docs.proofage.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Reading results

> Fetch the decision, the document data, the age estimate and the media of a verification, or find one by your own ID.

All of these are signed `GET` requests. Their fields are described in [Data models](/api-reference/data-models).

## The decision

```bash theme={null}
GET /v1/verifications/{verification}
```

Returns the verification: `status`, `reason`, `duplicate_check`, your `external_id` and `external_metadata`, and `erasure`. This is what the webhook told you, and the place to confirm it. The [webhook](/integration/webhooks) also carries the `document` object described below, without the images.

## Finding a verification by your ID

When you have only your own `external_id`, for example to check whether a user already has a verification, list the workspace's verifications:

```bash theme={null}
GET /v1/verifications?external_id=user_12345&limit=1
```

```json theme={null}
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "external_id": "user_12345",
      "status": "approved",
      "reason": null,
      "created_at": "2026-10-08T12:00:00+00:00",
      "updated_at": "2026-10-08T12:05:00+00:00"
    }
  ],
  "next_cursor": null
}
```

Each item is the verification as `GET /v1/verifications/{id}` returns it (shortened above), newest first.

* `external_id`: exact, case-sensitive match.
* `status`: one or more statuses, comma-separated, such as `status=approved,declined`. A verification waiting for an ID document is filtered as `started` and listed as `documents_required`.
* `limit`: 1 to 100; 20 by default.
* `cursor`: the `next_cursor` of the previous page, sent with the same filters. `next_cursor` is `null` on the last page.

The query string is signed too, with its parameters sorted by name and a comma written as `%2C`; see [API authentication](/getting-started/api-authentication#signing-a-request). Learn about outcomes from [webhooks](/integration/webhooks) rather than by listing again and again; see [Rate limiting](/integration/rate-limiting).

## The document

```bash theme={null}
GET /v1/verifications/{verification}/document
```

On KYC and age verification by ID document workspaces, and on a facial age estimation that fell back to a document. A KYC workspace gets eleven fields:

```json theme={null}
{
  "document": {
    "type": "passport",
    "issuing_country": "DE",
    "issuing_subdivision": null,
    "fields": {
      "first_name": "JANE",
      "middle_name": null,
      "last_name": "DOE",
      "date_of_birth": "1990-04-12",
      "gender": "F",
      "nationality": "DE",
      "place_of_birth": "BERLIN",
      "address": null,
      "document_number": "X1234567",
      "issue_date": "2020-04-14",
      "expiry_date": "2030-04-13"
    }
  },
  "media": [
    { "id": "4b6f…", "type": "selfie", "url": "https://api.proofage.net/v1/verifications/550e…/media/4b6f…" },
    { "id": "9c2a…", "type": "document_front", "url": "https://api.proofage.net/v1/verifications/550e…/media/9c2a…" }
  ],
  "meta": { "attempt_id": "1d3e…" }
}
```

An age workspace gets `type`, `issuing_country` and four fields. The other seven keys are absent, not `null`:

```json theme={null}
{
  "document": {
    "type": "id",
    "issuing_country": "FR",
    "issuing_subdivision": null,
    "fields": {
      "first_name": "JEAN",
      "last_name": "MARTIN",
      "date_of_birth": "1988-11-02",
      "document_number": "X4RTBPFW4"
    }
  },
  "media": [
    { "id": "9c2a…", "type": "document_front", "url": "https://api.proofage.net/v1/verifications/550e…/media/9c2a…" }
  ],
  "meta": { "attempt_id": "1d3e…" }
}
```

A US driving licence also carries the state that issued it, on any workspace:

```json theme={null}
"document": {
  "type": "driver_license",
  "issuing_country": "US",
  "issuing_subdivision": "CA",
  "fields": { "first_name": "JANE", "last_name": "DOE", "date_of_birth": "1990-04-12", "document_number": "D1234567" }
}
```

How to read it:

* `null` means the field was not read, or is not printed on that document. A passport has no address, many cards print no place of birth, and the German identity card prints no sex.
* `type` is an open enum (`passport`, `id`, `driver_license`, `residence_permit`, `other`): handle values you do not know. `other` is a readable document that is not an identity card, passport, driving licence or residence permit, such as a health insurance card. `id` is the same value the upload endpoint takes.
* `issuing_subdivision` is the state or province that issued the document, as a bare code (`FL`, `CA`, `PR`; up to three uppercase letters or digits), or `null`. Today it is filled for US driving licences and ID cards. It is `null` when `issuing_country` is, it is on every workspace, and it is kept after erasure.
* `issuing_country` and `nationality` are ISO 3166-1 alpha-2 (`XK` for Kosovo). `nationality` is published only when the document itself states it. They differ on a residence permit and can differ on any document.
* `gender` is `F`, `M` or `X`. `X` means the document states that the sex is unspecified. On a Mexican voter card or driving licence created before 20 August 2026 17:00 UTC, `gender` is `null`.
* `date_of_birth`, `issue_date` and `expiry_date` are `YYYY-MM-DD`. A document that prints only the month or year of expiry reports the last day of that period. A birth or issue date printed partially is `null`, never rounded. A permanent document (for example `PERMANENTE` or `INDEFINIDA`) reads as a `null` `expiry_date`.
* `place_of_birth` is the printed text, not normalised.
* `address` is the printed text as read: trimmed, `null` when empty, not parsed and not normalised. It may contain line breaks. KYC workspaces only.
* Text fields are trimmed; an empty one is `null`.

## The age estimate

```bash theme={null}
GET /v1/verifications/{verification}/estimation
```

On Facial age estimation workspaces:

```json theme={null}
{
  "verification_id": "550e8400-e29b-41d4-a716-446655440000",
  "attempt_id": "1d3e…",
  "age_threshold": { "minimum": 18, "passed": true, "confidence": 0.9731 },
  "gender": { "value": 0, "confidence": 0.98 }
}
```

`passed` answers whether the person is at or above the workspace's minimum age. The estimate itself is not returned as an age.

## The images

```bash theme={null}
GET /v1/verifications/{verification}/media/{media}
```

Returns the image bytes. Use the `url`s from the document result; they are API URLs, so the request must be signed like any other. The [server SDKs](/integration/sdks) stream the download for you.

## When data is gone

Images and personal data are kept for a limited time and can be erased on request; see [Data retention and erasure](/console/data-retention). After that:

* `erasure` on the verification is set and says when and why;
* document fields are `null` and image `url`s are `null`;
* downloading an image answers `404 MEDIA_NOT_FOUND`.

The status, the reason and the dates stay.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.