{ "openapi": "3.1.0", "info": { "title": "Simplifi Platform API", "version": "1.1", "contact": { "email": "easy@simplifi.ro", "url": "https://www.simplifi.ro/developers" }, "license": { "name": "Proprietary", "url": "https://www.simplifi.ro/" }, "description": "One API call puts a PDF in front of the people who have to sign it. How each\nof them signs is a per-signer choice: a **simple signature** confirmed by a\ncode, a **one-shot qualified certificate** issued after identity\nverification, or the person's **own long-term certificate** on their Simplifi\naccount. New here? Start with the\n[overview](/publicapi/v1/docs/platform) for the guided tour; this page is the\nfull endpoint reference.\n\n## How the pieces fit\n\n`POST /publicapi/v1/send-document` uploads the PDF(s), names the signers and\nreturns a signing link per signer. Two decisions shape your integration: who\nruns the signing process, and how each signer signs.\n\n### Who runs the signing process\n\n**1. Simplifi takes over** (`send_email: 1`). Simplifi emails each signer the\ninvitation, hosts the signing and sends the completion notice. Your part ends\nwith the call; the `document.completed` webhook (or a poll) tells you when to\ndownload the signed PDF and the Certificate of Completion.\n\n**2. You include signing in your own product** (`send_email: 0`, default).\nNo email leaves Simplifi. The response gives you a `signing_url` per signer\nand your product puts it in front of them: a button in your web or mobile\napp, your own email or SMS, a deep link. The signer signs on the\nSimplifi-hosted signing page and is sent back to your `return_url` with a\nsigned outcome, so they land on the screen they left. They see no Simplifi\nemails and no create-an-account prompts; to you, it is a step of your own\nflow.\n\n### How each signer signs\n\nEach signer has a `kind`; kinds mix on one document. These are three\ndifferent signer types, not stages: pick the one that fits each signer.\n\n**1. Simple signature** (`kind: simple`). Anyone, no account. The signer\nopens the link, reads the document, accepts the terms, confirms a one-time\ncode (an SMS code when you run the process; the email link itself when\nSimplifi does) and signs. Simplifi applies its **qualified electronic seal**\nin the signer's name; the Certificate of Completion records the name, the\nverified channel, time and IP. A simple electronic signature (eIDAS SES):\nconsents, acknowledgements, everyday agreements.\n\n**2. Qualified signature, one-shot certificate** (`kind: qualified`). Anyone,\nno account. The same journey plus **identity verification** on the page: the\nsigner photographs their ID document and passes a liveness check; a qualified\ncertificate is issued to them for this signing only and signs the document.\nA qualified electronic signature (eIDAS QES), equivalent to a handwritten one,\nwith no onboarding; identity verification is repeated every time.\n\n**3. Qualified signature, long-term certificate** (`kind: account`). The\nsigner already holds a qualified certificate on their own Simplifi account,\nissued once after identity verification (partners with a sponsorship program\nonboard their users through the API, see *Qualified signatures, long-term\ncertificates*).\nNo identity verification is repeated. Two ways to sign:\n\n- **The signer opens the link and logs in** (single sign-on if already\n signed in), then confirms the signature with their authenticator app.\n- **The signer has authorized your application** (OAuth on your own API\n client). The same link then works without the signer visiting any page:\n your software performs the signing step through the API, authorized by\n the signer's authenticator code. Users can disconnect your app at any time\n (**Connected apps**).\n\n## Track, collect, cancel\n\nWhatever the kind: `document.*` webhooks, `GET /publicapi/v1/documents/{uuid}`,\nthe signed PDF, the sealed Certificate of Completion, cancel.\n\n## Access and pricing\n\n**There is no API fee and nothing to apply for.** A company admin creates the\nAPI client in the platform's API Settings, a user consents once via OAuth\nwhen you act for them, and the API works. Usage\nbills per act through the same credits as the web application (envelopes,\nsignature packs, one-sided documents); the relevant endpoints return stable\n`insufficient_*_balance` errors when a balance runs out.\n\n## Authentication\n\n`send-document` and partner onboarding use an OAuth2 **client_credentials** access token\nfrom Keycloak (your company's service account). Your `oauth_client_id` and `client_secret` come from the API\nsettings page in the Simplifi platform (company admin).\n\nActing as your users (long-term certificates) instead uses per-user **offline tokens** minted\nthrough **your own API client** once a company admin enables user sign-in on\nit (authorization code with PKCE to a registered redirect URI, or the device\ngrant, with the `offline_access` scope): the user consents once, your software\nstores the offline (refresh) token and exchanges it for short-lived access\ntokens. Code exchange and refresh need your `client_secret`, so they run on\nyour server only, never in a web or mobile app.\n\n## Response envelope\n\nEvery response is wrapped in `{ \"success\": 0|1, \"error\": [..], \"data\": .. }`.\nError responses carry stable machine codes in the `error` array.\n\n## Webhooks\n\nRegister webhook endpoints in API Settings. Events are POSTed with an\n`X-Simplifi-Signature: sha256={hmac}` header (HMAC-SHA256 of the raw JSON\nbody with your endpoint's `signing_secret`). Each section ends with a\n**Webhook events** entry that documents the outbound payloads.\n\n## Rate limits\n\nBudgets are per API identity (the token's subject), never per IP address, in\none-minute windows. Every authenticated response advertises the current\nbudget via `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`\nheaders. Exceeding it returns `429 too_many_requests` with a `Retry-After`\nheader; a client that paces itself off `RateLimit-Remaining` never sees one.\nIntegration (service) tokens get 1800 requests per minute, end-user tokens\n600, and a heavy integrator's ceiling can be raised per OAuth client on\nrequest.\n\n## Versioning\n\nThe API is path-versioned: everything documented here lives under\n`/publicapi/v1`. Changes within v1 are additive (new endpoints, new optional\nfields, new webhook event types), so build clients that ignore unknown\nfields. Incompatible changes ship as a new version path with a migration\nwindow; deprecations are announced here before they take effect.\n" }, "servers": [ { "url": "https://api.simplifi.ro", "description": "Production" }, { "url": "https://api.dev.simplifi.ro", "description": "Development / sandbox" } ], "security": [ { "integratorOAuth": [] } ], "tags": [ { "name": "Connectivity", "description": "**Common**: auth smoke test, entitlements and webhook connectivity for the service-account (`client_credentials`) integration (send-document, partner onboarding)." }, { "name": "Send a document", "description": "**Send a document** - one call, a signing link per signer. Uploads one or\nmore PDFs, names the signers (each with a `kind`: `simple`, `qualified` or\n`account` - see the overview table), places the signature boxes and sends.\nCollapses the step-by-step Document API's create → signers → annotations →\nsend into a single request; rows, billing and webhooks are identical to\nthat path.\n\n**Simple signatures and one-shot certificates have no endpoints of their\nown.** Both are `kind` values on this call (`simple`, `qualified`); the\ndifference is what the signer goes through on the Simplifi-hosted page\nafter they open the link (a verification code, or identity verification\nplus a one-shot certificate) and what the Certificate of Completion\nrecords. Integration guide, chapters 2 and 3.\n\n**Who runs the signing process** is `send_email`, per request:\n\n- **Simplifi takes over** (`1`) - Simplifi emails each signer the\n invitation and the completion notice. Nothing more to do on your side\n until the `document.completed` webhook (or your poll) says it is done.\n- **You include signing in your own product** (`0`, default) - Simplifi\n sends the signers no email. Each signer in the response carries a\n `signing_url`; show it as a button in your app, send it in your own\n email or SMS. The signer signs on the Simplifi-hosted page and is\n redirected to your `return_url` with a signed outcome (guide 1.4).\n Guest signers prove their phone with an SMS code on the page\n (`otp_channel: sms`; pass `phone`, locked with `phone_locked` or as a prefill).\n\n**Service account only**: a user token is refused with\n**403 `service_account_required`**. Status, download and cancel are under\n**Track & collect**.\n" }, { "name": "Simple signatures", "x-traitTag": true, "description": "`kind: simple` on `send-document`. No endpoint of its own: this section\nis about what you do and what the signer goes through. Use it for\nconsents, acknowledgements, internal approvals and anything else where\nyou need a signed record from someone you cannot or need not identify\nwith an ID document. The signer needs nothing: no account, no app, no\nidentity verification.\n\n### What you do\n\n1. Call `POST /publicapi/v1/send-document` with the PDF, the signer's\n `email`, their `name` (required for this kind; it goes into the\n signature) and `kind: simple`, plus the signature boxes.\n2. Decide who runs the signing process:\n - **Simplifi takes over** (`send_email: 1`) - Simplifi emails the\n signer the link and later the completion notice. You are done.\n - **Inside your own product** (`send_email: 0`, default) - take the\n `signing_url` from the response and show it where it fits your flow\n (a button in your app, your own email or SMS). Pass `phone`\n (optionally `phone_locked: true`) so the signer can prove the\n channel with an SMS code on the page, and a `return_url` so they\n come back to your screen afterwards.\n3. Wait for `document.completed` (or poll the status), then download the\n signed PDF and the Certificate of Completion (**Track & collect**).\n\n### What the signer goes through\n\nThe link opens the Simplifi-hosted signing page, in their language:\nthe document(s) and the terms to accept, the verification code (SMS to\nthe number they type or you locked; the email link itself when Simplifi\ndelivered it), the signature, then the redirect to your `return_url`.\n\n### What you get\n\nSimplifi applies its **qualified electronic seal** on the signer's\nbehalf; the signature's Reason line carries the declared `name` and the\nstamp says \"Simple Electronic Signature\". Legally an eIDAS simple\nelectronic signature (SES). The evidence that carries it - view,\nconsent, channel verification, signature, IP and device, all\ntimestamped - is sealed into the Certificate of Completion. Store it\nwith the PDF.\n\n### What it costs\n\nNothing at send. One `simple_signature_envelopes` credit per document\npack when it completes; the send is refused with\n`409 insufficient_simple_signature_envelope_balance` if you have none.\n" }, { "name": "Qualified signatures, one-shot certificates", "x-traitTag": true, "description": "`kind: qualified` on `send-document`. No endpoint of its own: the same\ncall and the same two ways to run the process as for simple signatures;\nwhat changes is the identity verification on the page and the strength\nof what you get back. Use it when the document needs a **qualified\nelectronic signature** from someone who has no Simplifi account and whom\nyou will not necessarily see again: a customer signing a contract, an\napplicant, a counterparty. No onboarding and no certificate management\non your side; identity is verified on the page, every time.\n\n### What you do\n\n1. Call `POST /publicapi/v1/send-document` with `kind: qualified` for the\n signer (everything else as for a simple signer).\n2. Decide who runs the signing process, exactly as for simple signatures:\n **Simplifi takes over** (`send_email: 1`), or **inside your own\n product** (`send_email: 0`, `signing_url` delivered by you,\n `phone` for the SMS code, `return_url` to bring the signer\n back).\n3. Wait for `document.completed`, download the signed PDF and the\n Certificate of Completion.\n\n### What the signer goes through\n\nThe simple-signature steps (document, terms, verification code), then\n**identity verification** on the Simplifi-hosted page: a photo of their\nID document and a selfie with a liveness check. A **one-shot qualified\ncertificate** is issued in the signer's verified name, used for this\nsignature only, and the signer is redirected to your `return_url`. On\ndev, the test documents Simplifi provides are accepted.\n\n### What you get\n\nA qualified electronic signature (eIDAS QES, equivalent to a handwritten\none) by the signer, with the certificate identity (subject, serial,\nissuer) and the full evidence timeline sealed into the Certificate of\nCompletion. You do **not** receive the verified identity data itself:\nthe signer's name as verified appears in the signature and the\ncertificate, nothing more flows back to you.\n\n### What it costs\n\n`prepaid_envelopes` at send, one per qualified signer; in a pack the\nsigner is charged one envelope for the first document and one\n`sponsored_signing_invitations` credit for each further document.\nBilling is checked before anything is stored.\n\n### When the same person keeps coming back\n\nOnboard them once (partner onboarding) and send to them as `account`:\nno repeated identity verification, and your software can sign for them\nwith their consent. See the next section.\n" }, { "name": "Track & collect", "description": "**Track, collect, cancel.** Whatever the signer kind, the document is the\nsame object once it exists: poll `GET /publicapi/v1/documents/{uuid}` (or\nlisten to the `document.*` webhooks listed here), download the signed PDF,\nread the sealed Certificate of Completion, verify a certificate, cancel a\npending document. These operations accept both the service account (for\ndocuments you sent) and a user token (for the user's own documents).\n" }, { "name": "Onboard your users first (partner onboarding)", "description": "**4.1 Before anything** (partners with a sponsorship program): bring\nyour own customers onto Simplifi so your software can act for them. The\nmachine-to-machine twin of the *Sponsorships* console, called with your\n**service-account** (`client_credentials`) token - the person has no\naccount yet, so there is no user token to act with.\nInvite people to a Simplifi account sponsored by your program\n(`POST /partner/customers`), hand them the hosted onboarding link or let\nSimplifi email it, follow the lifecycle through the `customer.*`\nwebhooks (`invited → onboarding → verified → active`, or `revoked`), and\n- if your client has user sign-in enabled - pass PKCE material so the\nhosted onboarding ends with a *Continue to your app* step whose\n`continue_url` is the authorization URL for **your** client. Your app\nreceives the code on its redirect URI and holds an offline token for the\nnewly onboarded person without a second login screen.\n\nThe person creates their own account on Simplifi-hosted pages\n(Keycloak registration or sign-in, email verification, legal documents,\nidentity verification, authenticator, certificate, sponsorship consent).\nYou never supply credentials or acceptances, and the payloads never\nexpose the person's account identity - only your `external_ref` and the\nlifecycle state. Requires a live partner program on your company\n(**409 `partner_program_required`** otherwise); the service account only\n(**401 `integrator_unauthenticated`** for end-user tokens).\n" }, { "name": "Sign-in, consent and tokens", "description": "**Your users** (user token): your software acts as a specific Simplifi\nuser, on their own account, with their consent.\n\n### Getting access\n\n1. Nothing to buy or apply for: acting as your users needs **no subscription**\n - usage bills per act through the user's normal credits. Calls return\n **403 `platform_api_disabled`** if the surface is globally disabled,\n **403 `access_not_enabled`** if the gating company's API access was\n suspended by an administrator. Through **your own client** the gating\n company is yours, so personal-workspace users can be automated; only\n legacy `platform-api` tokens are gated on the user's company and get\n **402 `subscription_required`** without a company context.\n2. Your company admin enables **user sign-in** on your API client (API\n settings → *Allow users to sign in through this client*; at least one\n **redirect URI** must be registered first). The same `oauth_client_id`\n then serves both `client_credentials` and end-user flows.\n3. The user consents **once** via OAuth on **your client** with the\n `offline_access` scope - the consent screen names your company:\n - **Authorization code + PKCE (S256)** - the browser redirect flow, to\n one of your registered redirect URIs; exchange the code **on your\n server** with `client_id`, `client_secret` and the `code_verifier`.\n - or the **Device grant** - `POST {auth}/realms/Simplifi/protocol/openid-connect/auth/device`\n with `client_id={oauth_client_id}&client_secret={client_secret}&scope=openid offline_access`\n plus a PKCE challenge (the realm requires PKCE on every flow); send\n the user to `verification_uri_complete`, then poll the token endpoint\n with `grant_type=urn:ietf:params:oauth:grant-type:device_code`.\n4. Store the returned `refresh_token` - this is the **offline token**\n (long-lived; survives the user's web sessions). Exchange it for\n short-lived access tokens with `grant_type=refresh_token` (again with\n your `client_secret`, server-side) and call the API with\n `Authorization: Bearer {access_token}`. The user can disconnect your\n app at any time from **Connected apps** in the Simplifi app (the\n consent and every offline session minted through your client are\n deleted); you then get `invalid_grant` on refresh and must re-consent.\n Turning user sign-in off on your client refuses every user token with\n **403 `user_auth_disabled`** until it is turned back on.\n\n### Scope of a user token\n\nCalls run **as the user**: they see the user's documents and sign with the\nuser's own certificate. The token is capped to the intersection of the\ncurated user-token surface (documents + signing routes) and the user's\nown role permissions - anything else returns **403 `access_denied`**.\nCompany context is selected per request with the optional `x-role-uuid`\nheader (the user's role UUID in that company; omit for the personal\nworkspace). Through your own client the access gate is checked against\n**your** company, so personal-workspace users - e.g. customers you\nsponsor - can be automated too.\n\n**Who types the authenticator code.** Signing as a **member of your\ncompany** works as before: the body carries the user's TOTP. Signing as\nanyone else answers **409 `hosted_sca_required`** with a `sca_url`: send\nthe person there, they confirm on a Simplifi-hosted page, and the\noriginal request completes (see **Hosted SCA**). Consumer users never\ntype their code into a third-party UI.\n\nMachine-only (`client_credentials`) routes accept your client's\n**service account** only; an end-user token minted through the same\nclient is refused with **401 `integrator_unauthenticated`**.\n\nThe endpoints in this tag let users list and revoke their own offline\ntokens on the legacy shared client, and let company admins oversee their\nmembers' tokens there. Consents on your own client are managed by the\nuser in the Simplifi app (**Connected apps**) - there is deliberately no\nAPI for one integrator to see or revoke another's consent.\n" }, { "name": "Documents, as the user", "description": "**4.5 Other things you can do for your users**: the user's normal document\nworkflows, machine-to-machine. Read / download / Certificate of Completion\nare under **Track & collect**, create / add-signers / annotations / send\nunder **Document API (step by step)**; all of them accept user tokens too\n(acting as the user; `ownership` then defaults to `personal`). This section\nadds the operations available **only** with a user token: list,\nstatistics, draft update, reminders, cancel and delete/purge.\n" }, { "name": "How they sign", "description": "**4.4 How they sign** (user token): sign or reject a document **as the\nuser**, with their own qualified certificate. The signing session is keyed by the\nper-signer `sign_code` (returned in document detail / list responses) and\nconfirmed with the user's current authenticator (TOTP) code - the same\nstrong customer authentication the web app uses. When the acting user is\n**not a member of the integrator's company**, the code is collected on a\nSimplifi-hosted page instead (**409 `hosted_sca_required`** → `sca_url`;\nsee **Hosted SCA**). Not callable with integrator `client_credentials`\ntokens.\n" }, { "name": "Retention", "description": "**4.7 Retention** (company admin): per-company document retention policy.\nWhen set, PDF files of terminal documents (COMPLETED / REJECTED /\nCANCELLED) are hard-deleted N days after the terminal transition (metadata\nand the eIDAS audit trail are preserved; file downloads then return\n**410 `document_files_purged`**). Default: keep forever.\n" } ], "x-tagGroups": [ { "name": "Getting started", "tags": [ "Connectivity" ] }, { "name": "Send a document", "tags": [ "Send a document" ] }, { "name": "Simple signatures", "tags": [ "Simple signatures" ] }, { "name": "Qualified signatures, one-shot certificates", "tags": [ "Qualified signatures, one-shot certificates" ] }, { "name": "Qualified signatures, long-term certificates: your users' own", "tags": [ "Onboard your users first (partner onboarding)", "Sign-in, consent and tokens", "How they sign", "Documents, as the user", "Retention" ] }, { "name": "Track, collect, cancel", "tags": [ "Track & collect" ] } ], "paths": { "/publicapi/v1/csc/integrator/ping": { "get": { "tags": [ "Connectivity" ], "operationId": "integratorPing", "summary": "Auth smoke test", "description": "Verifies the client_credentials token resolves to your API client.", "responses": { "200": { "description": "Token valid.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean" }, "api_client_uuid": { "type": "string", "format": "uuid" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" } } } }, "/publicapi/v1/csc/integrator/entitlements": { "get": { "tags": [ "Connectivity" ], "operationId": "integratorEntitlements", "summary": "Subscription and allowance snapshot", "description": "Your company's current API access state and remaining allowance per\ncategory.\n\nUse this for dashboards, monitoring and pre-flight checks. For per-call freshness\nprefer the `X-Simplifi-Allowance-*` response headers returned by the billable\nendpoints - they cost you nothing and are always current. **Poll this endpoint at\nmost hourly.**\n\nThis endpoint never returns 402/403 for a blocked account: it answers 200 with the\nper-surface gate status in `surfaces`, so it stays usable exactly when you need to\nfind out what is wrong. The legacy `api_calls_enabled` / `blocked_reason` pair\ndescribes a separate, gated partner surface and is kept for backward compatibility:\n`api_calls_enabled: false` does NOT mean send-document / user-token calls are blocked - check\n`surfaces.platform` for those.\n\n`overdraft` is consumption already delivered that no active grant covers - sessions\nthat completed after your balance ran out. It is settled automatically against your\nnext purchase. `allowance.*_remaining` never goes below zero, so a non-zero\n`overdraft` is the only way to see how far past your balance you are.\n", "responses": { "200": { "description": "Current entitlement state.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "metering_mode": { "type": "string", "enum": [ "enforce", "log_only", "unmetered", "postpaid" ], "description": "Allowance is only enforced in `enforce`. In `postpaid` nothing is\never refused for balance: usage is rated at your agreed rate card\nand invoiced monthly (see `postpaid`); any leftover pre-paid credits\nare still consumed first.\n" }, "api_calls_enabled": { "type": "boolean", "description": "Legacy flag for a separate, gated partner surface; kept for backward compatibility - prefer `surfaces`." }, "blocked_reason": { "type": [ "string", "null" ], "enum": [ "csc_api_disabled", "access_not_enabled", "subscription_required", null ] }, "surfaces": { "type": "object", "description": "Gate status per API surface. `platform` covers send-document, the Document API\nand acting as your users - no approval or subscription needed; only a\nglobal kill switch or an admin suspension blocks it. `embedded`\ncovers a separate, gated partner surface and does not affect anything\ndocumented here.\n", "properties": { "platform": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "blocked_reason": { "type": [ "string", "null" ], "enum": [ "csc_api_disabled", "access_not_enabled", null ] } } }, "embedded": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "blocked_reason": { "type": [ "string", "null" ], "enum": [ "csc_api_disabled", "access_not_enabled", "subscription_required", null ] } } } } }, "subscription": { "type": "object", "properties": { "active": { "type": "boolean" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "End of the currently paid period. Not an end date if the subscription auto-renews." } } }, "allowance": { "type": "object", "properties": { "enrollments_remaining": { "type": "integer" }, "signatures_remaining": { "type": "integer" }, "packs_remaining": { "type": "integer" }, "simple_packs_remaining": { "type": "integer", "description": "`csc_api_simple_packs` - simple-signature sessions (`signature_kind: simple`)." } } }, "overdraft": { "type": "object", "description": "Units consumed beyond the balance, per category. Zero while in credit.", "properties": { "enrollments": { "type": "integer" }, "signatures": { "type": "integer" }, "packs": { "type": "integer" }, "simple_packs": { "type": "integer" } } }, "postpaid": { "oneOf": [ { "$ref": "#/components/schemas/PostpaidStatus" }, { "type": "null" } ], "description": "Present (non-null) only when `metering_mode` is `postpaid`." } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" } } } }, "/publicapi/v1/csc/integrator/webhooks/test": { "post": { "tags": [ "Connectivity" ], "operationId": "webhookTest", "summary": "Send webhook.test to all enabled endpoints", "description": "Dispatches a `webhook.test` event to every enabled webhook endpoint configured\nfor your API client. Use it to verify connectivity and your HMAC verification.\n", "responses": { "200": { "description": "Test events dispatched.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean" }, "message": { "type": "string" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" } } } }, "/publicapi/v1/csc/integrator/~webhook-events": { "get": { "tags": [ "Connectivity" ], "operationId": "connectivityWebhookEvents", "x-webhook-catalog": true, "summary": "Webhook events", "description": "**Documentation only** - not a callable route. Connectivity test events POSTed\nto your configured webhook endpoint(s). Trigger a delivery with\n`POST /integrator/webhooks/test`.\n", "responses": { "501": { "description": "Not callable; documents outbound webhook payloads only." }, "4XX": { "$ref": "#/components/responses/Error4xx" } }, "callbacks": { "webhook.test": { "$ref": "#/components/callbacks/WebhookTestEvent" } } } }, "/publicapi/v1/csc/integrator/~alert-webhook-events": { "get": { "tags": [ "Connectivity" ], "operationId": "alertWebhookEvents", "x-webhook-catalog": true, "summary": "Allowance & subscription alert events", "description": "**Documentation only** - not a callable route. Account-level alert events\nPOSTed to webhook endpoints subscribed to them. Emitted when a credit\nbalance crosses the warning threshold configured in the company's alert\nsettings (`allowance.low`), reaches zero (`allowance.exhausted`), when\nan API Access subscription approaches its expiry\n(`subscription.at_risk`, with a `reason` explaining why it needs\nattention - including a plain renewal heads-up), and when access has\nlapsed and calls are being refused (`subscription.lapsed`).\n\nEach alert fires once per threshold crossing and re-arms when the\nbalance recovers (top-up / renewal). The same alerts can also be\ndelivered by email and SMS - recipients and thresholds are managed by\nyour company admin in the app's API settings.\n", "responses": { "501": { "description": "Not callable; documents outbound webhook payloads only." }, "4XX": { "$ref": "#/components/responses/Error4xx" } }, "callbacks": { "allowance.low": { "$ref": "#/components/callbacks/AllowanceLowEvent" }, "allowance.exhausted": { "$ref": "#/components/callbacks/AllowanceExhaustedEvent" }, "subscription.at_risk": { "$ref": "#/components/callbacks/SubscriptionAtRiskEvent" }, "subscription.lapsed": { "$ref": "#/components/callbacks/SubscriptionLapsedEvent" } } } }, "/publicapi/v1/send-document": { "post": { "tags": [ "Send a document" ], "operationId": "sendDocument", "summary": "Send a document - one call, a link per signer", "description": "Upload one or more PDFs, name the signers and send - one request, a\nsigning link per signer. Internally this runs the Document API's create →\nannotations → signers → send steps, so the document, its signer rows, the\nbilling and the `document.*` webhooks are exactly those of the four-call\npath; `GET /publicapi/v1/documents/{uuid}` is the status surface.\n\n**Signers** (1-10). Each has a `kind` (see the tag description):\n`simple` (default; `name` required - it becomes the signature's Reason\nline), `qualified`, or `account`. Guest kinds accept the verification\nchannel fields (`otp_channel`, `phone`, `phone_locked`); on an `account`\nsigner they answer **400 `otp_channel_not_applicable`**. The same email\nmay appear once (**409 `duplicate_signer_email`**).\n\n**Documents** (1-20). One document is sent alone; two or more are sent\nas a **pack** (one `document_group_uuid`, one signing session per signer across\nall documents, one link). Each document may carry `signatures` -\nplacements referencing signers by index. A signer with no placement on a\ndocument gets a default box on that document's **last page, bottom-left**\n(the recommended 133 × 53 pt slot at x = 100, 40 pt above the bottom edge,\nstacked upward per signer).\n\n**Delivery.** `send_email` defaults to `0`: no email leaves Simplifi and\nguest signers verify an SMS code on the page (`otp_channel` defaults to\n`sms`; the signer types their own number unless you `phone`-prefill or\n`phone_locked` it). `send_email: 1` emails the invitations and sets the\ndefault `otp_channel` to `none`.\n\n**Allowance is pre-checked for every category the request will charge,\nbefore any file is stored**, from the rows it will write (N =\nnumber of documents): `prepaid_envelopes` = qualified guests;\n`sponsored_signing_invitations` = account signers × N + qualified guests\n× (N − 1); `simple_signature_envelopes` ≥ 1 when any signer is `simple`\n(debited once per pack at completion, so this one is a balance check,\nnot a reservation). Refusals are **409** with `data.shortfall`,\n`data.balance_holder` and the per-category `data.allowance`; nothing is\ncreated. The `X-Simplifi-Allowance-*` headers are present only when\nexactly one category is charged at send; `data.allowance` always lists\nevery charged category with the remaining balance after the send.\n\n**Atomic.** If a step fails after a draft exists, every draft the\nrequest created is discarded and the step's own error is returned with\n`data.step` (`create` | `annotations` | `signers` | `send`) and\n`data.document_index`.\n\n**Service account only** (`client_credentials`): a user\ntoken is refused with **403 `service_account_required`**.\n", "security": [ { "integratorOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendDocumentRequest" }, "examples": { "mixed": { "summary": "Three kinds on one document, links delivered by you", "value": { "signers": [ { "email": "ana@example.com", "name": "Ana Popescu", "kind": "simple" }, { "email": "ion@example.com", "name": "Ion Pop", "kind": "qualified", "phone": "+40722123456", "phone_locked": true }, { "email": "cfo@partner.ro", "kind": "account" } ], "documents": [ { "name": "Contract", "pdf_base64": "JVBERi0xLjcK…", "signatures": [ { "signer": 0, "page": 1, "x": 50, "y": 700, "width": 180, "height": 60 }, { "signer": 1, "page": 1, "x": 300, "y": 700, "width": 180, "height": 60 } ] } ], "return_url": "https://partner.example/done", "expires_in_hours": 72, "send_email": 0 } } } } } }, "responses": { "201": { "description": "Sent. One entry per signer with its `sign_code` and `signing_url`.", "headers": { "X-Simplifi-Allowance-Code": { "$ref": "#/components/headers/AllowanceCode" }, "X-Simplifi-Allowance-Remaining": { "$ref": "#/components/headers/AllowanceRemaining" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SendDocumentResponse" } } } ] } } } }, "400": { "description": "Request validation (nothing stored): `invalid_json`, `signers_required`,\n`too_many_signers`, `invalid_signer`, `invalid_signer_email`,\n`invalid_kind`, `invalid_signer_name`, `signer_name_required` (simple\nsigners), `invalid_signing_order`, `otp_channel_not_applicable`,\n`otp_channel_required`, `invalid_otp_channel`, `invalid_phone`,\n`phone_region_not_allowed`, `phone_not_applicable`, `phone_lock_requires_phone`,\n`documents_required`, `too_many_documents`, `invalid_document`,\n`document_name_required`, `invalid_pdf_base64`, `invalid_file_name`,\n`invalid_signatures` (`data.reason`: `unknown_signer_index`,\n`invalid_page`, `invalid_x` … `empty_box`), `invalid_return_url`,\n`invalid_expires_in_hours` (`data.min` / `data.max`),\n`invalid_send_email`. `data.signer_index` / `data.document_index`\npoint at the offending entry. A step error after validation passes\nthrough with its original code plus `data.step`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "`unauthenticated` - missing/expired/invalid `client_credentials` token (user tokens are not accepted on this route).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`service_account_required` (a user token was presented), `access_denied`, or the platform gate codes (`platform_api_disabled`, `access_not_enabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`duplicate_signer_email`, or an allowance refusal before anything is stored:\n`insufficient_prepaid_envelope_balance`,\n`insufficient_sponsored_signing_invitation_balance` (`data.balance_holder: sender`),\n`insufficient_simple_signature_envelope_balance` (`data.balance_holder: document_owner`).\n`data.shortfall` is the number of units still needed; `data.allowance` lists every\ncategory the request would charge with `required`, `remaining` and `debited_at`.\n", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "shortfall": { "type": "integer" }, "balance_holder": { "type": "string", "enum": [ "sender", "document_owner" ] }, "allowance": { "$ref": "#/components/schemas/SendDocumentAllowance" } } } } } ] } } } }, "422": { "description": "A step refused the request after validation (e.g. `invalid_pdf`, `invalid_signature_placement` with `data.reason` such as `page_out_of_range` / `outside_page_bounds`, `signature_annotation_required`); the code is the Document API's, with `data.step` and `data.document_index` added. Drafts are discarded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "`rate_limited` - integration tier limits (see Rate limits in the guide).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/publicapi/v1/documents": { "get": { "tags": [ "Documents, as the user" ], "operationId": "listDocuments", "summary": "List documents", "description": "List the documents visible to the acting principal, filtered and\npaginated. With a user token this is the user's own inbox\nand sent list - the same data the web app shows.\n\nThe response carries the document array in `data` and a top-level\n`pagination` object (`{ page, per_page, total, total_pages }`). Owner\nrows include the document `uuid`; rows where the acting user is a signer\ninclude their `sign_code` for the signing session endpoints.\n", "security": [ { "integratorOAuth": [] }, { "platformUserOAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RoleUuidHeader" }, { "name": "scope", "in": "query", "schema": { "type": "string", "default": "all_related", "enum": [ "all_related", "needs_my_signature", "signed_by_me", "rejected_by_me", "waiting_for_others", "drafts", "completed_sent", "cancelled_or_rejected_sent" ] } }, { "name": "envelope_ownership", "in": "query", "schema": { "type": "string", "enum": [ "personal", "company", "all" ], "default": "personal" } }, { "name": "lifecycle", "in": "query", "description": "Comma-separated lifecycle filter (`DRAFT,PENDING,COMPLETED,REJECTED,CANCELLED,EXPIRED`).", "schema": { "type": "string" } }, { "name": "action_required", "in": "query", "description": "Comma-separated; only with `scope=all_related`: `needs_my_signature`, `waiting_for_others` (or boolean shortcuts).", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "signers", "in": "query", "description": "Comma-separated signer emails (OR match, max 50).", "schema": { "type": "string" } }, { "name": "verification_status", "in": "query", "description": "Comma-separated guest identity-verification filter (OR match): `in_progress`, `declined`, `failed`. Matches documents having at least one guest signer whose verification is in any of the requested states.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "sort", "in": "query", "schema": { "type": "string", "default": "date_added", "enum": [ "date_added", "sent_at", "completed_at", "expires_at", "name", "size_bytes", "lifecycle", "owner_name", "action_required" ] } }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "DESC" } } ], "responses": { "200": { "description": "Page of document summaries (plus top-level `pagination`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PlatformDocumentSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "422": { "description": "`invalid_scope`, `invalid_sort_field`, `invalid_order`, `invalid_envelope_ownership`, `invalid_lifecycle`, `invalid_signers`, `invalid_verification_status`, `invalid_action_required`, `invalid_action_required_scope`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/publicapi/v1/documents/statistics": { "get": { "tags": [ "Documents, as the user" ], "operationId": "getDocumentStatistics", "summary": "Dashboard statistics", "description": "Aggregate counters for the acting principal's documents - what the web\napp's dashboard tiles show: documents needing the user's signature,\ndocuments waiting for others, completions and signatures over the last\n30 days.\n", "security": [ { "integratorOAuth": [] }, { "platformUserOAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RoleUuidHeader" }, { "name": "envelope_ownership", "in": "query", "schema": { "type": "string", "enum": [ "personal", "company", "all" ], "default": "personal" } } ], "responses": { "200": { "description": "Statistics.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PlatformDocumentStatistics" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "422": { "description": "`invalid_envelope_ownership`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/publicapi/v1/documents/{uuid}": { "get": { "tags": [ "Track & collect" ], "operationId": "getDocument", "summary": "Get document status (poll) - returns the whole pack", "description": "Read the lifecycle status and per-signer status. The response is the **pack view**: `data` carries `document_group_uuid`, `sent_at`, `member_count`, `current_document_uuid` (the uuid you requested) and a `documents` array with the full detail of every pack member (`is_current` marks the requested one). A standalone document is simply a pack of one - same shape, `member_count: 1`.\n\nFor documents your integration created, each signer entry also includes its `sign_code` and a ready-to-use `signing_url` for redirecting the end user.\n\n**Dual-principal**: also callable with a user token (owner-only view; signers use the signing session endpoints instead).\n", "security": [ { "integratorOAuth": [] }, { "platformUserOAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/DocumentUuid" } ], "responses": { "200": { "description": "Pack detail (the requested document plus its group siblings).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SignWithSimplifiDocumentPack" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "403": { "description": "`document_owner_required`, `email_required`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`document_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "put": { "tags": [ "Documents, as the user" ], "operationId": "updateDocumentDraft", "summary": "Update draft metadata", "description": "Update a DRAFT document's metadata (owner only, user token only). Send\nat least one field; omitted fields are left unchanged. `expires_at: null`\nclears the expiry; `detach_from_document_group: true` (or\n`document_group_uuid: null`) detaches the document from its pack.\n\n**Signing options on a draft.** `ades_level` changes the signature\nlevel for any container (validated against the target container when\nthe same call also switches it). `signature_format` moves the draft\nbetween containers after upload; which targets are possible depends on\nthe stored bytes and is published as `allowed_signature_formats` on the\ncreate / detail / update responses (PDF: `pades` or `cades`; XML:\n`xades` or `cades`; an uploaded `.p7m` or any other file: `cades`\nonly). Switching re-runs the target container's intake on the stored\nfile: PDF -> `cades` drops annotations and the PDF profile\n(`document_format: binary`, response gains `file_summary` /\n`existing_signatures`); `cades` -> `pades` re-runs the PDF gate and\nform detection (a re-detected form is refused with the usual\n`form_document_single_signer` / `signing_type_not_supported_for_profile`\nif the signer list no longer fits) and the response is the PDF shape\nagain. A stored level that is not valid for the new container falls\nback to that container's default (echoed as `ades_level`). Re-sending\nthe current value is a no-op 200. Re-render from the response - several\nfields change together.\n", "security": [ { "platformUserOAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/DocumentUuid" }, { "$ref": "#/components/parameters/RoleUuidHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "signature_level": { "type": "string", "enum": [ "QUALIFIED", "ADVANCED", "SIMPLE" ] }, "ownership": { "type": "string", "enum": [ "personal", "company" ] }, "detach_from_document_group": { "type": "boolean" }, "signature_format": { "$ref": "#/components/schemas/SignatureFormat" }, "ades_level": { "type": "string", "enum": [ "legacy", "B", "T", "LT", "LTA" ], "description": "Same rules as on create; `legacy` is PDF only, form PDFs accept only `legacy`." }, "pdf_profile": { "$ref": "#/components/schemas/PdfProfile" } } } } } }, "responses": { "200": { "description": "Updated metadata (`uuid`, `name`, `expires_at`, `signature_level`, `ownership`, `document_group_uuid`, `document_format`, `signature_format`, `ades_level`, `allowed_signature_formats`, `pdf_profile`, `form`, `form_candidates`; `file_summary` and `existing_signatures` on non-PDF containers).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "403": { "description": "`document_owner_required`, `company_admin_required`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`document_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "`document_not_draft`, `document_patch_required`, `name_required`, `invalid_signature_level`, `invalid_ownership`, `company_required_for_company_documents`, `document_group_locked`, `document_group_reassign_not_supported`, `ades_level_invalid`, `ades_level_not_allowed`, `ades_level_unsupported`, `ades_level_not_supported_for_profile` (form PDF), `invalid_signature_format` (`data.supported`), `signature_format_not_switchable` (`data.current`, `data.allowed_signature_formats`), plus the target container's intake errors when switching (`invalid_pdf`, `password_protected_pdf`, `invalid_xml`, `form_document_single_signer`, `signing_type_not_supported_for_profile`, ...), `invalid_pdf_profile`, `pdf_profile_not_applicable` (XML), `form_profile_required` (XFA forms cannot switch to `standard`), `form_no_placeholders` (`form` requested on a file without blank signature fields), `form_too_many_placeholders`, `signing_type_not_supported_for_profile` (`form` requested while a `SEAL` signer exists)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "Documents, as the user" ], "operationId": "deleteDocument", "summary": "Delete (and optionally purge) a document", "description": "Delete always hides (soft delete, user token only); PDFs are additionally\n**hard-deleted from disk** (\"purged\") when the deleter was the last\nstakeholder with file access. Document metadata, signers and the audit\ntrail are always preserved; after a purge, file downloads return\n**410 `document_files_purged`**.\n\nOwner delete by lifecycle:\n- `PENDING`: rejected with **409 `cancel_required_before_delete`** - an\n active signing session must be cancelled, not hidden while still signable.\n- `DRAFT`, `CANCELLED`, `EXPIRED`, `ERROR`: soft-deleted and files\n auto-purged (signers have no file access in these states).\n- `COMPLETED`, `REJECTED`: soft-deleted; files auto-purge only when no\n other participant still has access (e.g. the owner was the only\n signer). Otherwise files are reclaimed later by the daily purge job,\n once every participant has deleted or the company retention window\n elapses.\n\n`mode=purge` (owner only) forces the purge of a `COMPLETED`/`REJECTED`\ndocument's files while other participants still have access (deliberate\ndestruction, e.g. an erasure request). A company admin deleting a\ncompany-owned document deletes it for the whole company side, including\nthe uploader.\n\nSigners deleting a received document only hide it from their own view\nand never trigger a purge. A pending, unanswered invite cannot be\ndeleted (**409 `reject_required_before_delete`**) - reject it instead.\n", "security": [ { "platformUserOAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/DocumentUuid" }, { "$ref": "#/components/parameters/RoleUuidHeader" }, { "name": "mode", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "purge" ] } } ], "responses": { "200": { "description": "Deleted (`data.uuid` echoes the document). Whether the files were also hard-deleted follows deterministically from the rules above; the response carries no purge indicator.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "403": { "description": "`access_denied`, `document_owner_required`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`document_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`cancel_required_before_delete`, `cancel_required_before_purge`, `reject_required_before_delete`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "`invalid_delete_mode`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/publicapi/v1/documents/{uuid}/remind": { "post": { "tags": [ "Documents, as the user" ], "operationId": "remindDocumentSigner", "summary": "Remind a signer", "description": "Re-send the invitation email to one signer of a PENDING document (owner\nonly). The signer must currently be `INVITED` or `VIEWED`. Rate-limited:\nat most 3 reminders per signer per 24 hours, minimum 1 hour apart\n(**429 `document_remind_rate_limited`**, with `data.retry_after_seconds`).\n", "security": [ { "integratorOAuth": [] }, { "platformUserOAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/DocumentUuid" }, { "$ref": "#/components/parameters/RoleUuidHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "The signer to remind." } } } } } }, "responses": { "200": { "description": "Reminder queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "403": { "description": "`document_owner_required`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`document_not_found`, `signer_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "`invalid_document_lifecycle_for_reminder`, `valid_email_required`, `invalid_signer_status_for_reminder`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "`document_remind_rate_limited` (`data.retry_after_seconds`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/publicapi/v1/documents/{uuid}/cancel": { "post": { "tags": [ "Documents, as the user", "Track & collect" ], "operationId": "cancelDocument", "summary": "Cancel a document", "description": "Cancel a DRAFT or PENDING document (owner only). Requires the acting\n**user's current authenticator (TOTP) code** - cancellation is a signed\nuser action, so it is effectively user-token only.\n\nCancelling a PENDING document emails a cancellation notice to every\nalready-invited party (invited/viewed/signed signers and CC\nnotification addresses); their pending signature requests become void.\n", "security": [ { "platformUserOAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/DocumentUuid" }, { "$ref": "#/components/parameters/RoleUuidHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "totp" ], "properties": { "totp": { "type": "string", "description": "The user's current 6-digit authenticator code." } } } } } }, "responses": { "200": { "description": "Document cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "403": { "description": "`document_owner_required`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`document_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "`invalid_document_lifecycle_for_cancel`, `totp_code_required`, `totp_not_configured`, `invalid_totp`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/publicapi/v1/documents/{uuid}/file": { "get": { "tags": [ "Track & collect" ], "operationId": "getDocumentFile", "summary": "Download the (signed) document file", "description": "Download the current document file. Once the document is COMPLETED this is the\nfully-executed, signed file. PDF documents are served as `application/pdf`;\nXML documents (`document_format: xml`) as `application/xml` with the\nenveloped XAdES signatures inside - the same bytes you submit to KRS /\ne-Sprawozdania / KSeF. CAdES documents (`signature_format: cades`) are served\nas `application/pkcs7-mime` with a `..p7m` attachment name once at\nleast one signature exists (the CMS envelope wrapping the original file -\nthe `.p7m` accepted by Italian PA / Registro Imprese / InfoCamere), and as\nthe plain upload (`application/octet-stream`, or `application/pdf` /\n`application/xml` for recognised content) before that.\n\n**Dual-principal**: also callable with a user token\n(owner-only; a signer downloads via\n`GET /publicapi/v1/signing/{sign_code}/file` instead). Returns\n**410 `document_files_purged`** if the files were purged by retention or\nan explicit purge delete.\n", "security": [ { "integratorOAuth": [] }, { "platformUserOAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/DocumentUuid" } ], "responses": { "200": { "description": "File bytes (content type follows `document_format` / `signature_format`).", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "application/xml": { "schema": { "type": "string", "format": "binary" } }, "application/pkcs7-mime": { "schema": { "type": "string", "format": "binary" } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "`document_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/publicapi/v1/documents/{uuid}/audit-certificate": { "get": { "tags": [ "Track & collect" ], "operationId": "getDocumentAuditCertificate", "summary": "Download the Certificate of Completion", "description": "Download the sealed Certificate of Completion (audit certificate) for a\nCOMPLETED document: document identity and executed-file SHA-256, every\nsigner with signature kind and timestamps, and the captured evidence\ntimeline (views, consent, signatures, IP addresses as reported by\nCloudflare). The PDF is sealed with a qualified electronic seal of\nSIMPLIWORKS S.R.L., so any modification invalidates it.\n\nGenerated automatically at completion; if that attempt failed (e.g.\nsigning backend briefly down) this endpoint regenerates it on demand.\n\n**Dual-principal**: also callable with a user token\n(owner-only; a signer downloads via\n`GET /publicapi/v1/signing/{sign_code}/audit-certificate` instead).\n", "security": [ { "integratorOAuth": [] }, { "platformUserOAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/DocumentUuid" } ], "responses": { "200": { "description": "PDF bytes.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "403": { "description": "`document_owner_required`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`document_not_found`, `audit_certificate_not_available`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "`document_not_completed`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/publicapi/v1/documents/{uuid}/signatures": { "get": { "tags": [ "Track & collect" ], "operationId": "getDocumentSignatures", "summary": "List the XAdES / CAdES signatures embedded in a document", "description": "For XAdES (`document_format: xml`) and CAdES (`signature_format: cades`)\ndocuments: parse the current file (the signed final file once COMPLETED)\nand list every signature it contains - the enveloped `ds:Signature`s of\nan XML, or the SignerInfos of the CMS `.p7m` envelope - the ones placed\non this platform and any that were already in the upload. Each entry\nreports the signer certificate\n(common name, `serialNumber` attribute such as `PNOPL-…` / `TINIT-…`,\nissuer, validity), the detected format/level, and the cryptographic\nchecks the platform performs (`digests_ok`, `signature_ok`,\n`signing_certificate_match`, `valid`). This is a structural check, not\na trust-list validation - for a legally binding verdict validate the\ndownloaded file with the authority's validator (e-Sprawozdania,\nKSeF) or an eIDAS validator.\n\n**Dual-principal**: also callable with a user token (owner-only).\n", "security": [ { "integratorOAuth": [] }, { "platformUserOAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/DocumentUuid" } ], "responses": { "200": { "description": "Signature listing.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "document_format": { "$ref": "#/components/schemas/DocumentFormat" }, "signature_format": { "$ref": "#/components/schemas/SignatureFormat" }, "ades_level": { "$ref": "#/components/schemas/AdesLevel" }, "file_summary": { "$ref": "#/components/schemas/AdesFileSummary" }, "signatures": { "type": "array", "items": { "$ref": "#/components/schemas/XmlEmbeddedSignature" } }, "signature_count": { "type": "integer" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "403": { "description": "`document_owner_required`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`document_not_found`, `document_file_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "description": "`document_files_purged`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "`signatures_listing_not_available_for_format` (PAdES document; `data.document_format`, `data.signature_format`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/publicapi/v1/verify/{certificate_uuid}": { "get": { "tags": [ "Track & collect" ], "operationId": "verifyAuditCertificate", "summary": "Verify a Certificate of Completion (public)", "description": "Public, unauthenticated verification of a Certificate of Completion by\nthe certificate id printed on the PDF and encoded in its QR code.\nResolves both certificate kinds, discriminated by `data.kind`:\n`document` (platform signing document certificates) and `csc_session`\n(signing-session certificates). Returns just enough to confirm\nthe certificate is genuine and no personal data. For `document`:\ncompletion time, signer count and signature kinds, and the SHA-256\nfingerprints of the executed and original files - compare\n`executed_file_sha256` with the hash of the signed document you hold.\nFor `csc_session`: session completion time, signature level, and the\nper-document SHA-256 pairs (reviewed content / signed result).\n\nUnknown, malformed and not-yet-issued ids all return the same\n`valid: false` 404 shape, so the endpoint cannot be used to probe which\ndocuments or sessions exist. Rate limited per client IP and per\ncertificate id (429 `rate_limited`).\n\nJSON-only: the human-facing verification page (the QR target,\n`{app base}/verify/{certificate_uuid}`) is built on top of this\nendpoint.\n", "security": [], "parameters": [ { "name": "certificate_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Certificate ID printed on the Certificate of Completion." } ], "responses": { "200": { "description": "Certificate is genuine.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "valid": { "type": "boolean", "description": "Always `true` on 200." }, "kind": { "type": "string", "enum": [ "document", "csc_session" ], "description": "Certificate kind - which of the two field sets below applies." }, "certificate_uuid": { "type": "string", "format": "uuid" }, "certificate_generated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last (re)generation time of the certificate PDF." }, "document_uuid": { "type": "string", "format": "uuid", "description": "`kind=document` only." }, "document_completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "`kind=document` only." }, "signer_count": { "type": "integer", "description": "`kind=document` only." }, "signature_kinds": { "type": "object", "description": "`kind=document` only. Signer count per signature kind.", "properties": { "qualified": { "type": "integer" }, "simple": { "type": "integer" } } }, "executed_file_sha256": { "type": [ "string", "null" ], "description": "`kind=document` only. SHA-256 (hex) of the executed file; `null` once source files are purged by retention." }, "original_file_sha256": { "type": [ "string", "null" ], "description": "`kind=document` only. SHA-256 (hex) of the original uploaded file; `null` once purged." }, "session_completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "`kind=csc_session` only." }, "signature_level": { "type": "string", "enum": [ "SES" ], "description": "`kind=csc_session` only. Session certificates are issued for simple (SES) sessions." }, "document_count": { "type": "integer", "description": "`kind=csc_session` only." }, "documents": { "type": "array", "description": "`kind=csc_session` only. Per-document fingerprints, without labels (no PII).", "items": { "type": "object", "properties": { "reviewed_content_sha256": { "type": [ "string", "null" ], "description": "SHA-256 (hex) of the exact bytes presented for review." }, "signed_file_sha256": { "type": [ "string", "null" ], "description": "SHA-256 (hex) of the sealed output file; `null` once cleaned up from storage." } } } } } } } } ] } } } }, "404": { "description": "`certificate_not_found` - unknown, malformed or not-yet-issued id; `data.valid` is `false`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "`rate_limited`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/publicapi/v1/documents/~webhook-events": { "get": { "tags": [ "Track & collect" ], "operationId": "signWithSimplifiWebhookEvents", "x-webhook-catalog": true, "summary": "Webhook events", "description": "**Documentation only** - not a callable route. Document lifecycle events for\nSign-with-Simplifi integrations POSTed to your configured webhook endpoint(s).\n", "responses": { "501": { "description": "Not callable; documents outbound webhook payloads only." }, "4XX": { "$ref": "#/components/responses/Error4xx" } }, "callbacks": { "document.signer.signed": { "$ref": "#/components/callbacks/DocumentSignerSignedEvent" }, "document.completed": { "$ref": "#/components/callbacks/DocumentCompletedEvent" }, "document.rejected": { "$ref": "#/components/callbacks/DocumentRejectedEvent" } } } }, "/publicapi/v1/signing/{sign_code}": { "get": { "tags": [ "How they sign" ], "operationId": "getSignerCeremonyInfo", "summary": "Get signing session info (as signer)", "description": "The signer's view of a document (or pack) awaiting their signature,\nkeyed by their `sign_code`. Returns the documents with the signer's own\nplacement annotations, the signer roster with statuses, and\n`my_signer_info` for the acting user. Each document row (and the envelope top level, mirroring the current link's document) carries `audit_certificate_available` - same semantics as the owner detail: false means the Certificate of Completion will never exist (legacy completions). The authenticated user's email\nmust match the signer row (**403 `claim_required`** with a masked\n`invited_email_hint` otherwise). DRAFT documents return **404** to\nsigners.\n\nEach document row carries `document_format` / `signature_format` /\n`ades_level`; XAdES and CAdES rows add `file_summary`, `existing_signatures` and\nthe signer's `signing_type` (render the summary + signature list\ninstead of a page viewer, and call `/sign` with `totp` only). PDF rows\ncarry `pdf_profile`; `form` rows add `form` (placeholders, form code,\nwarnings) and `signing_type` - render the form card instead of the\nplacement canvas and call `/sign` with `totp` + optional `form_stamp`.\n", "security": [ { "platformUserOAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SignCode" }, { "$ref": "#/components/parameters/RoleUuidHeader" } ], "responses": { "200": { "description": "Signing session info (pack envelope with `documents[]`, `my_signer_info`, `current_sign_code`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "403": { "description": "`claim_required` (`data.invited_email_hint` is a masked email)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`document_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "How they sign" ], "operationId": "deleteAsSigner", "summary": "Delete a received document (as signer)", "description": "Signer-side counterpart of `DELETE /publicapi/v1/documents/{uuid}` for\nrecipients whose lists expose only `sign_code` (document `uuid` is an\nowner-only surface). Hides the document from the acting user's own\nlists by soft-deleting their visibility rows; the owner and other\nsigners keep access and this call never purges PDFs (files are\nreclaimed later by the purge job once no stakeholder is left).\n\nWhile the document is PENDING and the invite is still actionable\n(signer status `INVITED`/`VIEWED`), answers\n**409 `reject_required_before_delete`** - reject first, then delete.\nRequires an authenticated account matching the signer (invited email,\nbound role, or a succeeded claim); guest sign links cannot delete.\nRepeated calls succeed (idempotent).\n", "security": [ { "platformUserOAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SignCode" }, { "$ref": "#/components/parameters/RoleUuidHeader" } ], "responses": { "200": { "description": "Hidden from the caller's lists (`data.sign_code`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "403": { "description": "`access_denied` (account does not match the signer)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`signer_not_found`, `document_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`reject_required_before_delete`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/publicapi/v1/signing/{sign_code}/file": { "get": { "tags": [ "How they sign" ], "operationId": "getSignerCeremonyFile", "summary": "Download the document file (as signer)", "description": "Download the current document file from the signer's perspective. A\nsigner in status `INVITED` is automatically moved to `VIEWED` on first\ndownload. PDF documents stream as `application/pdf`, XML documents as\n`application/xml`, CAdES documents as `application/pkcs7-mime` (`.p7m`)\nonce signed and as the plain upload before (check `document_format` /\n`signature_format` on the signing session info).\n", "security": [ { "platformUserOAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SignCode" }, { "$ref": "#/components/parameters/RoleUuidHeader" } ], "responses": { "200": { "description": "File bytes (content type follows `document_format` / `signature_format`).", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "application/xml": { "schema": { "type": "string", "format": "binary" } }, "application/pkcs7-mime": { "schema": { "type": "string", "format": "binary" } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Signer or document not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "description": "`document_files_purged`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Document lifecycle or signer status does not allow viewing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/publicapi/v1/signing/{sign_code}/audit-certificate": { "get": { "tags": [ "How they sign" ], "operationId": "getSignerAuditCertificate", "summary": "Download the Certificate of Completion (as signer)", "description": "Download the sealed Certificate of Completion for a COMPLETED document\nfrom the signer's perspective (same PDF the owner gets from\n`GET /publicapi/v1/documents/{uuid}/audit-certificate`). Guest signers\nuse `GET /publicapi/v1/signing-guest/{sign_code}/audit-certificate`\nwhile their completed-access window is open.\n", "security": [ { "platformUserOAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SignCode" }, { "$ref": "#/components/parameters/RoleUuidHeader" } ], "responses": { "200": { "description": "PDF bytes.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Signer or document not found; `audit_certificate_not_available`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "`document_not_completed`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/publicapi/v1/signing/{sign_code}/sign": { "post": { "tags": [ "How they sign" ], "operationId": "signAsUser", "summary": "Sign (user's certificate + TOTP)", "description": "Sign the document **as the acting user**, with their own qualified\ncertificate, confirmed by their current authenticator (TOTP) code - the\nsame strong customer authentication the web app uses. The\n`signature_payload` placements must match the signer's annotations\n(count, type and coordinates).\n\nThe document must be PENDING, the signer `INVITED` or `VIEWED`, and it\nmust be the signer's turn per `signing_order` / `parallel_group`.\nBilling debits the acting role's existing signature entitlements (e.g.\n`one_sided_documents`) exactly like signing in the web app -\n**409 `insufficient_one_sided_document_balance`** on shortfall.\n\nFor documents sent through the API with a `return_url`, the\nresponse includes the signed `redirect_url` (see `send-document`).\n\n**XML documents** (`document_format: xml` on the signing session info): send\nonly `totp`. There are no placements - `signature_payload`,\n`timezone` and `stamp_branding` are ignored - and the platform appends\nan enveloped XAdES signature (level per the document's `ades_level`)\nwith the user's certificate. Only `signing_type: SIGNATURE` signers\nsign (422 `nothing_to_sign` otherwise); simple-signature signers are\nrefused (`signature_kind_not_supported_for_format`). The response adds\n`signature_format: xades` and `ades_level`.\n\n**Form PDFs** (`pdf_profile: form` on the signing session info): send `totp`\nand optionally `form_stamp` / `timezone`; `signature_payload` is\nignored. The user's certificate signs into **every** blank placeholder\nlisted in `form.placeholders` (one PDF revision each, legacy PKCS#7,\nappend-only - the profile ANAF's validator accepts). Without\n`form_stamp` the appearance is the Acrobat-style \"Digitally signed by\"\nblock at the placeholder's aspect; with it, the given ink inside the\nchosen branding frame (`stamp_branding: none` = ink only). Same signer\nrules as XML (`nothing_to_sign`,\n`signature_kind_not_supported_for_profile`). The response adds\n`pdf_profile: form` and the refreshed `form` metadata. Acrobat shows\nthe inherent \"form fields with property changes\" note on any signed\nXFA form (its own signatures too); ANAF's validator is unaffected.\n", "security": [ { "platformUserOAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SignCode" }, { "$ref": "#/components/parameters/RoleUuidHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "totp" ], "properties": { "totp": { "type": "string", "description": "The user's current 6-digit authenticator code." }, "form_stamp": { "$ref": "#/components/schemas/FormStamp" }, "signature_payload": { "type": "array", "description": "Required for standard PDF documents, ignored for XML and\nform PDFs. One entry per\nrequired annotation of this signer. Geometry\nis in PDF points with a top-left page origin (`x` right,\n`y` down) - same coordinate system as the `send-document`\nsignature placements.\n", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "SIGNATURE", "SEAL" ], "default": "SIGNATURE" }, "page": { "type": "integer", "minimum": 1, "description": "1-based page number." }, "x": { "type": "number", "description": "Left edge of the signature box, pt from the left page edge." }, "y": { "type": "number", "description": "Top edge of the signature box, pt from the top page edge." }, "width": { "type": "number", "description": "Box width in pt (recommended 133)." }, "height": { "type": "number", "description": "Box height in pt (recommended 53)." }, "stamp_branding": { "type": "string", "default": "simplifi" } } } }, "timezone": { "type": "string", "description": "IANA timezone for the visible stamp date (default Europe/Bucharest)." }, "return_url": { "type": "string", "format": "uri", "description": "Hosted SCA only (user not a member of your company): where\nthe Simplifi page sends the browser after signing,\nHMAC-signed with your `client_secret` like Sign with\nSimplifi. Must be `https` and covered by one of your\nregistered redirect URIs (prefix match at a `/` or `?`\nboundary), else **400 `invalid_return_url`**. Omitted → the\ndocument's own integrator `return_url` if any, else the\npage shows a completion screen.\n" } } } } } }, "responses": { "200": { "description": "Signed (`data.sign_code`; `data.redirect_url` for integrator-originated documents).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "`invalid_stamp_branding`, `invalid_timezone`, `invalid_return_url`, `invalid_form_stamp` (form PDFs: `form_stamp` is not an object / its `data` is not a decodable image)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "403": { "description": "Not authorized to sign this document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Signer or document not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`hosted_sca_required` (`data.sca_url`, `data.session_uuid`, `data.expires_at` - the acting user is not a member of your company: send them to the hosted SCA page and the stored request completes there) or `insufficient_one_sided_document_balance` (`data.shortfall`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/HostedScaRequiredError" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "422": { "description": "`totp_code_required`, `totp_not_configured`, `invalid_totp`, `signature_payload_annotation_count_mismatch`, `signature_payload_type_mismatch`, `invalid_signature_payload_type`, `invalid_signature_format`, `seal_not_allowed_for_prepaid_signer`, plus lifecycle / turn-order violations (e.g. it is not the signer's turn); XAdES / CAdES documents: `nothing_to_sign`, `signature_kind_not_supported_for_format`, `ades_level_unsupported`, `invalid_xml` (stored file no longer well-formed), `cms_unparsable` (stored .p7m no longer parses), `certificate_not_valid_at_signing_time`; form PDFs: `nothing_to_sign`, `signature_kind_not_supported_for_profile`, `form_no_placeholders`, `form_already_signed` (the stored file has no blank placeholder left), `form_too_many_placeholders`, `form_file_unreadable`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "`too_many_totp_attempts` - shared per-account TOTP lockout (5 wrong codes across any TOTP-gated operation locks the account's TOTP checks for 15 minutes). `data.retry_after_minutes` carries the wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/publicapi/v1/signing/{sign_code}/reject": { "post": { "tags": [ "How they sign" ], "operationId": "rejectAsUser", "summary": "Reject (as signer)", "description": "Reject the document as the acting user (their signer row must be\n`INVITED` or `VIEWED` on a PENDING document). Also TOTP-confirmed. The\ndocument becomes REJECTED and the owner is notified (plus the\n`document.rejected` webhook for integrator-originated documents).\n", "security": [ { "platformUserOAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SignCode" }, { "$ref": "#/components/parameters/RoleUuidHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "totp" ], "properties": { "totp": { "type": "string", "description": "The user's current 6-digit authenticator code." }, "reason": { "type": "string", "description": "Optional rejection reason (stored and forwarded)." } } } } } }, "responses": { "200": { "description": "Rejected (`data.document_uuid`; `data.redirect_url` for integrator-originated documents).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "403": { "description": "Not authorized to reject this document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Signer or document not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "`totp_code_required`, `totp_not_configured`, `invalid_totp`, plus lifecycle / signer-status violations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/publicapi/v1/account/roles": { "get": { "tags": [ "Sign-in, consent and tokens" ], "operationId": "listOwnRoles", "summary": "List my roles (source of x-role-uuid)", "description": "The authenticated user's roles with their UUIDs - this is where the\nvalue for the `x-role-uuid` company-context header comes from\n(`data.roles[].role_uuid` plus company and display fields). Pick the\nrole in the company whose subscription covers the API. Identity-gated:\nalways returns the caller's own roles; no `x-role-uuid` needed on this\ncall, and it works **before** a subscribed company context exists -\nunlike the rest of the surface it is not subscription-gated (402 here\nwould make the role UUID undiscoverable).\n\nWithout list query parameters the full `data.roles` array is returned.\nList mode (any of the parameters below) adds `pagination`.\n", "security": [ { "platformUserOAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "maximum": 100 } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "company_name", "role_code", "role_name", "short_form", "is_personal" ] } }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "company_uuid", "in": "query", "schema": { "type": "string" } }, { "name": "role_code", "in": "query", "schema": { "type": "string" } }, { "name": "is_personal", "in": "query", "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] } } ], "responses": { "200": { "description": "`data.roles[]` with `role_uuid`; `pagination` in list mode.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "description": "`platform_api_disabled` - the user-token surface is globally disabled (no 402 here: this route is not subscription-gated).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Invalid list or filter parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/publicapi/v1/platform/tokens": { "get": { "tags": [ "Sign-in, consent and tokens" ], "operationId": "listPlatformTokens", "summary": "List offline tokens", "description": "List the Keycloak **offline sessions** of the legacy shared\n`platform-api` client - i.e. the offline tokens currently authorized\non it. Without `role_uuid`, the acting user's own tokens are listed.\nWith `role_uuid` (a team member's role UUID), a **company admin**\nlists that member's tokens instead. Tokens minted through integrator\nclients (user sign-in) are managed per app with **Connected apps**.\n", "security": [ { "platformUserOAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RoleUuidHeader" }, { "name": "role_uuid", "in": "query", "required": false, "description": "Member role UUID - admin oversight of a team member's tokens.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Token list, most recently used first.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/PlatformOfflineToken" } } } } } } ] } } } }, "400": { "description": "`company_context_required`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "description": "`admin_role_required`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`member_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "`keycloak_sessions_unavailable`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "`keycloak_user_missing`, `keycloak_admin_not_configured`, `platform_api_client_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/publicapi/v1/platform/tokens/revoke": { "post": { "tags": [ "Sign-in, consent and tokens" ], "operationId": "revokePlatformToken", "summary": "Revoke an offline token", "description": "Revoke one offline session by its `session_id` (from the list response).\nThe stored offline refresh token stops working immediately; already\nissued access tokens expire naturally (minutes). Include `role_uuid` for\nthe company-admin variant (revoking a member's token). Revocation is\nrecorded as a security event.\n", "security": [ { "platformUserOAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RoleUuidHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id" ], "properties": { "session_id": { "type": "string", "description": "Offline session id from the list endpoint." }, "role_uuid": { "type": "string", "format": "uuid", "description": "Member role UUID (admin revoke)." } } } } } }, "responses": { "200": { "description": "Revoked (`data.status: revoked`, `data.session_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "`session_id_required`, `company_context_required`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "description": "`admin_role_required`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`member_not_found`, `token_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "`keycloak_revoke_failed`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "`keycloak_admin_not_configured`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/publicapi/v1/platform/retention": { "get": { "tags": [ "Retention" ], "operationId": "getRetentionPolicy", "summary": "Get retention policy", "description": "Read the company's document retention policy (company admin only;\nselect the company with `x-role-uuid`). `retention_days: null` means\nkeep forever (the default when no policy was ever set).\n", "security": [ { "platformUserOAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RoleUuidHeader" } ], "responses": { "200": { "description": "Current policy.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PlatformRetentionPolicy" } } } ] } } } }, "400": { "description": "`company_context_required`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "description": "`admin_role_required`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "put": { "tags": [ "Retention" ], "operationId": "setRetentionPolicy", "summary": "Set or clear retention policy", "description": "Set `retention_days` to 1-3650 to hard-delete the PDF files of terminal\ndocuments (COMPLETED / REJECTED / CANCELLED) that many days after the\nterminal transition, or to `null` to keep files forever. Metadata and\nthe audit trail are always preserved; purged file downloads return\n**410 `document_files_purged`**. Changes are recorded as a security\nevent.\n", "security": [ { "platformUserOAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RoleUuidHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "retention_days" ], "properties": { "retention_days": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 3650, "description": "Days to keep terminal documents' files; null = keep forever." } } } } } }, "responses": { "200": { "description": "Policy after the write.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PlatformRetentionPolicy" } } } ] } } } }, "400": { "description": "`company_context_required`, `retention_days_required`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "description": "`admin_role_required`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "`invalid_retention_days`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/publicapi/v1/signing/pack/{document_group_uuid}/sign": { "post": { "tags": [ "How they sign" ], "operationId": "signPackAsUser", "summary": "Sign a pack (one TOTP for all members)", "description": "Sign every pack member the authenticated user is currently allowed to sign, in one call, with **one TOTP code for the whole pack** and a shared signature timestamp. There is no per-document code cost: a 9-document pack needs a single authenticator code.\n\nTolerant by design: members that are already signed, not the user's turn, or not pending are reported `skipped`, not failed - safe to retry to finish a partial run. The TOTP challenge is only required when at least one qualified act (personal signature or company seal) is being applied; simple-signature-only packs skip it.\n\nEach entry pairs the member's `sign_code` with the same `signature_payload` shape used by the single-document sign operation. XML and form-PDF members (`document_format: xml` / `pdf_profile: form`) need no `signature_payload`; a form member takes an optional per-entry `form_stamp` (else the pack-level `form_stamp`, else the typed-name appearance).\n", "security": [ { "platformUserOAuth": [] } ], "parameters": [ { "name": "document_group_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The pack to sign (see `document_group_uuid` on document detail)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "documents" ], "properties": { "documents": { "type": "array", "minItems": 1, "description": "One entry per pack member to sign.", "items": { "type": "object", "required": [ "sign_code", "signature_payload" ], "properties": { "sign_code": { "type": "string" }, "signature_payload": { "type": "array", "description": "Same shape as the single-document sign operation (placements matching the signer's annotations). Not needed for XML / form-PDF members.", "items": { "type": "object" } }, "form_stamp": { "$ref": "#/components/schemas/FormStamp" } } } }, "totp": { "type": "string", "description": "The user's current 6-digit authenticator code. Required when at least one qualified signature or seal is applied; one code authorizes the entire pack.", "examples": [ "123456" ] }, "form_stamp": { "$ref": "#/components/schemas/FormStamp" }, "timezone": { "type": "string", "description": "Optional IANA timezone for the visible stamp timestamp (one instant shared by the whole pack).", "examples": [ "Europe/Bucharest" ] }, "return_url": { "type": "string", "format": "uri", "description": "Hosted SCA only - same rules as the single-document sign operation (https, covered by a registered redirect URI, else **400 `invalid_return_url`**)." } } } } } }, "responses": { "200": { "description": "Per-document results. `skipped` members do not fail the call; retry later to finish.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "document_group_uuid": { "type": "string", "format": "uuid" }, "summary": { "type": "object", "properties": { "requested": { "type": "integer" }, "signed": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" } } }, "documents": { "type": "array", "items": { "type": "object", "properties": { "sign_code": { "type": "string" }, "document_uuid": { "type": [ "string", "null" ], "format": "uuid" }, "status": { "type": "string", "enum": [ "signed", "skipped", "failed" ] }, "reason": { "type": "string", "description": "On skipped/failed only: e.g. `already_signed`, `not_your_turn`, `not_in_pack`, `signer_not_found`, `signature_payload_required`." } } } } } } } } ] } } } }, "400": { "description": "`invalid_timezone`, `invalid_return_url`, missing `document_group_uuid`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "`document_group_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`hosted_sca_required` (`data.sca_url` - the acting user is not a member of your company; one hosted confirmation covers the whole pack) or `insufficient_one_sided_document_balance` with `data.shortfall`", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/HostedScaRequiredError" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "422": { "description": "`documents is required and must be a non-empty array`, `totp_code_required`, `totp_not_configured`, `invalid_totp`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "`too_many_totp_attempts` - shared per-account TOTP lockout (5 wrong codes across any TOTP-gated operation locks the account's TOTP checks for 15 minutes). `data.retry_after_minutes` carries the wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/publicapi/v1/partner/customers": { "post": { "tags": [ "Onboard your users first (partner onboarding)" ], "operationId": "createPartnerCustomer", "summary": "Invite a customer to a sponsored account", "description": "Create a sponsored-account invitation under your partner program:\nthe same operation your company admins perform from the platform's\n*Sponsorships* console, machine-to-machine. Billing (`per_invitation`\nplans bill on create), rate limits and error codes are identical to\nthe console.\n\n**Distribution.** `simplifi_email`: Simplifi emails the invitation to\n`email` (co-branded with your program). `partner_delivered`: no email;\nthe response carries `hosted_url` and **you** deliver it (in-app\nmessage, your own email, a QR code) - `external_ref` is then\nrequired. Either way the person lands on the Simplifi-hosted\nonboarding, where they register or sign in, verify their identity,\nget their certificate and consent to the sponsorship; **no identity,\ncredential or acceptance is ever supplied by you**.\n\n**Consent hop (optional `oauth`).** If your client has user sign-in\nenabled, pass a PKCE challenge, your `state` and (optionally) one of\nyour registered redirect URIs. Once the sponsorship is `active`, the\nhosted onboarding offers the person a *Continue to {your app}* step\nwhose `continue_url` is the Keycloak authorization URL for **your**\nclient with exactly that material - your app receives the\nauthorization code on your redirect URI and exchanges it (with the\nverifier, server-side) for an offline token for the person you just\nonboarded, without a second login screen. The `oauth` object is\nvalidated before anything is created or billed.\n\nRe-inviting the same `external_ref` / email refreshes the existing\ninvitation (same `customer_uuid`, new token; a revoked one is\nrevived) rather than creating a duplicate. **201** on both.\n", "security": [ { "integratorOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerCustomerCreateRequest" } } } }, "responses": { "201": { "description": "Invitation created or refreshed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/PartnerCustomer" }, "hosted_url": { "type": "string", "format": "uri", "description": "`partner_delivered` only: the onboarding link to hand to the person. Shown once per create/resend; it is not retrievable later." } } } } } ] } } } }, "400": { "description": "`invalid_request`, `invalid_distribution`, `invalid_email`, `external_ref_required`, `invalid_external_ref`, `invalid_name`, `invalid_program_plan`; OAuth hop: `invalid_oauth`, `invalid_code_challenge`, `invalid_code_challenge_method`, `invalid_state`, `invalid_redirect_uri`, `redirect_uri_required`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "`integrator_unauthenticated` - missing/invalid/expired token, or an end-user token (this surface accepts the client's service account only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`access_not_enabled` - the company's API access is suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`partner_program_required` (no live partner program on this company), `program_not_active`, `link_already_exists`, `external_ref_in_use` (`data.invitation` carries the existing one), `user_auth_disabled` (an `oauth` object was sent but user sign-in is off for this client)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "`invitation_send_rate_limited` (`simplifi_email`; `data.retry_after_seconds`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "`invitation_email_queue_failed`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/publicapi/v1/partner/customers/{customer_uuid}": { "get": { "tags": [ "Onboard your users first (partner onboarding)" ], "operationId": "getPartnerCustomer", "summary": "Get a sponsored customer", "description": "Current state of one invitation / sponsorship, with the onboarding\n`steps` and the `next_step` the person still has to complete. Prefer\nthe `customer.*` webhooks for change notification and this call for\nreconciliation.\n", "security": [ { "integratorOAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerCustomerUuid" } ], "responses": { "200": { "description": "The customer record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/PartnerCustomer" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "404": { "description": "`customer_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`partner_program_required`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/publicapi/v1/partner/customers/{customer_uuid}/resend": { "post": { "tags": [ "Onboard your users first (partner onboarding)" ], "operationId": "resendPartnerCustomer", "summary": "Resend the invitation", "description": "Issue a fresh onboarding token for an invitation still in `invited`\n(the previous link stops working). `simplifi_email`: the email is sent\nagain (rate-limited); `partner_delivered`: a new `hosted_url` is\nreturned for you to deliver.\n", "security": [ { "integratorOAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerCustomerUuid" } ], "responses": { "200": { "description": "Token rotated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/PartnerCustomer" }, "hosted_url": { "type": "string", "format": "uri" } } } } } ] } } } }, "400": { "description": "`link_not_invited` - already claimed, active or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "404": { "description": "`customer_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`partner_program_required`, `program_not_active`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "`invitation_send_rate_limited` (`data.retry_after_seconds`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/publicapi/v1/partner/customers/{customer_uuid}/revoke": { "post": { "tags": [ "Onboard your users first (partner onboarding)" ], "operationId": "revokePartnerCustomer", "summary": "Revoke the sponsorship", "description": "End the sponsorship from your side (`revoked_by_partner`). An\nun-claimed invitation simply dies; an `active` sponsorship stops being\nbilled to your program and the person keeps their Simplifi account on\ntheir own terms. Emits `customer.revoked`.\n", "security": [ { "integratorOAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerCustomerUuid" } ], "responses": { "200": { "description": "Revoked.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/PartnerCustomer" } } } } } ] } } } }, "400": { "description": "`link_already_revoked`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "404": { "description": "`customer_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`partner_program_required`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/publicapi/v1/partner/customers/~webhook-events": { "get": { "tags": [ "Onboard your users first (partner onboarding)" ], "operationId": "partnerCustomerWebhookEvents", "x-webhook-catalog": true, "summary": "Webhook events", "description": "**Documentation only** - not a callable route. Sponsored-customer\nlifecycle events POSTed to webhook endpoints subscribed to them. The\npayload identifies the sponsorship (`customer_uuid`, your\n`external_ref`) and its new `status` - never the person's account\nidentity or contact details.\n\nOrder of a successful onboarding: `customer.invited` →\n`customer.onboarding` (the person claimed the link with an account)\n→ `customer.verified` (identity verification approved) →\n`customer.active` (certificate issued and sponsorship consented; the\nconsent hop `continue_url` is now offered). `customer.revoked` can\nfollow any state (by you or by the person).\n", "responses": { "501": { "description": "Not callable; documents outbound webhook payloads only." }, "4XX": { "$ref": "#/components/responses/Error4xx" } }, "callbacks": { "customer.invited": { "$ref": "#/components/callbacks/CustomerInvitedEvent" }, "customer.onboarding": { "$ref": "#/components/callbacks/CustomerOnboardingEvent" }, "customer.verified": { "$ref": "#/components/callbacks/CustomerVerifiedEvent" }, "customer.active": { "$ref": "#/components/callbacks/CustomerActiveEvent" }, "customer.revoked": { "$ref": "#/components/callbacks/CustomerRevokedEvent" } } } } }, "components": { "securitySchemes": { "integratorOAuth": { "type": "oauth2", "description": "Keycloak client_credentials. Token endpoint (production):\n`https://auth.simplifi.ro/realms/Simplifi/protocol/openid-connect/token`.\nDevelopment: `https://auth.dev.simplifi.ro/realms/Simplifi/protocol/openid-connect/token`.\n", "flows": { "clientCredentials": { "tokenUrl": "https://auth.simplifi.ro/realms/Simplifi/protocol/openid-connect/token", "scopes": {} } } }, "platformUserOAuth": { "type": "oauth2", "description": "**User tokens**: the user consents once on **your own API\nclient** with user sign-in enabled (authorization code + PKCE S256 to\na registered redirect URI, or the device grant) with the\n`offline_access` scope; your software stores the offline (refresh)\ntoken and exchanges it for short-lived access tokens with\n`grant_type=refresh_token`. Code exchange and refresh need your\n`client_secret`, so they run on your server only - never in a web or\nmobile app. No subscription; the gate is your company's API access\n(`403 access_not_enabled` when suspended, `403 user_auth_disabled`\nwhen user sign-in is off). See the \"Sign-in, consent and tokens\"\nsection.\n", "flows": { "authorizationCode": { "authorizationUrl": "https://auth.simplifi.ro/realms/Simplifi/protocol/openid-connect/auth", "tokenUrl": "https://auth.simplifi.ro/realms/Simplifi/protocol/openid-connect/token", "refreshUrl": "https://auth.simplifi.ro/realms/Simplifi/protocol/openid-connect/token", "scopes": { "openid": "OpenID Connect", "offline_access": "Mint a long-lived offline (refresh) token" } } } } }, "parameters": { "DocumentUuid": { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "SignCode": { "name": "sign_code", "in": "path", "required": true, "description": "The per-signer signing session code (from document detail / list responses).", "schema": { "type": "string" } }, "RoleUuidHeader": { "name": "x-role-uuid", "in": "header", "required": false, "description": "User tokens only: the user's role UUID selecting the\ncompany context to act in. Omit for the user's personal workspace\n(through your own client the access gate is checked against your\ncompany; legacy `platform-api` tokens need a company context or get\n402 `subscription_required`).\n", "schema": { "type": "string", "format": "uuid" } }, "PartnerCustomerUuid": { "name": "customer_uuid", "in": "path", "required": true, "description": "The sponsorship identifier returned at create (`customer.customer_uuid`) and carried by every `customer.*` webhook.", "schema": { "type": "string", "format": "uuid" } } }, "responses": { "Unauthenticated": { "description": "`integrator_unauthenticated` - missing/expired/invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "SubscriptionRequired": { "description": "`subscription_required` - the company's **API Access subscription**\n(required only for a separate, gated partner surface; send-document\nand acting as your users need no subscription) has no\nactive grant, or a user-token request ran without a company context.\nRelated 403 codes from the same gate: `access_not_enabled` (company API access suspended) and\n`platform_api_disabled` (user-token surface globally disabled).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "Error4xx": { "description": "Request failed; `error` carries a stable machine-readable code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "headers": { "AllowanceCode": { "description": "Entitlement category this request draws on.", "schema": { "type": "string", "enum": [ "csc_api_enrollments", "csc_api_signatures", "csc_api_packs" ] } }, "AllowanceRemaining": { "description": "Credits left in that category **before** this request's debit. Consumption is\nrecorded at the terminal event (IDV outcome, signing completion), not when the\nrequest is made, so this lags actual usage by one operation. Absent when the\ncompany is not in `enforce` metering mode.\n", "schema": { "type": "integer" } } }, "callbacks": { "DocumentSignerSignedEvent": { "{$request.body#/url}": { "post": { "summary": "A signer signed a Sign-with-Simplifi document", "operationId": "onDocumentSignerSigned", "description": "Fired for documents your integration created (origin tracked server-side).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDocumentSignerSigned" } } } }, "responses": { "200": { "description": "Return any 2xx quickly; process async." } } } } }, "DocumentCompletedEvent": { "{$request.body#/url}": { "post": { "summary": "A Sign-with-Simplifi document was fully executed", "operationId": "onDocumentCompleted", "description": "All signers have signed. Download the signed PDF from\n`GET /publicapi/v1/documents/{uuid}/file`.\n", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDocumentCompleted" } } } }, "responses": { "200": { "description": "Return any 2xx quickly; process async." } } } } }, "DocumentRejectedEvent": { "{$request.body#/url}": { "post": { "summary": "A signer rejected a Sign-with-Simplifi document", "operationId": "onDocumentRejected", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDocumentRejected" } } } }, "responses": { "200": { "description": "Return any 2xx quickly; process async." } } } } }, "WebhookTestEvent": { "{$request.body#/url}": { "post": { "summary": "Connectivity test event", "operationId": "onWebhookTest", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean" }, "message": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } ] } } } }, "responses": { "200": { "description": "Return any 2xx quickly; process async." } } } } }, "AllowanceLowEvent": { "{$request.body#/url}": { "post": { "summary": "Credit balance crossed the warning threshold", "operationId": "onAllowanceLow", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookAllowanceAlert" } } } }, "responses": { "200": { "description": "Return any 2xx quickly; process async." } } } } }, "AllowanceExhaustedEvent": { "{$request.body#/url}": { "post": { "summary": "Credit balance reached zero", "operationId": "onAllowanceExhausted", "description": "In `enforce` metering mode, requests that consume this credit type are\nnow refused with 402 until the balance is topped up.\n", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookAllowanceAlert" } } } }, "responses": { "200": { "description": "Return any 2xx quickly; process async." } } } } }, "SubscriptionAtRiskEvent": { "{$request.body#/url}": { "post": { "summary": "API Access subscription expires within the configured lookahead", "operationId": "onSubscriptionAtRisk", "description": "Fires ahead of the access expiry even for healthy auto-renewing\nsubscriptions (`reason: renewal_upcoming`); other reasons flag\nsomething to fix before access is interrupted. Re-fires if the\nreason changes (e.g. the renewal payment fails after the healthy\nheads-up already went out).\n", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionAlert" } } } }, "responses": { "200": { "description": "Return any 2xx quickly; process async." } } } } }, "SubscriptionLapsedEvent": { "{$request.body#/url}": { "post": { "summary": "API Access subscription has lapsed - calls are being refused", "operationId": "onSubscriptionLapsed", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionAlert" } } } }, "responses": { "200": { "description": "Return any 2xx quickly; process async." } } } } }, "CustomerInvitedEvent": { "{$request.body#/url}": { "post": { "operationId": "onCustomerInvited", "summary": "Sponsored-account invitation created (or revived)", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPartnerCustomerEvent" } } } }, "responses": { "200": { "description": "Return any 2xx quickly; process async." } } } } }, "CustomerOnboardingEvent": { "{$request.body#/url}": { "post": { "operationId": "onCustomerOnboarding", "summary": "The person claimed the invitation with a Simplifi account", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPartnerCustomerEvent" } } } }, "responses": { "200": { "description": "Return any 2xx quickly; process async." } } } } }, "CustomerVerifiedEvent": { "{$request.body#/url}": { "post": { "operationId": "onCustomerVerified", "summary": "Identity verification approved", "description": "Fired when the claimant's identity verification is approved (or immediately on claim when the account was already verified).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPartnerCustomerEvent" } } } }, "responses": { "200": { "description": "Return any 2xx quickly; process async." } } } } }, "CustomerActiveEvent": { "{$request.body#/url}": { "post": { "operationId": "onCustomerActive", "summary": "Sponsorship active", "description": "Certificate issued and sponsorship consented. If you supplied PKCE material, the hosted onboarding now offers the person the consent hop into your app (`continue_url`).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPartnerCustomerEvent" } } } }, "responses": { "200": { "description": "Return any 2xx quickly; process async." } } } } }, "CustomerRevokedEvent": { "{$request.body#/url}": { "post": { "operationId": "onCustomerRevoked", "summary": "Sponsorship revoked", "description": "`data.status` tells by whom: `revoked_by_partner` (your revoke call or console) or `revoked_by_customer` (the person ended it from their account).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPartnerCustomerEvent" } } } }, "responses": { "200": { "description": "Return any 2xx quickly; process async." } } } } } }, "schemas": { "Envelope": { "type": "object", "description": "Standard success envelope.", "properties": { "success": { "type": "integer", "enum": [ 1 ] }, "error": { "type": "array", "items": { "type": "string" }, "description": "Empty on success." }, "data": { "description": "Endpoint-specific response payload; see each operation's response schema." } } }, "ErrorEnvelope": { "type": "object", "description": "Standard error envelope; `error` carries stable machine codes.", "properties": { "success": { "type": "integer", "enum": [ 0 ] }, "error": { "type": "array", "items": { "type": "string" }, "examples": [ [ "document_not_found" ] ] }, "data": { "description": "Usually empty on errors; may carry endpoint-specific error context." } } }, "PostpaidStatus": { "type": "object", "description": "Postpaid companies only. The current UTC calendar month rated to date at your\nagreed rate card, plus your invoice history. Amounts are integers in the minor\nunit of `currency` (bani / cents) and **tax exclusive** - VAT is added on the\ninvoice. Usage covered by leftover pre-paid credits is not listed here.\n", "properties": { "period_start": { "type": "string", "format": "date-time", "description": "Start of the current billing month (UTC)." }, "period_end": { "type": "string", "format": "date-time", "description": "Exclusive end of the current billing month (UTC)." }, "currency": { "type": "string", "description": "ISO 4217, e.g. `RON` or `EUR`." }, "monthly_fee": { "type": "integer", "description": "Fixed monthly fee in minor units (0 when none)." }, "payment_terms_days": { "type": [ "integer", "null" ], "description": "Days until an issued invoice is due." }, "lines": { "type": "array", "description": "One line per category with usage this month. Categories with no uncovered usage are omitted.", "items": { "type": "object", "properties": { "entitlement_code": { "type": "string", "enum": [ "csc_api_enrollments", "csc_api_signatures", "csc_api_packs", "csc_api_simple_packs" ] }, "quantity": { "type": "integer" }, "unit_amount": { "type": "integer", "description": "Agreed unit price, minor units." }, "amount": { "type": "integer", "description": "`quantity` × `unit_amount`." } } } }, "subtotal": { "type": "integer", "description": "`monthly_fee` + sum of `lines[].amount`, minor units, tax exclusive." }, "includes_prior_uninvoiced_usage": { "type": "boolean", "description": "True when the rating also contains usage from an earlier month that has not been invoiced yet (late-arriving events, or a voided invoice). It will be billed with this month." }, "invoices": { "type": "array", "description": "Issued and in-preparation invoices, newest first (max 12).", "items": { "type": "object", "properties": { "period_start": { "type": "string", "format": "date-time" }, "period_end": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "draft", "open", "paid", "uncollectible" ], "description": "`draft` = being prepared, not yet sent; `open` = sent and awaiting payment." }, "currency": { "type": "string" }, "subtotal": { "type": "integer", "description": "Minor units, tax exclusive." }, "hosted_invoice_url": { "type": [ "string", "null" ], "description": "Stripe hosted invoice page (view / pay / download PDF). Null while the invoice is a draft." }, "due_date": { "type": [ "string", "null" ], "format": "date-time" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "WebhookAllowanceAlert": { "description": "`allowance.low` / `allowance.exhausted` payload.", "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "level": { "type": "string", "enum": [ "warning", "exhausted" ] }, "entitlement_code": { "type": "string", "enum": [ "csc_api_enrollments", "csc_api_signatures", "csc_api_packs", "csc_api_simple_packs" ] }, "remaining": { "type": "integer", "description": "Credits left when the alert fired." }, "threshold": { "type": [ "integer", "null" ], "description": "The configured warning threshold; null on exhausted alerts when no warning threshold is set." } } } } } ] }, "WebhookSubscriptionAlert": { "description": "`subscription.at_risk` / `subscription.lapsed` payload.", "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "level": { "type": "string", "enum": [ "warning", "exhausted" ], "description": "`warning` = at_risk, `exhausted` = lapsed." }, "reason": { "type": "string", "enum": [ "renewal_upcoming", "payment_failed", "cancellation_scheduled", "canceled", "no_subscription" ], "description": "Why the subscription needs attention. `renewal_upcoming` is a heads-up for a healthy auto-renewal." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "End of the current access grant; null on lapsed alerts (access already ended)." }, "days_left": { "type": "integer", "description": "Whole days until expiry; 0 on lapsed alerts." } } } } } ] }, "SendDocumentRequest": { "type": "object", "required": [ "signers", "documents" ], "properties": { "signers": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "$ref": "#/components/schemas/SendDocumentSigner" } }, "documents": { "type": "array", "minItems": 1, "maxItems": 20, "description": "One document is sent alone; two or more are sent as a pack (one signing session and one link per signer across all of them).", "items": { "$ref": "#/components/schemas/SendDocumentDocument" } }, "send_email": { "type": "integer", "enum": [ 0, 1 ], "default": 0, "description": "`0` (default): Simplifi sends no email to the signers; you deliver each\n`signing_url` and guest signers verify an SMS code on the page. `1`:\nSimplifi emails every invitation (and the guest `otp_channel` defaults\nto `none`).\n" }, "return_url": { "type": "string", "format": "uri", "description": "Where signers are redirected after the signing session (HMAC-signed parameters, as with the Document API). Must be one of the redirect URIs registered on your API client (400 `invalid_return_url`)." }, "expires_in_hours": { "type": "integer", "default": 72, "minimum": 1, "maximum": 720, "description": "Document expiry, counted from the send." } } }, "SendDocumentSigner": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "kind": { "type": "string", "enum": [ "simple", "qualified", "account" ], "default": "simple", "description": "See the tag description for signing session, account requirement and billing per kind. Uniform for the signer across a pack." }, "name": { "type": "string", "maxLength": 100, "description": "Signer's name. **Required for `simple`** - it is the name in the signature's Reason line (the signer may still correct it on the page); optional otherwise (identity verification / the account's own name wins). Prefilled on the guest page as `signer_name_prefill`." }, "signing_order": { "type": "integer", "default": 1, "minimum": 1, "maximum": 100, "description": "Sequential signing groups (lower signs first). Default `1` for everyone - every link is live at once." }, "otp_channel": { "type": "string", "enum": [ "sms", "email", "none" ], "description": "Guest kinds only (`simple` / `qualified`): how the signer proves their\nchannel on the page before signing. Default `sms` when\n`send_email: 0`, `none` when `send_email: 1`; `none` with\n`send_email: 0` is refused (400 `otp_channel_required`). On an\n`account` signer any of the three OTP fields answers 400\n`otp_channel_not_applicable`.\n" }, "phone": { "type": "string", "description": "Optional prefill of the signer's mobile number for the `sms` channel (E.164, or a Romanian national number - normalized). The signer can change it unless `phone_locked`." }, "phone_locked": { "type": "boolean", "default": false, "description": "Fix the number - the page shows it read-only and refuses any other number (`phone` required when true)." } } }, "SendDocumentDocument": { "type": "object", "required": [ "name", "pdf_base64" ], "properties": { "name": { "type": "string", "description": "Document title shown to signers and in the app." }, "pdf_base64": { "type": "string", "format": "byte", "description": "The PDF, base64-encoded (400 `invalid_pdf_base64` when the decoded bytes are not a PDF; the Document API's intake gate then validates and normalizes it)." }, "file_name": { "type": "string", "description": "Stored file name; defaults to `.pdf`." }, "signatures": { "type": "array", "description": "Signature boxes on this document. A signer without an entry gets a default box on the last page, bottom-left (133 × 53 pt at x = 100, stacked upward per signer).", "items": { "$ref": "#/components/schemas/SendDocumentPlacement" } } } }, "SendDocumentPlacement": { "type": "object", "required": [ "signer", "page", "x", "y" ], "description": "Geometry in PDF points with a top-left page origin (`x` right, `y` down) - the same coordinate system as Document API annotations.", "properties": { "signer": { "type": "integer", "description": "Index into `signers` (0-based)." }, "page": { "type": "integer", "minimum": 1, "description": "1-based page number." }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "default": 133, "description": "Recommended 133 (the stamp does not shrink below it; the branded frame draws ~75 pt left of `x` and ~15 pt below the box)." }, "height": { "type": "number", "default": 53 } } }, "SendDocumentResponse": { "type": "object", "properties": { "document_uuid": { "type": "string", "format": "uuid", "description": "The first document (the guest primary - guest links resolve through it). Use it with `GET /publicapi/v1/documents/{uuid}` for the whole pack." }, "document_group_uuid": { "type": "string", "format": "uuid", "description": "The pack. Present for a single document too (a standalone document is a pack of one)." }, "documents": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "lifecycle": { "type": "string", "examples": [ "PENDING" ] } } } }, "expires_at": { "type": "string", "format": "date-time" }, "send_email": { "type": "integer" }, "return_url": { "type": [ "string", "null" ], "format": "uri" }, "signers": { "type": "array", "items": { "$ref": "#/components/schemas/SendDocumentSignerResult" } }, "allowance": { "$ref": "#/components/schemas/SendDocumentAllowance" } } }, "SendDocumentSignerResult": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "kind": { "type": "string", "enum": [ "simple", "qualified", "account" ] }, "name": { "type": [ "string", "null" ] }, "signing_order": { "type": "integer" }, "sign_code": { "type": "string", "description": "The per-signer signing session code (guest kinds - of the first document, one link for the pack)." }, "signing_url": { "type": "string", "format": "uri", "description": "Ready-to-use link to deliver to the signer - the hosted guest page for `simple` / `qualified`, the Simplifi app's sign-receive page for `account`." }, "status": { "type": "string", "examples": [ "INVITED" ] }, "otp_channel": { "type": "string", "enum": [ "sms", "email", "none" ], "description": "Guest kinds only." }, "phone_masked": { "type": [ "string", "null" ], "description": "Guest kinds only; the prefilled number, masked (`+40*******56`). Raw numbers are never returned." }, "phone_locked": { "type": "boolean", "description": "Guest kinds only." }, "platform_api_sign": { "type": "string", "description": "`account` kind only: the user sign endpoint your software calls as the user (member → body TOTP; non-member → 409 `hosted_sca_required`).", "examples": [ "/publicapi/v1/signing/{sign_code}/sign" ] } } }, "SendDocumentAllowance": { "type": "object", "description": "Per entitlement code (`prepaid_envelopes`, `sponsored_signing_invitations`, `simple_signature_envelopes`), only the categories this request charges.", "additionalProperties": { "type": "object", "properties": { "required": { "type": "integer", "description": "Units this request needs (present on refusals)." }, "remaining": { "type": "integer", "description": "Balance - after the send on success, at the check on a refusal." }, "debited_at": { "type": "string", "enum": [ "send", "completion" ], "description": "`completion` for `simple_signature_envelopes` (one per pack when it completes); otherwise debited at send." } } } }, "SignWithSimplifiDocumentDetail": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "lifecycle_status": { "type": "string", "enum": [ "DRAFT", "PENDING", "COMPLETED", "REJECTED", "CANCELLED" ] }, "signature_level": { "type": "string" }, "ownership": { "type": "string", "enum": [ "company", "personal" ] }, "files_purged": { "type": "boolean", "description": "true when the PDF files were hard-deleted from disk (retention\npolicy, delete purge, or all-participants-deleted). Metadata and\nsigners remain; file downloads return 410 `document_files_purged`.\n" }, "audit_certificate_available": { "type": "boolean", "description": "true when the sealed Certificate of Completion exists (or will be regenerated on demand) - fetch it with `GET /publicapi/v1/documents/{uuid}/audit-certificate`. false means it does not and will not exist, e.g. documents completed before audit certificates shipped - hide the download action.\n" }, "return_url": { "type": "string", "format": "uri", "description": "Echo of the integrator return URL when this document was created by your API client." }, "document_format": { "$ref": "#/components/schemas/DocumentFormat" }, "signature_format": { "$ref": "#/components/schemas/SignatureFormat" }, "ades_level": { "$ref": "#/components/schemas/AdesLevel" }, "allowed_signature_formats": { "type": "array", "description": "DRAFT documents only. Containers this draft can be switched to with `PUT /documents/{uuid}` (`signature_format`), derived from the stored bytes; always contains the current `signature_format`. Drive the cog-tab selector from this.", "items": { "$ref": "#/components/schemas/SignatureFormat" } }, "pdf_profile": { "$ref": "#/components/schemas/PdfProfile" }, "form": { "$ref": "#/components/schemas/PdfFormMetadata" }, "form_candidates": { "$ref": "#/components/schemas/PdfFormCandidates" }, "file_summary": { "$ref": "#/components/schemas/AdesFileSummary" }, "existing_signatures": { "type": "array", "description": "XAdES / CAdES documents only (and only while files are not purged). Signatures currently embedded in the file - render these instead of a page viewer.", "items": { "$ref": "#/components/schemas/XmlEmbeddedSignature" } }, "signers": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "status": { "type": "string" }, "signing_type": { "type": "string" }, "invitation_type": { "type": "string" }, "signature_kind": { "type": "string", "enum": [ "qualified", "simple" ], "description": "Signature kind requested for this signer (see add signers)." }, "verification_status": { "type": "string", "enum": [ "in_progress", "declined", "failed" ], "description": "Guest signers only; omitted unless identity verification is in a noteworthy state. Computed alongside `status` (which stays on the INVITED/VIEWED/SIGNED/REJECTED state machine). Decline reasons are never exposed on owner surfaces." }, "verification_retryable": { "type": "boolean", "description": "Present with `verification_status` `declined` or `failed`: whether the guest can retry identity verification (same answer the guest's own retry screen shows)." }, "sign_code": { "type": "string", "description": "Present for documents your integration created." }, "signing_url": { "type": "string", "format": "uri", "description": "Ready-to-use end-user signing/redirect URL." } } } }, "is_current": { "type": "boolean", "description": "Present in pack views: true on the document whose uuid was requested." } } }, "DocumentFormat": { "type": "string", "enum": [ "pdf", "xml", "binary" ], "description": "What the stored bytes are, detected at upload. `pdf` and `xml` drive the UI (page viewer vs. file summary); `binary` is opaque content on the CAdES pipeline (any file type, or a PDF wrapped in a `.p7m` instead of PAdES-signed). The signing container is `signature_format`, not this." }, "SignatureFormat": { "type": "string", "enum": [ "pades", "xades", "cades" ], "description": "Signature container applied at signing - `pades` for PDF, `xades` (enveloped XAdES-BASELINE) for XML, `cades` (CMS SignedData `.p7m`, CAdES-BASELINE, parallel SignerInfos for co-signing) for any file." }, "AdesLevel": { "type": [ "string", "null" ], "enum": [ "legacy", "B", "T", "LT", "LTA", null ], "description": "Signature level of the document, one vocabulary for every container. `legacy` = Adobe PKCS#7\n(`adbe.pkcs7.detached`, PDF only; always used by form PDFs). `B` / `T` (signature timestamp) /\n`LT` (embedded revocation data) / `LTA` (archive timestamp) = the ETSI baseline profiles of\nthe container (PAdES-, XAdES-, CAdES-BASELINE). PDF documents implement all five; XML and\n`.p7m` implement `B` today and return `ades_level_unsupported` for the rest. `null` only on\nPDF documents created before per-document levels existed and already sent - they were\nsigned at the platform default of the time.\n" }, "PdfProfile": { "type": "string", "enum": [ "standard", "form" ], "default": "standard", "description": "PDF documents only (omitted for XML). `standard`: signatures are stamped at the\nplacements (annotations) the owner draws on the pages. `form`: the PDF is a form\nwith its own signature placeholders (dynamic/static XFA such as ANAF D700/C801, or\nan AcroForm with blank signature fields); the signature is written into every blank\nplaceholder, there are no annotations, and exactly one signing signer is allowed\n(`standard_invitation`, `qualified`). XFA forms are always `form` (asking for\n`standard` is refused with `form_profile_required`); AcroForm-only files default to\n`standard` and can opt in at create or via PATCH while DRAFT.\n" }, "PdfFormMetadata": { "type": [ "object", "null" ], "description": "Present on PDF documents; non-null only when `pdf_profile` is `form`. What the platform found in the form (refreshed after each signature).", "properties": { "kind": { "type": "string", "enum": [ "xfa_dynamic", "xfa_static", "acroform", "none" ] }, "universal_code": { "type": [ "string", "null" ], "description": "ANAF form identifier from the embedded XFA data (e.g. `D700_A1.0.0`), when present." }, "form_code": { "type": [ "string", "null" ], "examples": [ "D700" ] }, "form_version": { "type": [ "string", "null" ] }, "usage_rights": { "type": "boolean", "description": "The form carries Adobe Reader extensions (usage-rights signature); kept intact by append-only signing." }, "certified": { "type": "boolean" }, "existing_signatures": { "type": "integer", "description": "Signatures already in the file (excluding the usage-rights one)." }, "embedded_files": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "size": { "type": [ "integer", "null" ] } } } }, "placeholders": { "type": "array", "description": "Blank signature boxes that will each receive the signature. Empty once signed.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Field name (XFA SOM path for XFA forms, e.g. `form1[0].final[0].semnatura[0]`)." }, "label": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "xfa", "acroform" ] }, "aspect": { "type": [ "number", "null" ], "description": "Width / height of the placeholder box; the signature appearance is rendered at this aspect." }, "box_pt": { "type": [ "object", "null" ], "properties": { "w": { "type": "number" }, "h": { "type": "number" } } }, "page": { "type": [ "integer", "null" ], "description": "1-based page for AcroForm widgets; null for XFA fields (Acrobat lays them out)." } } } }, "warnings": { "type": "array", "items": { "type": "string", "enum": [ "no_embedded_xml", "already_signed", "certified_document", "no_placeholders" ] } }, "inspected_at": { "type": "string", "format": "date-time" } } }, "PdfFormCandidates": { "type": "array", "description": "Only on `standard` PDFs that are AcroForms with blank signature fields - the\nplaceholders the owner could switch to with `pdf_profile: form`.\n", "items": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "page": { "type": [ "integer", "null" ] } } } }, "FormStamp": { "type": "object", "description": "Form PDFs only - the visible appearance drawn inside each placeholder (rendered\nat the placeholder's aspect). Omit it entirely for the Acrobat-style\n\"Digitally signed by …\" typed-name block. The same object is accepted at the\npack level and per pack member (member wins).\n", "properties": { "data": { "type": "string", "description": "Base64 PNG of the signer's ink/signature image (a `data:image/png;base64,` prefix is accepted). Max 2 MiB." }, "stamp_branding": { "type": "string", "default": "simplifi", "description": "Branding frame around the ink (`simplifi`, `transparent`, `minimal`) or `none` for the ink alone, letterboxed into the placeholder." } } }, "XmlFileSummary": { "type": [ "object", "null" ], "description": "XML documents only. Parsed facts about the stored file. `schema` is `pl_mf_esf` for Polish Ministry of Finance financial statements, with recognised header values in `fields`; `null` schema and empty `fields` for any other XML.", "properties": { "root_element": { "type": "string" }, "root_namespace": { "type": [ "string", "null" ] }, "encoding": { "type": "string" }, "size_bytes": { "type": "integer" }, "sha256": { "type": "string", "description": "Hex SHA-256 of the current file bytes." }, "signature_count": { "type": "integer" }, "schema": { "type": [ "string", "null" ], "examples": [ "pl_mf_esf" ] }, "fields": { "type": "object", "additionalProperties": true, "description": "Schema-specific recognised values, e.g. `company_name`, `nip`, `krs`, `period_from`, `period_to`, `prepared_on`, `form_code`, `form_variant` for `pl_mf_esf`." } } }, "CadesFileSummary": { "type": [ "object", "null" ], "description": "CAdES documents only (`signature_format: cades`). Facts about the stored\nfile - the plain upload before the first signature (`container: none`) or the CMS\nSignedData `.p7m` after (`container: cms`) - and about the content it wraps.\n", "properties": { "container": { "type": "string", "enum": [ "none", "cms" ] }, "detected_format": { "type": [ "string", "null" ], "enum": [ "pdf", "xml", "binary", null ], "description": "Sniffed type of the (wrapped) content." }, "mime": { "type": "string", "description": "`application/octet-stream` before signing, `application/pkcs7-mime` once wrapped." }, "size_bytes": { "type": "integer", "description": "Size of the stored file (envelope included once signed)." }, "sha256": { "type": "string", "description": "Hex SHA-256 of the stored file bytes." }, "content_size_bytes": { "type": [ "integer", "null" ] }, "content_sha256": { "type": [ "string", "null" ], "description": "Hex SHA-256 of the wrapped content - the original file, stable across co-signatures." }, "signature_count": { "type": "integer" }, "content_summary": { "oneOf": [ { "$ref": "#/components/schemas/XmlFileSummary" }, { "type": "null" } ], "description": "When the content is XML, the same summary an XAdES document gets." } } }, "AdesFileSummary": { "description": "`file_summary` of a non-PAdES document: `XmlFileSummary` on the XAdES pipeline, `CadesFileSummary` on the CAdES pipeline (tell them apart by `signature_format`, or by the presence of `container`).", "oneOf": [ { "$ref": "#/components/schemas/XmlFileSummary" }, { "$ref": "#/components/schemas/CadesFileSummary" } ] }, "XmlEmbeddedSignature": { "type": "object", "description": "One signature found in the document file - an enveloped `ds:Signature` of an XML, or a SignerInfo of a CMS `.p7m` - with the platform's structural verification result. Not a trust-list validation.", "properties": { "index": { "type": "integer" }, "id": { "type": [ "string", "null" ], "description": "The `ds:Signature/@Id` (XML); `null` for CMS SignerInfos." }, "format": { "type": "string", "enum": [ "xades", "xmldsig", "cades", "cms" ], "description": "`xades` / `cades` when the signature carries the ETSI qualifying properties (SignedProperties / ESS signing-certificate); plain `xmldsig` / `cms` otherwise." }, "level": { "type": [ "string", "null" ], "description": "Detected baseline level (`B`, `T`, `LT`, `LTA`) when XAdES / CAdES." }, "algorithm": { "type": [ "string", "null" ], "description": "SignatureMethod URI (XML) or `rsa-sha256` / `ecdsa-sha256` style label (CMS)." }, "signing_time": { "type": [ "string", "null" ], "format": "date-time" }, "enveloped": { "type": "boolean", "description": "`true` for an enveloped XML signature; always `false` for CMS SignerInfos (the envelope wraps the content, not the other way round)." }, "signer": { "type": [ "object", "null" ], "properties": { "common_name": { "type": [ "string", "null" ] }, "serial_number_attribute": { "type": [ "string", "null" ], "description": "The certificate subject `serialNumber` (e.g. `PNOPL-85010112345`, `TINIT-RSSMRA…`)." }, "identifier_scheme": { "type": [ "string", "null" ], "description": "Parsed ETSI EN 319 412-1 prefix of `serial_number_attribute` (`PNO`, `TIN`, `PAS`, `IDC`, …)." }, "issuer": { "type": [ "string", "null" ] }, "certificate_serial_hex": { "type": [ "string", "null" ] }, "certificate_sha256": { "type": [ "string", "null" ] }, "not_before": { "type": [ "string", "null" ], "format": "date-time" }, "not_after": { "type": [ "string", "null" ], "format": "date-time" }, "key": { "type": [ "string", "null" ], "description": "Key type and size, e.g. `rsa-2048`, `ec-256`." } } }, "digests_ok": { "type": [ "boolean", "null" ], "description": "Every `ds:Reference` digest (XML) / the CMS `messageDigest` attribute matches the current content." }, "signature_ok": { "type": [ "boolean", "null" ], "description": "The `SignatureValue` (XML) / SignerInfo `signature` over the signed attributes (CMS) verifies against the embedded certificate." }, "signing_certificate_match": { "type": [ "boolean", "null" ], "description": "The XAdES `SigningCertificate` / CAdES ESS `signing-certificate(-v2)` digest matches the embedded certificate." }, "valid": { "type": "boolean", "description": "All of the above hold." }, "issues": { "type": "array", "items": { "type": "string" } } } }, "Pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "PlatformDocumentSummary": { "type": "object", "description": "One row of the document list. `uuid` is present on documents the acting\nprincipal owns; `sign_code` on documents where the acting user is a\nsigner. Timestamps are ISO 8601 UTC.\n", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Owner rows only." }, "sign_code": { "type": "string", "description": "Rows where the acting user is a signer." }, "name": { "type": "string" }, "lifecycle": { "type": "string", "enum": [ "DRAFT", "PENDING", "COMPLETED", "REJECTED", "CANCELLED", "EXPIRED" ] }, "signature_level": { "type": "string", "enum": [ "QUALIFIED", "ADVANCED", "SIMPLE" ] }, "ownership": { "type": "string", "enum": [ "personal", "company" ], "description": "Owner rows only." }, "document_format": { "$ref": "#/components/schemas/DocumentFormat" }, "signature_format": { "$ref": "#/components/schemas/SignatureFormat" }, "owner_name": { "type": "string" }, "size_bytes": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "signer_status": { "type": "object", "properties": { "total": { "type": "integer" }, "signed": { "type": "integer" }, "viewed": { "type": "integer" }, "invited": { "type": "integer" }, "rejected": { "type": "integer" }, "draft": { "type": "integer" } } }, "verification_status": { "type": "object", "description": "Guest identity-verification breakdown. Present only when at least one guest signer is in a noteworthy verification state; counts of guest signers per category.", "properties": { "in_progress": { "type": "integer" }, "declined": { "type": "integer" }, "failed": { "type": "integer" } } }, "recipients": { "type": "array", "items": { "type": "string" } }, "recipients_total": { "type": "integer" }, "action_required": { "type": "array", "description": "Only with `scope=all_related`.", "items": { "type": "string", "enum": [ "needs_my_signature", "waiting_for_others" ] } } } }, "PlatformDocumentStatistics": { "type": "object", "properties": { "needs_my_signature": { "type": "object", "properties": { "total": { "type": "integer" }, "new_last_24h": { "type": "integer" } } }, "waiting_for_others": { "type": "object", "properties": { "total": { "type": "integer" }, "older_than_3_days": { "type": "integer" } } }, "completed_last_30_days": { "type": "object", "properties": { "total": { "type": "integer" }, "previous_30_days": { "type": "integer" } } }, "signed_last_30_days": { "type": "object", "properties": { "total": { "type": "integer" }, "unique_senders": { "type": "integer" } } } } }, "PlatformOfflineToken": { "type": "object", "properties": { "session_id": { "type": "string", "description": "Keycloak offline session id (use to revoke)." }, "ip": { "type": "string" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_access_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "PlatformRetentionPolicy": { "type": "object", "properties": { "retention_days": { "type": [ "integer", "null" ], "description": "1-3650, or null = keep forever." }, "updated_at": { "type": [ "string", "null" ], "description": "When the policy was last changed (null if never set)." } } }, "WebhookDocumentSignerSigned": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "const": "document.signer.signed" }, "data": { "type": "object", "properties": { "document_uuid": { "type": "string", "format": "uuid" }, "document_group_uuid": { "type": "string" }, "signer_email": { "type": "string", "format": "email" }, "signed_at": { "type": "string", "format": "date-time" } } } } } ] }, "WebhookDocumentCompleted": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "const": "document.completed" }, "data": { "type": "object", "properties": { "document_uuid": { "type": "string", "format": "uuid" }, "document_group_uuid": { "type": "string" }, "status": { "type": "string", "const": "COMPLETED" }, "completed_at": { "type": "string", "format": "date-time" } } } } } ] }, "WebhookDocumentRejected": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "const": "document.rejected" }, "data": { "type": "object", "properties": { "document_uuid": { "type": "string", "format": "uuid" }, "document_group_uuid": { "type": "string" }, "status": { "type": "string", "const": "REJECTED" }, "rejected_by_email": { "type": "string", "format": "email" }, "reason": { "type": "string" }, "rejected_at": { "type": "string", "format": "date-time" } } } } } ] }, "WebhookEnvelope": { "type": "object", "description": "Common webhook envelope. Verify `X-Simplifi-Signature: sha256={hmac}` -\nHMAC-SHA256 over the raw JSON body with your endpoint signing_secret.\nDeliveries are retried with exponential backoff (up to 8 attempts); use `id`\nfor idempotent processing (resends keep the same `id`).\n", "properties": { "id": { "type": "string", "format": "uuid", "description": "Delivery UUID - stable across retries and resends." }, "type": { "type": "string", "examples": [ "application.verified" ] }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object" } } }, "SignWithSimplifiDocumentPack": { "type": "object", "description": "Pack (document group) wrapper returned by `GET /publicapi/v1/documents/{uuid}`. Every document belongs to a group; standalone documents are groups of one.\n", "properties": { "document_group_uuid": { "type": [ "string", "null" ], "format": "uuid", "description": "null only on legacy documents created before packs existed." }, "sent_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the group was sent (null while DRAFT)." }, "member_count": { "type": "integer" }, "current_document_uuid": { "type": "string", "format": "uuid" }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/SignWithSimplifiDocumentDetail" } } } }, "HostedScaRequiredError": { "allOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "type": "object", "description": "Returned by the sign operations when the acting user is **not a\nmember of the integrator's company**: strong customer authentication\nmust happen on a Simplifi-hosted page, never in a third-party UI.\nThe request has already passed validation and billing preflight; the\nplatform stored it and only waits for the user's authenticator code.\n", "properties": { "error": { "type": "array", "items": { "type": "string", "enum": [ "hosted_sca_required" ] } }, "data": { "type": "object", "properties": { "session_uuid": { "type": "string", "format": "uuid" }, "sca_url": { "type": "string", "format": "uri", "description": "Send the user's browser here (or open it in an in-app browser). Single-use token; re-requesting the same signature rotates it." }, "expires_at": { "type": "string", "format": "date-time", "description": "The hosted session's expiry (default 30 minutes)." }, "sca_method": { "type": "string", "enum": [ "totp" ] } } } } } ] }, "PartnerCustomerOauth": { "type": "object", "description": "PKCE material for the consent hop. Validated before the invitation is created or billed.", "required": [ "code_challenge", "state" ], "properties": { "code_challenge": { "type": "string", "description": "PKCE S256 challenge (43-128 chars of `A-Z a-z 0-9 - _`), computed from a verifier **you keep server-side**." }, "code_challenge_method": { "type": "string", "enum": [ "S256" ], "default": "S256" }, "state": { "type": "string", "maxLength": 256, "description": "Your opaque CSRF/state value; returned verbatim on your redirect URI." }, "redirect_uri": { "type": "string", "format": "uri", "description": "One of your client's registered redirect URIs. Omitted → the first registered one. If the chosen URI is removed from the allowlist later, the hop falls back to the first registered one, never to the removed one." } } }, "PartnerCustomerCreateRequest": { "type": "object", "required": [ "distribution" ], "properties": { "distribution": { "type": "string", "enum": [ "simplifi_email", "partner_delivered" ] }, "email": { "type": "string", "format": "email", "description": "Required for `simplifi_email`. Delivery address and prefill only - the person may register with a different address." }, "given_name": { "type": "string" }, "surname": { "type": "string" }, "external_ref": { "type": "string", "description": "Your own identifier for this person (required for `partner_delivered`; unique per program - re-sending with the same value refreshes the invitation)." }, "program_plan_uuid": { "type": "string", "format": "uuid", "description": "Which plan of your program sponsors the account. Omitted → the program's default plan." }, "oauth": { "$ref": "#/components/schemas/PartnerCustomerOauth" } } }, "PartnerCustomer": { "type": "object", "description": "A sponsored-account invitation / sponsorship as seen by the partner. Carries no account identity of the person - only what you supplied and the lifecycle state.", "properties": { "customer_uuid": { "type": "string", "format": "uuid" }, "distribution": { "type": "string", "enum": [ "simplifi_email", "partner_delivered" ] }, "external_ref": { "type": [ "string", "null" ] }, "invited_email": { "type": [ "string", "null" ] }, "invited_given_name": { "type": [ "string", "null" ] }, "invited_surname": { "type": [ "string", "null" ] }, "plan": { "type": "object", "properties": { "program_plan_uuid": { "type": [ "string", "null" ], "format": "uuid" }, "product_name": { "type": [ "string", "null" ] } } }, "status": { "type": "string", "enum": [ "invited", "onboarding", "active", "revoked_by_partner", "revoked_by_customer" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "token_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Expiry of the current onboarding link (resend rotates it)." }, "consent_at": { "type": [ "string", "null" ], "format": "date-time" }, "activated_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "billed_at": { "type": [ "string", "null" ], "format": "date-time" }, "email_send_count": { "type": "integer" }, "last_sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "steps": { "type": "object", "description": "Hosted-onboarding progress.", "properties": { "claimed": { "type": "boolean" }, "identity_verified": { "type": "boolean" }, "certificate_issued": { "type": "boolean" }, "consent_given": { "type": "boolean" }, "active": { "type": "boolean" } } }, "next_step": { "type": "string", "enum": [ "claim", "identity_verification", "certificate", "consent", "done", "revoked" ] }, "oauth_hop": { "type": "boolean", "description": "Whether PKCE material is stored on this sponsorship (a `continue_url` will be offered once `active`)." } } }, "WebhookPartnerCustomerEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "customer.invited", "customer.onboarding", "customer.verified", "customer.active", "customer.revoked" ] }, "data": { "type": "object", "properties": { "customer_uuid": { "type": "string", "format": "uuid" }, "external_ref": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "invited", "onboarding", "active", "revoked_by_partner", "revoked_by_customer" ] }, "distribution": { "type": "string", "enum": [ "simplifi_email", "partner_delivered" ] }, "event_at": { "type": "string", "format": "date-time" } } } } } ] } } } }