> 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 a business check

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

Returns one business check in full, including what the registry holds on the business. Poll this until `status` leaves `pending`. `businessRecord` is null until the business is found.

**Error codes**

| `error` | Status | Meaning |
|---|---|---|
| `not_found` | 404 | No business 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/business-checks/get-business-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 business check.

- `check` (BusinessCheck, 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

### BusinessCheck

- `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.
- `product` (string, required) — The check product that was run, for example `business`.
- `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.
- `registrationNumber` (string, optional, nullable) — The registration number that was looked up.
- `businessName` (string, optional, nullable) — The registered name the registry returned. Null until the business is found.
- `registrationName` (string, optional, nullable) — The registered name you sent with the check. Null when you sent none.
- `subdivision` (BusinessCheckSubdivision, optional, nullable) — The registry region that was asked. Null for countries with a single registry.
- `businessRecord` (BusinessRecord, optional, nullable) — What the registry holds on the business. A field the registry did not supply is absent.

### BusinessCheckSubdivision

The registry region that was asked. Null for countries with a single registry.

- `code` (string, optional) — The ISO 3166-2 region code.
- `name` (string, optional, nullable) — The name of the region.

### BusinessRecord

What the registry holds on the business. A field the registry did not supply is absent.

- `affiliates` (list of BusinessRecordAffiliatesItems, required) — Affiliated parties the registry lists.
- `keyPersonnel` (list of BusinessRecordKeyPersonnelItems, required) — Directors, shareholders and other officers the registry lists.
- `name` (string, optional) — The registered name.
- `registrationNumber` (string, optional) — The registration number.
- `registrationDate` (string, optional) — When the business was registered.
- `registrationSubmissionDate` (string, optional) — When the registration was submitted.
- `typeOfEntity` (string, optional) — The legal form of the business.
- `companyStatus` (string, optional) — The status the registry reports, for example active.
- `activity` (string, optional) — The principal activity.
- `activityDescription` (string, optional) — A description of the activity.
- `email` (string, optional) — The registered email address.
- `phone` (string, optional) — The registered phone number.
- `address` (string, optional) — The registered address.
- `branchAddress` (string, optional) — The branch address.
- `city` (string, optional) — The city.
- `state` (string, optional) — The state or region.
- `lga` (string, optional) — The local government area.
- `country` (string, optional) — The country.
- `tin` (string, optional) — The tax identification number.
- `jtbTin` (string, optional) — The joint tax board number.
- `taxId` (string, optional) — The tax id.
- `taxOffice` (string, optional) — The tax office.
- `vatNumber` (string, optional) — The VAT number.
- `registryNumber` (string, optional) — The registry number.
- `shareCapital` (string, optional) — The share capital.
- `sharesIssued` (string, optional) — The number of shares issued.
- `paidShareCapital` (string, optional) — The paid-up share capital.
- `subscribedShareCapital` (string, optional) — The subscribed share capital.
- `sharesValue` (string, optional) — The value of the shares.
- `accountNumber` (string, optional) — The bank account number that was verified (`business-account`).
- `accountHolder` (string, optional) — The account holder that was verified (`business-account`).
- `filings` (list of BusinessRecordFilingsItems, optional) — The filing history (`business-filings`).
- `accountVerification` (BusinessRecordAccountVerification, optional) — The bank account verdict (`business-account`).

### BusinessRecordAffiliatesItems

- `name` (string, optional) — The name of the affiliate.
- `type` (string, optional) — The kind of affiliate.
- `rcNumber` (string, optional) — Its registration number.
- `designation` (string, optional) — Its role.
- `shareholding` (string, optional) — Its shareholding.

### BusinessRecordKeyPersonnelItems

- `name` (string, optional) — The name of the person or company.
- `designation` (string, optional) — Their role as the registry records it, for example director or shareholder.
- `occupation` (string, optional) — Their occupation.
- `nationality` (string, optional) — Their nationality.
- `countryOfResidence` (string, optional) — Their country of residence.
- `gender` (string, optional) — Their gender.
- `dateOfBirth` (string, optional) — Their date of birth.
- `email` (string, optional) — Their email address.
- `phone` (string, optional) — Their phone number.
- `address` (string, optional) — Their address.
- `city` (string, optional) — Their city.
- `state` (string, optional) — Their state or region.
- `documentType` (string, optional) — The type of identity document the registry holds for them.
- `documentNumber` (string, optional) — The number of that identity document.
- `shareType` (string, optional) — The class of shares they hold.
- `sharesCount` (string, optional) — How many shares they hold.
- `sharesValue` (string, optional) — The value of the shares they hold.
- `shareAllotted` (string, optional) — The shares allotted to them.
- `appointedOn` (string, optional) — When they were appointed.
- `resignedOn` (string, optional) — When they resigned.
- `registrationNumber` (string, optional) — The registration number of a party that is itself a company.
- `isForeign` (boolean, optional) — Whether the registry marks them as foreign.
- `isChairman` (boolean, optional) — Whether they chair the board.
- `isCorporate` (boolean, optional) — Whether the registry marks this party as a company. Absent does not mean it is a person.

### BusinessRecordFilingsItems

- `date` (string, optional) — The filing date.
- `name` (string, optional) — The filing name.
- `type` (string, optional) — The filing type.
- `activityDescription` (string, optional) — What the filing covered.

### BusinessRecordAccountVerification

The bank account verdict (`business-account`).

- `verifiedDate` (string, optional) — When the account was verified.
- `accountFound` (string, optional) — Whether the account was found.
- `errorReason` (string, optional) — Why verification failed, if it did.
- `verified` (string, optional) — Whether the account matched.

## Examples

**Response**

```json
{
  "check": {
    "id": "cmt8s0a4p0002qw9k2m7f3abc",
    "status": "verified",
    "country": "NG",
    "initiatedVia": "api",
    "createdAt": "2026-09-12T10:00:00.000Z",
    "product": "business",
    "reasonCode": null,
    "verificationMethod": "sandbox",
    "chargedAmount": null,
    "completedAt": "2026-09-12T10:00:02.000Z",
    "reason": null,
    "chargedBreakdown": {},
    "registrationNumber": "RC0000001",
    "businessName": "Example Trading Limited",
    "registrationName": "Example Trading Limited",
    "subdivision": null,
    "businessRecord": {
      "affiliates": [],
      "keyPersonnel": [
        {
          "name": "Ada Example",
          "designation": "Director"
        }
      ],
      "name": "Example Trading Limited",
      "registrationNumber": "RC0000001",
      "typeOfEntity": "Private company limited by shares",
      "companyStatus": "Active"
    }
  }
}
```

**SDK Code**

```python
import requests

url = "https://sandbox-api.toden.co/api/kyc/checks/business/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/business/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/business/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/business/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/business/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/business/id', [
  'headers' => [
    'Authorization' => 'Bearer <apiKey>',
  ],
]);

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

```csharp
using RestSharp;

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