Quickstart

Three steps to your first RUC lookup.

1. Get an API key

Sign up and create a key in your account. It starts with sk_ and is shown only once: store it somewhere safe. The Free plan needs no card.

The key goes in the Authorization header, as a Bearer token:

Authorization: Bearer sk_your_key

2. Make the request

Replace 20100000008 with the RUC you want to look up (11 digits). That number is a fictional example.

curl

curl https://consultaruc-api.karvesol.com/ruc/20100000008 \
  -H "Authorization: Bearer sk_your_key"

JavaScript

const res = await fetch('https://consultaruc-api.karvesol.com/ruc/20100000008', {
  headers: { Authorization: 'Bearer sk_your_key' },
});
if (!res.ok) throw new Error((await res.json()).error);
const company = await res.json();
console.log(company.razon_social);

Python

import requests

res = requests.get(
    "https://consultaruc-api.karvesol.com/ruc/20100000008",
    headers={"Authorization": "Bearer sk_your_key"},
    timeout=10,
)
res.raise_for_status()
print(res.json()["razon_social"])

3. Read the response

If the RUC exists, the API returns 200 with JSON like this (example 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
}

Every field is explained in the GET /ruc/{id} reference. If something fails, see errors and limits.