Documentação · Prynt Reveal

Referência da API

Os endpoints do Reveal em `https://api.pryntid.com/v1/reveal/`: um público, chamado pelo script do navegador, e os de chave secreta para os seus servidores. A v1.1 é a atual; a v1.2 adiciona links assinados e espaços de agência e está sendo liberada.

Autenticação

Os endpoints de servidor recebem uma **chave secreta** no cabeçalho Authorization: Authorization: Bearer sk_live_…. Crie as chaves no console em **Desenvolvedores → Chaves de API**; nunca envie uma chave secreta para um navegador. O script do navegador usa a **chave pública** (pk_live_…) e só pode enviar eventos.

Chaves de teste (pk_test_…, sk_test_…) resolvem tudo como as live, mas nunca gastam créditos e aparecem separadas no console (?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 e caminhoChaveDesdeO que faz
POST /v1/reveal/collectpúblicav1Eventos do script do navegador (lotes de até 50). Normalmente você não o chama.
GET /v1/reveal/session/{sessionId}secretav1A resolução de uma sessão (empresa, confianças, método, motivos; a pessoa só quando verificada).
POST /v1/reveal/identifysecretav1 · v1.1Vincula uma identidade first-party (e-mail, userId ou crmId) a uma sessão ou visitante depois de um login ou formulário seu.
GET /v1/reveal/companiessecreta · plano com APIv1 · v1.1Contas identificadas, mais recentes primeiro, com filtros e paginação por cursor.
GET /v1/reveal/peoplesecreta · plano com APIv1.1Pessoas first-party (candidata / verificada), identificadores mascarados.
GET /v1/reveal/sessionssecreta · plano com APIv1.1Sessões com a sua resolução, filtros por status, país, pontuação e segmento.
POST /v1/reveal/links/signsecretav1.2 (em liberação)Um token pid assinado e com validade para links que você envia aos seus próprios assinantes.
GET /v1/reveal/workspacessecreta · Enterprisev1.2 (em liberação)Espaços de clientes vinculados a uma conta de agência.
GET /v1/reveal/workspaces/{clientTenantId}/accountssecreta · Enterprisev1.2 (em liberação)As contas de um cliente, com os mesmos filtros de /companies.

A descrição legível por máquina é o documento OpenAPI em https://api.pryntid.com/openapi.json (tag *Reveal*).

GET /v1/reveal/companies

ParâmetroSignificado
since, untilJanela ISO-8601 sobre a última visita; limitada pelo histórico do seu plano (7 / 30 / 90 / 365 dias)
websiteDomínio de um dos seus sites verificados
hot1 = só contas marcadas como quentes (páginas quentes / ICP / regras de pontuação)
segmentId de segmento: só as contas que estão agora nesse segmento
statusPOTENTIAL_ACCOUNT, VERIFIED_COMPANY ou VERIFIED_PERSON
countryCódigo ISO-3166-1 alfa-2, por ex. BR
minScorePontuação de intenção mínima (0–100)
cursor · page, per_pageO cursor tem prioridade sobre page; per_page 1–200, padrão 50
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
}

Uma conta cuja empresa não foi creditada (franquia esgotada) vem **bloqueada**: locked: true e company.name, domain, linkedinUrl, logoUrl como null; setor, porte, país e confiança continuam visíveis. Comprar um pacote ou mudar de plano a desbloqueia retroativamente.

GET /v1/reveal/people

Parâmetros: since, until, website, status (candidate ou verified), includeContact, cursor, page, per_page. Os identificadores vêm sempre mascarados (a***@acme.com). Com includeContact=1 cada item ganha contact: {email, name} — só para identidades fornecidas pelos seus próprios formulários, logins ou importações.

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 e /session/{id}

/sessions aceita since, until, website, status (também ANONYMOUS), country, minScore, segment, includeBots=1, cursor, page, per_page. /session/{sessionId} retorna uma sessão pelo id rvs_ — útil logo depois de receber um formulário no seu 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 }

As três confianças são independentes e nunca se misturam: companyConfidence (quem é dono da rede), deviceConfidence (mesmo dispositivo de antes) e personConfidence (só com evidência first-party). resolution.method e resolution.reasons[] explicam como a empresa foi resolvida.

POST /v1/reveal/identify

Corpo: sessionId ou visitorId (um é obrigatório) e email, userId ou crmId (pelo menos um), além de name e consentRef opcionais (a base pela qual a pessoa compartilhou os dados, por ex. signup-form-v3). Retorna {status, person}. Uma pessoa vira VERIFIED_PERSON só com esse tipo de evidência first-party, que fica guardada com ela.

# 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"}], …}}

Paginação

As listas respondem {items, page, per_page, total, nextCursor}. Siga nextCursor até ser null; ele é estável mesmo com dados novos chegando, ao contrário 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}

Erros

Todo erro é {"error": {"code", "message"}}, às vezes com fields (validação) ou retryAfter (segundos).

StatuscodeQuando
400bad_requestO corpo não é um objeto JSON
401unauthorized · invalid_keyFalta a chave secreta Bearer · chave desconhecida ou desativada
402plan_featureA API não está no seu plano (a partir do Scale)
403website_not_verified · website_disabled · origin_not_allowed · tenant_inactiveColeta de um site não verificado / desativado ou de uma origem não permitida
404website_unknown · session_unknownEsse site ou essa sessão não existe na sua conta
413too_many_eventsMais de 50 eventos em uma chamada de coleta
422validation_errorUm campo está errado; veja fields
429rate_limitedAcima do limite por minuto; aguarde retryAfter segundos
503resolver_error · not_readyTemporário; tente de novo com backoff

Limites e uso

  • API de consulta (/companies, /people, /sessions): 60 requisições por minuto por chave secreta.
  • Coleta e identify: até 600 requisições por minuto por chave (menos em alguns planos).
  • As chamadas à API são contadas em **Faturamento → Uso**; nunca gastam créditos de empresa. Detalhes em Limites.

O que mudou na v1.1 e na v1.2

v1.1 (atual)

  • Novos: GET /v1/reveal/people e GET /v1/reveal/sessions; paginação por cursor (nextCursor); filtros until, segment, status, country, minScore.
  • Account ganha segments[], stage, ownerUserId, intentTrend, locked.
  • identify aceita userId / crmId (guardado como linked_id mascarado).
  • collect aceita consentSource e o espToken de newsletter (com hash, só com consentimento).
  • As entregas de webhooks trazem X-Prynt-Version: 1.1 e eventos novos (reveal.segment_entered, reveal.account_momentum, reveal.known_contact, reveal.page_visited).

v1.2 (em liberação)

  • POST /v1/reveal/links/sign {email | contactRef, campaign?, ttlDays?} → {pid, expiresAt}: um token assinado para os links de e-mails que você envia aos seus próprios assinantes; contatos que não estão subscribed recebem 422 contact_not_eligible.
  • GET /v1/reveal/workspaces e GET /v1/reveal/workspaces/{clientTenantId}/accounts para agências (Enterprise).
  • Enquanto um endpoint não estiver ativado na sua conta ele responde 404; o documento OpenAPI o marca como 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>

Próximo: Créditos

Última atualização 2026-11-03 · Limites · Exclusão do visitante