Contribuinte APIcontribuinte.pt ↗
Search Portuguese companies by name or NIF and retrieve registration status, address, and CAE economic activity codes via the contribuinte.pt API.
What is the Contribuinte API?
The contribuinte.pt API gives developers access to Portuguese company registry data through 2 endpoints. Use search_companies to run full-text searches by company name or NIF and get back matching records with registered names and NIFs, or call get_company with a 9-digit NIF to retrieve a single company's registration status, full address, last-updated date, and CAE economic activity codes.
curl -X GET 'https://api.parse.bot/scraper/17ba97c2-fecb-4eae-9f90-9cfbf1d67c6c/search_companies?query=Sonae' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace contribuinte-pt-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: contribuinte_pt_api SDK — bounded, re-runnable; every call capped."""
from parse_apis.contribuinte_pt_api import Contribuinte, CompanyNotFound
client = Contribuinte()
# Search for companies by name; limit= caps TOTAL items fetched.
for company in client.company_summaries.search(query="Sonae", limit=3):
print(company.nif, company.name)
# Drill-down: take ONE summary, then get full details.
hit = client.company_summaries.search(query="Sonae", limit=1).first()
if hit:
full = hit.details()
print(full.name, full.status, full.address)
# Typed errors: wrap the fallible call, catch the specific class.
try:
detail = client.companies.get(nif="999999999")
print(detail.name)
except CompanyNotFound as e:
print(f"not found: NIF {e.nif}")
print("exercised: company_summaries.search / CompanySummary.details / companies.get")
Full-text search over Portuguese companies by name or NIF. Returns all matching companies with their NIF and registered name. Results are returned in a single page.
| Param | Type | Description |
|---|---|---|
| queryrequired | string | Company name or NIF to search for. |
{
"type": "object",
"fields": {
"query": "the search term used",
"total": "number of matching companies",
"companies": "array of company summaries with nif, name, and url"
},
"sample": {
"data": {
"query": "Sonae",
"total": 19,
"companies": [
{
"nif": "505134730",
"url": "https://contribuinte.pt/nif/505134730/sonae-industria-consultadoria-e-gestao-s-a",
"name": "Sonae Indústria - Consultadoria E Gestão, S. A."
},
{
"nif": "500273170",
"url": "https://contribuinte.pt/nif/500273170/sonae-sgps-s-a",
"name": "Sonae - Sgps, S.a."
}
]
},
"status": "success"
}
}About the Contribuinte API
Endpoints and Data Coverage
The search_companies endpoint accepts a query string — either a company name fragment or a full NIF — and returns a total count alongside a companies array. Each entry in that array contains the company's nif, registered name, and a url. Results come back in a single page, so there is no cursor or pagination parameter.
Company Detail Fields
The get_company endpoint takes a single required parameter: a 9-digit nif (Portugal's NIF/NIPC tax identification number, e.g. 505134730). The response includes the company's name, status (for example, Activa), registered address, and an updated field showing when the record was last refreshed in DD/MM/YYYY format. CAE economic activity codes are returned when present in the registry record.
Scope and Freshness
Coverage is limited to Portuguese legal entities registered with a NIF/NIPC. The updated field in each company record reflects the date that specific entry was last modified in the underlying registry, not the timestamp of your API call. Because results are returned in a single page from search_companies, very broad name queries may return large result sets; using a more specific name or a full NIF keeps responses manageable.
The Contribuinte API is a managed, monitored endpoint for contribuinte.pt — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when contribuinte.pt changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official contribuinte.pt API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Verify a Portuguese supplier's registration status before onboarding by checking the
statusfield viaget_company. - Enrich a CRM with registered addresses for Portuguese business contacts using the
addressfield fromget_company. - Classify Portuguese partners or vendors by economic sector using returned CAE activity codes.
- Validate a NIF submitted in a checkout or KYC form by confirming it resolves to a named, active company.
- Build a company search autocomplete backed by
search_companiesreturningnifandnamematches. - Monitor registry changes by periodically checking the
updateddate for a set of tracked NIFs. - Cross-reference invoice NIFs against official registry data to detect mismatches in company names.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does contribuinte.pt provide an official developer API?+
What does `search_companies` return and can results be paginated?+
query echo, a total count, and a companies array where each item includes nif, name, and url. All matching results are returned in one response — there are no pagination parameters such as page or offset.Are CAE economic activity codes always present in `get_company` responses?+
Does the API return historical company records or past addresses?+
name, status, address, updated date, and CAE codes. Historical records, previous addresses, or audit trails of status changes are not exposed. You can fork this API on Parse and revise it to add an endpoint targeting historical registry data if that becomes available.