Costa Rica Cedula Scraper — Hacienda Company Registry & KYB

Scrape the official Costa Rica Ministerio de Hacienda taxpayer registry by cédula jurídica or cédula física and get back a clean, English-keyed record: legal name, registration status, tax regime, administering tax office, the full list of registered economic activities, and the authority's own moroso (tax-delinquent) and omiso (non-filer) flags.

One cédula in, one structured taxpayer profile out. No account, no API key, no captcha solving — this Actor reads the same public registry a Costa Rican accountant uses, and normalizes it for machines.

What you get

For cédula jurídica 3101005212:

{
  "found": true,
  "identification": "3101005212",
  "identificationType": "cedula_juridica",
  "country": "CR",
  "legalName": "COCA COLA FEMSA DE COSTA RICA SOCIEDAD ANONIMA",
  "entityType": "company",
  "juridicalClass": "sociedad_anonima",
  "status": "registered",
  "canIssueElectronicInvoice": true,
  "isTaxDelinquent": false,
  "isNonFiler": false,
  "riskFlagsRaised": [],
  "hasRiskFlag": false,
  "taxRegime": "Régimen general",
  "taxOffice": "Dirección de Grandes Contribuyentes Nacionales",
  "mainActivity": "Elaboración de bebidas no alcohólicas; producción de aguas minerales y otras aguas embotelladas",
  "mainActivityCode": "1104.0",
  "activityCount": 9,
  "activities": [
    { "code": "1104.0", "description": "Elaboración de bebidas no alcohólicas; producción de aguas minerales y otras aguas embotelladas", "type": "primary", "status": "active" }
  ],
  "source": "Ministerio de Hacienda de Costa Rica",
  "sourceUrl": "https://api.hacienda.go.cr/fe/ae?identificacion=3101005212",
  "scrapedAt": "2026-08-29T14:44:00.000Z"
}

The activities array is shortened here (the real record lists all 9 registered activities). A natural person who stopped filing comes back with "status": "deregistered", "isNonFiler": true and "riskFlagsRaised": ["nonFiler", "deregistered"].

Why this data matters

The two risk flags are the point. Costa Rica's tax authority publicly marks taxpayers as moroso (owes taxes) and omiso (failed to file required returns). Those are official designations, exposed here as isTaxDelinquent and isNonFiler, and summarized in riskFlagsRaised / hasRiskFlag. If you onboard Costa Rican merchants, suppliers or borrowers, this is the most valuable field pair in the country's public data.

Registration status tells you whether an entity may invoice. status is registered, not_registered or deregistered; canIssueElectronicInvoice derives from it, and isExOfficio marks registrations Hacienda made on its own initiative (de oficio).

The activity list is a classification of the business. Every registered economic activity comes back with its code, description, primary/secondary type and active/inactive status — a ready-made industry tag for account qualification or supplier segmentation.

A value the authority did not publish stays null — never false. "Hacienda said nothing" is not the same as "no risk", and the Actor never confuses the two.

Use cases

You are	You use it for
KYB / AML platform	Merchant and supplier verification with official status plus delinquency flags
Fintech / lender	Borrower checks: is the entity registered, which regime, which activities
B2B sales team	Qualify accounts by economic activity and legal form
Procurement / compliance	Vendor due diligence, periodic re-screening of an existing book
Data team	Enrich a Costa Rican company list with authoritative registry fields

Input

Field	Type	Default	Notes
identifications	array	—	Costa Rican identification numbers. Also accepts a newline- or comma-separated string, or objects passed from another Actor (identification, cedula, id keys are recognized). Dashes and spaces are ignored.
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 the registry rate-limits the datacenter IP.

Accepted number formats:

Format	Digits	identificationType	entityType
Cédula física	9	cedula_fisica	natural_person
Cédula jurídica	10, starts with 3	cedula_juridica	company (with juridicalClass, e.g. sociedad_anonima, sociedad_responsabilidad_limitada, fundacion, asociacion)
NITE	10, starts with 5	nite	natural_person
DIMEX	11–12	dimex	natural_person

Simplest possible run:

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

Social-security arrears (CCSS)

Every record now also carries what the Caja Costarricense de Seguro Social publishes about unpaid employer contributions. The CCSS reports, under article 74 of its constitutive act, the ten largest debtors per economic sector — 174 employers in total — with the amount owed in Costa Rican colón, the sector and the stage of collection. The Actor loads that report once per run and matches it against every cédula you look up:

