One schema.
Hosted or integrated.

Authentication

Every documented developer API call carries a secret Bearer token. Secret keys are minted in your console and shown once at creation. Store them in your backend secret manager, never in client code. The key dialog defaults to this server-safe key type.

curl https://proseid.com/api/v1/records \
  -H "Authorization: Bearer proseid_sk_..." \
  -H "Content-Type: application/json"

Missing, invalid, or revoked tokens return 401 Unauthorized. A valid token that lacks the endpoint's validate, records, proof, schemas, or flows scope returns 403 Forbidden. Rate-limited requests return 429 with a Retry-After header.

{
  "error": {
    "code": "validation_failed",
    "message": "the document did not pass validation",
    "details": { ... }
  }
}

Idempotency

Pass an Idempotency-Key header when creating a record, schema, or Flow to make network retries safe. The same key and same request body returns the original resource; the same key with different content returns 409 idempotency_conflict.

curl https://proseid.com/api/v1/records \
  -H "Authorization: Bearer proseid_sk_..." \
  -H "Idempotency-Key: order_8f3a9b2c" \
  -H "Content-Type: application/json" \
  -d '{"flow":"acme/onboarding","responses":{"full_name":"Dana Lee"}}'

• → Use a unique key per logical operation (order ID, claim ID, etc.) — not per HTTP retry.
• → Same key + different body returns 409 Conflict.
• → Keys are scoped to your API key. Two separate keys can use the same Idempotency-Key independently.

Create, prepare, then publish

Management calls use a secret key with the schemas scope. They follow the same lifecycle as the dashboard: creating or replacing a working body does not make it runnable. You must prepare the exact saved body with a plain-language change message, then explicitly publish that prepared version as private or public.

POST /api/v1/schemas
Idempotency-Key: customer-eu-policy-v1

{
  "schema": {
    "protocol": "Proseid_v1.0",
    "schema_id": "acme/can-i-use-ai-eu",
    "version": "1.0.0",
    "metadata": { ... },
    "definitions": { ... },
    "state_model": { ... },
    "logic_tree": [ ... ]
  }
}

→ { "schema_id": "schema-document-id", "id": "schema-document-id", "version": "1.0.0", "status": "working_draft", "duplicate": false }

GET /api/v1/schemas/{id}/draft
→ { "schema": { ... }, "body_hash": "current hash", "prepared_id": null }

PUT /api/v1/schemas/{id}/draft
{
  "schema": { ...complete replacement body... },
  "expected_body_hash": "optional hash returned by GET or the previous save"
}
→ { "schema_id": "schema-document-id", "body_hash": "new hash", "status": "working_draft" }

POST /api/v1/schemas/{id}/prepare
{ "message": "Initial company AI policy" }

→ { "schema_id": "schema-document-id", "prepared_id": "...", "version": "1.0.0" }

POST /api/v1/schemas/{id}/publish
{
  "prepared_id": "...",
  "visibility": "private",
  "changelog": "Initial private release"
}

→ { "schema_id": "schema-document-id", "version": "1.0.0", "visibility": "private" }

POST /api/v1/schemas/{schema_id}/drafts
→ { "schema_id": "schema-document-id", "version": "1.1.0", "body_hash": "...", "status": "working_draft" }

Turn a published schema into a reusable Flow

Call POST /api/v1/flows with a secret key carrying the flows scope. Pass the schema_id returned by schema creation. The schema must already be published, and it may be public from any publisher or private and owned by the API key’s organization. flow_type is required and must be form, guided_assessment, determination, or checklist; it must also be compatible with that exact release.

POST /api/v1/flows
Idempotency-Key: customer-eu-determination

{
  "schema_id": "schema-document-id",
  "schema_version": "latest",
  "flow_type": "determination",
  "title": "Can I use AI?",
  "slug": "can-i-use-ai",
  "visibility": "unlisted",
  "completion_access": "open",
  "presentation_theme": "light",
  "embed_attribution": "full",
  "signing_mode": "none"
}

→ { "flow_id": "flow-document-id", "id": "flow-document-id", "flow_type": "determination", "status": "active", "pricing": { ...frozen price... }, "duplicate": false }

The returned schema_id is the internal ProseID document ID used by Flow creation. It is different from the publisher-qualified logical schema.schema_id stored inside the schema body. Save the returned value. Flow creation returns flow_id and echoes the accepted flow_type.

Run the rules that applied on that date

A schema may contain continuous temporal_map periods. Send effective_at as a real YYYY-MM-DD date to validate or record a historical completion. If omitted, the server uses the current UTC date. Future completion dates are rejected.

Time periods must be ordered, continuous, and non-overlapping; only the final period may have an open end. Rules without a rule-set assignment apply during every period. An invalid map or uncovered date fails closed.

Validate without creating a record

