Keep the source. Handle the shape.
include_provenance can change how the same record is structured.
GET /kyb/YOUR_COMPANY_ID/lite?include_provenance=true
POST /kyb/search
{"name":"Example Limited","location":"GB","include_provenance":true}| Endpoint | Default | With provenance |
|---|---|---|
| Company profile | Flat object | Nested basic, address and contact groups with sources. |
| Company officers | Paginated flat records | Nested officer, appointment and address groups. |
| Shareholders | Paginated data | Source added beside data and pagination. |
| Corporate tree | Array of nodes | Object containing data and source. |
| Financials | years and groups | Same fields plus a top-level source. |
A full company report can partially succeed.
Check each section for error before accessing its fields. A section can fail with an access or limit error while the overall response is HTTP 200. Full-report officer and shareholder lists are not paginated. Use standalone operations when you need their page controls.
{
"financial": {
"error": {
"status_code": 403,
"detail": {
"message_guard": "Example: financial access not enabled."
}
}
}
}Preserve accounting context.
Financial values can be strings, null or missing. Inspect the currency, reporting period and consolidation scope before converting or comparing them. Never substitute zero for an unavailable figure.