> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nesu.pt/llms.txt
> Use this file to discover all available pages before exploring further.

# Search companies

> Find up to 20 Portuguese company directory entries by company name or NIF.

## Prerequisites

You need an [active API key](../authentication), available rate-limit capacity, and one credit from your included allowance or purchased balance.

Search your company directory by name or NIF. Each admitted request consumes one credit.

## Query parameter

<ParamField query="q" type="string" required placeholder="Continente">
  Company name or NIF. You must supply a non-empty value after trimming leading and trailing whitespace.
</ParamField>

### Name matching

Your name query is normalized to lowercase, with accents removed, punctuation replaced by spaces, repeated whitespace collapsed, and common trailing legal suffixes such as `Lda` or `SA` removed. You receive companies whose normalized legal name begins with your normalized query, with exact matches first and remaining matches ordered by legal name.

You receive at most 20 results. There is no pagination or total count. Use a more specific prefix to narrow a broad search. You search legal names, not addresses or activity codes.

### NIF matching

If your query contains nine digits, optionally separated by spaces, hyphens, or periods, it is treated as a NIF and matched exactly. You do not receive NIF checksum validation on this endpoint; use [Get a company](/api-reference/get-company) for a validated company lookup.

A NIF with no directory entry returns an empty array. A missing search entry does not prevent you from trying a direct company lookup.

## Response

You receive `200 OK` with this envelope:

<ResponseField name="data" type="object[]" required>
  Zero to 20 company directory matches. No matches are represented by `[]`.
</ResponseField>

<ResponseField name="error" type="null" required>
  Always `null` on success. Failures use a separate problem response.
</ResponseField>

Each object in `data` has these fields:

| Field | Type | Meaning |
| - | - | - |
| `nif` | string | Your match's nine-digit NIF. Unlike the company detail response, this is a string. |
| `legal_name` | string | The company's legal name. |
| `status` | string | Currently an empty string in search results. |
| `locality` | string | Currently an empty string in search results. |
| `primary_cae` | string | Currently an empty string in search results. |

Use the NIF with [Get a company](/api-reference/get-company) when you need address, status, activity, or legal structure details.

## Errors

You receive `400 validation` if `q` is missing or whitespace-only, or `500 search-failed` if the directory search fails. Authentication and quota failures are described in [Errors](../errors).

<RequestExample>
  ```bash theme={null}
  curl --fail-with-body --silent --show-error --get \
    --header "Authorization: Bearer $NESU_API_KEY" \
    --data-urlencode 'q=Exemplo' \
    'https://api.nesu.pt/api/v1/companies'
  ```
</RequestExample>

<ResponseExample>
  Illustrative fixture response; this is not a live company record.

  ```json theme={null}
  {
    "data": [
      {
        "nif": "509442013",
        "legal_name": "Exemplo, Lda",
        "status": "",
        "locality": "",
        "primary_cae": ""
      }
    ],
    "error": null
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.