Look up a RUC: GET /ruc/{id}

Returns the SUNAT reduced registry data for one RUC. Each lookup costs 1 credit.

GET https://consultaruc-api.karvesol.com/ruc/{id}

Authentication

Header Authorization: Bearer <api_key>. Without a valid key the API returns 401.

Parameter

Name	In	Description
`id`	path	11-digit RUC, digits only.

`200` response

A JSON object with these fields:

Field	Type	Description
`ruc`	number	The RUC you looked up.
`razon_social`	string or `null`	Legal name of the taxpayer.
`estado`	string or `null`	Taxpayer status according to SUNAT (for example `ACTIVO`, `BAJA DEFINITIVA`, `SUSPENSION TEMPORAL`).
`condicion`	string or `null`	Address condition according to SUNAT (for example `HABIDO`, `NO HABIDO`).
`direccion`	string or `null`	Registered address.
`ubigeo`	string or `null`	6-digit ubigeo code.
`distrito`	string or `null`	District of the registered address.
`provincia`	string or `null`	Province of the registered address.
`departamento`	string or `null`	Department of the registered address.
`es_agente_retencion`	boolean	`true` if the RUC is listed as an IGV withholding agent.

Keep in mind:

Data is returned as SUNAT publishes it. Some estado and condicion texts are abbreviated or truncated at the source (for example NO HALLADO SE MUDO D) and are not completed.
direccion, ubigeo, distrito, provincia and departamento only come for RUCs starting with 20 (companies). For other RUCs they are null, because SUNAT does not publish them.
A field with no data comes as null.

Example (fictional data)

{
  "ruc": 20100000008,
  "razon_social": "EMPRESA DE EJEMPLO S.A.C.",
  "estado": "ACTIVO",
  "condicion": "HABIDO",
  "direccion": "AV. EJEMPLO 123",
  "ubigeo": "150101",
  "distrito": "LIMA",
  "provincia": "LIMA",
  "departamento": "LIMA",
  "es_agente_retencion": false
}

Status codes

Code	When	Body
`200`	The RUC exists.	The JSON above.
`400`	`id` is not 11 digits or not numeric.	`{"error": "…"}`
`401`	Missing or invalid key.	`{"error": "no autorizado"}`
`404`	The RUC is not in the registry.	`{"error": "RUC no encontrado"}`
`429`	You exceeded the per-minute limit or the Free plan quota.	`{"error": "…"}` and a `Retry-After` header
`503`	The registry is briefly unavailable.	`{"error": "padrón no disponible"}`