Taxpayer directory notes

The public API has two operations. GET /v1/taxpayers/search?q=... returns { taxpayers }, with only taxId, registeredName and commercialName per suggestion. Select a result and call GET /v1/taxpayers/{taxId} to receive { taxpayer }: one object containing its six identity fields and these additional facts. A known identifier can be looked up directly.

Null means unknown or unavailable; an unknown electronic-invoicer flag must not be treated as false. Detail lookup combines the imported directory and successful DGII web observations by exact RNC or cédula. A web observation at least as recent as the directory publication supplies non-null overlapping values; an older web observation only fills missing values. Missing web values do not erase directory facts. In particular, operationsStartedOn remains available from the directory because the web form does not provide it. Classification is joined separately by the same identifier.

Successful web discoveries are saved independently of refresh attempts and remain usable after the refresh cache expires. A timeout, unavailable form, or exhausted lookup budget preserves the last known facts. An explicit DGII not-registered result is recorded separately and suppresses a web-only discovery; it does not erase its previous successful observation or turn an existing directory record into an inferred inactive taxpayer. Missing from a downloaded publication alone does not mean suspended, inactive or unregistered. Returned facts may be last known observations and do not establish current compliance.

The public API omits publication dates, retrieval timestamps, hashes and freshness metadata. It does not currently have an authoritative taxpayer-level last-updated date, so it does not expose updatedAt or infer one from those internal timestamps. Domain dates such as operationsStartedOn remain part of the profile.

DGII taxpayer classification

The public detail field classification comes from the explicit Clasificación column in DGII's local and medium taxpayer implementation list. Records match by exact RNC or cédula, preserving leading zeroes. The label describes the taxpayer's classification in that list; it is not inferred from the identifier, company name, or MICM certification. The existing category field continues to carry the separate Consulta RNC category, such as a free-zone category.

Only the local and medium list supplies this field. The national list is not included. A null value means that the source has not been loaded, no matching record is available, or the classification lookup failed. It does not establish that the taxpayer is small or is not a large taxpayer. The list concerns electronic-invoicing implementation and does not establish a complete current taxpayer-size registry. Its deadline and authorization columns are retained internally and do not override isElectronicInvoicer.

Detail requests read the last successfully imported list from the database; they do not fetch the list from DGII. Failed imports preserve the previous data. Classification adds no work to search and no provenance fields to the public response. The authenticated profile contract remains unchanged. See classification import operations (maintainer-only artifact).

Authenticated services can read the profile, profile.webObservedAt, and existing directory evidence at /internal/v1/taxpayers/{taxId}/profile. That response also contains mipymeCertification, either a concise MICM record or null. Internal search retains { taxpayers, publishedAt }. Authenticated identity and search retain their existing six identity fields; MICM facts require an allowed service caller.

A MICM record has companyName, nullable activity and classification, issuedOn, validUntil, and its own publishedAt. The dates describe the certificate and the independent MICM publication. Expired certificates remain available with their dates. Null means no reliable single certificate is available: the source may be unavailable, the identifier absent, the records conflicting, or validity dates uncertain. It is not evidence that the taxpayer lacks certification. The independent /internal/v1/taxpayers/{taxId}/mipyme-certification endpoint returns { "certification": ... } using the same nullable record, even when DGII has no identity for that identifier. Hashes, raw parser fields, catalog metadata and archival evidence remain internal. See MICM source and operating requirements (maintainer-only artifact).

Name search includes taxpayers in the current publication and saved successful web discoveries, merging matches by identifier. An RNC or cédula on the same query also reads last-known directory rows. Neither search mode calls DGII. Keep the accessible autocomplete and exact lookup after selection; the exact lookup is what may consult the DGII web form. Search suggestions contain only the identifier and names, keeping their payload compact.

The former public /v1/taxpayers/{taxId}/profile endpoint has been removed. Its facts now appear directly under taxpayer in the detail response. The public identifier route no longer returns internal evidence for authenticated callers; services requiring provenance use the explicit internal routes.