> ## Documentation Index > Fetch the complete documentation index at: https://developers.portao3.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Search companies > Searches Brazil's public company registry, one establishment (headquarters or branch) per result, in CNPJ order. The data is Brazil's public company registry, from Receita Federal's monthly open data; a record that was looked up by CNPJ may have been refreshed in real time since. Each result's `refDate` is the month of the registry data it reflects. The search covers the stored records only — it never looks a company up. The data is the same for every organization — nothing in it belongs to yours. Every filter is optional and they combine. `legalName` matches the beginning of the legal name only (at least 3 characters), never the middle. `mainActivity` is a CNAE code, matched exactly when it has 7 digits and as a prefix when shorter. `companyDocument` lists every establishment of one company. Page with `limit` (up to 100) and `next`: pass the `next` cursor of one page to get the following one; the last page answers `next` as `null`. A result carries the registry's codes (`statusReason`, `legalNature`, …); `GET /realms/{realmId}/organizations/{organizationId}/companies/{document}` adds their text. ## OpenAPI ````yaml /api-reference/registry.openapi.json get /realms/{realmId}/organizations/{organizationId}/companies openapi: 3.0.3 info: title: Registry version: 1.0.0 description: >- Portão 3 registry API. Every endpoint requires a bearer token in the Authorization header (Authorization: Bearer ) unless its page states otherwise; see the Authentication guide. That requirement is not repeated per endpoint. Generated by tools/openapi from code (routes + security) and the hand-written spec (request/response bodies). Confidence tiers: generated:typed=37 copied:manual=0 unknown=0. servers: - url: https://api.registry.v2.portao3.com.br/ description: production - url: https://api.registry.dev.3pers.com.br/ description: development security: [] tags: - name: Customers - name: Companies - name: People - name: Products - name: Suppliers paths: /realms/{realmId}/organizations/{organizationId}/companies: get: tags: - Companies summary: Search companies description: >- Searches Brazil's public company registry, one establishment (headquarters or branch) per result, in CNPJ order. operationId: getRealmsByRealmIdOrganizationsByOrganizationIdCompanies parameters: - name: realmId in: path required: true description: |- ID of your realm. Format: `UUID` schema: type: string format: uuid example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b - name: organizationId in: path required: true description: |- ID of the organization making the request. Format: `UUID` schema: type: string format: uuid example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 - name: mainActivity in: query required: false description: >- Main economic activity (CNAE code). A 7-digit code matches that activity exactly; a shorter code, from 2 to 6 digits, matches every activity that starts with it (`62` is the whole division). schema: type: string pattern: ^\d{2,7}$ example: '4712100' - name: status in: query required: false description: |- Only establishments in one of these registration statuses. --- Example (comma-separated list): `?status=ACTIVE,SUSPENDED` schema: type: array items: type: string enum: - ANNULLED - ACTIVE - ACTIVE_IRREGULAR - SUSPENDED - INAPT - CLOSED style: form explode: false - name: legalName in: query required: false description: >- Only companies whose legal name starts with this text (case-insensitive, at least 3 characters). It matches the beginning of the name, never the middle. schema: type: string minLength: 3 maxLength: 120 example: exemplo comercio - name: legalNature in: query required: false description: >- Only companies of one of these legal natures (4-digit codes of Receita Federal's table). --- Example (comma-separated list): `?legalNature=2046,2062` schema: maxItems: 20 type: array items: type: string pattern: ^\d{4}$ style: form explode: false - name: companyDocument in: query required: false description: >- The first 8 characters of a CNPJ, which identify one company: lists the headquarters and every branch of it. schema: type: string pattern: ^[A-Za-z0-9]{8}$ example: '11222333' - name: next in: query required: false description: >- Cursor returned as `next` by the previous page. Omit it to get the first page. schema: type: string maxLength: 64 example: MTEyMjIzMzMwMDAxODE - name: limit in: query required: false description: Page size, from 1 to 100. Defaults to 15. schema: type: integer minimum: 1 maximum: 100 example: 25 responses: '200': description: Successful response content: application/json: schema: type: object properties: items: type: array items: type: object properties: _id: type: string description: Same value as `document`. example: '11222333000181' document: type: string description: >- CNPJ of the establishment: 14 characters (the first 12 digits or letters, the last 2 digits), without formatting. example: '11222333000181' companyDocument: type: string description: >- The first 8 characters of the CNPJ, which identify the company: every establishment of one company shares them. example: '11222333' branchNumber: type: string description: >- The 4 characters after the company's 8: `0001` is the headquarters. example: '0001' branchType: type: string enum: - HEADQUARTERS - BRANCH description: '`HEADQUARTERS` or `BRANCH`.' example: HEADQUARTERS tradingName: type: string description: Trade name of the establishment. example: EXEMPLO MERCADO status: type: string enum: - ANNULLED - ACTIVE - ACTIVE_IRREGULAR - SUSPENDED - INAPT - CLOSED description: >- Registration status: `ACTIVE`, `ACTIVE_IRREGULAR` (operating, with a pending irregularity at Receita Federal), `SUSPENDED`, `INAPT` (ineligible), `CLOSED` (deregistered) or `ANNULLED`. example: ACTIVE statusDate: type: string format: date-time description: When the registration status last changed. example: '2015-03-12T00:00:00.000Z' statusReason: type: string description: >- Code of the reason for the registration status, from Receita Federal's table. The company read adds its text as `statusReasonDescription`. example: '00' specialStatus: type: string description: >- Special situation of the company, as published by Receita Federal. example: RECUPERACAO JUDICIAL specialStatusDate: type: string format: date-time description: When the special situation began. example: '2022-06-01T00:00:00.000Z' foundingDate: type: string format: date-time description: When the establishment started its activities. example: '2015-03-12T00:00:00.000Z' mainActivity: type: string description: 'Main economic activity: a 7-digit CNAE code.' example: '4712100' secondaryActivities: type: array items: type: string example: '4721102' description: |- Secondary economic activities: 7-digit CNAE codes. --- Example: `["4721102","4722901"]` email: type: string description: E-mail address of the establishment, in lower case. example: contato@exemplo.com.br phoneNumber: type: string description: >- Main phone number, in international format (`+` followed by digits). Absent when the published number can't be converted to it. example: '+551133334444' secondaryPhoneNumber: type: string description: Secondary phone number, in international format. example: '+551155556666' fax: type: string description: Fax number, in international format. example: '+551177778888' address: type: object properties: street: type: string description: >- Street, with its type (such as `RUA` or `AVENIDA`). example: AVENIDA PAULISTA number: type: string description: Street number. example: '1578' complement: type: string description: Extra address detail. example: ANDAR 3 neighborhood: type: string description: Neighborhood. example: BELA VISTA city: type: string description: City name. example: SAO PAULO cityCode: type: string description: >- Code of the city in Receita Federal's municipality table. example: '7107' state: type: string description: Two-letter code of the Brazilian state. example: SP postalCode: type: string description: Postal code (CEP), 8 digits. example: '01310200' description: Address of the establishment. foreignCity: type: string description: City of an establishment based abroad. example: LISBOA country: type: string description: >- Country of an establishment based abroad, as a two-letter ISO 3166-1 code. Absent when the published country has no single ISO equivalent; `countryCode` keeps the published value. example: PT countryCode: type: string description: >- Country code of an establishment based abroad, as published by Receita Federal (a 3-digit code of its own country table). example: '607' legalName: type: string description: Legal name (razão social) of the company. example: EXEMPLO COMERCIO DE ALIMENTOS LTDA legalNature: type: string description: >- Legal nature of the company: a 4-digit code from Receita Federal's table. The company read adds its text as `legalNatureDescription`. example: '2062' size: type: string enum: - NOT_INFORMED - MICRO - SMALL - OTHER description: >- Size of the company: `MICRO`, `SMALL`, `OTHER` (any larger) or `NOT_INFORMED`. example: SMALL capital: type: number description: Share capital, in cents of BRL. example: 50000000 responsibleQualification: type: string description: >- Qualification code of the person responsible for the company, from Receita Federal's qualification table. example: '49' federativeEntity: type: string description: >- Federative entity responsible for the company. Only public bodies have one. example: UNIAO shareholders: type: array items: type: object properties: documentType: type: string enum: - CNPJ - CPF - FOREIGN description: >- Kind of partner: `CNPJ` for a company, `CPF` for a person or `FOREIGN` for a foreign partner. example: CPF name: type: string description: Name of the partner. example: MARIA DA SILVA document: type: string description: >- Document of the partner: a CNPJ, or a CPF — in full when the record was refreshed in real time, otherwise partly masked as published in the monthly data (`***123456**`). Absent for a foreign partner. example: '***123456**' qualification: type: string description: >- Qualification code of the partner, from Receita Federal's qualification table (`49` is partner-administrator, `22` partner). example: '49' joinedAt: type: string format: date-time description: When the partner joined the company. example: '2015-03-12T00:00:00.000Z' country: type: string description: >- Country of a foreign partner, as a two-letter ISO 3166-1 code. Absent when the published country has no single ISO equivalent; `countryCode` keeps the published value. example: US countryCode: type: string description: >- Country code of a foreign partner, as published by Receita Federal (a 3-digit code of its own country table). example: '249' ageRange: type: string description: >- Age range of a person partner, as the code published by Receita Federal: `0` not applicable, `1` up to 12 years, `2` 13 to 20, `3` 21 to 30, `4` 31 to 40, `5` 41 to 50, `6` 51 to 60, `7` 61 to 70, `8` 71 to 80, `9` over 80. example: '5' legalRepresentative: type: object properties: document: type: string description: >- CPF of the representative: in full when the record was refreshed in real time, otherwise partly masked as published in the monthly data (`***123456**`). example: '***123456**' name: type: string description: Name of the representative. example: JOAO PEREIRA DA SILVA qualification: type: string description: >- Qualification code of the representative, from Receita Federal's qualification table. example: '17' description: >- The partner's legal representative, when it has one. required: - documentType description: A partner or shareholder of the company. description: >- Partners and shareholders of the company, sorted by name. simples: type: object properties: optIn: type: boolean description: Whether the company is currently opted in. example: true optInDate: type: string format: date-time description: When the company opted in. example: '2016-01-01T00:00:00.000Z' optOutDate: type: string format: date-time description: When the company opted out, if it did. example: '2020-12-31T00:00:00.000Z' required: - optIn description: >- Whether the company opted into the Simples Nacional tax regime. mei: type: object properties: optIn: type: boolean description: Whether the company is currently opted in. example: true optInDate: type: string format: date-time description: When the company opted in. example: '2016-01-01T00:00:00.000Z' optOutDate: type: string format: date-time description: When the company opted out, if it did. example: '2020-12-31T00:00:00.000Z' required: - optIn description: >- Whether the company is registered as an individual microentrepreneur (MEI). refDate: type: string description: >- Month of the registry data this record reflects, as `YYYY-MM`: the monthly release that last updated it, or the month it was refreshed in real time. example: 2026-08 createdAt: type: string format: date-time description: When this record was first added to the registry. example: '2026-07-14T09:00:00.000Z' updatedAt: type: string format: date-time description: When this record last changed. example: '2026-08-18T09:00:00.000Z' required: - _id - document - companyDocument - branchNumber - branchType - status - refDate description: >- One establishment (headquarters or branch) of a company, as listed by the company search. description: The establishments of this page, in CNPJ order. next: type: string nullable: true description: >- Cursor for the next page: pass it as `next` to get it. `null` on the last page. example: MTEyMjIzMzMwMDAxODE required: - items - next description: A page of establishments. '422': description: >- `BAD_REQUEST` — A path or query parameter is invalid, such as an unknown `status`, a `legalName` shorter than 3 characters or a `limit` above 100; `fields` lists each one. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - BAD_REQUEST description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - REGISTRY description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. fields: type: array description: >- One entry per invalid request field (validation errors only). items: type: object properties: field: type: string description: >- Path of the invalid field, e.g. `label` or `values[0].value`. example: label message: type: string description: Why the field was rejected. example: label is required code: type: string description: >- `_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`. example: LABEL_REQUIRED values: type: array items: type: string description: >- The accepted values, when the field is an enumeration. required: - field - message - code required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: BAD_REQUEST origin: REGISTRY message: >- Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields. fields: - field: legalName message: 'Too big: expected string to have <=120 characters' code: LEGALNAME_MAX ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.