> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Business
> Pre-create a [business](/entities/businesses) *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.
export const AgentPromptAccordion = ({prompt, title = "AI Agent Integration Prompt"}) => {
const [copied, setCopied] = React.useState(false);
const handleCopy = e => {
e.stopPropagation();
if (!prompt) return;
navigator.clipboard.writeText(prompt.trim()).then(() => {
setCopied(true);
setTimeout(() => setCopied(false), 2000);
});
};
const agents = ["Claude Code", "Codex", "Cursor", "Devin", "Windsurf", "GitHub Copilot"];
return
{}
{title}
{}
{prompt.trim()}
{}
Paste into
{agents.map(name => {name})}
;
};
Content-Type: application/json
Request body fields:
- vendor_data (string, REQUIRED) — your unique identifier. Free-form string, NOT a UUID. Must be unique among non-deleted businesses for the app. Normalised lowercase + whitespace trim ("COMPANY-1" and "company-1" collide).
- display_name (string, nullable) — friendly display name shown in Console (takes precedence over legal_name).
- legal_name (string, nullable)
- registration_number (string, nullable)
- country_code (string, nullable) — country of incorporation, ISO 3166-1 alpha-2 (e.g. "GB", "US").
- region (string, nullable) — ISO 3166-2 subdivision code.
- status (enum) — "ACTIVE" | "FLAGGED" | "BLOCKED" (VendorBusinessStatusChoices). Defaults to "ACTIVE".
- metadata (object, nullable) — arbitrary JSON.
curl:
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"}'
Response 201: full BusinessDetailItem (same shape as GET /v3/businesses/{vendor_data}/). Includes didit_internal_id (UUID), session_count=0, metadata, comments=[], created_at, updated_at. See /reference/data-models.
Failure modes (envelope {"detail": "..."} for auth):
- 400 — validation errors keyed by field. Common cases:
{ "vendor_data": ["A business with this vendor_data already exists."] } // NOT idempotent — use PATCH /v3/businesses/{vendor_data}/ to update.
{ "vendor_data": ["This field is required."] }
{ "metadata": ["Metadata must be a JSON object."] }
- 401 — missing/invalid x-api-key.
- 403 — lacks create:businesses.
- 429 — rate-limited.
Upsert pattern (NOT idempotent on vendor_data):
GET /v3/businesses/{vendor_data}/ → on 404, POST /v3/businesses/create/; on 200, PATCH /v3/businesses/{vendor_data}/.
Notes:
- Registry-derived fields (legal_name, registration_number, country_code) can be seeded here but will be OVERWRITTEN by the first approved Business Verification (KYB) session's registry data.
- last_activity_at is set at the moment of creation.
For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`}
/>
## Overview
Explicitly creates a [Business entity](/entities/businesses/overview) 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_data` is required and unique per application. Duplicates return a conflict error — use [`PATCH /v3/businesses/{vendor_data}/`](/management-api/businesses/update) 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_code` matches your application's [dangerous countries](/entities/businesses/blocklist#dangerous-countries) list, the business is created in `BLOCKED` status.
* Emits `business.data.updated`.
## Permissions
Role must grant `create:businesses`.
## Related
* [Business data model](/entities/businesses/data-model)
* [Vendor data linking](/entities/vendor-data-linking)
* [Business operations](/entities/businesses/operations)
## OpenAPI
````yaml POST /v3/businesses/create/
openapi: 3.0.0
info:
version: 3.0.0
title: Didit Verification API
description: Identity verification API. Authenticate with x-api-key header.
servers:
- url: https://verification.didit.me
security: []
tags: []
paths:
/v3/businesses/create/:
post:
tags:
- Businesses
summary: Create business
description: >-
Pre-create a [business](/entities/businesses) *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.
operationId: create_business
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
vendor_data:
type: string
nullable: true
description: >-
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.
display_name:
type: string
nullable: true
maxLength: 255
description: >-
Friendly display name shown in the console (takes precedence
over `legal_name` for UI display).
legal_name:
type: string
nullable: true
maxLength: 255
description: Official legal name of the company.
registration_number:
type: string
nullable: true
maxLength: 100
description: Company registration or incorporation number.
country_code:
type: string
nullable: true
maxLength: 10
description: >-
Country of incorporation (ISO 3166-1 alpha-2, e.g. `GB`,
`US`).
status:
type: string
enum:
- ACTIVE
- FLAGGED
- BLOCKED
default: ACTIVE
description: Initial lifecycle status. Defaults to `ACTIVE`.
metadata:
type: object
nullable: true
description: >-
Arbitrary JSON object you attach to the business. Defaults
to `{}`.
examples:
Basic:
summary: Recommended minimum
value:
vendor_data: company-456
legal_name: New Corp Ltd
country_code: US
Full:
summary: All fields
value:
vendor_data: company-789
display_name: New Corp
legal_name: New Corp International Ltd
registration_number: '98765432'
country_code: DE
status: ACTIVE
metadata:
industry: fintech
tier: enterprise
responses:
'201':
description: >-
Business created. Full business record returned (same shape as Get
Business).
content:
application/json:
schema:
$ref: '#/components/schemas/BusinessDetailItem'
examples:
Created:
value:
didit_internal_id: a1b2c3d4-e5f6-4890-abcd-ef1234567890
vendor_data: company-456
display_name: null
legal_name: New Corp Ltd
registration_number: null
country_code: US
effective_name: New Corp Ltd
status: ACTIVE
session_count: 0
approved_count: 0
declined_count: 0
in_review_count: 0
features: {}
features_list: []
last_session_at: null
last_activity_at: '2026-03-15T10:30:00Z'
first_session_at: null
tags: []
created_at: '2026-03-15T10:30:00Z'
metadata: {}
updated_at: '2026-03-15T10:30:00Z'
'400':
description: >-
Invalid body — typically a duplicate `vendor_data`, an unknown
`status`, or malformed `metadata`.
content:
application/json:
examples:
Duplicate:
value:
vendor_data:
- A business with this vendor_data already exists.
Bad status:
value:
status:
- >-
Invalid status. Valid options are: ACTIVE, FLAGGED,
BLOCKED
Bad metadata:
value:
metadata:
- Metadata must be a JSON object.
'403':
description: >-
Missing, invalid, or revoked API key, or the key cannot create
businesses for this application. This endpoint returns `403` (never
`401`) for authentication failures, including requests with no
credentials at all.
content:
application/json:
examples:
Forbidden:
value:
detail: You do not have permission to perform this action.
'429':
description: >-
Rate limit exceeded; back off and retry after the interval indicated
in `Retry-After`.
content:
application/json:
examples:
Rate limited:
value:
detail: Request was throttled. Expected available in 30 seconds.
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: curl
label: curl
source: |-
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"}'
- lang: python
label: Python
source: |-
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'])
- lang: javascript
label: JavaScript
source: >-
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);
components:
schemas:
BusinessDetailItem:
type: object
description: >-
Full business detail. Extends BusinessListItem with metadata and
updated_at.
allOf:
- $ref: '#/components/schemas/BusinessListItem'
- type: object
properties:
metadata:
type: object
description: >-
Custom metadata JSON you attached to this business. Defaults to
`{}`.
updated_at:
type: string
format: date-time
BusinessListItem:
type: object
description: A verified business.
properties:
didit_internal_id:
type: string
format: uuid
description: Didit's stable internal UUID for this business.
vendor_data:
type: string
nullable: true
description: >-
Your unique identifier for this business (passed when creating
sessions). This can be null when no vendor identifier was supplied.
display_name:
type: string
nullable: true
description: Custom display name set by you
legal_name:
type: string
nullable: true
description: Official legal name from registry or manual entry
registration_number:
type: string
nullable: true
description: Company registration or incorporation number
country_code:
type: string
nullable: true
description: Country of incorporation (ISO 3166-1 alpha-2, e.g. `GB`, `US`).
effective_name:
type: string
nullable: true
description: 'Best available name: display_name if set, otherwise legal_name'
status:
type: string
enum:
- ACTIVE
- FLAGGED
- BLOCKED
description: >-
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`.
session_count:
type: integer
description: Total number of verification sessions for this business
approved_count:
type: integer
description: Number of approved sessions
declined_count:
type: integer
description: Number of declined sessions
in_review_count:
type: integer
description: Number of sessions in review
features:
type: object
description: >-
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`.
features_list:
type: array
items:
type: object
properties:
feature:
type: string
status:
type: string
description: >-
Same data as `features`, as an ordered array of `{feature, status}`
objects.
last_session_at:
type: string
format: date-time
nullable: true
description: Timestamp of the most recent session
first_session_at:
type: string
format: date-time
nullable: true
description: Timestamp of the first session
last_activity_at:
type: string
format: date-time
nullable: true
description: >-
Timestamp of the most recent activity (status change, session
update, etc.)
tags:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
name:
type: string
color:
type: string
description: Tags assigned to this business
created_at:
type: string
format: date-time
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
````