Verifications API

A verification asks a person to prove one or more things. You create it, send its link, and read the answers, each signed by Prson. The person answers in the Prson app and decides what to share.

Prices

How the price is reserved and spent: How you are charged.

Authentication

Send your key as Authorization: Bearer prs_live_… (or prs_sandbox_…) to https://api.prson.net. Keys come from the developer console and default to the scopes verifications:read and verifications:write. Keep keys on your server. AI agents can also connect with OAuth: see MCP.

Create a verification

POST /v1/verifications reserves the price from your balance and returns the verification with its share_url (201). Send the link to the person yourself.

curl -X POST https://api.prson.net/v1/verifications \
  -H "Authorization: Bearer $PRSON_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: booking-4821" \
  -d @- <<'JSON'
{
  "title": "Confirm you're over 18 and show your ID to rent a car",
  "requirements": [
    { "type": "fact", "fact": "age_gte_18" },
    { "type": "property", "property": "family_name" },
    { "type": "document", "require_document_verification": true, "document_types": ["passport", "national_id"] },
    { "type": "selfie", "optional": true }
  ],
  "expires_in_hours": 48,
  "external_ref": "booking-4821",
  "metadata": { "branch": "Lisbon airport" }
}
JSON

Body

A requirement

Every requirement takes these, plus the fields of its type:

Every fact id, property type and capture, with an example: What you can ask for. Send Idempotency-Key to make retries safe: the same key returns the same verification (200, replayed: true) instead of a second one.

Quote

POST /v1/verifications/quote takes the same body (title optional) and says what creating it would reserve now, for your key's app: discounts, a free plan's allowance, sandbox. It creates nothing.

curl -X POST https://api.prson.net/v1/verifications/quote \
  -H "Authorization: Bearer $PRSON_API_KEY" -H "Content-Type: application/json" \
  -d '{ "requirements": [{ "type": "fact", "fact": "age_gte_18" }] }'

# → { "quote": { "regular_cents": 100, "discount": { "kind": "launch", "percent": 50 … },
#                "price_cents": …, "reserved_cents": …, "test": false, "sources": { "document": "facts" },
#                "source_cents": { "base": …, "document": …, "signature": 0 },
#                "requirements": [{ "requirement": 0, "source": "document_facts", "premium_cents": 0 }] } }

Get, list and cancel

GET /v1/verifications/{id} returns the verification with every answer. Status moves open → partially_fulfilled (some requirements answered) → fulfilled (one person answered every required one), or ends cancelled or expired. Several people can answer the same link.

# Newest first, 25 a page; pass next_cursor back as cursor.
curl "https://api.prson.net/v1/verifications?status=fulfilled&limit=25" -H "Authorization: Bearer $PRSON_API_KEY"

# Cancel: the link stops working, released_cents goes back to your balance.
curl -X POST https://api.prson.net/v1/verifications/$ID/cancel -H "Authorization: Bearer $PRSON_API_KEY"

# A file from an answer (names in the response's "files")
curl -o selfie.jpg https://api.prson.net/v1/verifications/$ID/proofs/$PROOF_ID/photo -H "Authorization: Bearer $PRSON_API_KEY"

Responses

Each item of verification.responses is one answer to one requirement:

The verification also has charge (reserved_cents, spent_cents, any discount or allowance) and test: true in sandbox.

Documents to sign

Upload a PDF, then ask for a document_signature. The person reads every page in the Prson app and signs with a certificate naming them as their chip-read passport or ID card does. You get the signed PDF (PAdES B-T, timestamped): your file plus the signature, so its first bytes hash to the sha256 you uploaded. It is an advanced electronic signature under eIDAS, not a qualified one.

# 1. Upload the PDF (at most 12 MB, not encrypted)
curl -X POST "https://api.prson.net/v1/verifications/documents?name=rental-agreement.pdf" \
  -H "Authorization: Bearer $PRSON_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @rental-agreement.pdf
# → { "document": { "id": "vdoc_…", "sha256": "…", "size": 48213, "pages": 3, "unused_expires_at": … } }

# 2. Ask for a signature on it
curl -X POST https://api.prson.net/v1/verifications \
  -H "Authorization: Bearer $PRSON_API_KEY" -H "Content-Type: application/json" \
  -d '{ "title": "Sign the rental agreement",
        "requirements": [{ "type": "document_signature", "document_id": "vdoc_…",
                           "signature_position": { "page": 3, "x": 72, "y": 96, "width": 180, "height": 48 } }] }'

