> 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. # Run a one-off identity check POST https://sandbox-api.toden.co/api/kyc/checks/individual Content-Type: application/json Verifies a person's ID without the SDK capture flow. The check runs in the background: the response is `202` with a `verificationId`, and the result is ready shortly afterwards on the detail endpoint. No webhook is sent for a one-off check. A `requestId` you have used before returns the existing check with `202` and runs nothing new. **Sandbox.** A sandbox key accepts only the published test IDs (for example BVN `00000000001`) and answers a real ID with `422 only_test_ids_allowed`. A development key accepts test IDs and real IDs. Test checks return simulated results and are never charged. **Billing.** Production checks are charged for the parts that run: the record lookup, the document read when a document is sent, and the facial comparison when a selfie is sent. A check that ends in `error` because of a fault on our side is refunded. **Error codes** | `error` | Status | Meaning | |---|---|---| | `invalid_input` | 400 | The body failed validation, a slot was sent in both `mediaIds` and `images`, or neither an ID number nor a document front was sent. | | `invalid_image` | 400 | An inline image is not an https URL, a data URI or base64, or is too short to be a photo. | | `unsupported_media_type` | 400 | The bytes are not a JPEG, PNG or WebP photo. The format is read from the bytes. | | `image_too_large` | 400 | The photo is larger than 25 MB. | | `image_url_not_allowed` | 400 | The image URL is not http(s), or resolves to a non-public address. | | `image_fetch_failed` | 400 | The image URL could not be fetched, returned nothing, or redirected too many times. | | `spot_checks_disabled` | 403 | One-off checks are not enabled for your organisation. | | `spot_check_unavailable` | 403 | This ID type is currently unavailable for one-off checks. | | `id_type_not_enabled` | 403 | The ID type or a feature it needs is not enabled for your organisation. `scope` says which: `id_type`, `document_verification` or `gov_db_check`. | | `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. | | `organization_not_found` | 404 | The organisation behind the key no longer exists. | | `only_test_ids_allowed` | 422 | A sandbox key sent an ID number that is not a published test ID. | | `rate_limited` | 429 | The hourly verification limit for your organisation was reached. | | `pricing_not_configured` | 500 | No price is configured for this check. Contact support. | 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/create-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 ### Body (application/json) This endpoint expects an IndividualCheckRequest. - `country` (enum, required) — The country that issued the ID. - Allowed values: `NG`, `GH`, `KE`, `ZA`, `CI` - `idType` (string, required) — The ID type, for example `bvn`, `nin` or `passport`. It must be enabled for your organisation. - `consent` (true, required) — Must be true. You attest that the person consented to the check. - `idNumber` (string, optional) — The ID number. Required for number-only IDs. A document ID may send the document front instead, and the number is read from it. - `externalUserId` (string, optional) — Your own reference for the subject. A verified check is recorded against that customer record. - `createEntity` (boolean, optional, default: true) — Whether to save the verified subject as a customer record. Defaults to true. Send false to run the check without creating or updating a record. - `userData` (IndividualCheckRequestUserData, optional) — Details to compare against the record the check finds. - `mediaIds` (IndividualCheckRequestMediaIds, optional) — Photos already uploaded through the upload endpoint. Send each slot here or in `images`, never both. - `images` (IndividualCheckRequestImages, optional) — The same photos inline, each as an https URL, a data URI or base64. - `requestId` (string, optional) — Your idempotency key. A retry with the same value returns the same check and never runs or bills a second one. ## Response ### 202 The check was accepted and is being processed. - `verificationId` (string, required) — The id of the check. Read the result from the matching detail endpoint. - `status` (enum, required) — Always `pending` at submission. The check is processed in the background. - Allowed values: `pending` ## 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. ### 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. ### 422 Unprocessable Entity Error The request was understood but cannot be processed as sent. - `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. ### 429 Too Many Requests Error A rate limit was reached. Retry after a short wait. - `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. ### 500 Internal Server Error An unexpected error occurred. - `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 ### IndividualCheckRequestUserData Details to compare against the record the check finds. - `firstName` (string, optional) — The person's first name. - `lastName` (string, optional) — The person's last name. - `dateOfBirth` (string, optional) — The person's date of birth, for example `1990-01-15`. ### IndividualCheckRequestMediaIds Photos already uploaded through the upload endpoint. Send each slot here or in `images`, never both. - `documentFront` (string, optional) — The front of the ID document, as a `mediaId`. - `documentBack` (string, optional) — The back of the ID document, as a `mediaId`. - `selfie` (string, optional) — A selfie of the person, as a `mediaId`. Adds a facial comparison where the ID type supports one. ### IndividualCheckRequestImages The same photos inline, each as an https URL, a data URI or base64. - `documentFront` (string, optional) — The front of the ID document, inline. - `documentBack` (string, optional) — The back of the ID document, inline. - `selfie` (string, optional) — A selfie of the person, inline. Adds a facial comparison where the ID type supports one. ## Examples **Request** ```json { "country": "NG", "idType": "bvn", "consent": true, "idNumber": "00000000001", "userData": { "firstName": "Ada", "lastName": "Example", "dateOfBirth": "1990-01-15" }, "requestId": "check-user-42-2026-09-12" } ``` **Response** ```json { "verificationId": "cmt8s0a4p0001qw9k2m7f3xyz", "status": "pending" } ``` **SDK Code** ```python import requests url = "https://sandbox-api.toden.co/api/kyc/checks/individual" payload = { "country": "NG", "idType": "bvn", "consent": True, "idNumber": "00000000001", "userData": { "firstName": "Ada", "lastName": "Example", "dateOfBirth": "1990-01-15" }, "requestId": "check-user-42-2026-09-12" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://sandbox-api.toden.co/api/kyc/checks/individual'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"country":"NG","idType":"bvn","consent":true,"idNumber":"00000000001","userData":{"firstName":"Ada","lastName":"Example","dateOfBirth":"1990-01-15"},"requestId":"check-user-42-2026-09-12"}' }; 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" "strings" "net/http" "io" ) func main() { url := "https://sandbox-api.toden.co/api/kyc/checks/individual" payload := strings.NewReader("{\n \"country\": \"NG\",\n \"idType\": \"bvn\",\n \"consent\": true,\n \"idNumber\": \"00000000001\",\n \"userData\": {\n \"firstName\": \"Ada\",\n \"lastName\": \"Example\",\n \"dateOfBirth\": \"1990-01-15\"\n },\n \"requestId\": \"check-user-42-2026-09-12\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") 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::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"country\": \"NG\",\n \"idType\": \"bvn\",\n \"consent\": true,\n \"idNumber\": \"00000000001\",\n \"userData\": {\n \"firstName\": \"Ada\",\n \"lastName\": \"Example\",\n \"dateOfBirth\": \"1990-01-15\"\n },\n \"requestId\": \"check-user-42-2026-09-12\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://sandbox-api.toden.co/api/kyc/checks/individual") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"country\": \"NG\",\n \"idType\": \"bvn\",\n \"consent\": true,\n \"idNumber\": \"00000000001\",\n \"userData\": {\n \"firstName\": \"Ada\",\n \"lastName\": \"Example\",\n \"dateOfBirth\": \"1990-01-15\"\n },\n \"requestId\": \"check-user-42-2026-09-12\"\n}") .asString(); ``` ```php request('POST', 'https://sandbox-api.toden.co/api/kyc/checks/individual', [ 'body' => '{ "country": "NG", "idType": "bvn", "consent": true, "idNumber": "00000000001", "userData": { "firstName": "Ada", "lastName": "Example", "dateOfBirth": "1990-01-15" }, "requestId": "check-user-42-2026-09-12" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://sandbox-api.toden.co/api/kyc/checks/individual"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"country\": \"NG\",\n \"idType\": \"bvn\",\n \"consent\": true,\n \"idNumber\": \"00000000001\",\n \"userData\": {\n \"firstName\": \"Ada\",\n \"lastName\": \"Example\",\n \"dateOfBirth\": \"1990-01-15\"\n },\n \"requestId\": \"check-user-42-2026-09-12\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "country": "NG", "idType": "bvn", "consent": true, "idNumber": "00000000001", "userData": [ "firstName": "Ada", "lastName": "Example", "dateOfBirth": "1990-01-15" ], "requestId": "check-user-42-2026-09-12" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://sandbox-api.toden.co/api/kyc/checks/individual")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data 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() ```