Documentación · Prynt Reveal

Referencia de la API

Los endpoints de Reveal bajo `https://api.pryntid.com/v1/reveal/`: uno público al que llama el script del navegador y los de clave secreta para tus servidores. v1.1 es la versión actual; v1.2 añade enlaces firmados y espacios de agencia y se está desplegando.

Autenticación

Los endpoints de servidor llevan una **clave secreta** en la cabecera Authorization: Authorization: Bearer sk_live_…. Crea las claves en la consola en **Desarrolladores → Claves de API**; nunca envíes una clave secreta a un navegador. El script del navegador usa la **clave pública** (pk_live_…) y solo puede enviar eventos.

Las claves de test (pk_test_…, sk_test_…) resuelven todo igual que las live, pero nunca gastan créditos y se ven por separado en la consola (?env=test).

curl "https://api.pryntid.com/v1/reveal/companies?per_page=1" \
  -H "Authorization: Bearer sk_live_YOUR_SECRET_KEY"
# 401 unauthorized → no Bearer key · 402 plan_feature → the pull API starts on Scale

Endpoints

Método y rutaClaveDesdeQué hace
POST /v1/reveal/collectpúblicav1Eventos del script del navegador (lotes de hasta 50). Normalmente no lo llamas tú.
GET /v1/reveal/session/{sessionId}secretav1La resolución de una sesión (empresa, confianzas, método, motivos; la persona solo si está verificada).
POST /v1/reveal/identifysecretav1 · v1.1Vincula una identidad first-party (email, userId o crmId) a una sesión o visitante tras un login o un formulario tuyo.
GET /v1/reveal/companiessecreta · plan con APIv1 · v1.1Cuentas identificadas, las más recientes primero, con filtros y paginación por cursor.
GET /v1/reveal/peoplesecreta · plan con APIv1.1Personas first-party (candidata / verificada), identificadores enmascarados.
GET /v1/reveal/sessionssecreta · plan con APIv1.1Sesiones con su resolución, filtros por estado, país, puntuación y segmento.
POST /v1/reveal/links/signsecretav1.2 (en despliegue)Un token pid firmado y con caducidad para enlaces que envías a tus propios suscriptores.
GET /v1/reveal/workspacessecreta · Enterprisev1.2 (en despliegue)Espacios de clientes vinculados a una cuenta de agencia.
GET /v1/reveal/workspaces/{clientTenantId}/accountssecreta · Enterprisev1.2 (en despliegue)Las cuentas de un cliente, con los mismos filtros que /companies.

La descripción legible por máquina es el documento OpenAPI en https://api.pryntid.com/openapi.json (etiqueta *Reveal*).

GET /v1/reveal/companies

ParámetroSignificado
since, untilVentana ISO-8601 sobre la última visita; limitada por el historial de tu plan (7 / 30 / 90 / 365 días)
websiteDominio de uno de tus sitios verificados
hot1 = solo cuentas marcadas como calientes (páginas calientes / ICP / reglas de puntuación)
segmentId de segmento: solo las cuentas que están ahora en ese segmento
statusPOTENTIAL_ACCOUNT, VERIFIED_COMPANY o VERIFIED_PERSON
countryCódigo ISO-3166-1 alfa-2, p. ej. ES
minScorePuntuación de intención mínima (0–100)
cursor · page, per_pageEl cursor tiene prioridad sobre page; per_page 1–200, 50 por defecto
curl "https://api.pryntid.com/v1/reveal/companies?website=example.com&since=2026-11-01T00:00:00Z&hot=1&per_page=50" \
  -H "Authorization: Bearer sk_live_YOUR_SECRET_KEY"

