API · v1

Referencia de la API

Consulta datos del Perú desde tu servidor o tu agente: empresas (RUC, ficha, planilla, deuda), personas (DNI, licencia, huella completa del Estado), vehículos (placa, SOAT) y más. REST + MCP, JSON, con la fuente de cada dato.

Base URLhttps://quienes.pe/v1

FormatoJSON · { success, data, source }

LlaveCrear en el panel →

Autenticación

Cada solicitud lleva tu llave en el header Authorization. También aceptamos ?key= para pruebas rápidas, pero el header es lo recomendado. La llave descuenta de los créditos de tu cuenta; el plan define el rate-limit.

Authorization: Bearer qn_live_xxxxxxxxxxxxxxxxxxxx

La llave se muestra una sola vez al crearla. Guárdala en una variable de entorno, nunca en el código del cliente.

Límites y errores. Cada respuesta trae X-RateLimit-Remaining. Códigos: 401 llave faltante/ inválida · 400 parámetro mal formado · 402 créditos insuficientes · 429 rate-limit excedido · 502 el motor no respondió (no se cobra).

MCP Para agentes / LLMs

Conecta quienes.pe por MCP y tu agente (Claude, Cursor, tu harness) usa cada consulta como una herramienta. Descubre las 17 tools solo (tools/list) y cada llamada descuenta créditos de tu llave. Mismos créditos y rate-limit que la API REST.

Endpoint MCP

https://quienes.pe/mcp   ·   Authorization: Bearer qn_live_xxx

Conector remoto (config JSON)

{
  "mcpServers": {
    "quienes": {
      "url": "https://quienes.pe/mcp",
      "headers": { "Authorization": "Bearer qn_live_xxx" }
    }
  }
}

O con mcp-remote (clientes stdio)

npx mcp-remote https://quienes.pe/mcp \
  --header "Authorization: Bearer qn_live_xxx"

17 herramientas

quienes_buscarquienes_empresaquienes_fichaquienes_representantesquienes_establecimientosquienes_trabajadoresquienes_deuda_coactivaquienes_vinculosquienes_dniquienes_dni_rucquienes_fecha_nacimientoquienes_licenciaquienes_cequienes_huellaquienes_placaquienes_soatquienes_tipo_cambio

Empresas

GET/v1/consultagratis

Consulta general

Autodetecta el tipo de término: RUC (11 dígitos) → ficha básica; DNI (8) → RUC de persona natural; nombre → lista de coincidencias del padrón SUNAT (18.3M).

ParámetroTipoRequeridoDescripción

qstringsíRUC, DNI o nombre / razón social.

Request

curl "https://quienes.pe/v1/consulta?q=20100070970" \
  -H "Authorization: Bearer qn_live_xxx"

Response 200

{
  "success": true,
  "queryType": "ruc",
  "data": {
    "ruc": "20100070970",
    "razonSocial": "SUPERMERCADOS PERUANOS SOCIEDAD ANONIMA",
    "estado": "ACTIVO",
    "condicion": "HABIDO",
    "tipo": "empresa",
    "direccion": "CAL. MORELLI 181 P-2"
  }
}

GET/v1/perfilgratis

Perfil básico

Ficha básica del padrón SUNAT + establecimientos anexos. Rápido y gratis.

ParámetroTipoRequeridoDescripción

rucstringsíRUC de 11 dígitos.

Request

curl "https://quienes.pe/v1/perfil?ruc=20100070970" \
  -H "Authorization: Bearer qn_live_xxx"

Response 200

{
  "success": true,
  "data": {
    "ruc": "20100070970",
    "razonSocial": "SUPERMERCADOS PERUANOS SOCIEDAD ANONIMA",
    "estado": "ACTIVO",
    "anexos": [{ "ubigeo": "150101", "direccion": "JR. JOSE GALVEZ 1345" }]
  },
  "source": { "entity": "SUNAT", "dataset": "Padrón Reducido RUC" }
}

GET/v1/empresa3 créd.

Dossier completo

DOSSIER unificado en una sola llamada: identidad + ficha SUNAT (actividad CIIU, planilla, deuda) + representantes + establecimientos + vínculos por domicilio. Pensado para armar un grill de empresa sin encadenar varias consultas.

