Guide · Spain · Tax debt risk flag

Spain tax debtors list API: check a company against the AEAT large-debtor list

Q: How do I know how a company was matched?

Every flag has identifier_source: direct_read when the identifier was read directly from the source, name_corroborated when it was reconstructed and confirmed against the company name, with name_match_score. Filter on it if you want only directly read entries.

Q: Does it cover individuals or other countries?

No. The tax_debt flag is Spain only and is served on company records; individuals on the list are not served. The list is annual.

Q: How do I list every company that carries the flag?

Call GET /companies/search with country=ES and risk_flag_type=tax_debt (or has_risk_flag=true). No name is needed. Page with next_cursor and read each flag with include=risk_flags on the company.

The Spanish tax agency publishes a list of large debtors: debts over EUR 600,000. The API matches it to company records by NIF and serves each match as a risk flag, with the amount, the reference date and a link to the official source. It is a snapshot, not a live balance, and every flag says how its identifier was read.

Published 30 September 2026 · Versión en español

What the list is, and what the API serves

The Agencia Tributaria (AEAT) publishes, under article 95 bis of the General Tax Law, a list of debtors owing more than EUR 600,000. In Spanish searches it is the "lista de morosos de Hacienda". Prometiam reads it once it is published, matches each entry to a company record by NIF and serves the match as a tax_debt risk flag on that company. It is Spain only, and it is updated once a year.

You read the flag with include=risk_flags on the company detail, or you list every flagged company with has_risk_flag or risk_flag_type=tax_debt on the search. Both are shown below.

Read this before you rely on a hit

It is point-in-time, not a live balance. The list reports balances as at 31 December of the prior year and is published about six months later. A flag tells you what the AEAT published for a reference date, not what the company owes today.
Inclusion is appealable. A company can contest its entry, and its position may have changed since the reference date. Every flag carries as_of, is_point_in_time: true and a source_url; verify at the source before you act on a hit.
Only debts over EUR 600,000 are listed. The list is not a register of every tax debt, so no flag never means the company owes nothing.
Identifiers are OCR-derived. The source is a scanned PDF. Every identifier is checksum-validated and matched by exact NIF, never by name, which costs recall to protect precision: some listed companies are not flagged. The design prefers a missing flag to a wrong one.
Each flag says how it was read. identifier_source is direct_read when the identifier was read directly from the source, and name_corroborated when it was reconstructed and confirmed against the company's name, in which case name_match_score is set. Filter on it if you want only directly read entries.
Companies only. Only entries that resolve to a company record are served; individuals on the list are not.

Check one company by NIF

Two calls: resolve the NIF to the company's id, then ask for the flags on that company.

# 1. NIF -> company id
curl -H "Authorization: Bearer $PROMETIAM_API_KEY" \
  "https://api.prometiam.com/functions/v1/risk-api/companies/search?nif=$NIF&country=ES"

# 2. The risk flags on that company
curl -H "Authorization: Bearer $PROMETIAM_API_KEY" \
  "https://api.prometiam.com/functions/v1/risk-api/companies/$COMPANY_ID?country=ES&include=risk_flags"

An illustrative, trimmed response for a fictional company. The values are made up:

{
  "data": {
    "id": 123456,
    "nif": "B00000000",
    "company_name": "EXAMPLE, S.L.",
    "status": "active",
    "risk_flags": [
      {
        "flag_type": "tax_debt",
        "severity": "medium",
        "amount_eur": 1250000,
        "reference_date": "2025-12-31",
        "published_date": "2026-06-30",
        "source": "AEAT_95bis",
        "source_url": "<link to the official AEAT publication>",
        "extraction": "ocr",
        "identifier_source": "direct_read",
        "name_match_score": null,
        "as_of": "2025-12-31",
        "is_point_in_time": true,
        "note": "Point-in-time snapshot from an official published list, not a live balance. Verify at source_url before acting on it."
      }
    ]
  }
}

Field	What it holds
`flag_type`	`tax_debt` for this list. On a Spanish company the array can also hold the `registry_compliance` entry, so pick the flag by type, not by position.
`amount_eur`	The amount the list publishes, in euros.
`reference_date`, `as_of`	The date the list's balances refer to. `as_of` repeats it.
`published_date`	When the list was published.
`source_url`	The official source, for you to verify at.
`identifier_source`, `name_match_score`	How the identifier was read: `direct_read`, or `name_corroborated` with a name match score.
`is_point_in_time`, `note`	Always `true`, and a plain statement that this is a snapshot.

List every company that carries the flag

risk_flag_type=tax_debt works on its own, with no name and no identifier. has_risk_flag=true returns companies carrying any published risk flag, which today is this list, and it is Spain only. Page with pagination.next_cursor.

curl -H "Authorization: Bearer $PROMETIAM_API_KEY" \
  "https://api.prometiam.com/functions/v1/risk-api/companies/search?country=ES&risk_flag_type=tax_debt&limit=50"

