> Toden documentation. For the full index fetch /llms.txt. Every page is available as Markdown by appending .md to its URL. Identity verification uses /api/kyc, Risk Intelligence uses /api/v1; they are separate contracts with different error shapes. Never invent an endpoint, field or enum value: read the API reference page for the operation first.

# Retrieve an identity check

GET https://sandbox-api.toden.co/api/kyc/checks/individual/{id}

Returns one identity check in full: what you submitted, the outcome, the details the check established and links to its photos. Poll this until `status` leaves `pending`.

**Error codes**

| `error` | Status | Meaning |
|---|---|---|
| `not_found` | 404 | No identity check with that id, or it was deleted. |
| `secret_key_required` | 403 | A publishable key was used. This endpoint accepts secret keys only. |
| `environment_mismatch` | 403 | The key belongs to an environment this deployment does not serve. |
| `ip_not_allowed` | 403 | The key has an IP allowlist and the calling address is not on it. |
| `organization_suspended` | 403 | The organisation is suspended. The response carries `reason` and `suspendedAt`. |
| `business_not_approved` | 403 | A live key was used before the business was approved for production. |

A missing or unknown key answers `401`, where `error` is a short sentence rather than a code.

Requires a secret (`sk_`) key. A publishable key receives `403 secret_key_required`.

Reference: https://docs.toden.co/api-reference/verification/identity-checks/get-individual-check

## Authentication

- `Authorization` header (bearer token, required) — Send the API key as a Bearer token. Each operation states whether a publishable key is enough or a secret key is required.

## Servers

- `https://sandbox-api.toden.co` (Sandbox, default)
- `https://api.toden.co` (Production)

## Request

### Path parameters

- `id` (string, required) — The check id, as returned by the submit as `verificationId`.

## Response

### 200

The identity check.

- `check` (IndividualCheck, required)

## Errors

### 401 Unauthorized Error

The Authorization header is missing, or the API key is unknown or revoked.

- `error` (string, required) — A stable machine-readable code such as `invalid_input`. Authentication failures (401) carry a short sentence here instead of a code.
- `message` (string, optional) — A human-readable explanation, safe to log. The wording may change.

### 403 Forbidden Error

The key may not call this endpoint, or the organisation may not use this feature.

- `error` (string, required) — A stable machine-readable code such as `invalid_input`. Authentication failures (401) carry a short sentence here instead of a code.
- `message` (string, optional) — A human-readable explanation, safe to log. The wording may change.

### 404 Not Found Error

The resource does not exist for this organisation and environment.

- `error` (string, required) — A stable machine-readable code such as `invalid_input`. Authentication failures (401) carry a short sentence here instead of a code.
- `message` (string, optional) — A human-readable explanation, safe to log. The wording may change.

## Types

### IndividualCheck

- `id` (string, required) — The check id, the same value the submit returned as `verificationId`.
- `status` (enum, required) — `pending` until processing finishes, then the outcome.
  - Allowed values: `pending`, `verified`, `failed`, `not_found`, `error`
- `country` (string, required) — The ISO 3166-1 alpha-2 country the check was run for.
- `initiatedVia` (enum, required) — Whether the check was run through the API or from the dashboard.
  - Allowed values: `api`, `dashboard`
- `createdAt` (datetime, required) — When the check was submitted.
- `idType` (string, required) — The ID type that was checked.
- `reasonCode` (string, optional, nullable) — A stable code explaining an outcome that did not pass. Null on `verified` and `pending`.
- `verificationMethod` (enum, optional) — How the check was verified. `sandbox` marks a simulated test result. Null until processing finishes.
  - Allowed values: `gov_db`, `document_ocr`, `sandbox`
- `chargedAmount` (string, optional, nullable) — The price of the check in USD, as a decimal string. Null for test checks.
- `completedAt` (datetime, optional, nullable) — When processing finished. Null while the check is pending.
- `reason` (string, optional, nullable) — A sentence explaining an outcome that did not pass. Null on `verified` and `pending`.
- `chargedBreakdown` (map from string to string, optional, nullable) — The price per billed component in USD, keyed by component name. Null for test checks.
- `idNumber` (string, optional, nullable) — The ID number. Null when it was never supplied or read.
- `submittedData` (map from string to any, optional, nullable) — The `userData` you asked to compare, echoed back.
- `result` (IndividualCheckResult, optional, nullable) — What the check established. Present on a `verified` check only.
- `govRecord` (IndividualCheckGovRecord, optional, nullable) — Further fields from the record that was found. Null when there is none.
- `media` (IndividualCheckMedia, optional, nullable) — URLs for the photos attached to the check. Fetch each with a secret key. Null when there are none.