ParámetroTipoRequeridoDescripción

rucstringsíRUC de 11 dígitos.

Request

curl "https://quienes.pe/v1/empresa?ruc=20604881847" \
  -H "Authorization: Bearer qn_live_xxx"

Response 200

{
  "success": true,
  "data": {
    "ruc": "20604881847",
    "razonSocial": "GMC SOLUCIONES COMERCIALES S.A.C.",
    "estado": "ACTIVO", "condicion": "HABIDO",
    "ficha": { "actividades": [{ "ciiu": "2029", "desc": "FABRICACIÓN DE OTROS PRODUCTOS QUÍMICOS N.C.P." }] },
    "trabajadores": [{ "periodo": "2026-06", "trabajadores": 16 }],
    "deuda": { "hayDeuda": false, "deudas": [] },
    "representantes": [
      { "doc": "70356195", "nombre": "MALDONADO CANALES GIANFRANCO", "cargo": "GERENTE GENERAL" }
    ],
    "establecimientos": [ /* ... */ ],
    "vinculos": []
  },
  "source": { "entity": "SUNAT", "dataset": "Dossier de empresa" }
}

GET/v1/ficha3 créd.

Ficha SUNAT

Ficha rica de e-consultaRUC que el padrón no trae: actividad económica (CIIU), representantes legales, planilla de trabajadores y deuda coactiva. Se consulta en vivo y se cachea (la 1ª de un RUC nuevo tarda unos segundos).

ParámetroTipoRequeridoDescripción

rucstringsíRUC de 11 dígitos.

Request

curl "https://quienes.pe/v1/ficha?ruc=20100070970" \
  -H "Authorization: Bearer qn_live_xxx"

Response 200

{
  "success": true, "cached": true,
  "data": {
    "ficha": {
      "tipoContribuyente": "SOCIEDAD ANONIMA",
      "fechaInscripcion": "09/10/1992",
      "actividades": [{ "tipo": "Principal", "ciiu": "4711", "desc": "VENTA AL POR MENOR..." }]
    },
    "representantes": [{ "doc": "09342569", "nombre": "SHIMIZU MITSUMASU MISAEL", "cargo": "APODERADO" }]
  },
  "source": { "entity": "SUNAT", "dataset": "e-consultaRUC" }
}

GET/v1/representantes0.5 créd.

Representantes legales

Representantes legales y apoderados de una empresa, con su documento, cargo y fecha desde.

ParámetroTipoRequeridoDescripción

rucstringsíRUC de 11 dígitos.

Request

curl "https://quienes.pe/v1/representantes?ruc=20100070970" \
  -H "Authorization: Bearer qn_live_xxx"

Response 200

{
  "success": true,
  "data": [
    { "tipoDoc": "DNI", "doc": "09342569", "nombre": "SHIMIZU MITSUMASU MISAEL",
      "cargo": "APODERADO", "desde": "08/04/2013" }
  ]
}

GET/v1/establecimientos0.5 créd.

Establecimientos

Locales / establecimientos anexos de una empresa (depósitos, sucursales), con su tipo y dirección.

ParámetroTipoRequeridoDescripción

rucstringsíRUC de 11 dígitos.

Request

curl "https://quienes.pe/v1/establecimientos?ruc=20100070970" \
  -H "Authorization: Bearer qn_live_xxx"

Response 200

{
  "success": true,
  "data": [
    { "codigo": "0001", "tipo": "LO. L. COMERCIAL",
      "direccion": "AV. ... ", "departamento": "LIMA", "distrito": "SURCO" }
  ]
}

GET/v1/trabajadores0.5 créd.

Trabajadores en planilla

Número de trabajadores, prestadores de servicio y pensionistas declarados en SUNAT, mes a mes.

ParámetroTipoRequeridoDescripción

rucstringsíRUC de 11 dígitos.

Request

curl "https://quienes.pe/v1/trabajadores?ruc=20100070970" \
  -H "Authorization: Bearer qn_live_xxx"

Response 200

{
  "success": true,
  "data": [
    { "periodo": "2026-06", "trabajadores": 16, "prestadoresServicio": 8, "pensionistas": 0 }
  ]
}

