> 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.

# List identity checks

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

Returns one-off identity checks for your organisation in the environment of the key, newest first. Checks run from the dashboard appear here too. Rows are light, and the full result is on the detail endpoint.

**Error codes**

| `error` | Status | Meaning |
|---|---|---|
| `invalid_input` | 400 | A filter was not text, a date was invalid, or `from` is after `to`. |
| `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/list-individual-checks

## 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

### Query parameters

- `status` (enum, optional) — Only checks with this status. An unrecognised value is ignored.
  - Allowed values: `pending`, `verified`, `failed`, `not_found`, `error`
- `country` (string, optional) — Only checks for this ISO 3166-1 alpha-2 country.
- `idType` (string, optional) — Only checks of this ID type.
- `from` (string, optional) — Only records created at or after this ISO date or timestamp.
- `to` (string, optional) — Only records created at or before this ISO date or timestamp.
- `page` (integer, optional, default: 1) — The page to return, starting at 1.
- `pageSize` (integer, optional, default: 25) — Records per page, at most 100.

## Response

### 200

One page of identity checks.

- `checks` (list of IndividualCheckListItem, required) — The checks on this page, newest first.
- `total` (integer, required) — How many records match the filters across every page.
- `page` (integer, required) — The page that was returned.
- `pageSize` (integer, required) — The page size that was applied.

## Errors

### 400 Bad Request Error

The request body, query or path was invalid.

- `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.

### 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.

## Types

### IndividualCheckListItem

- `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.
- `idNumber` (string, optional, nullable) — The ID number. Null when it was never supplied or read.

## Examples

**Response**

```json
{
  "checks": [
    {
      "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",
      "idNumber": "00000000001"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 25
}
```

**SDK Code**

```python
import requests

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

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';
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"

	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")

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")
  .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', [
  'headers' => [
    'Authorization' => 'Bearer <apiKey>',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("https://sandbox-api.toden.co/api/kyc/checks/individual");
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")! 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()
```