{ "variable": [ { "id": "baseUrl", "key": "baseUrl", "type": "string", "name": "string", "value": "https:\/\/elemza.com" } ], "info": { "name": "Emza Platform \u2014 Public API v1", "_postman_id": "7f2c2ec4-e82b-426f-b63c-1fcb2942ff6e", "description": "Public REST API for Contract creation and Electronic Signature lifecycle. Bilingual (fa\/en) errors. RFC 7807 problem+json envelope.", "schema": "https:\/\/schema.getpostman.com\/json\/collection\/v2.1.0\/collection.json" }, "item": [ { "name": "Contracts", "description": "", "item": [ { "name": "Public signed-URL download.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/contracts\/:code\/dl", "query": [], "raw": "{{baseUrl}}\/api\/v1\/contracts\/:code\/dl", "variable": [ { "id": "code", "key": "code", "value": "architecto", "description": "16-char public code." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Validates Laravel's `signed` middleware. No Bearer token required \u2014\nthe URL signature is the auth proof. The signature is generated by\n`downloadPdf()` after the bearer was verified, so this is functionally\nequivalent to a 24h time-bounded capability URL.\n\nRecords an `ApiRequestLog`-style entry via the underlying `ContractDownload`\naudit table (same trail as the user-panel signed-link download flow)." }, "response": [ { "header": [ { "key": "x-request-id", "value": "01M0TB569B06B153MHVXBVGBW2" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/problem+json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 404, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/not_found\",\"status\":404,\"code\":\"not_found\",\"title_fa\":\"\\u0645\\u0646\\u0628\\u0639 \\u06cc\\u0627\\u0641\\u062a \\u0646\\u0634\\u062f\",\"title_en\":\"Resource not found\",\"request_id\":\"01M0TB569B06B153MHVXBVGBW2\"}", "name": "" } ] }, { "name": "List contracts", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/contracts", "query": [ { "key": "status", "value": "waiting_signature", "description": "Filter by status: draft|waiting_signature|completed|voided|canceled.", "disabled": false }, { "key": "signature_method", "value": "digital", "description": "Filter by signing method: electronic|digital.", "disabled": false }, { "key": "created_after", "value": "2026-01-01T00:00:00Z", "description": "ISO 8601 datetime.", "disabled": false }, { "key": "created_before", "value": "architecto", "description": "ISO 8601 datetime.", "disabled": false }, { "key": "signer_mobile", "value": "09121234567", "description": "Iran mobile regex 09XXXXXXXXX. **Requires `signers:read_pii` scope.**", "disabled": false }, { "key": "signer_national_code", "value": "architecto", "description": "10-digit Iran national code. **Requires `signers:read_pii` scope.**", "disabled": false }, { "key": "template_id", "value": "16", "description": "Filter by template.", "disabled": false }, { "key": "is_private", "value": "", "description": "Filter by privacy flag.", "disabled": true }, { "key": "page", "value": "16", "description": "Default 1.", "disabled": false }, { "key": "per_page", "value": "16", "description": "Max 100. Default 20.", "disabled": false }, { "key": "sort", "value": "architecto", "description": "created_at | -created_at | completed_at | -completed_at. Default -created_at.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/contracts?status=waiting_signature&signature_method=digital&created_after=2026-01-01T00%3A00%3A00Z&created_before=architecto&signer_mobile=09121234567&signer_national_code=architecto&template_id=16&is_private=&page=16&per_page=16&sort=architecto" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"status\":\"waiting_signature\",\"signature_method\":\"digital\",\"created_after\":\"2026-08-24T20:25:15\",\"created_before\":\"2026-08-24T20:25:15\",\"signer_mobile\":\"09564255931\",\"signer_national_code\":\"ikhwaykcmy\",\"template_id\":16,\"is_private\":true,\"page\":22,\"per_page\":7,\"sort\":\"created_at\"}" }, "description": "Returns paginated contracts visible to caller. Org root sees own + descendants'\nnon-private contracts; non-root sees own + contracts where they're a signer.\n\nScope: `contracts:read`.\n\n**PII filter scope requirement:** filtering by `signer_mobile` or\n`signer_national_code` requires the additional `signers:read_pii` ability\non your token. Without it, those query parameters return\n**403 `scope_missing`**. This prevents a low-privilege `contracts:read`\ntoken from using the index as a confirmation oracle to check whether a\ngiven mobile\/national-code signs any contract on the owner's tree.\n\nThe `*` wildcard scope also passes the check." }, "response": [ { "header": [ { "key": "x-request-id", "value": "01M0TB56ECVSX0CKVWKG3R4TNJ" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/problem+json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 401, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/token_invalid\",\"status\":401,\"code\":\"token_invalid\",\"title_fa\":\"\\u062a\\u0648\\u06a9\\u0646 \\u0646\\u0627\\u0645\\u0639\\u062a\\u0628\\u0631 \\u0627\\u0633\\u062a\",\"title_en\":\"Invalid token\",\"request_id\":\"01M0TB56ECVSX0CKVWKG3R4TNJ\"}", "name": "" }, { "header": [], "code": 403, "body": "{\n \"type\": \"https:\/\/docs.elemza.com\/errors\/scope_missing\",\n \"status\": 403,\n \"code\": \"scope_missing\",\n \"title_fa\": \"\u0627\u06cc\u0646 \u0641\u06cc\u0644\u062a\u0631 \u0646\u06cc\u0627\u0632 \u0628\u0647 \u0645\u062c\u0648\u0632 signers:read_pii \u062f\u0627\u0631\u062f\",\n \"title_en\": \"This filter requires the signers:read_pii scope\",\n \"request_id\": \"01KRH8JRC4Y855P10CYC1C0AYS\"\n}", "name": "PII filter without scope" } ] }, { "name": "Get contract", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/contracts\/:code", "query": [], "raw": "{{baseUrl}}\/api\/v1\/contracts\/:code", "variable": [ { "id": "code", "key": "code", "value": "ABC1234567XYZ890", "description": "16-char public code (A-Z, 0-9)." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns full contract shape with embedded signers, per-page geometry,\nand template positions snapshot.\n\nScope: `contracts:read`." }, "response": [ { "header": [ { "key": "x-request-id", "value": "01M0TB56EQYEJPZ984WW270GM5" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/problem+json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 401, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/token_invalid\",\"status\":401,\"code\":\"token_invalid\",\"title_fa\":\"\\u062a\\u0648\\u06a9\\u0646 \\u0646\\u0627\\u0645\\u0639\\u062a\\u0628\\u0631 \\u0627\\u0633\\u062a\",\"title_en\":\"Invalid token\",\"request_id\":\"01M0TB56EQYEJPZ984WW270GM5\"}", "name": "" } ] }, { "name": "Download signed PDF", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/contracts\/:code\/pdf", "query": [ { "key": "format", "value": "url", "description": "redirect|url|stream. Default redirect.", "disabled": false }, { "key": "ttl", "value": "16", "description": "Signed URL lifetime in seconds (60..86400). Default 86400. Ignored when `format=stream`.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/contracts\/:code\/pdf?format=url&ttl=16", "variable": [ { "id": "code", "key": "code", "value": "architecto", "description": "16-char public code." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns the final signed PDF in one of three formats (Phase 3):\n\n- `format=redirect` (default) \u2014 `302 Found` to a signed URL (24h TTL).\n The signed URL points at the unauthenticated `\/api\/v1\/contracts\/{code}\/dl`\n route, which validates the signature and streams the file. Use this when\n embedding in `` for partner-facing UIs.\n- `format=url` \u2014 JSON envelope with `url`, `expires_at`, `filename`, `size_bytes`,\n `checksum_sha256`. Use this when the API client wants to hand the URL\n to another system, embed in email, or pre-flight before downloading.\n- `format=stream` \u2014 streams the PDF inline (consumes API egress). Use when\n the caller is a backend service that wants the bytes in one round-trip.\n\nScope: `contracts:read`." }, "response": [ { "header": [ { "key": "x-request-id", "value": "01M0TB56F7FRJNS78ATMT67JVA" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/problem+json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 404, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/not_found\",\"status\":404,\"code\":\"not_found\",\"title_fa\":\"\\u0645\\u0646\\u0628\\u0639 \\u06cc\\u0627\\u0641\\u062a \\u0646\\u0634\\u062f\",\"title_en\":\"Resource not found\",\"request_id\":\"01M0TB56F7FRJNS78ATMT67JVA\"}", "name": "" } ] }, { "name": "Poll processing status", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/contracts\/:code\/processing", "query": [], "raw": "{{baseUrl}}\/api\/v1\/contracts\/:code\/processing", "variable": [ { "id": "code", "key": "code", "value": "architecto", "description": "16-char contract code." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Lightweight (<200 bytes) status of the rasterization + signer-creation job.\nReads `contract:progress:{id}` cache key directly \u2014 no DB hit.\n\n**Step values:** `files`, `signers`, `sms`, `done`, `error`.\n\nReturns `ready=true` when `step=done`. If progress key is gone (TTL expired)\nand contract has signers + pages, falls back to `ready=true` (job finished\nearlier and key was reaped).\n\nScope: `contracts:read`." }, "response": [ { "header": [ { "key": "x-request-id", "value": "01M0TB56FMBZKHZN0ZY16GMJAC" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/problem+json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 404, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/not_found\",\"status\":404,\"code\":\"not_found\",\"title_fa\":\"\\u0645\\u0646\\u0628\\u0639 \\u06cc\\u0627\\u0641\\u062a \\u0646\\u0634\\u062f\",\"title_en\":\"Resource not found\",\"request_id\":\"01M0TB56FMBZKHZN0ZY16GMJAC\"}", "name": "" } ] }, { "name": "Create contract", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/contracts", "query": [], "raw": "{{baseUrl}}\/api\/v1\/contracts" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "multipart\/form-data" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "formdata", "formdata": [ { "key": "title", "value": "\u0642\u0631\u0627\u0631\u062f\u0627\u062f \u0628\u06cc\u0645\u0647 \u0634\u062e\u0635 \u062b\u0627\u0644\u062b", "type": "text", "description": "Contract title (1..120 chars)." }, { "key": "signature_method", "value": "architecto", "type": "text", "description": "electronic|digital. Default electronic. `digital` = PADES\n signature via the Pendar CA cloud-HSM. Requires the PKI feature to be enabled for\n your account (pre-flight via `GET \/me` \u2192 `data.capabilities.pki`), otherwise\n **403 `pki_not_available`**. The method is contract-wide (all signers sign the same\n way) and IMMUTABLE after creation \u2014 to change it, cancel and recreate (ADR-0009)." }, { "key": "all_pages_signature", "value": "", "type": "text", "description": "Default false. When true, every page must carry the signature element." }, { "key": "is_private", "value": "", "type": "text", "description": "Default false. When true, hides contract from org-ancestors." }, { "key": "template_id", "value": "26", "type": "text", "description": "Optional \u2014 must be owned by the caller or shared from the org root;\n anything else is rejected with 422 `template_not_accessible` (never silently dropped).\n List valid ids via `GET \/api\/v1\/templates`." }, { "key": "template_enforcement", "value": "locked", "type": "text", "description": "locked|suggested (legacy aliases: strict|loose).\n Defaults to `locked` when `template_id` is set." }, { "key": "redirect_url", "value": "https:\/\/partner.example\/contracts\/42\/signed", "type": "text", "description": "HTTPS URL to send the signer back to after they finish signing.\n They see our confirmation first, then return automatically. Without it they stay on our\n confirmation page." }, { "key": "signers[0]", "value": "architecto", "type": "text", "description": "" }, { "key": "file", "src": [], "type": "file" } ] }, "description": "Creates a new contract. Two modes:\n\n**One-shot** \u2014 multipart\/form-data with `file` field + metadata. File is\npersisted to staging and `ProcessContractFilesJob` is dispatched. Optional\n`signers[]` are added by the same job after page rasterization completes.\nResponse is **202 Accepted**; poll `_links.processing` until `ready=true`.\n\n**Multi-step** \u2014 JSON without `file`. Creates a `draft` contract row only.\nCaller then issues `POST \/contracts\/{code}\/files` to attach the document.\n\n### Signature placement \u2014 `template_id` + `template_enforcement`\n\nPassing `template_id` snapshots that template's signature slots onto the new\ncontract. `template_enforcement` decides what those slots MEAN to the signer:\n\n- `locked` \u2014 each slot is pinned: the signer cannot drag the signature off it,\n and cannot sign on a page the template never assigned them.\n **This is the default whenever `template_id` is present.**\n- `suggested` \u2014 the signature merely *starts* on the slot; the signer may move\n it anywhere, on any page.\n\n`strict` \/ `loose` are accepted as legacy aliases of `locked` \/ `suggested`\n(the spelling earlier revisions of this page advertised).\n\nIf the template pins slots on more than one page, send `all_pages_signature=true`\nas well \u2014 otherwise one signature on any allowed page completes the contract.\n\nVerify what was applied on the create response (`template_id`,\n`template_enforcement`) or in full via `GET \/contracts\/{code}` \u2192 `template_positions`.\n\nScope: `contracts:write`." }, "response": [ { "header": [], "code": 422, "body": "{\n \"type\": \"https:\/\/docs.elemza.com\/errors\/template_not_accessible\",\n \"status\": 422,\n \"code\": \"template_not_accessible\",\n \"title_fa\": \"\u0642\u0627\u0644\u0628 \u0627\u0646\u062a\u062e\u0627\u0628\u200c\u0634\u062f\u0647 \u0648\u062c\u0648\u062f \u0646\u062f\u0627\u0631\u062f \u06cc\u0627 \u062f\u0631 \u062f\u0633\u062a\u0631\u0633 \u0634\u0645\u0627 \u0646\u06cc\u0633\u062a\",\n \"title_en\": \"The selected template does not exist or is not accessible to you\",\n \"request_id\": \"01KRH8JRC4Y855P10CYC1C0AYS\"\n}", "name": "template_id not reachable by the caller" } ] }, { "name": "Upload contract file(s) (two-step flow)", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/contracts\/:code\/files", "query": [], "raw": "{{baseUrl}}\/api\/v1\/contracts\/:code\/files", "variable": [ { "id": "code", "key": "code", "value": "architecto", "description": "16-char contract code." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "multipart\/form-data" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "formdata", "formdata": [ { "key": "file", "src": [], "type": "file" } ] }, "description": "Attaches a file to an existing **draft** contract that has no pages yet.\nSame async pipeline as `POST \/contracts` one-shot: stages bytes, dispatches\n`ProcessContractFilesJob`, returns 202 with the `processing` link.\n\nScope: `contracts:write`." }, "response": [] }, { "name": "Cancel contract", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/contracts\/:code", "query": [], "raw": "{{baseUrl}}\/api\/v1\/contracts\/:code", "variable": [ { "id": "code", "key": "code", "value": "architecto", "description": "16-char public code." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Cancels a contract in `draft` or `waiting_signature` state. Refunds the\nbilled amount to the original wallet (100% if no signer signed, 50% if any\nShahkar was consumed). Deletes contract files from storage. Waiting signers\nreceive an SMS notifying them the contract was canceled.\n\nScope: `contracts:write`." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": {\n \"code\": \"ABC1234567XYZ890\",\n \"status\": \"canceled\",\n \"canceled_at\": \"2026-05-11T10:00:00.000Z\",\n \"refund\": { \"amount\": 60000, \"currency\": \"IRT\" }\n }\n}", "name": "" } ] } ] }, { "name": "Digital certificates (PKI)", "description": "\nIssuing a certificate is not something an API can do on somebody's behalf: the law wants an OTP\nthat person typed and a live face check they attended. So these endpoints do the part an API\nlegitimately can \u2014 start the enrolment, hand back a link for the person, and let the integrator\nfollow it to the end.", "item": [ { "name": "Certificate status for one of your people", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/certificates", "query": [ { "key": "national_code", "value": "0010350829", "description": "The person's national code.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/certificates?national_code=0010350829" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Answers \"can this person sign digitally yet?\" for somebody you have enrolled.\n\n**Privacy** \u2014 this is not a lookup service for arbitrary national codes. It only answers for\npeople you yourself started an enrolment for; anyone else returns 404, so the endpoint cannot\nbe used to discover whether a given Iranian holds a certificate.\n\nScope required: `certificates:read`." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": {\n \"national_code\": \"0010350829\",\n \"status\": \"active\",\n \"valid_from\": \"2026-07-30T09:12:00.000Z\",\n \"valid_until\": \"2027-07-30T09:12:00.000Z\",\n \"mode\": \"live\"\n }\n}", "name": "Active certificate" }, { "header": [], "code": 200, "body": "{\n \"data\": { \"national_code\": \"0010350829\", \"status\": \"pending_ekyc\", \"valid_from\": null, \"valid_until\": null, \"mode\": \"live\" }\n}", "name": "Enrolment still in progress" } ] }, { "name": "One enrolment request", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/certificates\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/certificates\/:id", "variable": [ { "id": "id", "key": "id", "value": "01jqk8x2m4n6p8r0s2t4v6w8y0", "description": "The `request_id` from the onboarding call." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "The state of a single enrolment you started, by the `request_id` you received.\n\nScope required: `certificates:read`." }, "response": [ { "header": [ { "key": "x-request-id", "value": "01M0TB56P8HCD9VKZECE1SNVS5" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/problem+json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 401, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/token_invalid\",\"status\":401,\"code\":\"token_invalid\",\"title_fa\":\"\\u062a\\u0648\\u06a9\\u0646 \\u0646\\u0627\\u0645\\u0639\\u062a\\u0628\\u0631 \\u0627\\u0633\\u062a\",\"title_en\":\"Invalid token\",\"request_id\":\"01M0TB56P8HCD9VKZECE1SNVS5\"}", "name": "" } ] }, { "name": "Start a certificate enrolment", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/certificates\/onboarding", "query": [], "raw": "{{baseUrl}}\/api\/v1\/certificates\/onboarding" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"national_code\":\"0010350829\",\"mobile\":\"09121234567\",\"first_name\":\"\u0639\u0644\u06cc\",\"last_name\":\"\u0631\u0636\u0627\u06cc\u06cc\",\"pay_by\":\"issuer\",\"redirect_url\":\"https:\\\/\\\/partner.example\\\/done\",\"ttl_minutes\":120}" }, "description": "Creates a short-lived, single-use link for one of your users to obtain a digital certificate.\nSend them to `onboarding_url`; they complete the SMS code, the identity form and the video\ncheck on our pages, and you learn the outcome from `certificate.issued` \/ `certificate.failed`\n(or by polling `GET \/api\/v1\/certificates\/{request_id}`).\n\n**Who pays** \u2014 `pay_by: \"issuer\"` charges YOUR wallet for the one-time issuance fee right now\nand refunds it automatically if no certificate is ever issued. `pay_by: \"subject\"` (default)\nlets the person pay on the page.\n\n**Idempotency** \u2014 while an enrolment for the same national code is still open you get the SAME\nlink back, not a second one. Pendar treats an open enrolment as a single order.\n\nScope required: `certificates:write`." }, "response": [ { "header": [], "code": 201, "body": "{\n \"data\": {\n \"request_id\": \"01jqk8x2m4n6p8r0s2t4v6w8y0\",\n \"onboarding_url\": \"https:\/\/elemza.com\/pki\/onboarding\/01jqk8x2m4n6p8r0s2t4v6w8y0?expires=...&signature=...\",\n \"expires_at\": \"2026-07-30T12:00:00.000Z\",\n \"status\": \"pending\",\n \"pay_by\": \"issuer\",\n \"mode\": \"live\"\n }\n}", "name": "Link created" } ] } ] }, { "name": "Form submissions \u2014 fill a form through the API (ADR-0029)", "description": "\nSubmit-once semantics: no draft\/resume, no edit-after-submit (FB SCOPE-CONTRACT rows 6\/7).\nOwnership: every endpoint requires the form to BELONG to the token owner (v2 schema only) \u2014\nthe integrator drives fills of their OWN forms; end users never hold tokens.", "item": [ { "name": "Public signed-URL download twin (no Bearer \u2014 the URL signature is the auth proof,\nminted by downloadPdf() after the bearer was verified). Mirrors contracts \/dl.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/form-submissions\/:code\/dl", "query": [], "raw": "{{baseUrl}}\/api\/v1\/form-submissions\/:code\/dl", "variable": [ { "id": "code", "key": "code", "value": "architecto", "description": "16-char submission code." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [ { "header": [ { "key": "x-request-id", "value": "01M0TB56B2TW4QKAHSPA045ACY" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/problem+json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 404, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/not_found\",\"status\":404,\"code\":\"not_found\",\"title_fa\":\"\\u0645\\u0646\\u0628\\u0639 \\u06cc\\u0627\\u0641\\u062a \\u0646\\u0634\\u062f\",\"title_en\":\"Resource not found\",\"request_id\":\"01M0TB56B2TW4QKAHSPA045ACY\"}", "name": "" } ] }, { "name": "Public signed-URL twin for a single field file (no Bearer \u2014 the signature is the auth\nproof, minted by downloadFieldFile() only after the bearer was verified).", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/form-submissions\/:code\/files\/:field\/dl", "query": [], "raw": "{{baseUrl}}\/api\/v1\/form-submissions\/:code\/files\/:field\/dl", "variable": [ { "id": "code", "key": "code", "value": "architecto", "description": "16-char submission code." }, { "id": "field", "key": "field", "value": "architecto", "description": "The field's technical `name`." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [ { "header": [ { "key": "x-request-id", "value": "01M0TB56BDPVRXEKC0F5PRAYFA" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/problem+json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 404, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/not_found\",\"status\":404,\"code\":\"not_found\",\"title_fa\":\"\\u0645\\u0646\\u0628\\u0639 \\u06cc\\u0627\\u0641\\u062a \\u0646\\u0634\\u062f\",\"title_en\":\"Resource not found\",\"request_id\":\"01M0TB56BDPVRXEKC0F5PRAYFA\"}", "name": "" } ] }, { "name": "List submissions", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/forms\/:slug\/submissions", "query": [ { "key": "status", "value": "architecto", "description": "draft|pending_payment|submitted|processing|completed|signed.", "disabled": false }, { "key": "submitted_after", "value": "architecto", "description": "ISO 8601.", "disabled": false }, { "key": "submitted_before", "value": "architecto", "description": "ISO 8601.", "disabled": false }, { "key": "has_contract", "value": "", "description": "Only submissions that bridged to a contract.", "disabled": true }, { "key": "per_page", "value": "16", "description": "Max 100, default 20.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/forms\/:slug\/submissions?status=architecto&submitted_after=architecto&submitted_before=architecto&has_contract=&per_page=16", "variable": [ { "id": "slug", "key": "slug", "value": "architecto", "description": "The form's slug." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"status\":\"submitted\",\"submitted_after\":\"2026-08-24T20:25:15\",\"submitted_before\":\"2026-08-24T20:25:15\",\"has_contract\":true,\"page\":16,\"per_page\":22}" }, "description": "Paginated, newest first. Scope: `forms:read`." }, "response": [ { "header": [ { "key": "x-request-id", "value": "01M0TB56K1MBR6KBMRYXPDZBE3" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/problem+json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 401, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/token_invalid\",\"status\":401,\"code\":\"token_invalid\",\"title_fa\":\"\\u062a\\u0648\\u06a9\\u0646 \\u0646\\u0627\\u0645\\u0639\\u062a\\u0628\\u0631 \\u0627\\u0633\\u062a\",\"title_en\":\"Invalid token\",\"request_id\":\"01M0TB56K1MBR6KBMRYXPDZBE3\"}", "name": "" } ] }, { "name": "Get one submission", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/forms\/:slug\/submissions\/:code", "query": [], "raw": "{{baseUrl}}\/api\/v1\/forms\/:slug\/submissions\/:code", "variable": [ { "id": "slug", "key": "slug", "value": "architecto", "description": "The form's slug." }, { "id": "code", "key": "code", "value": "architecto", "description": "16-char submission code." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Scope: `forms:read`." }, "response": [ { "header": [ { "key": "x-request-id", "value": "01M0TB56KHGP7765916R7C299G" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/problem+json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 404, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/not_found\",\"status\":404,\"code\":\"not_found\",\"title_fa\":\"\\u0645\\u0646\\u0628\\u0639 \\u06cc\\u0627\\u0641\\u062a \\u0646\\u0634\\u062f\",\"title_en\":\"Resource not found\",\"request_id\":\"01M0TB56KHGP7765916R7C299G\"}", "name": "" } ] }, { "name": "Download submission PDF", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/forms\/:slug\/submissions\/:code\/pdf", "query": [ { "key": "format", "value": "architecto", "description": "redirect|url|stream. Default redirect.", "disabled": false }, { "key": "ttl", "value": "16", "description": "Signed URL lifetime seconds (60..86400). Default 86400.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/forms\/:slug\/submissions\/:code\/pdf?format=architecto&ttl=16", "variable": [ { "id": "slug", "key": "slug", "value": "architecto", "description": "The form's slug." }, { "id": "code", "key": "code", "value": "architecto", "description": "16-char submission code." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Image-overlay forms render a final PDF per submission (queued at submit). Same\nsigned-URL family as the contracts PDF endpoint:\n\n- `format=redirect` (default) \u2014 302 to a signed URL (anon-safe, forwardable)\n- `format=url` \u2014 JSON envelope with url\/expiry\/checksum\n- `format=stream` \u2014 bytes in this response\n\nScope: `forms:read`." }, "response": [ { "header": [ { "key": "x-request-id", "value": "01M0TB56M1X2AGEBJVV6DPVMAM" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/problem+json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 404, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/not_found\",\"status\":404,\"code\":\"not_found\",\"title_fa\":\"\\u0645\\u0646\\u0628\\u0639 \\u06cc\\u0627\\u0641\\u062a \\u0646\\u0634\\u062f\",\"title_en\":\"Resource not found\",\"request_id\":\"01M0TB56M1X2AGEBJVV6DPVMAM\"}", "name": "" } ] }, { "name": "Download one uploaded field file", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/forms\/:slug\/submissions\/:code\/files\/:field", "query": [ { "key": "format", "value": "architecto", "description": "redirect|url|stream. Default redirect.", "disabled": false }, { "key": "ttl", "value": "16", "description": "Signed URL lifetime seconds (60..86400). Default 86400.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/forms\/:slug\/submissions\/:code\/files\/:field?format=architecto&ttl=16", "variable": [ { "id": "slug", "key": "slug", "value": "architecto", "description": "The form's slug." }, { "id": "code", "key": "code", "value": "architecto", "description": "16-char submission code." }, { "id": "field", "key": "field", "value": "architecto", "description": "The field's technical `name`." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Serves whatever the submission actually holds for `{field}`: a stored `forms\/\u2026` path,\nOR an inline `data:\u2026;base64,\u2026` URI. Both shapes are real and both are served \u2014 the\ndata-URI is what a drawn signature is, and what API callers necessarily wrote before\nan uploads endpoint existed, so refusing it would orphan real historical data.\n\nThe field's type is resolved from the submission's OWN schema snapshot, not the live\nform: editing a form must never change what an already-recorded submission is\nunderstood to contain.\n\nSame three formats as the submission PDF endpoint.\n\nScope: `forms:read`." }, "response": [ { "header": [ { "key": "x-request-id", "value": "01M0TB56ME91KZHB7W3SNX629B" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/problem+json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 404, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/not_found\",\"status\":404,\"code\":\"not_found\",\"title_fa\":\"\\u0645\\u0646\\u0628\\u0639 \\u06cc\\u0627\\u0641\\u062a \\u0646\\u0634\\u062f\",\"title_en\":\"Resource not found\",\"request_id\":\"01M0TB56ME91KZHB7W3SNX629B\"}", "name": "" } ] }, { "name": "Submit a form (fill via API)", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/forms\/:slug\/submissions", "query": [], "raw": "{{baseUrl}}\/api\/v1\/forms\/:slug\/submissions", "variable": [ { "id": "slug", "key": "slug", "value": "architecto", "description": "The form's slug." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"data\":{\"first_name\":\"\u0639\u0644\u06cc\"}}" }, "description": "Runs the EXACT same pipeline as the public web renderer: schema validation,\nvisibility filtering, formula computation, trust scoring, the signature bridge\n(`requires_signature` forms auto-create a contract \u2014 response embeds it with per-signer\n`signing_url`s), image-overlay PDF rendering (queued), and owner notifications.\n\nScope: `forms:write` + `Idempotency-Key` supported.\n\nFields hidden by visibility conditions are stripped server-side. `query_shahkar` \/\n`query_legal_entity` field values must come from `POST \/forms\/{slug}\/verify-field`\n(same request IP) or their matched=true claim is stripped as a forgery.\n\n`file` \/ `image` fields take EITHER of two shapes, both real:\n - the `path` returned by `POST \/forms\/{slug}\/uploads` \u2014 preferred, stores the bytes on\n disk exactly as the web fill flow does, and is readable back via the `\/files\/{field}`\n endpoint;\n - an inline `data:;base64,\u2026` URI, which is also what a drawn `signature` is.\nBoth are magic-byte validated and size-capped server-side. (This docblock claimed\nuploads were \"not supported in v1 (mirrors the web fill flow)\" until 2026-08-14 \u2014 the\nsecond half had been untrue since 2026-06-22, when the web renderer got real uploads,\nand the first half was never enforced by any code: base64 always passed.)" }, "response": [] }, { "name": "Upload a file for a `file` \/ `image` field", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/forms\/:slug\/uploads", "query": [], "raw": "{{baseUrl}}\/api\/v1\/forms\/:slug\/uploads", "variable": [ { "id": "slug", "key": "slug", "value": "architecto", "description": "The form's slug." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "multipart\/form-data" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "formdata", "formdata": [ { "key": "field", "value": "national_card", "type": "text", "description": "The target field's technical `name` (see `\/schema`)." }, { "key": "file", "src": [], "type": "file" } ] }, "description": "Multipart, ONE file per call. The returned `path` is what you then put in\n`data.{field}` on `POST \/forms\/{slug}\/submissions`. The bytes land in the form's own\nfolder byte-identically to what the web fill flow produces, so the submissions table,\nthe answer sheet and the image-overlay PDF all render it the same way \u2014 an API fill\nand a browser fill become indistinguishable downstream, which is the whole point.\n\nSize and type come from the FIELD's own config (`max_size_kb` \/ `allowed_mimes` as the\ndesigner set them), clamped to the server ceiling, and the MIME is read from the\nfile's magic bytes \u2014 never from its name or extension.\n\n`signature` is deliberately not accepted here: it is drawn, and the canvas yields a\n`data:image\/png;base64,\u2026` value that goes straight into `data`.\n\nScope: `forms:write` + `Idempotency-Key` supported." }, "response": [] } ] }, { "name": "Forms \u2014 read-only access to v2 forms owned by the authenticated user.", "description": "\nPhase 5 MVP: list + show + stats. Submissions endpoint will land in Phase 5b\nwith proper pagination + transformer.", "item": [ { "name": "List forms (v2 only \u2014 schema_version='2.0')", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/forms", "query": [ { "key": "page", "value": "16", "description": "Page number. Default 1.", "disabled": false }, { "key": "per_page", "value": "16", "description": "Items per page. Max 100. Default 50.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/forms?page=16&per_page=16" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Paginated list of v2-schema forms owned by the calling user, most recent\nfirst. Form Builder v1 records are excluded \u2014 use the dashboard for those.\nReturns the standard `data` + `meta` + `links` envelope, consistent with the\nother list endpoints (API-G1, audit 2026-06 \u2014 previously a silent limit(100)).\n\nScope required: `forms:read`." }, "response": [ { "header": [ { "key": "x-request-id", "value": "01M0TB56HSWV85A9A6QE19BEB7" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/problem+json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 401, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/token_invalid\",\"status\":401,\"code\":\"token_invalid\",\"title_fa\":\"\\u062a\\u0648\\u06a9\\u0646 \\u0646\\u0627\\u0645\\u0639\\u062a\\u0628\\u0631 \\u0627\\u0633\\u062a\",\"title_en\":\"Invalid token\",\"request_id\":\"01M0TB56HSWV85A9A6QE19BEB7\"}", "name": "" } ] }, { "name": "Show one form (metadata only \u2014 schema available via dedicated \/schema endpoint in future)", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/forms\/:slug", "query": [], "raw": "{{baseUrl}}\/api\/v1\/forms\/:slug", "variable": [ { "id": "slug", "key": "slug", "value": "frm-e7465df28dd45785", "description": "The form's public slug." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Scope required: `forms:read`." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": {\n \"id\": 142,\n \"slug\": \"frm-e7465df28dd45785\",\n \"title\": \"\u0642\u0631\u0627\u0631\u062f\u0627\u062f \u0647\u0645\u06a9\u0627\u0631\u06cc\",\n \"status\": \"published\",\n \"renderer_type\": \"online\",\n \"submission_count\": 23,\n \"views_count\": 187,\n \"created_at\": \"2026-05-10T14:32:00.000Z\"\n }\n}", "name": "" }, { "header": [], "code": 404, "body": "{\n \"type\": \"https:\/\/docs.elemza.com\/errors\/form_not_found\",\n \"status\": 404,\n \"code\": \"form_not_found\",\n \"title_fa\": \"\u0641\u0631\u0645 \u06cc\u0627\u0641\u062a \u0646\u0634\u062f \u06cc\u0627 \u0645\u062a\u0639\u0644\u0642 \u0628\u0647 \u0634\u0645\u0627 \u0646\u06cc\u0633\u062a\",\n \"title_en\": \"Form not found or not owned by the caller\",\n \"request_id\": \"01KRH8JRC4Y855P10CYC1C0AYS\"\n}", "name": "Not found or not owned" } ] }, { "name": "Form analytics (views\/starts\/submissions\/conversion rates).", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/forms\/:slug\/stats", "query": [], "raw": "{{baseUrl}}\/api\/v1\/forms\/:slug\/stats", "variable": [ { "id": "slug", "key": "slug", "value": "frm-e7465df28dd45785", "description": "The form's public slug." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Aggregated funnel counters for one form: lifetime totals plus 7-day and 30-day windows, so\nyou can chart trends without additional queries.\n\nWARNING: Two engines count submissions here, and the response names both.\n\n- `submissions` \u2014 the lifetime counter, incremented once per accepted submission. It never\ndecreases, so a deleted submission stays counted, and it is written in exactly one place, so a\nrow created by any other path is invisible to it. **This is the v1 meaning and it does not\nchange without a version bump.** `submissions_recorded` is the same integer under a name that\nsays so.\n- `submissions_stored` \u2014 non-draft rows held right now. This is the number the owner sees in\ntheir panel, and it can differ from `submissions` in either direction.\n\n`abandons`, `completion_rate` and `abandon_rate` all derive from `submissions`, so the funnel\nadds up. `completion_rate_stored` is `null` when stored rows exceed recorded starts: the two\ncounters disagree, and a ratio across them would be drift rather than a measurement.\n\nAdded 2026-08-20 \u2014 `submissions_recorded`, `submissions_stored`, `completion_rate_stored`.\nPurely additive; no existing field changed meaning or value.\n\nScope required: `forms:read`." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": {\n \"views\": 187,\n \"starts\": 41,\n \"abandons\": 18,\n \"submissions\": 23,\n \"submissions_recorded\": 23,\n \"submissions_stored\": 25,\n \"start_rate\": 21.9,\n \"completion_rate\": 56.1,\n \"completion_rate_stored\": 61.0,\n \"abandon_rate\": 43.9,\n \"last_submission_at\": \"2026-08-19T11:02:44+00:00\",\n \"submissions_last_7d\": 4,\n \"submissions_last_30d\": 21\n }\n}", "name": "" }, { "header": [], "code": 404, "body": "{\n \"type\": \"https:\/\/docs.elemza.com\/errors\/form_not_found\",\n \"status\": 404, \"code\": \"form_not_found\",\n \"title_fa\": \"\u0641\u0631\u0645 \u06cc\u0627\u0641\u062a \u0646\u0634\u062f \u06cc\u0627 \u0645\u062a\u0639\u0644\u0642 \u0628\u0647 \u0634\u0645\u0627 \u0646\u06cc\u0633\u062a\",\n \"title_en\": \"Form not found or not owned by the caller\",\n \"request_id\": \"01KRH8JRC4Y855P10CYC1C0AYS\"\n}", "name": "Not found or not owned" } ] }, { "name": "Form schema (fillable-field catalog)", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/forms\/:slug\/schema", "query": [], "raw": "{{baseUrl}}\/api\/v1\/forms\/:slug\/schema", "variable": [ { "id": "slug", "key": "slug", "value": "architecto", "description": "The form's public slug." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Everything an integrator needs to build their own fill UI and construct a valid\n`POST \/forms\/{slug}\/submissions` payload: field names, types, labels, required flags,\noptions, pages, visibility conditions, and \u2014 per field \u2014 the SHAPE its value must take\n(`value_format`).\n\n`supported` used to report `false` for file\/image \"because the web fill flow does not\nsupport them either\". Both halves were wrong: the web renderer has had real uploads\nsince 2026-06-22, and nothing ever rejected an inline base64 value on the API side. It\nnow reports true for every fillable field, and `value_format` carries the real answer:\n\n - `upload_path_or_data_uri` \u2014 file\/image: either the `path` from\n `POST \/forms\/{slug}\/uploads`, or an inline `data:;base64,\u2026`\n - `data_uri` \u2014 signature: what the canvas produces\n - `verify_field_result` \u2014 query fields: from `POST \/forms\/{slug}\/verify-field`\n - `scalar` \u2014 everything else\n\n**`id` is the key to keep.** It is generated once and never changes \u2014 not when the\nfield is renamed, relabelled, reordered or moved. Key your local copy of a form by\n`id`, never by `name`: a client keyed by name cannot tell a RENAME apart from \"one\nfield deleted, one added\", and those call for opposite actions. `repeat.config.ref`\nand the `fill_flow` sections both reference fields by this same id.\n\n`pages` describes what each field's `page` points at, and is never empty.\n\n`fill_flow` is present only for `image_overlay` forms (null otherwise) and says\nwhich of the two presentations the owner chose: `document` draws fields at absolute\ncoordinates on a page bitmap, while `guided` turns them into ordered question cards\n\u2014 with `doc` saying whether the document is shown alongside. Only `guided` is\nreasonable to reproduce outside our own renderer.\n\nScope required: `forms:read`." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": {\n \"form\": { \"slug\": \"frm-e7465df28dd45785\", \"title\": \"\u0642\u0631\u0627\u0631\u062f\u0627\u062f \u0647\u0645\u06a9\u0627\u0631\u06cc\", \"version\": 12 },\n \"pages\": [\n { \"id\": \"page_a1b2c3d4e5f60718\", \"title\": \"\u0645\u0634\u062e\u0635\u0627\u062a \u0641\u0631\u062f\u06cc\", \"description\": null,\n \"sort_order\": 0, \"visibility_condition\": null }\n ],\n \"fill_flow\": null,\n \"fields\": [\n {\n \"id\": \"fld_9a3f1c72e4b58d06\",\n \"name\": \"full_name\",\n \"type\": \"text\",\n \"label\": \"\u0646\u0627\u0645 \u0648 \u0646\u0627\u0645 \u062e\u0627\u0646\u0648\u0627\u062f\u06af\u06cc\",\n \"required\": true,\n \"is_input\": true,\n \"supported\": true,\n \"value_format\": \"scalar\",\n \"page\": \"page_a1b2c3d4e5f60718\",\n \"help_text\": null,\n \"placeholder\": null,\n \"default_value\": null,\n \"options\": null,\n \"config\": {},\n \"has_visibility_condition\": false,\n \"visibility_condition\": null,\n \"is_formula\": false,\n \"formula\": null,\n \"validations\": [],\n \"sort_order\": 0\n }\n ]\n }\n}", "name": "An online form with one text field" } ] }, { "name": "Verify a query field (Shahkar \/ legal entity)", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/forms\/:slug\/verify-field", "query": [], "raw": "{{baseUrl}}\/api\/v1\/forms\/:slug\/verify-field", "variable": [ { "id": "slug", "key": "slug", "value": "architecto", "description": "The form's public slug." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"field\":\"architecto\",\"values\":{\"mobile\":\"09121234567\",\"national_code\":\"0010350829\"}}" }, "description": "Runs the SAME server-side verification the web renderer's \u00ab\u0627\u0633\u062a\u0639\u0644\u0627\u0645\u00bb buttons run, and\nwrites the same server-side binding that `POST \/forms\/{slug}\/submissions` checks \u2014 echo\nthe returned `value` back inside `data.{field}` when you submit, FROM THE SAME IP.\n\nThe form OWNER's daily Shahkar quota pays for the lookup (identical to web). Sandbox\ntokens short-circuit to `matched=true` without any provider call.\n\nScope required: `forms:write`." }, "response": [] } ] }, { "name": "Meta \u2014 health, identity, quota, cost", "description": "", "item": [ { "name": "Health check", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/health", "query": [], "raw": "{{baseUrl}}\/api\/v1\/health" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Lightweight liveness probe. **No authentication required.**\nAlways returns 200 if the API process is up.", "auth": { "type": "noauth" } }, "response": [ { "header": [], "code": 200, "body": "{\n \"status\": \"ok\",\n \"time\": \"2026-05-11T11:53:29.399Z\",\n \"version\": \"v1.0.0\"\n}", "name": "" } ] }, { "name": "Caller identity", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/me", "query": [], "raw": "{{baseUrl}}\/api\/v1\/me" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns information about the authenticated token, its owner user, and\nthe billing context (wallet balance, org root). Any valid token can call this \u2014\nno specific scope required.\n\nUse the `token.mode` field to confirm whether your token is in **live** mode\n(charges your wallet, real KYC\/SMS) or **test** sandbox mode (zero wallet\nimpact, mocked side effects). `wallet_balance` is always in tomans (IRR\/10)." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": {\n \"token\": {\n \"id\": \"42\",\n \"name\": \"production-server-2026\",\n \"mode\": \"live\",\n \"scopes\": [\"contracts:read\", \"contracts:write\", \"webhooks:manage\"],\n \"ip_whitelist\": [\"203.0.113.5\/32\"],\n \"expires_at\": \"2027-01-01T00:00:00.000Z\",\n \"last_used_at\": \"2026-05-13T18:00:42.000Z\"\n },\n \"user\": {\n \"id\": 1234,\n \"name\": \"\u0622\u0631\u0634 \u0628\u0646\u0627\u0626\u06cc\u0627\u0646 \u0686\u0645\u0644\u0647\",\n \"type\": \"personal\",\n \"is_org_root\": false,\n \"org_root_id\": null\n },\n \"billing_actor_user_id\": 1234,\n \"wallet_balance\": 849310\n }\n}", "name": "Live token" }, { "header": [], "code": 200, "body": "{\n \"data\": {\n \"token\": {\n \"id\": \"13\",\n \"name\": \"ci-tests-sandbox\",\n \"mode\": \"test\",\n \"scopes\": [\"*\"],\n \"ip_whitelist\": [],\n \"expires_at\": null,\n \"last_used_at\": \"2026-05-13T17:52:23.000Z\"\n },\n \"user\": {\n \"id\": 1234,\n \"name\": \"\u0622\u0631\u0634 \u0628\u0646\u0627\u0626\u06cc\u0627\u0646 \u0686\u0645\u0644\u0647\",\n \"type\": \"personal\",\n \"is_org_root\": false,\n \"org_root_id\": null\n },\n \"billing_actor_user_id\": 1234,\n \"wallet_balance\": 849310\n }\n}", "name": "Sandbox\/test token" } ] }, { "name": "Current quota", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/quota", "query": [], "raw": "{{baseUrl}}\/api\/v1\/quota" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns the caller's current-month signature quota usage + remaining,\npackage tier, and today's Shahkar verification credits.\n\n**Quota semantics:**\n- `free_quota` is the per-period allowance from the user's active package\n (Free=3 lifetime, Bronze=100\/mo, Silver=300\/mo, Gold=600\/mo \u2014 verify against\n live `\/admin\/packages`, these are the 2026-06 tariff). Returns 0 if the package\n is expired or unset.\n- `used`\/`remaining` may be FRACTIONAL: additional signers on one contract count\n as half a unit each (a 2-signer contract consumes 1.5). Whole values serialize\n as integers; a half consumes serializes as e.g. `1.5`.\n- `used` is total signature-units recorded since `package_started_at` (so\n pre-purchase usage doesn't deplete a freshly-bought plan). Free tier counts\n lifetime (no monthly reset).\n- `remaining = free_quota - used` for limited plans. **null** means\n genuinely unlimited (`signature_limit` IS NULL).\n- When `remaining` reaches 0, signatures still work \u2014 billed as overage from the\n wallet at `base \u00d7 (1 \u2212 overage_discount)`; the OVERAGE discount is\n Free=0%, Bronze=5%, Silver=15%, Gold=25% (separate from, and smaller than, the\n 10\/20\/30% in-package discount encoded in the package price).\n\n**Shahkar credits** are separate from signature quota. Daily allowance\nby package (Free=3, Bronze=5, Silver=10, Gold=20). Once exhausted, the\nclient must purchase batch top-ups before further Shahkar verifications.\n\nScope required: `contracts:read`." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": {\n \"service\": \"electronic_signature\",\n \"period_start\": \"2026-05-01T00:00:00.000Z\",\n \"period_end\": \"2026-05-31T23:59:59.999Z\",\n \"package\": { \"slug\": \"bronze\", \"name\": \"\u0628\u0631\u0646\u0632\u06cc\" },\n \"free_quota\": 30,\n \"used\": 17,\n \"remaining\": 13,\n \"shahkar\": {\n \"free_limit\": 5,\n \"used_today\": 2,\n \"free_remaining\": 3,\n \"extra_credits\": 0,\n \"extra_remaining\": 0,\n \"allowed\": true\n }\n }\n}", "name": "Bronze user mid-month" }, { "header": [], "code": 200, "body": "{\n \"data\": {\n \"service\": \"electronic_signature\",\n \"period_start\": \"2026-05-01T00:00:00.000Z\",\n \"period_end\": \"2026-05-31T23:59:59.999Z\",\n \"package\": { \"slug\": \"gold\", \"name\": \"\u0637\u0644\u0627\u06cc\u06cc\" },\n \"free_quota\": 0,\n \"used\": 412,\n \"remaining\": null,\n \"shahkar\": {\n \"free_limit\": 20, \"used_today\": 4,\n \"free_remaining\": 16, \"extra_credits\": 0,\n \"extra_remaining\": 0, \"allowed\": true\n }\n }\n}", "name": "Gold (unlimited)" }, { "header": [], "code": 200, "body": "{\n \"data\": {\n \"service\": \"electronic_signature\",\n \"period_start\": \"2026-05-01T00:00:00.000Z\",\n \"period_end\": \"2026-05-31T23:59:59.999Z\",\n \"package\": null,\n \"free_quota\": 0,\n \"used\": 0,\n \"remaining\": 0,\n \"shahkar\": {\n \"free_limit\": 0, \"used_today\": 0,\n \"free_remaining\": 0, \"extra_credits\": 0,\n \"extra_remaining\": 0, \"allowed\": false\n }\n }\n}", "name": "No active package (pay-per-use)" } ] }, { "name": "Cost estimate", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/cost-estimate", "query": [ { "key": "signers", "value": "3", "description": "Number of signers (1-20).", "disabled": false }, { "key": "discount_code", "value": "WELCOME10", "description": "Optional discount code.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/cost-estimate?signers=3&discount_code=WELCOME10" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns full cost breakdown for a hypothetical contract without committing.\nUse before calling `POST \/contracts` so users can see \"X toman\" upfront.\n\nScope required: `contracts:read`." }, "response": [ { "header": [ { "key": "x-request-id", "value": "01M0TB56CK30WTDC7J030ZXPFV" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/problem+json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 401, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/token_invalid\",\"status\":401,\"code\":\"token_invalid\",\"title_fa\":\"\\u062a\\u0648\\u06a9\\u0646 \\u0646\\u0627\\u0645\\u0639\\u062a\\u0628\\u0631 \\u0627\\u0633\\u062a\",\"title_en\":\"Invalid token\",\"request_id\":\"01M0TB56CK30WTDC7J030ZXPFV\"}", "name": "" } ] } ] }, { "name": "Signers", "description": "\nSigner endpoints for a contract.\n\nPhase 1 = read-only (index + show). Resend + delete = Phase 2 (mutations).\n\nSpec: docs\/api-master-plan\/02-endpoint-surface.md (Signer endpoints).", "item": [ { "name": "List signers", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/contracts\/:code\/signers", "query": [], "raw": "{{baseUrl}}\/api\/v1\/contracts\/:code\/signers", "variable": [ { "id": "code", "key": "code", "value": "architecto", "description": "16-char contract code." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Lists all signers on a contract. PII (mobile, national_code) is masked\nunless the caller's token has `signers:read_pii` scope.\n\nScope: `contracts:read`." }, "response": [ { "header": [ { "key": "x-request-id", "value": "01M0TB56GKFB93AA71XDX16ZQ5" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/problem+json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 404, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/not_found\",\"status\":404,\"code\":\"not_found\",\"title_fa\":\"\\u0645\\u0646\\u0628\\u0639 \\u06cc\\u0627\\u0641\\u062a \\u0646\\u0634\\u062f\",\"title_en\":\"Resource not found\",\"request_id\":\"01M0TB56GKFB93AA71XDX16ZQ5\"}", "name": "" } ] }, { "name": "Get signer", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/contracts\/:code\/signers\/:slug", "query": [], "raw": "{{baseUrl}}\/api\/v1\/contracts\/:code\/signers\/:slug", "variable": [ { "id": "code", "key": "code", "value": "architecto", "description": "16-char contract code." }, { "id": "slug", "key": "slug", "value": "DEF456GHJ789KLM", "description": "Per-signer slug." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Detailed view of a single signer. PII masked unless token has `signers:read_pii`.\n\nScope: `contracts:read`." }, "response": [ { "header": [ { "key": "x-request-id", "value": "01M0TB56GWSQ659J9SK71B68G7" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/problem+json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 404, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/not_found\",\"status\":404,\"code\":\"not_found\",\"title_fa\":\"\\u0645\\u0646\\u0628\\u0639 \\u06cc\\u0627\\u0641\\u062a \\u0646\\u0634\\u062f\",\"title_en\":\"Resource not found\",\"request_id\":\"01M0TB56GWSQ659J9SK71B68G7\"}", "name": "" } ] }, { "name": "Add signers", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/contracts\/:code\/signers", "query": [], "raw": "{{baseUrl}}\/api\/v1\/contracts\/:code\/signers", "variable": [ { "id": "code", "key": "code", "value": "architecto", "description": "16-char contract code." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"signers\":[\"architecto\"]}" }, "description": "Adds one or more signers to a draft contract. Runs **mandatory** Shahkar\npre-validation (mobile \u2194 national_code match) per signer in production.\nOn success, contract transitions to `waiting_signature` and SMS dispatch\njobs are queued for first-order signers.\n\nScope: `signers:write`." }, "response": [] }, { "name": "Resend signing link SMS", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/contracts\/:code\/signers\/:slug\/resend", "query": [], "raw": "{{baseUrl}}\/api\/v1\/contracts\/:code\/signers\/:slug\/resend", "variable": [ { "id": "code", "key": "code", "value": "architecto", "description": "16-char contract code." }, { "id": "slug", "key": "slug", "value": "architecto", "description": "Per-signer slug." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Re-sends the signing-link SMS to a waiting signer. Rate-limited to 3 per\n5 minutes per signer (returns 429 `rate_limit_exceeded`).\n\nScope: `signers:write`." }, "response": [] }, { "name": "Remove signer", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/contracts\/:code\/signers\/:slug", "query": [], "raw": "{{baseUrl}}\/api\/v1\/contracts\/:code\/signers\/:slug", "variable": [ { "id": "code", "key": "code", "value": "architecto", "description": "16-char contract code." }, { "id": "slug", "key": "slug", "value": "architecto", "description": "Per-signer slug." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Removes a signer from a contract. Only allowed when:\n- Signer status is `waiting` (not yet signed)\n- Contract status is `draft` or `waiting_signature`\n\nScope: `signers:write`." }, "response": [ { "header": [], "code": 204, "body": "{}", "name": "" } ] } ] }, { "name": "Templates", "description": "\nTemplate endpoints \u2014 read-only in v1.0. CRUD lands in v1.x.\n\nSpec: docs\/api-master-plan\/02-endpoint-surface.md (Template endpoints).", "item": [ { "name": "List templates", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/templates", "query": [ { "key": "view_scope", "value": "architecto", "description": "self | shared_from_parent | all_org. Default self.", "disabled": false }, { "key": "active", "value": "", "description": "Filter by active status.", "disabled": true }, { "key": "page", "value": "16", "description": "", "disabled": false }, { "key": "per_page", "value": "16", "description": "Max 100. Default 20.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/templates?view_scope=architecto&active=&page=16&per_page=16" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Lists contract templates the caller can use.\n\n`view_scope` options:\n- `self` \u2014 own templates only (default)\n- `shared_from_parent` \u2014 own + templates shared by org parent\/root\n- `all_org` \u2014 entire org tree (org root only)\n\nScope: `templates:read`." }, "response": [ { "header": [ { "key": "x-request-id", "value": "01M0TB56Q4V9KMNG657H9VRAJ5" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/problem+json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 401, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/token_invalid\",\"status\":401,\"code\":\"token_invalid\",\"title_fa\":\"\\u062a\\u0648\\u06a9\\u0646 \\u0646\\u0627\\u0645\\u0639\\u062a\\u0628\\u0631 \\u0627\\u0633\\u062a\",\"title_en\":\"Invalid token\",\"request_id\":\"01M0TB56Q4V9KMNG657H9VRAJ5\"}", "name": "" } ] }, { "name": "Get template", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/templates\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/templates\/:id", "variable": [ { "id": "id", "key": "id", "value": "architecto", "description": "The ID of the template." }, { "id": "template", "key": "template", "value": 16, "description": "Template ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Full template shape with embedded positions + page geometry + sample preview link.\n\nScope: `templates:read`." }, "response": [ { "header": [ { "key": "x-request-id", "value": "01M0TB56QFAPZ7H9RXZN7YJPKJ" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/problem+json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 404, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/not_found\",\"status\":404,\"code\":\"not_found\",\"title_fa\":\"\\u0645\\u0646\\u0628\\u0639 \\u06cc\\u0627\\u0641\\u062a \\u0646\\u0634\\u062f\",\"title_en\":\"Resource not found\",\"request_id\":\"01M0TB56QFAPZ7H9RXZN7YJPKJ\"}", "name": "" } ] }, { "name": "Template page preview", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/templates\/:template\/preview\/:page", "query": [], "raw": "{{baseUrl}}\/api\/v1\/templates\/:template\/preview\/:page", "variable": [ { "id": "template", "key": "template", "value": 16, "description": "Template ID." }, { "id": "page", "key": "page", "value": 16, "description": "Page number (1-indexed)." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "**NOT IMPLEMENTED YET** \u2014 returns `501 preview_not_available`. The signed\npage-preview URL lands in a later phase (Storage::temporaryUrl). Documented\nas a stub so merchants do not code against a fake `url:null` 200.\n\nScope: `templates:read`." }, "response": [ { "header": [ { "key": "x-request-id", "value": "01M0TB56QR43AMCAN2EM1QGE91" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/problem+json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 401, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/token_invalid\",\"status\":401,\"code\":\"token_invalid\",\"title_fa\":\"\\u062a\\u0648\\u06a9\\u0646 \\u0646\\u0627\\u0645\\u0639\\u062a\\u0628\\u0631 \\u0627\\u0633\\u062a\",\"title_en\":\"Invalid token\",\"request_id\":\"01M0TB56QR43AMCAN2EM1QGE91\"}", "name": "" }, { "header": [], "code": 501, "body": "{\"status\":501,\"code\":\"preview_not_available\"}", "name": "Stub \u2014 not implemented" } ] } ] }, { "name": "Webhooks", "description": "\nOutbound webhook subscriptions. Customers create one or more endpoints, each\nfiltered by an array of event names. Deliveries are signed with HMAC-SHA256\nvia the secret returned at create-time (shown only once).\n\nScope: `webhooks:manage`.", "item": [ { "name": "List webhook subscriptions", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhooks", "query": [ { "key": "active", "value": "", "description": "Filter by active state.", "disabled": true }, { "key": "page", "value": "16", "description": "", "disabled": false }, { "key": "per_page", "value": "16", "description": "Max 100.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/webhooks?active=&page=16&per_page=16" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"active\":true,\"page\":16,\"per_page\":22}" }, "description": "" }, "response": [ { "header": [ { "key": "x-request-id", "value": "01M0TB56SHQJ6EZQ4CSVZ2Y3EV" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/problem+json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 401, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/token_invalid\",\"status\":401,\"code\":\"token_invalid\",\"title_fa\":\"\\u062a\\u0648\\u06a9\\u0646 \\u0646\\u0627\\u0645\\u0639\\u062a\\u0628\\u0631 \\u0627\\u0633\\u062a\",\"title_en\":\"Invalid token\",\"request_id\":\"01M0TB56SHQJ6EZQ4CSVZ2Y3EV\"}", "name": "" } ] }, { "name": "Get webhook subscription", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhooks\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/webhooks\/:id", "variable": [ { "id": "id", "key": "id", "value": "B8c6F7NNfcj9m6RJYC6RtkmZN6", "description": "The ID of the webhook." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [ { "header": [ { "key": "x-request-id", "value": "01M0TB56SVEZ9C45TYK3QK1750" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/problem+json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 401, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/token_invalid\",\"status\":401,\"code\":\"token_invalid\",\"title_fa\":\"\\u062a\\u0648\\u06a9\\u0646 \\u0646\\u0627\\u0645\\u0639\\u062a\\u0628\\u0631 \\u0627\\u0633\\u062a\",\"title_en\":\"Invalid token\",\"request_id\":\"01M0TB56SVEZ9C45TYK3QK1750\"}", "name": "" } ] }, { "name": "List webhook deliveries", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhook-deliveries", "query": [ { "key": "subscription_id", "value": "architecto", "description": "Filter by subscription.", "disabled": false }, { "key": "event_name", "value": "architecto", "description": "Filter by event name.", "disabled": false }, { "key": "status", "value": "architecto", "description": "pending|delivered|failed|dead-letter", "disabled": false }, { "key": "page", "value": "16", "description": "", "disabled": false }, { "key": "per_page", "value": "16", "description": "Max 100.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/webhook-deliveries?subscription_id=architecto&event_name=architecto&status=architecto&page=16&per_page=16" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [ { "header": [ { "key": "x-request-id", "value": "01M0TB56TMQ5DM02AAXFJY67D0" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/problem+json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 401, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/token_invalid\",\"status\":401,\"code\":\"token_invalid\",\"title_fa\":\"\\u062a\\u0648\\u06a9\\u0646 \\u0646\\u0627\\u0645\\u0639\\u062a\\u0628\\u0631 \\u0627\\u0633\\u062a\",\"title_en\":\"Invalid token\",\"request_id\":\"01M0TB56TMQ5DM02AAXFJY67D0\"}", "name": "" } ] }, { "name": "Get webhook delivery", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhook-deliveries\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/webhook-deliveries\/:id", "variable": [ { "id": "id", "key": "id", "value": "B8c6F7NNfcj9m6RJYC6RtkmZN6", "description": "The ID of the webhook delivery." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Shows full payload, response code, error message, attempt history." }, "response": [ { "header": [ { "key": "x-request-id", "value": "01M0TB56V0MKCWTNVDCQ1QR7SG" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/problem+json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 401, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/token_invalid\",\"status\":401,\"code\":\"token_invalid\",\"title_fa\":\"\\u062a\\u0648\\u06a9\\u0646 \\u0646\\u0627\\u0645\\u0639\\u062a\\u0628\\u0631 \\u0627\\u0633\\u062a\",\"title_en\":\"Invalid token\",\"request_id\":\"01M0TB56V0MKCWTNVDCQ1QR7SG\"}", "name": "" } ] }, { "name": "Create webhook subscription", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhooks", "query": [], "raw": "{{baseUrl}}\/api\/v1\/webhooks" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"url\":\"https:\\\/\\\/example.com\\\/webhooks\\\/emza\",\"events\":[\"contract.completed\",\"contract.signer.signed\"],\"active\":false}" }, "description": "Registers an HTTPS endpoint to receive event deliveries. We POST each\nmatching event to your URL and sign it with HMAC-SHA256:\n\n X-Emza-Timestamp: \n X-Emza-Signature: sha256=\n\nCompare with `hash_equals`, and reject anything whose timestamp is more than 5 minutes old.\n\nNOTE: this docblock is published to customers by Scribe. Until 2026-07-31 it described a\nStripe-style `X-Emza-Signature: t=,v1=` header that this platform has never sent \u2014\nsee App\\Services\\Webhook\\WebhookSigner, which is the only authority on the wire format, and\ntests\/Feature\/Sdk\/SdkWebhookVerificationTest, which pins the two together.\n\n**The plain signing `secret` is returned ONCE \u2014 store it immediately.**\nSubsequent reads (`index`, `show`) omit the secret entirely. Use\n`PATCH \/webhooks\/{id}` with `rotate_secret=true` to issue a fresh secret\n(invalidates the previous one immediately).\n\n**URL validation (SSRF guard):** the `url` field is rejected with `422`\nif it fails any of:\n - Non-HTTPS scheme (`http:\/\/`, `ftp:\/\/`, `javascript:`, `file:\/\/`)\n - Loopback IPs (`127.0.0.0\/8`, `::1`)\n - RFC 1918 private (`10\/8`, `172.16\/12`, `192.168\/16`)\n - Link-local + cloud metadata (`169.254.0.0\/16`, `100.100.100.200`)\n - IPv6 link-local (`fe80::\/10`) or unique-local (`fc00::\/7`)\n - Hostname suffix `.local`, `.internal`, `.private`, `.lan` or `localhost`\n - Hostname whose DNS resolves to any of the above\n\n**Allowed event names** (set in `events` array \u2014 use `[\"*\"]` for all):\n`contract.created`, `contract.processing.completed`, `contract.processing.failed`,\n`contract.signer.added`, `contract.signer.authenticated`, `contract.signer.signed`,\n`contract.signer.rejected`, `contract.completed`, `contract.canceled`,\n`contract.refunded`, `*` (wildcard).\n\nIf `*` is present alongside specific events, the specifics are dropped\n(the wildcard makes them redundant). Same event listed twice is deduped.\n\nScope: `webhooks:manage`. Idempotency-Key required (24h replay window)." }, "response": [ { "header": [], "code": 201, "body": "{\n \"data\": {\n \"id\": \"01krh7z0e8a4n39gf2ary73xbj\",\n \"url\": \"https:\/\/example.com\/webhooks\/emza\",\n \"events\": [\"contract.completed\", \"contract.signer.signed\"],\n \"active\": true,\n \"disabled_at\": null,\n \"failed_deliveries_count\": 0,\n \"last_delivery_at\": null,\n \"last_delivery_status\": null,\n \"created_at\": \"2026-05-13T18:00:42.000Z\",\n \"updated_at\": \"2026-05-13T18:00:42.000Z\",\n \"secret\": \"35ada3b45aa00df901b74b2b483114315a0c21f7c096f17e0bb29ab7d907fe32\",\n \"_warning\": \"Save this secret now \u2014 it will NOT be shown again.\"\n }\n}", "name": "" }, { "header": [], "code": 422, "body": "{\n \"type\": \"https:\/\/docs.elemza.com\/errors\/validation\",\n \"status\": 422,\n \"code\": \"validation\",\n \"title_fa\": \"\u0627\u0639\u062a\u0628\u0627\u0631\u0633\u0646\u062c\u06cc \u0648\u0631\u0648\u062f\u06cc \u0634\u06a9\u0633\u062a \u062e\u0648\u0631\u062f\",\n \"title_en\": \"Request validation failed\",\n \"errors\": {\n \"url\": [\"\u0622\u062f\u0631\u0633\u200c\u0647\u0627\u06cc \u062f\u0627\u062e\u0644\u06cc \u0634\u0628\u06a9\u0647 (localhost \/ *.local \/ *.internal) \u0645\u062c\u0627\u0632 \u0646\u06cc\u0633\u062a\u0646\u062f.\"]\n },\n \"request_id\": \"01KRH8JRC4Y855P10CYC1C0AYS\"\n}", "name": "SSRF blocked URL" } ] }, { "name": "Update webhook subscription", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhooks\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/webhooks\/:id", "variable": [ { "id": "id", "key": "id", "value": "01krh7z0e8a4n39gf2ary73xbj", "description": "Webhook subscription ULID." } ] }, "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"url\":\"http:\\\/\\\/www.bailey.biz\\\/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html\",\"events\":[\"architecto\"],\"active\":false,\"rotate_secret\":false}" }, "description": "Partial update \u2014 any field omitted is left unchanged. New `url` values\npass through the same SSRF guard as `POST \/webhooks` (see Create endpoint).\n\nWhen `rotate_secret=true`, a fresh HMAC signing secret is generated and\nreturned in the response \u2014 the previous secret is invalidated immediately,\nso any in-flight or already-sent webhook deliveries signed with the old\nsecret will fail verification on the receiver side. Plan rotations during\na quiet period or pause via `active=false` first.\n\nScope: `webhooks:manage`. Idempotency-Key required (24h replay window)." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": {\n \"id\": \"01krh7z0e8a4n39gf2ary73xbj\",\n \"url\": \"https:\/\/example.com\/webhooks\/emza\",\n \"events\": [\"*\"],\n \"active\": false,\n \"failed_deliveries_count\": 2,\n \"last_delivery_at\": \"2026-05-13T17:30:00.000Z\",\n \"last_delivery_status\": \"delivered\"\n }\n}", "name": "" } ] }, { "name": "Delete webhook subscription", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhooks\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/webhooks\/:id", "variable": [ { "id": "id", "key": "id", "value": "B8c6F7NNfcj9m6RJYC6RtkmZN6", "description": "The ID of the webhook." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Soft-deletes the subscription. In-flight deliveries that have already\nbeen queued will complete; no new deliveries are dispatched." }, "response": [] }, { "name": "Send a synthetic test event", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhooks\/:id\/test", "query": [], "raw": "{{baseUrl}}\/api\/v1\/webhooks\/:id\/test", "variable": [ { "id": "id", "key": "id", "value": "B8c6F7NNfcj9m6RJYC6RtkmZN6", "description": "The ID of the webhook." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Fires a `webhook.test` event to verify the endpoint is reachable + signed\ncorrectly. Counts toward `webhook_deliveries` like a real event." }, "response": [] }, { "name": "Replay webhook delivery", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhook-deliveries\/:id\/replay", "query": [], "raw": "{{baseUrl}}\/api\/v1\/webhook-deliveries\/:id\/replay", "variable": [ { "id": "id", "key": "id", "value": "B8c6F7NNfcj9m6RJYC6RtkmZN6", "description": "The ID of the webhook delivery." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Creates a NEW delivery row with the same payload + subscription. The\noriginal row keeps its terminal status (failed \/ dead-letter \/ delivered)." }, "response": [] } ] } ], "auth": { "type": "bearer", "bearer": [ { "key": "Authorization", "type": "string" } ] } }