CNPJAPI

Check a CNPJ's installment plans with Receita Federal via API

Every month, Receita Federal (Brazil's federal tax authority) publishes as open data the list of active installment plans for federal taxes: who has a plan in progress, of which type, how much was placed in installments and the outstanding balance. CNPJAPI tells you by API, on paid plans, whether the company had an active installment plan in the latest data published by Receita Federal, not its status today. The information comes in every CNPJ lookup, in the same JSON as the registration data, with no extra call and no extra cost. It does not replace the official tax clearance certificate.

It is useful, dated data for credit analysis and for vetting customers and suppliers: it shows the type and balance of the installment plans the company had in the published data, without saying whether the installments are up to date.

What an active installment plan with Receita Federal is

When a company does not pay a federal tax on time, it can ask Receita Federal to pay the debt in installments. While the plan is in progress (not paid off, terminated or excluded), it shows in the active installment plan data. There are standard plans (for MEI, for Simples Nacional, and the ordinary or simplified plan), special plans created by law (such as PERT and RELP), and plans for public bodies.

An installment plan kept up to date does not, by itself, prevent the "positive with effects of negative" certificate (certidão positiva com efeitos de negativa): having an installment plan is not, by itself, an irregularity.

How it differs from the federal tax debt registry

The federal tax debt registry (dívida ativa da União) holds debts that PGFN (the National Treasury Attorney's Office) has already registered for collection (for taxes administered by Receita Federal, after it refers them). An installment plan with Receita Federal comes before that: the debt is still with Receita Federal. Installment plans for debts already in the registry are made at PGFN and show in the federal tax debt block, in regular status (tax benefit). They are different datasets, and a company can be in both.

Installment plans with Receita Federal Federal tax debt registry
Response field ParcelamentosRFB DividaAtiva
Source Receita Federal PGFN
Debt Placed in installments at Receita Federal, before registration Registered for collection
Publication Monthly, with the publication date Quarterly, with the extraction month

Seven points before you use it

  1. Source: Receita Federal's open data on active installment plans. Every response carries "Fonte": "Receita Federal, dados abertos de parcelamentos ativos".
  2. Date: Receita Federal publishes the data every month, between the 20th and the 31st. The response carries the date Receita Federal published the data (PublicadoEm).
  3. Lag: the data is a snapshot of the extraction date and can be up to about two months old. Payoffs, terminations (including for late payment) and requests made after the publication do not show until the next publication.
  4. Where to check the current status: the tax clearance certificate (Receita Federal and PGFN) shows the current standing of any CNPJ, but does not list installment plans. Only the company itself sees the details of its plans, in e-CAC.
  5. Not a certificate: this information does not replace the official tax clearance certificate (certidão de regularidade fiscal).
  6. An installment plan is not an irregularity: an installment plan kept up to date does not, by itself, prevent the "positive with effects of negative" certificate.
  7. No information on late payments: the data does not say whether any installment is overdue. The balance includes overdue installments and those still to come due.

How it works

Make the regular CNPJ lookup (GET /{cnpj}) with the API key of a paid plan. The response gains a ParcelamentosRFB field, after DividaAtiva. For a company with installment plans, it looks like this (fictitious CNPJ and amounts):

curl https://api.cnpjapi.com.br/98765432000198 \
  -H "Authorization: Bearer cnpj_sua_chave"

"ParcelamentosRFB": {
  "Fonte": "Receita Federal, dados abertos de parcelamentos ativos",
  "PublicadoEm": "2026-10-27",
  "ConstavaParcelamentoAtivo": true,
  "Parcelamentos": 2,
  "ValorParcelado": 412300.50,
  "SaldoDevedor": 301455.12,
  "PorTipo": {
    "MEI": { "Parcelamentos": 0, "ValorParcelado": 0.00, "SaldoDevedor": 0.00 },
    "SimplesNacional": { "Parcelamentos": 0, "ValorParcelado": 0.00, "SaldoDevedor": 0.00 },
    "OrdinarioSimplificado": { "Parcelamentos": 1, "ValorParcelado": 142756.79, "SaldoDevedor": 133332.08 },
    "Especial": { "Parcelamentos": 1, "ValorParcelado": 269543.71, "SaldoDevedor": 168123.04, "Modalidades": ["PERT"] },
    "OrgaoPublico": { "Parcelamentos": 0, "ValorParcelado": 0.00, "SaldoDevedor": 0.00, "Modalidades": [] }
  },
  "CNPJsRegistrados": ["98765432000198"]
}

Five points to read the response right:

  • ConstavaParcelamentoAtivo is about the data published on PublicadoEm, not today. true means the company was in that publication's active installment plan data, including with a zero balance.
  • The five types always come. MEI, SimplesNacional, OrdinarioSimplificado, Especial and OrgaoPublico appear in every response, zeroed when there is none. Especial adds up the special plans for legal entities, Simples Nacional and MEI; Especial and OrgaoPublico carry the Modalidades with the names Receita Federal publishes.
  • Balance at the extraction date. SaldoDevedor is the balance adjusted up to the extraction, in BRL, adding overdue installments and those still to come due. The data does not say whether any installment is overdue.
  • The match is by the CNPJ root. Looking up any establishment returns the plans of the whole company, and CNPJsRegistrados tells which CNPJs of the root are in the data.
  • No start date. The response does not carry the date the plan was requested or granted, so it does not tell how long the plan has existed.

When the company is not in the data, the block comes with ConstavaParcelamentoAtivo: false, zeroed totals and types, CNPJsRegistrados: [] and the PublicadoEm. Read it as "had no active installment plan in the data Receita Federal published on October 27, 2026", not as "no debt".

Code example

The Node examples use native fetch (Node 18+) and top-level await - run them as an ES module (a .mjs file, or "type": "module" in package.json), or wrap the code in an async function.

Python:

import requests

cnpj = "98765432000198"
r = requests.get(
    f"https://api.cnpjapi.com.br/{cnpj}",
    headers={"Authorization": "Bearer cnpj_sua_chave"},
    timeout=10,
)
r.raise_for_status()
company = r.json()

plans = company.get("ParcelamentosRFB")
if plans is None:
    # free or ended paid plan ("ParcelamentosRFBDisponivelEm") or check unavailable right now ("ParcelamentosRFBErro")
    print("Installment plans not checked:", company.get("ParcelamentosRFBDisponivelEm") or company.get("ParcelamentosRFBErro"))
elif plans["ConstavaParcelamentoAtivo"]:
    print(f'Had an active installment plan in the data published on {plans["PublicadoEm"]}:',
          plans["Parcelamentos"], "plans, balance BRL", plans["SaldoDevedor"])
else:
    print(f'No active installment plan in the data published on {plans["PublicadoEm"]}')

Node.js:

const cnpj = "98765432000198";
const r = await fetch(`https://api.cnpjapi.com.br/${cnpj}`, {
  headers: { Authorization: "Bearer cnpj_sua_chave" },
});
if (!r.ok) throw new Error(`HTTP ${r.status}`);
const company = await r.json();

const plans = company.ParcelamentosRFB;
if (plans === null || plans === undefined) {
  console.log("Installment plans not checked:", company.ParcelamentosRFBDisponivelEm ?? company.ParcelamentosRFBErro);
} else if (plans.ConstavaParcelamentoAtivo) {
  console.log(`Had an active installment plan in the data published on ${plans.PublicadoEm}:`, plans.Parcelamentos, "plans, balance BRL", plans.SaldoDevedor);
} else {
  console.log(`No active installment plan in the data published on ${plans.PublicadoEm}`);
}

When the block is missing

  • Free plan (or an ended paid plan): "ParcelamentosRFB": null and "ParcelamentosRFBDisponivelEm": "planos_pagos". The CNPJ data comes normally.
  • Check unavailable right now: "ParcelamentosRFB": null and "ParcelamentosRFBErro": "indisponivel". This is also what comes when the served data is more than 70 days past its publication with no newer data loaded (Receita Federal published late or the next data has not been loaded yet), so stale data is not served. The CNPJ lookup is not affected.
  • ReceitaWS format (?formato=receitaws or /v1/cnpj/{cnpj}): the field does not exist.

Many CNPJs at once

In a batch (POST /consulta/lote, up to 20 CNPJs per call), each found item carries the same block inside Dados. Handy to review your whole customer base at once.

Frequently asked questions

How recent is the installment plan information?

Receita Federal publishes the data every month, between the 20th and the 31st, and every lookup shows the publication date. The data can be up to about two months old.

Does having an installment plan mean the company is irregular?

Not necessarily. An installment plan kept up to date does not, by itself, prevent the "positive with effects of negative" certificate (certidão positiva com efeitos de negativa). The data also does not say whether any installment is overdue.

If the company is not in the data, does that mean it owes nothing to Receita Federal?

No. It means the company had no active installment plan in that publication's data. Debts not in installments, not yet declared or already in the federal tax debt registry are not in this data.

How does it differ from the federal tax debt registry?

The federal tax debt registry holds debts that PGFN has already registered for collection (for taxes administered by Receita Federal, after it refers them). An installment plan with Receita Federal comes before that. Installment plans for debts already in the registry show in the federal tax debt block, in regular status.

Does the lookup replace the tax clearance certificate?

No. For that, request the tax clearance certificate (certidão de regularidade fiscal) through the official channels.

Caveats

  • The data comes from Receita Federal's official data, aggregated by CNPJ root and by plan type, without changing the amounts; it is not a judgment by CNPJAPI about the company.
  • Use the information as a dated signal, not as today's status. For decisions that depend on the current status, obtain the tax clearance certificate.

Next steps