Version: 1.0

Click Management API

The Propper Click API provides consent and clickwrap management for websites and applications. Create templates, publish versioned policies, deploy them to domains, and collect legally-binding acceptance records with full evidence bundles.

---

Base URL

https://api.propper.ai/v1/click

Authentication

OAuth 2.0 Bearer token:

Authorization: Bearer <access_token>

OAuth Scopes

• click:admin: Full administrative access (create, update, delete)
• click:read: Read-only access to templates, deployments, and acceptances
• click:accept: Mint hosted acceptance links, read their status and revoke them (also included in click:write and click:admin)

Key Endpoints

• Templates: Create and manage consent/clickwrap templates
• Template Versions: Publish, archive, and manage versioned content
• Deployments: Deploy templates to domains and control activation
• Acceptances: View acceptance records and evidence bundles
• Acceptance links: Mint per-signer links to a Propper-hosted acceptance page, read their status and revoke them

---

Request correlation

Every response (success and error) includes an x-request-id header (a UUID) and a traceparent header (W3C Trace Context). Error bodies also carry the same id as requestId. Quote x-request-id when contacting support to pinpoint the exact request, and use it to correlate the API with your own logs. Send your own traceparent to tie a multi-call workflow under one trace.

---

Errors

Every error response has the same JSON body:

{
  "errorCode": "CLICK_VALIDATION_FAILED",
  "message": "Request validation failed",
  "requestId": "0b6f3a52-9a44-4f4b-9c1e-6a1f0e0f7c11",
  "details": [
    { "field": "name", "message": "name must be a string", "code": "isString" }
  ]
}

• errorCode is a stable code you can branch on. The HTTP status says the class of failure; the code says which one. New codes may be added, so treat an unknown code like the default code for its status.
• message is a short explanation for a person. Do not parse it.
• requestId is the same value as the x-request-id response header.
• details appears only on validation failures (400 CLICK_VALIDATION_FAILED, and a 422 that names the field it rejects). Each entry names the field, what is wrong in message, and the rule in code. A server error (5xx) never carries details, and its message is generic.
• requiredEntitlement appears only with 403 ENTITLEMENT_REQUIRED and names the entitlement your account needs, such as click.access.

Error codes

