Búsqueda de personas

Esta guía cubre la lectura centrada en la persona: encontrar a un titular o representante y saber cuánto del registro es suyo. Complementa la búsqueda por campos, donde las personas son un filtro sobre marcas; aquí son el sujeto de la consulta.

El esquema completo y siempre actualizado por campo vive en la referencia OpenAPI interactiva en /docs (Scalar). Esta guía explica el contrato y enlaza a esa referencia — no reformula el esquema. Cuando un campo no está documentado aquí, /docs es autoritativo.

A lo largo de la guía la URL base se escribe como $TARNO_BASE_URL y la clave como $TARNO_API_KEY, y cada llamada lleva el encabezado X-API-Key.

GET /v1/personas · scope brands:read · equivalente MCP: search_personas

Hasta ahora las personas sólo se podían usar como filtro de marcas (?titular=, ?rut=) o como agregado (/v1/insights/by-holder). Este endpoint invierte la pregunta: parte de la persona y te dice cuánto del registro es suyo.

curl -sS "$TARNO_BASE_URL/v1/personas?q=carey" -H "X-API-Key: $TARNO_API_KEY"

[
  {
    "id": "1261017",
    "nombre": "ESTUDIO CAREY LIMITADA",
    "identificador": "76111111-6",
    "pais": "CL",
    "region": "13",
    "comuna": "13101",
    "marcasTitular": 12,
    "marcasRepresentante": 3480,
    "marcasTotal": 3492,
    "marcasHistoricas": 0,
    "tipo": "juridica",
    "tipoOrigen": "rut",
    "observacion": null,
    "nombrePublicado": "Estudio Carey Limitada",
    "revision": false
  },
  {
    "id": "884213",
    "nombre": "JUAN CAREY SOTO",
    "identificador": null,
    "pais": "CL",
    "region": null,
    "comuna": null,
    "marcasTitular": 1,
    "marcasRepresentante": 0,
    "marcasTotal": 1,
    "marcasHistoricas": 0,
    "tipo": "desconocido",
    "observacion": null,
    "nombrePublicado": "Juan Carey Soto",
    "revision": false
  }
]

Cómo buscar

Parámetro	Qué hace
`q`	Coincidencia parcial e insensible a tildes sobre nombre y apellido. Mínimo 2 caracteres. `argandona` encuentra `Argandoña`.
`rut`	Coincidencia exacta. Acepta cualquier formato (`17.271.415-3`, `17271415-3`) y lo normaliza.
`limit` / `offset`	Paginación. `limit` por defecto 25, máximo 100.
`envelope`	`true` añade el sobre `{ data, dataAsOf }`.

Debes indicar q o rut; sin ninguno de los dos la respuesta es 400, para que nadie liste la tabla entera por accidente.

Los resultados vienen ordenados por volumen de marcas, de mayor a menor. Al buscar un apellido común, el estudio con miles de marcas aparece antes que su homónimo con una sola.

Los conteos son de AHORA, y `marcasHistoricas` te avisa de lo que falta

marcasTitular, marcasRepresentante y marcasTotal cuentan sólo lo que la persona tiene hoy. Si transfirió una marca, deja de sumarla.

marcasHistoricas cuenta lo que tuvo y ya no tiene. Existe para que esa resta no sea silenciosa: sin él verías un número menor y nada que te dijera que hay historia. Es 0 para casi todo el mundo; que no lo sea es la señal de que conviene preguntar por el histórico:

# las marcas que esta persona TUVO y ya no tiene
curl -sS "$TARNO_BASE_URL/v1/brands?titular=Carey&vigencia=historica" -H "X-API-Key: $TARNO_API_KEY"

Qué clase de parte es cada persona

Desde 2026-09-08 cada persona lleva cinco campos más, los mismos en los tres sitios donde el contrato publica una persona: el detalle de marca (GET /v1/brands/:nroSolicitud), el informe de registrabilidad y esta búsqueda. Son aditivos: no se quitó, renombró ni re-tipó ningún campo anterior, ni cambió ningún scope —se leen bajo el mismo brands:read—, así que una integración escrita antes de esa fecha sigue parseando la respuesta sin tocar nada.

Campo	Tipo	Qué dice
`tipo`	`natural` \| `juridica` \| `desconocido`	Qué clase de parte es.
`tipoOrigen`	`rut` \| `sufijo` \| `manual`	Qué señal produjo `tipo`. Se omite —nunca llega como `null`— cuando no hubo ninguna.
`observacion`	string \| null	La cláusula de jurisdicción que INAPI escribe pegada al nombre.
`nombrePublicado`	string \| null	La grafía tal como la publicó INAPI, frente al `nombre` canónico.
`revision`	boolean	Hay una ambigüedad conocida en esta fila.

Los cinco están declarados opcionales en el esquema —de ahí que el cambio sea aditivo—; además, tipoOrigen desaparece del objeto cuando no hay señal.

