{"openapi":"3.1.0","info":{"title":"Welcome to Boniforce API Documentation","description":"\nWith the Boniforce API you can access company information and create new reports.\n\n## Authentication\n\nThe API is authenticated using a bearer token (API key).\nYou can get your API key by [contacting us](mailto:team@boniforce.de) or by creating one yourself via our dashboard application at [dashboard.boniforce.de](http://dashboard:3000/).\n\n## Workflow\n\nThe API workflow is as follows:\n\n### 1. Obtain an API key\n\nYou can obtain an API key by contacting us or by creating one yourself via our dashboard application at http://dashboard:3000/.\n\n### 2. Search for a company\n\nUse the `/v1/search` endpoint to search for a company. You can pass the company name as a URL query parameter.\nThe endpoint returns a list of companies that match the search query.\nFor further identification, it also returns the register information (`register_type`, `register_number`, `register_court`) of each company.\nEach result includes a `search_result_id` that can be passed to `POST /reports` instead of register fields.\n\nIf `/v1/search` returns no match, use `/v1/search/advanced` as a fallback.\n\n### 3. Create a report\n\nUse the `/v1/reports` endpoint to create a new report. Pass either the register information\n(`register_type`, `register_number`, `register_court`) or a `search_result_id` from a prior search.\nWhen register details are missing, company identification is best-effort during report generation.\nThis queues a job on our side that is processed in the background.\nThe endpoint returns a job ID and a status.\n\n### Optional: Financial data\n\nUse `POST /v1/financial_data` with the same JSON body as report creation to retrieve raw financial statement data for that company.\n\n### 4. Check job status\n\nUse the `/v1/jobs/{job_id}/status` endpoint to check the status of a report.\nYou need to pass the job ID that you received when creating the report.\n\nThe endpoint returns the current status of the report.\nPossible values: `queued`, `processing`, `completed`, `failed`.\n\nIf the status is `completed`, you can retrieve the report using the `/v1/reports/{report_id}` endpoint.\n\n### 5. Retrieve the report\n\nUse the `/v1/reports/{report_id}` endpoint to retrieve the report.\n\n## Pricing\n\nOur API uses a pay-as-you-go pricing model, with credits that are assigned to packages.\nEach package contains a certain number of credits that can be used to make requests to the API.\nThis allows you to control your costs and avoid unexpected charges.\n\nFor an overview of the available packages, please refer to our [packages page](http://dashboard:3000//credits/upgrade).\n\nThe credits required for each endpoint are listed below.\n\n| Endpoint | Credits | Description |\n| -------- | ------- | ----------- |\n| Search | 1 | Search for companies by name. |\n| Advanced Search | 5 | Extended search using internal databases and improved matching when normal search finds nothing. |\n| Report Creation | 75 | Create a new report for a company. |\n| Financial Data | 25 | Per-year financial features. |\n| Financial Data Analysis | 50 | Per-year financial features, score, and analysis breakdown. |\n| Job Status | 0 | Check the status of a report generation job. |\n| Report Retrieval | 0 | Retrieve a report by `report_id`. |\n| API Key Creation | 0 | Create a new API key (currently not supported). |\n\n## Sandbox\n\nWe offer a dedicated sandbox environment so you can integrate and test your\nclient against the Boniforce API *without spending credits* and without relying\non real company data.\n\n- **Base URL:** [https://sandbox.boniforce.de/v1](https://sandbox.boniforce.de/v1)\n- **Documentation:** [https://sandbox.boniforce.de/v1/docs](https://sandbox.boniforce.de/v1/docs)\n\nThe sandbox exposes the same endpoints as the production API, but all response data is *artificial* - company search results, reports, scores, and financial data are generated for testing purposes and do not reflect real companies.\n\n### Get Access\n\nSandbox requests use the same bearer token scheme as production, but with a test key. \nTo use the sandbox, prefix your API key with `sk_test-` instead of `sk_live-`:\n\n```\nAuthorization: Bearer sk_test-SOME_STRING\n```\n\n","version":"1.0.0"},"paths":{"/v1/search":{"get":{"tags":["Search"],"summary":"Search for companies","description":"```\nGET /search\n```\n\nUse this endpoint to search for companies by name.\nThe endpoint returns the matched companies together with the official register information.\nThe register information (`register_type`, `register_number`, `register_court`) uniquely identifies the company and is used to create a report.\nEach result includes a `search_result_id` that can be passed to `POST /reports` instead of register fields.\n\n`registered_office` is always empty on this endpoint. Companies are identified via register information; a separate city field is not needed.\n\n**Credits:** 1 credits per request","operationId":"search_companies_search_get","security":[{"Bearer Token":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"Search string (company name, etc.)","title":"Query"},"description":"Search string (company name, etc.)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CompanySearchResponse"},"title":"Response Search Companies Search Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/search/advanced":{"get":{"tags":["Search"],"summary":"Advanced search for companies","description":"```\nGET /search/advanced\n```\n\nUse this endpoint when the normal `/search` endpoint does not return a matching company.\nIt queries internal databases with an improved matching mechanism that tries to find\ncompanies more eagerly - including partial names, abbreviations, and alternative spellings.\n\nThe response format matches `/search`: a list of companies with register information\n(`register_type`, `register_number`, `register_court`) when available.\nEach result includes a `search_result_id` that can be passed to `POST /reports`.\n\n**Identification:** When register details are missing or ambiguous, results include\n`registered_office` (city) to help end users tell similar companies apart. This field\nis provided for display and identification only - it does not replace register information\nwhen register fields are present.\n\nRegister details may be incomplete or not fully up to date; we cannot guarantee that\nreturned register information reflects the latest commercial register status.\n\n**Credits:** 5 credits per request","operationId":"search_companies_advanced_search_advanced_get","security":[{"Bearer Token":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"Search string (company name, etc.)","title":"Query"},"description":"Search string (company name, etc.)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CompanySearchResponse"},"title":"Response Search Companies Advanced Search Advanced Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/reports":{"get":{"tags":["Reports"],"summary":"List available reports","description":"```\nGET /reports\n```\n\nReturns a list of available reports for the authenticated user. \nUse the returned report_id to retrieve the detailed report using the `/v1/reports/{report_id}` endpoint.\n\n**Credits**: 0 credits per request.","operationId":"list_user_reports_reports_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/ReportListItemResponse"},"type":"array","title":"Response List User Reports Reports Get"}}}}},"security":[{"Bearer Token":[]}]},"post":{"tags":["Reports"],"summary":"Create a report","description":"```\nPOST /reports\n```\n\nRequest a new report for the given company identified by its register information (register_type, register_number, register_court). \nAlthough the company `name` is required, it is not used for identification purposes.\n\nAlternatively, pass a `search_result_id` returned by `/search` or `/search/advanced`.\n\nWhen register details are missing from the stored search result, company identification\nis best-effort and register data may be completed during report generation without guarantee.\n\nThe endpoint returns a `job_id` and a `status` - most likely `queued` for the first time.\n\n**Credits**: 75 credits per request.","operationId":"create_report_reports_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportCreateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportCreateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"Bearer Token":[]}]}},"/v1/financial_data":{"get":{"tags":["Financial data"],"summary":"Get company financial data","description":"```\nGET /financial_data\n```\n\nReturns financial statement features for a company.\n\n**Identification (one of the following is required):**\n\n- **`search_result_id`** — the id returned by `GET /search` or\n  `GET /search/advanced`. This uniquely identifies the company.\n- **`register_type`** + **`register_number`** + **`register_court`** — all\n  three must be provided together.\n\n`company_name` is always optional and only used to improve matching when\nregister fields are provided.\n\n**Response** (per reporting year, values in EUR):\n\n- `financials` — flat summary used for scoring (`jahr`,\n  `jahresueberschuss`, `eigenkapital`, `verbindlichkeiten`, `umlaufvermoegen`,\n  `bilanzsumme`, `forderungen`, `liquide_mittel`).\n- `financial_reports` - structured Aktiva / Passiva / GuV breakdown. \n  Top-level categories: `anlagevermoegen`,\n  `umlaufvermoegen`, `vorraete` (Aktiva); `eigenkapital`, `rueckstellungen`,\n  `verbindlichkeiten` (Passiva). Each carries a `<category>_details` object\n  with one-level child breakdowns where available; missing children are\n  returned as `null`. `guv` is reserved (always `null` for now).\n\n**Credits:** 25 credits per request.","operationId":"get_financial_data_financial_data_get","security":[{"Bearer Token":[]}],"parameters":[{"name":"company_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name"}},{"name":"register_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Register Type"}},{"name":"register_number","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Register Number"}},{"name":"register_court","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Register Court"}},{"name":"search_result_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search Result Id"}},{"name":"session_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinancialDataResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/financial_data/analysis":{"get":{"tags":["Financial data"],"summary":"Get financial data analysis and score","description":"```\nGET /financial_data/analysis\n```\n\nReturns the same per-year financial features as `/financial_data`, enriched with the\ncomputed `score` (0-100) and the ratio breakdown\n(`eigenkapitalquote`, `verbindlichkeitenquote`, `deckungsgrad_verbindlichkeiten`,\n`verschuldungsgrad`). Each ratio includes its raw `value`, the scaled `score`\n(0-100) and a traffic-light `color` code (`0` = green, `1` = orange, `2` = red).\n\n**Identification (one of the following is required):**\n\n- **`search_result_id`** — the id returned by `GET /search` or\n  `GET /search/advanced`. This uniquely identifies the company.\n- **`register_type`** + **`register_number`** + **`register_court`** — all\n  three must be provided together.\n\n`company_name` is always optional and only used to improve matching when\nregister fields are provided.\n\n**Credits:** 50 credits per request.","operationId":"get_financial_data_analysis_financial_data_analysis_get","security":[{"Bearer Token":[]}],"parameters":[{"name":"company_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name"}},{"name":"register_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Register Type"}},{"name":"register_number","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Register Number"}},{"name":"register_court","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Register Court"}},{"name":"search_result_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search Result Id"}},{"name":"session_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinancialAnalysisResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/jobs/{job_id}/status":{"get":{"tags":["Jobs"],"summary":"Get report generation status","description":"```\nGET /jobs/{job_id}/status\n```\n\nQuery the status of the report generation (process) using the `job_id` that you received when creating the report.\nReturns the current status of a report generation job.\nPossible values: `queued`, `processing`, `completed`, `failed`.\n\nIf the status is `completed`, you can retrieve the detailed report using the `/v1/reports/{report_id}` endpoint.\n\n**Note**: The status is updated every 2 seconds.\n\n**Credits**: 0 credits per request.","operationId":"get_job_status_endpoint_jobs__job_id__status_get","security":[{"Bearer Token":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/reports/{report_id}":{"get":{"tags":["Reports"],"summary":"Get report by report_id","description":"```\nGET /reports/{report_id}\n```\n\nReturns a detailed financial credit report for the given report identified by its `report_id`.\n\nThe response always includes a `status` field reflecting the **company's**\nstate (e.g. `active`, `inactive`, `liquidation`). If the company is\n`inactive` or in `liquidation`, there is no meaningful credit profile to\nreport: `score`, `score_details`, `credit_assessment_result`, `credit_limit`\nand `assessments` are returned as `null`. The `company` envelope (name,\nregister info, firmographics) is still populated.\n\n**Credits**: 0 credits per request.","operationId":"get_report_by_report_id_reports__report_id__get","security":[{"Bearer Token":[]}],"parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","title":"Report Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoniReportResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/reports/{report_id}/financial_data":{"get":{"tags":["Reports"],"summary":"Get financial data for a company","description":"```\nGET /reports/{report_id}/financial_data\n```\n\nReturns the financial statement data for a company that the authenticated\nuser has already generated a report for. No credits are charged - the\nendpoint only returns data that was already fetched during report creation\nor a prior `/financial_data` call.\n\nThe response shape matches `GET /financial_data`: both the flat\n`financials` summary and the structured `financial_reports` breakdown\n(Aktiva / Passiva / GuV) are returned, with identical values per year.\n\nReturns `404` if the user has no report for `report_id`, or if no financial\ndata is available for the company.\n\n**Credits**: 0 credits per request.","operationId":"get_report_financial_data_reports__report_id__financial_data_get","security":[{"Bearer Token":[]}],"parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","title":"Report Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinancialDataResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/reports/{report_id}/financial_data/analysis":{"get":{"tags":["Reports"],"summary":"Get financial data analysis for a report","description":"```\nGET /reports/{report_id}/financial_data/analysis\n```\n\nReturns the same per-year financial features as\n`GET /reports/{report_id}/financial_data`, enriched with the computed `score`\n(0-100) and the ratio breakdown (`eigenkapitalquote`, `verbindlichkeitenquote`,\n`deckungsgrad_verbindlichkeiten`, `verschuldungsgrad`). Each ratio includes its raw\n`value`, the scaled `score` (0-100) and a traffic-light `color` code\n(`0` = green, `1` = orange, `2` = red).\n\nOnly works for reports the authenticated user has already generated.\nNo credits are charged.\n\nReturns `404` if the user has no report for `report_id`, or if no cached financial\ndata is available.\n\n**Credits**: 0 credits per request.","operationId":"get_report_financial_data_analysis_reports__report_id__financial_data_analysis_get","security":[{"Bearer Token":[]}],"parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","title":"Report Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinancialAnalysisResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/company/{report_id}/details":{"get":{"tags":["Company"],"summary":"Get company metadata (details)","description":"```\nGET /company/{report_id}/details\n```\n\nReturns metadata for a company the authenticated user has already generated a\nreport for. The response carries the same company envelope as the `company`\nfield of `GET /reports/{report_id}` (name, address, `register_info`,\n`firmographics`), enriched with the company's `representatives` (managing\ndirectors / Geschäftsführer, Prokuristen, etc.).\n\nEach representative is either a `NATURAL_PERSON` or a `LEGAL_ENTITY` and carries\nits `role`, `start_date` and `end_date`. An entry without an `end_date` is still\nactive.\n\nReturns `404` if the user has no report for `report_id`.\n\n**Credits:** 0 credits per request.","operationId":"get_company_details_company__report_id__details_get","security":[{"Bearer Token":[]}],"parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","title":"Report Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyDetailsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/company/{report_id}/shareholders":{"get":{"tags":["Company"],"summary":"Get shareholders (owners) of a company","description":"```\nGET /company/{report_id}/shareholders\n```\n\nReturns the shareholders (owners / Gesellschafter) of a company the\nauthenticated user has already generated a report for. Each entry is either a\n`NATURAL_PERSON` (private individual) or a `LEGAL_ENTITY` (company), with its\n`percentage_share`, `nominal_share` and - for legal entities - the German\n`register_info`.\n\nTo avoid spending credits on every call, results are cached for one week.\nA cached (fresh) response is returned for free; if the data is older than one\nweek (or has never been fetched), it is refreshed, which costs credits. The\n`last_updated` field reflects when the data was last refreshed.\n\nReturns `404` if the user has no report for `report_id`, or if the company\ncould not be resolved.\n\n**Credits:** 25 credits per refresh (0 when served from cache).","operationId":"get_report_shareholders_company__report_id__shareholders_get","security":[{"Bearer Token":[]}],"parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","title":"Report Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareholdersResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/company/{report_id}/holdings":{"get":{"tags":["Company"],"summary":"Get holdings of a company","description":"```\nGET /company/{report_id}/holdings\n```\n\nReturns the holdings of a company the authenticated user has already generated\na report for - i.e. the other companies this company owns shares in. Each entry\nis a `LEGAL_ENTITY` with its `percentage_share`, `nominal_share` and German\n`register_info`.\n\nTo avoid spending credits on every call, results are cached for one week.\nA cached (fresh) response is returned for free; if the data is older than one\nweek (or has never been fetched), it is refreshed, which costs credits. The\n`last_updated` field reflects when the data was last refreshed.\n\nReturns `404` if the user has no report for `report_id`, or if the company\ncould not be resolved.\n\n**Credits:** 25 credits per refresh (0 when served from cache).","operationId":"get_report_holdings_company__report_id__holdings_get","security":[{"Bearer Token":[]}],"parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","title":"Report Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HoldingsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/user/api_keys":{"post":{"tags":["API Keys"],"summary":"Create API key","description":"```curl\nPOST /user/api_keys\n```\n\nCreate a new API key. \n\n**Credits**: 0 credits.","operationId":"create_api_key_user_api_keys_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AktivaDetails":{"properties":{"anlagevermoegen":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Anlagevermoegen"},"anlagevermoegen_details":{"$ref":"#/components/schemas/AnlagevermoegenDetails"},"umlaufvermoegen":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Umlaufvermoegen"},"umlaufvermoegen_details":{"$ref":"#/components/schemas/UmlaufvermoegenDetails"},"vorraete":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Vorraete"},"vorraete_details":{"$ref":"#/components/schemas/VorraeteDetails"},"bilanzsumme":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Bilanzsumme"}},"type":"object","title":"AktivaDetails","description":"Per-year Aktiva section (values in EUR)."},"AnlagevermoegenDetails":{"properties":{"sachanlagen":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Sachanlagen"},"immaterielle_vermoegensgegenstaende":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Immaterielle Vermoegensgegenstaende"},"finanzanlagen":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Finanzanlagen"}},"type":"object","title":"AnlagevermoegenDetails","description":"One-level breakdown of `aktiva.anlagevermoegen` (values in EUR)."},"ApiKeyCreateRequest":{"properties":{"uid":{"type":"string","title":"Uid"},"name":{"type":"string","title":"Name"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id"}},"type":"object","required":["uid","name"],"title":"ApiKeyCreateRequest","description":"Request model for creating an API key."},"ApiKeyCreateResponse":{"properties":{"name":{"type":"string","title":"Name"},"api_key":{"type":"string","title":"Api Key"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["name","api_key","created_at"],"title":"ApiKeyCreateResponse","description":"Response model for API key creation (includes plain key - only shown once)."},"BoniReportResponse":{"properties":{"report_id":{"type":"string","title":"Report Id"},"version":{"type":"number","title":"Version","default":1.0},"score":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Score"},"score_details":{"anyOf":[{"$ref":"#/components/schemas/ScoreAssessment"},{"type":"null"}]},"credit_limit":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Credit Limit"},"credit_assessment_result":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Credit Assessment Result"},"assessments":{"anyOf":[{"items":{"$ref":"#/components/schemas/CreditAssessmentDetails"},"type":"array"},{"type":"null"}],"title":"Assessments"},"company":{"anyOf":[{"$ref":"#/components/schemas/CompanyResponse"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["report_id"],"title":"BoniReportResponse","description":"Boni report response model"},"CompanyDetailsResponse":{"properties":{"name":{"type":"string","title":"Name"},"report_id":{"type":"string","title":"Report Id"},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address"},"register_info":{"anyOf":[{"$ref":"#/components/schemas/CompanyRegisterInformation"},{"type":"null"}]},"firmographics":{"anyOf":[{"$ref":"#/components/schemas/CompanyFirmographics"},{"type":"null"}]},"representatives":{"items":{"$ref":"#/components/schemas/Representative"},"type":"array","title":"Representatives"}},"type":"object","required":["name","report_id"],"title":"CompanyDetailsResponse","description":"Company metadata: the report's company envelope plus its representatives."},"CompanyFirmographics":{"properties":{"employees":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Employees"},"employees_class":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Employees Class"},"legal_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Legal Type"},"foundation_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Foundation Year"}},"type":"object","title":"CompanyFirmographics","description":"Descriptive, non-identifying information about a company."},"CompanyRegisterInformation":{"properties":{"register_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Register Type"},"register_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Register Number"},"register_court":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Register Court"}},"type":"object","title":"CompanyRegisterInformation","description":"Identifying information from the German commercial register."},"CompanyResponse":{"properties":{"name":{"type":"string","title":"Name"},"report_id":{"type":"string","title":"Report Id"},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address"},"register_info":{"anyOf":[{"$ref":"#/components/schemas/CompanyRegisterInformation"},{"type":"null"}]},"firmographics":{"anyOf":[{"$ref":"#/components/schemas/CompanyFirmographics"},{"type":"null"}]}},"type":"object","required":["name","report_id"],"title":"CompanyResponse","description":"Company details model"},"CompanySearchResponse":{"properties":{"name":{"type":"string","title":"Name"},"active":{"type":"boolean","title":"Active"},"register_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Register Number"},"register_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Register Type"},"register_court":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Register Court"},"search_result_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search Result Id"},"registered_office":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Registered Office","description":"City of the company, for end-user identification when register details are missing. Populated on `/search/advanced` only; always null on `/search` where companies are identified via register information."}},"type":"object","required":["name","active"],"title":"CompanySearchResponse","description":"Company search response model"},"CreditAssessmentDetails":{"properties":{"type":{"type":"string","title":"Type"},"value":{"type":"integer","title":"Value"},"details":{"anyOf":[{"$ref":"#/components/schemas/ScoreAssessment"},{"items":{"$ref":"#/components/schemas/GeneralEntry"},"type":"array"},{"type":"null"}],"title":"Details"}},"type":"object","required":["type","value"],"title":"CreditAssessmentDetails","description":"Boni report assessment details model"},"EigenkapitalDetails":{"properties":{"gezeichnetes_kapital":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Gezeichnetes Kapital"},"gewinnvortrag":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Gewinnvortrag"},"verlustvortrag":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Verlustvortrag"},"jahresueberschuss":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Jahresueberschuss"},"jahresfehlbetrag":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Jahresfehlbetrag"},"nicht_gedeckter_fehlbetrag":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Nicht Gedeckter Fehlbetrag"}},"type":"object","title":"EigenkapitalDetails","description":"One-level breakdown of `passiva.eigenkapital` (values in EUR)."},"FinancialAnalysisResponse":{"properties":{"report_id":{"type":"string","title":"Report Id"},"register_type":{"type":"string","title":"Register Type"},"register_number":{"type":"string","title":"Register Number"},"register_court":{"type":"string","title":"Register Court"},"financials":{"items":{"$ref":"#/components/schemas/FinancialAnalysisYear"},"type":"array","title":"Financials"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["report_id","register_type","register_number","register_court","financials"],"title":"FinancialAnalysisResponse","description":"Financial data response extended with per-year scores and ratios.\n\nIntentionally does not inherit from `FinancialDataResponse`: the\nstructured `financial_reports` field is scoped to `/financial_data`\nendpoints only and must not appear in the analysis schema or body."},"FinancialAnalysisYear":{"properties":{"jahr":{"type":"integer","title":"Jahr"},"jahresueberschuss":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Jahresueberschuss"},"eigenkapital":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Eigenkapital"},"verbindlichkeiten":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Verbindlichkeiten"},"umlaufvermoegen":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Umlaufvermoegen"},"bilanzsumme":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Bilanzsumme"},"forderungen":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Forderungen"},"liquide_mittel":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Liquide Mittel"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"},"ratios":{"items":{"$ref":"#/components/schemas/FinancialRatio"},"type":"array","title":"Ratios"}},"type":"object","required":["jahr"],"title":"FinancialAnalysisYear","description":"Per-year financial features enriched with the computed score and ratio breakdown."},"FinancialDataResponse":{"properties":{"report_id":{"type":"string","title":"Report Id"},"register_type":{"type":"string","title":"Register Type"},"register_number":{"type":"string","title":"Register Number"},"register_court":{"type":"string","title":"Register Court"},"financials":{"items":{"$ref":"#/components/schemas/FinancialFeaturesYear"},"type":"array","title":"Financials"},"financial_reports":{"anyOf":[{"items":{"$ref":"#/components/schemas/FinancialReport"},"type":"array"},{"type":"null"}],"title":"Financial Reports"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["report_id","register_type","register_number","register_court","financials"],"title":"FinancialDataResponse","description":"Financial data response keyed by reporting year."},"FinancialFeaturesYear":{"properties":{"jahr":{"type":"integer","title":"Jahr"},"jahresueberschuss":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Jahresueberschuss"},"eigenkapital":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Eigenkapital"},"verbindlichkeiten":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Verbindlichkeiten"},"umlaufvermoegen":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Umlaufvermoegen"},"bilanzsumme":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Bilanzsumme"},"forderungen":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Forderungen"},"liquide_mittel":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Liquide Mittel"}},"type":"object","required":["jahr"],"title":"FinancialFeaturesYear","description":"Extracted financial features for a single reporting year (values in EUR)."},"FinancialRatio":{"properties":{"name":{"type":"string","title":"Name"},"value":{"type":"number","title":"Value"},"score":{"type":"integer","title":"Score"},"color":{"type":"integer","title":"Color"}},"type":"object","required":["name","value","score","color"],"title":"FinancialRatio","description":"Single financial ratio contributing to the overall financial score."},"FinancialReport":{"properties":{"year":{"type":"integer","title":"Year"},"currency":{"type":"string","title":"Currency","default":"EUR"},"aktiva":{"$ref":"#/components/schemas/AktivaDetails"},"passiva":{"$ref":"#/components/schemas/PassivaDetails"},"guv":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Guv"}},"type":"object","required":["year"],"title":"FinancialReport","description":"Structured per-year financial report parsed from OpenRegister.\n\nThe flat `FinancialFeaturesYear` array in `FinancialDataResponse.financials`\nis a summary of this structure: corresponding values are identical (see\n`flat_features_from_financial_report`)."},"GeneralEntry":{"properties":{"key":{"type":"string","title":"Key"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label"},"value":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"items":{"type":"string"},"type":"array"},{"items":{"$ref":"#/components/schemas/GeneralEntry"},"type":"array"},{"type":"null"}],"title":"Value"}},"type":"object","required":["key"],"title":"GeneralEntry"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HoldingsResponse":{"properties":{"report_id":{"type":"string","title":"Report Id"},"holdings":{"items":{"$ref":"#/components/schemas/OwnershipEntry"},"type":"array","title":"Holdings"},"last_updated":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Updated"},"available":{"type":"boolean","title":"Available","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"}},"type":"object","required":["report_id"],"title":"HoldingsResponse","description":"Holdings (companies the company owns shares in)."},"JobStatusResponse":{"properties":{"job_id":{"type":"string","title":"Job Id"},"report_id":{"type":"string","title":"Report Id"},"status":{"type":"string","title":"Status"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["job_id","report_id","status"],"title":"JobStatusResponse","description":"Response for GET /jobs/{job_id}/status."},"OwnershipEntry":{"properties":{"name":{"type":"string","title":"Name"},"type":{"type":"string","title":"Type"},"percentage_share":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Percentage Share"},"nominal_share":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Nominal Share"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","default":"EUR"},"register_info":{"anyOf":[{"$ref":"#/components/schemas/CompanyRegisterInformation"},{"type":"null"}]}},"type":"object","required":["name","type"],"title":"OwnershipEntry","description":"A single ownership relation - used for both shareholders (owners of the\ncompany) and holdings (companies the company owns shares in)."},"PassivaDetails":{"properties":{"eigenkapital":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Eigenkapital"},"eigenkapital_details":{"$ref":"#/components/schemas/EigenkapitalDetails"},"rueckstellungen":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rueckstellungen"},"rueckstellungen_details":{"$ref":"#/components/schemas/RueckstellungenDetails"},"verbindlichkeiten":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Verbindlichkeiten"},"verbindlichkeiten_details":{"$ref":"#/components/schemas/VerbindlichkeitenDetails"},"bilanzsumme":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Bilanzsumme"}},"type":"object","title":"PassivaDetails","description":"Per-year Passiva section (values in EUR)."},"ReportCreateRequest":{"properties":{"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name"},"register_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Register Type"},"register_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Register Number"},"register_court":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Register Court"},"search_result_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search Result Id"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id"}},"type":"object","title":"ReportCreateRequest","description":"Request body for creating a company report via the API."},"ReportCreateResponse":{"properties":{"report_id":{"type":"string","title":"Report Id"},"job_id":{"type":"string","title":"Job Id"},"register_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Register Type"},"register_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Register Number"},"register_court":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Register Court"},"status":{"type":"string","title":"Status","default":"queued"}},"type":"object","required":["report_id","job_id"],"title":"ReportCreateResponse","description":"Response after a report generation job has been queued."},"ReportListItemResponse":{"properties":{"name":{"type":"string","title":"Name"},"report_id":{"type":"string","title":"Report Id"},"version":{"type":"number","title":"Version","default":1.0},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["name","report_id"],"title":"ReportListItemResponse","description":"Report list item response model"},"Representative":{"properties":{"name":{"type":"string","title":"Name"},"role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Role"},"type":{"type":"string","title":"Type"},"start_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Start Date"},"end_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"End Date"}},"type":"object","required":["name","type"],"title":"Representative","description":"A person or entity authorized to represent the company (e.g. managing\ndirector / Geschäftsführer, Prokurist)."},"RueckstellungenDetails":{"properties":{"steuerrueckstellungen":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Steuerrueckstellungen"},"sonstige_rueckstellungen":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Sonstige Rueckstellungen"},"pensionsrueckstellungen":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pensionsrueckstellungen"}},"type":"object","title":"RueckstellungenDetails","description":"One-level breakdown of `passiva.rueckstellungen` (values in EUR)."},"ScoreAssessment":{"properties":{"label":{"type":"string","title":"Label"},"color_code":{"type":"integer","title":"Color Code"},"range":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Range"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"}},"type":"object","required":["label","color_code"],"title":"ScoreAssessment","description":"Score assessment model"},"ShareholdersResponse":{"properties":{"report_id":{"type":"string","title":"Report Id"},"shareholders":{"items":{"$ref":"#/components/schemas/OwnershipEntry"},"type":"array","title":"Shareholders"},"last_updated":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Updated"},"available":{"type":"boolean","title":"Available","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"}},"type":"object","required":["report_id"],"title":"ShareholdersResponse","description":"Shareholders (owners) of a company."},"UmlaufvermoegenDetails":{"properties":{"vorraete":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Vorraete"},"forderungen":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Forderungen"},"kassenbestand_kreditinstitut":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Kassenbestand Kreditinstitut"}},"type":"object","title":"UmlaufvermoegenDetails","description":"One-level breakdown of `aktiva.umlaufvermoegen` (values in EUR)."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VerbindlichkeitenDetails":{"properties":{"lieferungen_leistungen":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Lieferungen Leistungen"},"gegenueber_gesellschaftern":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Gegenueber Gesellschaftern"},"gegenueber_kreditinstituten":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Gegenueber Kreditinstituten"},"gegen_verbundene_unternehmen":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Gegen Verbundene Unternehmen"},"sonstige":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Sonstige"},"anleihen":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Anleihen"},"restlaufzeit_bis_1_jahr":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Restlaufzeit Bis 1 Jahr"},"restlaufzeit_mehr_als_1_jahr":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Restlaufzeit Mehr Als 1 Jahr"}},"type":"object","title":"VerbindlichkeitenDetails","description":"One-level breakdown of `passiva.verbindlichkeiten` (values in EUR)."},"VorraeteDetails":{"properties":{"fertige_erzeugnisse_waren":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fertige Erzeugnisse Waren"},"geleistete_anzahlungen":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Geleistete Anzahlungen"},"roh_hilfs_betriebsstoffe":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Roh Hilfs Betriebsstoffe"},"unfertige_erzeugnisse":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Unfertige Erzeugnisse"}},"type":"object","title":"VorraeteDetails","description":"One-level breakdown of `aktiva.vorraete` (values in EUR)."}},"securitySchemes":{"Bearer Token":{"type":"http","description":"Enter your API token (without 'Bearer ' prefix)","scheme":"bearer"}}},"servers":[{"url":"/","description":"Relative to the API host"}]}