Skip to main content
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.

​
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.
  • 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.
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.
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.

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

​
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.
The response examples in these docs use illustrative fixture data. Your company records, quotas, balances, and dates will differ.