> 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. # Get a verification result GET https://sandbox-api.toden.co/api/kyc/verifications/{id} Returns the full result, including the verified identity, the decision history and earlier attempts. `result` is present only when the checks passed; `reason` and `reasonCode` only when they did not. Before the applicant submits, the same identifier returns the unsubmitted attempt, with `data` holding what they have entered so far. A workflow can withhold fields from this response through its returned-data settings. **Error codes** | `error` | Status | Meaning | |---|---|---| | `Verification not found` | 404 | No verification or session with that id for this organisation and environment. | | `Missing or invalid Authorization header` | 401 | No bearer credential was sent. | | `Invalid API key` | 401 | The key is unknown or revoked. | | `environment_mismatch` | 403 | The key belongs to an environment this host does not serve. | | `origin_not_allowed` | 403 | The request origin is not on the publishable key allowlist. | | `ip_not_allowed` | 403 | The caller address is not on the secret key allowlist. | | `organization_suspended` | 403 | The organisation is suspended. | | `secret_key_required` | 403 | A publishable key was used on a secret-key endpoint. | Requires a secret (`sk_`) key. A publishable key receives `403 secret_key_required`. Reference: https://docs.toden.co/api-reference/verification/verifications/get-verification ## 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 verification identifier. A session identifier works too, because a verification keeps the identifier of its session. ## Response ### 200 The verification result, or the unsubmitted attempt. - `Verifications_getVerification_Response_200` ## 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 ### VerificationResult The full result of a submitted verification. Fields may be withheld by the workflow returned-data settings. - `verificationId` (string, required) — The verification identifier. - `status` (enum, required) — The top-line status. - Allowed values: `not_started`, `in_progress`, `processing`, `in_review`, `awaiting_resubmission`, `approved`, `declined`, `abandoned`, `expired`, `error`, `cancelled` - `checkStatus` (enum, required) — What the checks themselves found. - Allowed values: `pending`, `verified`, `failed`, `not_found`, `error` - `statusHistory` (list of VerificationStatusChange, required) — Every change to the top-line status, newest first. - `attempt` (integer, required) — Which attempt this result describes. - `attempts` (list of VerificationAttempt, required) — The earlier attempts, oldest first. - `country` (string, required) — ISO 3166 alpha-2 country code. - `idType` (string, required) — The ID type, or the business lookup product. - `createdAt` (datetime, required) — When the verification was first created. - `submittedAt` (datetime, required) — When the current attempt was submitted. - `waitingOn` (enum, optional) — What a `processing` verification is waiting for, when its decision is held on a longer check. Null otherwise. - Allowed values: `screening`, `key_people`, `address_presence` - `review` (VerificationResultReview, optional, nullable) — The current decision made by a person or your backend. Null when nobody has decided. - `completedAt` (datetime, optional) — When the current attempt finished. Absent while the checks are running. - `externalUserId` (string, optional, nullable) — Your reference for the subject. - `metadata` (map from string to any, optional, nullable) — Your customer metadata, as stored. Bounded: at most 16 KiB, four levels deep and 100 keys. - `workflow` (VerificationResultWorkflow, optional, nullable) — The workflow that drove the submission. Null when none did. - `hold` (VerificationResultHold, optional, nullable) — Present while processing is paused for insufficient credit. Null otherwise. - `multiId` (VerificationResultMultiId, optional, nullable) — The per-ID results of a multiple-ID verification. Null for a single ID. Each check carries that ID result fields, with photo references given as media URLs. - `addressIntel` (VerificationResultAddressIntel, optional, nullable) — The address check result. Null when no address was collected. - `supportingDocuments` (list of VerificationResultSupportingDocumentsItems, optional, nullable) — The supporting documents collected and what each check found. Null when none were collected. - `faceSearch` (VerificationResultFaceSearch, optional, nullable) — A summary of the search for the same face among earlier verifications. Null when no search ran. - `deviceRules` (VerificationResultDeviceRules, optional, nullable) — What the workflow device and network rules found. Null when none were checked. - `result` (VerificationResultResult, optional) — The verified identity. Present only when the checks passed. - `reason` (string, optional, nullable) — A sentence describing why the checks did not pass, written for the applicant. - `reasonCode` (string, optional, nullable) — A stable code for why the checks did not pass. ### VerificationAttemptData What an unsubmitted attempt holds so far. - `verificationId` (string, required) — The identifier, which the verification keeps once submitted. - `status` (enum, required) — Where the unsubmitted attempt stands. - Allowed values: `in_progress`, `abandoned`, `expired`, `cancelled` - `step` (string, required, nullable) — The step the applicant had reached. - `captured` (list of string, required) — The names of the capture slots already filled. Never the captured data. - `createdAt` (datetime, required) — When the session was created. - `lastSeenAt` (datetime, required, nullable) — When the applicant was last active. - `expiresAt` (datetime, required) — When the session stops accepting a submission. - `workflowId` (string, required, nullable) — The public identifier of the workflow that drove the submission, or null when none did. - `externalUserId` (string, required, nullable) — Your reference for the subject. - `metadata` (map from string to any, optional, nullable) — Your customer metadata, as stored on the session. Bounded: at most 16 KiB, four levels deep and 100 keys. - `data` (VerificationAttemptDataData, optional, nullable) — What the applicant has entered so far. Null when nothing has been saved. ### VerificationStatusChange One change to the top-line status. - `status` (string, required) — The status after the change. - `previousStatus` (string, required, nullable) — The status before the change. - `source` (enum, required) — Where the change came from. - Allowed values: `dashboard`, `api`, `workflow`, `platform` - `changedBy` (VerificationStatusChangeChangedBy, required) — Who made the change. - `changedAt` (datetime, required) — When the change was made. - `decision` (enum, required) — The decision a person or your backend made, if any. - Allowed values: `APPROVED`, `DECLINED`, `RESUBMISSION` - `outcome` (string, required, nullable) — The workflow outcome, if the workflow made the change. - `runId` (string, required, nullable) — The workflow run that made the change, if any. - `resubmitSteps` (list of string, required) — The steps the applicant was asked to redo. ### VerificationAttempt An earlier attempt of this verification: what it concluded, never its personal data. - `attempt` (integer, required) — The attempt number. - `checkStatus` (string, required) — What the checks found on that attempt. - `reason` (string, required, nullable) — A sentence describing why the checks did not pass, written for the applicant. - `reasonCode` (string, required, nullable) — A stable code for why the checks did not pass. - `assuranceLevel` (string, required, nullable) — How strongly that attempt verified the identity. - `decision` (string, required, nullable) — The decision recorded on that attempt. - `resubmitSteps` (list of string, required) — The steps the applicant was asked to redo after it. - `submittedAt` (datetime, required) — When that attempt was submitted. - `completedAt` (datetime, required, nullable) — When that attempt finished. - `resubmittedAt` (datetime, required) — When the next attempt replaced it. ### VerificationResultReview The current decision made by a person or your backend. Null when nobody has decided. - `decision` (enum, optional) — The decision. - Allowed values: `APPROVED`, `DECLINED`, `RESUBMISSION` - `reviewedAt` (datetime, optional) — When it was made. - `reviewedById` (string, optional) — Who made it: a user identifier, or `api_key:` for a decision made through the API. ### VerificationResultWorkflow The workflow that drove the submission. Null when none did. - `id` (string, optional) — The workflow public identifier. - `name` (string, optional) — The workflow name today. - `version` (integer, optional, nullable) — The published version that ran. ### VerificationResultHold Present while processing is paused for insufficient credit. Null otherwise. - `reason` (string, optional, nullable) — Why processing is paused. - `heldAt` (datetime, optional) — When the pause began. - `expiresAt` (datetime, optional, nullable) — When the paused verification will be abandoned. ### VerificationResultMultiId The per-ID results of a multiple-ID verification. Null for a single ID. Each check carries that ID result fields, with photo references given as media URLs. - `count` (integer, optional) — How many IDs the workflow checks. - `minPassed` (integer, optional) — How many must pass. - `passed` (integer, optional) — How many passed. - `checks` (list of map from string to any, optional) — One entry per ID, in the order submitted. ### VerificationResultAddressIntel The address check result. Null when no address was collected. ### VerificationResultSupportingDocumentsItems - `url` (string, optional, nullable) — Where to download the document with a secret key, or null when it cannot be served. - `method` (enum, optional) — How the document was provided, when the workflow lets the applicant draw it. - Allowed values: `drawn`, `uploaded` ### VerificationResultFaceSearch A summary of the search for the same face among earlier verifications. Null when no search ran. - `status` (string, optional) — Whether the search ran. - `skippedReason` (string, optional, nullable) — Why the search did not run. - `result` (string, optional) — What the search found. - `action` (string, optional) — What the workflow did about it. - `faceCount` (integer, optional, nullable) — How many faces were in the selfie. - `matchCount` (integer, optional) — How many other people matched. - `blocklisted` (boolean, optional) — Whether the face matched your blocklist. - `allowlisted` (boolean, optional) — Whether the face matched your allowlist. - `checkedAt` (string, optional, nullable) — When the search ran. ### VerificationResultDeviceRules What the workflow device and network rules found. Null when none were checked. - `result` (enum, optional) — The strongest case found, or `clear`. - Allowed values: `clear`, `country_not_allowed`, `app_integrity_failed`, `declined_device`, `virtual_camera`, `emulator`, `rooted_device`, `tor_exit`, `multiple_devices`, `expected_ip_mismatch`, `privacy_network`, `timezone_mismatch`, `recovered_device`, `shared_device`, `repeated_attempts`, `ip_country_mismatch` - `action` (enum, optional) — What the workflow did about it. - Allowed values: `approve`, `review`, `decline` - `cases` (list of enum, optional) — Every case found. - Allowed values: `country_not_allowed`, `app_integrity_failed`, `declined_device`, `virtual_camera`, `emulator`, `rooted_device`, `tor_exit`, `multiple_devices`, `expected_ip_mismatch`, `privacy_network`, `timezone_mismatch`, `recovered_device`, `shared_device`, `repeated_attempts`, `ip_country_mismatch` - `ipCountry` (string, optional, nullable) — The country of the applicant network address. - `countryAllowed` (boolean, optional, nullable) — Whether that country is one the workflow allows. ### VerificationResultResult The verified identity. Present only when the checks passed. - `idNumber` (string, optional, nullable) — The ID number. - `idNumberMasked` (string, optional, nullable) — The ID number, masked. - `firstName` (string, optional, nullable) — Given name from the source record. - `lastName` (string, optional, nullable) — Family name from the source record. - `middleName` (string, optional, nullable) — Middle name, if available. - `dateOfBirth` (string, optional, nullable) — Date of birth. - `gender` (string, optional, nullable) — Gender from the source record. - `dataMatch` (boolean, optional, nullable) — Whether the submitted details matched the record. Null when nothing was compared. - `facialMatch` (VerificationResultResultFacialMatch, optional, nullable) — The selfie comparison. Null when none ran. - `facialMatchSource` (enum, optional) — Which photo the selfie was compared with. - Allowed values: `gov_record`, `chip`, `document` - `facialMatchSkipped` (string, optional, nullable) — Why no comparison ran, for example `no_face_on_document`. ### VerificationAttemptDataData What the applicant has entered so far. Null when nothing has been saved. ### VerificationStatusChangeChangedBy Who made the change. - `type` (enum, required) — The kind of actor. - Allowed values: `user`, `api_key`, `workflow`, `platform` - `id` (string, required, nullable) — The actor identifier. For a workflow, its public identifier. ### VerificationResultResultFacialMatch The selfie comparison. Null when none ran. - `match` (boolean, optional) — Whether the selfie matched. - `confidence` (double, optional, nullable) — The match score, where 80 is the default pass mark. ## Examples **Response** ```json { "addressIntel": null, "attempt": 1, "attempts": [], "checkStatus": "verified", "completedAt": "2026-04-27T12:00:05.000Z", "country": "NG", "createdAt": "2026-04-27T12:00:00.000Z", "deviceRules": null, "externalUserId": "user_42", "faceSearch": null, "hold": null, "idType": "bvn", "metadata": { "loanId": "loan_20191" }, "multiId": null, "result": { "dataMatch": true, "dateOfBirth": "1990-01-01", "facialMatch": { "confidence": 85, "match": true }, "facialMatchSkipped": null, "facialMatchSource": "gov_record", "firstName": "ADA", "gender": "f", "idNumber": "00000000001", "idNumberMasked": "0000•••001", "lastName": "EXAMPLE", "middleName": null }, "review": null, "status": "approved", "statusHistory": [], "submittedAt": "2026-04-27T12:00:00.000Z", "supportingDocuments": null, "verificationId": "ver_01j9x2k4m8", "workflow": { "id": "wf_AbC123dEf456", "name": "Identity verification", "version": 3 } } ``` **SDK Code** ```python import requests url = "https://sandbox-api.toden.co/api/kyc/verifications/id" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'https://sandbox-api.toden.co/api/kyc/verifications/id'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; 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/verifications/id" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") 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/verifications/id") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://sandbox-api.toden.co/api/kyc/verifications/id") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://sandbox-api.toden.co/api/kyc/verifications/id', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://sandbox-api.toden.co/api/kyc/verifications/id"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://sandbox-api.toden.co/api/kyc/verifications/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() ```