Name: Quinas API: Portugal NIF, IBAN Validation and Holidays
Brand: hybrid-forge-lab
SKU: api-hybrid-forge-lab-quinas
Availability: InStock
Author: API Market

# Quinas Portugal Business Data API

## Overview

The Quinas Portugal Business Data API validates Portuguese identifiers and works out Portuguese business days. It checks NIF and NIPC tax numbers and says what kind of entity they belong to, validates Cartão de Cidadão numbers and PT IBANs or NIBs (with the bank name and BIC), lists the Banco de Portugal bank codes and all 308 municipalities, and returns national, regional and municipal holidays for any year from 1990 to 2100. Business-day endpoints check a date, add or subtract business days and count business days between two dates for a chosen municipality.

It is built for developers of invoicing, payroll, e-commerce, KYC and logistics software that serves Portugal, where a wrong tax number or a missed municipal holiday causes real problems. Every answer is plain JSON with a `valid` flag and a `reason` for identifiers, or the dates and holiday names for calendar questions, and everything is computed locally from the official algorithms and published lists.

## Features

*   **Twelve endpoints**: NIF, Cartão de Cidadão and IBAN validation, banks, municipalities, holidays, three business-day calculators, bulk validation and a health check.
*   **Entity type from NIF**: a valid NIF also returns its `type` (for example company) and the `vat_number` in PT format.
*   **Bank lookup**: IBAN and NIB validation returns the bank code, bank name and BIC from the Banco de Portugal list.
*   **Municipal holidays**: all 308 municipalities with their district, region and own holiday, plus the Azores and Madeira regional holidays.
*   **Business-day maths**: check a date, add N business days or count business days between dates, per municipality.
*   **Bulk validation**: validate up to 100 NIFs, CC numbers and IBANs in one call on paid plans.
*   **Rate limit**: up to 10 requests per second on every plan.

## Use Cases

*   **Invoicing and checkout**: validate a customer's NIF before issuing an invoice.
*   **KYC and onboarding**: check citizen card numbers and IBANs when opening accounts.
*   **Payroll and HR**: count working days per municipality for pay periods and leave.
*   **Logistics and SLAs**: compute delivery and due dates that skip local holidays.
*   **Payments**: confirm an IBAN and show the bank name before saving a payout account.

## API Documentation

### Base URL

All requests go through the API.market proxy at this base URL:

```
https://prod.api.market/api/v1/hybrid-forge-lab/quinas
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Health check

Returns `ok`, the service version and its uptime.

**Method:** `GET`

**Endpoint:** `/v1/health`

**Parameters:**

This endpoint takes no parameters.

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/hybrid-forge-lab/quinas/v1/health' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "ok": true,
  "version": "0.3.0",
  "uptime_s": 0
}
```

#### 2. Validate a NIF or NIPC

Checks a 9-digit Portuguese tax number and returns whether it is valid, the kind of entity it belongs to and its PT VAT number.

**Method:** `GET`

**Endpoint:** `/v1/nif/{nif}`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `nif` | path | The 9-digit NIF or NIPC. | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/hybrid-forge-lab/quinas/v1/nif/501964843' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "input": "501964843",
  "nif": "501964843",
  "valid": true,
  "type": "company",
  "type_label": "Pessoa coletiva",
  "vat_number": "PT501964843",
  "reason": null
}
```

#### 3. Validate a Cartão de Cidadão number

Checks a citizen card document number and returns whether it is valid and the civil identification number it contains. The example uses the official test number.

**Method:** `GET`

**Endpoint:** `/v1/cc/{number}`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `number` | path | The Cartão de Cidadão document number, for example `000000000ZZ4`. | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/hybrid-forge-lab/quinas/v1/cc/000000000ZZ4' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "input": "000000000ZZ4",
  "number": "000000000ZZ4",
  "valid": true,
  "civil_id": "00000000",
  "reason": null
}
```

#### 4. Validate an IBAN or NIB

Checks a Portuguese IBAN or 21-digit NIB and returns the NIB, the bank code, the bank name and its BIC.

**Method:** `GET`

