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:

{
  "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:

{ "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.