### IndividualCheckResult

What the check established. Present on a `verified` check only.

- `firstName` (string, optional, nullable) — The first name on the record.
- `lastName` (string, optional, nullable) — The last name on the record.
- `middleName` (string, optional, nullable) — The middle name on the record.
- `dateOfBirth` (string, optional, nullable) — The date of birth on the record.
- `gender` (string, optional, nullable) — The gender on the record.
- `dataMatch` (boolean, optional, nullable) — Whether the details you sent agree with the record. Null when nothing was compared.
- `facialMatch` (IndividualCheckResultFacialMatch, optional, nullable) — The selfie comparison. Null when no comparison ran.
- `facialMatchSource` (enum, optional) — Which photo the selfie was compared with.
  - Allowed values: `gov_record`, `chip`, `document`
- `facialMatchSkipped` (string, optional, nullable) — Why a facial comparison did not run, for example `no_face_on_document`. Null otherwise.

### IndividualCheckGovRecord

Further fields from the record that was found. Null when there is none.

- `signature` (string, optional, nullable) — The signature image on the record, when one exists.
- `fields` (map from string to any, optional) — The remaining record fields. The keys vary by country and ID type.

### IndividualCheckMedia

URLs for the photos attached to the check. Fetch each with a secret key. Null when there are none.

- `documentFront` (string, optional) — The front of the ID document, as a URL.
- `documentBack` (string, optional) — The back of the ID document, as a URL.
- `selfie` (string, optional) — A selfie of the person, as a URL. Adds a facial comparison where the ID type supports one.

### IndividualCheckResultFacialMatch

The selfie comparison. Null when no comparison ran.

- `match` (boolean, optional) — Whether the selfie matched the reference photo.
- `confidence` (double, optional, nullable) — The similarity score on a 0 to 100 scale.

## Examples

**Response**

```json
{
  "check": {
    "id": "cmt8s0a4p0001qw9k2m7f3xyz",
    "status": "verified",
    "country": "NG",
    "initiatedVia": "api",
    "createdAt": "2026-09-12T10:00:00.000Z",
    "idType": "bvn",
    "reasonCode": null,
    "verificationMethod": "sandbox",
    "chargedAmount": null,
    "completedAt": "2026-09-12T10:00:02.000Z",
    "reason": null,
    "chargedBreakdown": {},
    "idNumber": "00000000001",
    "submittedData": {
      "dateOfBirth": "1990-01-15",
      "firstName": "Ada",
      "lastName": "Example"
    },
    "result": {
      "firstName": "ADA",
      "lastName": "EXAMPLE",
      "middleName": null,
      "dateOfBirth": "1990-01-15",
      "gender": "f",
      "dataMatch": true,
      "facialMatch": null,
      "facialMatchSkipped": null
    },
    "govRecord": null,
    "media": null
  }
}
```

**SDK Code**

```python
import requests

url = "https://sandbox-api.toden.co/api/kyc/checks/individual/id"

headers = {"Authorization": "Bearer <apiKey>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://sandbox-api.toden.co/api/kyc/checks/individual/id';
const options = {method: 'GET', headers: {Authorization: 'Bearer <apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox-api.toden.co/api/kyc/checks/individual/id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://sandbox-api.toden.co/api/kyc/checks/individual/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <apiKey>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://sandbox-api.toden.co/api/kyc/checks/individual/id")
  .header("Authorization", "Bearer <apiKey>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://sandbox-api.toden.co/api/kyc/checks/individual/id', [
  'headers' => [
    'Authorization' => 'Bearer <apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://sandbox-api.toden.co/api/kyc/checks/individual/id");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <apiKey>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://sandbox-api.toden.co/api/kyc/checks/individual/id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```