--- title: "ReceitaWS Integration" description: "ReceitaWS returns Brazilian company registration data for a CNPJ straight from the Receita Federal. Agents validate a CNPJ and pull the registered name, address, activities, partners and status, with an optional freshness limit on cached results." url: https://flowrunner.ai/integrations/receitaws date_modified: 2026-09-04T19:38:13-07:00 --- # ReceitaWS [Analytics & Data](https://flowrunner.ai/integrations/category/analytics-data) ReceitaWS returns Brazilian company registration data for a CNPJ straight from the Receita Federal. Agents validate a CNPJ and pull the registered name, address, activities, partners and status, with an optional freshness limit on cached results. [Verified](https://flowrunner.ai/integrations/verified "What does verified mean?") · 2 actions · API key · available [ReceitaWS website](https://receitaws.com.br/) · [Platform Documentation](https://receitaws.com.br/) · Capability data verified 2026-08-27 1. A supplier invoice or onboarding form arrives carrying a CNPJ 2. Agent reads the CNPJ off the document and normalizes it to fourteen digits 3. Get Company returns the register record, and the agent checks the status field rather than the HTTP result 4. Get Company With Max Age re-runs the lookup with Maximum Age 0 when the registration status is anything other than active 5. Agent compares the registered legal name, address, and CNAE activity codes against the vendor master 6. Agent posts the live record and the stored record side by side to the AP channel 7. The AP owner decides whether the supplier goes on payment hold ## What This Integration Enables ReceitaWS is the smallest connector in this catalog that still changes how a finance team works, and its two operations are the whole point. One is a free lookup against the Receita Federal that may hand back a cached copy of unknown age. The other takes an argument that no other register API in this catalog exposes: how stale a copy you are willing to accept. Set it to zero and you force a live query. Set it higher and you get a fast, cheap answer. Freshness stops being a property of the API and becomes a decision the workflow makes, one call at a time. That matters because Brazilian registration data is not static. A company's status moves, its partners change, its address changes, and the CNAE activity codes on the register are what a tax determination often turns on. FlowRunner agents can afford to check on every document rather than once at onboarding, because the cheap route costs nothing per call. When the cheap answer looks wrong, the agent spends a live query to be sure, and then stops, because deciding what to do about a supplier whose registration has moved is not a lookup. ### Without FlowRunner **Checked once, at onboarding**: A CNPJ is verified the day the vendor is created and never looked at again **Stale answers pass unnoticed**: A cached lookup and a live one are indistinguishable once the result is written down **Refusals read as records**: An invalid CNPJ comes back in the same envelope as a real company and passes a casual check ### With FlowRunner **Checked on the invoice, not the calendar**: Every document that carries a CNPJ gets a lookup before it reaches the payment run **Freshness is chosen, not assumed**: The agent states how old a cached record it will accept, and forces a live query when the answer matters **Refusals are handled as refusals**: The agent reads the status field, so a rejected CNPJ never becomes a vendor record ## Use Case Scenarios ### The CNPJ on the invoice is checked before the invoice is An invoice lands in the AP inbox and an extraction step pulls the CNPJ. The agent calls Get Company, reads back the legal name, trading name, registration status, address, and the primary and secondary CNAE codes, and compares them against the vendor record in [NetSuite](https://flowrunner.ai/integrations/netsuite) or [Odoo](https://flowrunner.ai/integrations/odoo). A clean match routes the invoice onward. A name that does not match, or an address that has moved, becomes an exception carrying both records rather than a blocked queue with no explanation. Nothing about this is a new process. It is the same check a careful AP clerk does, running on every document instead of on the ones somebody happened to doubt. ### A vendor master sweep that is honest about its own age On a schedule, the agent walks the active vendor list and calls Get Company for each CNPJ. Because the free route is rate limited per IP address and may serve a cached copy, the sweep is treated as a screen rather than as evidence: it produces a shortlist of records that appear to have changed. Only that shortlist goes through Get Company With Max Age at Maximum Age 0, which spends from the account allowance to get a live answer from the Receita Federal. The result is a monthly hygiene pass on the whole vendor file at a fraction of the cost of querying it live, with the expensive calls aimed only at the rows that earned them. ### Onboarding that refuses to invent a supplier A new supplier submits a form. The agent normalizes the CNPJ, calls Get Company, and finds a response that is shaped like a record but carries an error status, which is how ReceitaWS reports both an invalid number and one that is simply not on the register. Rather than creating a vendor with a blank legal name, the agent sends the submitter back a specific message naming the field. If the number resolves but the registered name differs materially from what was typed on the form, the agent gathers both, attaches the register address, and posts the pair to the buyer in [Slack](https://flowrunner.ai/integrations/slack) with a single question about which one is the real counterparty. ## Human-in-Loop Highlight Putting a supplier on payment hold stops real money reaching a real business, and it is the kind of act that gets reversed slowly and apologetically. So when a sweep finds a vendor whose registration status is no longer active, the agent does not act on it. It first spends a live query with Get Company With Max Age at Maximum Age 0, because the free route may have handed it a cached record and a stale status is a bad reason to freeze a payment. Then it stops and asks: "Vendor 41.234.567/0001-89, Comercial Sul Ltda, has open invoices totaling R$ 84,000. The Receita Federal record now shows status BAIXADA, dated 12 March, confirmed by a live query. A status change can be a filing lapse rather than a closure. Hold payment, request documents, or continue?" The buyer answers. FlowRunner's [human-in-the-loop](https://flowrunner.ai/concepts/human-in-the-loop) step is what keeps a register lookup from turning into a unilateral decision about somebody's cash flow. Agent processes routinely Detects exception requiring judgment Clear match Continues automatically Ambiguous Routes to human via preferred channel Human decides Agent resumes with decision ## Agent Capabilities 2 actions ### Company Lookup 2 - **Get Company** Looks up a Brazilian company by CNPJ and returns its Receita Federal registration record: legal and trading name, status and status date, incorporation date, legal nature, size, share capital, address, contact details, the primary and secondary CNAE activity codes, and the registered partners. This is the free route, rate limited per IP address, and it may serve a cached copy. Use it for screening sweeps and for the first check on an inbound document. - **Get Company With Max Age** Looks up a company by CNPJ while stating how old a cached copy the workflow will accept. ReceitaWS serves cached data when it is younger than Maximum Age and queries the Receita Federal afresh when it is not, so zero forces a live answer and a larger number is faster and cheaper. This route requires an API token and each fresh query draws on the account allowance, which makes it the call to aim at the records that already look wrong. ## Frequently Asked Questions ### What can FlowRunner do with ReceitaWS? FlowRunner agents can run Get Company and Get Company With Max Age in ReceitaWS. ### Does connecting ReceitaWS to FlowRunner require OAuth? No. ReceitaWS connects to FlowRunner with an API key, no OAuth flow required. ### Can ReceitaWS trigger a FlowRunner workflow automatically? ReceitaWS doesn't currently expose triggers in FlowRunner. It connects as an action step inside workflows started by another trigger. **Work at ReceitaWS?** This integration exposes ReceitaWS to AI agents on every FlowRunner plan, including through MCP, at no cost to you. [See what FlowRunner offers integration partners](https://flowrunner.ai/integrations/partners), including how to keep this page current. --- Markdown version of https://flowrunner.ai/integrations/receitaws. Site index: https://flowrunner.ai/llms.txt