{
  "openapi": "3.1.1",
  "info": {
    "description": "Public Dominican taxpayer facts backed by the latest official DGII directory and a bounded DGII web-form fallback.",
    "title": "Indexa Taxpayers API",
    "version": "1.0.0"
  },
  "components": {
    "schemas": {}
  },
  "paths": {
    "/v1/taxpayers/search": {
      "get": {
        "operationId": "searchTaxpayers",
        "summary": "Find taxpayers by name, RNC, or cédula",
        "tags": [
          "Taxpayers"
        ],
        "description": "One query finds taxpayers. A value that is 9 or 11 digits, ignoring spaces and hyphens, is an RNC or cédula and returns that taxpayer or an empty list from the current publication, last-known directory rows, and saved web discoveries. It does not call the DGII web form; GET /v1/taxpayers/{taxId} does. Any other value searches aggregated registered and commercial names in the current publication and saved web discoveries without case or accent sensitivity. limit applies only to names. No matches does not establish non-registration.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 2048
            },
            "in": "query",
            "name": "q",
            "required": true,
            "description": "A name, a 9-digit RNC, or an 11-digit cédula. Spaces and hyphens are ignored for identifiers. Names use 3–120 normalized characters, including three consecutive letters or digits."
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            },
            "in": "query",
            "name": "limit",
            "required": false,
            "description": "Maximum name matches. Ignored when q is an RNC or cédula."
          }
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "taxpayers"
                  ],
                  "properties": {
                    "taxpayers": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "taxId",
                          "registeredName",
                          "commercialName"
                        ],
                        "properties": {
                          "taxId": {
                            "type": "string",
                            "pattern": "^(?:[0-9]{9}|[0-9]{11})$"
                          },
                          "registeredName": {
                            "type": "string",
                            "minLength": 1
                          },
                          "commercialName": {
                            "anyOf": [
                              {
                                "type": "string",
                                "minLength": 1
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "additionalProperties": false
                      }
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "search_invalid"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1
                        },
                        "requestId": {
                          "type": "string",
                          "minLength": 1
                        }
                      },
                      "additionalProperties": false
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "503": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "search_unavailable"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1
                        },
                        "requestId": {
                          "type": "string",
                          "minLength": 1
                        }
                      },
                      "additionalProperties": false
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/v1/taxpayers/{taxId}": {
      "get": {
        "operationId": "getTaxpayer",
        "summary": "Look up a taxpayer",
        "tags": [
          "Taxpayers"
        ],
        "description": "Returns taxpayer identity and available DGII facts: category, electronic-invoicer status, economic activity, operations start date, payment regime, DGII status, and classification in DGII’s local and medium taxpayer electronic-invoicing implementation list. Classification null means unavailable or not listed; it does not establish whether the taxpayer is large. Classification is separate from category and MICM certification. Fields are aggregated by exact identifier from the directory and saved DGII web observations. Missing source values and failed refreshes do not erase available facts. Other unavailable facts are null.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "pattern": "^(?:[0-9]{9}|[0-9]{11})$"
            },
            "in": "path",
            "name": "taxId",
            "required": true
          }
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "taxpayer"
                  ],
                  "properties": {
                    "taxpayer": {
                      "type": "object",
                      "required": [
                        "taxId",
                        "kind",
                        "registeredName",
                        "commercialName",
                        "registrationStatus",
                        "checksumStatus",
                        "category",
                        "isElectronicInvoicer",
                        "economicActivity",
                        "operationsStartedOn",
                        "paymentRegime",
                        "dgiiStatus",
                        "classification"
                      ],
                      "properties": {
                        "taxId": {
                          "type": "string",
                          "pattern": "^(?:[0-9]{9}|[0-9]{11})$"
                        },
                        "kind": {
                          "anyOf": [
                            {
                              "type": "string",
                              "enum": [
                                "rnc"
                              ]
                            },
                            {
                              "type": "string",
                              "enum": [
                                "cedula"
                              ]
                            }
                          ]
                        },
                        "registeredName": {
                          "type": "string",
                          "minLength": 1
                        },
                        "commercialName": {
                          "anyOf": [
                            {
                              "type": "string",
                              "minLength": 1
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "registrationStatus": {
                          "anyOf": [
                            {
                              "type": "string",
                              "enum": [
                                "active"
                              ]
                            },
                            {
                              "type": "string",
                              "enum": [
                                "inactive"
                              ]
                            }
                          ]
                        },
                        "checksumStatus": {
                          "anyOf": [
                            {
                              "type": "string",
                              "enum": [
                                "checksum_valid"
                              ]
                            },
                            {
                              "type": "string",
                              "enum": [
                                "issued_exception"
                              ]
                            }
                          ]
                        },
                        "category": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "DGII category as published; not a legal form or company-size classification."
                        },
                        "isElectronicInvoicer": {
                          "anyOf": [
                            {
                              "type": "boolean"
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "DGII electronic-invoicer flag. Null means unknown, not false."
                        },
                        "economicActivity": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "operationsStartedOn": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "date"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "paymentRegime": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "dgiiStatus": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "classification": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "Classification in DGII’s local and medium taxpayer electronic-invoicing implementation list. Null means unavailable or not listed; it does not establish whether the taxpayer is large. Separate from category and MICM certification."
                        }
                      },
                      "additionalProperties": false
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "tax_id_invalid"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1
                        },
                        "requestId": {
                          "type": "string",
                          "minLength": 1
                        }
                      },
                      "additionalProperties": false
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "taxpayer_not_found"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1
                        },
                        "requestId": {
                          "type": "string",
                          "minLength": 1
                        }
                      },
                      "additionalProperties": false
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "500": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "internal_error"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "minLength": 1
                        },
                        "requestId": {
                          "type": "string",
                          "minLength": 1
                        }
                      },
                      "additionalProperties": false
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "503": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "type": "object",
                      "required": [
                        "error"
                      ],
                      "properties": {
                        "error": {
                          "type": "object",
                          "required": [
                            "code",
                            "message",
                            "requestId"
                          ],
                          "properties": {
                            "code": {
                              "type": "string",
                              "enum": [
                                "directory_not_ready"
                              ]
                            },
                            "message": {
                              "type": "string",
                              "minLength": 1
                            },
                            "requestId": {
                              "type": "string",
                              "minLength": 1
                            }
                          },
                          "additionalProperties": false
                        }
                      },
                      "additionalProperties": false
                    },
                    {
                      "type": "object",
                      "required": [
                        "error"
                      ],
                      "properties": {
                        "error": {
                          "type": "object",
                          "required": [
                            "code",
                            "message",
                            "requestId"
                          ],
                          "properties": {
                            "code": {
                              "type": "string",
                              "enum": [
                                "authority_lookup_unavailable"
                              ]
                            },
                            "message": {
                              "type": "string",
                              "minLength": 1
                            },
                            "requestId": {
                              "type": "string",
                              "minLength": 1
                            }
                          },
                          "additionalProperties": false
                        }
                      },
                      "additionalProperties": false
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "description": "Canonical lookup against the latest official DGII directory with a DGII web-form fallback on misses.",
      "name": "Taxpayers"
    }
  ],
  "servers": [
    {
      "url": "/"
    }
  ]
}