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 path | Key | Since | What it does |
|---|---|---|---|
POST /v1/reveal/collect | public | v1 | Events from the browser script (batch of up to 50). You normally never call it yourself. |
GET /v1/reveal/session/{sessionId} | secret | v1 | The resolution of one session (company, confidences, method, reasons; the person only when verified). |
POST /v1/reveal/identify | secret | v1 · v1.1 | Links 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/companies | secret · plan API | v1 · v1.1 | Identified accounts, newest first, with filters and cursor pagination. |
GET /v1/reveal/people | secret · plan API | v1.1 | First-party people (candidate / verified), identifiers masked. |
GET /v1/reveal/sessions | secret · plan API | v1.1 | Sessions with their resolution, filters by status, country, score, segment. |
POST /v1/reveal/links/sign | secret | v1.2 (rolling out) | A signed, expiring pid token for links you send to your own subscribers. |
GET /v1/reveal/workspaces | secret · Enterprise | v1.2 (rolling out) | Client workspaces linked to an agency account. |
GET /v1/reveal/workspaces/{clientTenantId}/accounts | secret · Enterprise | v1.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 parameter | Meaning |
|---|---|
since, until | ISO-8601 window on the last visit; capped by your plan's history window (7 / 30 / 90 / 365 days) |
website | Domain of one of your verified websites |
hot | 1 = only accounts marked hot (hot pages / ICP / score rules) |
segment | Segment id: only accounts currently in that segment |
status | POTENTIAL_ACCOUNT, VERIFIED_COMPANY or VERIFIED_PERSON |
country | ISO-3166-1 alpha-2 code, e.g. DE |
minScore | Minimum intent score (0–100) |
cursor · page, per_page | Cursor 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).
| Status | code | When |
|---|---|---|
| 400 | bad_request | Body is not a JSON object |
| 401 | unauthorized · invalid_key | No Bearer secret key · unknown or disabled key |
| 402 | plan_feature | The pull API is not in your plan (Scale and up) |
| 403 | website_not_verified · website_disabled · origin_not_allowed · tenant_inactive | Collect from an unverified / disabled website or a non-allowed origin |
| 404 | website_unknown · session_unknown | No such website or session for your account |
| 413 | too_many_events | More than 50 events in one collect call |
| 422 | validation_error | A field is wrong; see fields |
| 429 | rate_limited | Over the per-minute limit; wait retryAfter seconds |
| 503 | resolver_error · not_ready | Temporary; 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/peopleandGET /v1/reveal/sessions; cursor pagination (nextCursor);until,segment,status,country,minScorefilters. Accountaddssegments[],stage,ownerUserId,intentTrend,locked.identifyacceptsuserId/crmId(stored as a maskedlinked_id).collectacceptsconsentSourceand the newsletterespToken(hashed, only with consent).- Webhook deliveries carry
X-Prynt-Version: 1.1and 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 notsubscribedget422 contact_not_eligible.GET /v1/reveal/workspacesandGET /v1/reveal/workspaces/{clientTenantId}/accountsfor agencies (Enterprise).- Until an endpoint is enabled on your account it answers
404; the OpenAPI document marks itx-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> Last updated 2026-11-03 · Limits · Visitor opt-out