> ## 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.

# Business Operations

> Create, read, update, change status, and delete Didit Business (KYB) entities via the Management API. Pay-per-call from $2.00, no contracts.

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 <div className="didit-agent-card">
      {}
      <div className="didit-agent-titlebar">
        <div className="didit-agent-dots" aria-hidden="true">
          <span className="didit-agent-dot didit-agent-dot-red"></span>
          <span className="didit-agent-dot didit-agent-dot-yellow"></span>
          <span className="didit-agent-dot didit-agent-dot-green"></span>
        </div>
        <span className="didit-agent-filename">{title}</span>
        <button type="button" className={`didit-agent-copy ${copied ? "didit-agent-copy-copied" : ""}`} onClick={handleCopy} title="Copy prompt to clipboard" aria-label={copied ? "Copied!" : "Copy prompt to clipboard"}>
          {copied ? <>
              <svg width="13" height="13" viewBox="0 0 16 16" fill="none">
                <path d="M3 8.5l3.5 3.5L13 4" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
              </svg>
              <span>Copied</span>
            </> : <>
              <svg width="13" height="13" viewBox="0 0 16 16" fill="none">
                <rect x="5" y="5" width="9" height="9" rx="1.5" stroke="currentColor" strokeWidth="1.5" />
                <path d="M11 5V3.5A1.5 1.5 0 0 0 9.5 2h-6A1.5 1.5 0 0 0 2 3.5v6A1.5 1.5 0 0 0 3.5 11H5" stroke="currentColor" strokeWidth="1.5" />
              </svg>
              <span>Copy</span>
            </>}
        </button>
      </div>

      {}
      <pre className="didit-agent-body"><code>{prompt.trim()}</code></pre>

      {}
      <div className="didit-agent-footer">
        <span className="didit-agent-footer-label">Paste into</span>
        <div className="didit-agent-chips">
          {agents.map(name => <span key={name} className="didit-agent-chip">{name}</span>)}
        </div>
      </div>
    </div>;
};

<AgentPromptAccordion
  title="Business Operations Prompt"
  prompt={`# Goal — full CRUD over Didit Business (KYB) entities

All operations sit under \`https://verification.didit.me/v3/businesses/\` authenticated with \`x-api-key: $DIDIT_API_KEY\`. Each Business is keyed by \`vendor_data\` (case-sensitive, unique per application).

## Endpoint catalog

| Action | Method + path |
|---|---|
| List businesses | \`GET /v3/businesses/\` |
| Get one business | \`GET /v3/businesses/{vendor_data}/\` |
| Create business | \`POST /v3/businesses/create/\` |
| Update profile | \`PATCH /v3/businesses/{vendor_data}/\` |
| Change status | \`PATCH /v3/businesses/{vendor_data}/update-status/\` |
| Batch delete | \`POST /v3/businesses/delete/\` |

## List (with filters)

\`\`\`bash
curl -G https://verification.didit.me/v3/businesses/ \\
-H "x-api-key: $DIDIT_API_KEY" \\
--data-urlencode "status=ACTIVE" \\
--data-urlencode "country_code=GBR" \\
--data-urlencode "page_size=50"
\`\`\`

## Get one business

\`\`\`bash
curl https://verification.didit.me/v3/businesses/biz-acme/ \\
-H "x-api-key: $DIDIT_API_KEY"
\`\`\`

## Create

\`\`\`bash
curl -X POST https://verification.didit.me/v3/businesses/create/ \\
-H "x-api-key: $DIDIT_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{
"vendor_data": "biz-acme",
"display_name": "Acme Corp",
"country_code": "GBR",
"metadata": {"partner": "Acme Holdings"}
}'
\`\`\`

Not idempotent — a duplicate \`vendor_data\` returns conflict. \`GET\` first or PATCH.

## Update profile

\`\`\`bash
curl -X PATCH https://verification.didit.me/v3/businesses/biz-acme/ \\
-H "x-api-key: $DIDIT_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{"metadata": {"tier": "enterprise"}}'
\`\`\`

Mutable: \`display_name\`, \`metadata\`, \`tags\`. Read-only (registry-derived after a KYB session): \`legal_name\`, \`registration_number\`, \`country_code\`, all aggregate counters, \`features\` map.

## Change status

\`\`\`bash
curl -X PATCH https://verification.didit.me/v3/businesses/biz-acme/update-status/ \\
-H "x-api-key: $DIDIT_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{"status": "BLOCKED", "reason": "Sanctioned subsidiary detected"}'
\`\`\`

Valid statuses: \`ACTIVE\`, \`FLAGGED\`, \`BLOCKED\`. \`BLOCKED\` businesses have new KYB sessions and transactions auto-declined.

## Batch delete

\`\`\`bash
curl -X POST https://verification.didit.me/v3/businesses/delete/ \\
-H "x-api-key: $DIDIT_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{"vendor_data": ["biz-acme", "biz-alpha", "biz-beta"]}'
\`\`\`

Idempotent. History retained for retention window, then hard-deleted.

## Webhooks fired

| Operation | Event |
|---|---|
| create | \`business.data.updated\` |
| update (PATCH) | \`business.data.updated\` with \`changed_fields\` |
| update-status | \`business.status.updated\` |
| delete | \`business.data.updated\` with \`deleted_at\` set |

## Running a KYB session against an existing Business

KYB sessions use the same \`POST /v3/session/\` endpoint as KYC — the workflow's \`workflow_type: "kyb"\` switches the session into business mode:

\`\`\`bash
curl -X POST https://verification.didit.me/v3/session/ \\
-H "x-api-key: $DIDIT_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{"workflow_id": "$KYB_WORKFLOW_ID", "vendor_data": "biz-acme"}'
\`\`\`

## Failure modes

- \`401\` — missing / invalid \`x-api-key\`.
- \`403\` — role lacks the permission (DEVELOPER can't PATCH; see /console/roles-permissions).
- \`409\` on create — \`vendor_data\` exists; PATCH instead.
- \`404\` — wrong \`vendor_data\` casing.
- \`429\` — rate-limited; back off with \`Retry-After\`.

## Response shape

See /reference/data-models and /entities/businesses/data-model for the full Business schema.

## Sources of truth

- /management-api/businesses/list, /management-api/businesses/get, /management-api/businesses/create — per-endpoint reference
- /entities/businesses/data-model — field-by-field
- /business-verification/integration-guide — KYB session flow
- /integration/integration-prompt — canonical end-to-end prompt
`}
/>

All Business entity management happens through six public endpoints under `/v3/businesses/`. This page gives you the conceptual walkthrough — see the [API reference](/management-api/businesses/list) 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.

```bash theme={null}
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`.

```bash theme={null}
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:

```bash theme={null}
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.

```bash theme={null}
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`.

```bash theme={null}
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](/console/data-retention) period, then hard-deleted.

```bash theme={null}
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](/console/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

<CardGroup cols={3}>
  <Card title="Data model" icon="database" href="/entities/businesses/data-model">
    Full field reference.
  </Card>

  <Card title="List API" icon="list" href="/management-api/businesses/list">
    GET /v3/businesses/ schema.
  </Card>

  <Card title="Create API" icon="plus" href="/management-api/businesses/create">
    POST /v3/businesses/create/ schema.
  </Card>
</CardGroup>