GET/v1/deuda-coactiva0.5 créd.

Deuda coactiva

Deuda en cobranza coactiva con el Estado (SUNAT). Devuelve si hay deuda y el detalle de cada una.

ParámetroTipoRequeridoDescripción

rucstringsíRUC de 11 dígitos.

Request

curl "https://quienes.pe/v1/deuda-coactiva?ruc=20100070970" \
  -H "Authorization: Bearer qn_live_xxx"

Response 200

{
  "success": true,
  "data": { "hayDeuda": false, "deudas": [] }
}

GET/v1/vinculos0.5 créd.

Vínculos por domicilio

Otras empresas que comparten el domicilio fiscal con este RUC — señal de grupo económico o vínculo.

ParámetroTipoRequeridoDescripción

rucstringsíRUC de 11 dígitos.

Request

curl "https://quienes.pe/v1/vinculos?ruc=20100070970" \
  -H "Authorization: Bearer qn_live_xxx"

Response 200

{
  "success": true,
  "data": [
    { "ruc": "20xxxxxxxxx", "razonSocial": "OTRA EMPRESA S.A.C." }
  ]
}

Personas

GET/v1/dni0.5 créd. sensible

DNI → nombre

Nombre completo e identidad oficial por DNI (RENIEC). Dato personal: úsalo con base legal (verificación de identidad, onboarding, cobranza). No lo redistribuyas ni lo indexes.

ParámetroTipoRequeridoDescripción

dnistringsíDNI de 8 dígitos.

Request

curl "https://quienes.pe/v1/dni?dni=45215942" \
  -H "Authorization: Bearer qn_live_xxx"

Response 200

{
  "success": true,
  "data": {
    "numero": "45215942",
    "nombreCompleto": "GARCIA CHANCO, CARLOS AUGUSTO",
    "nombres": "CARLOS AUGUSTO",
    "apellidoPaterno": "GARCIA", "apellidoMaterno": "CHANCO"
  },
  "source": { "entity": "RENIEC" }
}

GET/v1/dni-ruc0.5 créd.

¿DNI tiene RUC?

Deriva el RUC de persona natural (RUC-10) a partir del DNI, si existe en el padrón.

ParámetroTipoRequeridoDescripción

dnistringsíDNI de 8 dígitos.

Request

curl "https://quienes.pe/v1/dni-ruc?dni=45215942" \
  -H "Authorization: Bearer qn_live_xxx"

Response 200

{
  "success": true,
  "data": { "tieneRuc": true, "ruc": "10452159421" }
}

GET/v1/fecha-nacimiento0.5 créd. sensible

Fecha de nacimiento

Fecha de nacimiento y primer nombre por DNI. Dato sensible (Ley 29733): base legal obligatoria.

ParámetroTipoRequeridoDescripción

dnistringsíDNI de 8 dígitos.

Request

curl "https://quienes.pe/v1/fecha-nacimiento?dni=45215942" \
  -H "Authorization: Bearer qn_live_xxx"

Response 200

{
  "success": true,
  "data": { "dni": "45215942", "fechaNacimiento": "12/05/1984", "nombres": "CARLOS" }
}

GET/v1/licencia0.5 créd.

Licencia de conducir

Licencia de conducir por DNI (MTC): categoría, estado, vencimiento y restricciones.

ParámetroTipoRequeridoDescripción

dnistringsíDNI de 8 dígitos.

Request

curl "https://quienes.pe/v1/licencia?dni=45215942" \
  -H "Authorization: Bearer qn_live_xxx"

Response 200

{
  "success": true,
  "data": {
    "nombreCompleto": "GARCIA CHANCO, CARLOS AUGUSTO",
    "licencia": { "numero": "Q45215942", "categoria": "A-IIB",
      "estado": "VIGENTE", "fechaVencimiento": "2029-05-12", "restricciones": "" }
  }
}

GET/v1/ce0.5 créd. sensible

Carné de extranjería

Datos de un extranjero por su carné de extranjería (Migraciones): nombre y nacionalidad.

ParámetroTipoRequeridoDescripción

numerostringsíNúmero de carné de extranjería.

