> ## Documentation Index > Fetch the complete documentation index at: https://docs.otbstudio.ai/llms.txt > Use this file to discover all available pages before exploring further. # Screen companies > Lists companies by what they do and where they are. Every filter is optional and the filters combine with AND; give at least one of `nace`, `area`, `legal_form` or `situation`. The default list is active companies, which includes companies in bankruptcy or dissolution. The results cost nothing. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/companies/screen openapi: 3.0.3 info: title: OTB Studio API version: 1.0.0 description: >- The Belgian company register over REST: search, profiles, ownership, filed financials and mandates. Every route needs an `otb_live_` token, and every served reply is charged in credits for the datapoints it carries. servers: - url: https://api.otbstudio.ai security: - token: [] tags: - name: Companies description: One company register, read five ways. paths: /v1/companies/screen: get: tags: - Companies summary: Screen companies description: >- Lists companies by what they do and where they are. Every filter is optional and the filters combine with AND; give at least one of `nace`, `area`, `legal_form` or `situation`. The default list is active companies, which includes companies in bankruptcy or dissolution. The results cost nothing. operationId: screenCompanies parameters: - name: nace in: query required: false description: >- A NACE-BEL code or prefix, such as `56.1`. Repeat for more. A prefix of 4 digits or less matches the 2008 and the 2025 version. schema: type: array items: type: string style: form explode: true example: - '56.1' - name: activity in: query required: false description: >- `main` (the default) or `any`, which adds the secondary and ancillary activities. schema: type: string enum: - main - any - name: area in: query required: false description: >- A municipality, sub-municipality, arrondissement, province, region, zip code or area code. Repeat for more. schema: type: array items: type: string style: form explode: true example: - Puurs-Sint-Amands - name: legal_form in: query required: false description: A KBO legal form code, such as `014`. Repeat for more. schema: type: array items: type: string style: form explode: true - name: situation in: query required: false description: >- A juridical situation category: `normal`, `insolvency`, `dissolution`, `merger_or_split` or `ended`. Repeat for more. schema: type: array items: type: string style: form explode: true - name: founded_after in: query required: false description: Founded on or after this date. schema: type: string format: date - name: founded_before in: query required: false description: Founded on or before this date. schema: type: string format: date - name: include_inactive in: query required: false description: '`true` also lists companies that are struck off.' schema: type: boolean default: false - name: sort_by in: query required: false description: >- `name` (the default), `oldest`, `newest`, or a figure from `GET /v1/figures`, such as `employees`, `analysis.solvency` or `growth3y.turnover`. Companies with no value for the figure come last. schema: type: string default: name - name: sort_order in: query required: false description: 'For a figure: `desc` (the default) or `asc`.' schema: type: string enum: - desc - asc default: desc - name: min in: query required: false description: >- Keep the companies whose newest filing has the figure at least this value, such as `min[equity]=1000000`. A company with no value does not pass. A ratio is a fraction: `min[analysis.solvency]=0.5` is 50%. style: deepObject explode: true schema: type: object additionalProperties: type: number - name: max in: query required: false description: >- Keep the companies whose newest filing has the figure at most this value, such as `max[analysis.customerCreditDays]=30`. style: deepObject explode: true schema: type: object additionalProperties: type: number - name: include in: query required: false description: >- A figure each result also shows, such as `turnover`. Repeat for more. Each value costs a credit, and a result of a screen that uses a figure 2 more. style: form explode: true schema: type: array items: type: string - name: limit in: query required: false description: >- How many companies to return, 1 to 50. A missing, zero or negative value gives 20, a larger one 50. schema: type: integer default: 20 - name: offset in: query required: false description: Where the page starts. Take it from `nextOffset`. schema: type: integer default: 0 - name: also_requested in: query required: false description: >- A part of the request no filter covers, such as `has a terrace`. It comes back in `unsupported`. Repeat for more. schema: type: array items: type: string style: form explode: true responses: '200': description: >- The companies that matched, and what the screen did with the request. headers: X-Credits-Cost: $ref: '#/components/headers/X-Credits-Cost' X-Credits-Remaining: $ref: '#/components/headers/X-Credits-Remaining' content: application/json: schema: $ref: '#/components/schemas/Screen' example: matched: 68 returned: 2 hasMore: true nextOffset: 2 sortedBy: name bySituation: - category: normal companies: 66 - category: insolvency companies: 2 resolvedArea: zips: - '2870' - '2890' items: - input: Puurs-Sint-Amands level: municipality area: code: '12041' nl: Puurs-Sint-Amands fr: Puurs-Sint-Amands zips: - '2870' - '2890' includes: - Breendonk - Liezele - Lippelo - Oppuurs - Puurs - Ruisbroek - Sint-Amands nace: - input: '56.1' code: '56.1' versions: - NACE-BEL 2025 - NACE-BEL 2008 nl: Restaurants en mobiele eetgelegenheden fr: Restaurants et services de restauration mobile en: Restaurants and mobile food service activities unsupported: - aspect: has a terrace reason: >- the screen cannot filter on this. Check it per company with get_company, or say that it was not applied results: - enterpriseNumber: BE0789990368 name: Den Amandus zipCode: '2890' municipality: Puurs-Sint-Amands founded: '2022-03-01' mainActivity: code: '56.111' version: NACE-BEL 2025 nl: Activiteiten van eetgelegenheden met volledige bediening situation: code: '000' nl: Normale toestand fr: Situation normale en: Normal situation category: normal - enterpriseNumber: BE0863104614 name: PUURS LOF zipCode: '2870' municipality: Puurs-Sint-Amands founded: '2004-01-30' mainActivity: code: '56.111' version: NACE-BEL 2025 nl: Activiteiten van eetgelegenheden met volledige bediening '400': description: No `nace`, `area`, `legal_form` or `situation` filter. content: application/json: schema: $ref: '#/components/schemas/FilterRequired' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/Internal' '503': $ref: '#/components/responses/Busy' components: headers: X-Credits-Cost: description: What this reply cost, in credits. schema: type: integer X-Credits-Remaining: description: The balance after this reply. schema: type: integer Retry-After: description: Seconds to wait before trying again. schema: type: integer schemas: Screen: type: object description: The companies that matched, and what the screen did with the request. additionalProperties: false required: - matched - returned - hasMore - sortedBy - bySituation - unsupported - results properties: matched: type: integer description: Every company that passed the filters, not only this page. returned: type: integer hasMore: type: boolean nextOffset: type: integer description: The offset of the next page, when there is one. sortedBy: type: string description: >- `name`, `oldest`, `newest`, or a figure and its order, such as `employees desc`. bounds: type: object additionalProperties: type: object additionalProperties: false properties: min: type: number max: type: number description: >- The min and max the screen applied, by figure, such as `{"employees": {"min": 10}}`. Each one costs 5 credits: `matched` answers it. bySituation: type: array items: $ref: '#/components/schemas/SituationCount' description: >- The matched companies per juridical situation category, so a list that includes bankruptcies says so. resolvedArea: $ref: '#/components/schemas/ResolvedArea' nace: type: array items: $ref: '#/components/schemas/NaceMatch' unsupported: type: array items: $ref: '#/components/schemas/Unsupported' description: Every part of the request the screen did not apply, with the reason. results: type: array items: $ref: '#/components/schemas/ScreenResult' FilterRequired: type: object additionalProperties: false required: - code properties: code: type: string enum: - filter_required SituationCount: type: object description: How many matched companies are in one situation category. additionalProperties: false required: - category - companies properties: category: type: string companies: type: integer ResolvedArea: type: object description: Every area item resolved, and the zip codes of all of them. additionalProperties: false required: - zips - items properties: zips: type: array items: type: string items: type: array items: $ref: '#/components/schemas/AreaMatch' NaceMatch: type: object description: What one NACE input matched. additionalProperties: false required: - input - code - versions properties: input: type: string code: type: string versions: type: array items: type: string description: The NACE-BEL versions that have codes under it. nl: type: string description: >- KBO's description of the code itself, in Dutch. Absent for a prefix that is no KBO code. fr: type: string en: type: string note: type: string Unsupported: type: object description: One part of the request the screen did not apply. additionalProperties: false required: - aspect - reason properties: aspect: type: string reason: type: string ScreenResult: type: object description: >- One company. Thin on purpose: open it with `GET /v1/companies/{id}` for the rest. additionalProperties: false required: - enterpriseNumber - name properties: enterpriseNumber: type: string name: type: string zipCode: type: string municipality: type: string description: Statbel's name of the municipality, in Dutch. founded: type: string format: date mainActivity: description: >- The main code that matched the `nace` filter, or the newest main code. allOf: - $ref: '#/components/schemas/ScreenActivity' juridicalForm: $ref: '#/components/schemas/KBOCode' situation: $ref: '#/components/schemas/KBOCode' figures: type: object additionalProperties: type: number description: >- The newest values of the figures the screen filtered or sorted on, and of those in `include`, by the name in `GET /v1/figures`. A growth is a fraction: 0.2 is 20%. A figure with no value is left out. Each value costs a credit, and a result of a screen that uses a figure 2 more. figuresClosingDate: type: string format: date description: The closing date of the filing the figures are from. Unauthorized: type: object additionalProperties: false required: - code properties: code: type: string enum: - missing_token - invalid_token PaymentRequired: type: object additionalProperties: false required: - code properties: code: type: string enum: - insufficient_credits RateLimited: type: object additionalProperties: false required: - code properties: code: type: string enum: - rate_limited Internal: type: object additionalProperties: false required: - code properties: code: type: string enum: - internal Busy: type: object additionalProperties: false required: - code properties: code: type: string enum: - busy AreaMatch: type: object description: What one area item resolved to. additionalProperties: false required: - input - zips properties: input: type: string level: type: string description: >- `municipality`, `sub_municipality`, `arrondissement`, `province`, `region` or `zip`. Absent when the item resolved to no area. area: $ref: '#/components/schemas/Area' zips: type: array items: type: string includes: type: array items: type: string description: The bpost place names in `zips`. alternatives: type: array items: $ref: '#/components/schemas/AreaRef' description: >- The other areas with the same name. Send one's `code`, or a place's `zips`, to select it. reason: type: string description: Why `zips` is empty, and what to send instead. ScreenActivity: type: object description: One NACE code with KBO's description. additionalProperties: false required: - code - version properties: code: type: string version: type: string nl: type: string fr: type: string en: type: string KBOCode: type: object description: >- A KBO reference code with the register's own description. KBO's code list has Dutch and French; `en` is OpenTheBox's English. additionalProperties: false required: - code properties: code: type: string description: The KBO code, the same as in the matching `...Code` field. nl: type: string description: >- KBO's description in Dutch. Absent when KBO's code list has no row for the code. fr: type: string description: KBO's description in French. en: type: string description: >- An English description, from OpenTheBox, not KBO: KBO publishes no English. Quote `nl` or `fr` when the official wording matters. text: type: string description: >- The provider's own words for the legal form of a company registered abroad, such as `SARL`. It is not a KBO code and has no translation; then `nl`, `fr` and `en` are absent. category: type: string description: >- Only on `juridicalSituation`: `normal`, `dissolution`, `insolvency` (a procedure running now), `merger_or_split` or `ended`. The grouping is OpenTheBox's, not KBO's. Area: type: object description: >- A Belgian administrative area, from Statbel. Statbel publishes no English. additionalProperties: false required: - code properties: code: type: string description: Statbel's NIS code for the area. nl: type: string description: Statbel's name in Dutch, without "Provincie" or "Arrondissement". fr: type: string description: Statbel's name in French. AreaRef: type: object description: One candidate area. A sub-municipality also carries its zip codes. additionalProperties: false required: - level - code properties: level: type: string code: type: string nl: type: string fr: type: string zips: type: array items: type: string description: >- Only on a sub-municipality: its zip codes, which select it. Its code is its municipality's. responses: Unauthorized: description: >- No token, or a token that is not valid. `missing_token` when there is no `Authorization: Bearer` header, `invalid_token` when the token is unknown, revoked or of the wrong kind. content: application/json: schema: $ref: '#/components/schemas/Unauthorized' PaymentRequired: description: >- The organisation has no plan, its balance is empty, or the balance does not cover this reply. When the reply was too expensive, the headers say what it would have cost and what is left. headers: X-Credits-Cost: $ref: '#/components/headers/X-Credits-Cost' X-Credits-Remaining: $ref: '#/components/headers/X-Credits-Remaining' content: application/json: schema: $ref: '#/components/schemas/PaymentRequired' RateLimited: description: >- The organisation is over its rate (10 calls a second, bursts of 20). Retry after `Retry-After`. headers: Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/RateLimited' Internal: description: Something failed on our side. content: application/json: schema: $ref: '#/components/schemas/Internal' Busy: description: The data could not be read within 15 seconds. Retry after `Retry-After`. headers: Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/Busy' securitySchemes: token: type: http scheme: bearer description: An `otb_live_` token, minted in the OTB Studio dashboard. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.