{
  "items": [{
    "id": 4182, "websiteId": 12, "status": "VERIFIED_COMPANY", "companyConfidence": 0.86,
    "company": { "name": "Acme GmbH", "domain": "acme.de", "industry": "Software", "sizeBucket": "201-500",
                 "country": "DE", "city": "Munich", "kind": "business", "confidence": 0.86, "locked": false,
                 "provenance": { "sourceId": "asn", "license": "…", "fetchedAt": "2026-11-02T08:00:00Z" } },
    "sessionsCount": 4, "pagesCount": 11, "peopleCount": 0, "intentScore": 72, "hot": true, "icpMatch": true,
    "topPages": [{ "path": "/pricing", "views": 3 }], "segments": [{ "id": 3, "name": "DACH SaaS", "enteredAt": "…" }],
    "stage": "new", "ownerUserId": null, "intentTrend": 18, "locked": false,
    "firstSeenAt": "2026-11-01T09:12:00Z", "lastSeenAt": "2026-11-03T10:00:00Z"
  }],
  "page": 1, "per_page": 50, "total": 1, "nextCursor": null
}

Una cuenta cuya empresa no se acreditó (asignación agotada) llega **bloqueada**: locked: true y company.name, domain, linkedinUrl, logoUrl a null; sector, tamaño, país y confianza siguen visibles. Comprar un paquete o subir de plan la desbloquea de forma retroactiva.

GET /v1/reveal/people

Parámetros: since, until, website, status (candidate o verified), includeContact, cursor, page, per_page. Los identificadores siempre van enmascarados (a***@acme.com). Con includeContact=1 cada elemento añade contact: {email, name} — solo para identidades que aportaron tus propios formularios, logins o importaciones.

curl "https://api.pryntid.com/v1/reveal/people?status=verified&includeContact=1" -H "Authorization: Bearer sk_live_YOUR_SECRET_KEY"

{ "items": [{ "id": 81, "status": "verified", "displayName": "Ann Lee", "companyId": 902, "personConfidence": 0.95,
              "identifiers": [{ "kind": "email", "verified": true, "masked": "a***@acme.com" }],
              "evidence": [{ "type": "form", "sourceId": "demo-form", "consentRef": "demo-form", "collectedAt": "…" }],
              "contact": { "email": "[email protected]", "name": "Ann Lee" } }],   // contact: only with includeContact=1
  "page": 1, "per_page": 50, "total": 1, "nextCursor": null }

GET /v1/reveal/sessions y /session/{id}

/sessions acepta since, until, website, status (también ANONYMOUS), country, minScore, segment, includeBots=1, cursor, page, per_page. /session/{sessionId} devuelve una sesión por su id rvs_ — útil justo después de recibir un formulario en tu servidor.

curl "https://api.pryntid.com/v1/reveal/session/rvs_8f2c…" -H "Authorization: Bearer sk_live_YOUR_SECRET_KEY"

{ "sessionId": "rvs_8f2c…", "status": "VERIFIED_COMPANY",
  "companyConfidence": 0.86, "deviceConfidence": 0.97, "personConfidence": 0,
  "resolution": { "method": "global_asn", "reasons": ["network_asn"], "asnType": "business" },
  "paths": ["/pricing", "/docs"], "country": "DE", "intentScore": 64, "hot": true, "consent": true, "person": null }

Las tres confianzas son independientes y nunca se mezclan: companyConfidence (quién es dueño de la red), deviceConfidence (mismo dispositivo que antes) y personConfidence (solo con evidencia first-party). resolution.method y resolution.reasons[] explican cómo se resolvió la empresa.

POST /v1/reveal/identify

Cuerpo: sessionId o visitorId (uno es obligatorio) y email, userId o crmId (al menos uno), más name y consentRef opcionales (la base con la que la persona compartió sus datos, p. ej. signup-form-v3). Devuelve {status, person}. Una persona pasa a VERIFIED_PERSON solo con este tipo de evidencia first-party, que se guarda con ella.

# After a login or a form on YOUR server: link the person to the browser session (first-party evidence)
curl -X POST https://api.pryntid.com/v1/reveal/identify \
  -H "Authorization: Bearer sk_live_YOUR_SECRET_KEY" -H "Content-Type: application/json" \
  -d '{"sessionId": "rvs_…", "email": "[email protected]", "name": "Ann Lee", "consentRef": "signup-terms-v3"}'

# → 200 {"status": "VERIFIED_PERSON", "person": {"id": 81, "status": "verified", "displayName": "Ann Lee",
#        "identifiers": [{"kind": "email", "verified": true, "masked": "a***@acme.com"}],
#        "evidence": [{"type": "login", "consentRef": "signup-terms-v3", "collectedAt": "2026-11-03T10:02:11Z"}], …}}

