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

# Get a company

> Retrieve a Portuguese company's address, activity, legal structure, and available debt brackets by NIF.

## Prerequisites

You need an [active API key](../authentication), a NIF with a valid checksum, available rate-limit capacity, and one credit from your included allowance or purchased balance.

Retrieve company details using a Portuguese tax identification number. Each admitted request consumes one credit, including a cached lookup.

## Path parameter

<ParamField path="nif" type="string" required placeholder="509442013">
  A nine-digit Portuguese tax identification number with a valid checksum. Spaces, hyphens, and periods are accepted as separators; URL-encode spaces if you include them. Prefer an unformatted nine-digit value.
</ParamField>

## Response

You receive `200 OK` with this envelope:

<ResponseField name="result" type="string" required>
  Always `"success"` on success.
</ResponseField>

<ResponseField name="data" type="object" required>
  Your company's details, with the fields below.
</ResponseField>

### Company fields

| Field | Type | Meaning |
| - | - | - |
| `nif` | integer | The company's NIF. Unlike search results, this is a JSON number. |
| `title` | string | The company's legal name. |
| `address` | string | The company's address. |
| `zipcode` | string | Postal code. |
| `city` | string | City or locality. |
| `activity` | string | Activity description. |
| `status` | string | Company status supplied by the data provider. Treat this as text rather than a fixed enum. |
| `cae` | string | Primary economic activity classification (CAE) code. |
| `structure` | object | Legal nature and share capital. |
| `tax_debt` | object or null | Available tax-authority debt bracket. |
| `social_security_debt` | object or null | Available social-security debt bracket. |

These fields are present in the response. Text fields can be empty when information is unavailable.

### Legal structure

| Field | Type | Meaning |
| - | - | - |
| `structure.nature` | string | The company's legal nature. |
| `structure.capital` | string | Share capital as a decimal string, not a JSON number. Preserve decimal precision when processing it. |
| `structure.capital_currency` | string | Currency associated with the capital value. |

If your data provider supplies no capital or currency, the stored values default to `"0"` and `"EUR"` respectively. Do not interpret those defaults as independently verified financial figures.

### Debt brackets

When `tax_debt` or `social_security_debt` is an object, it has these fields:

| Field | Type | Meaning |
| - | - | - |
| `start` | integer | Lower amount of the published debt bracket. |
| `end` | integer or null | Upper amount; `null` indicates an open-ended bracket. |
| `last_updated` | string | The source dataset's update date in `YYYY-MM-DD` format. |

Debt data describes a bracket, not an exact balance. A `null` debt object means no bracket is available in the imported dataset; it is not confirmation of zero debt. Check `last_updated` when using a bracket.

## Data freshness

You receive stored company details when the record is less than six days old. For a missing or older record, the API attempts a refresh through NIF.PT, then falls back to the commercial registry if NIF.PT fails.

If the refresh fails, you receive an error rather than the older stored record. Debt datasets are imported separately, so their source dates can differ from the freshness of your company's details.

## Errors

* `400 validation`: your NIF cannot be normalized to nine digits or fails the checksum.
* `404 company-not-found`: no company was found for your valid NIF.
* `502 company-lookup-failed`: the lookup or refresh could not complete.

See [Errors](../errors) for authentication, quota, and other shared failures.

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

<ResponseExample>
  Illustrative fixture response; this is not a live company record or debt report.

  ```json theme={null}
  {
    "result": "success",
    "data": {
      "nif": 509442013,
      "title": "Exemplo, Lda",
      "address": "Rua de Exemplo, 1",
      "zipcode": "1000-001",
      "city": "Lisboa",
      "activity": "Atividade de exemplo",
      "status": "",
      "cae": "",
      "structure": {
        "nature": "Sociedade por quotas",
        "capital": "5000.00",
        "capital_currency": "EUR"
      },
      "tax_debt": {
        "start": 10000,
        "end": 50000,
        "last_updated": "2026-09-15"
      },
      "social_security_debt": null
    }
  }
  ```
</ResponseExample>


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