desconocido es un valor, no un hueco. Medido en producción el 2026-09-07 sobre 396.287 personas: 127.263 llevan RUT (79.385 natural, 47.878 jurídica), otras 167.568 llevan un sufijo societario en el nombre, y aproximadamente un tercio del corpus no lleva ninguna de las dos señales. Ese tercio es desconocido, y decirlo es más honesto que deducirlo. Leerlo como «probablemente una persona natural» metería unas 130.000 partes sin clasificar dentro de un filtro tipo = 'natural'. Si necesitas certeza, exige tipoOrigen: 'rut' —el corte con el que el Estado asigna el número— en vez de aceptar una deducción a partir de una palabra al final del nombre.

tipoOrigen se omite; no llega como null. Cuando no hubo señal la clave desaparece del objeto, que es exactamente cuando tipo vale desconocido (el segundo elemento del ejemplo de arriba no tiene tipoOrigen). Un if (p.tipoOrigen === null) no se cumple nunca: la comprobación correcta es p.tipoOrigen === undefined o !("tipoOrigen" in p).

nombre es el campo con el que se BUSCA; nombrePublicado es el campo que se MUESTRA o se COMPARA contra un documento de origen. nombre es la forma canónica —MAYÚSCULAS con tildes— y es la que el motor indexa; nombrePublicado conserva la grafía de la fuente para que cualquier valor se pueda contrastar contra INAPI. Cotejar contra nombrePublicado reintroduce justo el ruido de mayúsculas y tildes que la forma canónica existe para quitar.

observacion es prosa de INAPI, no una nota nuestra. Es la cláusula de jurisdicción sacada de dentro del nombre: «X, SOCIEDAD ORGANIZADA BAJO LAS LEYES DEL ESTADO DE DELAWARE» se guarda como nombre: 'X' más esta observación. Se publica literal, erratas incluidas: 1.472 personas la llevan en 681 grafías distintas de la misma cláusula (SOCIEDD ORGANIZADA…, SOC. ORG. BAJO LAS LEYES…). No la parsees como vocabulario controlado; es prosa.

revision avisa, no descalifica. Significa que el propio corpus marcó la fila para que la mire una persona —un RUT que no cuadra con el sufijo del nombre, una cláusula que se comió el nombre entero—, no que el dato sea malo. Quien enseña la parte a un abogado quizá quiera decirlo; quien cuenta marcas puede ignorarlo. El motivo no se publica: es vocabulario de operador y crece con cada pasada, así que el contrato responde sólo a la pregunta que tiene el consumidor, «¿me puedo fiar de esta fila a ciegas?».

El corpus de personas se reescribió el 2026-09-08

Los nombres son canónicos desde esa fecha: 396.444 personas se reescribieron a la forma canónica y unas 240.000 cambiaron de grafía. Si comparas valores cacheados de antes con los que devuelve la API hoy, verás diferencias de mayúsculas y tildes que no son cambios de dato. Además:

Las cláusulas de jurisdicción ya no están dentro de nombre: viven en observacion, y el nombre al que estaban pegadas es ahora sólo el nombre.
Agrupar o de-duplicar personas en tu lado por nombre daba de más: la misma parte que leía Estudio Carey Limitada en una marca y ESTUDIO CAREY LIMITADA en otra ahora lee igual en las dos.
Se fusionaron 179 grupos de duplicados. Ninguna marca cambió de dueño, así que el total de una parte sólo puede subir al absorber a su gemela, nunca bajar.

Dos cosas que conviene entender

Devuelve conteos, no marcas. Un estudio grande tiene miles: incrustarlas haría la respuesta ilimitada y duplicaría el motor de búsqueda que /v1/brands ya es. Para obtener las marcas de una persona, usa los valores que te devuelve aquí:

# todas las marcas donde esta persona es parte, por RUT (cualquier rol)
curl -sS "$TARNO_BASE_URL/v1/brands?rut=76111111-6" -H "X-API-Key: $TARNO_API_KEY"

# sólo donde es titular, por nombre
curl -sS "$TARNO_BASE_URL/v1/brands?titular=Carey" -H "X-API-Key: $TARNO_API_KEY"

# lo que tuvo y ya no tiene (o `vigencia=todas` para ambas)
curl -sS "$TARNO_BASE_URL/v1/brands?titular=Carey&vigencia=historica" -H "X-API-Key: $TARNO_API_KEY"

Esas llamadas devuelven la titularidad actual por defecto: quien transfirió una marca deja de aparecer en ella. vigencia cambia esa pregunta — ver búsqueda por campos.

identificador es null muchas veces, y no es un fallo de datos. El RUT es un identificador chileno, así que:

un titular extranjero nunca tendrá uno — no existe;
en solicitudes anteriores a 2023 INAPI no lo publicaba (cobertura del 17-26 % entre 2017 y 2022, frente a ~75 % desde 2024).

Si tu integración cruza por RUT, trata el null como "no disponible", nunca como "no coincide".

Desde un agente de IA

search_personas(q: "carey", limit: 5)
search_personas(rut: "17.271.415-3")

La herramienta MCP devuelve siempre el sobre { data, dataAsOf } y es byte-idéntica a GET /v1/personas?envelope=true.