---
updatedAt: 2026-09-30T07:49:22.000Z
agentTools:
  projectIndex: https://docs.company.info/llms.txt
---

# Create a new investigation order

Submits a new UBO investigation for a Dutch organization. The order is
processed asynchronously — poll the order and check `status.phase` to
track progress.


# OpenAPI definition

```json
{
  "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-investigations",
      "description": "Production"
    }
  ],
  "security": [
    {
      "authToken": []
    },
    {
      "jwtAuth": []
    }
  ],
  "tags": [
    {
      "name": "Orders",
      "description": "Create, list, and track investigation orders"
    }
  ],
  "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"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "authToken": {
        "description": "API Key Authentication",
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "jwtAuth": {
        "description": "JWT Authentication",
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "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"
            }
          }
        }
      },
      "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"
          }
        }
      },
      "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"
              }
            }
          }
        }
      }
    }
  }
}
```