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'
{
"data": [
{
"nif": "509442013",
"legal_name": "Exemplo, Lda",
"status": "",
"locality": "",
"primary_cae": ""
}
],
"error": null
}
API reference
Search companies
Find up to 20 Portuguese company directory entries by company name or NIF.
GET
/
api
/
v1
/
companies
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'
{
"data": [
{
"nif": "509442013",
"legal_name": "Exemplo, Lda",
"status": "",
"locality": "",
"primary_cae": ""
}
],
"error": null
}
Prerequisites
You need an active API key, 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
string
required
Company name or NIF. You must supply a non-empty value after trimming leading and trailing whitespace.
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 asLda 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 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 receive200 OK with this envelope:
object[]
required
Zero to 20 company directory matches. No matches are represented by
[].null
required
Always
null on success. Failures use a separate problem response.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. |
Errors
You receive400 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.
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'
Illustrative fixture response; this is not a live company record.{
"data": [
{
"nif": "509442013",
"legal_name": "Exemplo, Lda",
"status": "",
"locality": "",
"primary_cae": ""
}
],
"error": null
}