Call POST /api/v1/validate/{publisher}/{slug} to run an answer document against the schema currently bound to a published Flow. This route uses the validate scope and is free: it creates no record, proof, delivery, or debit.

POST /api/v1/validate/acme/employee-onboarding
{
  "responses": { "full_name": "Dana Lee", "start_date": "2026-07-01" },
  "effective_at": "2026-07-01"
}

{
  "valid": true,
  "status": "READY",
  "definitions": { ... },
  "effective_at": "2026-07-01",
  "temporal_context": { "logic_version": "rules_2026", "valid_range": ["2026-01-01", null] },
  "issues": []
}

{ "error": {
  "code": "validation_failed",
  "details": {
    "status": "INCOMPLETE",
    "issues": [ ... ]
  }
} }

Record answers you already collected

POST /api/v1/records is a completion endpoint, not the beginning of an interactive Flow. Your backend sends the final answers it already holds; ProseID resolves the published Flow and pinned schema, validates the answers, charges the organization, encrypts the stored record, signs its proof, and returns the completed recordId. To let a respondent complete the experience on ProseID instead, create a Flow link without supplying responses.

POST /api/v1/records
{
  "flow": "acme/employee-onboarding",
  "responses": { "full_name": "Dana Lee", "start_date": "2026-07-01" },
  "effective_at": "2026-07-01",
  "metadata": { "orderId": "order_8f3a9b2c" }
}

{
  "recordId": "k9Zx7Qm3nR8pT2vB1cY5wJ",
  "status": "completed",
  "interface_language": "en",
  "costMicrons": 200,
	  "balanceAfterMicrons": 9800,
	  "effective_at": "2026-07-01",
	  "logic_version": "rules_2026",
	  "temporal_range": ["2026-01-01", null],
	  "duplicate": false,
	  "delivered": { "email": false, "webhook": true }
}

Know what failed before you retry

Every non-2xx developer response uses the same error.code, error.message, and optional error.details envelope. Branch on the stable code, not the human message. A rejected completion does not create a completed record or debit the organization’s usage balance.

{
  "error": {
    "code": "insufficient_balance",
    "message": "The organization has insufficient balance.",
    "details": {
      "availableMicrons": 100,
      "availableCashMicrons": 0,
      "requiredMicrons": 400,
      "requiredCashMicrons": 200
    }
  }
}

Retrieve the completed record

Call GET /api/v1/records/{recordId} with the records scope. The server confirms that the key belongs to the record's organization and decrypts the response fields from KMS-backed storage. A missing, foreign, pending-deletion, or deleted record returns the same 404 record_not_found response.

GET /api/v1/records/k9Zx7Qm3nR8pT2vB1cY5wJ

{
  "recordId": "k9Zx7Qm3nR8pT2vB1cY5wJ",
  "status": "completed",
  "flow_id": "8f3a9b2c1d4e",
  "schema_id": "employee-onboarding",
  "schema_version": "3.0.0",
  "effective_at": "2026-07-01",
  "logic_version": "rules_2026",
  "temporal_range": ["2026-01-01", null],
  "publisher": "acme",
  "signed": false,
  "costMicrons": 200,
  "completedAt": "2026-07-15T18:42:11.000Z",
  "responses": { "full_name": "Dana Lee", "start_date": "2026-07-01" },
  "metadata": { "orderId": "order_8f3a9b2c" }
}

Resolve a schema release

Call GET /api/v1/schemas/{schemaId} with the schemas scope. Add ?version=3.0.0 to pin an immutable release; without it, the route resolves the current version. Public releases are readable by any organization key. Private and draft schemas are readable only by their owning organization.

The response keeps Registry metadata outside the executable schema body: description, legalReferences, and jurisdictions describe the release but never become respondent inputs.

GET /api/v1/schemas/employee-onboarding?version=3.0.0

{
  "id": "employee-onboarding",
  "title": "Employee onboarding",
  "publisher": "acme",
  "version": "3.0.0",
  "description": "A 72-hour personal-data-breach notification workflow.",
  "legalReferences": [{ "instrument": "Regulation (EU) 2016/679 (GDPR)", "provision": "Article 33", "source_url": "https://eur-lex.europa.eu/eli/reg/2016/679/oj" }],
  "jurisdictions": ["SE", "EEA"],
  "published": true,
  "visibility": "public",
  "deprecated": false,
  "maintenanceStatus": "maintained",
  "lineage": null,
  "schema": { ...canonical schema body... }
}

Verify without trusting our API

Call GET /api/v1/records/{recordId}/proof with the proof scope. Current proofs use an ES256 signature whose private key stays inside Google Cloud KMS. The proof's kid selects a public key from our public JWKS. Save that public key set to verify later without calling ProseID. Add ?format=pdf to download the server-rendered proof certificate instead of JSON.