**Endpoint:** `/v1/iban/{iban}`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `iban` | path | A PT IBAN (25 characters) or a 21-digit NIB, without spaces. | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/hybrid-forge-lab/quinas/v1/iban/PT50003506970000123456703' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "input": "PT50003506970000123456703",
  "iban": "PT50003506970000123456703",
  "nib": "003506970000123456703",
  "valid": true,
  "bank_code": "0035",
  "bank": "CAIXA GERAL DE DEPÓSITOS, SA",
  "bic": "CGDIPTPLXXX",
  "reason": null
}
```

#### 5. List bank codes

Returns the bank codes used in Portuguese IBANs, with each bank's name and BIC.

**Method:** `GET`

**Endpoint:** `/v1/banks`

**Parameters:**

This endpoint takes no parameters.

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/hybrid-forge-lab/quinas/v1/banks' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
[
  {
    "code": "0001",
    "name": "BANCO DE PORTUGAL, EP",
    "bic": "BGALPTTGXXX"
  }
]
```

#### 6. Bulk validation

Validates up to 100 NIFs, Cartão de Cidadão numbers and IBANs in one call. Send any of the three arrays; each item gets the same result as the single endpoints.

**Method:** `POST`

**Endpoint:** `/v1/validate/bulk`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `nif` | body | NIFs or NIPCs to validate. | array of strings | No | - | - |
| `cc` | body | Cartão de Cidadão numbers to validate. | array of strings | No | - | - |
| `iban` | body | IBANs or NIBs to validate. | array of strings | No | - | - |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/hybrid-forge-lab/quinas/v1/validate/bulk' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "nif": [
    "501964843"
  ],
  "cc": [
    "000000000ZZ4"
  ],
  "iban": [
    "PT50003506970000123456703"
  ]
}'
```

This endpoint is available on the Pro, Ultra and Mega plans, not on Free.

#### 7. List municipalities

Returns the municipalities with their INE code, district, region and municipal holiday. Filter by name with `q` or by `district`.

**Method:** `GET`

**Endpoint:** `/v1/municipalities`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `q` | query | Part of a municipality name. | string | No | - | - |
| `district` | query | A district name, for example `Porto`. | string | No | - | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/hybrid-forge-lab/quinas/v1/municipalities?q=lisboa' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
[
  {
    "code": "1106",
    "name": "Lisboa",
    "district": "Lisboa",
    "region": "continente",
    "holiday_name": "Santo António",
    "holiday_rule": "fixed: 13-06",
    "holiday_since": null,
    "holiday_source": "wikipedia",
    "holiday_source_url": "https://pt.wikipedia.org/wiki/Feriados_em_Portugal"
  }
]
```

#### 8. Get one municipality

Returns one municipality by its INE code or name.

**Method:** `GET`

**Endpoint:** `/v1/municipalities/{municipality}`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `municipality` | path | INE code (for example `1106`) or name (for example `lisboa`). | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/hybrid-forge-lab/quinas/v1/municipalities/lisboa' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "code": "1106",
  "name": "Lisboa",
  "district": "Lisboa",
  "region": "continente",
  "holiday_name": "Santo António",
  "holiday_rule": "fixed: 13-06",
  "holiday_since": null,
  "holiday_source": "wikipedia",
  "holiday_source_url": "https://pt.wikipedia.org/wiki/Feriados_em_Portugal"
}
```

#### 9. Holidays for a year

Returns the public holidays for a year. Add a `municipality` to include its regional and municipal holidays.

**Method:** `GET`

**Endpoint:** `/v1/holidays`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `year` | query | Year from 1990 to 2100. | integer | Yes | - | - |
| `municipality` | query | INE code or name to add regional and municipal holidays. | string | No | - | - |
| `optional` | query | Also include optional holidays. | boolean | No | `false` | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/hybrid-forge-lab/quinas/v1/holidays?year=2026&municipality=lisboa&optional=false' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "year": 2026,
  "municipality": {
    "code": "1106",
    "name": "Lisboa",
    "district": "Lisboa",
    "region": "continente",
    "holiday_name": "Santo António",
    "holiday_rule": "fixed: 13-06",
    "holiday_since": null,
    "holiday_source": "wikipedia",
    "holiday_source_url": "https://pt.wikipedia.org/wiki/Feriados_em_Portugal"
  },
  "count": 14,
  "holidays": [
    {
      "date": "2026-01-01",
      "name": "Ano Novo",
      "name_en": "New Year's Day",
      "type": "national",
      "rule": null
    },
    {
      "date": "2026-04-03",
      "name": "Sexta-feira Santa",
      "name_en": "Good Friday",
      "type": "national",
      "rule": null
    }
  ]
}
```

#### 10. Is a date a business day?

Tells you whether a date is a business day in a municipality, and why not when it is a weekend or a holiday.

**Method:** `GET`

