Skip to main content
All Business entity management happens through six public endpoints under /v3/businesses/. This page gives you the conceptual walkthrough — see the API reference for full request / response schemas.

​
List businesses

GET /v3/businesses/ Paginated list of businesses for your application with filters on status, search, country, and date range. 
curl -G https://verification.didit.me/v3/businesses/ \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "status=ACTIVE" \
  --data-urlencode "country_code=GBR" \
  --data-urlencode "page_size=50"

​
Get a business

GET /v3/businesses/{vendor_data}/ Retrieve a single business by vendor_data. 
curl https://verification.didit.me/v3/businesses/biz-acme/ \
  -H "x-api-key: YOUR_API_KEY"

​
Create a business

POST /v3/businesses/create/ Pre-create a Business before any Business Verification (KYB) session runs: 
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": "biz-acme",
    "display_name": "Acme Corp",
    "country_code": "GBR",
    "metadata": { "partner": "Acme Holdings" }
  }'
Returns a conflict error if a business with that vendor_data already exists. Use PATCH to update an existing business.

​
Update a business

PATCH /v3/businesses/{vendor_data}/ Update mutable profile fields. Fields derived from registry lookups (legal_name, registration_number, country_code) are read-only after verification but can be overridden — overrides are flagged in the audit log. Mutable fields: display_name, metadata, tags. Read-only after verification: all registry-derived fields, aggregate counters, features map. 
curl -X PATCH https://verification.didit.me/v3/businesses/biz-acme/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "tier": "enterprise" } }'
Emits business.data.updated.

​
Change status

PATCH /v3/businesses/{vendor_data}/update-status/ Move a business between ACTIVE, FLAGGED, and BLOCKED. 
curl -X PATCH https://verification.didit.me/v3/businesses/biz-acme/update-status/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "BLOCKED",
    "reason": "Sanctioned subsidiary detected in ownership chain"
  }'
From → toCommon trigger
ACTIVE → FLAGGEDBusiness Verification (KYB) session moved to IN_REVIEW, ongoing AML hit, transaction rule
ACTIVE → BLOCKEDBusiness Verification (KYB) session DECLINED with auto-block, confirmed sanctioned entity
FLAGGED → ACTIVEAnalyst cleared review
BLOCKED → ACTIVEManual unblock after remediation
Emits business.status.updated.

​
Delete businesses (batch)

POST /v3/businesses/delete/ Delete one or more businesses. History is retained for the configured data retention period, then hard-deleted. 
curl -X POST https://verification.didit.me/v3/businesses/delete/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "vendor_data": ["biz-acme", "biz-alpha", "biz-beta"] }'
Idempotent — deleting an already-deleted business is a no-op.

​
Permission model

All /v3/businesses/* endpoints are scoped by the businesses permission resource:
Rolelistgetcreateupdateupdate-statusdelete
OWNER✅✅✅✅✅✅
ADMIN✅✅✅✅✅✅
COMPLIANCE_OFFICER✅✅❌✅✅❌
DEVELOPER✅✅✅❌❌❌
READER✅✅❌❌❌❌
See Roles & permissions.

​
Webhooks fired by these operations

OperationWebhook
createbusiness.data.updated
updatebusiness.data.updated with changed_fields
update-statusbusiness.status.updated
deletebusiness.data.updated with deleted_at set

​
Next steps

Data model

Full field reference.

List API

GET /v3/businesses/ schema.

Create API

POST /v3/businesses/create/ schema.