> ## 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.

# Quickstart

> Make your first authenticated request and retrieve Portuguese company information by name or NIF.

Use the Nesu API to search Portuguese companies, retrieve company details by tax identification number (NIF), and monitor your account usage.

Your API base URL is `https://api.nesu.pt/api/v1`. Successful requests return JSON; errors return [problem details](errors).

## Prerequisites

* A Nesu account and an active API key. In your Nesu dashboard, open **Chaves de API**, create a key, and save the full secret when it appears. See [Authentication](authentication).
* A terminal with Bash and cURL installed.

## 1. Check your connection

Set your API key in your terminal, then request your usage. Replace the placeholder with your full key, including its `nesu_` prefix.

```bash theme={null}
export NESU_API_KEY='YOUR_NESU_API_KEY'

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer $NESU_API_KEY" \
  'https://api.nesu.pt/api/v1/usage'
```

A successful request returns `success: true` and a `data` object containing your plan, credit balance, quotas, and rate-limit capacity. This request uses rate-limit capacity but does not consume a credit.

## 2. Search for a company

Pass a company name in `q`. Use `--data-urlencode` to handle spaces and accented characters.

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

You receive up to 20 matches in `data`. An empty array means your query has no directory matches. You can also search using a NIF. See [Search companies](api-reference/search-companies).

## 3. Retrieve company details

Use a NIF from your search results as the path parameter. The example below uses `509442013`; replace it with the company you need.

```bash theme={null}
curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer $NESU_API_KEY" \
  'https://api.nesu.pt/api/v1/companies/509442013'
```

A successful lookup returns `result: "success"` and a `data` object with the company's name, address, activity, legal structure, and available debt brackets. See [Get a company](api-reference/get-company).

<Note>
  Each admitted search or company lookup consumes one credit, even if it later returns a validation error, no matches, or a lookup error. Check your input before sending requests. See [Limits and credits](limits).
</Note>

## Integrate into your application

* Send requests from your server so your API key stays private.
* Read each endpoint's response contract: search, lookup, and usage use different success envelopes.
* Inspect the HTTP status and problem `type` when a request fails. For `429`, honor `Retry-After`; distinguish a temporary rate limit from an exhausted credit quota.
* When processing multiple companies, pace requests using the rate-limit headers and monitor [account usage](api-reference/get-usage).

The response examples in these docs use illustrative fixture data. Your company records, quotas, balances, and dates will differ.


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