# CUIT Lookup — AFIP Argentine Taxpayer Registry Search (`mfapitools/cuit-lookup`) Actor Bulk-ingested AFIP taxpayer registry — consulta CUIT/CUIL instant lookup. Two modes: refresh (downloads the official weekly zip, parses ~6M records into a sharded index) and lookup (instant CUIT queries from the index). Pay per successful lookup — not-found queries are free. - **URL**: https://apify.com/mfapitools/cuit-lookup.md - **Developed by:** [Mariano Ferreras](https://apify.com/mfapitools) (community) - **Categories:** Business, Automation, Agents - **Stats:** 2 total users, 1 monthly users, 50.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $2.00 / 1,000 cuit founds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## CUIT Lookup — AFIP Argentine Taxpayer Registry Search > **Pay-per-event — zero monthly fee, zero subscription.** Look up Argentine CUITs (tax IDs) against the official **AFIP taxpayer registry**. Covers ~6.2M records — individuals (física) and companies (jurídica) — with tax status, employer flag, and monotributo category. Pay only for found records. No rental. No idle fees. --- ### What it does This is a **cuit lookup** tool that performs a **cuit search** against the official AFIP **padron AFIP** — the weekly bulk file published by Argentina's tax authority (`apellidoNombreDenominacion.zip`). It downloads and indexes the file on refresh (~86MB weekly, ~320MB uncompressed, ~6 million fixed-width records), then serves **cuit online** lookups in milliseconds from a sharded Key-Value Store index (256 shards by SHA-256 prefix). Each result includes the person or company name, **CUIT/CUIL** display format (`XX-XXXXXXXX-X`), person type (física/jurídica), income tax status, VAT status, monotributo category, employer flag, and society member flag. This actor uses the official AFIP padrón bulk file (re-downloaded weekly) rather than scraping the CuitOnline web interface — this means direct AFIP-sourced data with no third-party dependency, but at most ~7 days of freshness lag. --- ### How it works Two modes: #### `refresh` (run weekly) Downloads and indexes the official AFIP padrón zip. Parses ~6 million fixed-width records, stores them in a sharded Key-Value Store index. Pushes one summary row to the dataset. This mode is **never charged**, but it is not free to run — a full ingest takes ~2.5 minutes and processes ~6M records. **You don't have to run `refresh` before your first `lookup`** — since each customer's index lives in their own Apify account, a `lookup` run automatically bootstraps the index inline the first time it finds none (adds ~2-3 minutes to that one run, still uncharged). After that, schedule `refresh` weekly via Apify Scheduler to keep the index current — `lookup` only ever bootstraps a *missing* index, it never refreshes a stale one. **Freshness guard (built-in):** since each customer's index lives in their own account, it's easy to end up re-running `refresh` more often than the source data actually changes (AFIP publishes the padrón weekly). To avoid burning a ~2.5-minute ingest for nothing, `refresh` checks the existing index's age first: - If the stored index is younger than `minRefreshAgeHours` (default **72**), the run logs a `skipped` result row and exits immediately — no download, no re-ingest. - Set `forceRefresh: true` to bypass the guard and re-ingest unconditionally (useful right after AFIP publishes a new weekly file, or if you suspect the index is corrupt). - The very first refresh on a fresh account always runs in full — there's nothing to compare against yet. If you schedule `refresh` weekly (recommended), the guard is normally a no-op — a real weekly schedule and a 72h default rarely collide. It mainly protects against accidental re-triggers, tighter-than-weekly schedules, or manual re-runs. #### `lookup` (default) Given one or more **Argentine tax ID** numbers (CUITs, 11 digits), reads the relevant index shard (millisecond response) and returns each record. Invalid CUITs (bad check digit) are skipped with a warning and not charged. Only **found** records trigger a `cuit-lookup` event charge. --- ### Input | Field | Type | Default | Description | |-------|------|---------|-------------| | `mode` | enum | `"lookup"` | `"refresh"` or `"lookup"` | | `cuits` | string[] | — | Argentine CUITs (11 digits, with or without dashes). Required in lookup mode. Capped at 100,000 entries — lookup cost is always bounded by this explicit list. | | `maxItems` | int | 50 | Max results in lookup mode (0 = unlimited). | | `minRefreshAgeHours` | int | 72 | `refresh` mode only. Skip re-ingest if the stored index is younger than this many hours. | | `forceRefresh` | bool | false | `refresh` mode only. Ignore `minRefreshAgeHours` and re-ingest unconditionally. | --- ### Output (per CUIT) | Field | Type | Description | |-------|------|-------------| | `cuit` | string | Display format `XX-XXXXXXXX-X` | | `found` | bool | Whether the CUIT was found in the index | | `name` | string\|null | Full name or business name | | `personType` | "fisica"\|"juridica"\|null | Derived from CUIT prefix (20/23/24/27 = física) | | `incomeTaxStatus` | string\|null | Raw Impuesto a las Ganancias status (AC, EX, NC, NI, etc.) | | `vatStatus` | string\|null | Raw IVA status (AC, EX, NC, NI, etc.) | | `monotributoCategory` | string\|null | Monotributo category (A–K, or NN) | | `isSocietyMember` | bool\|null | Integrante de sociedad | | `isEmployer` | bool\|null | Empleador | | `indexRefreshedAt` | ISO\|null | When the index was last refreshed | --- ### Pricing This actor uses **pay-per-event** pricing. You are never charged for not-found lookups, invalid CUITs, or failed requests. | Event | Price | When charged | |-------|-------|-------------| | `cuit-lookup` | **$0.002** | Per CUIT record **found** in the index. Not-found lookups are free. | At $0.002 per found CUIT, 1,000 lookups cost $2.00 — competitive vs. $3/1k alternatives. **Taxpayer verification** at scale costs pennies. `refresh` runs are never charged, but a full ingest (~2.5 minutes, ~6M records) is not free to run — schedule it weekly (matching AFIP's publish cadence and the default `minRefreshAgeHours: 72`) rather than more often; the built-in freshness guard (see above) will skip redundant re-runs automatically either way. --- ### Use cases - **KYC / onboarding pre-fill** — validate a CUIT and pre-fill business name during merchant onboarding - **Supplier verification** — batch-check supplier CUITs for tax status and employer registration - **B2B due diligence** — verify company registration before issuing invoices or contracts - **Fintech batch enrichment** — enrich customer lists with taxpayer names and types - **Agent / LLM tool** — plug into an MCP toolchain for Argentine company lookups --- ### Use with AI agents (MCP) This actor is available as a tool for AI assistants via the Apify MCP server. Agents can call it to **look up Argentine CUITs** directly — no Apify console needed, just a single function call. #### MCP setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com?tools=mfapitools/cuit-lookup", "--header", "Authorization: Bearer " ] } } } ```` #### Example agent prompts - "Look up the CUIT for this Argentine company and tell me its tax status" - "Batch verify these 20 supplier CUITs and flag any that aren't found" - "Check if this CUIT belongs to a person or a company" The actor returns structured JSON with the same fields shown above. Agentic workflows (Claude Code, Cursor, any MCP-compatible AI) can perform **taxpayer verification** and CUIT lookups in the same run they're processing KYC or supplier data. *** ### Limitations (v1) - **Province and main economic activity are NOT available** — these fields are absent from the AFIP bulk file; they would require the SOAP-based `ws_sr_constancia_inscripcion` service (needs an AFIP digital certificate, v2 candidate). - **Freshness ≤ 7 days** — the AFIP zip is published weekly. The `Last-Modified` header is logged during refresh. - **No name search** — v1 is CUIT-keyed only. Name/denominación search would require a separate trigram index (v2 candidate). - **Natural persons included** — the AFIP file contains full names and tax statuses of individuals. This is official public registry data published by the state, but the README must note this for compliance. Contact us if you need a `juridicasOnly` filter. - **Unofficial redistribution** — this actor redistributes AFIP's public file in a more queryable form. Attribution: "Fuente: AFIP — www.afip.gob.ar" *** ### Legal Data source: Administración Federal de Ingresos Públicos (AFIP) — official public taxpayer registry file at `https://www.afip.gob.ar/genericos/cInscripcion/archivos/apellidoNombreDenominacion.zip`. This is government data published specifically for third-party taxpayer verification. We will remove any record upon credible legal complaint. *** ### Changelog See [CHANGELOG.md](./CHANGELOG.md). # Actor input Schema ## `mode` (type: `string`): `refresh` downloads and indexes the latest AFIP padrón (intended for weekly scheduling; also runs automatically on your account's first `lookup` if no index exists yet, adding ~2-3 min to that one run). `lookup` (default) queries individual CUITs from the stored index. ## `cuits` (type: `array`): List of Argentine CUITs (11 digits, with or without dashes). Only used in `lookup` mode. Invalid check-digit CUITs are skipped with a warning and not charged. ## `maxItems` (type: `integer`): Maximum number of CUIT lookups to process. 0 = unlimited. Charges apply per found record. ## `minRefreshAgeHours` (type: `integer`): `refresh` mode only. If the stored index was already refreshed more recently than this many hours ago, the run skips the download/re-ingest and exits immediately (no charge either way — refresh is always free, but skipping avoids ~150s of compute for a repeat refresh against an unchanged weekly AFIP file). Set `forceRefresh` to override. ## `forceRefresh` (type: `boolean`): `refresh` mode only. Ignore `minRefreshAgeHours` and re-download/re-ingest the AFIP padrón even if the stored index is still fresh. ## Actor input object example ```json { "mode": "lookup", "cuits": [ "30-70308853-4", "27-27841710-2" ], "maxItems": 50, "minRefreshAgeHours": 72, "forceRefresh": false } ``` # Actor output Schema ## `results` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "mode": "lookup", "cuits": [ "30-70308853-4", "27-27841710-2" ] }; // Run the Actor and wait for it to finish const run = await client.actor("mfapitools/cuit-lookup").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "mode": "lookup", "cuits": [ "30-70308853-4", "27-27841710-2", ], } # Run the Actor and wait for it to finish run = client.actor("mfapitools/cuit-lookup").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "mode": "lookup", "cuits": [ "30-70308853-4", "27-27841710-2" ] }' | apify call mfapitools/cuit-lookup --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=mfapitools/cuit-lookup", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "CUIT Lookup — AFIP Argentine Taxpayer Registry Search", "description": "Bulk-ingested AFIP taxpayer registry — consulta CUIT/CUIL instant lookup. Two modes: refresh (downloads the official weekly zip, parses ~6M records into a sharded index) and lookup (instant CUIT queries from the index). Pay per successful lookup — not-found queries are free.", "version": "0.1", "x-build-id": "WMCUXn4XpsKcD9Ax2" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/mfapitools~cuit-lookup/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-mfapitools-cuit-lookup", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/mfapitools~cuit-lookup/runs": { "post": { "operationId": "runs-sync-mfapitools-cuit-lookup", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/mfapitools~cuit-lookup/run-sync": { "post": { "operationId": "run-sync-mfapitools-cuit-lookup", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "mode": { "title": "Run mode", "enum": [ "lookup", "refresh" ], "type": "string", "description": "`refresh` downloads and indexes the latest AFIP padrón (intended for weekly scheduling; also runs automatically on your account's first `lookup` if no index exists yet, adding ~2-3 min to that one run). `lookup` (default) queries individual CUITs from the stored index.", "default": "lookup" }, "cuits": { "title": "CUITs to look up", "type": "array", "description": "List of Argentine CUITs (11 digits, with or without dashes). Only used in `lookup` mode. Invalid check-digit CUITs are skipped with a warning and not charged." }, "maxItems": { "title": "Max results", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Maximum number of CUIT lookups to process. 0 = unlimited. Charges apply per found record.", "default": 50 }, "minRefreshAgeHours": { "title": "Minimum refresh age (hours)", "minimum": 0, "maximum": 8760, "type": "integer", "description": "`refresh` mode only. If the stored index was already refreshed more recently than this many hours ago, the run skips the download/re-ingest and exits immediately (no charge either way — refresh is always free, but skipping avoids ~150s of compute for a repeat refresh against an unchanged weekly AFIP file). Set `forceRefresh` to override.", "default": 72 }, "forceRefresh": { "title": "Force refresh", "type": "boolean", "description": "`refresh` mode only. Ignore `minRefreshAgeHours` and re-download/re-ingest the AFIP padrón even if the stored index is still fresh.", "default": false } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```