Request

curl "https://quienes.pe/v1/ce?numero=000823140" \
  -H "Authorization: Bearer qn_live_xxx"

Response 200

{
  "success": true,
  "data": { "numero": "000823140", "nombreCompleto": "CHEN YUN", "nacionalidad": "CHINA" }
}

GET/v1/huella8 créd. sensible

Huella completa

La huella COMPLETA de una persona por DNI: identidad (RENIEC) + SUNAT + 13 fuentes del Estado (afiliación política, salud EsSalud, deudor alimentario/judicial, deuda municipal, licencias y récord de conducir, colegiatura, títulos, líneas móviles, AFP) + presencia en internet y filtraciones. Es la consulta más completa y la más lenta (~30–40s). Usa ?tier=core para solo el núcleo rápido (identidad + SUNAT + internet).

ParámetroTipoRequeridoDescripción

dnistringsíDNI de 8 dígitos.

tierstringopcionalcore = solo núcleo rápido · gov = solo fuentes del Estado · vacío = todo.

Request

curl "https://quienes.pe/v1/huella?dni=45215942" \
  -H "Authorization: Bearer qn_live_xxx"

Response 200

{
  "success": true,
  "data": {
    "dni": "45215942",
    "reniec": { "nombreCompleto": "GARCIA CHANCO, CARLOS AUGUSTO", "fechaNacimiento": "12/05/1984" },
    "ruc": "10452159421", "perfil": { /* SUNAT */ },
    "afiliacion": { "tieneRegistro": false }, "salud": { "acreditado": true },
    "sat": { "tieneDeuda": false }, "redam": { "inscrito": false },
    "web": [ /* menciones y filtraciones en internet */ ],
    "cadena": [ /* qué fuente corrió y qué aportó */ ]
  }
}

Vehículos

GET/v1/placa0.5 créd.

Placa → vehículo + SOAT

Vehículo por placa (SUNARP): marca, modelo, serie, color, motor; más su SOAT vigente (SBS).

ParámetroTipoRequeridoDescripción

placastringsíPlaca vehicular (6–7 caracteres).

Request

curl "https://quienes.pe/v1/placa?placa=D4Z090" \
  -H "Authorization: Bearer qn_live_xxx"

Response 200

{
  "success": true,
  "data": {
    "placa": { "placa": "D4Z090", "marca": "VOLKSWAGEN", "modelo": "GOL", "color": "ROJO" },
    "soat": { "nombreCompania": "La Positiva", "estado": "VIGENTE", "fechaFin": "2026-06-14" }
  }
}

GET/v1/soat0.5 créd.

SOAT por placa

Póliza SOAT vigente por placa: compañía, vigencia, estado y número de póliza.

ParámetroTipoRequeridoDescripción

placastringsíPlaca vehicular (6–7 caracteres).

Request

curl "https://quienes.pe/v1/soat?placa=D4Z090" \
  -H "Authorization: Bearer qn_live_xxx"

Response 200

{
  "success": true,
  "data": {
    "placa": "D4Z090", "nombreCompania": "La Positiva",
    "fechaInicio": "14/06/2025", "fechaFin": "14/06/2026",
    "estado": "VIGENTE", "numeroPoliza": "0001416038..."
  }
}

Financiero

GET/v1/tipo-cambiogratis

Tipo de cambio

Tipo de cambio SUNAT del dólar (compra y venta). Sin fecha devuelve el de hoy.

ParámetroTipoRequeridoDescripción

fechastringopcionalFecha YYYY-MM-DD. Vacío = hoy.

Request

curl "https://quienes.pe/v1/tipo-cambio?fecha=2026-08-01" \
  -H "Authorization: Bearer qn_live_xxx"

Response 200

{
  "success": true,
  "data": { "moneda": "USD", "fecha": "2026-08-01", "compra": 3.751, "venta": 3.759, "origen": "SUNAT" }
}

Uso responsable

Los datos de personas jurídicas (RUC 20) son públicos. Los de personas naturales se tratan conforme a la Ley 29733 de Protección de Datos Personales: úsalos con base legal (verificación de identidad, onboarding, cobranza) y no los redistribuyas ni indexes.