# Costa Rica Cedula Scraper — Hacienda Company Registry & KYB (`registralia/costa-rica-cedula-scraper`) Actor

Scrape Costa Rica's official Hacienda taxpayer registry by cedula juridica or fisica. Get legal name, registration status, legal form, tax regime, tax office and all economic activities - plus the authority's own moroso (tax debt) and omiso (non-filer) flags. No API key. JSON, CSV, Excel.

- **URL**: https://apify.com/registralia/costa-rica-cedula-scraper.md
- **Developed by:** [Nico Dennis Günther](https://apify.com/registralia) (community)
- **Categories:**
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $14.00 / 1,000 taxpayer record returneds

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/actors/running/actors-in-store.md#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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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

## Costa Rica Cedula Scraper — Hacienda Company Registry & KYB

Scrape the **official Costa Rica company registry** at the Ministerio de Hacienda by cédula jurídica or física and get back a clean, English-keyed record: legal name, registration status, legal form, tax regime, every registered economic activity, and the tax authority’s own delinquency and non-filer designations.

One cédula in, one structured taxpayer profile out. No account, no API key, no captcha solving — this Actor reads the registry Costa Rica's electronic-invoicing regime runs on, and normalizes it for machines.

### What you get

For cédula jurídica `3101005212`:

```json
{
  "identification": "3101005212",
  "identificationType": "cedula_juridica",
  "country": "CR",
  "legalName": "COCA COLA FEMSA DE COSTA RICA SOCIEDAD ANONIMA",
  "entityType": "company",
  "juridicalClass": "sociedad_anonima",
  "status": "registered",
  "statusOriginal": "Inscrito",
  "canIssueElectronicInvoice": true,
  "isTaxDelinquent": false,
  "isNonFiler": false,
  "riskFlagsRaised": [],
  "hasRiskFlag": false,
  "taxRegime": "Régimen general",
  "taxOffice": "Dirección de Grandes Contribuyentes Nacionales",
  "mainActivity": "Venta al por mayor de otros alimentos",
  "mainActivityCode": "4630.9",
  "activityCount": 2,
  "activities": [
    { "code": "4630.9", "description": "Venta al por mayor de otros alimentos", "type": "primary", "status": "active" },
    { "code": "3830.0", "description": "Recuperación de materiales", "type": "secondary", "status": "active" }
  ]
}
```

### Why this data matters

**`isTaxDelinquent` and `isNonFiler` are the point.** Hacienda publicly marks taxpayers as *moroso* (owes tax) and *omiso* (failed to file required returns). These are official designations by the tax authority, not inferences, and they are the two fields Costa Rican due diligence actually turns on.

**`canIssueElectronicInvoice` answers a question that costs real money.** Costa Rica runs a mandatory electronic invoicing regime, and this is the registry behind it. A supplier who is not *inscrito* cannot legally issue you a valid factura electrónica — which means the expense is not deductible. Checking this before you onboard a vendor is cheaper than discovering it at year end.

**`juridicalClass` tells you what you are actually dealing with.** The second block of a cédula jurídica encodes the legal form, so `3-101-` is a sociedad anónima, `3-102-` an SRL, `3-109-` a foundation, `3-110-` an association. Decoded for you, it is a free segmentation column: filter the corporations out of a list of NGOs without opening a single record.

### Use cases

| You are | You use it for |
|---|---|
| KYB / AML platform | Supplier and merchant verification with official status plus delinquency flags |
| Accounts payable / finance | Confirm a vendor may legally invoice you before you book a deductible expense |
| Fintech / lender | Borrower checks: is the entity registered, under which regime, flagged by the authority |
| B2B sales team | Qualify and segment accounts by economic activity code and legal form |
| Procurement / compliance | Vendor due diligence and periodic re-screening of an existing book |

### Input

| Field | Type | Default | Notes |
|---|---|---|---|
| `identifications` | array | — | Costa Rican identification numbers. Dashes and spaces are ignored, so `3-101-005212` works. Also accepts a newline- or comma-separated string, or objects passed from another Actor. |
| `includeRaw` | boolean | `false` | Attaches the untouched Spanish payload under `raw` for auditing. |
| `maxConcurrency` | integer | `5` | Parallel lookups, capped at 10. It is a public service; stay polite. |
| `requestTimeoutSecs` | integer | `30` | |
| `maxRetries` | integer | `3` | Exponential backoff on 429 and 5xx. |
| `proxyConfiguration` | object | off | Only needed if Hacienda rate-limits the datacenter IP. |

Simplest possible run:

```json
{ "identifications": ["3101005212", "3101002001"] }
```

### Which numbers work

| Shape | Meaning |
|---|---|
| 9 digits | Cédula física — a Costa Rican natural person |
| 10 digits starting with `3` | Cédula jurídica — company, association, foundation |
| 10 digits starting with `5` | NITE — assigned to taxpayers without a cédula |
| 11–12 digits | DIMEX — foreign resident |

Costa Rica publishes no check digit for these numbers, so this Actor classifies the shape and lets the registry be the judge of existence. It will not tell you a number "passed validation" when the country defines no such test.

### Three ways to read the results

The dataset ships with prepared views, so nothing needs flattening by hand:

- **Taxpayers** — one row per cédula with the review columns.
- **Flagged only** — the columns that matter when the authority raised a warning.
- **Economic activities** — one row per registered activity with its official code.

Export any of them as CSV, Excel, JSON or XML, or pull them from the API.

### Output notes

- Every input number produces exactly one dataset item, so a batch of 500 gives you 500 rows you can join back on `identification`.
- Failures are data, not silence: unmatched or malformed inputs come back with `found: false` and an `error` of `not_found`, `invalid_identification` or `lookup_failed`.
- Registry `SI`/`NO` values become real booleans, and `Inscrito` / `Desinscrito` / `No inscrito` map to `registered` / `deregistered` / `not_registered`, with the original kept in `statusOriginal`.
- **A flag the registry does not state stays `null`, never `false`.** Reporting a missing value as a clean bill of health is the one bug in a KYB feed that can actually cost you money, so this Actor does not do it.

### Pricing

Pay per event, and you only pay for what the registry actually returned:

| Event | Price | When |
|---|---|---|
| Taxpayer record | **$0.014** | Once per identification number found, including status, regime, all activities and both risk flags |
| Actor start | $0.0001 | Container startup. Not an access fee. |

**Not-found and malformed numbers are free**, so a dirty input list costs you nothing extra. There is no minimum spend and no subscription.

A worked example: screening 500 Costa Rican suppliers — 500 × $0.014 = **$7.00**. Re-screening the same book monthly costs the same again, and catches the ones that slipped into *moroso* since last time.

For comparison, the manual alternative is opening the Hacienda portal and transcribing fields, one taxpayer at a time — one to three minutes each. At 500 suppliers that is more than a full working day.

### Notes on the source

Data comes from Hacienda's public taxpayer endpoint (`api.hacienda.go.cr/fe/ae`), the same service Costa Rican invoicing software queries. This Actor does not authenticate, does not bypass any access control and does not solve captchas — it reads what the authority serves openly and passes the values through unchanged. Sole traders and DIMEX holders are natural persons, so treat their records as personal data under your own GDPR and Ley 8968 obligations.

**Not an official Hacienda product.** This Actor is an independent tool built by Echocall LLC. It is not affiliated with, endorsed by, or operated by the Ministerio de Hacienda or any Costa Rican government body. "Hacienda" and "cédula" are used descriptively to name the public data source.

### Roadmap

Same approach, more registries — Panama, Guatemala, Paraguay, Uruguay. If you need Ecuador or a mixed regional list in one run, see **LATAM Company Lookup**, which routes Ecuadorian RUCs and Costa Rican cédulas through one call and returns a single shared schema.

### FAQ

**How do I look up a Costa Rican company by cédula jurídica?**

Hacienda publishes its taxpayer registry as an open service. This Actor queries it and returns structured JSON, CSV or Excel — one row per cédula, in bulk, with no login and no API key.

**What is a cédula jurídica?**

It is Costa Rica's 10-digit company registration number, always starting with `3`. The middle block encodes the legal form, so `3-101-` is a sociedad anónima, `3-102-` an SRL, `3-109-` a foundation and `3-110-` an association. This Actor decodes that block for you into `juridicalClass`.

**What do *moroso* and *omiso* mean?**

*Moroso* means the taxpayer owes tax; *omiso* means it failed to file required returns. Both are official designations by the tax authority, exposed here as `isTaxDelinquent` and `isNonFiler`. They are the two fields Costa Rican due diligence actually turns on.

**How do I check whether a supplier can issue a valid electronic invoice?**

Read `canIssueElectronicInvoice`. Costa Rica runs a mandatory electronic invoicing regime, and this is the registry behind it — a supplier who is not *inscrito* cannot legally issue you a valid factura electrónica, which means the expense is not deductible.

**Does it work for individuals as well as companies?**

Yes. A 9-digit cédula física covers a Costa Rican natural person, 10 digits starting with `5` is a NITE, and 11–12 digits is a DIMEX for a foreign resident.

**Is scraping the Hacienda registry legal?**

This Actor reads the same public endpoint Costa Rican invoicing software queries. It does not authenticate, does not bypass access controls and does not solve captchas. Natural persons' records are personal data under your own GDPR and Ley 8968 obligations.

**What does it cost to try?**

Every new Apify account includes free monthly usage credit, which covers a few hundred lookups before you pay anything.

### Related Actors

- **Ecuador SRI RUC Scraper** — the same idea for Ecuador, including the SRI's ghost-taxpayer fraud flags.
- **LATAM Company Registry Scraper** — one call for a mixed list of Costa Rican cédulas and Ecuadorian RUCs, returning a single shared schema.

# Actor input Schema

## `identifications` (type: `array`):

Costa Rican identification numbers: 9 digits for a cédula física (person), 10 digits starting with 3 for a cédula jurídica (company), 10 starting with 5 for a NITE, or 11-12 digits for a DIMEX. Dashes and spaces are ignored, so 3-101-005212 works too.

## `includeRaw` (type: `boolean`):

Attach the untouched Spanish-language response from Hacienda under a `raw` field, for auditing or for fields this Actor does not map.

## `maxConcurrency` (type: `integer`):

How many identification numbers to look up at the same time. Capped at 10 — Hacienda runs a public service, so stay polite.

## `requestTimeoutSecs` (type: `integer`):

Seconds to wait for a single Hacienda response before giving up on it.

## `maxRetries` (type: `integer`):

How often to retry a request that was rate-limited or answered with a server error. Backoff is exponential.

## `proxyConfiguration` (type: `object`):

Only needed if Hacienda rate-limits the datacenter IP. Leave it off unless you see retries in the log.

## Actor input object example

```json
{
  "identifications": [
    "3101005212",
    "3101002001"
  ],
  "includeRaw": false,
  "maxConcurrency": 5,
  "requestTimeoutSecs": 30,
  "maxRetries": 3,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `companies` (type: `string`):

One normalized record per identification number: legal name, registration status, tax regime, economic activities, and the official tax-delinquency and non-filer flags.

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "identifications": [
        "3101005212"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("registralia/costa-rica-cedula-scraper").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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "identifications": ["3101005212"] }

# Run the Actor and wait for it to finish
run = client.actor("registralia/costa-rica-cedula-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "identifications": [
    "3101005212"
  ]
}' |
apify call registralia/costa-rica-cedula-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,registralia/costa-rica-cedula-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/fjXLQgwTcyWt5all1/builds/Rba8NvhxZsZ6n3Mrx/openapi.json