--- title: "Contacts API" description: "v1 endpoints for customers and suppliers: tax identification, location and default withholding flags." canonical: https://factura.com.do/en/desarrolladores/contactos lang: en generator: factura.com.do docs-index --- Resource · Customers and suppliers # Contacts API Two symmetric slices: `/customers` and `/suppliers`. They share the same request body shape and the same verbs (list, get, create, update, delete). The difference is which document type the contact is associated with: customers in E31/E32, suppliers in E41. ## Overview A contact (customer or supplier) lives in the workspace and is reused in every document. The body is symmetric for both slices: `identificationTypeId`, `taxIdentification`, `legalName`, `phone`, `email`, `address` plus location fields (`countryId`, `provinceId?`, `municipalityId?`). The handler does not query the DGII registry on save; the live checks are listed below. The difference between `customers` and `suppliers`: for customers, `taxIdentification` is required and uniqueness is validated per workspace (rejects duplicates with `{ success: false, message: "Un cliente con esta identificación ya existe en el sistema" }`); for suppliers, `taxIdentification` is optional, uniqueness is not validated, and the `isRegisteredInDGII` flag later decides whether the supplier enters the E41 flow (informal) or whether your system should wait for an E31 they issue themselves. ## Customers Customers are associated with sales documents (E31, E32, E33, E34). When issuing a document the invoice handler re-validates that the referenced customer is active (`customer.IsActive`); if inactive it responds `400` with `El cliente está inactivo y no puede ser utilizado en documentos.` [ GET /api/v1/customers X-Api-Key Stable Devuelve un PagedResult de clientes registrados en el espacio de trabajo. ](#) | Name | Type | Description | | ---------------- | ---------------- | ---------------------------------------------------------------------- | | pageNumber query | integer Optional | Página solicitada. Por defecto 1. | | pageSize query | integer Optional | Tamaño de página. Por defecto 10\. La API no impone un máximo. | | search query | string Optional | Filtra por RNC, nombre o correo del cliente. | | isActive query | boolean Optional | Filtra por estado del cliente. Sin valor devuelve activos e inactivos. | [ GET /api/v1/customers/{id} X-Api-Key Stable Devuelve el detalle completo de un cliente. ](#) | Name | Type | Description | | ------- | ---------------------- | -------------------------- | | id path | string (uuid) Required | Identificador del cliente. | [ POST /api/v1/customers X-Api-Key Stable Registra un cliente en el espacio de trabajo. ](#) | Name | Type | Description | | -------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | identificationTypeId body | integer Required | Tipo de identificación tributaria (RNC, cédula, pasaporte, etc.) según el catálogo. | | taxIdentification body | string Required | Número de identificación tributaria (RNC o cédula). La API no lo consulta en la DGII; si quieres verificarlo, usa antes \`GET /api/v1/rnc/{rnc}\`. Rechaza un número que ya exista en otro cliente. | | countryId body | integer Required | Identificador del país del cliente. | | provinceId body | integer Optional | Identificador de la provincia del cliente. | | municipalityId body | integer Optional | Identificador del municipio del cliente. | | legalName body | string Required | Razón social o nombre legal del cliente. | | phone body | string Required | Teléfono de contacto del cliente. | | email body | string Required | Correo del cliente para envío de comprobantes. | | address body | string Required | Dirección física del cliente. | | defaultSecuenceTypeId body | integer Optional | Tipo de NCF por defecto a usar cuando se emite un comprobante a este cliente. | | isRegisteredInDGII body | boolean Optional | Marca si el cliente está formalmente inscrito en la DGII. | | withholdings body | string\[\] (uuid) Optional | Retenciones por defecto aplicables a este cliente. | [ PUT /api/v1/customers/{id} X-Api-Key Stable Modifica los datos de un cliente existente. ](#) | Name | Type | Description | | -------------------------- | -------------------------- | ------------------------------------------------------------------------------------- | | id path | string (uuid) Required | Identificador del cliente. | | identificationTypeId body | integer Required | Tipo de identificación tributaria. | | taxIdentification body | string Required | Número de identificación tributaria (RNC o cédula). La API no lo consulta en la DGII. | | countryId body | integer Required | Identificador del país del cliente. | | provinceId body | integer Optional | Identificador de la provincia del cliente. | | municipalityId body | integer Optional | Identificador del municipio del cliente. | | legalName body | string Required | Razón social o nombre legal del cliente. | | phone body | string Required | Teléfono de contacto del cliente. | | email body | string Required | Correo del cliente. | | address body | string Required | Dirección física del cliente. | | defaultSecuenceTypeId body | integer Optional | Tipo de NCF por defecto para este cliente. | | isRegisteredInDGII body | boolean Optional | Marca si el cliente está formalmente inscrito en la DGII. | | withholdings body | string\[\] (uuid) Optional | Retenciones por defecto aplicables a este cliente. | [ DELETE /api/v1/customers/{id} X-Api-Key Stable Marca un cliente como eliminado (soft-delete) sin afectar comprobantes históricos. ](#) | Name | Type | Description | | ------- | ---------------------- | -------------------------- | | id path | string (uuid) Required | Identificador del cliente. | ### Example: create a customer with RNC POST /api/v1/customers cURL TypeScript create-customer.sh ``` curl -X POST https://tuempresa.factura.com.do/api/v1/customers \ -H "X-Api-Key: $FACTURA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "identificationTypeId": 1, "taxIdentification": "131000001", "countryId": 214, "provinceId": 1, "municipalityId": 1, "legalName": "Empresa Receptora SRL", "phone": "+1-809-555-0100", "email": "facturas@empresa-receptora.do", "address": "Av. 27 de Febrero 100, Santo Domingo" }' ``` create-customer.ts ``` const res = await fetch( "https://tuempresa.factura.com.do/api/v1/customers", { method: "POST", headers: { "X-Api-Key": process.env.FACTURA_API_KEY!, "Content-Type": "application/json", }, body: JSON.stringify({ identificationTypeId: 1, taxIdentification: "131000001", countryId: 214, legalName: "Empresa Receptora SRL", phone: "+1-809-555-0100", email: "facturas@empresa-receptora.do", address: "Av. 27 de Febrero 100, Santo Domingo", }), }, ); if (!res.ok) throw new Error(`factura.com.do: ${res.status}`); const { customerId, success, message } = await res.json(); ``` Response response.json ``` { "customerId": "5f0c3a8e-2b7d-4c1e-9a6f-3d8b2e1c7a40", "success": true, "message": "The customer has been successfully saved" } ``` ### Example: duplicate tax identification The customer slice verifies uniqueness of `taxIdentification` within the workspace; if another customer already has the same value it responds with `200 OK` and `success: false` (same pattern as void). Always read `success` before assuming a successful create. 200-tax-identification-duplicate.json ``` { "customerId": "00000000-0000-0000-0000-000000000000", "success": false, "message": "Un cliente con esta identificación ya existe en el sistema" } ``` ## Suppliers Suppliers are associated with purchase documents (E41). `taxIdentification` is optional in the DTO; what controls the flow is the `isRegisteredInDGII` flag: when `false` the supplier is considered informal and the API lets you issue an E41 on their behalf; when `true` the handler blocks E41 (that supplier must issue their own E31). For disbursements with no identifiable supplier, use the minor expense flow (E43). [ GET /api/v1/suppliers X-Api-Key Stable Devuelve un PagedResult de proveedores registrados en el espacio de trabajo. ](#) | Name | Type | Description | | ---------------- | ---------------- | ------------------------------------------------------------------------ | | pageNumber query | integer Optional | Página solicitada. Por defecto 1. | | pageSize query | integer Optional | Tamaño de página. Por defecto 10\. La API no impone un máximo. | | search query | string Optional | Filtra por RNC, nombre o correo del proveedor. | | isActive query | boolean Optional | Filtra por estado del proveedor. Sin valor devuelve activos e inactivos. | [ GET /api/v1/suppliers/{id} X-Api-Key Stable Devuelve el detalle completo de un proveedor. ](#) | Name | Type | Description | | ------- | ---------------------- | ---------------------------- | | id path | string (uuid) Required | Identificador del proveedor. | [ POST /api/v1/suppliers X-Api-Key Stable Registra un proveedor en el espacio de trabajo. ](#) | Name | Type | Description | | -------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | identificationTypeId body | integer Required | Tipo de identificación tributaria del proveedor (RNC, cédula, etc.). | | taxIdentification body | string Optional | Número de identificación tributaria (RNC o cédula). La API no lo consulta en la DGII; si quieres verificarlo, usa antes \`GET /api/v1/rnc/{rnc}\`. | | countryId body | integer Required | Identificador del país del proveedor. | | provinceId body | integer Optional | Identificador de la provincia del proveedor. | | municipalityId body | integer Optional | Identificador del municipio del proveedor. | | legalName body | string Required | Razón social o nombre legal del proveedor. | | phone body | string Required | Teléfono de contacto del proveedor. | | email body | string Required | Correo del proveedor. | | address body | string Required | Dirección física del proveedor. | | defaultSecuenceTypeId body | integer Optional | Tipo de NCF por defecto a usar al registrar una compra a este proveedor. | | isRegisteredInDGII body | boolean Optional | Marca si el proveedor está formalmente inscrito en la DGII. | | withholdings body | string\[\] (uuid) Optional | Retenciones por defecto aplicables a este proveedor. | [ PUT /api/v1/suppliers/{id} X-Api-Key Stable Modifica los datos de un proveedor existente. ](#) | Name | Type | Description | | -------------------------- | -------------------------- | ------------------------------------------------------------------------------------- | | id path | string (uuid) Required | Identificador del proveedor. | | identificationTypeId body | integer Required | Tipo de identificación tributaria. | | taxIdentification body | string Optional | Número de identificación tributaria (RNC o cédula). La API no lo consulta en la DGII. | | countryId body | integer Required | Identificador del país del proveedor. | | provinceId body | integer Optional | Identificador de la provincia del proveedor. | | municipalityId body | integer Optional | Identificador del municipio del proveedor. | | legalName body | string Required | Razón social o nombre legal del proveedor. | | phone body | string Required | Teléfono de contacto del proveedor. | | email body | string Required | Correo del proveedor. | | address body | string Required | Dirección física del proveedor. | | defaultSecuenceTypeId body | integer Optional | Tipo de NCF por defecto para este proveedor. | | isRegisteredInDGII body | boolean Optional | Marca si el proveedor está formalmente inscrito en la DGII. | | withholdings body | string\[\] (uuid) Optional | Retenciones por defecto aplicables a este proveedor. | [ DELETE /api/v1/suppliers/{id} X-Api-Key Stable Marca un proveedor como eliminado (soft-delete) sin afectar comprobantes históricos. ](#) | Name | Type | Description | | ------- | ---------------------- | ---------------------------- | | id path | string (uuid) Required | Identificador del proveedor. | ### Example: create a supplier create-supplier.sh ``` curl -X POST https://tuempresa.factura.com.do/api/v1/suppliers \ -H "X-Api-Key: $FACTURA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "identificationTypeId": 1, "taxIdentification": "131000002", "countryId": 214, "legalName": "Insumos Generales SRL", "phone": "+1-809-555-0200", "email": "ventas@insumos.do", "address": "Calle Duarte 45, Santiago", "isRegisteredInDGII": true }' ``` ## RNC validation The contacts handler does not query the DGII registry on save; it only verifies uniqueness of `taxIdentification` for customers. If your integration needs to confirm that an RNC exists in the registry before registering it, use the dedicated endpoint `GET /api/v1/rnc/{rnc}` documented in [catalog](/en/desarrolladores/catalogo); that endpoint does hit the registry in real time. Validate first, register after If your integration loads contacts in bulk, call [RNC validation against the registry](/en/desarrolladores/catalogo) first and discard suspended ones before registering them. Save-time validation will not do it for you. ## Next steps Next step ## Continue here - [ Catalog RNC validation, products, taxes and available units. ](/en/desarrolladores/catalogo) - [ Invoices Issue an E31 document to the newly created customer. ](/en/desarrolladores/facturas) - [ Purchases Record E41 documents for the newly created supplier. ](/en/desarrolladores/compras)