For the register-side warning that a company has stopped filing, a different flag with a different meaning, see the strike-off risk API.

Use it in code

const API = 'https://api.prometiam.com/functions/v1/risk-api'
const headers = { Authorization: 'Bearer ' + process.env.PROMETIAM_API_KEY }

// AEAT large-debtor flags for a Spanish company, by NIF. [] means no flag: that is no information, not a clean bill.
export async function taxDebtFlags(nif) {
  const found = await fetch(API + '/companies/search?country=ES&nif=' + encodeURIComponent(nif), { headers })
  if (!found.ok) throw new Error('search failed: ' + found.status)
  const { data } = await found.json()
  if (!data.length) return null                       // NIF not on the register

  const res = await fetch(API + '/companies/' + data[0].id + '?country=ES&include=risk_flags', { headers })
  if (!res.ok) throw new Error('detail failed: ' + res.status)
  const company = (await res.json()).data
  return (company.risk_flags || [])
    .filter((f) => f.flag_type === 'tax_debt')
    .map((f) => ({
      amount_eur: f.amount_eur,
      as_of: f.as_of,                                 // a snapshot date, not today
      published_date: f.published_date,
      read_directly: f.identifier_source === 'direct_read',
      source_url: f.source_url,
    }))
}

import os
import requests

API = 'https://api.prometiam.com/functions/v1/risk-api'
HEAD = {'Authorization': 'Bearer ' + os.environ['PROMETIAM_API_KEY']}

def tax_debt_flags(nif, directly_read_only=False):
    """AEAT large-debtor flags for a Spanish company. None: NIF not on the register."""
    found = requests.get(API + '/companies/search', params={'country': 'ES', 'nif': nif},
                         headers=HEAD, timeout=30)
    found.raise_for_status()
    rows = found.json()['data']
    if not rows:
        return None

    detail = requests.get(API + '/companies/' + str(rows[0]['id']),
                          params={'country': 'ES', 'include': 'risk_flags'}, headers=HEAD, timeout=30)
    detail.raise_for_status()
    flags = [f for f in detail.json()['data'].get('risk_flags', []) if f['flag_type'] == 'tax_debt']
    if directly_read_only:
        flags = [f for f in flags if f['identifier_source'] == 'direct_read']
    return flags

What to do with a hit is a policy decision. A sensible default is to route the company to review, keep as_of and source_url with the decision, and ask the company for the current position. A missing flag is no information, not a clean bill. See the company detail and search sections of the docs, and the free NIF lookup to find the NIF first.

What it is not

Not the company's current position. For that, ask the company for its AEAT certificate of being up to date with its tax obligations. This API reports a published list.
Not a credit score. There is no rating and no probability of default. The flag is one fact with its provenance.
Not an insolvency check. Corporate insolvency notices are a separate endpoint, corporate only, for sixteen markets (FR, DE, GB, AT, CH, NO, FI, US, NL, DK, HR, SE, ES, LV, EE, SG).
Not outside Spain. The tax_debt flag exists for Spain only.

It fits a KYB file next to the company record, the administrators from the BORME and, where you screen them, sanctions (beta). See KYB onboarding, supplier due diligence and verifying a Spanish NIF in Python.

Pricing

Starter begins with a 14-day trial: 500 credits in total, 10 requests/minute, card required, nothing charged for 14 days. Subscribing keeps the same key working. Then Starter at €9.99/month (1,000 credits), Professional at €29.99/month (10,000 credits) and Scale at €99.99/month (50,000 credits), monthly or annual. Checking a company is two calls. See pricing.

FAQ

What is the AEAT debtors list?
The Spanish tax agency (AEAT) publishes, under article 95 bis of the General Tax Law, a list of debtors owing more than EUR 600,000. Prometiam matches the list to company records by NIF and serves each match as a tax_debt risk flag on the company.

Is the flag a live balance?
No. The list reports balances as at 31 December of the prior year and is published about six months later, so a flag is a point-in-time snapshot. Inclusion is appealable, and the position may have changed since the reference date. Each flag carries as_of, is_point_in_time and a link to the official source to verify before acting on it.

Does no flag mean the company owes nothing to the tax agency?
No. Only debts over EUR 600,000 are listed, the list is annual, and matching is by exact NIF on identifiers read from a scanned PDF, which costs recall to protect precision. Some listed companies are therefore not flagged. Treat a missing flag as no information.

How do I know how a company was matched?
Every flag has identifier_source: direct_read when the identifier was read directly from the source, name_corroborated when it was reconstructed and confirmed against the company name, with name_match_score. Filter on it if you want only directly read entries.

Does it cover individuals or other countries?
No. The tax_debt flag is Spain only and is served on company records; individuals on the list are not served. The list is annual.

How do I list every company that carries the flag?
Call GET /companies/search with country=ES and risk_flag_type=tax_debt (or has_risk_flag=true). No name is needed. Page with next_cursor and read each flag with include=risk_flags on the company.