Skip to content
Endpoint
GET/api/nif/{nif}

Look up taxpayer details from a normalized NIF value.

The NIF route accepts an Angolan tax identifier in the path, validates it, requests data from the public tax portal, and returns a parsed JSON response.

The path parameter is trimmed, uppercased, and limited to letters and digits before the lookup is attempted.

Input type

Path parameter

Upstream source

Angolan tax portal

Primary failure

Portal availability

Success payload

JSON200 response
{  "NIF": "004813023LA040",  "Name": "EMPRESA EXEMPLO, LDA",  "Type": "Pessoa Colectiva",  "Status": "Activo",  "Defaulting": "Não",  "VATRegime": "Regime Geral",  "isTaxResident": true}

Returned fields

FieldMeaning
NIFNormalized identifier used for the lookup and echoed in the response.
NameRegistered taxpayer name parsed from the portal response.
TypeTaxpayer classification returned by the source portal.
StatusCurrent taxpayer status string.
DefaultingWhether the taxpayer is flagged as in default.
VATRegimeVAT regime text returned by the portal.
isTaxResidentBoolean derived from the resident or non-resident marker in the result section.

What can go wrong

  • An empty or invalid path parameter returns a 400 INVALID_NIF error before any upstream call is made.
  • If the tax portal reports no result, the route returns a 404 NIF_NOT_FOUND response.
  • Malformed or structurally changed HTML from the portal returns a 502 UNPARSEABLE_RESPONSE error.
  • Network and TLS issues are surfaced as upstream availability errors, with an internal fallback for certificate edge cases.
Because the upstream source is HTML, schema changes on the portal are the biggest long-term maintenance risk. Keep a contract test around the parser.

Integration tips

  • Normalize spaces and casing in user-entered identifiers before you build the route path.
  • Treat this endpoint as live verification rather than a permanent source of record; portal data can change over time.
  • Store the raw lookup result alongside your own audit context when the output informs compliance actions.
  • Show clear user messaging when the portal is temporarily unavailable instead of turning upstream failures into generic validation errors.