Documentation · Prynt Reveal

API reference

The Reveal endpoints under `https://api.pryntid.com/v1/reveal/`: one public endpoint the browser script calls, and secret-key endpoints for your servers. v1.1 is current; v1.2 adds signed links and agency workspaces and is rolling out.

Authentication

Server endpoints take a **secret key** in the Authorization header: Authorization: Bearer sk_live_…. Create keys in the console under **Developers → API keys**; never ship a secret key to a browser. The browser script uses the **public key** (pk_live_…) and can only send events.

Test keys (pk_test_…, sk_test_…) resolve everything like live keys but never spend credits and are kept apart in the 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

Method and pathKeySinceWhat it does
POST /v1/reveal/collectpublicv1Events from the browser script (batch of up to 50). You normally never call it yourself.
GET /v1/reveal/session/{sessionId}secretv1The resolution of one session (company, confidences, method, reasons; the person only when verified).
POST /v1/reveal/identifysecretv1 · v1.1Links a first-party identity (email, userId or crmId) to a session or visitor after a login or a form on your side.
GET /v1/reveal/companiessecret · plan APIv1 · v1.1Identified accounts, newest first, with filters and cursor pagination.
GET /v1/reveal/peoplesecret · plan APIv1.1First-party people (candidate / verified), identifiers masked.
GET /v1/reveal/sessionssecret · plan APIv1.1Sessions with their resolution, filters by status, country, score, segment.
POST /v1/reveal/links/signsecretv1.2 (rolling out)A signed, expiring pid token for links you send to your own subscribers.
GET /v1/reveal/workspacessecret · Enterprisev1.2 (rolling out)Client workspaces linked to an agency account.
GET /v1/reveal/workspaces/{clientTenantId}/accountssecret · Enterprisev1.2 (rolling out)A client's accounts, same filters as /companies.

The machine-readable description is the OpenAPI document at https://api.pryntid.com/openapi.json (tag *Reveal*).

GET /v1/reveal/companies

Query parameterMeaning
since, untilISO-8601 window on the last visit; capped by your plan's history window (7 / 30 / 90 / 365 days)
websiteDomain of one of your verified websites
hot1 = only accounts marked hot (hot pages / ICP / score rules)
segmentSegment id: only accounts currently in that segment
statusPOTENTIAL_ACCOUNT, VERIFIED_COMPANY or VERIFIED_PERSON
countryISO-3166-1 alpha-2 code, e.g. DE
minScoreMinimum intent score (0–100)
cursor · page, per_pageCursor wins over page; per_page 1–200, default 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
}

An account whose company was not credited (allowance exhausted) comes back **locked**: locked: true and company.name, domain, linkedinUrl, logoUrl are null, while industry, size, country and the confidence stay visible. Buying a pack or upgrading unlocks it retroactively.

GET /v1/reveal/people

Parameters: since, until, website, status (candidate or verified), includeContact, cursor, page, per_page. Identifiers are always masked (a***@acme.com). With includeContact=1 each item adds contact: {email, name} — only for identities your own forms, logins or imports supplied.

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

/sessions takes since, until, website, status (also ANONYMOUS), country, minScore, segment, includeBots=1, cursor, page, per_page. /session/{sessionId} returns one session by its rvs_ id — handy right after a form submission on your server.

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 }

The three confidences are separate and never merged: companyConfidence (who owns the network), deviceConfidence (same device as before) and personConfidence (only with first-party evidence). resolution.method and resolution.reasons[] say how the company was resolved.

POST /v1/reveal/identify

Body: sessionId or visitorId (one is required), and email, userId or crmId (at least one), plus optional name and consentRef (the basis on which the person shared the data, e.g. signup-form-v3). Returns {status, person}. A person becomes VERIFIED_PERSON only with this kind of first-party evidence; the evidence is stored with the person.

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

Pagination

List responses are {items, page, per_page, total, nextCursor}. Follow nextCursor until it is null; it is stable while new data arrives, unlike 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}

Errors

Every error is {"error": {"code", "message"}}, sometimes with fields (validation) or retryAfter (seconds).

StatuscodeWhen
400bad_requestBody is not a JSON object
401unauthorized · invalid_keyNo Bearer secret key · unknown or disabled key
402plan_featureThe pull API is not in your plan (Scale and up)
403website_not_verified · website_disabled · origin_not_allowed · tenant_inactiveCollect from an unverified / disabled website or a non-allowed origin
404website_unknown · session_unknownNo such website or session for your account
413too_many_eventsMore than 50 events in one collect call
422validation_errorA field is wrong; see fields
429rate_limitedOver the per-minute limit; wait retryAfter seconds
503resolver_error · not_readyTemporary; retry with backoff

Rate limits and usage

  • Pull API (/companies, /people, /sessions): 60 requests per minute per secret key.
  • Collect and identify: up to 600 requests per minute per key (lower on some plans).
  • API calls are counted in **Billing → Usage**; they never spend company credits. Details in Limits.

What changed in v1.1 and v1.2

v1.1 (current)

  • New: GET /v1/reveal/people and GET /v1/reveal/sessions; cursor pagination (nextCursor); until, segment, status, country, minScore filters.
  • Account adds segments[], stage, ownerUserId, intentTrend, locked.
  • identify accepts userId / crmId (stored as a masked linked_id).
  • collect accepts consentSource and the newsletter espToken (hashed, only with consent).
  • Webhook deliveries carry X-Prynt-Version: 1.1 and new events (reveal.segment_entered, reveal.account_momentum, reveal.known_contact, reveal.page_visited).

v1.2 (rolling out)

  • POST /v1/reveal/links/sign {email | contactRef, campaign?, ttlDays?} → {pid, expiresAt}: a signed token for links in emails you send to your own subscribers; contacts that are not subscribed get 422 contact_not_eligible.
  • GET /v1/reveal/workspaces and GET /v1/reveal/workspaces/{clientTenantId}/accounts for agencies (Enterprise).
  • Until an endpoint is enabled on your account it answers 404; the OpenAPI document marks it 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>

Next: Credits

Last updated 2026-11-03 · Limits · Visitor opt-out