# UrbanStock DGII RNC API

> Free, zero-auth REST API and lookup engine for the Dominican Republic DGII National Taxpayer Registry (Padrón Nacional de Contribuyentes — RNC & Cédula), maintained by UrbanStock POS. Automatically synchronized every early morning from official DGII registries with complete legal names (Razón Social), commercial names (Nombre Comercial), economic activity (Actividad Económica), payment regime, start date, tax status (ACTIVO / SUSPENDIDO / DADO DE BAJA), official check digit verification (Módulo 11 / Módulo 10), and NCF / e-CF structural validation.

- Base URL: https://rnc.urbanstockpos.com
- Country / Jurisdiction: Dominican Republic (República Dominicana — DGII)
- Auth: Public access (no API key required for standard lookups; optional `X-API-Key` header for high-volume POS systems)
- CORS: Enabled (`*`) for browser apps, server backends, and AI agents
- Last updated: 2026-11-07 (797,960 taxpayers indexed)
- Machine specs: [OpenAPI 3.1 JSON](https://rnc.urbanstockpos.com/openapi.json) · [AI Plugin Manifest](https://rnc.urbanstockpos.com/.well-known/ai-plugin.json) · [HTML Docs](https://rnc.urbanstockpos.com/docs) · [Sitemap XML](https://rnc.urbanstockpos.com/sitemap.xml)

## Public Endpoints (Ready for AI Agents & Applications)

- `GET https://rnc.urbanstockpos.com/api/v1/rnc/{rnc}`: Exact lookup by 9-digit RNC (e.g. `1-XX-XXXXX-X` or `1XXXXXXXX`) or 11-digit Cédula (e.g. `001-XXXXXXX-X`), with or without hyphens. Includes official check digit verification (`MOD11_DGII` / `MOD10_JCE`).
- `GET https://rnc.urbanstockpos.com/api/v1/search?q={name}&estado=ACTIVO&limit=15`: Accent-insensitive fuzzy partial search by legal name (Razón Social) or commercial name (Nombre Comercial). Minimum 3 characters with at least one 3+ letter word. Optional `estado`: `ACTIVO`, `SUSPENDIDO`, `DADO DE BAJA`, `CESE TEMPORAL`, `ANULADO`, `RECHAZADO`. Max `limit`: 25.
- `POST https://rnc.urbanstockpos.com/api/v1/rnc/batch`: Bulk lookup of up to 50 RNC/Cédula values in one JSON body `{"rncs": ["..."]}` (also accepts `GET https://rnc.urbanstockpos.com/api/v1/rnc/batch?rncs=00000000000,000000000`). Returns `checkDigits` diagnostics alongside taxpayer records.
- `POST https://rnc.urbanstockpos.com/api/v1/validate/ncf` (and `GET https://rnc.urbanstockpos.com/api/v1/validate/ncf?ncf=...&rncEmisor=...`): Validates Dominican fiscal receipt structure (Serie B `B01–B17` and electronic e-CF `E31–E47`), fiscal credit eligibility (ITBIS / Formato 606), official e-CF QR URLs (`ecf.dgii.gov.do` / `fc.dgii.gov.do`), and cross-checks Emitter/Buyer RNC status against the DGII catalog.
- `GET https://rnc.urbanstockpos.com/api/v1/meta` and `GET https://rnc.urbanstockpos.com/health`: Current DGII update date, taxpayer counts, and service availability.

## Non-Real Sandbox Test Examples (Safe Dummy Data)

For connectivity tests or demonstrations without querying real individuals or businesses, this API reserves synthetic test identifiers that return `isTestExample: true`, `isActive: false`, and `estado: "PRUEBA (TEST)"`:

- Test RNC (9 digits): `GET https://rnc.urbanstockpos.com/api/v1/rnc/000000000` (or `0-00-00000-0`)
- Test Cédula (11 digits): `GET https://rnc.urbanstockpos.com/api/v1/rnc/00000000000` (or `000-0000000-0`)
- Test Company Search: `GET https://rnc.urbanstockpos.com/api/v1/search?q=EMPRESA%20DE%20PRUEBA`
- Test Batch: `POST https://rnc.urbanstockpos.com/api/v1/rnc/batch` with `{"rncs":["00000000000","000000000"]}` or `GET https://rnc.urbanstockpos.com/api/v1/rnc/batch?rncs=00000000000,000000000`
- Test NCF / e-CF Validation: `POST https://rnc.urbanstockpos.com/api/v1/validate/ncf` with `{"ncf":"E310000000001","rncEmisor":"000000000"}`

*Note for POS / Fiscal Software:* Always verify `data.isActive === true` before issuing NCF / e-CF fiscal credit receipts (B01 / E31). Synthetic test examples always return `isActive: false`.