{
  "proof_version": 2,
  "issuer": "https://proseid.com",
  "canonicalization": "proseid-json-v2",
  "alg": "ES256",
  "kid": "public-key-thumbprint",
  "jwks_uri": "https://proseid.com/.well-known/proseid-jwks.json",
  "signed_at": "2026-07-15T18:42:11.000Z",
  "record_id": "…",
	  "flow_id": "…",
	  "schema_id": "employee-onboarding",
	  "schema_version": "3.0.0",
	  "effective_at": "2026-07-01",
	  "logic_version": "rules_2026",
	  "temporal_range": ["2026-01-01", null],
	  "publisher": "acme",
	  "status": "READY",
  "responses_hash": "…",
  "output_hash": "…",
	  "completed_at": "2026-07-15T18:42:11.000Z",
	  "signing_provider": "",
	  "signing_reference": "",
  "signature": "…"
}

Webhook delivery

A newly created standard Flow costs $0.20 per completed record (200 microns); validation via /api/v1/validate is free. The accepted base price is frozen on the Flow, so a later platform-price change cannot reprice it. When a Flow completes, ProseID immediately POSTs to the Flow's configured webhook URL with a 10-second timeout. A transient failure enters the durable retry queue. Poll GET /api/v1/records/{id} as the source of truth — webhook delivery is separate from completion and billing.

{
  "event": "record.completed",
  "event_version": 1,
  "test": false,
  "record_id": "k9Zx7Qm3nR8pT2vB1cY5wJ",
  "flow_id": "8f3a9b2c1d4e",
  "flow_type": "guided_assessment",
  "interface_language": "en",
  "schema_id": "employee-onboarding",
	  "schema_version": "3.0.0",
	  "effective_at": "2026-07-01",
	  "logic_version": "rules_2026",
	  "temporal_range": ["2026-01-01", null],
	  "publisher": "acme",
	  "signed": false,
	  "signing_mode": "none",
	  "signing_provider": null,
	  "cost_microns": 200,
	  "source": "hosted",
	  "completed_at": "2026-07-15T18:42:11.000Z",
  "metadata": null,
  "responses": { ...Flow answers... },
  "signature": null
}

Verify the request came from us using the X-Proseid-Signature header — an HMAC-SHA256 of the raw body keyed with your webhook secret. X-Proseid-Event is record.completed. The Flow editor can send the same full payload with test: true, actual fields from the exact schema release, and a test record ID. It shows the final HTTP status and response preview before you save, creates no record, and uses no balance.

• → Unsigned completions use signing_mode "none". Basic typed-name signatures use signing_mode "basic" and remain at the Flow’s frozen standard price (currently $0.20 for new Flows).
• → Each Flow has its own webhook secret. You can reveal or copy it from the Flow editor, and regenerate it later; the old secret stops working when the change is saved.
• → Retries use backoff — roughly 2 min, then 10 min, 1 h, 6 h, and 24 h after the first attempt (6 attempts total). After the last attempt, delivery is marked permanently failed and the organization is notified.
• → Respond 2xx within 10s. Anything else (or a timeout) counts as failed and triggers a retry.

Flow links

Instead of POSTing answers yourself, issue a browser-bound link your end user opens and completes. New hosted Flows require these one-time links by default, so a shareable public preview cannot submit or use your balance; opening completion to anyone with the stable link is an explicit Flow setting. The first browser to open an issued link claims it; only that browser can finish it. The hosted Flow uses the experience selected by its publisher—Standard Form, Guided Assessment, Determination or Compliance Checklist—shows the remaining time, and saves unfinished work in that browser, so a refresh or resent link does not erase it. Nothing is billed until they confirm; the Flow’s frozen per-completion price covers the whole experience, including an entire checklist.

POST /api/v1/flow-links
{
  "flow": "acme/employee-onboarding",
  "recipient_email": "[email protected]",
  "send_email": true,
  "expires_in_days": 14
}

	→ { "token": "…", "url": "https://proseid.com/flow-links/…", "status": "pending", "emailed": true }

Poll GET /api/v1/flow-links/{token} for its state (pending → opened → completed | cancelled | expired); once completed it returns the completedRecordId you read via GET /api/v1/records/{id}.

GET /api/v1/flow-links/{token}

	→ {
	  "token": "…",
	  "status": "completed",
	  "flowId": "8f3a9b2c1d4e",
	  "url": "https://proseid.com/flow-links/…",
	  "recipientEmail": "[email protected]",
	  "completedRecordId": "k9Zx7Qm3nR8pT2vB1cY5wJ",
	  "expiresAt": "2026-07-29T18:42:11.000Z",
	  "createdAt": "2026-07-15T18:42:11.000Z"
	}

DELETE /api/v1/flow-links/{token}

→ { "token": "…", "status": "cancelled" }