{"openapi":"3.0.3","info":{"title":"UBO Investigation API","description":"The UBO Investigation API identifies the Ultimate Beneficial Owners (UBOs)\nof Dutch organizations. Given a KVK registration number, it traverses the\nownership structure, fetches official trade register extracts, maps entities\nand their relationships, and classifies who ultimately controls or benefits\nfrom the organization.\n\nThis is an asynchronous API: submit an order, poll its status, then fetch\nthe result once processing has succeeded.\n\nRequests and responses for orders and receipts use the JSON:API format\n(`application/vnd.api+json`). Errors follow the RFC 9457 Problem Details\nformat (`application/problem+json`).\n","version":"1.0.0"},"servers":[{"url":"https://api.company.info/nl/organizations/ubo-investigation","description":"Production"}],"security":[{"apiKey":[]}],"tags":[{"name":"Orders","description":"Create, list, and track investigation orders"},{"name":"Results","description":"Retrieve the receipt and full result of a completed order"}],"paths":{"/v1/orders":{"post":{"tags":["Orders"],"summary":"Create a new investigation order","description":"Submits a new UBO investigation for a Dutch organization. The order is\nprocessed asynchronously — poll the order and check `status.phase` to\ntrack progress.\n","operationId":"createOrder","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrderRequest"},"example":{"data":{"type":"orders","attributes":{"reference":"my-charge-code","organization":{"id":"33302047"},"dataSources":{"documents":{"extract":{"fromDate":"2024-10-02","orderIfChanged":true}}}}}}}}},"responses":{"201":{"description":"Order created and workflow started","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/OrderResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalError"}}},"get":{"tags":["Orders"],"summary":"List investigation orders","description":"Returns all investigation orders for your account, optionally filtered by reference.","operationId":"listOrders","parameters":[{"name":"filter[reference]","in":"query","required":false,"description":"Return only orders matching this reference value","schema":{"type":"string","maxLength":250}}],"responses":{"200":{"description":"List of orders","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/OrderListResponse"}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/orders/{id}":{"get":{"tags":["Orders"],"summary":"Get a single investigation order","description":"Retrieves a single order by its UUID. Use this to poll the processing status.","operationId":"getOrder","parameters":[{"$ref":"#/components/parameters/OrderID"}],"responses":{"200":{"description":"Order details","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/OrderResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/orders/{id}/receipt":{"get":{"tags":["Results"],"summary":"Get the receipt for a completed order","description":"Returns a summary of the resources consumed by the investigation —\ndocuments ordered or reused and profiles visited. Available once the\norder phase is `succeeded` or `failed`.\n","operationId":"getOrderReceipt","parameters":[{"$ref":"#/components/parameters/OrderID"}],"responses":{"200":{"description":"Order receipt with document and profile counts","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ReceiptResponse"},"example":{"data":{"type":"receipt","attributes":{"dataSources":{"documents":{"extracts":[{"type":"ordered","count":2},{"type":"reused","count":1}]}},"profiles":{"organizations":3,"individuals":5}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/orders/{id}/result":{"get":{"tags":["Results"],"summary":"Get the investigation result for a completed order","description":"Returns the full investigation output: a graph of entities and their\nconnections, plus the UBO classification. Available once the order\nphase is `succeeded`.\n","operationId":"getOrderResult","parameters":[{"$ref":"#/components/parameters/OrderID"}],"responses":{"200":{"description":"Full investigation result with entities, connections, and UBO classification","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ResultResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key authentication. Contact your Account Manager to have one created."}},"parameters":{"OrderID":{"name":"id","in":"path","required":true,"description":"Order UUID","schema":{"type":"string","format":"uuid"}}},"responses":{"BadRequest":{"description":"Invalid request body or parameters","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"},"example":{"type":"https://api.company.info/problems/bad-request","title":"Bad Request","status":400,"detail":"invalid fromDate format, expected YYYY-MM-DD"}}}},"NotFound":{"description":"Resource not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"},"example":{"type":"https://api.company.info/problems/not-found","title":"Not Found","status":404,"detail":"Order with ID 3e02855b-6c6d-44da-8d8f-42137f54eaf7 was not found"}}}},"InternalError":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"},"example":{"type":"https://api.company.info/problems/internal-error","title":"Internal Server Error","status":500,"detail":"an unexpected error occurred"}}}}},"schemas":{"ProblemDetail":{"type":"object","title":"Problem Detail","description":"RFC 9457 problem detail, returned with content type application/problem+json.","required":["title","status"],"properties":{"type":{"type":"string","format":"uri","description":"URI reference identifying the problem type","example":"https://api.company.info/problems/not-found"},"title":{"type":"string","description":"Short, human-readable summary of the problem","example":"Not Found"},"status":{"type":"integer","description":"HTTP status code","example":404},"detail":{"type":"string","description":"Human-readable explanation specific to this occurrence","example":"Order with ID 3e02855b-6c6d-44da-8d8f-42137f54eaf7 was not found"}}},"OrderExtract":{"type":"object","required":["fromDate"],"properties":{"fromDate":{"type":"string","format":"date","description":"Only include documents dated from this date (YYYY-MM-DD)","example":"2024-10-02"},"orderIfChanged":{"type":"boolean","description":"Re-order the extract if it has changed since last retrieved","default":false}}},"OrderDataSources":{"type":"object","required":["documents"],"properties":{"documents":{"type":"object","required":["extract"],"properties":{"extract":{"$ref":"#/components/schemas/OrderExtract"}}}}},"OrderOrganization":{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"8-digit KVK organization ID","minLength":8,"maxLength":8,"example":"33302047"},"name":{"type":"string","description":"Organization name (populated by the workflow)","example":"CompanyInfo B.V."}}},"OrderStatus":{"type":"object","title":"Order Status","required":["phase"],"properties":{"phase":{"type":"string","description":"Order processing phase","enum":["queued","processing","succeeded","failed","cancelled"],"example":"queued"},"reason":{"type":"string","description":"Failure reason; only present when phase is failed","enum":["timeout","invalidDocument","documentOrderingFailed","profileFetchFailed","internalError"],"example":"timeout"},"message":{"type":"string","description":"Human-readable detail; only present when phase is failed","example":"Document retrieval timed out after 30s"}}},"OrderAttributes":{"type":"object","required":["organization","dataSources","status"],"properties":{"reference":{"type":"string","maxLength":250,"description":"Optional searchable charge code","example":"my-charge-code"},"organization":{"$ref":"#/components/schemas/OrderOrganization"},"dataSources":{"$ref":"#/components/schemas/OrderDataSources"},"status":{"$ref":"#/components/schemas/OrderStatus"}}},"OrderData":{"type":"object","title":"Order","required":["type","id","attributes"],"properties":{"type":{"type":"string","enum":["orders"],"example":"orders"},"id":{"type":"string","format":"uuid","description":"Order ID used for all subsequent calls","example":"3e02855b-6c6d-44da-8d8f-42137f54eaf7"},"attributes":{"$ref":"#/components/schemas/OrderAttributes"}}},"OrderResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/OrderData"}}},"OrderListResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OrderData"}}}},"CreateOrderAttributes":{"type":"object","required":["organization","dataSources"],"properties":{"reference":{"type":"string","maxLength":250,"description":"Optional searchable charge code","example":"my-charge-code"},"organization":{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"8-digit KVK organization ID","minLength":8,"maxLength":8,"example":"33302047"}}},"dataSources":{"$ref":"#/components/schemas/OrderDataSources"}}},"CreateOrderRequest":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","attributes"],"properties":{"type":{"type":"string","enum":["orders"],"example":"orders"},"attributes":{"$ref":"#/components/schemas/CreateOrderAttributes"}}}}},"ExtractCount":{"type":"object","required":["type","count"],"properties":{"type":{"type":"string","description":"Whether the extracts were newly ordered or reused from cache","enum":["ordered","reused"],"example":"ordered"},"count":{"type":"integer","minimum":0,"example":2}}},"ReceiptAttributes":{"type":"object","title":"Receipt Attributes","properties":{"dataSources":{"type":"object","properties":{"documents":{"type":"object","properties":{"extracts":{"type":"array","items":{"$ref":"#/components/schemas/ExtractCount"}}}}}},"profiles":{"type":"object","properties":{"organizations":{"type":"integer","minimum":0,"description":"Number of organization profiles traversed","example":3},"individuals":{"type":"integer","minimum":0,"description":"Number of individual profiles visited","example":5}}}}},"ReceiptResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","attributes"],"properties":{"type":{"type":"string","enum":["receipt"],"example":"receipt"},"attributes":{"$ref":"#/components/schemas/ReceiptAttributes"}}}}},"EntityDataSource":{"type":"object","properties":{"kind":{"type":"string","example":"Document"},"category":{"type":"string","example":"standardExtract"}}},"EntityLinks":{"type":"object","description":"Optional links; may be absent depending on data availability","properties":{"profile":{"type":"string","format":"uri","example":"https://api.company.info/v1/organizations/33302047"},"dataSource":{"type":"string","format":"uri"}}},"Entity":{"type":"object","title":"Entity","required":["type","dataSource"],"properties":{"type":{"type":"string","description":"The kind of node in the ownership graph","enum":["Organization","Individual","ForeignOrganization","Unknown"],"example":"Organization"},"dataSource":{"$ref":"#/components/schemas/EntityDataSource"},"attributes":{"type":"object","description":"Type-specific attributes (organization or individual fields)"},"links":{"$ref":"#/components/schemas/EntityLinks"}}},"Connection":{"type":"object","title":"Connection","description":"A directed relationship between two entities, identified by their UUIDs","required":["from","to","meta"],"properties":{"from":{"type":"string","format":"uuid","description":"UUID of the entity holding the role"},"to":{"type":"string","format":"uuid","description":"UUID of the entity being connected to"},"isCircularReference":{"type":"boolean","description":"True when `to` is an entity that already appears higher up in this\nownership chain. The connection is still returned so the cycle is\nvisible, but traversal does not continue past it.\n","default":false,"example":false},"meta":{"type":"object","required":["functions"],"properties":{"functions":{"type":"array","description":"The functions held by `from` within `to`. A connection is only returned when it carries at least one function.","items":{"$ref":"#/components/schemas/ConnectionFunction"}}}}}},"FunctionType":{"type":"string","title":"Function Type","description":"Function (role) type held by an entity, returned in Dutch in PascalCase.\n\nKnown values: `Bestuurder`, `Commissaris`, `Gevolmachtigde`,\n`EnigAandeelhouder`, `Eigenaar`, `Vennoot`, `Vereffenaar`, `Maat`,\n`FunctionarisBuitr`, `Curator`, `RechterCommissaris`, `Bewindvoerder`,\n`BevoegdFunctionaris`, `Bewaarder`, `Functionaris`, `LedenRederij`.\n\nTreat this as an open set: a value that is not recognised is passed\nthrough unchanged rather than rejected.\n","example":"Gevolmachtigde"},"ConnectionFunction":{"type":"object","title":"Connection Function","description":"A single function held through a connection","required":["type"],"properties":{"type":{"$ref":"#/components/schemas/FunctionType"},"startDate":{"type":"string","format":"date","description":"Date from which the function is effective, when available","example":"2019-04-01"}}},"ClassificationStatus":{"type":"object","properties":{"phase":{"type":"string","enum":["done","failed"],"example":"done"},"reason":{"type":"string"},"message":{"type":"string"}}},"ClassificationFunction":{"type":"object","title":"Classification Function","description":"The function through which the classification applies","required":["type"],"properties":{"type":{"$ref":"#/components/schemas/FunctionType"}}},"ClassificationResult":{"type":"object","properties":{"from":{"type":"string","format":"uuid","description":"UUID of the classified individual"},"to":{"type":"string","format":"uuid","description":"UUID of the organization the classification applies to"},"function":{"$ref":"#/components/schemas/ClassificationFunction"},"label":{"type":"string","description":"UBO classification label","enum":["UBO","UBOGateway","UBOSuspect"],"example":"UBOGateway"}}},"ResultAttributes":{"type":"object","title":"Result Attributes","properties":{"organizationID":{"type":"string","description":"8-digit organization ID the result belongs to","example":"33302047"},"entities":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/Entity"},"description":"Map of entity UUID to entity object"},"connections":{"type":"array","items":{"$ref":"#/components/schemas/Connection"}},"classification":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/ClassificationStatus"},"result":{"type":"array","items":{"$ref":"#/components/schemas/ClassificationResult"}}}}}},"ResultResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","id","attributes"],"properties":{"type":{"type":"string","enum":["result"],"example":"result"},"id":{"type":"string","format":"uuid"},"attributes":{"$ref":"#/components/schemas/ResultAttributes"}}}}}}}}