Business Operations

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 → to	Common trigger
`ACTIVE` → `FLAGGED`	Business Verification (KYB) session moved to `IN_REVIEW`, ongoing AML hit, transaction rule
`ACTIVE` → `BLOCKED`	Business Verification (KYB) session `DECLINED` with auto-block, confirmed sanctioned entity
`FLAGGED` → `ACTIVE`	Analyst cleared review
`BLOCKED` → `ACTIVE`	Manual 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:

Role	list	get	create	update	update-status	delete
OWNER	✅	✅	✅	✅	✅	✅
ADMIN	✅	✅	✅	✅	✅	✅
COMPLIANCE_OFFICER	✅	✅	❌	✅	✅	❌
DEVELOPER	✅	✅	✅	❌	❌	❌
READER	✅	✅	❌	❌	❌	❌

See Roles & permissions.

Webhooks fired by these operations

Operation	Webhook
`create`	`business.data.updated`
`update`	`business.data.updated` with `changed_fields`
`update-status`	`business.status.updated`
`delete`	`business.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.

Overview

Pricing

Workflows & Verification

Review & Operations

Entities (Users & Businesses)

Settings & Customization

Security & Compliance

Resources

List businesses

Get a business

Create a business

Update a business

Change status

Delete businesses (batch)

Permission model

Webhooks fired by these operations

Next steps

Data model

List API

Create API

​List businesses

​Get a business

​Create a business

​Update a business

​Change status

​Delete businesses (batch)

​Permission model

​Webhooks fired by these operations

​Next steps

Data model

List API

Create API

List businesses

Get a business

Create a business

Update a business

Change status

Delete businesses (batch)

Permission model

Webhooks fired by these operations

Next steps