Find a taxpayer

Enter a 9-digit RNC or 11-digit Cédula. If you do not know the number, search by registered or commercial name and choose a suggestion.

Understand the result

Name search returns taxpayers with only three fields: taxId, registeredName and commercialName. Select a match or enter an exact identifier to get taxpayer, which contains 13 flat fields: six identity fields and seven additional DGII facts. The search suggestions do not include registration or profile status.

Field	Meaning
`taxId`	RNC or Cédula. Keep it as a string so leading zeroes are preserved.
`kind`	`rnc` or `cedula`.
`registeredName`	Registered name from the available DGII observations.
`commercialName`	Public-facing business name, or `null` when unknown or unavailable.
`registrationStatus`	`active` or `inactive` in the current observation.
`checksumStatus`	Identifier validation classification; it does not prove registration or tax compliance.
`category`	DGII category, or `null`; it is not a legal form or company-size classification.
`classification`	DGII classification from its local and medium taxpayer electronic-invoicing implementation list, or `null`.
`isElectronicInvoicer`	`true`, `false` or `null`, based on the DGII web form.
`economicActivity`	DGII activity description, or `null`.
`operationsStartedOn`	Operations start date (`YYYY-MM-DD`), or `null`.
`paymentRegime`	Source regime label such as `NORMAL`, `RST` or `PST`, or `null`.
`dgiiStatus`	Exact DGII status label, or `null`.

null means unknown or unavailable. In particular, isElectronicInvoicer: null does not mean false. The API maps the source values SI/SÍ to true and NO to false; it leaves unrecognized values as null. Regime, category and DGII status remain source strings. A result does not confirm current tax compliance. The directory covers taxpayers published by the DGII, not every citizen, and does not support bulk export.

DGII classification preserves labels from its local and medium taxpayer electronic-invoicing implementation list, such as Grande Local and Mediana; it is separate from category and MICM certification. The Grandes Contribuyentes Nacionales list is not included. classification: null means no usable result was available from this source; it does not establish whether the taxpayer is large. The API does not infer this field from tax ID digits.

The detail response combines available DGII information using the RNC or cédula as the shared identifier. A missing value in one source does not erase a value available in another; for example, an operations start date from the directory remains available when the web form omits it. Returned facts can be last known observations and do not confirm current tax compliance.

Taxpayers found through an exact web lookup are saved and become available to name and identifier search. Search reads stored information without submitting the DGII form. Later detail requests may refresh the information, but a temporary DGII failure preserves the last known facts. A confirmed not-registered response is handled separately from a failed request.

Use taxpayer lookup in your app

For an exact lookup, send digits only:

const apiOrigin = '__API_ORIGIN__';
const taxId = '101850043';
const response = await fetch(`${apiOrigin}/v1/taxpayers/${encodeURIComponent(taxId)}`);
if (!response.ok) throw new Error(`Taxpayer lookup failed: ${response.status}`);
const { taxpayer } = await response.json();

To find suggestions by name, request up to ten matches, then confirm the selected identifier with the exact lookup above:

const apiOrigin = '__API_ORIGIN__';
const query = new URLSearchParams({ q: 'ferreteria', limit: '10' });
const response = await fetch(`${apiOrigin}/v1/taxpayers/search?${query}`);
if (!response.ok) throw new Error(`Taxpayer search failed: ${response.status}`);
const { taxpayers } = await response.json();

Name search ignores case and accents, collapses repeated whitespace, and treats punctuation such as % and _ literally. Use 3–120 normalized characters with at least three consecutive letters or digits. Exact matches appear before prefixes and substrings. Results are not paginated; refine the name to narrow the list.

The full lookup can add web facts to a directory record without replacing its identity or original profile fields. A failed or budget-limited enrichment leaves additional facts unknown and preserves the usable directory answer. A complete web fallback does not supply an operations start date. Keep these details out of autocomplete suggestions.

The public response contains taxpayer facts, not import or retrieval metadata. The API does not currently have an authoritative date for when DGII last updated this taxpayer's record, so it does not return updatedAt. A source publication date or the time we retrieved the record would not establish that date.

Handle no match, unavailable data, and caching

Do not turn every failed request into “taxpayer not registered.” A 404 exact lookup means the identifier was not found under the service's current source policy. An empty name search does not establish non-registration because an exact lookup may still find the taxpayer through a fallback source.

HTTP 400 means the input needs correction. HTTP 503 means no usable answer is available; an older observation alone does not cause an error. Keep the user's input and offer a retry. If you receive 429, slow down and respect Retry-After when present.

Follow the response cache headers; successful responses can be cached for up to 60 seconds. Do not cache errors.

Understand freshness and DGII fallback

Exact lookup can return current or last-known directory records and use the bounded DGII web fallback. An older publication does not by itself hide an available record. When a newer publication omits a taxpayer, the last-known record remains available; omission does not establish suspension or non-registration.

Publication dates, retrieval times, hashes and freshness metadata remain in the internal APIs. Name search uses the current publication. An identifier sent to /v1/taxpayers/search can also read last-known records. Neither search mode calls the DGII form.

The response is not a DGII certification. Read data quality and limits or the directory contract when you need the complete source and freshness rules.

MICM certification for authenticated services

MICM certification is not part of the public profile and is not available through this gateway. Services with an allowlisted Vercel OIDC identity can call the Taxpayer Directory directly at https://taxpayer-directory-api.vercel.app:

GET /internal/v1/taxpayers/{taxId}/profile includes nullable mipymeCertification.
GET /internal/v1/taxpayers/{taxId}/mipyme-certification returns { "certification": ... }, independently of whether DGII has an identity record.

Each certificate contains companyName, nullable activity and classification, issuedOn, validUntil, and its own publishedAt. Issue and expiry dates use YYYY-MM-DD; publication time is a timestamp. Interpret these dates separately from DGII observation dates. A uniquely determined expired certificate can still be returned, and an older publication does not by itself hide the certificate.

A null certificate means no reliable single record was available: the source may be unavailable, the taxpayer absent, the records conflicting, or the validity dates uncertain. It does not establish that the company is uncertified. These facts do not determine company size, tax treatment or commercial eligibility on their own. Hashes and import diagnostics remain internal. Keep caller credentials on the server.

Explore the taxpayers API →