# 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.

| Field | Meaning |
| --- | --- |
| `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 source status, or null |
| `category` | DGII web category, or null; this is not a legal form or company-size classification |
| `classification` | `Grande Local` or `Mediana` as published in DGII's local and medium taxpayer electronic-invoicing implementation list, or null |
| `isElectronicInvoicer` | Web flag normalized from `SI`/`SÍ` to true and `NO` to false; other or absent values are null |

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](https://dgii.gov.do/app/WebApps/Misc/VerLista/?doc=GCL-240110). 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](../OPERATIONS.md#dgii-local-and-medium-taxpayer-classifications).

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](../OPERATIONS.md#micm-mipyme-certifications).

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.