{ "openapi": "3.1.0", "info": { "title": "HelpRange API", "version": "2026-11-15", "description": "REST API of HelpRange: upload documents, create protected share links, run data rooms (guests, folders, Q&A, request lists), send documents for e-signature, create offers and read page-by-page analytics.\n\n**Authentication.** Create a team API key in Settings → API keys and send it as `Authorization: Bearer hr_live_…` (also accepted: `X-API-Key: `, `Authorization: Api-Key `; the older `/public-api` endpoints take the key in `Authorization`, bare or as `Bearer`). A key acts as the administrator who created it, with their rights in the panel, and only within its **scopes** (`documents:read`, `documents:write`, `links:read`, `links:write`, `rooms:read`, `rooms:write`, `analytics:read`, `team:read`, `webhooks:manage`); each operation names the scope it needs in `x-required-scope`. A key without it: 403 `{\"error\", \"code\": \"insufficient_scope\", \"required_scope\"}`. The legacy personal key (profile page) and OAuth access tokens of the HelpRange MCP connector (`Authorization: Bearer `) keep full access. Keep keys on your server.\n\n**Test mode.** Keys starting with `hr_test_` work on a separate sandbox of your team with sample data – never on live data. No e-mail is sent (test mode accepts only addresses at reserved test domains such as example.com; others: 400 `sandbox_email_domain`), nothing reaches Stripe, and sandbox activity sends no webhooks. Every response of a team key carries `\"livemode\": true|false` (JSON objects) and the `X-HelpRange-Livemode` header. Sandbox data is deleted 30 days after the sandbox was created or reset.\n\n**Retries.** There is no Idempotency-Key header. GET requests are safe to retry. A share link's label is unique per document, so retrying \"Create a share link\" with the same label answers 400 instead of making a second link; inviting a guest who is already in the room answers 200 with `already_a_guest: true`.\n\n**Webhooks.** Signed JSON events (`HelpRange-Signature: t=,v1=.\">`), retried for about 3 days, with a 30-day delivery log – see `webhooks` in this document and https://www.helprange.com/developers/webhooks. Endpoints are set up in Settings → Integrations.\n\n**Plans.** REST API v2 and /public-api are part of the Max and Unlimited plans, the Deal Room Pass and the trial (`/me`, `/folders` and buyer access also work on Pro). Other plans: 402 with `{\"error\": \"...\"}`.\n\n**Errors.** JSON `{\"error\": \"...\"}` (some with a `code`); v1 uses `{\"status\", \"message\"}` or `{\"result\": \"failure\", \"reason\"}`.\n\n**Usage limits** (per team, all keys and connected apps together; clock hour / minute, UTC): 3,600 requests an hour and 120 a minute; 300 write requests an hour; 2,000 share links and 1,000 guests created through the API a day; 100 e-mails to other people an hour and 500 a day (at most 50 recipients per request); per IP address 4,000 requests an hour and 60 with a missing or invalid key; more than 300 failed requests in an hour pause the team's API for 15 minutes. Over a limit: 429 with `{\"error\", \"code\", \"retry_after\"}` and `Retry-After`. Every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`.", "contact": { "name": "HelpRange", "email": "hello@helprange.com", "url": "https://www.helprange.com/developers" }, "termsOfService": "https://www.helprange.com/terms" }, "servers": [ { "url": "https://www.helprange.com" } ], "externalDocs": { "description": "API reference", "url": "https://www.helprange.com/developers/api" }, "tags": [ { "name": "Account", "description": "Who is connected, the plan and its limits." }, { "name": "Folders", "description": "Folders and their subfolders." }, { "name": "Documents", "description": "Uploads, documents, statistics and share links." }, { "name": "Triggers", "description": "Polling triggers for Zapier, Make and n8n: newest first, each item with a stable id." }, { "name": "Data rooms", "description": "Data rooms, their index, guests, folders, documents, Q&A and request lists." }, { "name": "E-signature", "description": "Send documents for e-signature, follow them and download the signed PDF." }, { "name": "Offers", "description": "Offers with their own link; the API never e-mails the client." }, { "name": "Store", "description": "Store sales and buyer access to product folders." }, { "name": "Lead forms", "description": "Lead magnet / landing page forms." }, { "name": "Activity", "description": "The team activity feed." }, { "name": "v1 (legacy)", "description": "The original /public-api endpoints. They keep working; new integrations should use REST API v2." }, { "name": "Webhooks", "description": "Events HelpRange POSTs to your endpoint (Settings → Integrations)." } ], "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "paths": { "/api/v2/me": { "get": { "operationId": "getMe", "summary": "Who is connected", "description": "The user the API key (or OAuth token) belongs to – the \"test\" call of Zapier, Make and n8n. Also works on Pro.", "tags": [ "Account" ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "team": { "type": [ "string", "null" ] }, "plan": { "type": [ "string", "null" ], "description": "Plan key, e.g. max, pro, trial." } }, "required": [ "email", "name", "team", "plan" ] }, "example": { "email": "ann@acme.com", "name": "Ann Admin", "team": "Acme", "plan": "max" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "team:read", "x-plan": "Pro, Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "get-me", "x-hr-write": false } }, "/api/v2/plan": { "get": { "operationId": "getPlan", "summary": "Plan, features and limits", "description": "The team's plan, which features it includes (and the plan each other feature needs), AI requests left, reader views left (Free and the trial), the first-week view cap and data rooms left.", "tags": [ "Account" ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": "string" }, "plan_key": { "type": "string" }, "you_are_admin": { "type": "boolean" }, "features": { "type": "array", "items": { "type": "object", "properties": { "feature": { "type": "string" }, "available": { "type": "boolean" }, "plan_needed": { "type": "string" } }, "required": [ "feature", "available", "plan_needed" ] } }, "ai_requests": { "type": "object", "properties": { "used": { "type": "integer" }, "limit": { "type": "integer" }, "left": { "type": "integer" }, "period": { "type": "string" } }, "required": [ "used", "limit", "left", "period" ] }, "reader_views": { "type": [ "object", "null" ], "properties": { "limit": { "type": "integer" }, "left": { "type": "integer" }, "period": { "type": "string" } }, "required": [ "limit", "left", "period" ] }, "first_week_cap": { "type": [ "object", "null" ], "properties": { "limit": { "type": "integer" }, "left": { "type": "integer" } }, "required": [ "limit", "left" ] }, "data_rooms_left": { "type": [ "integer", "null" ] }, "mcp_server": { "type": "boolean", "description": "The plan includes the MCP server." }, "rest_api": { "type": "boolean", "description": "The plan includes the REST API." }, "pricing_url": { "type": "string", "format": "uri" }, "trial_ends_on": { "type": "string", "format": "date", "description": "Only on the trial." }, "pass_ends_on": { "type": "string", "format": "date", "description": "Only on the Deal Room Pass." } }, "required": [ "plan", "plan_key", "you_are_admin", "features", "ai_requests", "reader_views", "first_week_cap", "data_rooms_left", "mcp_server", "rest_api", "pricing_url" ] }, "example": { "plan": "Max", "plan_key": "max", "you_are_admin": true, "features": [ { "feature": "E-signature", "available": true, "plan_needed": "Pro" } ], "ai_requests": { "used": 12, "limit": 500, "left": 488, "period": "calendar month" }, "reader_views": null, "first_week_cap": null, "data_rooms_left": null, "mcp_server": true, "rest_api": true, "pricing_url": "https://www.helprange.com/pricing" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "team:read", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "get-plan", "x-hr-write": false } }, "/api/v2/folders": { "get": { "operationId": "listFolders", "summary": "List folders", "description": "Folders you can open, by name (administrators: every folder of the team; members: the folders they are a member or the owner of). Also works on Pro.", "tags": [ "Folders" ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "folders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } } }, "required": [ "folders" ] }, "example": { "folders": [ { "id": 31, "name": "Legal" }, { "id": 44, "name": "Sales" } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "documents:read", "x-plan": "Pro, Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "list-folders", "x-hr-write": false } }, "/api/v2/folders/{folder_id}": { "get": { "operationId": "getFolder", "summary": "Get a folder", "description": "A folder's name, document count and whether subfolders are on.", "tags": [ "Folders" ], "parameters": [ { "name": "folder_id", "in": "path", "required": true, "description": "Folder id (from List folders).", "schema": { "type": "integer", "minimum": 1 }, "example": 31 } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "documents": { "type": "integer", "description": "Documents in the folder." }, "subfolders_available": { "type": "boolean", "description": "This folder can have subfolders." }, "subfolders_enabled": { "type": "boolean" }, "subfolders_removed": { "type": "integer", "description": "Only after turning subfolders off: how many were removed." } }, "required": [ "id", "name", "documents", "subfolders_available", "subfolders_enabled" ] }, "example": { "id": 31, "name": "Legal", "documents": 16, "subfolders_available": true, "subfolders_enabled": true } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "documents:read", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "get-folder", "x-hr-write": false }, "post": { "operationId": "setFolderSubfolders", "summary": "Turn subfolders on or off", "description": "Subfolders are off by default. Turning them off moves every document back to the top of the folder (nothing is deleted) and deletes the subfolders. Answers with the folder.", "tags": [ "Folders" ], "parameters": [ { "name": "folder_id", "in": "path", "required": true, "description": "Folder id (from List folders).", "schema": { "type": "integer", "minimum": 1 }, "example": 31 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subfolders_enabled": { "type": "boolean", "description": "true to turn subfolders on, false to turn them off." } }, "required": [ "subfolders_enabled" ] }, "example": { "subfolders_enabled": true } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "subfolders_enabled": { "type": "boolean", "description": "true to turn subfolders on, false to turn them off." } }, "required": [ "subfolders_enabled" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "documents": { "type": "integer", "description": "Documents in the folder." }, "subfolders_available": { "type": "boolean", "description": "This folder can have subfolders." }, "subfolders_enabled": { "type": "boolean" }, "subfolders_removed": { "type": "integer", "description": "Only after turning subfolders off: how many were removed." } }, "required": [ "id", "name", "documents", "subfolders_available", "subfolders_enabled" ] }, "example": { "id": 31, "name": "Legal", "documents": 16, "subfolders_available": true, "subfolders_enabled": true } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "documents:write", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "set-folder-subfolders", "x-hr-write": true } }, "/api/v2/folders/{folder_id}/subfolders": { "get": { "operationId": "listSubfolders", "summary": "List subfolders", "description": "Subfolders of a folder with their document counts. Subfolders only group documents – the folder's protection, links and members apply to them unchanged. One level: a subfolder never holds other subfolders.", "tags": [ "Folders" ], "parameters": [ { "name": "folder_id", "in": "path", "required": true, "description": "Folder id (from List folders).", "schema": { "type": "integer", "minimum": 1 }, "example": 31 } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "folder_id": { "type": "integer" }, "folder": { "type": "string" }, "subfolders_available": { "type": "boolean" }, "subfolders_enabled": { "type": "boolean" }, "subfolders": { "type": "array", "items": { "$ref": "#/components/schemas/Subfolder" } }, "documents_at_top": { "type": "integer", "description": "Documents in no subfolder." } }, "required": [ "folder_id", "folder", "subfolders_available", "subfolders_enabled", "subfolders", "documents_at_top" ] }, "example": { "folder_id": 31, "folder": "Legal", "subfolders_available": true, "subfolders_enabled": true, "subfolders": [ { "id": 7, "name": "Contracts", "position": 0, "folder_id": 31, "documents_count": 12 } ], "documents_at_top": 4 } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "documents:read", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "list-subfolders", "x-hr-write": false }, "post": { "operationId": "createSubfolder", "summary": "Create a subfolder", "description": "Creates a subfolder in a folder. Refused with 400 while subfolders are off for the folder (turn them on with Turn subfolders on or off).", "tags": [ "Folders" ], "parameters": [ { "name": "folder_id", "in": "path", "required": true, "description": "Folder id (from List folders).", "schema": { "type": "integer", "minimum": 1 }, "example": 31 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100, "description": "Subfolder name." } }, "required": [ "name" ] }, "example": { "name": "Contracts" } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100, "description": "Subfolder name." } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "position": { "type": "integer" }, "folder_id": { "type": "integer" }, "documents_count": { "type": "integer" }, "folder": { "type": "string" } }, "required": [ "id", "name", "position", "folder_id", "documents_count", "folder" ] }, "example": { "id": 7, "name": "Contracts", "position": 0, "folder_id": 31, "documents_count": 0, "folder": "Legal" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "documents:write", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "create-subfolder", "x-hr-write": true } }, "/api/v2/folders/{folder_id}/subfolders/move": { "post": { "operationId": "moveDocumentsToSubfolder", "summary": "Move documents to a subfolder", "description": "Moves documents of the folder into one of its subfolders, or back to the top of the folder (subfolder_id null or missing). Ids that are not in this folder are listed in not_in_folder.", "tags": [ "Folders" ], "parameters": [ { "name": "folder_id", "in": "path", "required": true, "description": "Folder id (from List folders).", "schema": { "type": "integer", "minimum": 1 }, "example": 31 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "document_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "description": "Documents of this folder (up to 100). Form posts: repeated fields or \"1,2\"." }, "subfolder_id": { "type": [ "integer", "null" ], "description": "A subfolder of this folder; null = the top of the folder." } }, "required": [ "document_ids" ] }, "example": { "document_ids": [ 252, 253 ], "subfolder_id": 7 } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "document_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "description": "Documents of this folder (up to 100). Form posts: repeated fields or \"1,2\"." }, "subfolder_id": { "type": [ "integer", "null" ], "description": "A subfolder of this folder; null = the top of the folder." } }, "required": [ "document_ids" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "moved": { "type": "integer" }, "folder_id": { "type": "integer" }, "subfolder_id": { "type": [ "integer", "null" ] }, "subfolder": { "type": [ "string", "null" ] }, "not_in_folder": { "type": "array", "items": { "type": "integer" } } }, "required": [ "moved", "folder_id", "subfolder_id", "subfolder", "not_in_folder" ] }, "example": { "moved": 2, "folder_id": 31, "subfolder_id": 7, "subfolder": "Contracts", "not_in_folder": [] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "documents:write", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "move-documents-to-subfolder", "x-hr-write": true } }, "/api/v2/subfolders/{subfolder_id}": { "post": { "operationId": "renameSubfolder", "summary": "Rename a subfolder", "description": "Renames a subfolder.", "tags": [ "Folders" ], "parameters": [ { "name": "subfolder_id", "in": "path", "required": true, "description": "Subfolder id (from List subfolders).", "schema": { "type": "integer", "minimum": 1 }, "example": 7 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100, "description": "New name." } }, "required": [ "name" ] }, "example": { "name": "Signed contracts" } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100, "description": "New name." } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "position": { "type": "integer" }, "folder_id": { "type": "integer" }, "folder": { "type": "string" } }, "required": [ "id", "name", "position", "folder_id", "folder" ] }, "example": { "id": 7, "name": "Signed contracts", "position": 0, "folder_id": 31, "folder": "Legal" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "documents:write", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "rename-subfolder", "x-hr-write": true } }, "/api/v2/subfolders/{subfolder_id}/delete": { "post": { "operationId": "deleteSubfolder", "summary": "Delete a subfolder", "description": "Deletes the subfolder only – its documents go back to the top of the folder; no document is deleted.", "tags": [ "Folders" ], "parameters": [ { "name": "subfolder_id", "in": "path", "required": true, "description": "Subfolder id (from List subfolders).", "schema": { "type": "integer", "minimum": 1 }, "example": 7 } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "id": { "type": "integer" }, "folder_id": { "type": "integer" }, "folder": { "type": "string" }, "moved_to_folder": { "type": "integer", "description": "Documents moved back to the top of the folder." } }, "required": [ "deleted", "id", "folder_id", "folder", "moved_to_folder" ] }, "example": { "deleted": true, "id": 7, "folder_id": 31, "folder": "Legal", "moved_to_folder": 12 } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "documents:write", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "delete-subfolder", "x-hr-write": true } }, "/api/v2/documents": { "get": { "operationId": "listDocuments", "summary": "List documents", "description": "Your latest 100 documents, newest first, in folders you can open.", "tags": [ "Documents" ], "parameters": [ { "name": "folder_id", "in": "query", "required": false, "description": "Only documents of this folder.", "schema": { "type": "integer" }, "example": 31 }, { "name": "subfolder", "in": "query", "required": false, "description": "A subfolder id, or \"none\" for documents in no subfolder. subfolder_id is accepted too.", "schema": { "type": "string", "pattern": "^([0-9]+|none)$" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/FileInfo" }, { "$ref": "#/components/schemas/Place" } ] } } }, "required": [ "documents" ] }, "example": { "documents": [ { "id": 250, "name": "proposal.pdf", "folder_id": 31, "type": "document", "pages": 12, "default_link": "https://www.helprange.com/view/471dcc98874d4d0cb7c3eb1874c4e3db/proposal.pdf", "subfolder_id": 7, "subfolder": "Contracts", "path": "Legal › Contracts" } ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "documents:read", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "list-documents", "x-hr-write": false } }, "/api/v2/files": { "post": { "operationId": "uploadFile", "summary": "Upload a file", "description": "Uploads a file into a folder (folder_id, or your default folder). Send the file as multipart \"file\" (recommended), as a public \"file_url\" HelpRange downloads (within 30 seconds), or as \"content_base64\" with \"filename\" in a JSON body. Limit: the team's upload limit, 100 MB per file (larger files only in the panel). Over it: 413 with code FILE_TOO_LARGE or REQUEST_TOO_LARGE; the team's daily upload limit: 429 with code UPLOAD_LIMIT.", "tags": [ "Documents" ], "requestBody": { "required": false, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "description": "The file." }, "folder_id": { "type": "integer" }, "filename": { "type": "string" } }, "required": [ "file" ] } }, "application/json": { "schema": { "type": "object", "properties": { "folder_id": { "type": "integer", "description": "Target folder (default: your default folder)." }, "file_url": { "type": "string", "format": "uri", "description": "A public URL of the file." }, "content_base64": { "type": "string", "description": "The file, base64-encoded." }, "filename": { "type": "string", "description": "File name (default: the uploaded / downloaded name, or document.pdf)." } } }, "example": { "file_url": "https://example.com/proposal.pdf", "folder_id": 31 } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "folder_id": { "type": "integer", "description": "Target folder (default: your default folder)." }, "file_url": { "type": "string", "format": "uri", "description": "A public URL of the file." }, "content_base64": { "type": "string", "description": "The file, base64-encoded." }, "filename": { "type": "string", "description": "File name (default: the uploaded / downloaded name, or document.pdf)." } } } } }, "description": "One of: multipart \"file\", \"file_url\" or \"content_base64\"." }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileInfo" }, "example": { "id": 250, "name": "proposal.pdf", "folder_id": 31, "type": "document", "pages": 12, "default_link": "https://www.helprange.com/view/471dcc98874d4d0cb7c3eb1874c4e3db/proposal.pdf" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "413": { "$ref": "#/components/responses/Error413" }, "423": { "$ref": "#/components/responses/Error423" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "documents:write", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "upload-file", "x-hr-write": true } }, "/api/v2/files/{file_id}/links": { "post": { "operationId": "createLink", "summary": "Create a share link", "description": "A new tracked share link for a document with its own settings. A setting your plan does not include is refused with the plan that has it. Counts towards the daily cap of 2,000 links created through the API.", "tags": [ "Documents" ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "Document id (from List documents).", "schema": { "type": "integer", "minimum": 1 }, "example": 250 } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "description": "Who the link is for, e.g. \"ACME - Anna\" (shown in statistics). Unique per document: a label the document already has is refused with 400. Default: a label with the date and time." }, "allow_download": { "type": [ "boolean", "integer", "string" ], "description": "Allow download & print. Default: blocked on Pro and up, allowed on Free. true / false (also 1 / 0 or \"true\" / \"false\")." }, "passcode": { "type": "string", "description": "Password the viewer must enter (Pro and higher). Surrounding spaces are dropped; only spaces = no passcode. At most 30 characters." }, "expires_on": { "type": "string", "format": "date", "description": "Last day the link works, YYYY-MM-DD (Pro and higher). Today or later – a day in the past or an unreadable date is refused with 400." }, "views_limit": { "type": [ "integer", "null" ], "minimum": 0, "description": "Maximum number of views. 0, null or empty = no limit; a negative or non-whole number is refused with 400." }, "watermark": { "type": [ "boolean", "integer", "string" ], "description": "Watermark pages with the viewer's e-mail and date (Pro and higher). true / false (also 1 / 0 or \"true\" / \"false\")." }, "require_email": { "type": [ "boolean", "integer", "string" ], "description": "Ask for the viewer's e-mail before opening (Pro and higher). true / false (also 1 / 0 or \"true\" / \"false\")." }, "disallow_forwarding": { "type": [ "boolean", "integer", "string" ], "description": "Only the first person who opens it can use it. true / false (also 1 / 0 or \"true\" / \"false\")." }, "one_viewer_at_a_time": { "type": [ "boolean", "integer", "string" ], "description": "Only one person can view at the same time. true / false (also 1 / 0 or \"true\" / \"false\")." } } }, "example": { "label": "ACME - Anna", "passcode": "oak-41", "expires_on": "2026-12-31", "watermark": true, "require_email": true } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "label": { "type": "string", "description": "Who the link is for, e.g. \"ACME - Anna\" (shown in statistics). Unique per document: a label the document already has is refused with 400. Default: a label with the date and time." }, "allow_download": { "type": [ "boolean", "integer", "string" ], "description": "Allow download & print. Default: blocked on Pro and up, allowed on Free. true / false (also 1 / 0 or \"true\" / \"false\")." }, "passcode": { "type": "string", "description": "Password the viewer must enter (Pro and higher). Surrounding spaces are dropped; only spaces = no passcode. At most 30 characters." }, "expires_on": { "type": "string", "format": "date", "description": "Last day the link works, YYYY-MM-DD (Pro and higher). Today or later – a day in the past or an unreadable date is refused with 400." }, "views_limit": { "type": [ "integer", "null" ], "minimum": 0, "description": "Maximum number of views. 0, null or empty = no limit; a negative or non-whole number is refused with 400." }, "watermark": { "type": [ "boolean", "integer", "string" ], "description": "Watermark pages with the viewer's e-mail and date (Pro and higher). true / false (also 1 / 0 or \"true\" / \"false\")." }, "require_email": { "type": [ "boolean", "integer", "string" ], "description": "Ask for the viewer's e-mail before opening (Pro and higher). true / false (also 1 / 0 or \"true\" / \"false\")." }, "disallow_forwarding": { "type": [ "boolean", "integer", "string" ], "description": "Only the first person who opens it can use it. true / false (also 1 / 0 or \"true\" / \"false\")." }, "one_viewer_at_a_time": { "type": [ "boolean", "integer", "string" ], "description": "Only one person can view at the same time. true / false (also 1 / 0 or \"true\" / \"false\")." } } } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ShareLink" }, { "type": "object", "properties": { "document_id": { "type": "integer" }, "document": { "type": "string" } }, "required": [ "document_id", "document" ] } ] }, "example": { "id": 264, "url": "https://www.helprange.com/view/8956d1e7b91b47e196a8040b1d4894f8/proposal.pdf", "label": "ACME - Anna", "allow_download": false, "passcode": true, "expires_on": "2026-12-31", "views_limit": null, "watermark": true, "require_email": true, "disallow_forwarding": false, "one_viewer_at_a_time": false, "document_id": 250, "document": "proposal.pdf" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "links:write", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "create-link", "x-hr-write": true } }, "/api/v2/documents/{file_id}": { "get": { "operationId": "getDocument", "summary": "Document statistics", "description": "Views, downloads, total reading time, average seconds per page and the latest views (who, when, how long) of one document.", "tags": [ "Documents" ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "Document id (from List documents).", "schema": { "type": "integer", "minimum": 1 }, "example": 250 }, { "name": "recent_views", "in": "query", "required": false, "description": "How many latest views to return, 1–100 (default 20).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "example": 5 } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" }, "pages": { "type": [ "integer", "null" ] }, "views": { "type": "integer" }, "downloads": { "type": "integer" }, "total_seconds_read": { "type": [ "integer", "null" ] }, "last_viewed_at": { "type": [ "string", "null" ], "format": "date-time" }, "share_link": { "type": [ "string", "null" ], "format": "uri" }, "avg_seconds_per_page": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "page": { "type": "integer" }, "avg_seconds": { "type": "integer" } }, "required": [ "page", "avg_seconds" ] } }, "recent_views": { "type": "array", "items": { "$ref": "#/components/schemas/View" } }, "folder_id": { "type": "integer" }, "folder": { "type": "string" }, "subfolder_id": { "type": [ "integer", "null" ] }, "subfolder": { "type": [ "string", "null" ] }, "path": { "type": "string" } }, "required": [ "id", "name", "type", "pages", "views", "downloads", "total_seconds_read", "last_viewed_at", "share_link", "avg_seconds_per_page", "recent_views", "folder_id", "folder", "subfolder_id", "subfolder", "path" ] }, "example": { "id": 250, "name": "proposal.pdf", "type": "document", "pages": 12, "views": 39, "downloads": 2, "total_seconds_read": 1830, "last_viewed_at": "2026-11-09T14:02:11+00:00", "share_link": "https://www.helprange.com/view/471dcc98874d4d0cb7c3eb1874c4e3db/proposal.pdf", "avg_seconds_per_page": [ { "page": 1, "avg_seconds": 21 }, { "page": 2, "avg_seconds": 64 } ], "recent_views": [ { "viewer": "anna@client.com", "opened_at": "2026-11-09T14:02:11+00:00", "seconds_read": 312, "country": "DE", "downloaded": false, "document": "proposal.pdf", "document_id": 250 } ], "folder_id": 31, "folder": "Legal", "subfolder_id": null, "subfolder": null, "path": "Legal" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "documents:read", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "get-document", "x-hr-write": false } }, "/api/v2/documents/{file_id}/links": { "get": { "operationId": "listDocumentLinks", "summary": "List share links of a document", "description": "Every share link of a document with its settings.", "tags": [ "Documents" ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "Document id (from List documents).", "schema": { "type": "integer", "minimum": 1 }, "example": 250 } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "document": { "type": "string" }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/ShareLink" } } }, "required": [ "document", "links" ] }, "example": { "document": "proposal.pdf", "links": [ { "id": 264, "url": "https://www.helprange.com/view/8956d1e7b91b47e196a8040b1d4894f8/proposal.pdf", "label": "ACME - Anna", "allow_download": false, "passcode": true, "expires_on": "2026-12-31", "views_limit": null, "watermark": true, "require_email": true, "disallow_forwarding": false, "one_viewer_at_a_time": false } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "links:read", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "list-document-links", "x-hr-write": false } }, "/api/v2/views": { "get": { "operationId": "listRecentViews", "summary": "Recent document views", "description": "Polling trigger \"New document view\": the latest 50 views of documents in your folders, newest first. Each item has a stable id (de-duplicate by it). The response is a JSON array.", "tags": [ "Triggers" ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "opened_at": { "type": "string", "format": "date-time" }, "viewer": { "type": "string" }, "document_id": { "type": "integer" }, "document": { "type": "string" }, "link_label": { "type": "string", "description": "\"default\" for the default link." }, "seconds_read": { "type": [ "integer", "null" ] }, "country": { "type": [ "string", "null" ] }, "downloaded": { "type": "boolean" } }, "required": [ "id", "opened_at", "viewer", "document_id", "document", "link_label", "seconds_read", "country", "downloaded" ] } }, "example": [ { "id": 98321, "opened_at": "2026-11-15T09:12:40+00:00", "viewer": "anna@client.com", "document_id": 250, "document": "proposal.pdf", "link_label": "ACME - Anna", "seconds_read": 312, "country": "DE", "downloaded": false } ] } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "analytics:read", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "list-recent-views", "x-hr-write": false } }, "/api/v2/uploads": { "get": { "operationId": "listRecentUploads", "summary": "Recent client uploads", "description": "Polling trigger \"New file from a client\": the latest 50 files uploaded through file requests and data room guest uploads, newest first. id is the upload's id; document_id the uploaded document. The response is a JSON array.", "tags": [ "Triggers" ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/FileInfo" }, { "type": "object", "properties": { "document_id": { "type": "integer" }, "uploaded_by": { "type": [ "string", "null" ] }, "uploaded_by_name": { "type": [ "string", "null" ] }, "uploaded_at": { "type": "string", "format": "date-time" } }, "required": [ "document_id", "uploaded_by", "uploaded_by_name", "uploaded_at" ] } ] } }, "example": [ { "id": 512, "name": "signed-loi.pdf", "folder_id": 31, "type": "document", "pages": 12, "default_link": "https://www.helprange.com/view/471dcc98874d4d0cb7c3eb1874c4e3db/proposal.pdf", "document_id": 270, "uploaded_by": "bob@fund.com", "uploaded_by_name": "Bob Buyer", "uploaded_at": "2026-11-15T08:01:00+00:00" } ] } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "documents:read", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "list-recent-uploads", "x-hr-write": false } }, "/api/v2/folders/{folder_id}/buyers": { "post": { "operationId": "grantBuyerAccess", "summary": "Give a buyer access", "description": "Gives a buyer access to a product folder (any shop: Teachable, Thinkific, Shopify …): a personal protected link by e-mail for the folder's access length, the buyer id in the watermark. The buyer gets one e-mail (counted in the team's API e-mail budget). 201 for a new buyer, 200 when they already had access. Also works on Pro.", "tags": [ "Store" ], "parameters": [ { "name": "folder_id", "in": "path", "required": true, "description": "Folder id (from List folders).", "schema": { "type": "integer", "minimum": 1 }, "example": 31 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The buyer's e-mail." }, "buyer_id": { "type": "string", "description": "Your own buyer / order id, shown in the watermark (optional)." } }, "required": [ "email" ] }, "example": { "email": "buyer@example.com", "buyer_id": "order-1042" } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The buyer's e-mail." }, "buyer_id": { "type": "string", "description": "Your own buyer / order id, shown in the watermark (optional)." } }, "required": [ "email" ] } } } }, "responses": { "201": { "description": "Created (200: existing buyer)", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "folder_id": { "type": "integer" }, "folder": { "type": "string" }, "new_buyer": { "type": "boolean" }, "access_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "email", "folder_id", "folder", "new_buyer", "access_ends_at" ] }, "example": { "id": "31-buyer@example.com", "email": "buyer@example.com", "folder_id": 31, "folder": "Market report", "new_buyer": true, "access_ends_at": null } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "links:write", "x-plan": "Pro, Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "grant-buyer-access", "x-hr-write": true } }, "/api/v2/folders/{folder_id}/buyers/remove": { "post": { "operationId": "revokeBuyerAccess", "summary": "Remove a buyer's access", "description": "Takes a buyer's access to a product folder away. Also works on Pro.", "tags": [ "Store" ], "parameters": [ { "name": "folder_id", "in": "path", "required": true, "description": "Folder id (from List folders).", "schema": { "type": "integer", "minimum": 1 }, "example": 31 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The buyer's e-mail." } }, "required": [ "email" ] }, "example": { "email": "buyer@example.com" } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The buyer's e-mail." } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "folder_id": { "type": "integer" }, "folder": { "type": "string" }, "removed": { "type": "boolean", "description": "false when they had no access." } }, "required": [ "id", "email", "folder_id", "folder", "removed" ] }, "example": { "id": "31-buyer@example.com", "email": "buyer@example.com", "folder_id": 31, "folder": "Market report", "removed": true } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "links:write", "x-plan": "Pro, Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "revoke-buyer-access", "x-hr-write": true } }, "/api/v2/store/sales": { "get": { "operationId": "listStoreSales", "summary": "Store products and sales", "description": "Store products with Stripe sales and revenue, and the latest Stripe purchases (members: products of their folders).", "tags": [ "Store" ], "parameters": [ { "name": "product_id", "in": "query", "required": false, "description": "Only this product.", "schema": { "type": "integer" } }, { "name": "days", "in": "query", "required": false, "description": "Purchases of the last N days, 1–3650 (default 90).", "schema": { "type": "integer", "minimum": 1, "maximum": 3650 } }, { "name": "limit", "in": "query", "required": false, "description": "Purchases to return, 1–200 (default 50).", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "price": { "type": "number" }, "currency": { "type": "string" }, "subscription": { "type": "boolean" }, "published": { "type": "boolean" }, "sales": { "type": "integer" }, "revenue": { "type": "number" }, "buyers_with_access": { "type": "integer" } }, "required": [ "id", "name", "kind", "price", "currency", "subscription", "published", "sales", "revenue", "buyers_with_access" ] } }, "purchases": { "type": "array", "items": { "type": "object", "properties": { "product": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" }, "company": { "type": "string" }, "paid": { "type": "string" }, "subscription_active": { "type": [ "boolean", "null" ] }, "at": { "type": "string", "format": "date-time" } }, "required": [ "product", "email", "name", "company", "paid", "subscription_active", "at" ] } } }, "required": [ "products", "purchases" ] }, "example": { "products": [ { "id": 4, "name": "Market report 2026", "kind": "folder", "price": 49.0, "currency": "EUR", "subscription": false, "published": true, "sales": 18, "revenue": 882.0, "buyers_with_access": 18 } ], "purchases": [ { "product": "Market report 2026", "email": "buyer@x.com", "name": "Bo Buyer", "company": "", "paid": "€49.00", "subscription_active": null, "at": "2026-11-10T11:00:00+00:00" } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "analytics:read", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "list-store-sales", "x-hr-write": false } }, "/api/v2/landing-templates": { "get": { "operationId": "listLandingTemplates", "summary": "List lead magnet forms", "description": "Lead magnet / landing page forms of the team; folders are the folders (you can open) that use the form.", "tags": [ "Lead forms" ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "landing_templates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string", "enum": [ "email", "first_name", "last_name", "company", "phone" ] } }, "required_fields": { "type": "array", "items": { "type": "string", "enum": [ "email", "first_name", "last_name", "company" ] } }, "email_verification": { "type": "boolean" }, "consent": { "type": "boolean" }, "folders": { "type": "array", "items": { "type": "integer" } } }, "required": [ "id", "name", "title", "description", "fields", "required_fields", "email_verification", "consent", "folders" ] } } }, "required": [ "landing_templates" ] }, "example": { "landing_templates": [ { "id": 8, "name": "Whitepaper gate", "title": "Get the 2026 report", "description": "", "fields": [ "email", "company" ], "required_fields": [ "email" ], "email_verification": true, "consent": true, "folders": [ 31 ] } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "links:read", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "list-landing-templates", "x-hr-write": false } }, "/api/v2/activity": { "get": { "operationId": "listActivity", "summary": "Team activity", "description": "The Activity feed, newest first: views, new links, data room events, offers, e-signature, store purchases, uploads and (administrators) team events. Members see events of their own documents. Page back with before=next_before.", "tags": [ "Activity" ], "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Only one kind of event (\"team\": administrators only).", "schema": { "type": "string", "enum": [ "views", "sharing", "rooms", "offers", "esign", "store", "uploads", "team" ] }, "example": "esign" }, { "name": "limit", "in": "query", "required": false, "description": "1–200 (default 30).", "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "example": 2 }, { "name": "before", "in": "query", "required": false, "description": "Only events before this time: next_before of the previous page.", "schema": { "type": "string" } }, { "name": "member_id", "in": "query", "required": false, "description": "Administrators: only this team member's events.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time" }, "type": { "type": "string" }, "text": { "type": "string" }, "detail": { "type": "string" }, "url": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "at", "type", "text", "detail", "url" ] } }, "more": { "type": "boolean" }, "next_before": { "type": [ "string", "null" ] } }, "required": [ "events", "more", "next_before" ] }, "example": { "events": [ { "at": "2026-11-10T09:12:40+00:00", "type": "esign", "text": "anna@client.com signed \"NDA\"", "detail": "", "url": "https://www.helprange.com/user/signature-doc?signatureId=9f1c2e7a4b" } ], "more": true, "next_before": "2026-11-10T09:12:40.123456+00:00" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "analytics:read", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "list-activity", "x-hr-write": false } }, "/api/v2/signature-requests": { "get": { "operationId": "listSignatureRequests", "summary": "List e-signature requests", "description": "E-signature requests – administrators see the whole team, members the ones they created or sent – newest first.", "tags": [ "E-signature" ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Only this status.", "schema": { "type": "string", "enum": [ "draft", "sent", "expired", "completed", "declined", "voided" ] }, "example": "sent" }, { "name": "query", "in": "query", "required": false, "description": "Words in the title or a recipient's name / e-mail.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "1–200 (default 50).", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "signature_requests": { "type": "array", "items": { "$ref": "#/components/schemas/Envelope" } } }, "required": [ "signature_requests" ] }, "example": { "signature_requests": [ { "id": "9f1c2e7a4b", "title": "Mutual NDA", "status": "sent", "status_label": "Sent", "sender": "Ann Admin", "document_id": 250, "data_room": null, "created_at": "2026-11-10T08:00:00+00:00", "sent_at": "2026-11-10T08:00:02+00:00", "expires_at": "2026-12-10T22:59:59+00:00", "completed_at": null, "ended_at": null, "signed": 0, "recipients_count": 2, "url": "https://www.helprange.com/user/signature-doc?signatureId=9f1c2e7a4b" } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "documents:read", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "list-signature-requests", "x-hr-write": false }, "post": { "operationId": "createSignatureRequest", "summary": "Send a document for e-signature", "description": "Sends a document from a folder you can open for e-signature (plans with e-signature). A signature page with a block per signer is added at the end; every recipient gets an e-mail with a signing link (counted in the team's API e-mail budget). Form posts can pass repeated signer_email fields instead of signers.", "tags": [ "E-signature" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "document_id": { "type": "integer", "description": "A document in a folder you can open." }, "signers": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "action": { "type": "string", "enum": [ "sign", "review" ] } }, "required": [ "email" ] }, "description": "Recipients in signing order." }, "title": { "type": "string", "description": "Default: the file name." }, "message": { "type": "string", "description": "Shown in the e-mail." }, "sequential": { "type": "boolean", "description": "true: sign one after another." }, "expires_on": { "type": "string", "format": "date", "description": "YYYY-MM-DD (default: 30 days)." } }, "required": [ "document_id", "signers" ] }, "example": { "document_id": 250, "title": "Mutual NDA", "signers": [ { "name": "Anna Client", "email": "anna@client.com" }, { "name": "Legal", "email": "legal@client.com", "action": "review" } ], "sequential": true } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "document_id": { "type": "integer", "description": "A document in a folder you can open." }, "signers": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "action": { "type": "string", "enum": [ "sign", "review" ] } }, "required": [ "email" ] }, "description": "Recipients in signing order." }, "title": { "type": "string", "description": "Default: the file name." }, "message": { "type": "string", "description": "Shown in the e-mail." }, "sequential": { "type": "boolean", "description": "true: sign one after another." }, "expires_on": { "type": "string", "format": "date", "description": "YYYY-MM-DD (default: 30 days)." } }, "required": [ "document_id", "signers" ] } } } }, "responses": { "201": { "description": "Created and sent", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "sent": { "type": "boolean" } }, "required": [ "sent" ] } ] }, "example": { "id": "9f1c2e7a4b", "title": "Mutual NDA", "status": "sent", "status_label": "Sent", "sender": "Ann Admin", "document_id": 250, "data_room": null, "created_at": "2026-11-10T08:00:00+00:00", "sent_at": "2026-11-10T08:00:02+00:00", "expires_at": "2026-12-10T22:59:59+00:00", "completed_at": null, "ended_at": null, "signed": 0, "recipients_count": 2, "url": "https://www.helprange.com/user/signature-doc?signatureId=9f1c2e7a4b", "sent": true } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "documents:write", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "create-signature-request", "x-hr-write": true } }, "/api/v2/signature-requests/{envelope_id}": { "get": { "operationId": "getSignatureRequest", "summary": "E-signature request details", "description": "One request with each recipient's status and the audit trail.", "tags": [ "E-signature" ], "parameters": [ { "name": "envelope_id", "in": "path", "required": true, "description": "E-signature request id (from List e-signature requests).", "schema": { "type": "string", "pattern": "^[0-9a-zA-Z_-]+$" }, "example": "9f1c2e7a4b" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "message": { "type": "string" }, "sequential": { "type": "boolean" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "sign", "review" ] }, "order": { "type": "integer" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "can_act_now": { "type": "boolean" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "name", "email", "role", "order", "status", "status_label", "can_act_now", "completed_at" ] } }, "events": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time" }, "kind": { "type": "string" }, "label": { "type": "string" }, "recipient": { "type": [ "string", "null" ] } }, "required": [ "at", "kind", "label", "recipient" ] } }, "signed_pdf_available": { "type": "boolean" } }, "required": [ "message", "sequential", "recipients", "events", "signed_pdf_available" ] } ] }, "example": { "id": "9f1c2e7a4b", "title": "Mutual NDA", "status": "sent", "status_label": "Sent", "sender": "Ann Admin", "document_id": 250, "data_room": null, "created_at": "2026-11-10T08:00:00+00:00", "sent_at": "2026-11-10T08:00:02+00:00", "expires_at": "2026-12-10T22:59:59+00:00", "completed_at": null, "ended_at": null, "signed": 0, "recipients_count": 2, "url": "https://www.helprange.com/user/signature-doc?signatureId=9f1c2e7a4b", "message": "", "sequential": true, "recipients": [ { "name": "Anna Client", "email": "anna@client.com", "role": "sign", "order": 1, "status": "viewed", "status_label": "Viewed", "can_act_now": true, "completed_at": null } ], "events": [ { "at": "2026-11-10T08:00:00+00:00", "kind": "created", "label": "Created", "recipient": null }, { "at": "2026-11-10T08:05:13+00:00", "kind": "opened", "label": "Opened", "recipient": "anna@client.com" } ], "signed_pdf_available": false } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "documents:read", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "get-signature-request", "x-hr-write": false } }, "/api/v2/signature-requests/{envelope_id}/remind": { "post": { "operationId": "remindSignatureRequest", "summary": "Remind signers", "description": "E-mails a reminder to the recipients who still have to act – at most once an hour per request (400 otherwise).", "tags": [ "E-signature" ], "parameters": [ { "name": "envelope_id", "in": "path", "required": true, "description": "E-signature request id (from List e-signature requests).", "schema": { "type": "string", "pattern": "^[0-9a-zA-Z_-]+$" }, "example": "9f1c2e7a4b" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "reminded": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "reminded" ] }, "example": { "id": "9f1c2e7a4b", "reminded": [ "anna@client.com" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "documents:write", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "remind-signature-request", "x-hr-write": true } }, "/api/v2/signature-requests/{envelope_id}/void": { "post": { "operationId": "voidSignatureRequest", "summary": "Void an e-signature request", "description": "Cancels a sent request: nobody can sign it any more and the waiting recipients are told. Cannot be undone.", "tags": [ "E-signature" ], "parameters": [ { "name": "envelope_id", "in": "path", "required": true, "description": "E-signature request id (from List e-signature requests).", "schema": { "type": "string", "pattern": "^[0-9a-zA-Z_-]+$" }, "example": "9f1c2e7a4b" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Optional, shown to the waiting recipients." } } }, "example": { "reason": "Wrong version" } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Optional, shown to the waiting recipients." } } } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "id": "9f1c2e7a4b", "title": "Mutual NDA", "status": "voided", "status_label": "Voided", "sender": "Ann Admin", "document_id": 250, "data_room": null, "created_at": "2026-11-10T08:00:00+00:00", "sent_at": "2026-11-10T08:00:02+00:00", "expires_at": "2026-12-10T22:59:59+00:00", "completed_at": null, "ended_at": "2026-11-11T10:00:00+00:00", "signed": 0, "recipients_count": 2, "url": "https://www.helprange.com/user/signature-doc?signatureId=9f1c2e7a4b" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "documents:write", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "void-signature-request", "x-hr-write": true } }, "/api/v2/signature-requests/{envelope_id}/signed-pdf": { "get": { "operationId": "getSignedPdf", "summary": "Signed PDF link", "description": "Download link of the signed PDF with the certificate of completion. 409 while not everyone has signed. Requests signed before 2026-11-10 answer with a panel link and a note instead.", "tags": [ "E-signature" ], "parameters": [ { "name": "envelope_id", "in": "path", "required": true, "description": "E-signature request id (from List e-signature requests).", "schema": { "type": "string", "pattern": "^[0-9a-zA-Z_-]+$" }, "example": "9f1c2e7a4b" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "valid_days": { "type": "integer" }, "sha256": { "type": [ "string", "null" ] }, "sealed": { "type": "boolean" }, "note": { "type": "string" } }, "required": [ "id", "url" ] }, "example": { "id": "9f1c2e7a4b", "url": "https://www.helprange.com/esign/download/eyJ0.../", "valid_days": 30, "sha256": "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8", "sealed": true } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "documents:read", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "get-signed-pdf", "x-hr-write": false } }, "/api/v2/data-rooms": { "get": { "operationId": "listDataRooms", "summary": "List data rooms", "description": "Data rooms with guest and document counts (administrators: every room; members: the rooms they created).", "tags": [ "Data rooms" ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data_rooms": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "guests": { "type": "integer" }, "documents": { "type": "integer" }, "pending_access_requests": { "type": "integer" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "frozen": { "type": "boolean" }, "index_numbering": { "type": "boolean" }, "folders_enabled": { "type": "boolean" } }, "required": [ "id", "name", "guests", "documents", "pending_access_requests", "expires_at", "frozen", "index_numbering", "folders_enabled" ] } } }, "required": [ "data_rooms" ] }, "example": { "data_rooms": [ { "id": 10, "name": "Project Falcon", "guests": 4, "documents": 37, "pending_access_requests": 1, "expires_at": null, "frozen": false, "index_numbering": true, "folders_enabled": true } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "rooms:read", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "list-data-rooms", "x-hr-write": false } }, "/api/v2/data-rooms/{data_room_id}": { "get": { "operationId": "getDataRoom", "summary": "Data room details", "description": "Guests (views, last visit, NDA status), documents, freeze status with closing archives, and Q&A counts.", "tags": [ "Data rooms" ], "parameters": [ { "name": "data_room_id", "in": "path", "required": true, "description": "Data room id (from List data rooms).", "schema": { "type": "integer", "minimum": 1 }, "example": 10 } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nda_required": { "type": [ "string", "null" ], "description": "Name of the NDA guests accept, or null." }, "folders_enabled": { "type": "boolean" }, "approval_workflow": { "type": "boolean" }, "guests": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "views": { "type": "integer" }, "last_view_at": { "type": [ "string", "null" ], "format": "date-time" }, "nda": { "type": "string", "enum": [ "signed", "signed an older version", "not signed" ] }, "nda_signed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "email", "views", "last_view_at" ] } }, "pending_access_requests": { "type": "integer" }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "views": { "type": "integer" }, "room_link_id": { "type": "integer" }, "room_folder_id": { "type": [ "integer", "null" ] }, "room_folder": { "type": [ "string", "null" ] }, "group": { "type": [ "string", "null" ] }, "approval": { "type": "string", "enum": [ "published", "pending", "changes" ] } }, "required": [ "id", "name", "views", "room_link_id", "room_folder_id", "room_folder", "group", "approval" ] } }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "index_numbering": { "type": "boolean" }, "freeze": { "type": "object", "properties": { "frozen": { "type": "boolean" }, "guest_access": { "type": "string" }, "frozen_at": { "type": [ "string", "null" ], "format": "date-time" }, "archives": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "files": { "type": "integer" }, "size": { "type": [ "integer", "null" ] }, "sha256": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "download_url": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "id", "status", "files", "size", "sha256", "created_at", "finished_at", "download_url" ] } } }, "required": [ "frozen", "guest_access", "frozen_at", "archives" ] }, "qa": { "type": "object", "properties": { "available": { "type": "boolean" }, "open_questions": { "type": "integer" }, "questions": { "type": "integer" }, "request_items": { "type": "integer" }, "guests_can_ask": { "type": "boolean" }, "answers_need_approval": { "type": "boolean" }, "guests_see_request_list": { "type": "boolean" } }, "required": [ "available", "open_questions", "questions", "request_items", "guests_can_ask", "answers_need_approval", "guests_see_request_list" ] } }, "required": [ "id", "name", "nda_required", "folders_enabled", "approval_workflow", "guests", "pending_access_requests", "documents", "expires_at", "index_numbering", "freeze", "qa" ] }, "example": { "id": 10, "name": "Project Falcon", "nda_required": "Falcon NDA", "folders_enabled": true, "approval_workflow": false, "guests": [ { "email": "buyer@bidco.com", "views": 23, "last_view_at": "2026-11-09T17:40:00+00:00", "nda": "signed", "nda_signed_at": "2026-11-02T10:00:00+00:00" } ], "pending_access_requests": 1, "documents": [ { "id": 250, "name": "teaser.pdf", "views": 11, "room_link_id": 901, "room_folder_id": null, "room_folder": null, "group": null, "approval": "published" } ], "expires_at": null, "index_numbering": true, "freeze": { "frozen": false, "guest_access": "full", "frozen_at": null, "archives": [] }, "qa": { "available": true, "open_questions": 3, "questions": 12, "request_items": 40, "guests_can_ask": true, "answers_need_approval": false, "guests_see_request_list": true } } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "rooms:read", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "get-data-room", "x-hr-write": false }, "post": { "operationId": "setDataRoomFolders", "summary": "Turn data room folders on or off", "description": "Folders inside a data room are off by default. Turning them off deletes the room's folders; their documents stay in the room at the top level. Answers with the room.", "tags": [ "Data rooms" ], "parameters": [ { "name": "data_room_id", "in": "path", "required": true, "description": "Data room id (from List data rooms).", "schema": { "type": "integer", "minimum": 1 }, "example": 10 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "folders_enabled": { "type": "boolean", "description": "true to turn folders on, false to turn them off." } }, "required": [ "folders_enabled" ] }, "example": { "folders_enabled": true } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "folders_enabled": { "type": "boolean", "description": "true to turn folders on, false to turn them off." } }, "required": [ "folders_enabled" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nda_required": { "type": [ "string", "null" ], "description": "Name of the NDA guests accept, or null." }, "folders_enabled": { "type": "boolean" }, "approval_workflow": { "type": "boolean" }, "guests": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "views": { "type": "integer" }, "last_view_at": { "type": [ "string", "null" ], "format": "date-time" }, "nda": { "type": "string", "enum": [ "signed", "signed an older version", "not signed" ] }, "nda_signed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "email", "views", "last_view_at" ] } }, "pending_access_requests": { "type": "integer" }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "views": { "type": "integer" }, "room_link_id": { "type": "integer" }, "room_folder_id": { "type": [ "integer", "null" ] }, "room_folder": { "type": [ "string", "null" ] }, "group": { "type": [ "string", "null" ] }, "approval": { "type": "string", "enum": [ "published", "pending", "changes" ] } }, "required": [ "id", "name", "views", "room_link_id", "room_folder_id", "room_folder", "group", "approval" ] } }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "index_numbering": { "type": "boolean" }, "freeze": { "type": "object", "properties": { "frozen": { "type": "boolean" }, "guest_access": { "type": "string" }, "frozen_at": { "type": [ "string", "null" ], "format": "date-time" }, "archives": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "files": { "type": "integer" }, "size": { "type": [ "integer", "null" ] }, "sha256": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "download_url": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "id", "status", "files", "size", "sha256", "created_at", "finished_at", "download_url" ] } } }, "required": [ "frozen", "guest_access", "frozen_at", "archives" ] }, "qa": { "type": "object", "properties": { "available": { "type": "boolean" }, "open_questions": { "type": "integer" }, "questions": { "type": "integer" }, "request_items": { "type": "integer" }, "guests_can_ask": { "type": "boolean" }, "answers_need_approval": { "type": "boolean" }, "guests_see_request_list": { "type": "boolean" } }, "required": [ "available", "open_questions", "questions", "request_items", "guests_can_ask", "answers_need_approval", "guests_see_request_list" ] } }, "required": [ "id", "name", "nda_required", "folders_enabled", "approval_workflow", "guests", "pending_access_requests", "documents", "expires_at", "index_numbering", "freeze", "qa" ] }, "example": { "id": 10, "name": "Project Falcon", "nda_required": "Falcon NDA", "folders_enabled": true, "approval_workflow": false, "guests": [ { "email": "buyer@bidco.com", "views": 23, "last_view_at": "2026-11-09T17:40:00+00:00", "nda": "signed", "nda_signed_at": "2026-11-02T10:00:00+00:00" } ], "pending_access_requests": 1, "documents": [ { "id": 250, "name": "teaser.pdf", "views": 11, "room_link_id": 901, "room_folder_id": null, "room_folder": null, "group": null, "approval": "published" } ], "expires_at": null, "index_numbering": true, "freeze": { "frozen": false, "guest_access": "full", "frozen_at": null, "archives": [] }, "qa": { "available": true, "open_questions": 3, "questions": 12, "request_items": 40, "guests_can_ask": true, "answers_need_approval": false, "guests_see_request_list": true } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "rooms:write", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "set-data-room-folders", "x-hr-write": true } }, "/api/v2/data-rooms/{data_room_id}/index": { "get": { "operationId": "getDataRoomIndex", "summary": "Data room index", "description": "The room's numbered index (1, 1.1 …) in the structure guests see – always one level of folders. With room folders on, folder nodes are the room's folders (room_folder_id); otherwise, with \"Show Folders\" on, the folder the documents come from (folder_id, plus subfolder_id for \"Folder / Subfolder\"). The numbers exist even while numbering is off for guests (index_numbering false).", "tags": [ "Data rooms" ], "parameters": [ { "name": "data_room_id", "in": "path", "required": true, "description": "Data room id (from List data rooms).", "schema": { "type": "integer", "minimum": 1 }, "example": 10 } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data_room_id": { "type": "integer" }, "index_numbering": { "type": "boolean" }, "index": { "type": "array", "items": { "$ref": "#/components/schemas/IndexNode" } } }, "required": [ "data_room_id", "index_numbering", "index" ] }, "example": { "data_room_id": 10, "index_numbering": true, "index": [ { "type": "folder", "number": "1", "name": "Financials", "folder_id": null, "room_folder_id": 5, "children": [ { "type": "document", "number": "1.1", "name": "pnl.xlsx", "document_id": 260, "room_link_id": 910, "room_folder_id": 5 } ] }, { "type": "document", "number": "2", "name": "teaser.pdf", "document_id": 250, "room_link_id": 901, "room_folder_id": null } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "rooms:read", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "get-data-room-index", "x-hr-write": false } }, "/api/v2/data-rooms/{data_room_id}/guests": { "post": { "operationId": "inviteDataRoomGuest", "summary": "Invite a guest", "description": "Like \"Add guest\" in the panel: the invitation e-mail goes out when the room sends e-mail notifications and has a document. 201 for a new guest, 200 when they already are one, 409 when the room is frozen. Counts towards the daily cap of 1,000 guests and the API e-mail budget.", "tags": [ "Data rooms" ], "parameters": [ { "name": "data_room_id", "in": "path", "required": true, "description": "Data room id (from List data rooms).", "schema": { "type": "integer", "minimum": 1 }, "example": 10 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The guest's e-mail address." } }, "required": [ "email" ] }, "example": { "email": "buyer@bidco.com" } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The guest's e-mail address." } }, "required": [ "email" ] } } } }, "responses": { "201": { "description": "Created (200: already a guest)", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "data_room_id": { "type": "integer" }, "invited": { "type": "boolean" }, "already_a_guest": { "type": "boolean" } }, "required": [ "id", "email", "data_room_id", "invited", "already_a_guest" ] }, "example": { "id": 77, "email": "buyer@bidco.com", "data_room_id": 10, "invited": true, "already_a_guest": false } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "rooms:write", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "invite-data-room-guest", "x-hr-write": true } }, "/api/v2/data-rooms/{data_room_id}/access-requests": { "get": { "operationId": "listDataRoomAccessRequests", "summary": "Access requests", "description": "People who asked to join the room. Approve or deny them on the data room page.", "tags": [ "Data rooms" ], "parameters": [ { "name": "data_room_id", "in": "path", "required": true, "description": "Data room id (from List data rooms).", "schema": { "type": "integer", "minimum": 1 }, "example": 10 }, { "name": "status", "in": "query", "required": false, "description": "Default pending.", "schema": { "type": "string", "enum": [ "pending", "approved", "denied", "all" ] } }, { "name": "limit", "in": "query", "required": false, "description": "1–200 (default 50).", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "access_requests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "data_room_id": { "type": "integer" }, "data_room": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "company": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "string" }, "requested_at": { "type": "string", "format": "date-time" }, "decided_at": { "type": [ "string", "null" ], "format": "date-time" }, "review_url": { "type": "string", "format": "uri" } }, "required": [ "id", "data_room_id", "data_room", "name", "email", "company", "message", "status", "requested_at", "decided_at", "review_url" ] } } }, "required": [ "access_requests" ] }, "example": { "access_requests": [ { "id": 5, "data_room_id": 10, "data_room": "Project Falcon", "name": "Bob Buyer", "email": "bob@fund.com", "company": "Fund LP", "message": "We are bidding.", "status": "pending", "requested_at": "2026-11-10T07:00:00+00:00", "decided_at": null, "review_url": "https://www.helprange.com/user/outside-team/10/" } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "rooms:read", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "list-data-room-access-requests", "x-hr-write": false } }, "/api/v2/data-rooms/{data_room_id}/signature-requests": { "get": { "operationId": "listDataRoomSignatureRequests", "summary": "Data room signature requests", "description": "Documents of the room sent to guests for signature, with each signer's status.", "tags": [ "Data rooms" ], "parameters": [ { "name": "data_room_id", "in": "path", "required": true, "description": "Data room id (from List data rooms).", "schema": { "type": "integer", "minimum": 1 }, "example": 10 } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data_room": { "type": "string" }, "signature_requests": { "type": "array", "items": { "type": "object", "properties": { "envelope_id": { "type": "string" }, "document": { "type": "string" }, "document_id": { "type": "integer" }, "status": { "type": "string" }, "summary": { "type": "string" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "due": { "type": [ "string", "null" ], "format": "date-time" }, "signers": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "status": { "type": "string" }, "signed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "email", "status", "signed_at" ] } } }, "required": [ "envelope_id", "document", "document_id", "status", "summary", "sent_at", "due", "signers" ] } } }, "required": [ "data_room", "signature_requests" ] }, "example": { "data_room": "Project Falcon", "signature_requests": [ { "envelope_id": "9f1c2e7a4b", "document": "spa.pdf", "document_id": 260, "status": "sent", "summary": "1 of 2 signed", "sent_at": "2026-11-10T08:00:02+00:00", "due": null, "signers": [ { "email": "buyer@bidco.com", "status": "signed", "signed_at": "2026-11-10T09:00:00+00:00" } ] } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "rooms:read", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "list-data-room-signature-requests", "x-hr-write": false } }, "/api/v2/data-rooms/{data_room_id}/questions": { "get": { "operationId": "listDataRoomQuestions", "summary": "List Q&A questions", "description": "Questions of the room's Q&A, newest first. Q&A and request lists need the Max or Unlimited plan, the Deal Room Pass or the trial (else 402).", "tags": [ "Data rooms" ], "parameters": [ { "name": "data_room_id", "in": "path", "required": true, "description": "Data room id (from List data rooms).", "schema": { "type": "integer", "minimum": 1 }, "example": 10 }, { "name": "status", "in": "query", "required": false, "description": "Default all. answered = waiting for approval.", "schema": { "type": "string", "enum": [ "all", "open", "published", "new", "assigned", "answered", "approved", "declined" ] }, "example": "open" }, { "name": "category", "in": "query", "required": false, "description": "Only this category.", "schema": { "type": "string", "enum": [ "legal", "financial", "tax", "hr", "commercial", "it", "other" ] } }, { "name": "limit", "in": "query", "required": false, "description": "1–500 (default 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data_room_id": { "type": "integer" }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/Question" } } }, "required": [ "data_room_id", "questions" ] }, "example": { "data_room_id": 10, "questions": [ { "id": 41, "number": "Q7", "status": "assigned", "status_label": "Assigned", "category": "legal", "text": "Any pending litigation?", "source": "guest", "asked_by": "buyer@bidco.com", "document_id": 252, "document": "articles.pdf", "index": "2.1", "page": 4, "visibility": "private", "request_item_id": null, "assignee": "ann@acme.com", "answer": null, "answer_approved": false, "decline_reason": null, "asked_at": "2026-11-10T07:30:00+00:00", "answered_at": null, "approved_at": null } ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "rooms:read", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "list-data-room-questions", "x-hr-write": false }, "post": { "operationId": "addDataRoomQuestion", "summary": "Add a Q&A question", "description": "Adds a question (e.g. from a buyer's list), like importing a question list in the panel: nobody is e-mailed. Answer and approve it in the panel. 409 when the room is frozen. Q&A and request lists need the Max or Unlimited plan, the Deal Room Pass or the trial (else 402).", "tags": [ "Data rooms" ], "parameters": [ { "name": "data_room_id", "in": "path", "required": true, "description": "Data room id (from List data rooms).", "schema": { "type": "integer", "minimum": 1 }, "example": 10 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 4000, "description": "The question." }, "category": { "type": "string", "enum": [ "legal", "financial", "tax", "hr", "commercial", "it", "other" ], "description": "Default other." }, "document_id": { "type": "integer", "description": "A document of the room the question is about …" }, "index": { "type": "string", "description": "… or its index number, e.g. \"2.1\"." }, "page": { "type": "integer", "minimum": 1, "description": "Page number." }, "all_guests": { "type": "boolean", "description": "true: published to the room's FAQ once answered." } }, "required": [ "text" ] }, "example": { "text": "Any pending litigation?", "category": "legal", "index": "2.1", "page": 4 } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 4000, "description": "The question." }, "category": { "type": "string", "enum": [ "legal", "financial", "tax", "hr", "commercial", "it", "other" ], "description": "Default other." }, "document_id": { "type": "integer", "description": "A document of the room the question is about …" }, "index": { "type": "string", "description": "… or its index number, e.g. \"2.1\"." }, "page": { "type": "integer", "minimum": 1, "description": "Page number." }, "all_guests": { "type": "boolean", "description": "true: published to the room's FAQ once answered." } }, "required": [ "text" ] } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Question" }, "example": { "id": 42, "number": "Q8", "status": "new", "status_label": "New", "category": "legal", "text": "Any pending litigation?", "source": "import", "asked_by": null, "document_id": 252, "document": "articles.pdf", "index": "2.1", "page": 4, "visibility": "private", "request_item_id": null, "assignee": null, "answer": null, "answer_approved": false, "decline_reason": null, "asked_at": "2026-11-10T07:30:00+00:00", "answered_at": null, "approved_at": null } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "rooms:write", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "add-data-room-question", "x-hr-write": true } }, "/api/v2/data-rooms/{data_room_id}/requests": { "get": { "operationId": "listDataRoomRequestItems", "summary": "List due diligence request items", "description": "The room's request list. Q&A and request lists need the Max or Unlimited plan, the Deal Room Pass or the trial (else 402).", "tags": [ "Data rooms" ], "parameters": [ { "name": "data_room_id", "in": "path", "required": true, "description": "Data room id (from List data rooms).", "schema": { "type": "integer", "minimum": 1 }, "example": 10 }, { "name": "status", "in": "query", "required": false, "description": "Only this status.", "schema": { "type": "string", "enum": [ "open", "in_progress", "provided", "na" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data_room_id": { "type": "integer" }, "request_items": { "type": "array", "items": { "$ref": "#/components/schemas/RequestItem" } } }, "required": [ "data_room_id", "request_items" ] }, "example": { "data_room_id": 10, "request_items": [ { "id": 3, "number": "1.1", "category": "Legal", "description": "Articles of association", "priority": "high", "due_date": "2026-12-01", "assignee": "ann@acme.com", "status": "provided", "status_label": "Provided", "documents": [ { "document_id": 252, "index": "2.1" } ], "created_at": "2026-11-10T07:00:00+00:00", "updated_at": "2026-11-10T07:10:00+00:00" } ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "rooms:read", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "list-data-room-request-items", "x-hr-write": false }, "post": { "operationId": "addDataRoomRequestItem", "summary": "Add a request list item", "description": "Adds an item to the room's due diligence request list. 409 when the room is frozen. Q&A and request lists need the Max or Unlimited plan, the Deal Room Pass or the trial (else 402).", "tags": [ "Data rooms" ], "parameters": [ { "name": "data_room_id", "in": "path", "required": true, "description": "Data room id (from List data rooms).", "schema": { "type": "integer", "minimum": 1 }, "example": 10 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "description": "What is requested." }, "number": { "type": "string", "description": "Your numbering, e.g. \"1.1\"." }, "category": { "type": "string", "description": "Free text, e.g. \"Legal\"." }, "priority": { "type": "string", "enum": [ "high", "medium", "low" ], "description": "Default medium." }, "due_date": { "type": "string", "format": "date", "description": "YYYY-MM-DD." }, "assignee": { "type": "string", "description": "E-mail of a team member who manages the room." }, "status": { "type": "string", "enum": [ "open", "in_progress", "provided", "na" ], "description": "Default open." }, "documents": { "type": "array", "items": { "type": [ "string", "integer" ] }, "description": "Documents that answer it: index numbers as strings (\"2.1\") and / or document ids as numbers." } }, "required": [ "description" ] }, "example": { "description": "Articles of association", "number": "1.1", "priority": "high", "due_date": "2026-12-01", "documents": [ "2.1" ] } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "description": { "type": "string", "description": "What is requested." }, "number": { "type": "string", "description": "Your numbering, e.g. \"1.1\"." }, "category": { "type": "string", "description": "Free text, e.g. \"Legal\"." }, "priority": { "type": "string", "enum": [ "high", "medium", "low" ], "description": "Default medium." }, "due_date": { "type": "string", "format": "date", "description": "YYYY-MM-DD." }, "assignee": { "type": "string", "description": "E-mail of a team member who manages the room." }, "status": { "type": "string", "enum": [ "open", "in_progress", "provided", "na" ], "description": "Default open." }, "documents": { "type": "array", "items": { "type": [ "string", "integer" ] }, "description": "Documents that answer it: index numbers as strings (\"2.1\") and / or document ids as numbers." } }, "required": [ "description" ] } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestItem" }, "example": { "id": 3, "number": "1.1", "category": "Legal", "description": "Articles of association", "priority": "high", "due_date": "2026-12-01", "assignee": "ann@acme.com", "status": "open", "status_label": "Open", "documents": [ { "document_id": 252, "index": "2.1" } ], "created_at": "2026-11-10T07:00:00+00:00", "updated_at": "2026-11-10T07:10:00+00:00" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "rooms:write", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "add-data-room-request-item", "x-hr-write": true } }, "/api/v2/data-rooms/{data_room_id}/folders": { "get": { "operationId": "listDataRoomFolders", "summary": "List data room folders", "description": "Folders of a data room with their document counts. A room folder groups the room's documents (one level); the files stay in the folders they come from.", "tags": [ "Data rooms" ], "parameters": [ { "name": "data_room_id", "in": "path", "required": true, "description": "Data room id (from List data rooms).", "schema": { "type": "integer", "minimum": 1 }, "example": 10 } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data_room_id": { "type": "integer" }, "data_room": { "type": "string" }, "frozen": { "type": "boolean" }, "folders_enabled": { "type": "boolean" }, "folders": { "type": "array", "items": { "$ref": "#/components/schemas/RoomFolder" } } }, "required": [ "data_room_id", "data_room", "frozen", "folders_enabled", "folders" ] }, "example": { "data_room_id": 10, "data_room": "Project Falcon", "frozen": false, "folders_enabled": true, "folders": [ { "id": 5, "name": "Financials", "position": 0, "data_room_id": 10, "documents_count": 3 } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "rooms:read", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "list-data-room-folders", "x-hr-write": false }, "post": { "operationId": "createDataRoomFolder", "summary": "Create a data room folder", "description": "Creates a folder in a data room. Refused with 400 while folders are off for the room; 409 when the room is frozen.", "tags": [ "Data rooms" ], "parameters": [ { "name": "data_room_id", "in": "path", "required": true, "description": "Data room id (from List data rooms).", "schema": { "type": "integer", "minimum": 1 }, "example": 10 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100, "description": "Folder name." } }, "required": [ "name" ] }, "example": { "name": "Financials" } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100, "description": "Folder name." } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoomFolder" }, "example": { "id": 5, "name": "Financials", "position": 0, "data_room_id": 10, "documents_count": 0 } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "rooms:write", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "create-data-room-folder", "x-hr-write": true } }, "/api/v2/data-rooms/{data_room_id}/folders/move": { "post": { "operationId": "moveDataRoomDocuments", "summary": "Move data room documents", "description": "Moves documents of the room into one of its folders, or to the room's top level (folder_id null or missing). Ids not in the room are listed in not_in_room. 409 when the room is frozen.", "tags": [ "Data rooms" ], "parameters": [ { "name": "data_room_id", "in": "path", "required": true, "description": "Data room id (from List data rooms).", "schema": { "type": "integer", "minimum": 1 }, "example": 10 } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "room_link_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "description": "Room documents (room_link_id from the room's documents or the index) …" }, "document_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "description": "… and / or document ids." }, "folder_id": { "type": [ "integer", "null" ], "description": "A folder of this room; null = the top level." } } }, "example": { "room_link_ids": [ 910, 911 ], "folder_id": 5 } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "room_link_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "description": "Room documents (room_link_id from the room's documents or the index) …" }, "document_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "description": "… and / or document ids." }, "folder_id": { "type": [ "integer", "null" ], "description": "A folder of this room; null = the top level." } } } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "moved": { "type": "integer" }, "data_room_id": { "type": "integer" }, "room_folder_id": { "type": [ "integer", "null" ] }, "room_folder": { "type": [ "string", "null" ] }, "not_in_room": { "type": "array", "items": { "type": "integer" } } }, "required": [ "moved", "data_room_id", "room_folder_id", "room_folder", "not_in_room" ] }, "example": { "moved": 2, "data_room_id": 10, "room_folder_id": 5, "room_folder": "Financials", "not_in_room": [] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "rooms:write", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "move-data-room-documents", "x-hr-write": true } }, "/api/v2/data-rooms/{data_room_id}/folders/{folder_id}": { "post": { "operationId": "renameDataRoomFolder", "summary": "Rename a data room folder", "description": "Renames a folder of a data room. 409 when the room is frozen.", "tags": [ "Data rooms" ], "parameters": [ { "name": "data_room_id", "in": "path", "required": true, "description": "Data room id (from List data rooms).", "schema": { "type": "integer", "minimum": 1 }, "example": 10 }, { "name": "folder_id", "in": "path", "required": true, "description": "Data room folder id (from List data room folders).", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100, "description": "New name." } }, "required": [ "name" ] }, "example": { "name": "Finance" } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100, "description": "New name." } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoomFolder" }, "example": { "id": 5, "name": "Finance", "position": 0, "data_room_id": 10 } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "rooms:write", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "rename-data-room-folder", "x-hr-write": true } }, "/api/v2/data-rooms/{data_room_id}/folders/{folder_id}/delete": { "post": { "operationId": "deleteDataRoomFolder", "summary": "Delete a data room folder", "description": "Deletes the room folder only – its documents stay in the room, at the top level. 409 when the room is frozen.", "tags": [ "Data rooms" ], "parameters": [ { "name": "data_room_id", "in": "path", "required": true, "description": "Data room id (from List data rooms).", "schema": { "type": "integer", "minimum": 1 }, "example": 10 }, { "name": "folder_id", "in": "path", "required": true, "description": "Data room folder id (from List data room folders).", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "id": { "type": "integer" }, "data_room_id": { "type": "integer" }, "moved_to_top": { "type": "integer", "description": "Documents moved to the top level." } }, "required": [ "deleted", "id", "data_room_id", "moved_to_top" ] }, "example": { "deleted": true, "id": 5, "data_room_id": 10, "moved_to_top": 3 } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "rooms:write", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "delete-data-room-folder", "x-hr-write": true } }, "/api/v2/data-rooms/{data_room_id}/documents": { "get": { "operationId": "listDataRoomDocuments", "summary": "List data room documents", "description": "The room's documents in index order, with their room folder and the folder (and subfolder) they come from; group is the folder guests see the document under.", "tags": [ "Data rooms" ], "parameters": [ { "name": "data_room_id", "in": "path", "required": true, "description": "Data room id (from List data rooms).", "schema": { "type": "integer", "minimum": 1 }, "example": 10 } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data_room_id": { "type": "integer" }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/RoomDocument" } } }, "required": [ "data_room_id", "documents" ] }, "example": { "data_room_id": 10, "documents": [ { "room_link_id": 910, "document_id": 260, "name": "pnl.xlsx", "number": "1.1", "group": "Financials", "room_folder_id": 5, "room_folder": "Financials", "folder_id": 44, "folder": "Finance", "subfolder_id": 9, "subfolder": "2026", "path": "Finance › 2026", "approval": "published" } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "rooms:read", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "list-data-room-documents", "x-hr-write": false }, "post": { "operationId": "addDataRoomDocuments", "summary": "Add documents to a data room", "description": "Like \"Add existing documents\" on the room page: documents from folders you can open, optionally straight into a room folder. The files stay in their folders. When the room sends e-mail notifications, its guests get one e-mail for the batch (at most 50 recipients per request, else 400 TOO_MANY_RECIPIENTS). 409 when the room is frozen.", "tags": [ "Data rooms" ], "parameters": [ { "name": "data_room_id", "in": "path", "required": true, "description": "Data room id (from List data rooms).", "schema": { "type": "integer", "minimum": 1 }, "example": 10 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "document_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "description": "Documents to add (up to 100)." }, "folder_id": { "type": "integer", "description": "A folder of this room (optional)." } }, "required": [ "document_ids" ] }, "example": { "document_ids": [ 260, 261 ], "folder_id": 5 } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "document_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "description": "Documents to add (up to 100)." }, "folder_id": { "type": "integer", "description": "A folder of this room (optional)." } }, "required": [ "document_ids" ] } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "added": { "type": "integer" }, "data_room_id": { "type": "integer" }, "room_folder_id": { "type": [ "integer", "null" ] }, "room_folder": { "type": [ "string", "null" ] }, "documents": { "type": "array", "items": { "type": "object", "properties": { "room_link_id": { "type": "integer" }, "document_id": { "type": "integer" } }, "required": [ "room_link_id", "document_id" ] } } }, "required": [ "added", "data_room_id", "room_folder_id", "room_folder", "documents" ] }, "example": { "added": 2, "data_room_id": 10, "room_folder_id": 5, "room_folder": "Financials", "documents": [ { "room_link_id": 912, "document_id": 260 }, { "room_link_id": 913, "document_id": 261 } ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "rooms:write", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "add-data-room-documents", "x-hr-write": true } }, "/api/v2/offers": { "get": { "operationId": "listOffers", "summary": "List offers", "description": "Offers you can see (administrators: the whole team), newest first, with paging.", "tags": [ "Offers" ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Default open (everything but archived).", "schema": { "type": "string", "enum": [ "open", "all", "active", "expired", "accepted", "declined", "draft", "closed" ] }, "example": "active" }, { "name": "search", "in": "query", "required": false, "description": "Words in the title, the client's name, company or e-mail (q works too).", "schema": { "type": "string" }, "example": "acme" }, { "name": "limit", "in": "query", "required": false, "description": "1–200 (default 50).", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "page", "in": "query", "required": false, "description": "From 1.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "offers": { "type": "array", "items": { "$ref": "#/components/schemas/OfferRow" } }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "next_page": { "type": [ "integer", "null" ] } }, "required": [ "offers", "page", "limit", "total", "next_page" ] }, "example": { "offers": [ { "id": 31, "title": "Fit-out Q1", "status": "active", "expired": false, "client": { "first_name": "Anna", "last_name": "Nowak", "company": "Acme", "email": "anna@acme.com" }, "kind": "files", "url": "https://www.helprange.com/o/Xk2pQ9/", "document_views": 4, "page_visits": 2, "last_viewed_at": "2026-11-11T09:12:00+00:00", "sent_at": null, "created_at": "2026-11-11T08:00:00+00:00", "updated_at": "2026-11-11T08:00:00+00:00" } ], "page": 1, "limit": 50, "total": 1, "next_page": null } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "links:read", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "list-offers", "x-hr-write": false }, "post": { "operationId": "createOffer", "summary": "Create an offer", "description": "Creates an offer with its own link: based on a folder (folder_id – new files show up), from documents (file_ids), or empty with just a title and client. Offers without a folder get their own folder \"Offer - \". The API never e-mails the client: send the returned url yourself.", "tags": [ "Offers" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "folder_id": { "type": "integer", "description": "Base the offer on this folder." }, "file_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "description": "Documents (a JSON list, repeated form fields or \"1,2\")." }, "status": { "type": "string", "enum": [ "active", "draft" ], "description": "Default active." }, "title": { "type": "string", "description": "What the client sees as the title. Create: default the folder's / first document's name." }, "client_first_name": { "type": "string" }, "client_last_name": { "type": "string" }, "client_company": { "type": "string" }, "client_email": { "type": "string", "description": "The client's e-mail – never e-mailed by the API." }, "message": { "type": "string", "maxLength": 2000, "description": "Message on the offer page." }, "price_summary": { "type": "string", "description": "One line, e.g. \"3 packages, from 2,400 EUR\"." }, "show_accept": { "type": "boolean", "description": "\"Accept offer\" button (default on)." }, "accept_label": { "type": "string" }, "show_contact": { "type": "boolean", "description": "\"Request contact\" button (default on)." }, "contact_label": { "type": "string" }, "show_decline": { "type": "boolean", "description": "\"Decline\" button with an optional reason (default off)." }, "decline_label": { "type": "string" }, "require_email_verification": { "type": "boolean", "description": "The client verifies their e-mail with a one-time code (default on)." }, "access": { "type": "string", "enum": [ "any", "email", "domain" ], "description": "With e-mail verification: anyone, only client_email, or client_email and colleagues at the same domain." }, "allow_download": { "type": "boolean" }, "watermark": { "type": "boolean" }, "expires_on": { "type": "string", "description": "Last day, YYYY-MM-DD (\"\" removes it)." }, "passcode": { "type": "string", "description": "Asked before the offer opens (\"\" removes it)." }, "screenshot_protection": { "type": "boolean", "description": "Pro and higher (else 402)." }, "one_viewer_at_a_time": { "type": "boolean" }, "open_directly": { "type": "boolean", "description": "One-file offers: open the document directly instead of the offer page." }, "layout": { "type": "string", "enum": [ "classic", "split", "cover", "minimal" ] } } }, "example": { "title": "Fit-out Q1", "file_ids": [ 250, 251 ], "client_company": "Acme", "client_email": "anna@acme.com", "access": "domain", "show_decline": true, "passcode": "oak-41", "expires_on": "2026-12-31" } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "folder_id": { "type": "integer", "description": "Base the offer on this folder." }, "file_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "description": "Documents (a JSON list, repeated form fields or \"1,2\")." }, "status": { "type": "string", "enum": [ "active", "draft" ], "description": "Default active." }, "title": { "type": "string", "description": "What the client sees as the title. Create: default the folder's / first document's name." }, "client_first_name": { "type": "string" }, "client_last_name": { "type": "string" }, "client_company": { "type": "string" }, "client_email": { "type": "string", "description": "The client's e-mail – never e-mailed by the API." }, "message": { "type": "string", "maxLength": 2000, "description": "Message on the offer page." }, "price_summary": { "type": "string", "description": "One line, e.g. \"3 packages, from 2,400 EUR\"." }, "show_accept": { "type": "boolean", "description": "\"Accept offer\" button (default on)." }, "accept_label": { "type": "string" }, "show_contact": { "type": "boolean", "description": "\"Request contact\" button (default on)." }, "contact_label": { "type": "string" }, "show_decline": { "type": "boolean", "description": "\"Decline\" button with an optional reason (default off)." }, "decline_label": { "type": "string" }, "require_email_verification": { "type": "boolean", "description": "The client verifies their e-mail with a one-time code (default on)." }, "access": { "type": "string", "enum": [ "any", "email", "domain" ], "description": "With e-mail verification: anyone, only client_email, or client_email and colleagues at the same domain." }, "allow_download": { "type": "boolean" }, "watermark": { "type": "boolean" }, "expires_on": { "type": "string", "description": "Last day, YYYY-MM-DD (\"\" removes it)." }, "passcode": { "type": "string", "description": "Asked before the offer opens (\"\" removes it)." }, "screenshot_protection": { "type": "boolean", "description": "Pro and higher (else 402)." }, "one_viewer_at_a_time": { "type": "boolean" }, "open_directly": { "type": "boolean", "description": "One-file offers: open the document directly instead of the offer page." }, "layout": { "type": "string", "enum": [ "classic", "split", "cover", "minimal" ] } } } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/OfferRow" }, { "type": "object", "properties": { "stored_status": { "type": "string" }, "public_url": { "type": "string", "format": "uri" }, "panel_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "price_summary": { "type": "string" }, "buttons": { "type": "object", "properties": { "accept": { "type": "object", "properties": { "shown": { "type": "boolean" }, "label": { "type": "string" } }, "required": [ "shown", "label" ] }, "contact": { "type": "object", "properties": { "shown": { "type": "boolean" }, "label": { "type": "string" } }, "required": [ "shown", "label" ] }, "decline": { "type": "object", "properties": { "shown": { "type": "boolean" }, "label": { "type": "string" } }, "required": [ "shown", "label" ] } }, "required": [ "accept", "contact", "decline" ] }, "protection": { "type": "object", "properties": { "require_email_verification": { "type": "boolean" }, "access": { "type": "string" }, "allowed_emails": { "type": "string" }, "allow_download": { "type": "boolean" }, "watermark": { "type": "boolean" }, "passcode": { "type": "boolean" }, "screenshot_protection": { "type": "boolean" }, "one_viewer_at_a_time": { "type": "boolean" }, "expires_on": { "type": [ "string", "null" ], "format": "date" } }, "required": [ "require_email_verification", "access", "allowed_emails", "allow_download", "watermark", "passcode", "screenshot_protection", "one_viewer_at_a_time", "expires_on" ] }, "open_directly": { "type": "boolean" }, "layout": { "type": "string" }, "theme": { "type": "string" }, "base_folder": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "own_folder": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "folder_id": { "type": "integer" }, "source": { "type": "string", "enum": [ "folder", "own_folder", "picked" ] }, "view_url": { "type": [ "string", "null" ], "format": "uri" }, "views": { "type": "integer" } }, "required": [ "id", "name", "folder_id", "source", "view_url", "views" ] } }, "people": { "type": "integer" }, "engagement": { "type": [ "integer", "null" ] }, "responses_count": { "type": "integer" }, "responses": { "type": "array", "items": { "$ref": "#/components/schemas/OfferResponse" } }, "sent_to": { "type": [ "string", "null" ] }, "created_by": { "type": [ "string", "null" ] }, "legacy_url": { "type": [ "string", "null" ], "format": "uri" }, "send_by_email": { "type": "string" } }, "required": [ "stored_status", "public_url", "panel_url", "message", "price_summary", "buttons", "protection", "open_directly", "layout", "theme", "base_folder", "own_folder", "files", "people", "engagement", "responses_count", "responses", "sent_to", "created_by", "legacy_url", "send_by_email" ] } ] }, "example": { "id": 31, "title": "Fit-out Q1", "status": "active", "expired": false, "client": { "first_name": "Anna", "last_name": "Nowak", "company": "Acme", "email": "anna@acme.com" }, "kind": "files", "url": "https://www.helprange.com/o/Xk2pQ9/", "document_views": 4, "page_visits": 2, "last_viewed_at": "2026-11-11T09:12:00+00:00", "sent_at": null, "created_at": "2026-11-11T08:00:00+00:00", "updated_at": "2026-11-11T08:00:00+00:00", "stored_status": "active", "public_url": "https://www.helprange.com/o/Xk2pQ9/", "panel_url": "https://www.helprange.com/user/offers/31/", "message": "Hi Anna, here is our proposal.", "price_summary": "from 2,400 EUR", "buttons": { "accept": { "shown": true, "label": "" }, "contact": { "shown": true, "label": "" }, "decline": { "shown": true, "label": "" } }, "protection": { "require_email_verification": true, "access": "domain", "allowed_emails": "anna@acme.com @acme.com", "allow_download": false, "watermark": false, "passcode": true, "screenshot_protection": false, "one_viewer_at_a_time": false, "expires_on": "2026-12-31" }, "open_directly": false, "layout": "classic", "theme": "light", "base_folder": null, "own_folder": { "id": 77, "name": "Offer - Fit-out Q1" }, "files": [ { "id": 250, "name": "proposal.pdf", "folder_id": 77, "source": "own_folder", "view_url": "https://www.helprange.com/view/5b0c.../proposal.pdf", "views": 3 } ], "people": 1, "engagement": 82, "responses_count": 1, "responses": [ { "kind": "declined the offer", "type": "decline", "offer_id": 31, "email": "anna@acme.com", "email_verified": true, "offer": "Fit-out Q1", "comment": "Too expensive", "document_id": null, "engagement": 64, "country": "PL", "at": "2026-11-11T10:00:00+00:00" } ], "sent_to": null, "created_by": "ann@acme.com", "legacy_url": null, "send_by_email": "HelpRange does not e-mail offers through the API or MCP. Send the offer link (url) yourself, or use \"Send by e-mail\" on the offer page in HelpRange." } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "links:write", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "create-offer", "x-hr-write": true } }, "/api/v2/offers/{offer_id}": { "get": { "operationId": "getOffer", "summary": "Offer details", "description": "Texts, client, buttons, protection, layout, its documents (each with the offer's own link and views), visits, engagement and the 10 latest responses. status is what the panel shows (expired for an active offer past its date); stored_status the saved one.", "tags": [ "Offers" ], "parameters": [ { "name": "offer_id", "in": "path", "required": true, "description": "Offer id (from List offers).", "schema": { "type": "integer", "minimum": 1 }, "example": 31 } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/OfferRow" }, { "type": "object", "properties": { "stored_status": { "type": "string" }, "public_url": { "type": "string", "format": "uri" }, "panel_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "price_summary": { "type": "string" }, "buttons": { "type": "object", "properties": { "accept": { "type": "object", "properties": { "shown": { "type": "boolean" }, "label": { "type": "string" } }, "required": [ "shown", "label" ] }, "contact": { "type": "object", "properties": { "shown": { "type": "boolean" }, "label": { "type": "string" } }, "required": [ "shown", "label" ] }, "decline": { "type": "object", "properties": { "shown": { "type": "boolean" }, "label": { "type": "string" } }, "required": [ "shown", "label" ] } }, "required": [ "accept", "contact", "decline" ] }, "protection": { "type": "object", "properties": { "require_email_verification": { "type": "boolean" }, "access": { "type": "string" }, "allowed_emails": { "type": "string" }, "allow_download": { "type": "boolean" }, "watermark": { "type": "boolean" }, "passcode": { "type": "boolean" }, "screenshot_protection": { "type": "boolean" }, "one_viewer_at_a_time": { "type": "boolean" }, "expires_on": { "type": [ "string", "null" ], "format": "date" } }, "required": [ "require_email_verification", "access", "allowed_emails", "allow_download", "watermark", "passcode", "screenshot_protection", "one_viewer_at_a_time", "expires_on" ] }, "open_directly": { "type": "boolean" }, "layout": { "type": "string" }, "theme": { "type": "string" }, "base_folder": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "own_folder": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "folder_id": { "type": "integer" }, "source": { "type": "string", "enum": [ "folder", "own_folder", "picked" ] }, "view_url": { "type": [ "string", "null" ], "format": "uri" }, "views": { "type": "integer" } }, "required": [ "id", "name", "folder_id", "source", "view_url", "views" ] } }, "people": { "type": "integer" }, "engagement": { "type": [ "integer", "null" ] }, "responses_count": { "type": "integer" }, "responses": { "type": "array", "items": { "$ref": "#/components/schemas/OfferResponse" } }, "sent_to": { "type": [ "string", "null" ] }, "created_by": { "type": [ "string", "null" ] }, "legacy_url": { "type": [ "string", "null" ], "format": "uri" }, "send_by_email": { "type": "string" } }, "required": [ "stored_status", "public_url", "panel_url", "message", "price_summary", "buttons", "protection", "open_directly", "layout", "theme", "base_folder", "own_folder", "files", "people", "engagement", "responses_count", "responses", "sent_to", "created_by", "legacy_url", "send_by_email" ] } ] }, "example": { "id": 31, "title": "Fit-out Q1", "status": "active", "expired": false, "client": { "first_name": "Anna", "last_name": "Nowak", "company": "Acme", "email": "anna@acme.com" }, "kind": "files", "url": "https://www.helprange.com/o/Xk2pQ9/", "document_views": 4, "page_visits": 2, "last_viewed_at": "2026-11-11T09:12:00+00:00", "sent_at": null, "created_at": "2026-11-11T08:00:00+00:00", "updated_at": "2026-11-11T08:00:00+00:00", "stored_status": "active", "public_url": "https://www.helprange.com/o/Xk2pQ9/", "panel_url": "https://www.helprange.com/user/offers/31/", "message": "Hi Anna, here is our proposal.", "price_summary": "from 2,400 EUR", "buttons": { "accept": { "shown": true, "label": "" }, "contact": { "shown": true, "label": "" }, "decline": { "shown": true, "label": "" } }, "protection": { "require_email_verification": true, "access": "domain", "allowed_emails": "anna@acme.com @acme.com", "allow_download": false, "watermark": false, "passcode": true, "screenshot_protection": false, "one_viewer_at_a_time": false, "expires_on": "2026-12-31" }, "open_directly": false, "layout": "classic", "theme": "light", "base_folder": null, "own_folder": { "id": 77, "name": "Offer - Fit-out Q1" }, "files": [ { "id": 250, "name": "proposal.pdf", "folder_id": 77, "source": "own_folder", "view_url": "https://www.helprange.com/view/5b0c.../proposal.pdf", "views": 3 } ], "people": 1, "engagement": 82, "responses_count": 1, "responses": [ { "kind": "declined the offer", "type": "decline", "offer_id": 31, "email": "anna@acme.com", "email_verified": true, "offer": "Fit-out Q1", "comment": "Too expensive", "document_id": null, "engagement": 64, "country": "PL", "at": "2026-11-11T10:00:00+00:00" } ], "sent_to": null, "created_by": "ann@acme.com", "legacy_url": null, "send_by_email": "HelpRange does not e-mail offers through the API or MCP. Send the offer link (url) yourself, or use \"Send by e-mail\" on the offer page in HelpRange." } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "links:read", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "get-offer", "x-hr-write": false }, "patch": { "operationId": "updateOffer", "summary": "Update an offer", "description": "Changes only the fields you send. The offer's links follow at once (protection, expiry, status). The API never e-mails the client: send the returned url yourself.", "tags": [ "Offers" ], "parameters": [ { "name": "offer_id", "in": "path", "required": true, "description": "Offer id (from List offers).", "schema": { "type": "integer", "minimum": 1 }, "example": 31 } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "What the client sees as the title. Create: default the folder's / first document's name." }, "client_first_name": { "type": "string" }, "client_last_name": { "type": "string" }, "client_company": { "type": "string" }, "client_email": { "type": "string", "description": "The client's e-mail – never e-mailed by the API." }, "message": { "type": "string", "maxLength": 2000, "description": "Message on the offer page." }, "price_summary": { "type": "string", "description": "One line, e.g. \"3 packages, from 2,400 EUR\"." }, "show_accept": { "type": "boolean", "description": "\"Accept offer\" button (default on)." }, "accept_label": { "type": "string" }, "show_contact": { "type": "boolean", "description": "\"Request contact\" button (default on)." }, "contact_label": { "type": "string" }, "show_decline": { "type": "boolean", "description": "\"Decline\" button with an optional reason (default off)." }, "decline_label": { "type": "string" }, "require_email_verification": { "type": "boolean", "description": "The client verifies their e-mail with a one-time code (default on)." }, "access": { "type": "string", "enum": [ "any", "email", "domain" ], "description": "With e-mail verification: anyone, only client_email, or client_email and colleagues at the same domain." }, "allow_download": { "type": "boolean" }, "watermark": { "type": "boolean" }, "expires_on": { "type": "string", "description": "Last day, YYYY-MM-DD (\"\" removes it)." }, "passcode": { "type": "string", "description": "Asked before the offer opens (\"\" removes it)." }, "screenshot_protection": { "type": "boolean", "description": "Pro and higher (else 402)." }, "one_viewer_at_a_time": { "type": "boolean" }, "open_directly": { "type": "boolean", "description": "One-file offers: open the document directly instead of the offer page." }, "layout": { "type": "string", "enum": [ "classic", "split", "cover", "minimal" ] }, "status": { "type": "string", "enum": [ "active", "draft", "accepted", "declined", "closed" ], "description": "active also reopens an accepted, declined or archived offer; closed = archived." } } }, "example": { "status": "active", "expires_on": "2027-01-31", "one_viewer_at_a_time": true } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "What the client sees as the title. Create: default the folder's / first document's name." }, "client_first_name": { "type": "string" }, "client_last_name": { "type": "string" }, "client_company": { "type": "string" }, "client_email": { "type": "string", "description": "The client's e-mail – never e-mailed by the API." }, "message": { "type": "string", "maxLength": 2000, "description": "Message on the offer page." }, "price_summary": { "type": "string", "description": "One line, e.g. \"3 packages, from 2,400 EUR\"." }, "show_accept": { "type": "boolean", "description": "\"Accept offer\" button (default on)." }, "accept_label": { "type": "string" }, "show_contact": { "type": "boolean", "description": "\"Request contact\" button (default on)." }, "contact_label": { "type": "string" }, "show_decline": { "type": "boolean", "description": "\"Decline\" button with an optional reason (default off)." }, "decline_label": { "type": "string" }, "require_email_verification": { "type": "boolean", "description": "The client verifies their e-mail with a one-time code (default on)." }, "access": { "type": "string", "enum": [ "any", "email", "domain" ], "description": "With e-mail verification: anyone, only client_email, or client_email and colleagues at the same domain." }, "allow_download": { "type": "boolean" }, "watermark": { "type": "boolean" }, "expires_on": { "type": "string", "description": "Last day, YYYY-MM-DD (\"\" removes it)." }, "passcode": { "type": "string", "description": "Asked before the offer opens (\"\" removes it)." }, "screenshot_protection": { "type": "boolean", "description": "Pro and higher (else 402)." }, "one_viewer_at_a_time": { "type": "boolean" }, "open_directly": { "type": "boolean", "description": "One-file offers: open the document directly instead of the offer page." }, "layout": { "type": "string", "enum": [ "classic", "split", "cover", "minimal" ] }, "status": { "type": "string", "enum": [ "active", "draft", "accepted", "declined", "closed" ], "description": "active also reopens an accepted, declined or archived offer; closed = archived." } } } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/OfferRow" }, { "type": "object", "properties": { "stored_status": { "type": "string" }, "public_url": { "type": "string", "format": "uri" }, "panel_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "price_summary": { "type": "string" }, "buttons": { "type": "object", "properties": { "accept": { "type": "object", "properties": { "shown": { "type": "boolean" }, "label": { "type": "string" } }, "required": [ "shown", "label" ] }, "contact": { "type": "object", "properties": { "shown": { "type": "boolean" }, "label": { "type": "string" } }, "required": [ "shown", "label" ] }, "decline": { "type": "object", "properties": { "shown": { "type": "boolean" }, "label": { "type": "string" } }, "required": [ "shown", "label" ] } }, "required": [ "accept", "contact", "decline" ] }, "protection": { "type": "object", "properties": { "require_email_verification": { "type": "boolean" }, "access": { "type": "string" }, "allowed_emails": { "type": "string" }, "allow_download": { "type": "boolean" }, "watermark": { "type": "boolean" }, "passcode": { "type": "boolean" }, "screenshot_protection": { "type": "boolean" }, "one_viewer_at_a_time": { "type": "boolean" }, "expires_on": { "type": [ "string", "null" ], "format": "date" } }, "required": [ "require_email_verification", "access", "allowed_emails", "allow_download", "watermark", "passcode", "screenshot_protection", "one_viewer_at_a_time", "expires_on" ] }, "open_directly": { "type": "boolean" }, "layout": { "type": "string" }, "theme": { "type": "string" }, "base_folder": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "own_folder": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "folder_id": { "type": "integer" }, "source": { "type": "string", "enum": [ "folder", "own_folder", "picked" ] }, "view_url": { "type": [ "string", "null" ], "format": "uri" }, "views": { "type": "integer" } }, "required": [ "id", "name", "folder_id", "source", "view_url", "views" ] } }, "people": { "type": "integer" }, "engagement": { "type": [ "integer", "null" ] }, "responses_count": { "type": "integer" }, "responses": { "type": "array", "items": { "$ref": "#/components/schemas/OfferResponse" } }, "sent_to": { "type": [ "string", "null" ] }, "created_by": { "type": [ "string", "null" ] }, "legacy_url": { "type": [ "string", "null" ], "format": "uri" }, "send_by_email": { "type": "string" } }, "required": [ "stored_status", "public_url", "panel_url", "message", "price_summary", "buttons", "protection", "open_directly", "layout", "theme", "base_folder", "own_folder", "files", "people", "engagement", "responses_count", "responses", "sent_to", "created_by", "legacy_url", "send_by_email" ] } ] }, "example": { "id": 31, "title": "Fit-out Q1", "status": "active", "expired": false, "client": { "first_name": "Anna", "last_name": "Nowak", "company": "Acme", "email": "anna@acme.com" }, "kind": "files", "url": "https://www.helprange.com/o/Xk2pQ9/", "document_views": 4, "page_visits": 2, "last_viewed_at": "2026-11-11T09:12:00+00:00", "sent_at": null, "created_at": "2026-11-11T08:00:00+00:00", "updated_at": "2026-11-11T08:00:00+00:00", "stored_status": "active", "public_url": "https://www.helprange.com/o/Xk2pQ9/", "panel_url": "https://www.helprange.com/user/offers/31/", "message": "Hi Anna, here is our proposal.", "price_summary": "from 2,400 EUR", "buttons": { "accept": { "shown": true, "label": "" }, "contact": { "shown": true, "label": "" }, "decline": { "shown": true, "label": "" } }, "protection": { "require_email_verification": true, "access": "domain", "allowed_emails": "anna@acme.com @acme.com", "allow_download": false, "watermark": false, "passcode": true, "screenshot_protection": false, "one_viewer_at_a_time": false, "expires_on": "2026-12-31" }, "open_directly": false, "layout": "classic", "theme": "light", "base_folder": null, "own_folder": { "id": 77, "name": "Offer - Fit-out Q1" }, "files": [ { "id": 250, "name": "proposal.pdf", "folder_id": 77, "source": "own_folder", "view_url": "https://www.helprange.com/view/5b0c.../proposal.pdf", "views": 3 } ], "people": 1, "engagement": 82, "responses_count": 1, "responses": [ { "kind": "declined the offer", "type": "decline", "offer_id": 31, "email": "anna@acme.com", "email_verified": true, "offer": "Fit-out Q1", "comment": "Too expensive", "document_id": null, "engagement": 64, "country": "PL", "at": "2026-11-11T10:00:00+00:00" } ], "sent_to": null, "created_by": "ann@acme.com", "legacy_url": null, "send_by_email": "HelpRange does not e-mail offers through the API or MCP. Send the offer link (url) yourself, or use \"Send by e-mail\" on the offer page in HelpRange." } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "links:write", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "update-offer", "x-hr-write": true }, "post": { "operationId": "updateOfferPost", "summary": "Update an offer (POST)", "description": "Changes only the fields you send. The offer's links follow at once (protection, expiry, status). POST does the same as PATCH, for tools that cannot send PATCH. The API never e-mails the client: send the returned url yourself.", "tags": [ "Offers" ], "parameters": [ { "name": "offer_id", "in": "path", "required": true, "description": "Offer id (from List offers).", "schema": { "type": "integer", "minimum": 1 }, "example": 31 } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "What the client sees as the title. Create: default the folder's / first document's name." }, "client_first_name": { "type": "string" }, "client_last_name": { "type": "string" }, "client_company": { "type": "string" }, "client_email": { "type": "string", "description": "The client's e-mail – never e-mailed by the API." }, "message": { "type": "string", "maxLength": 2000, "description": "Message on the offer page." }, "price_summary": { "type": "string", "description": "One line, e.g. \"3 packages, from 2,400 EUR\"." }, "show_accept": { "type": "boolean", "description": "\"Accept offer\" button (default on)." }, "accept_label": { "type": "string" }, "show_contact": { "type": "boolean", "description": "\"Request contact\" button (default on)." }, "contact_label": { "type": "string" }, "show_decline": { "type": "boolean", "description": "\"Decline\" button with an optional reason (default off)." }, "decline_label": { "type": "string" }, "require_email_verification": { "type": "boolean", "description": "The client verifies their e-mail with a one-time code (default on)." }, "access": { "type": "string", "enum": [ "any", "email", "domain" ], "description": "With e-mail verification: anyone, only client_email, or client_email and colleagues at the same domain." }, "allow_download": { "type": "boolean" }, "watermark": { "type": "boolean" }, "expires_on": { "type": "string", "description": "Last day, YYYY-MM-DD (\"\" removes it)." }, "passcode": { "type": "string", "description": "Asked before the offer opens (\"\" removes it)." }, "screenshot_protection": { "type": "boolean", "description": "Pro and higher (else 402)." }, "one_viewer_at_a_time": { "type": "boolean" }, "open_directly": { "type": "boolean", "description": "One-file offers: open the document directly instead of the offer page." }, "layout": { "type": "string", "enum": [ "classic", "split", "cover", "minimal" ] }, "status": { "type": "string", "enum": [ "active", "draft", "accepted", "declined", "closed" ], "description": "active also reopens an accepted, declined or archived offer; closed = archived." } } }, "example": { "status": "active", "expires_on": "2027-01-31", "one_viewer_at_a_time": true } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "What the client sees as the title. Create: default the folder's / first document's name." }, "client_first_name": { "type": "string" }, "client_last_name": { "type": "string" }, "client_company": { "type": "string" }, "client_email": { "type": "string", "description": "The client's e-mail – never e-mailed by the API." }, "message": { "type": "string", "maxLength": 2000, "description": "Message on the offer page." }, "price_summary": { "type": "string", "description": "One line, e.g. \"3 packages, from 2,400 EUR\"." }, "show_accept": { "type": "boolean", "description": "\"Accept offer\" button (default on)." }, "accept_label": { "type": "string" }, "show_contact": { "type": "boolean", "description": "\"Request contact\" button (default on)." }, "contact_label": { "type": "string" }, "show_decline": { "type": "boolean", "description": "\"Decline\" button with an optional reason (default off)." }, "decline_label": { "type": "string" }, "require_email_verification": { "type": "boolean", "description": "The client verifies their e-mail with a one-time code (default on)." }, "access": { "type": "string", "enum": [ "any", "email", "domain" ], "description": "With e-mail verification: anyone, only client_email, or client_email and colleagues at the same domain." }, "allow_download": { "type": "boolean" }, "watermark": { "type": "boolean" }, "expires_on": { "type": "string", "description": "Last day, YYYY-MM-DD (\"\" removes it)." }, "passcode": { "type": "string", "description": "Asked before the offer opens (\"\" removes it)." }, "screenshot_protection": { "type": "boolean", "description": "Pro and higher (else 402)." }, "one_viewer_at_a_time": { "type": "boolean" }, "open_directly": { "type": "boolean", "description": "One-file offers: open the document directly instead of the offer page." }, "layout": { "type": "string", "enum": [ "classic", "split", "cover", "minimal" ] }, "status": { "type": "string", "enum": [ "active", "draft", "accepted", "declined", "closed" ], "description": "active also reopens an accepted, declined or archived offer; closed = archived." } } } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/OfferRow" }, { "type": "object", "properties": { "stored_status": { "type": "string" }, "public_url": { "type": "string", "format": "uri" }, "panel_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "price_summary": { "type": "string" }, "buttons": { "type": "object", "properties": { "accept": { "type": "object", "properties": { "shown": { "type": "boolean" }, "label": { "type": "string" } }, "required": [ "shown", "label" ] }, "contact": { "type": "object", "properties": { "shown": { "type": "boolean" }, "label": { "type": "string" } }, "required": [ "shown", "label" ] }, "decline": { "type": "object", "properties": { "shown": { "type": "boolean" }, "label": { "type": "string" } }, "required": [ "shown", "label" ] } }, "required": [ "accept", "contact", "decline" ] }, "protection": { "type": "object", "properties": { "require_email_verification": { "type": "boolean" }, "access": { "type": "string" }, "allowed_emails": { "type": "string" }, "allow_download": { "type": "boolean" }, "watermark": { "type": "boolean" }, "passcode": { "type": "boolean" }, "screenshot_protection": { "type": "boolean" }, "one_viewer_at_a_time": { "type": "boolean" }, "expires_on": { "type": [ "string", "null" ], "format": "date" } }, "required": [ "require_email_verification", "access", "allowed_emails", "allow_download", "watermark", "passcode", "screenshot_protection", "one_viewer_at_a_time", "expires_on" ] }, "open_directly": { "type": "boolean" }, "layout": { "type": "string" }, "theme": { "type": "string" }, "base_folder": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "own_folder": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "folder_id": { "type": "integer" }, "source": { "type": "string", "enum": [ "folder", "own_folder", "picked" ] }, "view_url": { "type": [ "string", "null" ], "format": "uri" }, "views": { "type": "integer" } }, "required": [ "id", "name", "folder_id", "source", "view_url", "views" ] } }, "people": { "type": "integer" }, "engagement": { "type": [ "integer", "null" ] }, "responses_count": { "type": "integer" }, "responses": { "type": "array", "items": { "$ref": "#/components/schemas/OfferResponse" } }, "sent_to": { "type": [ "string", "null" ] }, "created_by": { "type": [ "string", "null" ] }, "legacy_url": { "type": [ "string", "null" ], "format": "uri" }, "send_by_email": { "type": "string" } }, "required": [ "stored_status", "public_url", "panel_url", "message", "price_summary", "buttons", "protection", "open_directly", "layout", "theme", "base_folder", "own_folder", "files", "people", "engagement", "responses_count", "responses", "sent_to", "created_by", "legacy_url", "send_by_email" ] } ] }, "example": { "id": 31, "title": "Fit-out Q1", "status": "active", "expired": false, "client": { "first_name": "Anna", "last_name": "Nowak", "company": "Acme", "email": "anna@acme.com" }, "kind": "files", "url": "https://www.helprange.com/o/Xk2pQ9/", "document_views": 4, "page_visits": 2, "last_viewed_at": "2026-11-11T09:12:00+00:00", "sent_at": null, "created_at": "2026-11-11T08:00:00+00:00", "updated_at": "2026-11-11T08:00:00+00:00", "stored_status": "active", "public_url": "https://www.helprange.com/o/Xk2pQ9/", "panel_url": "https://www.helprange.com/user/offers/31/", "message": "Hi Anna, here is our proposal.", "price_summary": "from 2,400 EUR", "buttons": { "accept": { "shown": true, "label": "" }, "contact": { "shown": true, "label": "" }, "decline": { "shown": true, "label": "" } }, "protection": { "require_email_verification": true, "access": "domain", "allowed_emails": "anna@acme.com @acme.com", "allow_download": false, "watermark": false, "passcode": true, "screenshot_protection": false, "one_viewer_at_a_time": false, "expires_on": "2026-12-31" }, "open_directly": false, "layout": "classic", "theme": "light", "base_folder": null, "own_folder": { "id": 77, "name": "Offer - Fit-out Q1" }, "files": [ { "id": 250, "name": "proposal.pdf", "folder_id": 77, "source": "own_folder", "view_url": "https://www.helprange.com/view/5b0c.../proposal.pdf", "views": 3 } ], "people": 1, "engagement": 82, "responses_count": 1, "responses": [ { "kind": "declined the offer", "type": "decline", "offer_id": 31, "email": "anna@acme.com", "email_verified": true, "offer": "Fit-out Q1", "comment": "Too expensive", "document_id": null, "engagement": 64, "country": "PL", "at": "2026-11-11T10:00:00+00:00" } ], "sent_to": null, "created_by": "ann@acme.com", "legacy_url": null, "send_by_email": "HelpRange does not e-mail offers through the API or MCP. Send the offer link (url) yourself, or use \"Send by e-mail\" on the offer page in HelpRange." } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "links:write", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "update-offer-post", "x-hr-write": true } }, "/api/v2/offers/{offer_id}/files": { "post": { "operationId": "addOfferFiles", "summary": "Add documents to an offer", "description": "Adds documents from folders you can open (up to 50). Answers with the offer.", "tags": [ "Offers" ], "parameters": [ { "name": "offer_id", "in": "path", "required": true, "description": "Offer id (from List offers).", "schema": { "type": "integer", "minimum": 1 }, "example": 31 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "file_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "description": "Document ids." } }, "required": [ "file_ids" ] }, "example": { "file_ids": [ 252 ] } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "file_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "description": "Document ids." } }, "required": [ "file_ids" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/OfferRow" }, { "type": "object", "properties": { "stored_status": { "type": "string" }, "public_url": { "type": "string", "format": "uri" }, "panel_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "price_summary": { "type": "string" }, "buttons": { "type": "object", "properties": { "accept": { "type": "object", "properties": { "shown": { "type": "boolean" }, "label": { "type": "string" } }, "required": [ "shown", "label" ] }, "contact": { "type": "object", "properties": { "shown": { "type": "boolean" }, "label": { "type": "string" } }, "required": [ "shown", "label" ] }, "decline": { "type": "object", "properties": { "shown": { "type": "boolean" }, "label": { "type": "string" } }, "required": [ "shown", "label" ] } }, "required": [ "accept", "contact", "decline" ] }, "protection": { "type": "object", "properties": { "require_email_verification": { "type": "boolean" }, "access": { "type": "string" }, "allowed_emails": { "type": "string" }, "allow_download": { "type": "boolean" }, "watermark": { "type": "boolean" }, "passcode": { "type": "boolean" }, "screenshot_protection": { "type": "boolean" }, "one_viewer_at_a_time": { "type": "boolean" }, "expires_on": { "type": [ "string", "null" ], "format": "date" } }, "required": [ "require_email_verification", "access", "allowed_emails", "allow_download", "watermark", "passcode", "screenshot_protection", "one_viewer_at_a_time", "expires_on" ] }, "open_directly": { "type": "boolean" }, "layout": { "type": "string" }, "theme": { "type": "string" }, "base_folder": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "own_folder": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "folder_id": { "type": "integer" }, "source": { "type": "string", "enum": [ "folder", "own_folder", "picked" ] }, "view_url": { "type": [ "string", "null" ], "format": "uri" }, "views": { "type": "integer" } }, "required": [ "id", "name", "folder_id", "source", "view_url", "views" ] } }, "people": { "type": "integer" }, "engagement": { "type": [ "integer", "null" ] }, "responses_count": { "type": "integer" }, "responses": { "type": "array", "items": { "$ref": "#/components/schemas/OfferResponse" } }, "sent_to": { "type": [ "string", "null" ] }, "created_by": { "type": [ "string", "null" ] }, "legacy_url": { "type": [ "string", "null" ], "format": "uri" }, "send_by_email": { "type": "string" } }, "required": [ "stored_status", "public_url", "panel_url", "message", "price_summary", "buttons", "protection", "open_directly", "layout", "theme", "base_folder", "own_folder", "files", "people", "engagement", "responses_count", "responses", "sent_to", "created_by", "legacy_url", "send_by_email" ] } ] }, "example": { "id": 31, "title": "Fit-out Q1", "status": "active", "expired": false, "client": { "first_name": "Anna", "last_name": "Nowak", "company": "Acme", "email": "anna@acme.com" }, "kind": "files", "url": "https://www.helprange.com/o/Xk2pQ9/", "document_views": 4, "page_visits": 2, "last_viewed_at": "2026-11-11T09:12:00+00:00", "sent_at": null, "created_at": "2026-11-11T08:00:00+00:00", "updated_at": "2026-11-11T08:00:00+00:00", "stored_status": "active", "public_url": "https://www.helprange.com/o/Xk2pQ9/", "panel_url": "https://www.helprange.com/user/offers/31/", "message": "Hi Anna, here is our proposal.", "price_summary": "from 2,400 EUR", "buttons": { "accept": { "shown": true, "label": "" }, "contact": { "shown": true, "label": "" }, "decline": { "shown": true, "label": "" } }, "protection": { "require_email_verification": true, "access": "domain", "allowed_emails": "anna@acme.com @acme.com", "allow_download": false, "watermark": false, "passcode": true, "screenshot_protection": false, "one_viewer_at_a_time": false, "expires_on": "2026-12-31" }, "open_directly": false, "layout": "classic", "theme": "light", "base_folder": null, "own_folder": { "id": 77, "name": "Offer - Fit-out Q1" }, "files": [ { "id": 250, "name": "proposal.pdf", "folder_id": 77, "source": "own_folder", "view_url": "https://www.helprange.com/view/5b0c.../proposal.pdf", "views": 3 } ], "people": 1, "engagement": 82, "responses_count": 1, "responses": [ { "kind": "declined the offer", "type": "decline", "offer_id": 31, "email": "anna@acme.com", "email_verified": true, "offer": "Fit-out Q1", "comment": "Too expensive", "document_id": null, "engagement": 64, "country": "PL", "at": "2026-11-11T10:00:00+00:00" } ], "sent_to": null, "created_by": "ann@acme.com", "legacy_url": null, "send_by_email": "HelpRange does not e-mail offers through the API or MCP. Send the offer link (url) yourself, or use \"Send by e-mail\" on the offer page in HelpRange." } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "links:write", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "add-offer-files", "x-hr-write": true } }, "/api/v2/offers/{offer_id}/files/remove": { "post": { "operationId": "removeOfferFiles", "summary": "Remove documents from an offer", "description": "Takes documents out of the offer – the files stay in their folders. Answers with the offer.", "tags": [ "Offers" ], "parameters": [ { "name": "offer_id", "in": "path", "required": true, "description": "Offer id (from List offers).", "schema": { "type": "integer", "minimum": 1 }, "example": 31 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "file_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "description": "Document ids." } }, "required": [ "file_ids" ] }, "example": { "file_ids": [ 252 ] } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "file_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "description": "Document ids." } }, "required": [ "file_ids" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/OfferRow" }, { "type": "object", "properties": { "stored_status": { "type": "string" }, "public_url": { "type": "string", "format": "uri" }, "panel_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "price_summary": { "type": "string" }, "buttons": { "type": "object", "properties": { "accept": { "type": "object", "properties": { "shown": { "type": "boolean" }, "label": { "type": "string" } }, "required": [ "shown", "label" ] }, "contact": { "type": "object", "properties": { "shown": { "type": "boolean" }, "label": { "type": "string" } }, "required": [ "shown", "label" ] }, "decline": { "type": "object", "properties": { "shown": { "type": "boolean" }, "label": { "type": "string" } }, "required": [ "shown", "label" ] } }, "required": [ "accept", "contact", "decline" ] }, "protection": { "type": "object", "properties": { "require_email_verification": { "type": "boolean" }, "access": { "type": "string" }, "allowed_emails": { "type": "string" }, "allow_download": { "type": "boolean" }, "watermark": { "type": "boolean" }, "passcode": { "type": "boolean" }, "screenshot_protection": { "type": "boolean" }, "one_viewer_at_a_time": { "type": "boolean" }, "expires_on": { "type": [ "string", "null" ], "format": "date" } }, "required": [ "require_email_verification", "access", "allowed_emails", "allow_download", "watermark", "passcode", "screenshot_protection", "one_viewer_at_a_time", "expires_on" ] }, "open_directly": { "type": "boolean" }, "layout": { "type": "string" }, "theme": { "type": "string" }, "base_folder": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "own_folder": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "folder_id": { "type": "integer" }, "source": { "type": "string", "enum": [ "folder", "own_folder", "picked" ] }, "view_url": { "type": [ "string", "null" ], "format": "uri" }, "views": { "type": "integer" } }, "required": [ "id", "name", "folder_id", "source", "view_url", "views" ] } }, "people": { "type": "integer" }, "engagement": { "type": [ "integer", "null" ] }, "responses_count": { "type": "integer" }, "responses": { "type": "array", "items": { "$ref": "#/components/schemas/OfferResponse" } }, "sent_to": { "type": [ "string", "null" ] }, "created_by": { "type": [ "string", "null" ] }, "legacy_url": { "type": [ "string", "null" ], "format": "uri" }, "send_by_email": { "type": "string" } }, "required": [ "stored_status", "public_url", "panel_url", "message", "price_summary", "buttons", "protection", "open_directly", "layout", "theme", "base_folder", "own_folder", "files", "people", "engagement", "responses_count", "responses", "sent_to", "created_by", "legacy_url", "send_by_email" ] } ] }, "example": { "id": 31, "title": "Fit-out Q1", "status": "active", "expired": false, "client": { "first_name": "Anna", "last_name": "Nowak", "company": "Acme", "email": "anna@acme.com" }, "kind": "files", "url": "https://www.helprange.com/o/Xk2pQ9/", "document_views": 4, "page_visits": 2, "last_viewed_at": "2026-11-11T09:12:00+00:00", "sent_at": null, "created_at": "2026-11-11T08:00:00+00:00", "updated_at": "2026-11-11T08:00:00+00:00", "stored_status": "active", "public_url": "https://www.helprange.com/o/Xk2pQ9/", "panel_url": "https://www.helprange.com/user/offers/31/", "message": "Hi Anna, here is our proposal.", "price_summary": "from 2,400 EUR", "buttons": { "accept": { "shown": true, "label": "" }, "contact": { "shown": true, "label": "" }, "decline": { "shown": true, "label": "" } }, "protection": { "require_email_verification": true, "access": "domain", "allowed_emails": "anna@acme.com @acme.com", "allow_download": false, "watermark": false, "passcode": true, "screenshot_protection": false, "one_viewer_at_a_time": false, "expires_on": "2026-12-31" }, "open_directly": false, "layout": "classic", "theme": "light", "base_folder": null, "own_folder": { "id": 77, "name": "Offer - Fit-out Q1" }, "files": [ { "id": 250, "name": "proposal.pdf", "folder_id": 77, "source": "own_folder", "view_url": "https://www.helprange.com/view/5b0c.../proposal.pdf", "views": 3 } ], "people": 1, "engagement": 82, "responses_count": 1, "responses": [ { "kind": "declined the offer", "type": "decline", "offer_id": 31, "email": "anna@acme.com", "email_verified": true, "offer": "Fit-out Q1", "comment": "Too expensive", "document_id": null, "engagement": 64, "country": "PL", "at": "2026-11-11T10:00:00+00:00" } ], "sent_to": null, "created_by": "ann@acme.com", "legacy_url": null, "send_by_email": "HelpRange does not e-mail offers through the API or MCP. Send the offer link (url) yourself, or use \"Send by e-mail\" on the offer page in HelpRange." } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "links:write", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "remove-offer-files", "x-hr-write": true } }, "/api/v2/offers/{offer_id}/responses": { "get": { "operationId": "listResponsesOfOffer", "summary": "Responses to an offer", "description": "Every answer to this offer (accept, contact, decline with its reason in comment), newest first.", "tags": [ "Offers" ], "parameters": [ { "name": "offer_id", "in": "path", "required": true, "description": "Offer id (from List offers).", "schema": { "type": "integer", "minimum": 1 }, "example": 31 }, { "name": "kind", "in": "query", "required": false, "description": "Only this kind of answer.", "schema": { "type": "string", "enum": [ "accept", "contact", "decline" ] } }, { "name": "days", "in": "query", "required": false, "description": "Answers of the last N days, 1–3650.", "schema": { "type": "integer", "minimum": 1, "maximum": 3650 } }, { "name": "limit", "in": "query", "required": false, "description": "1–200 (default 50).", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "responses": { "type": "array", "items": { "$ref": "#/components/schemas/OfferResponse" } } }, "required": [ "responses" ] }, "example": { "responses": [ { "kind": "declined the offer", "type": "decline", "offer_id": 31, "email": "anna@acme.com", "email_verified": true, "offer": "Fit-out Q1", "comment": "Too expensive", "document_id": null, "engagement": 64, "country": "PL", "at": "2026-11-11T10:00:00+00:00" } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "analytics:read", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "list-responses-of-offer", "x-hr-write": false } }, "/api/v2/offer-responses": { "get": { "operationId": "listOfferResponses", "summary": "Offer responses", "description": "Clients who accepted an offer, asked to be contacted or declined it, across all offers – the last 90 days unless days is given.", "tags": [ "Offers" ], "parameters": [ { "name": "kind", "in": "query", "required": false, "description": "Only this kind of answer.", "schema": { "type": "string", "enum": [ "accept", "contact", "decline" ] } }, { "name": "days", "in": "query", "required": false, "description": "Answers of the last N days, 1–3650.", "schema": { "type": "integer", "minimum": 1, "maximum": 3650 } }, { "name": "limit", "in": "query", "required": false, "description": "1–200 (default 50).", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "responses": { "type": "array", "items": { "$ref": "#/components/schemas/OfferResponse" } } }, "required": [ "responses" ] }, "example": { "responses": [ { "kind": "declined the offer", "type": "decline", "offer_id": 31, "email": "anna@acme.com", "email_verified": true, "offer": "Fit-out Q1", "comment": "Too expensive", "document_id": null, "engagement": 64, "country": "PL", "at": "2026-11-11T10:00:00+00:00" } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "405": { "$ref": "#/components/responses/Error405" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "ApiKeyHeader": [] }, { "ApiKeyAuthorization": [] }, { "OAuth2": [ "helprange" ] } ], "x-required-scope": "analytics:read", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "list-offer-responses", "x-hr-write": false } }, "/public-api/directory": { "get": { "operationId": "v1ListDirectories", "summary": "v1: List directories", "description": "Folders you can open in the panel (administrators: every folder of the team).", "tags": [ "v1 (legacy)" ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "directories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } } }, "required": [ "directories" ] }, "example": { "directories": [ { "id": 17, "name": "sales_documents" }, { "id": 28, "name": "marketing_documents" } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/V1Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "LegacyApiKey": [] } ], "x-required-scope": "documents:read", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "v1-list-directories", "x-hr-write": false }, "post": { "operationId": "v1CreateDirectory", "summary": "v1: Create a directory", "description": "Creates a folder in your team. Both properties must be present; onlyIpAddresses may be null.", "tags": [ "v1 (legacy)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Folder name (unique in the team)." }, "onlyIpAddresses": { "type": [ "string", "null" ], "description": "Comma-separated IP addresses / CIDR ranges allowed to view, or null." } }, "required": [ "name", "onlyIpAddresses" ] }, "example": { "name": "my directory", "onlyIpAddresses": "34.124.145.56,101.127.144.90" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "link": { "type": "string", "description": "Path of the folder's link." } }, "required": [ "id", "link" ] }, "example": { "id": 260, "link": "/view-directory/8956d1e7b91b47e196a8040b1d4894f8" } } } }, "400": { "$ref": "#/components/responses/V1Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/V1Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "LegacyApiKey": [] } ], "x-required-scope": "documents:write", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "v1-create-directory", "x-hr-write": true } }, "/public-api/directory/{directory_id}/file": { "get": { "operationId": "v1ListFiles", "summary": "v1: List files in a directory", "description": "Documents of a folder with their links.", "tags": [ "v1 (legacy)" ], "parameters": [ { "name": "directory_id", "in": "path", "required": true, "description": "Folder id.", "schema": { "type": "integer", "minimum": 1 }, "example": 243 } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "file_links": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string", "description": "The link's label, or \"default\"." }, "uuid": { "type": "string", "description": "Default link only." }, "link": { "type": "string", "description": "Default link only: path of the link." } }, "required": [ "id", "name" ] } } }, "required": [ "id", "name", "file_links" ] } } }, "required": [ "files" ] }, "example": { "files": [ { "id": 250, "name": "marketing_copy.pdf", "file_links": [ { "id": 264, "uuid": "471dcc98874d4d0cb7c3eb1874c4e3db", "link": "/view/471dcc98874d4d0cb7c3eb1874c4e3db", "name": "default" } ] } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/V1Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "LegacyApiKey": [] } ], "x-required-scope": "documents:read", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "v1-list-files", "x-hr-write": false } }, "/public-api/directory/{directory_id}/upload/{filename}": { "post": { "operationId": "v1UploadFile", "summary": "v1: Upload a file to a directory", "description": "Uploads a file (multipart \"file\") under the given name. Uploading again with the same name replaces the file. 100 MB per file. A refused upload answers {\"result\": \"failure\", \"reason\": …} – 400 (too large, bad name), 429 (daily upload limit), 500 (our side).", "tags": [ "v1 (legacy)" ], "parameters": [ { "name": "directory_id", "in": "path", "required": true, "description": "Folder id.", "schema": { "type": "integer", "minimum": 1 }, "example": 38 }, { "name": "filename", "in": "path", "required": true, "description": "File name: letters, digits, \"-\", \"_\" and \".\".", "schema": { "type": "string", "pattern": "^[\\w\\-\\.]+$" }, "example": "proposal.pdf" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream" } }, "required": [ "file" ] } } }, "description": "multipart/form-data with the file." }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "default_link": { "type": "string" } }, "required": [ "id", "default_link" ] }, "example": { "id": 260, "default_link": "/view/8956d1e7b91b47e196a8040b1d4894f8" } } } }, "400": { "$ref": "#/components/responses/V1Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/V1Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Upload failed on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Failure" } } } } }, "security": [ { "BearerApiKey": [] }, { "LegacyApiKey": [] } ], "x-required-scope": "documents:write", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "v1-upload-file", "x-hr-write": true } }, "/public-api/file/{file_id}/statistics": { "get": { "operationId": "v1FileStatistics", "summary": "v1: File statistics", "description": "Views, average reading time (per page too), engagement score and every visit of a document.", "tags": [ "v1 (legacy)" ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "Document id.", "schema": { "type": "integer", "minimum": 1 }, "example": 124 } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "avg_time_per_page_seconds": { "type": "array", "items": { "type": "integer" } }, "total_views": { "type": "integer" }, "avg_time_seconds": { "type": [ "number", "null" ] }, "engagement_score": { "type": [ "number", "null" ] }, "recordings": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string" }, "ip": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "referrer_url": { "type": [ "string", "null" ] }, "read_time_sec": { "type": [ "integer", "null" ] } }, "required": [ "time", "ip", "country", "referrer_url", "read_time_sec" ] } } }, "required": [ "avg_time_per_page_seconds", "total_views", "avg_time_seconds", "engagement_score", "recordings" ] }, "example": { "engagement_score": 11.57, "total_views": 39, "avg_time_seconds": 24, "avg_time_per_page_seconds": [ 10, 6, 4, 9, 15 ], "recordings": [ { "time": "2026-10-24 10:34:56", "ip": "134.34.12.56", "country": "US", "referrer_url": "https://www.facebook.com", "read_time_sec": 100 } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/V1Forbidden" }, "404": { "$ref": "#/components/responses/V1Error404" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "LegacyApiKey": [] } ], "x-required-scope": "analytics:read", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "v1-file-statistics", "x-hr-write": false } }, "/public-api/file/{file_id}/link": { "post": { "operationId": "v1CreateLink", "summary": "v1: Create a link", "description": "A new labelled link for a document. label, isAllowDownloadingAndPrint, isOnlyOneUserViewing, passcode and expirationDate must be present (passcode and expirationDate may be null). Booleans: true / false, 1 / 0 or \"true\" / \"false\". An empty label, an expirationDate in the past or unreadable, or a negative / non-whole viewsLimit answer 400 with {\"result\": \"failure\", \"reason\"}. A protection setting your plan does not include answers 403 with {\"result\": \"failure\", \"reason\", \"plan_error\", \"features\"}.", "tags": [ "v1 (legacy)" ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "Document id.", "schema": { "type": "integer", "minimum": 1 }, "example": 124 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "description": "Name of the link (not empty)." }, "isAllowDownloadingAndPrint": { "type": [ "boolean", "integer", "string" ], "description": "Allow download & print. true / false (also 1 / 0 or \"true\" / \"false\")." }, "isOnlyOneUserViewing": { "type": [ "boolean", "integer", "string" ], "description": "Only one person can view at the same time. true / false (also 1 / 0 or \"true\" / \"false\")." }, "passcode": { "type": [ "string", "null" ], "description": "Only spaces = no passcode." }, "expirationDate": { "type": [ "string", "null" ], "format": "date", "description": "Last day, YYYY-MM-DD: today or later (a past day → 400)." }, "viewsLimit": { "type": [ "integer", "null" ], "minimum": 0, "description": "0 or null = no limit; negative → 400." }, "isForwardable": { "type": [ "boolean", "integer", "string" ], "description": "Default true. true / false (also 1 / 0 or \"true\" / \"false\")." }, "isScreenshotMask": { "type": [ "boolean", "integer", "string" ], "description": "Screenshot protection. true / false (also 1 / 0 or \"true\" / \"false\")." }, "isScreenAppOnly": { "type": [ "boolean", "integer", "string" ], "description": "Open only in the app. true / false (also 1 / 0 or \"true\" / \"false\")." }, "isWatermark": { "type": [ "boolean", "integer", "string" ], "description": "Watermark. true / false (also 1 / 0 or \"true\" / \"false\")." } }, "required": [ "label", "isAllowDownloadingAndPrint", "isOnlyOneUserViewing", "passcode", "expirationDate" ] }, "example": { "label": "someLabel", "isAllowDownloadingAndPrint": true, "isOnlyOneUserViewing": false, "isForwardable": true, "isScreenshotMask": false, "isWatermark": false, "passcode": "abcd", "expirationDate": "2026-12-24", "viewsLimit": 10 } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "link": { "type": "string" } }, "required": [ "id", "link" ] }, "example": { "id": 261, "link": "/view/8956d1e7b91b47e1a67a8040b1d4894f" } } } }, "400": { "$ref": "#/components/responses/V1Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/V1Forbidden" }, "404": { "$ref": "#/components/responses/V1Error404" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "LegacyApiKey": [] } ], "x-required-scope": "links:write", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "v1-create-link", "x-hr-write": true } }, "/public-api/guest": { "post": { "operationId": "v1CreateGuest", "summary": "v1: Add a guest", "description": "Creates a guest of your team by e-mail (an existing guest of the team with this e-mail is reused). Nobody is e-mailed. Counts towards the daily cap of 1,000 guests.", "tags": [ "v1 (legacy)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The guest's e-mail." } }, "required": [ "email" ] }, "example": { "email": "john@company.com" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" } }, "required": [ "id" ] }, "example": { "id": 5 } } } }, "400": { "$ref": "#/components/responses/V1Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/V1Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "LegacyApiKey": [] } ], "x-required-scope": "rooms:write", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "v1-create-guest", "x-hr-write": true } }, "/public-api/guest/{guest_id}/assign/{data_room_id}": { "post": { "operationId": "v1AssignGuest", "summary": "v1: Assign a guest to a data room", "description": "Adds a guest (from v1: Add a guest) to a data room and sends the room invitation e-mail (counted in the API e-mail budget). Already in the room: no new invitation.", "tags": [ "v1 (legacy)" ], "parameters": [ { "name": "guest_id", "in": "path", "required": true, "description": "Guest id.", "schema": { "type": "integer", "minimum": 1 }, "example": 7 }, { "name": "data_room_id", "in": "path", "required": true, "description": "Data room id.", "schema": { "type": "integer", "minimum": 1 }, "example": 10 } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests the team may make in the current clock hour.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current hour.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time when the hour ends.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "enum": [ "success" ] }, "already_in_room": { "type": "boolean" } }, "required": [ "result", "already_in_room" ] }, "example": { "result": "success", "already_in_room": false } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/V1Forbidden" }, "404": { "$ref": "#/components/responses/V1Error404" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "BearerApiKey": [] }, { "LegacyApiKey": [] } ], "x-required-scope": "rooms:write", "x-plan": "Max, Unlimited, Deal Room Pass, trial", "x-hr-slug": "v1-assign-guest", "x-hr-write": true } } }, "webhooks": { "document.opened": { "post": { "operationId": "webhook_document_opened", "summary": "document.opened", "tags": [ "Webhooks" ], "description": "Someone opened a shared link. Answer 2xx within 10 seconds; anything else is retried (1 min … 24 h, 9 attempts over about 3 days). 410 Gone turns the endpoint off. Verify HelpRange-Signature and deduplicate on id.", "parameters": [ { "name": "HelpRange-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=<unix seconds>,v1=<hex HMAC-SHA256(secret, \"<t>.<raw body>\")>. For 24 hours after a secret rotation a second v1= signed with the previous secret." }, { "name": "HelpRange-Event-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; the same on every retry." }, { "name": "HelpRange-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "HelpRange-Delivery-Attempt", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "1, 2, … (retries)." }, { "name": "X-HelpRange-Signature", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Legacy: hex HMAC-SHA256 of the raw body only." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_3f9c2b7e0d1a4c5b8e6f7a9d0c1b2e3f", "event": "document.opened", "api_version": "2026-11-15", "created_at": "2026-11-15T09:12:03.512345Z", "data": { "document": "Offer 2026", "file_id": 123, "link": "ACME", "link_id": 456, "viewer": "jane@acme.com", "country": "PL", "browser": "Chrome", "os": "Mac OS X", "opening_id": 789 } } } } }, "responses": { "200": { "description": "Received (any 2xx)." }, "410": { "description": "Gone – HelpRange turns the endpoint off." } } } }, "file_request.uploaded": { "post": { "operationId": "webhook_file_request_uploaded", "summary": "file_request.uploaded", "tags": [ "Webhooks" ], "description": "A file came in through a file request. Answer 2xx within 10 seconds; anything else is retried (1 min … 24 h, 9 attempts over about 3 days). 410 Gone turns the endpoint off. Verify HelpRange-Signature and deduplicate on id.", "parameters": [ { "name": "HelpRange-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=<unix seconds>,v1=<hex HMAC-SHA256(secret, \"<t>.<raw body>\")>. For 24 hours after a secret rotation a second v1= signed with the previous secret." }, { "name": "HelpRange-Event-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; the same on every retry." }, { "name": "HelpRange-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "HelpRange-Delivery-Attempt", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "1, 2, … (retries)." }, { "name": "X-HelpRange-Signature", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Legacy: hex HMAC-SHA256 of the raw body only." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_3f9c2b7e0d1a4c5b8e6f7a9d0c1b2e3f", "event": "file_request.uploaded", "api_version": "2026-11-15", "created_at": "2026-11-15T09:12:03.512345Z", "data": { "request": "Financials 2025", "directory": "Due diligence", "filename": "balance.pdf", "uploader_name": "Jan Kowalski", "uploader_email": "jan@example.com", "upload_id": 42 } } } } }, "responses": { "200": { "description": "Received (any 2xx)." }, "410": { "description": "Gone – HelpRange turns the endpoint off." } } } }, "room.access_requested": { "post": { "operationId": "webhook_room_access_requested", "summary": "room.access_requested", "tags": [ "Webhooks" ], "description": "A verified visitor asks to join a data room. Answer 2xx within 10 seconds; anything else is retried (1 min … 24 h, 9 attempts over about 3 days). 410 Gone turns the endpoint off. Verify HelpRange-Signature and deduplicate on id.", "parameters": [ { "name": "HelpRange-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=<unix seconds>,v1=<hex HMAC-SHA256(secret, \"<t>.<raw body>\")>. For 24 hours after a secret rotation a second v1= signed with the previous secret." }, { "name": "HelpRange-Event-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; the same on every retry." }, { "name": "HelpRange-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "HelpRange-Delivery-Attempt", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "1, 2, … (retries)." }, { "name": "X-HelpRange-Signature", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Legacy: hex HMAC-SHA256 of the raw body only." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_3f9c2b7e0d1a4c5b8e6f7a9d0c1b2e3f", "event": "room.access_requested", "api_version": "2026-11-15", "created_at": "2026-11-15T09:12:03.512345Z", "data": { "room": "Project Falcon", "room_id": 7, "request_id": 31, "email": "cfo@buyer.com", "name": "Anna Buyer", "company": "Buyer Ltd", "message": "Please add me.", "review_url": "https://www.helprange.com/user/outside-team/7/#access-requests" } } } } }, "responses": { "200": { "description": "Received (any 2xx)." }, "410": { "description": "Gone – HelpRange turns the endpoint off." } } } }, "nda.accepted": { "post": { "operationId": "webhook_nda_accepted", "summary": "nda.accepted", "tags": [ "Webhooks" ], "description": "A visitor accepted (or signed) the NDA of a link or data room. Answer 2xx within 10 seconds; anything else is retried (1 min … 24 h, 9 attempts over about 3 days). 410 Gone turns the endpoint off. Verify HelpRange-Signature and deduplicate on id.", "parameters": [ { "name": "HelpRange-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=<unix seconds>,v1=<hex HMAC-SHA256(secret, \"<t>.<raw body>\")>. For 24 hours after a secret rotation a second v1= signed with the previous secret." }, { "name": "HelpRange-Event-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; the same on every retry." }, { "name": "HelpRange-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "HelpRange-Delivery-Attempt", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "1, 2, … (retries)." }, { "name": "X-HelpRange-Signature", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Legacy: hex HMAC-SHA256 of the raw body only." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_3f9c2b7e0d1a4c5b8e6f7a9d0c1b2e3f", "event": "nda.accepted", "api_version": "2026-11-15", "created_at": "2026-11-15T09:12:03.512345Z", "data": { "nda": "Mutual NDA", "version": 2, "opened": "Project Falcon", "room_id": 7, "link_id": null, "name": "Anna Buyer", "company": "Buyer Ltd", "email": "cfo@buyer.com", "method": "click", "text_sha256": "9f86d0…", "signed_sha256": "", "sealed": true, "certificate_url": "https://www.helprange.com/nda/certificate/…" } } } } }, "responses": { "200": { "description": "Received (any 2xx)." }, "410": { "description": "Gone – HelpRange turns the endpoint off." } } } }, "document.acknowledged": { "post": { "operationId": "webhook_document_acknowledged", "summary": "document.acknowledged", "tags": [ "Webhooks" ], "description": "A data room guest confirmed reading a document. Answer 2xx within 10 seconds; anything else is retried (1 min … 24 h, 9 attempts over about 3 days). 410 Gone turns the endpoint off. Verify HelpRange-Signature and deduplicate on id.", "parameters": [ { "name": "HelpRange-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=<unix seconds>,v1=<hex HMAC-SHA256(secret, \"<t>.<raw body>\")>. For 24 hours after a secret rotation a second v1= signed with the previous secret." }, { "name": "HelpRange-Event-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; the same on every retry." }, { "name": "HelpRange-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "HelpRange-Delivery-Attempt", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "1, 2, … (retries)." }, { "name": "X-HelpRange-Signature", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Legacy: hex HMAC-SHA256 of the raw body only." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_3f9c2b7e0d1a4c5b8e6f7a9d0c1b2e3f", "event": "document.acknowledged", "api_version": "2026-11-15", "created_at": "2026-11-15T09:12:03.512345Z", "data": { "document": "Policy.pdf", "file_id": 123, "version": "3", "room": "Onboarding", "room_id": 7, "email": "new.hire@acme.com", "response_id": 55 } } } } }, "responses": { "200": { "description": "Received (any 2xx)." }, "410": { "description": "Gone – HelpRange turns the endpoint off." } } } }, "offer.accepted": { "post": { "operationId": "webhook_offer_accepted", "summary": "offer.accepted", "tags": [ "Webhooks" ], "description": "A reader accepted an offer. Answer 2xx within 10 seconds; anything else is retried (1 min … 24 h, 9 attempts over about 3 days). 410 Gone turns the endpoint off. Verify HelpRange-Signature and deduplicate on id.", "parameters": [ { "name": "HelpRange-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=<unix seconds>,v1=<hex HMAC-SHA256(secret, \"<t>.<raw body>\")>. For 24 hours after a secret rotation a second v1= signed with the previous secret." }, { "name": "HelpRange-Event-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; the same on every retry." }, { "name": "HelpRange-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "HelpRange-Delivery-Attempt", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "1, 2, … (retries)." }, { "name": "X-HelpRange-Signature", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Legacy: hex HMAC-SHA256 of the raw body only." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_3f9c2b7e0d1a4c5b8e6f7a9d0c1b2e3f", "event": "offer.accepted", "api_version": "2026-11-15", "created_at": "2026-11-15T09:12:03.512345Z", "data": { "document": "Offer 2026", "file_id": 123, "link_id": 456, "folder_id": null, "email": "bob@corp.com", "email_verified": true, "comment": "Let us go ahead.", "engagement": 87, "response_id": 56, "offer_id": 9 } } } } }, "responses": { "200": { "description": "Received (any 2xx)." }, "410": { "description": "Gone – HelpRange turns the endpoint off." } } } }, "offer.declined": { "post": { "operationId": "webhook_offer_declined", "summary": "offer.declined", "tags": [ "Webhooks" ], "description": "A reader declined an offer. Answer 2xx within 10 seconds; anything else is retried (1 min … 24 h, 9 attempts over about 3 days). 410 Gone turns the endpoint off. Verify HelpRange-Signature and deduplicate on id.", "parameters": [ { "name": "HelpRange-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=<unix seconds>,v1=<hex HMAC-SHA256(secret, \"<t>.<raw body>\")>. For 24 hours after a secret rotation a second v1= signed with the previous secret." }, { "name": "HelpRange-Event-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; the same on every retry." }, { "name": "HelpRange-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "HelpRange-Delivery-Attempt", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "1, 2, … (retries)." }, { "name": "X-HelpRange-Signature", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Legacy: hex HMAC-SHA256 of the raw body only." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_3f9c2b7e0d1a4c5b8e6f7a9d0c1b2e3f", "event": "offer.declined", "api_version": "2026-11-15", "created_at": "2026-11-15T09:12:03.512345Z", "data": { "document": "Offer 2026", "file_id": 123, "link_id": 456, "folder_id": null, "email": "bob@corp.com", "email_verified": true, "comment": "", "engagement": 40, "response_id": 57, "offer_id": 9 } } } } }, "responses": { "200": { "description": "Received (any 2xx)." }, "410": { "description": "Gone – HelpRange turns the endpoint off." } } } }, "offer.contact_requested": { "post": { "operationId": "webhook_offer_contact_requested", "summary": "offer.contact_requested", "tags": [ "Webhooks" ], "description": "A reader asked to be contacted about an offer or document. Answer 2xx within 10 seconds; anything else is retried (1 min … 24 h, 9 attempts over about 3 days). 410 Gone turns the endpoint off. Verify HelpRange-Signature and deduplicate on id.", "parameters": [ { "name": "HelpRange-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=<unix seconds>,v1=<hex HMAC-SHA256(secret, \"<t>.<raw body>\")>. For 24 hours after a secret rotation a second v1= signed with the previous secret." }, { "name": "HelpRange-Event-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; the same on every retry." }, { "name": "HelpRange-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "HelpRange-Delivery-Attempt", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "1, 2, … (retries)." }, { "name": "X-HelpRange-Signature", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Legacy: hex HMAC-SHA256 of the raw body only." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_3f9c2b7e0d1a4c5b8e6f7a9d0c1b2e3f", "event": "offer.contact_requested", "api_version": "2026-11-15", "created_at": "2026-11-15T09:12:03.512345Z", "data": { "document": "Offer 2026", "file_id": 123, "link_id": 456, "folder_id": null, "email": "bob@corp.com", "email_verified": false, "comment": "Call me on Monday.", "engagement": null, "response_id": 58, "offer_id": 9 } } } } }, "responses": { "200": { "description": "Received (any 2xx)." }, "410": { "description": "Gone – HelpRange turns the endpoint off." } } } } }, "components": { "securitySchemes": { "BearerApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "hr_live_… / hr_test_…", "description": "A team API key from Settings → API keys: \"Authorization: Bearer hr_live_…\" (live data) or \"hr_test_…\" (the sandbox). Each key has scopes – see x-required-scope on every operation. Recommended." }, "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "A team API key (hr_live_… / hr_test_…) or the legacy personal key (profile page, full access)." }, "ApiKeyAuthorization": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "\"Api-Key <key>\", or the bare key." }, "OAuth2": { "type": "oauth2", "description": "OAuth 2.1 access token of the HelpRange MCP connector (authorization code + PKCE S256; dynamic client registration at /oauth/register), sent as \"Authorization: Bearer <token>\".", "flows": { "authorizationCode": { "authorizationUrl": "https://www.helprange.com/oauth/authorize", "tokenUrl": "https://www.helprange.com/oauth/token", "refreshUrl": "https://www.helprange.com/oauth/token", "scopes": { "helprange": "Act as the signed-in user, with the same rights as in the panel." } } } }, "LegacyApiKey": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "v1 /public-api: the bare API key in Authorization (a team key also as \"Bearer hr_live_…\")." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "What went wrong, in a sentence you can show to a person." }, "code": { "type": "string", "description": "Machine-readable reason, only on some errors (e.g. FILE_TOO_LARGE, REQUEST_TOO_LARGE, UPLOAD_LIMIT, ROOM_FROZEN, TOO_MANY_RECIPIENTS)." } }, "required": [ "error" ] }, "RateLimitError": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "RATE_LIMITED", "DAILY_LIMIT", "PAUSED" ] }, "retry_after": { "type": "integer", "minimum": 1, "description": "Seconds to wait (also in Retry-After)." } }, "required": [ "error", "code", "retry_after" ], "description": "A usage limit was reached (plus/api_guard.py). The request was not carried out." }, "V1ValidationError": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "Validation Error", "Not Found Error", "Conflict Error" ] }, "message": { "type": "string" } }, "required": [ "status", "message" ], "description": "v1 /public-api error body." }, "V1Failure": { "type": "object", "properties": { "result": { "type": "string", "enum": [ "failure" ] }, "reason": { "type": "string" } }, "required": [ "result", "reason" ], "description": "v1 upload / link refusal." }, "ScopeError": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "insufficient_scope" ] }, "required_scope": { "type": "string", "description": "The scope this endpoint needs for this method." }, "key_scopes": { "type": "array", "items": { "type": "string" }, "description": "The scopes the key has." } }, "required": [ "error", "code", "required_scope" ], "description": "A team API key without the scope the endpoint needs (plus/api_keys.py)." }, "WebhookEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event id (= HelpRange-Event-Id header); the same on retries and resends – deduplicate on it." }, "event": { "type": "string", "description": "Event type, e.g. document.opened." }, "api_version": { "type": "string", "description": "Payload version, e.g. 2026-11-15." }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "description": "Depends on the event; new fields may be added." }, "test": { "type": "boolean", "description": "Only on test events sent from the delivery log." } }, "required": [ "id", "event", "api_version", "created_at", "data" ], "description": "The envelope of every webhook request (plus/webhooks.payload_for)." }, "FileInfo": { "type": "object", "properties": { "id": { "type": "integer", "description": "Document id." }, "name": { "type": "string", "description": "File name." }, "folder_id": { "type": "integer", "description": "Folder the document is in." }, "type": { "type": "string", "enum": [ "document", "video", "link", "download-only file" ] }, "pages": { "type": [ "integer", "null" ], "description": "Pages (documents shown in the viewer)." }, "default_link": { "type": [ "string", "null" ], "format": "uri", "description": "The document's default share link." } }, "required": [ "id", "name", "folder_id", "type", "pages", "default_link" ] }, "Place": { "type": "object", "properties": { "subfolder_id": { "type": [ "integer", "null" ] }, "subfolder": { "type": [ "string", "null" ] }, "path": { "type": "string", "description": "Where the document is: \"Folder\" or \"Folder › Subfolder\"." } }, "required": [ "subfolder_id", "subfolder", "path" ] }, "ShareLink": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string", "format": "uri" }, "label": { "type": "string", "description": "\"default\" for the document's default link." }, "allow_download": { "type": "boolean" }, "passcode": { "type": "boolean", "description": "Whether a passcode is set (never the passcode itself)." }, "expires_on": { "type": [ "string", "null" ], "format": "date" }, "views_limit": { "type": [ "integer", "null" ] }, "watermark": { "type": "boolean" }, "require_email": { "type": "boolean", "description": "Viewers enter their e-mail before opening." }, "disallow_forwarding": { "type": "boolean", "description": "Only the first person who opens the link can use it." }, "one_viewer_at_a_time": { "type": "boolean" } }, "required": [ "id", "url", "label", "allow_download", "passcode", "expires_on", "views_limit", "watermark", "require_email", "disallow_forwarding", "one_viewer_at_a_time" ] }, "View": { "type": "object", "properties": { "viewer": { "type": "string", "description": "Verified e-mail of the viewer, or \"anonymous\"." }, "opened_at": { "type": "string", "format": "date-time" }, "seconds_read": { "type": [ "integer", "null" ] }, "country": { "type": [ "string", "null" ] }, "downloaded": { "type": "boolean" }, "document": { "type": "string" }, "document_id": { "type": "integer" } }, "required": [ "viewer", "opened_at", "seconds_read", "country", "downloaded", "document", "document_id" ] }, "Envelope": { "type": "object", "properties": { "id": { "type": "string", "description": "E-signature request id." }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "sent", "expired", "completed", "declined", "voided" ] }, "status_label": { "type": "string" }, "sender": { "type": [ "string", "null" ] }, "document_id": { "type": [ "integer", "null" ] }, "data_room": { "type": [ "string", "null" ], "description": "Data room name for room signature requests." }, "created_at": { "type": "string", "format": "date-time" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "ended_at": { "type": [ "string", "null" ], "format": "date-time" }, "signed": { "type": "integer", "description": "Recipients who signed or reviewed." }, "recipients_count": { "type": "integer" }, "url": { "type": "string", "format": "uri", "description": "The request in the HelpRange panel." } }, "required": [ "id", "title", "status", "status_label", "sender", "document_id", "data_room", "created_at", "sent_at", "expires_at", "completed_at", "ended_at", "signed", "recipients_count", "url" ] }, "OfferClient": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "company": { "type": "string" }, "email": { "type": "string" } } }, "OfferRow": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "accepted", "declined", "expired", "closed" ] }, "expired": { "type": "boolean" }, "client": { "$ref": "#/components/schemas/OfferClient" }, "kind": { "type": "string" }, "url": { "type": "string", "format": "uri", "description": "The offer link to send to the client." }, "document_views": { "type": "integer" }, "page_visits": { "type": "integer" }, "last_viewed_at": { "type": [ "string", "null" ], "format": "date-time" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "status", "expired", "client", "kind", "url", "document_views", "page_visits", "last_viewed_at", "sent_at", "created_at", "updated_at" ] }, "OfferResponse": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "accepted the offer", "asked to be contacted", "declined the offer" ] }, "type": { "type": "string", "enum": [ "accept", "contact", "decline" ] }, "offer_id": { "type": [ "integer", "null" ] }, "email": { "type": [ "string", "null" ] }, "email_verified": { "type": "boolean" }, "offer": { "type": "string", "description": "Offer (or document) name." }, "comment": { "type": [ "string", "null" ], "description": "The client's comment / decline reason." }, "document_id": { "type": [ "integer", "null" ] }, "engagement": { "type": [ "integer", "null" ] }, "country": { "type": [ "string", "null" ] }, "at": { "type": "string", "format": "date-time" } }, "required": [ "kind", "type", "offer_id", "email", "email_verified", "offer", "comment", "document_id", "engagement", "country", "at" ] }, "Subfolder": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "position": { "type": "integer" }, "folder_id": { "type": "integer" }, "documents_count": { "type": "integer" } }, "required": [ "id", "name", "position", "folder_id" ] }, "RoomFolder": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "position": { "type": "integer" }, "data_room_id": { "type": "integer" }, "documents_count": { "type": "integer" } }, "required": [ "id", "name", "position", "data_room_id" ] }, "RoomDocument": { "type": "object", "properties": { "room_link_id": { "type": "integer", "description": "The document's place in the room (use with /folders/move)." }, "document_id": { "type": "integer" }, "name": { "type": "string" }, "number": { "type": "string", "description": "Index number, e.g. \"1.2\" (\"\" while waiting for approval)." }, "group": { "type": [ "string", "null" ], "description": "The folder guests see it under (null at the top level)." }, "room_folder_id": { "type": [ "integer", "null" ] }, "room_folder": { "type": [ "string", "null" ] }, "folder_id": { "type": "integer" }, "folder": { "type": "string" }, "subfolder_id": { "type": [ "integer", "null" ] }, "subfolder": { "type": [ "string", "null" ] }, "path": { "type": "string" }, "approval": { "type": "string", "enum": [ "published", "pending", "changes" ] } }, "required": [ "room_link_id", "document_id", "name", "number", "group", "room_folder_id", "room_folder", "folder_id", "folder", "subfolder_id", "subfolder", "path", "approval" ] }, "IndexNode": { "type": "object", "description": "A folder (with children) or a document of the room index.", "properties": { "type": { "type": "string", "enum": [ "folder", "document" ] }, "number": { "type": "string" }, "name": { "type": "string" }, "folder_id": { "type": [ "integer", "null" ] }, "subfolder_id": { "type": [ "integer", "null" ] }, "room_folder_id": { "type": [ "integer", "null" ] }, "document_id": { "type": "integer" }, "room_link_id": { "type": "integer" }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/IndexNode" } } }, "required": [ "type", "number", "name" ] }, "Question": { "type": "object", "properties": { "id": { "type": "integer" }, "number": { "type": "string", "description": "e.g. \"Q7\"." }, "status": { "type": "string", "enum": [ "new", "assigned", "answered", "approved", "declined" ] }, "status_label": { "type": "string" }, "category": { "type": "string" }, "text": { "type": "string" }, "source": { "type": "string" }, "asked_by": { "type": [ "string", "null" ] }, "document_id": { "type": [ "integer", "null" ] }, "document": { "type": [ "string", "null" ] }, "index": { "type": [ "string", "null" ] }, "page": { "type": [ "integer", "null" ] }, "visibility": { "type": "string", "enum": [ "all_guests", "private" ] }, "request_item_id": { "type": [ "integer", "null" ] }, "assignee": { "type": [ "string", "null" ] }, "answer": { "type": [ "string", "null" ] }, "answer_approved": { "type": "boolean" }, "decline_reason": { "type": [ "string", "null" ] }, "asked_at": { "type": "string", "format": "date-time" }, "answered_at": { "type": [ "string", "null" ], "format": "date-time" }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "number", "status", "status_label", "category", "text", "source", "asked_by", "document_id", "document", "index", "page", "visibility", "request_item_id", "assignee", "answer", "answer_approved", "decline_reason", "asked_at", "answered_at", "approved_at" ] }, "RequestItem": { "type": "object", "properties": { "id": { "type": "integer" }, "number": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "priority": { "type": "string", "enum": [ "high", "medium", "low" ] }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "assignee": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "open", "in_progress", "provided", "na" ] }, "status_label": { "type": "string" }, "documents": { "type": "array", "items": { "type": "object", "properties": { "document_id": { "type": "integer" }, "index": { "type": "string" } }, "required": [ "document_id", "index" ] } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "number", "category", "description", "priority", "due_date", "assignee", "status", "status_label", "documents", "created_at", "updated_at" ] } }, "responses": { "Error400": { "description": "Invalid input – the message says which parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error401": { "description": "Missing or invalid API key / OAuth token. Team keys: code invalid_key, key_revoked, key_expired or key_owner_removed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error402": { "description": "Your plan does not include the REST API (or this feature).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error404": { "description": "Not found – or not yours (the API never says which).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error409": { "description": "The data room is frozen, or the signed PDF is not ready yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error413": { "description": "The file or the request body is over the upload limit (code FILE_TOO_LARGE / REQUEST_TOO_LARGE).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error423": { "description": "The target data room is frozen (code ROOM_FROZEN).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error403": { "description": "The team API key lacks the scope this endpoint needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeError" }, "example": { "error": "This API key does not have the \"rooms:write\" scope needed for POST /api/v2/data-rooms/12/guests.", "code": "insufficient_scope", "required_scope": "rooms:write", "key_scopes": [ "documents:read", "rooms:read" ] } } } }, "Error405": { "description": "Wrong HTTP method for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TooManyRequests": { "description": "A usage limit was reached – wait Retry-After seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "example": { "error": "Too many requests: your team's API limit is 3600 requests an hour. Try again in 12 minutes.", "code": "RATE_LIMITED", "retry_after": 712 } } } }, "V1Error400": { "description": "Invalid input – the message says which parameter.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V1ValidationError" }, { "$ref": "#/components/schemas/V1Failure" } ] }, "example": { "status": "Validation Error", "message": "property is missing" } } } }, "V1Error404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ValidationError" } } } }, "V1Forbidden": { "description": "v1: the key is invalid, or the folder / file / guest / data room is not yours (HTML page unless you send Accept: application/json). Team keys (v1 and v2): code insufficient_scope with required_scope – the key lacks the scope this endpoint needs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string" }, "error": { "type": "string" }, "reason": { "type": "string" } } } }, "text/html": { "schema": { "type": "string" } } } } } }, "x-rate-limits": { "team_hour": 3600, "team_minute": 120, "team_writes_hour": 300, "team_links_day": 2000, "team_guests_day": 1000, "team_emails_hour": 100, "team_emails_day": 500, "team_emails_request": 50, "ip_hour": 4000, "ip_auth_fail_hour": 60, "team_errors_hour": 300, "pause_minutes": 15 } }