Sirveil Exposure

API reference

Dos endpoints facturables. Una tarifa. Lánzalo en una tarde.

$0.10 por verificación completada. $0.35 por barrido completado. $0.00 por cualquier cosa que no pudiéramos atender — nuestros errores y los de nuestros proveedores son nuestro costo, no el tuyo. Todo lo siguiente es legible sin una cuenta.

Versión preliminar — cifras fijadas en el lanzamiento.

Inicio rápido

URL base https://ai.sirveil.ai. La autenticación es una sola clave bearer. Sin SDK que instalar, sin baile de OAuth, sin sandbox que solicitar — tu primera respuesta real está a una curl de distancia. Obtén una clave en /scan-api/signup y el medidor comienza en cero.

Inicio rápido

curlPythonNode

Copiar

Una verificación — una persona, un sitio que tú nombras. Diseñada para

dominios de corredores y búsqueda de personas; "no se pudo determinar" es una respuesta real.

Los campos de identidad van dentro de "identity"; el dominio permanece en el nivel superior.

curl https://ai.sirveil.ai/api/v1/verify
-H "Authorization: Bearer sk_live_…"
-d '{ "identity": { "firstName":"Jane", "lastName":"Doe", "phone":"5035551212" }, "domain":"examplebroker.com" }'

→ una respuesta estructurada, con su evidencia

