Primary VDT API Integration Flow
Integrators wire only the APIs their product needs — the diagram shows every supported path. Solid arrows are primary steps; dashed edges are optional lookups or return paths. Click any node to open its API reference in a new tab.
How to read the diagram
| Element | Meaning |
|---|---|
| Choice nodes (dashed border) | Branch points — your UI decides which path to take |
| Solid main path | Typical browse flow: registry → list → ledger detail |
| Dashed blue edges | Optional lookups (filter, refresh list, view created, re-read) |
| Dashed orange / green / red | Lifecycle actions from ledger detail |
Integration paths
1. Registry discovery (always start here)
GET /public-api/v1/registries/list → GET /public-api/v1/registries/{id}
List available registries, then load the selected registry schema before any ledger operation. Read isDataVdt — it controls which lifecycle APIs are valid for that registry.
Registry type decision (API routing)
After Get Registry, every create and update request is routed by isDataVdt:
| Rule | ERC-721 | DataVDT |
|---|---|---|
Create without options.mint: true | Rejected | Draft saved |
| Update after mint | Re-mint allowed | Rejected — immutable |
| Re-mint after mint | Allowed | Never |
| Burn | When burnable: true | Not supported |
| Transfer | When transferable: true | Not supported |
Wire your UI from Get VDT mint status and registry isDataVdt — hide update on minted DataVDT ledgers and never expose burn or transfer for DataVDT registries.
2. Browse ledgers
After selecting a registry, call List VDTs to show all ledgers under that registry.
| API | Method | Purpose |
|---|---|---|
| List VDTs | GET /public-api/v1/vdt/list/{registryId} | Paginated ledger list |
| Search VDTs | POST /public-api/v1/vdt/search | Optional filter by searchable attributes |
| Get VDT | GET /public-api/v1/vdt/{entityId} | Ledger detail — full 4W snapshot |
Use Search VDTs when the user searches by a business key (employee number, asset tag, etc.) instead of browsing the full list.
3. Create & mint
| Registry | Create behavior |
|---|---|
| ERC-721 | options.mint: true required |
| DataVDT | options.mint: false → draft; options.mint: true → create and mint |
Call Create Primary VDT with registryId, attributesData, and deviceId.
After create, optionally refresh list or view created ledger via Get VDT using the returned entityId.
4. Ledger actions (from detail view)
Gate actions on isDataVdt, mint status, and registry flags:
| Action | API | Method | When available |
|---|---|---|---|
| Update | Update VDT | PATCH /public-api/v1/vdt/{entityId} | DataVDT: draft only. ERC-721: always (requires options.mint: true) |
| Transfer | Transfer VDT | POST /public-api/v1/vdt/transfer | ERC-721 only, when transferable: true and ledger is minted |
| Burn | Burn VDT | DELETE /public-api/v1/vdt/burn | ERC-721 custom only, when burnable: true and ledger is minted |
DataVDT: once minted, the ledger is immutable — no update, no re-mint, no burn, no transfer.
5. Transfer — KYB org lookup
Before Transfer VDT, load the destination organization list:
GET /public-api/v1/kyb/groups/members
This returns business-group member organizations (Business Customers, Business Contacts, and custom groups). The user selects a destination org; pass its ID as toOrgId in the transfer request.
Transfer and burn are asynchronous — a successful response means the request was accepted, not that the blockchain transaction is finalized.
Required scopes
| Operation | Token scope |
|---|---|
| Registry list / get | vdt.read |
| List / search / get VDT | vdt.read |
| Create / update | vdt.write |
| List org members (KYB) | kyb.organization.read |
| Transfer | vdt.transfer |
| Burn | vdt.burn |