Code	Status	Meaning
CLICK_BAD_REQUEST	400	The request is malformed or cannot be processed as sent.
CLICK_VALIDATION_FAILED	400	A field of the request is invalid. details names each field and the rule it broke.
CLICK_UNAUTHORIZED	401	The credentials are missing, invalid or expired.
CLICK_FORBIDDEN	403	The credentials are valid but the token lacks the required scope, or the resource belongs to another organization.
CLICK_NOT_FOUND	404	The resource does not exist in your organization.
CLICK_CONFLICT	409	The request conflicts with the current state of a resource, such as a duplicate.
CLICK_UNPROCESSABLE	422	The request is well formed but cannot be applied.
CLICK_RATE_LIMITED	429	Too many requests. Retry after a pause.
CLICK_INTERNAL_ERROR	500	An unexpected error on our side. Quote the requestId when contacting support.
CLICK_SERVICE_UNAVAILABLE	503	The service is temporarily unavailable. Retry with backoff.
CLICK_DEPLOYMENT_NOT_FOUND	404	No deployment with this ID exists in your organization.
CLICK_DEPLOYMENT_INACTIVE	404	The deployment exists but is not active, so it serves nothing.
CLICK_CONTENT_MISSING	500	The deployment has no content to serve.
CLICK_CONTENT_UNAVAILABLE	503	The deployment's content is temporarily unavailable. Retry with backoff.
CLICK_RENDER_UPSTREAM_UNAVAILABLE	503	Rendering is temporarily unavailable. Retry with backoff.
CLICK_ACCEPT_UPSTREAM_UNAVAILABLE	503	Recording the acceptance is temporarily unavailable. Nothing was recorded. Retry with backoff.
CLICK_ACCEPT_OUTCOME_UNKNOWN	504	The accept call timed out or dropped after the request may have reached the recorder, so the acceptance may or may not be recorded. Retry with the same X-Idempotency-Key: the answer is the receipt if it was recorded, or a fresh attempt if not.
CLICK_DASHBOARD_UPSTREAM_UNAVAILABLE	503	The dashboard metrics are temporarily unavailable. Retry with backoff.
CLICK_CHECKSUM_MISMATCH	422	The checksum sent with an acceptance is not the checksum of the content the deployment serves. Nothing is recorded.
CLICK_VERSION_NOT_SERVED	422	The version named by an acceptance is not the version the deployment serves, nor one it served in the last 15 minutes. Nothing is recorded.
CLICK_DEPLOYMENT_HAS_REVISIONS	409	A deployment with revisions is history that evidence points at: deactivate it instead of deleting it.
CLICK_NOTHING_CHANGED	409	The draft equals the latest published version, so there is nothing to publish.
CLICK_VERSION_CONFLICT	409	Another version was published while this one was being prepared. Review the new version and publish again.
CLICK_TEMPLATE_ARCHIVED	409	The template is archived, so it cannot be published, edited or deployed.
CLICK_FIRST_PUBLISH_MUST_BE_MAJOR	422	The first publish of a template is version 1.0.0 and must be a MAJOR.
CLICK_CONSPICUOUSNESS_ACK_REQUIRED	422	The presentation changes were flagged, and publishing them as a PATCH needs a conspicuousness acknowledgment.
CLICK_REACCEPT_GATE_REQUIRED	422	A MAJOR that follows an earlier version needs a re-acceptance gate: IMMEDIATE, BY_DEADLINE (with a future deadline) or NEXT_VISIT.
CLICK_GATE_NOT_APPLICABLE	422	A re-acceptance gate, deadline or affected set applies only to a MAJOR that follows an earlier version.
CLICK_LINKED_DOCUMENT_UNREACHABLE	422	A document linked from the template could not be fetched and hashed, so the version was not published.
CLICK_TEMPLATE_NOT_PUBLISHABLE	422	The draft cannot be published, for example because it has no content in any locale.
CLICK_CONTENT_UNSAFE	422	A body contains markup that would have to be removed, such as a script, an event handler or a tag outside the allowed set. Nothing was written; the message names what would be removed.
CLICK_DEPLOYMENT_SLOT_TAKEN	409	A deployment already exists for this environment, domain, path and variant.
CLICK_REVISION_CONFLICT	409	The deployment changed while this request was being applied. Read it again and retry.
CLICK_NOTHING_TO_CHANGE	409	The deployment already serves that version, or already has those settings.
CLICK_VERSION_TEMPLATE_MISMATCH	409	The version belongs to a different template than the deployment.
CLICK_IDEMPOTENCY_KEY_REUSED	422	The X-Idempotency-Key was already used for a different request body. Nothing is recorded.
CLICK_DEPLOYMENT_ENVIRONMENT_LOCKED	409	The deployment has recorded acceptances, so its environment cannot change. Create a new deployment for the other environment.
CLICK_RETURN_URL_INVALID	400	The return URL is not allowed: it must use https, carry no credentials and be an allowed origin for the deployment. details names the reason.
CLICK_HOSTED_TYPE_UNSUPPORTED	422	The hosted acceptance page serves static agreements only; this deployment's template is of another type.
CLICK_ACCEPTANCE_LINK_NOT_FOUND	404	No acceptance link with this ID exists in your organization.
CLICK_ACCEPTANCE_LINK_COMPLETED	409	The signer already accepted or declined through this link, so it can no longer be revoked.
CLICK_ACCEPTANCE_LINK_MINT_CONFLICT	409	Another mint for the same deployment and signer is in progress. Retry the request.
ENTITLEMENT_REQUIRED	403	Your account does not include Click. requiredEntitlement names the entitlement to add. This is the platform code every Propper API returns for a missing entitlement, so it has no CLICK_ prefix.

Authentication

HTTP: Bearer Auth

OAuth 2.0 Bearer token

Security Scheme Type:	http
HTTP Authorization Scheme:	bearer
Bearer format:	JWT

Contact

Propper Support: support@propper.ai

URL: https://propper.ai