curl -X POST 'https://verification.didit.me/v3/businesses/create/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"vendor_data": "company-456", "legal_name": "New Corp Ltd", "country_code": "US"}'import requests
resp = requests.post(
'https://verification.didit.me/v3/businesses/create/',
headers={'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json'},
json={
'vendor_data': 'company-456',
'legal_name': 'New Corp Ltd',
'country_code': 'US',
},
)
resp.raise_for_status()
biz = resp.json()
print(biz['didit_internal_id'])const resp = await fetch('https://verification.didit.me/v3/businesses/create/', {
method: 'POST',
headers: { 'x-api-key': process.env.DIDIT_API_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({
vendor_data: 'company-456',
legal_name: 'New Corp Ltd',
country_code: 'US',
}),
});
const biz = await resp.json();
console.log(biz.didit_internal_id);<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://verification.didit.me/v3/businesses/create/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'vendor_data' => 'company-456',
'legal_name' => 'New Corp Ltd',
'country_code' => 'US'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://verification.didit.me/v3/businesses/create/"
payload := strings.NewReader("{\n \"vendor_data\": \"company-456\",\n \"legal_name\": \"New Corp Ltd\",\n \"country_code\": \"US\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://verification.didit.me/v3/businesses/create/")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"vendor_data\": \"company-456\",\n \"legal_name\": \"New Corp Ltd\",\n \"country_code\": \"US\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://verification.didit.me/v3/businesses/create/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"vendor_data\": \"company-456\",\n \"legal_name\": \"New Corp Ltd\",\n \"country_code\": \"US\"\n}"
response = http.request(request)
puts response.read_bodyCreate Business
Pre-create a business without a KYB session. All fields are optional, but you should always send vendor_data — without it the record cannot be linked to sessions or transactions. When provided, vendor_data must be unique among non-deleted businesses (exact match; conflicts return 400). Not idempotent.
curl -X POST 'https://verification.didit.me/v3/businesses/create/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"vendor_data": "company-456", "legal_name": "New Corp Ltd", "country_code": "US"}'import requests
resp = requests.post(
'https://verification.didit.me/v3/businesses/create/',
headers={'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json'},
json={
'vendor_data': 'company-456',
'legal_name': 'New Corp Ltd',
'country_code': 'US',
},
)
resp.raise_for_status()
biz = resp.json()
print(biz['didit_internal_id'])const resp = await fetch('https://verification.didit.me/v3/businesses/create/', {
method: 'POST',
headers: { 'x-api-key': process.env.DIDIT_API_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({
vendor_data: 'company-456',
legal_name: 'New Corp Ltd',
country_code: 'US',
}),
});
const biz = await resp.json();
console.log(biz.didit_internal_id);<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://verification.didit.me/v3/businesses/create/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'vendor_data' => 'company-456',
'legal_name' => 'New Corp Ltd',
'country_code' => 'US'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://verification.didit.me/v3/businesses/create/"
payload := strings.NewReader("{\n \"vendor_data\": \"company-456\",\n \"legal_name\": \"New Corp Ltd\",\n \"country_code\": \"US\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://verification.didit.me/v3/businesses/create/")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"vendor_data\": \"company-456\",\n \"legal_name\": \"New Corp Ltd\",\n \"country_code\": \"US\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://verification.didit.me/v3/businesses/create/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"vendor_data\": \"company-456\",\n \"legal_name\": \"New Corp Ltd\",\n \"country_code\": \"US\"\n}"
response = http.request(request)
puts response.read_bodyOverview
Explicitly creates a Business entity before any Business Verification (KYB) session runs.When to use it
- Pre-seed metadata (partner, tier, internal identifiers) before the first Business Verification (KYB) session.
- Migrate from another KYB vendor with an existing business roster.
- Transaction-only registration — submit transactions for a business that you verified through an offline process.
Notes
vendor_datais required and unique per application. Duplicates return a conflict error — usePATCH /v3/businesses/{vendor_data}/to update.- Registry-derived fields (
legal_name,registration_number,country_code) can be seeded but will be overwritten by the first approved Business Verification (KYB) session’s registry data. - If
country_codematches your application’s dangerous countries list, the business is created inBLOCKEDstatus. - Emits
business.data.updated.
Permissions
Role must grantcreate:businesses.
Related
Authorizations
Your application's API key, from Developers -> API keys in the Business Console. The primary key has full access. A named key can be scoped: none, read or write per resource, limited to some workflows or to approved sessions, to a list of IP addresses, and to an expiry date. 401 means the key is missing, wrong, revoked or expired; 403 means the key has no access to this resource or action, or the request came from an address outside its IP list; 404 on a session route means the session is outside the key's workflows or statuses. A key without media access receives image, video and PDF URLs as null, and a key without sessions write receives session links and tokens as null. See https://docs.didit.me/console/api-keys.
Body
Your unique identifier for this business (free-form string, NOT a UUID). Optional but strongly recommended. When provided, must be unique among non-deleted businesses for the application; matched exactly as sent.
Friendly display name shown in the console (takes precedence over legal_name for UI display).
255Official legal name of the company.
255Company registration or incorporation number.
100Country of incorporation (ISO 3166-1 alpha-2, e.g. GB, US).
10Initial lifecycle status. Defaults to ACTIVE.
ACTIVE, FLAGGED, BLOCKED Arbitrary JSON object you attach to the business. Defaults to {}.
Response
Business created. Full business record returned (same shape as Get Business).
Full business detail. Extends BusinessListItem with metadata and updated_at.
Didit's stable internal UUID for this business.
Your unique identifier for this business (passed when creating sessions). This can be null when no vendor identifier was supplied.
Custom display name set by you
Official legal name from registry or manual entry
Company registration or incorporation number
Country of incorporation (ISO 3166-1 alpha-2, e.g. GB, US).
Best available name: display_name if set, otherwise legal_name
Lifecycle status of the business record (NOT a session status). ACTIVE is the default, FLAGGED marks it for manual attention, BLOCKED prevents new sessions for this vendor_data.
ACTIVE, FLAGGED, BLOCKED Total number of verification sessions for this business
Number of approved sessions
Number of declined sessions
Number of sessions in review
Aggregated per-feature status across all of this business's KYB sessions. Currently the only key is KYB (the registry company check status). Possible values: Approved, Declined, In Review, Not Finished, Resub Requested.
Same data as features, as an ordered array of {feature, status} objects.
Show child attributes
Show child attributes
Timestamp of the most recent session
Timestamp of the first session
Timestamp of the most recent activity (status change, session update, etc.)
Tags assigned to this business
Show child attributes
Show child attributes
Custom metadata JSON you attached to this business. Defaults to {}.