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

# Unternehmensverifizierung (KYB): Vendor-CRUD-Operationen

> Didit-Unternehmen (KYB) per Management API verwalten: anlegen, auflisten, abrufen, aktualisieren, Status ändern, löschen. Abrechnung pro Aufruf.



Prompt für Unternehmensoperationen
        Prompt in die Zwischenablage kopieren



      
      

\<pre>

\````# 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. The business records are removed permanently. Verification sessions are not covered by this endpoint; delete those with the session delete endpoints.

\## 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````

\</pre>



      
      

Einfügen in

Die gesamte Verwaltung von Unternehmen erfolgt über sechs öffentliche Endpoints unter `/v3/businesses/`. Diese Seite bietet einen konzeptionellen Überblick. Die vollständigen Schemas für Anfragen und Antworten finden Sie in der [API-Referenz](https://docs.didit.me/de/management-api/businesses/list.md).## Unternehmen auflisten**`GET /v3/businesses/`**Paginierte Liste der Unternehmen für Ihre Anwendung mit Filtern für Status, Suchbegriff, Land und Datumsbereich.```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"
```## Ein Unternehmen abrufen**`GET /v3/businesses/{vendor_data}/`**Ruft ein einzelnes Unternehmen anhand von `vendor_data` ab.```bash theme={null}
curl https://verification.didit.me/v3/businesses/biz-acme/ \
  -H "x-api-key: YOUR_API_KEY"
```## Ein Unternehmen anlegen**`POST /v3/businesses/create/`**Legen Sie ein Unternehmen vorab an, bevor eine Sitzung der Unternehmensverifizierung (KYB) ausgeführt wird:```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" }
  }'
```Gibt einen Konfliktfehler zurück, wenn bereits ein Unternehmen mit diesem `vendor_data` existiert. Verwenden Sie `PATCH`, um ein bestehendes Unternehmen zu aktualisieren.## Ein Unternehmen aktualisieren**`PATCH /v3/businesses/{vendor_data}/`**Aktualisieren Sie änderbare Profilfelder. Felder, die aus Registerabfragen stammen (`legal_name`, `registration_number`, `country_code`), sind nach der Verifizierung schreibgeschützt, können aber überschrieben werden. Überschreibungen werden im Audit-Log markiert.**Änderbare Felder:** `display_name`, `metadata`, `tags`.
**Nach der Verifizierung schreibgeschützt:** alle aus Registerdaten abgeleiteten Felder, Summenzähler, `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" } }'
```Löst `business.data.updated` aus.## Status ändern**`PATCH /v3/businesses/{vendor_data}/update-status/`**Verschieben Sie ein Unternehmen zwischen `ACTIVE`, `FLAGGED` und `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"
  }'
```| Von → nach | Häufiger Auslöser |
| - | - |
| `ACTIVE` → `FLAGGED` | Sitzung der Unternehmensverifizierung (KYB) wurde in `In Review` verschoben, laufender AML-Treffer, Transaktionsregel |
| `ACTIVE` → `BLOCKED` | Bestätigte sanktionierte Entität, manueller Eintrag in die Sperrliste |
| `FLAGGED` → `ACTIVE` | Analyst hat die Prüfung freigegeben |
| `BLOCKED` → `ACTIVE` | Manuelle Entsperrung nach Behebung |Löst `business.status.updated` aus.## Unternehmen löschen (Batch)**`POST /v3/businesses/delete/`**Löscht ein oder mehrere Unternehmen. Die Unternehmensdatensätze werden dauerhaft entfernt. Ihre Verifizierungssitzungen sind von diesem Endpoint nicht erfasst und bleiben erhalten, wobei ihre Verknüpfung mit dem Unternehmen entfernt wird. Löschen Sie diese mit [Sitzung löschen](https://docs.didit.me/de/sessions-api/delete-session.md). Transaktionen sind ebenfalls nicht erfasst. Löschen Sie diese über die Konsole.```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: Das Löschen eines bereits gelöschten Unternehmens hat keine Wirkung.## BerechtigungsmodellAlle Endpoints unter `/v3/businesses/*` werden über die Berechtigungsressource `businesses` gesteuert:| Rolle | list | get | create | update | update-status | delete |
| - | :-: | :-: | :-: | :-: | :-: | :-: |
| OWNER | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| ADMIN | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| COMPLIANCE\_OFFICER | ✅ | ✅ | ❌ | ✅ | ✅ | ❌ |
| DEVELOPER | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
| READER | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |Siehe [Rollen und Berechtigungen](https://docs.didit.me/de/console/roles-permissions.md).## Von diesen Vorgängen ausgelöste Webhooks| Operation | Webhook |
| - | - |
| `create` | `business.data.updated` |
| `update` | `business.data.updated` mit `changed_fields` |
| `update-status` | `business.status.updated` |
| `delete` | `business.data.updated` mit gesetztem `deleted_at` |## Nächste Schritte> [card] [Datenmodell](https://docs.didit.me/de/entities/businesses/data-model.md)
>
> Vollständige Feldreferenz.> [card] [List-API](https://docs.didit.me/de/management-api/businesses/list.md)
>
> Schema für GET /v3/businesses/.> [card] [Erstellungs-API](https://docs.didit.me/de/management-api/businesses/create.md)
>
> Schema für POST /v3/businesses/create/.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.