{ "state": "indexed", "domain": "examplebroker.com", "evidence": [ … ], "dropped_fields": [], "billed": "$0.10" // llamadas fallidas: $0.00 }

pip install requests — esa es toda la historia del SDK

import requests

r = requests.post("https://ai.sirveil.ai/api/v1/verify", headers={"Authorization": "Bearer sk_live_…"}, json={"identity": {"firstName": "Jane", "lastName": "Doe", "phone": "5035551212"}, "domain": "examplebroker.com"})

print(r.json()["state"]) # indexed | not_indexed | indeterminate

// no hay SDK que instalar — fetch es el cliente const r = await fetch("https://ai.sirveil.ai/api/v1/verify", { method: "POST", headers: { Authorization: "Bearer sk_live_…" }, body: JSON.stringify({ identity: { firstName: "Jane", lastName: "Doe", phone: "5035551212" }, domain: "examplebroker.com" }) }); const result = await r.json(); console.log(result.state); // indexed | not_indexed | indeterminate

Esa llamada facturó diez centavos. Si hubiera fallado, no habría facturado nada. Esa es toda la relación comercial — el resto de esta página es detalle.

Autenticación

Cada solicitud lleva un encabezado. Las claves se ven como sk_live_… y provienen de /scan-api/signup — minutos, no reuniones. La clave es la cuenta: te identifica, te mide, y eso es todo lo que hace.

EncabezadoCopiar

Authorization: Bearer sk_live_…

• Mantenla del lado del servidor. Una clave bearer en JavaScript del navegador es una clave bearer que has publicado. Enruta las llamadas a través de tu backend.
• Rota libremente. Emite una nueva clave, mueve el tráfico, revoca la anterior — el medidor sigue a la cuenta, no a la clave.
• Clave faltante o incorrecta → 401, facturado $0.00, como todo error.

Construyendo una buena solicitud

Ambos endpoints aceptan la misma forma de identidad: un objeto JSON identity que contiene todo lo que sabemos sobre el sujeto. Solo identity.firstName y identity.lastName son obligatorios — pero el nombre solo te abre la puerta. Lo que hace que la respuesta valga la pena pagar es un identificador fuerte junto a él. Una solicitud con nombre y número de teléfono es una experiencia de producto materialmente diferente de una solicitud con solo el nombre.

Qué identificador enviar primero

Clasificamos los identificadores por qué tan bien se recuperan realmente en nuestras propias ejecuciones contra nuestra propia muestra — no por qué tan selectivos parecen en papel. La clasificación a continuación es el orden en que la búsqueda realmente los valora, en ambos endpoints:

Rango	Identificador	Por qué ocupa ese lugar
1.º	teléfono	Las páginas de perfil de corredores están indexadas por números de teléfono. El mejor campo para enviar.
2.º	correo electrónico	Casi único en la web abierta. Un fuerte segundo si no tienes teléfono.
3.º	streetAddress1 + ciudad/estado	Fuerte — las páginas de corredores también están indexadas por dirección — pero es el campo que la gente más se resiste a entregar en una primera pasada.
—	solo nombre	El recurso de respaldo. Funciona, pero es el caso débil — consulta las advertencias mínimas en cada endpoint.

Por qué el teléfono supera al correo electrónico aquí. En una búsqueda web general, una dirección de correo electrónico es el identificador más selectivo — una consulta de correo electrónico desnudo es casi única en todo internet. Pero una vez que una consulta se limita a un solo dominio de corredor, esa clasificación se invierte: las páginas de perfil de corredores se construyen alrededor de números de teléfono y direcciones, y muy a menudo no imprimen ningún correo electrónico. Así que la búsqueda lidera deliberadamente con teléfono, contra el orden más obvio. El orden surgió de nuestras propias ejecuciones — no publicamos ninguna cifra de precisión para el Servicio, y esta no es una.

• city + state son la defensa más barata contra el colapso de homónimos. Para cualquier nombre común, son la diferencia entre una respuesta sobre una persona y una respuesta sobre cuatro.
• streetAddress1 es recomendado, no mínimo — envíalo cuando lo tengas, pero no dejes que se interponga entre tú y tu primera llamada.
• usernames extiende la búsqueda a través de una gran lista de sitios públicos. Solo se ejecuta en un identificador que tú declares — nunca adivinamos uno por ti.

Campos que no podemos usar: dropped_fields

Un campo que no podemos usar — un número de teléfono malformado, una fecha de nacimiento no analizable — se descarta y se nombra en el arreglo dropped_fields de la respuesta. Nunca falla toda la solicitud, y nunca se ignora silenciosamente: un campo ignorado silenciosamente significaría que pagaste el precio completo por una búsqueda más débil sin forma de descubrirlo. Nombrar el campo descartado es cómo te enteras.

Consejo de integración: registra dropped_fields durante tu desarrollo. Es la forma más rápida de detectar un desajuste de formato entre tu modelo de datos y el nuestro — y convierte un vago ticket de "los resultados parecen escasos" en una corrección de una línea de tu lado.

POST/api/v1/verify

La verificación — una persona, un dominio que tú nombras. Síncrona. Mediana de 890 ms, p95 de 1,463 ms (benchmarks).

Pregunta si una persona está indexada en un solo sitio. Los dominios de corredores y búsqueda de personas devuelven veredictos decidibles; los sitios con muro de inicio de sesión o noindex devuelven un honesto indeterminate en lugar de un falso "no". Cada respuesta llega con su evidencia.

Cuerpo de la solicitud

Los campos de identidad viajan dentro de un objeto identity; domain permanece en el nivel superior. Este es el cuerpo que recomendamos enviar — cuatro campos, liderado por teléfono:

Recomendado — 4 camposCopiar

{ "identity": { "firstName": "Jane", "lastName": "Doe", "phone": "5035551212" }, "domain": "examplebroker.com" }

El teléfono es el identificador de mayor rango en este endpoint — las páginas de perfil de corredores están indexadas por números de teléfono — así que esta forma produce una consulta anclada por identificador en lugar del respaldo de solo nombre (consulta Construyendo una buena solicitud). ¿Sin teléfono? Sustituye email. ¿Ninguno de los dos? streetAddress1 más city.

Mínimo — 3 campos (el piso, no la recomendación)Copiar

{ "identity": { "firstName": "Jane", "lastName": "Doe" }, "domain": "examplebroker.com" }

El piso funciona, pero no lideres con él. Una solicitud de solo nombre ejecuta la búsqueda más débil posible a precio completo, y es la solicitud más probable de responder indeterminate — una llamada técnicamente exitosa que se siente como un fracaso. Envía un identificador fuerte junto con el nombre.

Campo	Tipo	Obligatorio	Notas
identity.firstName	string	obligatorio	Nombre de pila del sujeto, como lo listaría un corredor.
identity.lastName	string	obligatorio	Apellido del sujeto.
identity.phone	string	opcional	Identificador de mayor rango aquí. Enviar teléfono o correo electrónico es lo que convierte un respaldo de solo nombre en una búsqueda anclada por identificador.
identity.email	string	opcional	Segundo en rango. Casi único en la web abierta; menos en páginas de corredores, que rara vez imprimen uno.
identity.city	string	opcional	Con el estado, la defensa más barata contra el colapso de homónimos en nombres comunes.
identity.state	string	opcional	Estado de EE. UU. de dos letras, p. ej. "OR".
identity.streetAddress1	string	opcional	Recomendado, no mínimo — la tercera forma de identificador, fuerte cuando se envía.
identity.dateOfBirth	string	opcional	Ayuda a confirmar una coincidencia. Los valores no analizables se descartan y se nombran en dropped_fields.
identity.employer	string	opcional	Desambiguación adicional cuando los corredores listan uno.
identity.usernames	array	opcional	Extiende la búsqueda a través de sitios públicos — solo para identificadores que tú declares; nunca adivinamos uno.
domain	string	obligatorio	Nivel superior, junto a identity. El sitio a verificar, nombre de host desnudo — p. ej. examplebroker.com. Se acepta cualquier sitio público excepto una clase (consulta domain_excluded en Errores); la decidibilidad depende de la clase (consulta Estados).

Por qué el nombre es obligatorio. No existen búsquedas solo por teléfono o solo por correo electrónico — nunca, en ningún nivel. El nombre es el ancla contra la que se puntúa cada registro candidato; sin él, nada decide si el registro que encontramos es la persona correcta. Otros proveedores devolverán una coincidencia por número de teléfono sin decirte nunca qué tan seguros están de que es la persona correcta. Nosotros no lo haremos. Un identificador fuerte junto al nombre es lo que hace que el resultado valga la pena pagar.

Respuesta

200 OKCopiar

{ "state": "indexed", // indexed | not_indexed | indeterminate "domain": "examplebroker.com", "evidence": [ { "source": "https://examplebroker.com/profile/jane-doe-tx-1982", "query": ""Jane Doe" site:examplebroker.com", "observed_at": "2026-08-16T14:02:11Z" } ], "dropped_fields": [], // cualquier entrada inutilizable, nombrada — nunca ignorada en silencio "billed": "$0.10" // llamadas fallidas: $0.00 }

dropped_fields enumera cualquier campo de identidad que no pudimos usar — un teléfono malformado, una fecha de nacimiento inparseable — descartado y nombrado en lugar de fallar la solicitud o desaparecer en silencio. Consulta Cómo construir una buena solicitud.

Facturación: $0.10 por verificación completada — y indeterminate es una verificación completada, porque "la búsqueda pública no puede verlo" es una respuesta real. Una llamada que no pudimos atender — por nuestra culpa o por la de un proveedor — se factura $0.00. Una llamada que se completa se factura, incluso si tu cliente dejó de esperarla.

POST/api/v1/scan

El barrido completo — una persona, doce dominios consultados, los 548 conciliados. Síncrono por defecto. Mediana de 154 s, el más lento 203 s (n=5; nuestras ejecuciones sobre nuestros datos, no un compromiso).

Un barrido consulta un conjunto fijo de doce dominios de búsqueda de personas; los hallazgos se clasifican contra, y la cobertura se reporta sobre, el Registro — actualmente 548 dominios, derivados del registro de corredores de datos de California, un registro público que puedes auditar, más un conjunto prioritario curado. El Registro no es la lista de consulta, y un barrido no consulta cada dominio en él. Lo que $0.35 planos compran es doce dominios consultados y los 548 conciliados — los que alcanzamos, y por nombre los que no.

Es un POST síncrono simple y corriente. Tú llamas, la línea permanece abierta, el informe terminado vuelve en el cuerpo. Sin trabajo que supervisar, sin callback que alojar, nada en lo que optar — eso es simplemente lo que sucede. Lo único que debes saber: toma alrededor de dos minutos y medio, y la ejecución más lenta que hemos medido fue de 203 segundos, así que establece el tiempo de espera de tu cliente por encima de eso. Si tu stack odia las conexiones largas, hay un encabezado para eso — ver abajo.

Cuerpo de la solicitud

Misma forma que una verificación: campos de identidad dentro de un objeto identity. Este es el cuerpo que recomendamos para un barrido — seis campos:

Recomendado — 6 camposCopiar

{ "identity": { "firstName": "Jane", "lastName": "Doe", "phone": "5035551212", "email": "jane.doe@example.com", "city": "Portland", "state": "OR" } }

Cada campo gana su lugar: el nombre supera la puerta; el teléfono y el correo electrónico son en lo que la búsqueda liderada por identificador realmente se apoya; la ciudad y el estado son la defensa más barata contra el colapso de homónimos — en un nombre común, la diferencia entre un informe sobre una persona y un informe sobre cuatro. Detalles en Cómo construir una buena solicitud.

Mínimo — 2 campos (el piso, no la recomendación)Copiar

{ "identity": { "firstName": "Jane", "lastName": "Doe" } }

El piso funciona, pero no lideres con él. Un barrido solo con nombre cuesta los mismos $0.35 que cualquier otro y ejecuta la búsqueda más débil posible — precio completo por la configuración con menos probabilidades de encontrar lo que hay, y la más propensa a responder indeterminate donde una solicitud más fuerte habría decidido. Envía un identificador fuerte con el nombre.

Campo	Tipo	Requerido	Notas
identity.firstName	string	requerido	Nombre de pila del sujeto.
identity.lastName	string	requerido	Apellido del sujeto.
identity.phone	string	opcional	Identificador de mayor rango. Proporcionar teléfono o correo electrónico es lo que convierte un barrido solo con nombre en uno anclado por identificador.
identity.email	string	opcional	Segundo identificador en rango; casi único en la web abierta.
identity.city	string	opcional	Con el estado, defiende contra el colapso de homónimos en nombres comunes.
identity.state	string	opcional	Estado de EE. UU. de dos letras, p. ej. "OR".
identity.streetAddress1	string	opcional	Recomendado, no mínimo — la tercera forma de identificador; las páginas de perfil de corredores están claveadas por dirección.
identity.dateOfBirth	string	opcional	Ayuda a confirmar una coincidencia. Los valores inparseables se descartan y se nombran en dropped_fields.
identity.employer	string	opcional	Desambiguación extra cuando los corredores listan uno.
identity.usernames	array	opcional	Extiende el barrido a través de una gran lista de sitios públicos — solo para identificadores que declares; nunca adivinamos uno.
webhook_url	string	opcional	De nivel superior, junto a identity. Aún no activo — la superficie de entrega está especificada, no enviada; consulta Webhooks. Cuando llegue, se aplica solo a llamadas Prefer: respond-async, ya que una llamada síncrona ya te entregó el informe.

Respuesta — la predeterminada

Nada en lo que optar. El informe terminado es el cuerpo de la respuesta.

200 OK · el informe completoCopiar

{ "job_id": "job_9f2c…", "status": "complete", "summary": { "indexed": 5, "not_indexed": 7, "indeterminate": 0 }, "coverage": { … }, // los 548 conciliados — ver Estados y evidencia "results": [ … ], "billed": "$0.35" }

¿No quieres mantener la línea? Prefer: respond-async

Un encabezado, y tomamos el trabajo y te entregamos un ticket en su lugar:

Solicitud · opt-in asíncronoCopiar

curl https://ai.sirveil.ai/api/v1/scan
-H "Authorization: Bearer sk_live_…"
-H "Prefer: respond-async"
-d '{ "identity": { "firstName":"Jane", "lastName":"Doe", "phone":"5035551212" } }'

202 Aceptado · solo asíncronoCopiar

{ "job_id": "job_9f2c…", "status": "queued" }

Luego consulta GET /api/v1/jobs/:job_id tantas veces como quieras — la consulta es gratuita. (Existe un campo webhook_url en la forma, pero los webhooks aún no están construidos — no diseñes alrededor de eso hoy.) Asíncrono cambia cuándo llega la respuesta, no qué dice ni cuánto cuesta. Mismo informe, mismos $0.35.

Facturación: $0.35 por barrido completado, facturado cuando el barrido termina — no cuando comienza. Un barrido que no pudimos atender se factura $0.00, en cualquier modo — pero un barrido que se completa se factura incluso si tu cliente dejó de esperar. Consulta la trampa abajo.

Una trampa, y es la que el síncrono por defecto crea. Un barrido que se ejecuta hasta completarse es una respuesta completada, y se factura estés o no todavía en la línea para capturarlo. Cuelga a los 120 segundos en una ejecución que termina a los 154 y el trabajo se hizo, el medidor lo dice, y nunca viste el informe. Dos formas de no pagar por una respuesta que no leíste: establece el tiempo de espera por encima de 203 segundos, o envía Prefer: respond-async y recógelo del trabajo. Mejor que lo escuches aquí que de una factura.

GET/api/v1/jobs/:job_id

Recoge un barrido asíncrono — el informe terminado, o qué tan avanzado está.

Solo necesitas esto si enviaste Prefer: respond-async; un barrido predeterminado ya te entregó el informe. Mientras un barrido asíncrono se ejecuta, status es queued o running. Cuando cambia a complete, el informe completo está en el cuerpo, cada entrada con su veredicto y su evidencia. Obtener un trabajo es gratuito — consulta tanto como quieras.

Respuesta

200 OK · completadoCopiar

{ "job_id": "job_9f2c…", "status": "complete", // queued | running | complete | failed "summary": { "indexed": 5, "not_indexed": 7, "indeterminate": 0 // veredictos para los dominios realmente consultados }, "coverage": { … }, // y el resto del registro, nombrado — ver Estados "results": [ { "domain": "examplebroker.com", "state": "indexed", "evidence": [ … ] }, { "domain": "quietbroker.example", "state": "not_indexed", "evidence": [ … ] } // … una entrada por dominio consultado, cada una con su fuente ], "billed": "$0.35" // un trabajo fallido: $0.00 }

Facturación: los $0.35 pertenecen al barrido, no a la obtención. GET /api/v1/jobs/:iden sí es gratuito a cualquier frecuencia de consulta.

GET/api/v1/whoami

Tu clave, tu plan, tus límites — gratuito, y no consume cuota.

Entrégale tu clave portadora y te dice a qué cuenta pertenece la clave, en qué plan está esa cuenta, y el límite de tasa, la asignación restante y el techo que se aplican a ti. Es la respuesta real a "¿cuáles son mis límites?" — mejor que cualquier cosa que pudiéramos imprimir en una página, porque un número impreso puede volverse obsoleto para tu cuenta y este no puede.

También es la primera llamada correcta en cualquier integración: prueba que la clave funciona antes de gastar un centavo. Una clave incorrecta o revocada devuelve 401 aquí por $0.00, en lugar de en tu primera llamada facturable.

200 OKCopiar

curl https://ai.sirveil.ai/api/v1/whoami
-H "Authorization: Bearer sk_live_…"

→ quién eres y qué se te aplica

{ "plan": "developer", "rate_limit_per_minute": …, "quota_remaining": …, // unidades: una verificación es 1, un barrido es 100 "spend_ceiling" // nuestro guardián de costos de proveedor, no un tope en tu factura: … }

ConfirmarLos nombres exactos de los campos se están fijando con ingeniería antes del lanzamiento. Los cuatro hechos — cuenta, plan, límites, restante — son el contenido comprometido; lee la respuesta en vivo como la fuente de verdad en lugar de este ejemplo.

Facturación: gratuito. Sin cargo, sin unidad de cuota, a cualquier frecuencia de consulta. No vamos a medirte por preguntar cuánto te queda.

POST/api/v1/mcppreview

Una superficie de Protocolo de Contexto de Modelo para agentes — una herramienta de solo lectura hoy.

¿Conectando esto a un agente en lugar de una aplicación? Este endpoint habla MCP sobre la misma clave portadora. Expone una única herramienta de solo lectura — no toda la API — y nada sobre las respuestas cambia: mismos veredictos, misma evidencia, mismos tres estados. Se factura exactamente igual que el endpoint subyacente. Una verificación realizada a través de MCP cuesta $0.10 por verificación y una unidad. Lo decimos aquí en lugar de dejar que lo descubras en una factura, porque un agente en un bucle gasta dinero real a velocidad de máquina. Lee tu saldo restante desde GET /api/v1/whoami antes de apuntar uno hacia esto.

Vista previaLa superficie MCP no está congelada por versión: los nombres de herramientas y los esquemas pueden avanzar por delante de los endpoints que envuelven, y el proceso de cambios disruptivos aún no lo cubre. Los cambios llegan a /scan-api/changelog.

Estados y evidencia

Cada veredicto es una de tres cadenas. No hay una cuarta, y no hay "probablemente".

indexado

La búsqueda pública puede ver una página para este sujeto en este dominio. El arreglo de evidencia dice exactamente dónde y cómo.

no_indexado

Ausente del índice de búsqueda para este dominio, lo cual no es lo mismo que ausente del sitio, y no fingiremos que lo es. Se devuelve solo cuando la consulta con forma de nombre se ejecutó y volvió vacía.

indeterminado

No existe un sí/no honesto. Cuatro formas de llegar aquí: la identidad era solo-nombre; el texto de la página no contenía el nombre completo declarado; la confianza cayó por debajo del umbral mínimo; o el dominio está detrás de un muro de inicio de sesión o tiene noindex.

Un nombre por sí solo nunca puede devolver indexed. Una coincidencia de nombre por sí sola no puede distinguir a esta persona de todos los demás que comparten el nombre, por lo que siempre cae en indeterminate. Envía un teléfono si tienes uno: la selectividad va teléfono → correo electrónico → calle → nombre, lo cual está invertido respecto a la búsqueda web general a propósito: un perfil de corredor de datos con alcance de site: está claveado por teléfono y dirección y a menudo no imprime ningún correo electrónico.

La decidibilidad depende de la clase, y te decimos en qué clase estás. Los dominios de corredores de datos y búsqueda de personas devuelven veredictos decidibles, porque ser públicamente encontrables es su modelo de negocio. Los sitios con muro de inicio de sesión o noindex devuelven indeterminate: si la búsqueda pública no puede ver la página del sujeto, nosotros tampoco podemos, y tampoco puede el extraño que te preocupa. Un indeterminate que calculamos es una respuesta completada y facturada; una llamada que no pudimos atender se factura $0.00. Y si nuestro proveedor de búsqueda falla, obtienes indeterminate con outcome: unserved y una factura de nada: pagamos por ese intento, no tú.

Los negativos son el producto, y también lo es reconocer lo que no alcanzamos. Un barrido consulta un conjunto fijo priorizado de dominios de búsqueda de personas, y luego informa un resultado para cada dominio en el registro en cuatro categorías: indexed, not_indexed, indeterminate y no alcanzado: nombrado, hasta el límite por respuesta (never_queried_truncated te dice cuándo se cortó la lista). Los no con fecha te permiten decirle a un cliente "estás limpio aquí" y probarlo. Las brechas nombradas son lo que les permite creer el resto. Publicamos lo que no alcanzamos, lo cual, hasta donde sabemos, nos convierte en los únicos que lo hacen.

El bloque de cobertura

Cada barrido devuelve un objeto de cobertura junto con los hallazgos. Nada se esconde en un error de redondeo:

Copia de cobertura

{ "expected": 548, "queried_hit": 5, "queried_empty": 7, "queried_failed": 0, "never_queried": 536, "never_queried_domains": [ "..." ], // nombrado, limitado a 100 por respuesta "never_queried_truncated": true }

ConfirmarLas cifras de las categorías anteriores son formas ilustrativas, no una ejecución real. Una distribución en vivo irá aquí cuando ingeniería la entregue: preferimos mostrarte un marcador de posición que etiquetamos antes que un número que inventamos.

Cada respuesta lleva sus propios límites, en el cuerpo. Una cadena contract.limitation viaja dentro de cada respuesta de verificación diciendo lo que el endpoint realmente hizo: leer un índice de búsqueda, no obtener la página. Está en la carga útil, no en una nota al pie que tendrías que ir a buscar.

Cada respuesta es reproducible, incluidas las que salieron mal. Cada una lleva pipeline_version, linkage_weights_version y calibration_version, tanto en errores 400 y 500 como en éxitos. Deliberadamente: un libro de contabilidad que sella solo sus victorias tiene un agujero exactamente donde están las pérdidas.

La confianza y el vínculo son diagnósticos, no determinaciones. Cuando confidence, calibrated_probability o linkage por campo vuelven, explican cómo se alcanzó un veredicto. No los trates como una medida de precisión, y por favor no le muestres uno a un sujeto como una puntuación.

El arreglo de evidencia

Cada hallazgo muestra su trabajo: de dónde vino, qué preguntamos y cuándo miramos. Verificamos lo que la búsqueda pública puede ver, porque eso es lo que un abusador o un extraño puede ver.

Los dos endpoints no alcanzan los mismos lugares, y no los difuminaremos juntos. Una verificación alcanza exactamente a un tercero (el proveedor de búsqueda) y no hace llamadas de modelo. Solo consultas públicas, sin inicios de sesión, sin puertas traseras. Un barrido llega más lejos: además del proveedor de búsqueda, puede consultar fuentes de enriquecimiento de identidad, violaciones de datos y registros de ladrones de credenciales, y registros judiciales, más páginas públicas de nombre de usuario donde proporcionaste un identificador, y usa inferencia de modelo para adjudicar y redactar resultados. Algunas de esas son datos de suscripción comercial, no páginas web públicas. Ningún endpoint inicia sesión en nada ni evita un control de acceso. La cuenta completa está en Aviso de privacidad de API §5.

Entrada de evidenciaCopia

{ "source": "https://examplebroker.com/profile/jane-doe-tx-1982", // URL pública que vimos "query": ""Jane Doe" site:examplebroker.com", // la consulta que ejecutamos "observed_at": "2026-08-16T14:02:11Z" // cuándo miramos (UTC) }

Vista previaLos tres campos anteriores (URL de origen, consulta utilizada, marca de tiempo de observación) son la forma comprometida; los nombres exactos de los campos están bloqueados en el lanzamiento.

Lo que conservamos

Sección corta, porque no hay mucho que conservar. La identidad que envías se usa para responder la llamada que hiciste, y ese es todo el trabajo que hace.

• Una llamada síncrona no escribe nada sobre el sujeto en el almacenamiento. La ruta de verificación está protegida en el código contra escrituras en la base de datos.
• Una excepción, y es la caché. El texto de consulta normalizado (que contiene el identificador) reside en memoria en una instancia durante unos 15 minutos, particionado por cuenta y nunca escrito en disco. La misma caché que hace consistente una respuesta repetida, y la misma que factura en su totalidad. Preferimos nombrarlo antes que dejar que "no persiste nada" haga un trabajo que no puede hacer.
• Un trabajo asíncrono retiene la identidad que enviaste y el informe terminado durante 24 horas para que tengas tiempo de recogerlo, luego el cuerpo almacenado se anula. Esa ventana es el precio de no mantener una conexión abierta.
• La fila de medición se conserva indefinidamente: cuenta, clave, endpoint, marca de tiempo, estado, latencia, unidades facturadas, resultado, identificador de ejecución. Sin cuerpos de solicitud, sin cuerpos de respuesta. Una factura que puedas auditar debe sobrevivir a los datos con los que se calculó; no tiene que contenerlos.
• No vendemos ni compartimos tus identificadores ni tu salida, y no entrenamos modelos con ellos.

Estos son comportamientos actuales, no el límite exterior. El Aviso de privacidad de API es el documento rector, y §7 es la autoridad en retención. Es explícito que la fila de actividad por llamada no tiene caducidad establecida hoy: una decisión no resuelta, no una diseñada, y lo dice en esas palabras. Lo anterior es lo que el sistema hace hoy. Donde los dos difieran, el Aviso gobierna.

Errores

Los errores son JSON, dicen qué salió mal en palabras, y nunca facturan. Una forma, en todas partes:

Cuerpo de errorCopia

{ "error": { "type": "identity_incomplete", "message": "identity.firstName y identity.lastName son obligatorios: el nombre es el ancla contra la que se puntúa cada coincidencia.", "doc_url": "https://sirveil.ai/scan-api/docs#errors" } }

Estado	Significado	Facturado
400	Solicitud malformada: JSON roto, campo obligatorio faltante. Tipos nombrados abajo.	$0.00 — nunca
401	Clave de API faltante, revocada o incorrecta.	$0.00 — nunca
402	spend_ceiling_reached: un límite a nivel de cuenta está en efecto. Protege nuestro costo de proveedor, no un tope en tu factura. Consulta Límites de velocidad.	$0.00 — nunca
403	tenant_suspended: la cuenta está suspendida; o domain_excluded: nombraste un dominio en la clase de reconocimiento facial e identificación biométrica, la única negativa que no es renunciable.	$0.00 — nunca
404	No existe tal ruta, o no existe tal job_id en tu cuenta.	$0.00 — nunca
410	result_expired: consultaste un trabajo asíncrono después de su ventana de 24 horas. Una respuesta explícita, no un silencio que tendrías que interpretar.	$0.00 — nunca
422	JSON válido, valores inutilizables: por ejemplo, un dominio que no es un nombre de host.	$0.00 — nunca
429	rate_limited: demasiadas solicitudes por minuto. Retrocede, respeta Retry-After, continúa.	$0.00 — nunca
429	quota_exceeded: la asignación de unidades del mes está agotada. Mismo estado, problema diferente: esperar no arreglará este.	$0.00 — nunca
500	Culpa nuestra. Seguro reintentar; si persiste, dínoslo. /scan-api/status es solo informativo: no es una métrica de disponibilidad, no es un compromiso de nivel de servicio (Términos de API §11).	$0.00 — nunca
503	search_unavailable: una fuente de recuperación está caída. En una verificación, en su lugar puedes obtener un indeterminado honesto con un resultado no atendido.	$0.00 — nunca
503	async_not_available: enviaste Prefer: respond-async en una implementación donde async no está disponible. No se cobra nada.	$0.00 — nunca
503	capacity_reached: un guardia diario a nivel de plataforma. No eres tú, no es tu integración. Intenta más tarde.	$0.00 — nunca

Tipos de error nombrados

Tipo	Estado	Qué significa
identity_incomplete	400	A la solicitud le falta un nombre. El mensaje real de la API: "identity.firstName y identity.lastName son obligatorios: el nombre es el ancla contra la que se puntúa cada coincidencia." Ambos endpoints lo devuelven.
invalid_domain	400	Solo en POST /api/v1/verify: falta el dominio de nivel superior o no es un nombre de host simple utilizable. No hay lista de permitidos: se acepta cualquier nombre de host público, salvo la clase excluida que se indica más abajo, pero tiene que ser un nombre de host.
rate_limited	429	Demasiadas llamadas por minuto. Retry-After te indica cuánto tiempo esperar. Esperar lo soluciona.
quota_exceeded	429	Se ha agotado la asignación de unidades del mes. Esperar no lo soluciona: la asignación se restablece al inicio del siguiente mes UTC, o pídenos que la aumentemos.
spend_ceiling_reached	402	Hay un límite a nivel de cuenta en vigor y se rechazan más llamadas hasta que se levante. Mide el costo de nuestro proveedor, no un tope en tu factura. No es un cargo; no se factura nada. ¿Lo ves en uso normal? support@sirveil.ai y lo subiremos: preferimos mover un número antes que perder tu tráfico.
capacity_reached	503	Un guardia diario a nivel de plataforma. No hay nada malo con tu clave ni con tu solicitud.
tenant_suspended	403	La cuenta está suspendida. La suspensión se rige por los Términos de la API; si ves esto y no sabes por qué, support@sirveil.ai te lo dirá.
domain_excluded	403	Nombres un dominio en la clase de reconocimiento facial e identificación biométrica: un servicio cuya función principal es identificar a una persona a partir de una imagen o una plantilla biométrica. Se rechaza antes de que se construya cualquier consulta y antes de que se facture nada. Es un control en el código, en ambos endpoints, y no es renunciable: ni por nosotros, ni a ningún precio.

Cada uno de estos se rechaza antes de que se ejecute cualquier búsqueda: sin trabajo realizado, sin facturación, y el costo registrado es null, no cero. Una solicitud rechazada no nos costó nada responderla, y no vamos a afirmar una medición que nunca hicimos.

La columna de facturación no es una nota de cortesía: es el modelo de precios. Se te factura por respuesta completada, y un error no es una respuesta. Los problemas de infraestructura son nuestro costo, no el tuyo.

Límites de tasa

Generosos por defecto, se aumentan a petición. Los límites están configurados para acomodar el tráfico normal de integración: sondear GET /api/v1/jobs/:id mientras se ejecuta un barrido está muy incluido. Se aplican sobre la base del mejor esfuerzo y podemos ajustarlos, así que lee los tuyos desde whoami en lugar de asumir. Cuatro límites pueden decir que no, verificados en orden para que siempre obtengas la respuesta más específica disponible. Los cuatro facturan $0.00.

• Límite de tasa — 429 rate_limited, con un encabezado Retry-After. Respétalo y estarás bien.
• Cuota de unidades, donde tu cuenta tenga una — 429 quota_exceeded. Una verificación cuesta 1 unidad, un barrido cuesta 100, en un mes calendario UTC. Las cuentas de Marketplace se aprovisionan sin tope de unidades.
• Límite de cuenta — 402 spend_ceiling_reached. Las llamadas se rechazan, no se cobran. Pide y lo subiremos. Una cosa que no es: el límite se mide contra el costo de nuestro proveedor para tu cuenta, no contra tu factura. No es protección de gasto y no fingiremos que lo es: lo único que limita una factura medida es el número de llamadas que hace tu integración.
• Capacidad de plataforma — 503 capacity_reached. Un guardia diario a nivel de plataforma. Raro, y no es una falla en tu integración.

Lee tus propios límites, gratis, cuando quieras. GET /api/v1/whoami devuelve el plan, el límite de tasa, la asignación restante y el límite que se aplican a tu cuenta. No cuesta nada y no consume cuota, lo que lo convierte en una mejor respuesta que cualquier número impreso en una página: un número impreso puede estar desactualizado para ti, y ese no puede.

No hay una escalera de planes para buscar el tuyo: whoami es la respuesta, y es gratis. ¿Funcionando a propósito al máximo? Límites aumentados y precios por volumen: support@sirveil.ai.

Semántica de facturación

Un medidor y una factura mensual. Ese es todo el aparato.

• Pospago puro. Cada respuesta completada incrementa el medidor: $0.10 por verificación, $0.35 por barrido. Al final del mes se te factura lo que marcó el medidor. Sin paquetes, sin créditos, sin suscripciones, sin mínimos.
• Cero llamadas, cero dólares. Un mes tranquilo no produce cargo ni factura. Nada se paga por adelantado, así que nada puede caducar y ningún dinero tuyo queda en nuestros libros.
• Medición de Marketplace. El Servicio está disponible para compra a través de AWS Marketplace: esa es toda la lista hoy (Términos de la API, Sección 3.1) — y el uso aparece en tu factura existente de AWS a través del medidor de Marketplace. Un canal nombrado en un artefacto pero no listado en los Términos no es una oferta. Para una compra en Marketplace, el precio publicado en ese listado cuando se hace la llamada es el precio para esa llamada.
• Los cambios en la tarifa requieren al menos 30 días de aviso y nunca se aplican retroactivamente. El volumen comprometido recibe ofertas privadas por debajo de las tarifas publicadas: support@sirveil.ai.
• Los errores facturan $0.00 — consulta Errores. Las matemáticas completas están en /for-business#math.
• Un acierto de caché factura en su totalidad. Haz la misma pregunta dos veces en una ventana corta y puedes recibir la misma respuesta por consistencia — y factura y consume cuota exactamente como una llamada nueva. El caché hace que una respuesta repetida sea consistente, no gratis. Preferimos decirlo aquí antes de que lo encuentres en una factura.
• Una respuesta no servida no factura nada. Si nuestro proveedor de búsqueda está caído, recibes indeterminate con outcome: unserved y un cargo de cero. Pagamos por ese intento; tú no.
• Una negativa registra el costo como null, no cero. No se gastó nada y no se midió nada, y no afirmaremos una medición que nunca hicimos.

Versionado y desaprobación

/api/v1 es la superficie estable: los endpoints, campos de solicitud, estados y envoltura de errores en esta página. Añadimos campos sin aviso: analiza con tolerancia e ignora lo que no reconozcas. No eliminamos ni reutilizamos nada bajo /api/v1 sin un proceso de cambio disruptivo:

• Al menos 30 días de aviso antes de que un cambio disruptivo entre en vigor. Ese es el compromiso que publicamos y al que nos mantenemos, y en la práctica apuntamos a dar mucho más tiempo. Los Términos de la API rigen el acuerdo en sí.
• Anunciado en /scan-api/changelog primero, antes que cualquier otro canal.
• Un cambio disruptivo se lanza como /api/v2; /api/v1 sigue respondiendo durante la ventana de aviso.
• Cualquier cosa marcada como vista previa o aún no construida en esta página queda fuera de ese proceso hasta que se marque como estable. Para eso está la etiqueta.

Donde esta página y el contrato discrepen, gana el contrato. Estos documentos describen cómo se comporta la API y los mantenemos honestos; los Términos de la API, el Aviso de privacidad de la API y la Política de uso aceptable son a lo que realmente estamos obligados. Nada en esta página es una garantía: preferimos decirlo claramente antes de que una bonita frase en los documentos se lea como tal.

Webhooks aún no construidos

Aún no construido**Este no existe todavía.**Está especificado y en la lista de construcción, no enviado — así que no diseñes una integración en torno a él hoy. La forma siguiente es lo que será, y aterriza en /scan-api/changelog cuando sea real. El sondeo funciona ahora, y es gratis.

Cuando se lance: pasa webhook_url en un barrido asíncrono y te enviaremos el informe terminado por POST en lugar de hacerte sondear. Las entregas están firmadas con HMAC-SHA256 sobre el cuerpo crudo, en el encabezado X-Sirveil-Signature — verifícalo antes de confiar en la carga útil.

Entrega (borrador)Copiar

POST https://yourapp.example/hooks/sirveil X-Sirveil-Signature: sha256=6b4f… // HMAC-SHA256 del cuerpo crudo Content-Type: application/json

{ "job_id": "job_9f2c…", "status": "complete", "summary": { … }, "results": [ … ] }

El sondeo GET /api/v1/jobs/:id funciona hoy y seguirá funcionando: los webhooks son una conveniencia, no una dependencia.

Dónde seguir

Ver los recibos

890 ms mediana / 1,463 ms p95 verificaciones (n=18, caché frío), 154 s mediana / 203 s barridos más lentos (n=5) — nuestras ejecuciones en nuestros datos, ejecuciones lentas muy incluidas. Mediciones, no compromisos.

Benchmarks →

Hacer las matemáticas

El medidor interactivo: deslizadores, una factura de ejemplo y toda la tarifa en una página.

Precios →

Obtener una clave

Minutos, no reuniones. El medidor comienza en cero y se queda ahí hasta que llames.

Regístrate →

{"@context": "https://schema.org", "@type": "BreadcrumbList", "itemListElement": [{"@type": "ListItem", "position": 1, "name": "Home", "item": "https://sirveil.ai"}, {"@type": "ListItem", "position": 2, "name": "Sirveil for Business \u2014 Scan API", "item": "https://sirveil.ai/for-business"}, {"@type": "ListItem", "position": 3, "name": "API Docs", "item": "https://sirveil.ai/scan-api/docs"}]}