Field	Meaning
onCcssTopDebtorList	The employer appears on the CCSS list of largest debtors.
ccssDebtCrc	Contributions owed, in colón, as published by the CCSS.
ccssEconomicDivision	Sector the CCSS lists the employer under.
ccssCollectionStatus	Stage of collection, e.g. Cobro Administrativo.
ccssListedName	Name as spelled on the CCSS list — it can differ from the name at Hacienda.
ccssListSourceUrl	The CCSS page the list is published on.

Why it is worth having: unpaid social-security contributions are one of the earliest signs that a Costa Rican company is in trouble, they are published by the authority itself, and they do not appear in a credit report. The largest entries run into hundreds of millions of colón.

Two honest limits. First, this is the largest debtors per sector, not the full debtor register — the CCSS does not publish that. A false therefore means "not among the largest", not "owes nothing". Second, the CCSS service answers Costa Rican IP addresses only and drops every other connection; the Actor routes this one request through an Apify residential proxy in Costa Rica, so you need no VPN of your own. Set ccssProxyCountry to empty to switch that off, or checkCcssDebtorList to false to skip the list entirely and save the ten to twenty seconds it takes to load.

The per-employer enquiry on the same CCSS site is protected by a captcha. We do not automate that, and we do not offer it: a captcha bypass would break the moment the authority changes it, and a compliance data product cannot rest on that.

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; Spanish status values are mapped to registered / not_registered / deregistered, with the original kept in statusOriginal.
• Run summary counts (found, not found, invalid, failed, flagged) are stored in the key-value store under STATS.
• Export as CSV, Excel, JSON or XML, or pull the dataset from the API.

Pricing

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

Event	Price	When
Taxpayer record returned	$0.014	Once per identification number Hacienda actually returned, including legal name, status, regime, activities and the delinquency and non-filer 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. Platform compute is included in the event price. There is no minimum spend and no subscription.

A worked example: 500 Costa Rican companies — 500 × $0.014 = $7.00.

For comparison, the manual alternative is opening the Hacienda portal and transcribing fields, one taxpayer at a time — two to four minutes each. At 500 companies that is roughly a full working day.

Notes on the source

Data comes from the Ministerio de Hacienda's public taxpayer consultation service (the same endpoint behind the electronic-invoicing lookup). This Actor does not bypass any access control, does not authenticate, and does not solve captchas — it reads an endpoint the authority serves openly and passes the values through unchanged. Cédulas físicas, NITE and DIMEX identify natural persons, so treat those records as personal data under your own GDPR / Ley 8968 obligations.

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

Roadmap

Same schema, more countries — Ecuador and Panama are already available, El Salvador, Honduras, Paraguay and Uruguay are next — plus a single cross-border lookup Actor so one call covers a whole region. Guatemala is not on the list: its registry sits behind a captcha and we do not work around access controls.

FAQ

How do I look up a cédula jurídica in Costa Rica?

The Ministerio de Hacienda publishes its taxpayer registry as an open consultation service. This Actor queries it for you and hands back structured JSON, CSV or Excel instead of a web page you have to read by hand — one row per number, in bulk.

What is a cédula jurídica?

Costa Rica's 10-digit identifier for legal entities. It always starts with 3; digits 2–4 encode the legal form (101 sociedad anónima, 102 sociedad de responsabilidad limitada, 109 fundación, and so on), which the Actor exposes as juridicalClass.

Can I look up natural persons too?

Yes. A 9-digit cédula física, a 10-digit NITE starting with 5, or an 11–12-digit DIMEX (foreign residents) all work as input. Remember these are personal data.

What do moroso and omiso mean?

Moroso is a taxpayer that owes taxes; omiso is one that failed to file required returns. Both are official Hacienda designations and are returned as isTaxDelinquent and isNonFiler. These two fields are why most buyers use this Actor rather than a generic company-data source.

Can I check whether a Costa Rican company is registered and may invoice?

Yes — status maps the registry's Spanish value to registered, not_registered or deregistered, and canIssueElectronicInvoice derives from it.

Is scraping the Hacienda registry legal?

This Actor reads a public government service. It does not authenticate, does not bypass access controls and does not solve captchas. Records of natural persons are personal data under your own GDPR / 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's SRI registry, including the contribuyente fantasma flag and legal representatives.
• Panama RUC Scraper — Panama's DGI e-invoicing registry, plus the official tax-delinquent list and Registro Público folio status (suspended / dissolved / merged).
• LATAM Company Registry Scraper — one call for a mixed list of Ecuadorian RUCs and Costa Rican cédulas, returning a single shared schema.