Paginación

Las listas responden {items, page, per_page, total, nextCursor}. Sigue nextCursor hasta que sea null; es estable aunque lleguen datos nuevos, a diferencia de page.

import os, time, requests   # Python: pull every account identified since a date

URL = "https://api.pryntid.com/v1/reveal/companies"
headers = {"Authorization": f"Bearer {os.environ['PRYNT_SECRET_KEY']}"}
params = {"since": "2026-11-01T00:00:00Z", "per_page": 200}
while True:
    r = requests.get(URL, headers=headers, params=params, timeout=30)
    if r.status_code == 429:                       # 60 requests / minute per secret key
        time.sleep(r.json()["error"].get("retryAfter", 1)); continue
    r.raise_for_status()
    page = r.json()
    for account in page["items"]:
        ...                                        # upsert into your warehouse / CRM
    if not page["nextCursor"]:
        break
    params = {"cursor": page["nextCursor"], "per_page": 200}

Errores

Todos los errores son {"error": {"code", "message"}}, a veces con fields (validación) o retryAfter (segundos).

EstadocodeCuándo
400bad_requestEl cuerpo no es un objeto JSON
401unauthorized · invalid_keyFalta la clave secreta Bearer · clave desconocida o desactivada
402plan_featureLa API no está en tu plan (desde Scale)
403website_not_verified · website_disabled · origin_not_allowed · tenant_inactiveRecogida desde un sitio no verificado / desactivado o un origen no permitido
404website_unknown · session_unknownNo existe ese sitio o esa sesión en tu cuenta
413too_many_eventsMás de 50 eventos en una llamada de recogida
422validation_errorUn campo es incorrecto; mira fields
429rate_limitedPor encima del límite por minuto; espera retryAfter segundos
503resolver_error · not_readyTemporal; reintenta con backoff

Límites y uso

  • API de consulta (/companies, /people, /sessions): 60 peticiones por minuto por clave secreta.
  • Recogida e identify: hasta 600 peticiones por minuto por clave (menos en algunos planes).
  • Las llamadas a la API se cuentan en **Facturación → Uso**; nunca gastan créditos de empresa. Detalles en Límites.

Qué cambió en v1.1 y v1.2

v1.1 (actual)

  • Nuevos: GET /v1/reveal/people y GET /v1/reveal/sessions; paginación por cursor (nextCursor); filtros until, segment, status, country, minScore.
  • Account añade segments[], stage, ownerUserId, intentTrend, locked.
  • identify acepta userId / crmId (guardado como linked_id enmascarado).
  • collect acepta consentSource y el espToken de newsletter (con hash, solo con consentimiento).
  • Las entregas de webhooks llevan X-Prynt-Version: 1.1 y eventos nuevos (reveal.segment_entered, reveal.account_momentum, reveal.known_contact, reveal.page_visited).

v1.2 (en despliegue)

  • POST /v1/reveal/links/sign {email | contactRef, campaign?, ttlDays?} → {pid, expiresAt}: un token firmado para los enlaces de emails que envías a tus propios suscriptores; los contactos que no están subscribed reciben 422 contact_not_eligible.
  • GET /v1/reveal/workspaces y GET /v1/reveal/workspaces/{clientTenantId}/accounts para agencias (Enterprise).
  • Mientras un endpoint no esté activado en tu cuenta responde 404; el documento OpenAPI lo marca x-status: planned.
# v1.2 (rolling out): a signed, expiring token for links you send to YOUR OWN subscribers
curl -X POST https://api.pryntid.com/v1/reveal/links/sign \
  -H "Authorization: Bearer sk_live_YOUR_SECRET_KEY" -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "campaign": "nov-newsletter", "ttlDays": 30}'

# → 200 {"pid": "…", "expiresAt": "2026-12-03T10:00:00Z"}
# → 422 contact_not_eligible   when the contact is not 'subscribed' in your contact index
# Append it to the link: https://example.com/webinar?prynt_pid=<pid>

Siguiente: Créditos

Última actualización 2026-11-03 · Límites · Exclusión del visitante