{ "info": { "_postman_id": "f57595f3-4e12-5207-8ad7-17bc8ecccce0", "name": "BuiltSign API v1", "description": "The BuiltSign v1 API, generated from https://api.builtsign.com/openapi.json.\n\n1. Set the collection variable `apiKey` to a sandbox key (`bs_...`, Settings > API keys, tick Sandbox).\n2. Leave `baseUrl` at https://api.builtsign.com.\n3. Calls that create or send get a fresh `Idempotency-Key` ({{$guid}}) on every send. To test a retry, replace it with a fixed value.\n\nDocs: https://builtsign.com/developers. Changelog: https://builtsign.com/developers/changelog.", "version": "1.0.0", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key", "type": "string" }, { "key": "value", "value": "{{apiKey}}", "type": "string" }, { "key": "in", "value": "header", "type": "string" } ] }, "variable": [ { "key": "baseUrl", "value": "https://api.builtsign.com", "type": "string" }, { "key": "apiKey", "value": "", "type": "string", "description": "Your API key. Use a sandbox key to test." } ], "item": [ { "name": "Signing requests", "item": [ { "name": "List signing requests", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/signing-requests", "host": [ "{{baseUrl}}" ], "path": [ "v1", "signing-requests" ], "query": [ { "key": "status", "value": "", "description": "", "disabled": true }, { "key": "created_after", "value": "", "description": "Only requests created after this ISO 8601 timestamp", "disabled": true }, { "key": "created_before", "value": "", "description": "Only requests created before this ISO 8601 timestamp", "disabled": true }, { "key": "signer_email", "value": "", "description": "Filter by signer email (exact match)", "disabled": true }, { "key": "limit", "value": "50", "description": "", "disabled": true }, { "key": "offset", "value": "0", "description": "", "disabled": true }, { "key": "starting_after", "value": "", "description": "Cursor: the `next_cursor` (an item id) of the previous page. Returns the items after it in the same sort order. Cannot be combined with `offset`.", "disabled": true }, { "key": "sort", "value": "created_at", "description": "", "disabled": true }, { "key": "order", "value": "desc", "description": "", "disabled": true } ] }, "description": "List all signing requests for your organisation, newest first.\n\n**Filters:**\n- `status`: `draft`, `pending`, `completed`, `cancelled`, `expired`\n- `created_after` / `created_before`: ISO 8601 timestamps\n- `signer_email`: exact match on a signer's email address\n- `sort` (`created_at`, `updated_at`, `expires_at`) and `order` (`asc`, `desc`)\n\n**Paging:** `limit` with either `offset` or the cursor `starting_after`. For\nsyncing, use the cursor: pass the `next_cursor` of the previous page as\n`starting_after` until `has_more` is `false`. Items with the same timestamp are\nordered by id, so a page boundary never skips or repeats one.\n\n**Requires scope:** `read`" }, "response": [] }, { "name": "Create a signing request", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "description": "A new key per send. Repeat a fixed key to test a safe retry." } ], "url": { "raw": "{{baseUrl}}/v1/signing-requests", "host": [ "{{baseUrl}}" ], "path": [ "v1", "signing-requests" ] }, "body": { "mode": "raw", "raw": "{\n \"document_id\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n \"signers\": [\n {\n \"name\": \"Jan Janssen\",\n \"email\": \"jan@bedrijf.nl\",\n \"order\": 1\n },\n {\n \"name\": \"Maria Pietersen\",\n \"email\": \"maria@bedrijf.nl\",\n \"order\": 2\n }\n ],\n \"message\": \"Graag het contract ondertekenen voor akkoord.\",\n \"signing_order\": \"sequential\",\n \"expires_in_days\": 7,\n \"auto_send\": true\n}", "options": { "raw": { "language": "json" } } }, "description": "Create a new signing request and optionally send it immediately.\n\n**Steps:**\n1. Upload a document via the dashboard or API to get a `document_id`\n (a sandbox key can only use documents uploaded with a sandbox key)\n2. Call this endpoint with the document ID and signer details\n3. If `auto_send: true`, invite emails are sent immediately\n4. Poll `GET /api/v1/events` or use webhooks to track progress\n\n**Signing order:**\n- `parallel` — all signers receive the invite at once\n- `sequential` — signer #2 is notified only after signer #1 has signed\n\n**SMS code:**\n- Every signer confirms with an SMS code; `phone_verification_required` is always `true` outside the sandbox\n- A signer `phone` locks the code to that number; without one the signer enters their own\n- `sms_invite: true` on a signer with a `phone` also sends the signing link by SMS (paid plans)\n- Not enough SMS left in the bundle: `402` with `quota_exceeded` and `details.resource: \"sms\"` on send\n\n**With `auto_send: true`** the send limits are checked first: when the plan\ncannot cover the send (`402`), nothing is created, so a retry never leaves a\nstray draft behind.\n\n**Malware scan:** a document the malware scan rejected returns `422` with\n`document_blocked` and nothing is created. One whose scan is still running can be used.\n\n**Limits:** 1 to 50 signers, `message` at most 2000 characters,\n`expires_in_days` 1 to 365. Outside these: `422` with `validation_error`.\n\n**Requires scope:** `write`" }, "response": [] }, { "name": "Get a signing request", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/signing-requests/:request_id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "signing-requests", ":request_id" ], "variable": [ { "key": "request_id", "value": "", "description": "" } ] }, "description": "Fetch a single signing request by ID, including all signers and their current status.\n\n**Requires scope:** `read`" }, "response": [] }, { "name": "Get signing events", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/signing-requests/:request_id/events", "host": [ "{{baseUrl}}" ], "path": [ "v1", "signing-requests", ":request_id", "events" ], "variable": [ { "key": "request_id", "value": "", "description": "" } ] }, "description": "Get events for a signing request." }, "response": [] }, { "name": "Send signing request", "request": { "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "{{$guid}}", "description": "A new key per send. Repeat a fixed key to test a safe retry." } ], "url": { "raw": "{{baseUrl}}/v1/signing-requests/:request_id/send", "host": [ "{{baseUrl}}" ], "path": [ "v1", "signing-requests", ":request_id", "send" ], "variable": [ { "key": "request_id", "value": "", "description": "" } ] }, "description": "Send a draft signing request to its signers." }, "response": [] }, { "name": "Cancel signing request", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "description": "A new key per send. Repeat a fixed key to test a safe retry." } ], "url": { "raw": "{{baseUrl}}/v1/signing-requests/:request_id/cancel", "host": [ "{{baseUrl}}" ], "path": [ "v1", "signing-requests", ":request_id", "cancel" ], "variable": [ { "key": "request_id", "value": "", "description": "" } ] }, "body": { "mode": "raw", "raw": "{\n \"reason\": \"Sent by mistake\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Cancel a pending signing request." }, "response": [] }, { "name": "Remind signers", "request": { "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "{{$guid}}", "description": "A new key per send. Repeat a fixed key to test a safe retry." } ], "url": { "raw": "{{baseUrl}}/v1/signing-requests/:request_id/remind", "host": [ "{{baseUrl}}" ], "path": [ "v1", "signing-requests", ":request_id", "remind" ], "variable": [ { "key": "request_id", "value": "", "description": "" } ] }, "description": "Send a reminder email to all pending signers.\nFor sequential requests, only the current active signer is reminded.\nNo-op for sandbox requests (no emails sent, event still logged)." }, "response": [] }, { "name": "Reactivate signing request", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/signing-requests/:request_id/reactivate", "host": [ "{{baseUrl}}" ], "path": [ "v1", "signing-requests", ":request_id", "reactivate" ], "variable": [ { "key": "request_id", "value": "", "description": "" } ] }, "body": { "mode": "raw", "raw": "{\n \"expires_in_days\": 7\n}", "options": { "raw": { "language": "json" } } }, "description": "Reactivate an expired signing request with a fresh expiry date.\nThe request is set back to draft — call /send again to notify signers." }, "response": [] }, { "name": "Create embedded url", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/signing-requests/:request_id/embedded-url", "host": [ "{{baseUrl}}" ], "path": [ "v1", "signing-requests", ":request_id", "embedded-url" ], "variable": [ { "key": "request_id", "value": "", "description": "" } ] }, "body": { "mode": "raw", "raw": "{\n \"allowed_origin\": \"https://app.example.com\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Generate embedded signing URLs for loading inside an iframe.\n\nThe `allowed_origin` must be registered in your organisation's embed origins allowlist\n(Settings > Integrations). Each URL is valid for 60 minutes, and only that origin\nmay load it in a frame (`frame-ancestors`).\n\nThe signing page posts `builtsign:ready`, `builtsign:signed`, `builtsign:declined` and\n`builtsign:error` to the parent window (target origin `allowed_origin`). With `return_url`\nthe iframe navigates there after signing or declining; its origin must be on the allowlist too." }, "response": [] }, { "name": "Add signature fields", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/signing-requests/:request_id/fields", "host": [ "{{baseUrl}}" ], "path": [ "v1", "signing-requests", ":request_id", "fields" ], "variable": [ { "key": "request_id", "value": "", "description": "" } ] }, "body": { "mode": "raw", "raw": "{\n \"fields\": [\n {\n \"signer_id\": \"00000000-0000-0000-0000-000000000000\",\n \"field_type\": \"signature\",\n \"page_number\": 1,\n \"x_percent\": 60,\n \"y_percent\": 82,\n \"width_percent\": 30,\n \"height_percent\": 8\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "description": "Place signature fields on a signing request.\n\nAll fields are created in one call — replaces any existing fields.\nPositions are percentage-based (0–100) relative to the page dimensions." }, "response": [] }, { "name": "Download signed pdf", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/signing-requests/:request_id/download", "host": [ "{{baseUrl}}" ], "path": [ "v1", "signing-requests", ":request_id", "download" ], "variable": [ { "key": "request_id", "value": "", "description": "" } ] }, "description": "Get a presigned download URL for the completed signed PDF.\nThe URL is valid for 15 minutes; request a new one when it expires. Only available when status is `completed`.\nRight after completion the signed PDF can still be in preparation: the call then returns 409\n`document_not_ready` with a `Retry-After` header. Without `Retry-After` the error is final:\n409 `conflict` when the signed PDF could not be generated, 410 `document_file_removed` once it\nwas removed after the retention period." }, "response": [] }, { "name": "Download the audit certificate", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/signing-requests/:request_id/audit-certificate", "host": [ "{{baseUrl}}" ], "path": [ "v1", "signing-requests", ":request_id", "audit-certificate" ], "variable": [ { "key": "request_id", "value": "", "description": "" } ] }, "description": "The audit certificate (PDF) of a signing request: who signed what, when and\nhow (IP address, device, SMS and ID checks), with the document hash, the\ntrusted timestamp and the evidence hash. Store it next to the signed PDF.\n\nAvailable once the request is `completed`, `cancelled` or `expired`.\n- `409 signing_request_wrong_status`: the request is still a draft or open.\n- `409 document_not_ready` with `Retry-After`: the request was just completed\n and the signed PDF and its evidence are still being prepared. Retry after the\n given number of seconds.\n\nSandbox requests get a certificate marked as sandbox.\n\n**Requires scope:** `read`" }, "response": [] } ] }, { "name": "Documents", "item": [ { "name": "List documents", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/documents", "host": [ "{{baseUrl}}" ], "path": [ "v1", "documents" ], "query": [ { "key": "limit", "value": "50", "description": "", "disabled": true }, { "key": "offset", "value": "0", "description": "", "disabled": true }, { "key": "starting_after", "value": "", "description": "Cursor: the `next_cursor` (an item id) of the previous page. Returns the items after it in the same sort order. Cannot be combined with `offset`.", "disabled": true } ] }, "description": "List the documents of your organisation, newest first.\n\n**Paging:** `limit` with either `offset` or the cursor `starting_after`. For\nsyncing, use the cursor: pass the `next_cursor` of the previous page as\n`starting_after` until `has_more` is `false`.\n\n**Requires scope:** `read`" }, "response": [] }, { "name": "Upload document", "request": { "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "{{$guid}}", "description": "A new key per send. Repeat a fixed key to test a safe retry." } ], "url": { "raw": "{{baseUrl}}/v1/documents/upload", "host": [ "{{baseUrl}}" ], "path": [ "v1", "documents", "upload" ] }, "body": { "mode": "formdata", "formdata": [ { "key": "file", "type": "file", "src": [] } ] }, "description": "Upload a PDF document via API key.\nReturns document_id for use in POST /v1/signing-requests.\nMax file size: 50 MB; larger files (up to 1 GB) go through POST /v1/uploads." }, "response": [] }, { "name": "Get a document", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/documents/:document_id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "documents", ":document_id" ], "variable": [ { "key": "document_id", "value": "", "description": "" } ] }, "description": "Fetch one document with its signing requests and what a delete would do now\n(`removal`).\n\n**Requires scope:** `read`" }, "response": [] }, { "name": "Delete a document", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/v1/documents/:document_id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "documents", ":document_id" ], "variable": [ { "key": "document_id", "value": "", "description": "" } ] }, "description": "Delete a document that holds no evidence, together with its draft signing\nrequests that were never signed. The file is removed from storage.\n\n- `409 document_has_open_request`: the document is part of a signing request\n that is still open. Cancel that request first.\n- `409 document_has_evidence`: the document carries signatures, a decline or an\n ID check, or is a signed copy. Signed copies and evidence are kept for 7 years,\n so the document cannot be deleted.\n\n`GET /v1/documents/{id}` shows in `removal` what a delete would do.\n\n**Requires scope:** `write`" }, "response": [] }, { "name": "Start a large upload", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "description": "A new key per send. Repeat a fixed key to test a safe retry." } ], "url": { "raw": "{{baseUrl}}/v1/uploads", "host": [ "{{baseUrl}}" ], "path": [ "v1", "uploads" ] }, "body": { "mode": "raw", "raw": "{\n \"filename\": \"bouwtekening.pdf\",\n \"file_size\": 734003200,\n \"content_type\": \"application/pdf\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Upload a PDF of up to 1 GB in parts, straight to storage. Use this for files over\n50 MB; `POST /v1/documents/upload` takes up to 50 MB in one request.\n\n**Steps:**\n1. Call this endpoint with the file name and exact size. You get an upload `id`, a `part_size` and a presigned `PUT` URL per part.\n2. Send part *n* (bytes `(n-1) * part_size` up to `n * part_size`) with `PUT` to its URL, in parallel if you like. Keep the `ETag` response header of every part.\n3. Call `POST /v1/uploads/{upload_id}/complete` with all part numbers and ETags. That returns the `document_id` for `POST /v1/signing-requests`.\n\nThe part URLs are valid for 15 minutes (`expires_at`). Ask fresh ones with\n`POST /v1/uploads/{upload_id}/parts`, also for parts above the first 100.\nAn upload that is never completed expires after 7 days; `POST /v1/uploads/{upload_id}/abort` stops it right away.\n\nThe size limit of your plan and its storage are checked here and again on\ncomplete, against the real size. Sandbox keys: up to 1 GB, nothing counts toward your quota.\n\n**Requires scope:** `write`" }, "response": [] }, { "name": "Get upload URLs for parts", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/uploads/:upload_id/parts", "host": [ "{{baseUrl}}" ], "path": [ "v1", "uploads", ":upload_id", "parts" ], "variable": [ { "key": "upload_id", "value": "", "description": "" } ] }, "body": { "mode": "raw", "raw": "{\n \"part_numbers\": [\n 3,\n 4\n ]\n}", "options": { "raw": { "language": "json" } } }, "description": "Fresh presigned `PUT` URLs for up to 100 parts of an upload in progress: for\nparts above the first 100, or when the earlier URLs expired. Asking a URL again\nfor a part you already sent is fine; the last `PUT` of a part counts.\n\n**Requires scope:** `write`" }, "response": [] }, { "name": "Complete a large upload", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "description": "A new key per send. Repeat a fixed key to test a safe retry." } ], "url": { "raw": "{{baseUrl}}/v1/uploads/:upload_id/complete", "host": [ "{{baseUrl}}" ], "path": [ "v1", "uploads", ":upload_id", "complete" ], "variable": [ { "key": "upload_id", "value": "", "description": "" } ] }, "body": { "mode": "raw", "raw": "{\n \"parts\": [\n {\n \"part_number\": 1,\n \"etag\": \"\\\"a54357aff0632cce46d942af68356b38\\\"\"\n },\n {\n \"part_number\": 2,\n \"etag\": \"\\\"0c78aef83f66abc1fa1e8477f296d394\\\"\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "description": "Joins the parts into one file and creates the document. Pass every part number\nwith the `ETag` that its `PUT` returned. The API then checks the real size\nagainst your plan, and that the file starts with `%PDF`; a file that fails is\ndeleted. Returns the same document as `POST /v1/documents/upload`, and fires\nthe `document.uploaded` webhook.\n\n**Requires scope:** `write`" }, "response": [] }, { "name": "Abort a large upload", "request": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/v1/uploads/:upload_id/abort", "host": [ "{{baseUrl}}" ], "path": [ "v1", "uploads", ":upload_id", "abort" ], "variable": [ { "key": "upload_id", "value": "", "description": "" } ] }, "description": "Stops an upload in progress and deletes the parts sent so far.\n\n**Requires scope:** `write`" }, "response": [] } ] }, { "name": "Templates", "item": [ { "name": "List templates", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/templates", "host": [ "{{baseUrl}}" ], "path": [ "v1", "templates" ], "query": [ { "key": "limit", "value": "50", "description": "", "disabled": true }, { "key": "offset", "value": "0", "description": "", "disabled": true } ] }, "description": "List templates for the organization.\n\nA sandbox key lists only templates created with a sandbox key; a live key never lists those." }, "response": [] }, { "name": "Create template", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "description": "A new key per send. Repeat a fixed key to test a safe retry." } ], "url": { "raw": "{{baseUrl}}/v1/templates", "host": [ "{{baseUrl}}" ], "path": [ "v1", "templates" ] }, "body": { "mode": "raw", "raw": "{\n \"name\": \"Example\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Create a new signing template.\n\nTemplate names are unique per owner (the user who created the API key), ignoring case\nand surrounding spaces: a name that is already in use returns `409` with\n`template_name_exists` and the existing template's id in `details.template_id`." }, "response": [] }, { "name": "Get template", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/templates/:template_id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "templates", ":template_id" ], "variable": [ { "key": "template_id", "value": "", "description": "" } ] }, "description": "Get a template by ID." }, "response": [] }, { "name": "Update template", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/templates/:template_id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "templates", ":template_id" ], "variable": [ { "key": "template_id", "value": "", "description": "" } ] }, "body": { "mode": "raw", "raw": "{\n \"name\": \"Example\",\n \"description\": \"\",\n \"document_id\": \"00000000-0000-0000-0000-000000000000\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Update a template.\n\nRenaming to a name the template's owner already uses returns `409` with `template_name_exists`.\nA `document_id` must be a document of your organization (with a sandbox key: one uploaded\nwith a sandbox key), otherwise `404` with `document_not_found`." }, "response": [] }, { "name": "Delete template", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/v1/templates/:template_id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "templates", ":template_id" ], "variable": [ { "key": "template_id", "value": "", "description": "" } ] }, "description": "Delete a template." }, "response": [] }, { "name": "Send from template", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "description": "A new key per send. Repeat a fixed key to test a safe retry." } ], "url": { "raw": "{{baseUrl}}/v1/templates/:template_id/send", "host": [ "{{baseUrl}}" ], "path": [ "v1", "templates", ":template_id", "send" ], "variable": [ { "key": "template_id", "value": "", "description": "" } ] }, "body": { "mode": "raw", "raw": "{\n \"signers\": [\n {\n \"email\": \"jan@example.com\",\n \"name\": \"Example\",\n \"role\": \"Signer\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "description": "Create and send a signing request from a template.\n\nMap your signers to template roles by name (case-insensitive).\nEvery signer gets an SMS code before signing, whatever the template says;\nonly sandbox keys skip it. A signer `phone` locks the code to that number,\n`sms_invite: true` also sends the signing link by SMS (paid plans).\nOptionally provide `variables` to substitute {{key}} placeholders in field values.\nSet `auto_send: false` to create a draft you can still modify before sending.\n\nSupports `Idempotency-Key`: retrying with the same key returns the original\nrequest instead of creating and sending a duplicate." }, "response": [] } ] }, { "name": "Bulk send", "item": [ { "name": "Bulk send", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "description": "A new key per send. Repeat a fixed key to test a safe retry." } ], "url": { "raw": "{{baseUrl}}/v1/bulk-send", "host": [ "{{baseUrl}}" ], "path": [ "v1", "bulk-send" ] }, "body": { "mode": "raw", "raw": "{\n \"template_id\": \"00000000-0000-0000-0000-000000000000\",\n \"recipients\": [\n {\n \"signers\": [\n {\n \"email\": \"jan@example.com\",\n \"name\": \"Example\",\n \"role\": \"Signer\"\n }\n ]\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "description": "Send the same template to multiple recipients in a single API call.\nEach recipient gets an independent signing request.\nReturns immediately with a `bulk_job_id` you can poll via GET /bulk-jobs/{id}.\nEvery signer gets an SMS code (not with a sandbox key); with `auto_send` the\nwhole job is refused with `402` when the SMS bundle cannot cover it.\n\nSupports `Idempotency-Key`: retrying with the same key returns the original\njob instead of sending the whole batch again." }, "response": [] }, { "name": "Get bulk job", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/bulk-jobs/:bulk_job_id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "bulk-jobs", ":bulk_job_id" ], "variable": [ { "key": "bulk_job_id", "value": "", "description": "" } ] }, "description": "Get the status and results of a bulk send job." }, "response": [] } ] }, { "name": "Events", "item": [ { "name": "List signing events", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/events", "host": [ "{{baseUrl}}" ], "path": [ "v1", "events" ], "query": [ { "key": "limit", "value": "50", "description": "", "disabled": true }, { "key": "offset", "value": "0", "description": "", "disabled": true }, { "key": "event_type", "value": "", "description": "Filter by event type, e.g. 'signer.signed'", "disabled": true }, { "key": "signing_request_id", "value": "", "description": "", "disabled": true }, { "key": "after", "value": "", "description": "Only events after this ISO 8601 timestamp", "disabled": true }, { "key": "after_id", "value": "", "description": "Older name of `starting_after`: only events older than the event with this ID", "disabled": true }, { "key": "starting_after", "value": "", "description": "Cursor: the `next_cursor` (an item id) of the previous page. Returns the items after it in the same sort order. Cannot be combined with `offset`.", "disabled": true } ] }, "description": "Poll for signing events across your organisation. Useful for building integrations\nthat react to document activity without using webhooks.\n\n**Event types:**\n| Type | When |\n|---|---|\n| `signing_request.created` | Request created |\n| `signing_request.sent` | Invitations sent |\n| `signing_request.reminded` | Reminder sent |\n| `signing_request.completed` | All signatures collected |\n| `signing_request.cancelled` | Request cancelled |\n| `signing_request.expired` | Request expired |\n| `signer.viewed` | Signer opened the signing link |\n| `signer.signed` | A signer signed |\n| `signer.declined` | A signer declined |\n| `signer.withdrawn` | A signer withdrew their signature |\n| `signer.reviewed` | Identity check flagged for manual review |\n| `identity.approved` | Identity verification passed |\n| `identity.rejected` | Identity verification failed |\n| `document.signed` | Final signed PDF is available |\n\nOther audit-trail entries appear as `signing_event.` (for example\n`signing_event.downloaded`) and can be filtered by that same name.\n`document.uploaded` and `member.invited` are webhook-only and do not appear here.\n\n**Paging:** newest first. Pass `starting_after` (the `next_cursor` of the\nprevious page) to fetch the next, older page, until `has_more` is `false`.\nEvents that share a timestamp are never skipped. `after_id` (with `last_id`)\nstill works the same way; `offset` works too, but not together with a cursor.\n\n**Requires scope:** `read`" }, "response": [] } ] }, { "name": "Webhooks", "item": [ { "name": "List webhooks", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/webhooks", "host": [ "{{baseUrl}}" ], "path": [ "v1", "webhooks" ] }, "description": "List the webhooks of the organisation in the key's mode: a sandbox key lists only\nwebhooks created with a sandbox key, a live key only the others." }, "response": [] }, { "name": "Create webhook", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/webhooks", "host": [ "{{baseUrl}}" ], "path": [ "v1", "webhooks" ] }, "body": { "mode": "raw", "raw": "{\n \"name\": \"Example\",\n \"url\": \"https://example.com/webhooks/builtsign\",\n \"events\": [\n \"signing_request.completed\",\n \"document.signed\"\n ]\n}", "options": { "raw": { "language": "json" } } }, "description": "Create a webhook endpoint to receive signing events.\nThe `secret` field is returned only once — store it securely.\nA webhook created with a sandbox key receives only sandbox events; one created with a\nlive key (or in the dashboard) only live events." }, "response": [] }, { "name": "Get webhook", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/webhooks/:webhook_id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "webhooks", ":webhook_id" ], "variable": [ { "key": "webhook_id", "value": "", "description": "" } ] }, "description": "Get a single webhook by ID." }, "response": [] }, { "name": "Update webhook", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/webhooks/:webhook_id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "webhooks", ":webhook_id" ], "variable": [ { "key": "webhook_id", "value": "", "description": "" } ] }, "body": { "mode": "raw", "raw": "{\n \"name\": \"Example\",\n \"url\": \"https://example.com/webhooks/builtsign\",\n \"events\": [\n \"signing_request.completed\",\n \"document.signed\"\n ]\n}", "options": { "raw": { "language": "json" } } }, "description": "Update a webhook's name, URL, subscribed events, or status.\nSet `status` to `\"paused\"` to temporarily stop deliveries." }, "response": [] }, { "name": "Delete webhook", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/v1/webhooks/:webhook_id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "webhooks", ":webhook_id" ], "variable": [ { "key": "webhook_id", "value": "", "description": "" } ] }, "description": "Delete a webhook endpoint. All delivery history is also removed." }, "response": [] }, { "name": "Regenerate webhook secret", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/webhooks/:webhook_id/regenerate-secret", "host": [ "{{baseUrl}}" ], "path": [ "v1", "webhooks", ":webhook_id", "regenerate-secret" ], "variable": [ { "key": "webhook_id", "value": "", "description": "" } ] }, "body": { "mode": "raw", "raw": "{\n \"overlap_hours\": 24\n}", "options": { "raw": { "language": "json" } } }, "description": "Rotate the webhook signing secret. The new secret is returned once, store it immediately.\n\nThe previous secret keeps signing deliveries for `overlap_hours` (default 24): during\nthat time `X-BuiltSign-Webhook-Signature` carries a `v1` for each secret, so a receiver\nstill on the old secret keeps accepting deliveries. The legacy `X-Webhook-Signature`\nheader uses the new secret right away." }, "response": [] }, { "name": "List webhook deliveries", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/webhooks/:webhook_id/deliveries", "host": [ "{{baseUrl}}" ], "path": [ "v1", "webhooks", ":webhook_id", "deliveries" ], "query": [ { "key": "limit", "value": "50", "description": "", "disabled": true }, { "key": "offset", "value": "0", "description": "", "disabled": true }, { "key": "success", "value": "", "description": "", "disabled": true } ], "variable": [ { "key": "webhook_id", "value": "", "description": "" } ] }, "description": "Get delivery history for a webhook endpoint.\nUse `success=false` to filter only failed attempts." }, "response": [] }, { "name": "Test webhook", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/webhooks/:webhook_id/test", "host": [ "{{baseUrl}}" ], "path": [ "v1", "webhooks", ":webhook_id", "test" ], "variable": [ { "key": "webhook_id", "value": "", "description": "" } ] }, "body": { "mode": "raw", "raw": "{\n \"event_type\": \"signing_request.created\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Send a signed test event to the endpoint, with `\"test\": true` in the payload and\nthe header `X-Webhook-Test: true`. It is signed like a real delivery, is not stored\nas a delivery and does not count as a failure. Works on paused and failed webhooks." }, "response": [] }, { "name": "Redeliver webhook delivery", "request": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/v1/webhooks/deliveries/:delivery_id/redeliver", "host": [ "{{baseUrl}}" ], "path": [ "v1", "webhooks", "deliveries", ":delivery_id", "redeliver" ], "variable": [ { "key": "delivery_id", "value": "", "description": "" } ] }, "description": "Send a stored delivery again, with the same body and so the same `event_id`.\nOnly deliveries of a webhook in the key's mode (sandbox or live) of your organisation.\nReturns the new delivery, which has its own id. It is not retried automatically;\nwhen it succeeds, the retries still planned for the original stop." }, "response": [] } ] }, { "name": "Contacts", "item": [ { "name": "List contacts", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/contacts", "host": [ "{{baseUrl}}" ], "path": [ "v1", "contacts" ], "query": [ { "key": "search", "value": "", "description": "", "disabled": true }, { "key": "limit", "value": "50", "description": "", "disabled": true }, { "key": "offset", "value": "0", "description": "", "disabled": true } ] }, "description": "List saved contacts for the authenticated organisation. Not available with a sandbox key (`403`)." }, "response": [] }, { "name": "Create or update a contact", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/contacts", "host": [ "{{baseUrl}}" ], "path": [ "v1", "contacts" ] }, "body": { "mode": "raw", "raw": "{\n \"name\": \"Example\",\n \"email\": \"jan@example.com\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Create a contact, or update name if the email already exists in the organisation.\nNot available with a sandbox key (`403`)." }, "response": [] }, { "name": "Delete a contact", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/v1/contacts/:contact_id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "contacts", ":contact_id" ], "variable": [ { "key": "contact_id", "value": "", "description": "" } ] }, "description": "Delete a contact by ID. Not available with a sandbox key (`403`)." }, "response": [] } ] }, { "name": "Usage", "item": [ { "name": "Get usage & quota", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/usage", "host": [ "{{baseUrl}}" ], "path": [ "v1", "usage" ] }, "description": "Return current-period usage and plan limits for the authenticated organisation." }, "response": [] }, { "name": "Get the organization behind this API key", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/me", "host": [ "{{baseUrl}}" ], "path": [ "v1", "me" ] }, "description": "Return the organization and the API key used for this call. Handy to label a connection." }, "response": [] } ] } ] }