You can also send JSON { "content_base64", "name" }. An upload no verification uses is deleted after a week; the signed PDF is deleted 30 days after the verification expires.

Webhooks

Add an endpoint and Prson POSTs events to it as they happen, instead of you polling.

curl -X POST https://api.prson.net/v1/org/webhooks \
  -H "Authorization: Bearer $PRSON_API_KEY" -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/prson/webhook", "events": ["verification.completed", "verification.slot_verified"] }'
# → { "endpoint": { "id": "whe_…", … }, "secret": "whsec_…" }   the secret is shown once

Each delivery is JSON { id, type, created_at, api_version, data } with two headers: Prson-Event-Id (an idempotency key: a delivery can arrive twice) and Prson-Signature. Check the signature and that t is recent. Reply 2xx within 10 seconds; failures are retried with backoff for about a day.

import { createHmac, timingSafeEqual } from "node:crypto";

// Prson-Signature: t={unix seconds},v1={hex HMAC-SHA256(secret, "{t}.{raw body}")}
export function isFromPrson(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(String(header).split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  const got = Buffer.from(parts.v1 ?? "", "hex");
  return got.length === expected.length && timingSafeEqual(got, expected);
}

// Express: keep the raw body for the check.
app.post("/prson/webhook", express.raw({ type: "application/json" }), (req, res) => {
  if (!isFromPrson(req.body.toString("utf8"), req.get("Prson-Signature"), process.env.PRSON_WEBHOOK_SECRET)) return res.sendStatus(400);
  const event = JSON.parse(req.body);          // { id, type, created_at, api_version, data: { verification, response? } }
  // Prson-Event-Id is an idempotency key: a delivery can arrive twice.
  res.sendStatus(200);
});

Checking a verdict

Every answer carries verdict_signature: { envelope, signature, kid }: Prson's RS256 signature over the canonical JSON of the envelope, which names the verification, the requirement, the level and the time, and commits to each disclosed value. verdict_disclosures holds the values as [salt, kind, id, value]. Keep both to prove later, offline, exactly what Prson vouched for.

import { verifyVerdict } from "@prson/login-verifier";

const keys = await fetch("https://api.prson.net/v1/company/public-key").then((r) => r.json());
const r = response; // one item of verification.responses
const result = verifyVerdict(r.verdict_signature.envelope, r.verdict_signature.signature, r.verdict_disclosures, {
  kid: r.verdict_signature.kid,
  keys: keys.verificationKeys,
});
// result.ok: Prson signed this answer, and every disclosed value is covered by the signature.

Errors

Errors are JSON: { "error": "code", "message": "…" }, sometimes with more fields.

Rate limits and limits

• Too many requests in a short time get 429 too_many_requests: wait and retry with backoff. Some routes have daily limits, named in the error.
• 1 to 10 requirements per verification; a title up to 200 characters; metadata up to 4 KB.
• A link works 1 to 168 hours (default 72).
• A key can have a spend cap: past it, creating is refused with 422.

Sandbox and production

Apps in sandbox create free verifications marked test; they can't email people. Answer them with the Prson app like any other. Production needs a verified developer and a topped-up balance or an approved free plan; the console shows what's missing. Phone and address requirements work only where Prson can verify them: capabilities in GET /v1/verifications/requirements says so, and asking for one that is off gets 422 requirement_unavailable.

How you are charged

Creating a verification reserves its price from your prepaid balance. It is spent as answers verify: the base with the first verified answer, the ID check with the first verified answer that used the chip, the signature with the signed PDF, each premium with its requirement's answer. The rest goes back when you cancel or it expires. Nobody answers: nothing is charged. POST /v1/verifications/quote prices a request without creating it.

A capture that is checked against the chip (require_document_verification or required_facts) uses the ID check's facts price; a selfie, photo or document photo that isn't uses only the base. The larger of the launch and volume discounts applies, never both. Volume discounts: 25% from the 1,001th production verification of a month; 40% from the 10,001th production verification of a month. Open-source apps get 1,000 verifications a month free, non-commercial ones 100. Which price each requirement uses is in What you can ask for; the live prices are in GET /v1/verifications/requirements.