**Endpoint:** `/v1/business-days/check`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `date` | query | The date, as `YYYY-MM-DD`. | string | Yes | - | - |
| `municipality` | query | INE code or name. Without it only national holidays count. | string | No | - | - |
| `optional` | query | Treat optional holidays as days off. | boolean | No | `false` | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/hybrid-forge-lab/quinas/v1/business-days/check?date=2026-06-13&municipality=lisboa&optional=false' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "date": "2026-06-13",
  "business_day": false,
  "weekend": true,
  "holiday": {
    "date": "2026-06-13",
    "name": "Santo António",
    "name_en": null,
    "type": "municipal",
    "rule": "fixed: 13-06"
  },
  "municipality": "Lisboa"
}
```

#### 11. Add business days

Returns the date that is N business days after a start date, or before it with a negative N.

**Method:** `GET`

**Endpoint:** `/v1/business-days/add`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `start` | query | Start date, as `YYYY-MM-DD`. | string | Yes | - | - |
| `days` | query | Business days to add; negative to go back. | integer | Yes | - | - |
| `municipality` | query | INE code or name. Without it only national holidays count. | string | No | - | - |
| `optional` | query | Treat optional holidays as days off. | boolean | No | `false` | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/hybrid-forge-lab/quinas/v1/business-days/add?start=2026-12-23&days=3&municipality=lisboa&optional=false' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "start": "2026-12-23",
  "days": 3,
  "result": "2026-12-29",
  "municipality": "Lisboa"
}
```

#### 12. Business days between dates

Counts the business days between two dates (start excluded, end included) and the calendar days.

**Method:** `GET`

**Endpoint:** `/v1/business-days/between`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `start` | query | Start date, as `YYYY-MM-DD` (not counted). | string | Yes | - | - |
| `end` | query | End date, as `YYYY-MM-DD` (counted). | string | Yes | - | - |
| `municipality` | query | INE code or name. Without it only national holidays count. | string | No | - | - |
| `optional` | query | Treat optional holidays as days off. | boolean | No | `false` | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/hybrid-forge-lab/quinas/v1/business-days/between?start=2026-12-01&end=2026-12-31&municipality=lisboa&optional=false' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "start": "2026-12-01",
  "end": "2026-12-31",
  "business_days": 20,
  "calendar_days": 30,
  "municipality": "Lisboa"
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request worked. An invalid number is still a 200, with `valid: false` and a `reason`. |
| 400 | Bad Request | A required parameter is missing or has the wrong format, for example a date that is not `YYYY-MM-DD` or a year outside 1990 to 2100. |
| 401 | Unauthorized | The `x-api-market-key` header is missing or the key is not valid. |
| 403 | Forbidden | Your key has no active subscription to this API, your plan quota is used up, or the endpoint is not part of your plan. |
| 404 | Not Found | The path is wrong, or the item in the path was not found. |
| 429 | Too Many Requests | You sent more than 10 requests per second. Wait for the time in `Retry-After` and try again. |
| 500 | Internal Server Error | Something failed on the provider side. Retry once; if it keeps failing, contact us. |
| 503 | Service Unavailable | The service is briefly unavailable. Retry after a short pause. |

## Rate Limits

Every plan allows up to 10 requests per second. Monthly quotas are 15 calls on Free (a 7-day trial), 25,000 on Pro, 150,000 on Ultra and 1,000,000 on Mega, and each request counts as one call whatever it returns. A bulk request counts as one call. Going over 10 requests per second returns `429 Too Many Requests`. Throttle your client, back off when you get a 429 and honour the `Retry-After` header before retrying.

## FAQ

*   **What is the difference between NIF and NIPC?**

    Both are 9-digit Portuguese tax numbers. NIF is used for people and NIPC for companies and other legal entities. The same endpoint checks both, and `type` tells you which kind of entity the number belongs to.

*   **Does a valid NIF mean the company exists?**

    No. Validation checks the official check-digit algorithm. It does not look the number up in a company register.

*   **Why is `bank` null for my IBAN?**

    The check digits are fine but the bank code is not in the Banco de Portugal list, so `reason` says `unknown bank code`. Check the bank code with `/v1/banks`.

*   **How do I name a municipality?**

    Use its INE code (for example `1106` for Lisboa) or its name. `/v1/municipalities` lists both.

*   **Are municipal holidays included by default?**

    Only when you pass `municipality`. Without it, holiday and business-day answers use national holidays only.

*   **Is bulk validation on the Free plan?**

    No. `/v1/validate/bulk` is on Pro, Ultra and Mega. The Free plan has every other endpoint.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Validate Portuguese NIF, NIPC, citizen card and IBAN numbers, and get holidays and business days for all 308 municipalities in Portugal.

Quinas API: Portugal NIF, IBAN Validation and Holidays

Free