--- title: HelpRange for Developers: REST API, Webhooks, MCP, SSO & SCIM | HelpRange url: https://www.helprange.com/developers --- Developers # Build on HelpRange Upload documents, create protected share links, run data rooms and pull page-by-page analytics into your own systems – with a REST API, signed webhooks, an MCP server for AI assistants, and SSO with SCIM provisioning. [API reference](https://www.helprange.com/developers/api) [Build with AI](https://www.helprange.com/developers/ai) [Start a free trial](https://www.helprange.com/#signUpSection) [### REST API Files, share links, data rooms, guests, Q&A, e-signature requests, offers and statistics as JSON – with an OpenAPI 3.1 file.](#rest-api) [### Build with AI One-click MCP install for Cursor, VS Code and Claude, llms.txt, an AGENTS.md section and agent framework examples.](#ai) [### Webhooks Signed JSON events with retries and a delivery log when a document is opened, an NDA is accepted or an offer is answered.](#webhooks) [### MCP server Connect Claude, ChatGPT, Cursor or any MCP client with OAuth – your documents and analytics in the chat.](#mcp) [### SSO & SCIM SAML 2.0 or OpenID Connect sign-in, and SCIM 2.0 provisioning from Okta or Microsoft Entra ID.](#sso-scim) [### Zapier, Make & n8n The same API behind ready-made triggers and actions – no code needed.](#no-code) [### Embeds Put our free calculators and checklists on your own site with one iframe.](#embed) ## REST API REST API v2 returns JSON and covers what your team does in the panel: folders and documents, uploads, share links with their protection settings, data rooms (guests, folders, access requests, Q&A, request lists), e-signature requests, offers and offer responses, store sales and the team's activity. It is the API behind our Zapier, Make and n8n apps. The older `/public-api` endpoints keep working. Base URL ``` https://www.helprange.com/api/v2 ``` **Plans:** the REST API is part of Max, Unlimited, the Deal Room Pass and the 7-day trial (`/me`, `/folders` and buyer access also work on Pro). Every endpoint, parameter, scope and response is in the [API reference](https://www.helprange.com/developers/api) – one page per operation with curl, JavaScript and Python samples and a console to try it – and in the [OpenAPI 3.1 file](https://www.helprange.com/developers/openapi.json) for Postman, Insomnia and code generators. ## Build with AI Everything an AI tool or coding agent needs to work with HelpRange: - **MCP server** `https://www.helprange.com/mcp` with OAuth – [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=helprange&config=eyJ1cmwiOiJodHRwczovL3d3dy5oZWxwcmFuZ2UuY29tL21jcCJ9), [Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22helprange%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fwww.helprange.com%2Fmcp%22%7D), Claude Code: `claude mcp add --transport http helprange https://www.helprange.com/mcp` , and HelpRange in Claude's connectors directory. - **Docs for LLMs**: [llms.txt](https://www.helprange.com/developers/llms.txt) and [llms-full.txt](https://www.helprange.com/developers/llms-full.txt) (the whole API, webhooks and MCP reference as Markdown), generated from the OpenAPI file. - **[AGENTS.md section](https://www.helprange.com/developers/agents.md)** to drop into your repository, a **Custom GPT action** from the OpenAPI file, and examples for the Vercel AI SDK, LangChain, LlamaIndex and the OpenAI Agents SDK. - **[Recipes](https://www.helprange.com/developers/recipes)**: send a deck to investors and see who read it, build a data room with an NDA, post to Slack when a document is opened. [Build with AI](https://www.helprange.com/developers/ai) ## Authentication Administrators create team API keys in **Settings → API keys**: one key per integration, each with only the [scopes](https://www.helprange.com/developers/keys#scopes) it needs, an optional expiry, rotation with an overlap and instant revocation. Send the key as `Authorization: Bearer hr_live_…` (`X-API-Key` works too). Keys starting with `hr_test_` work on a [sandbox](https://www.helprange.com/developers/keys#sandbox) with sample data that never sends e-mail. The legacy key on your profile page and OAuth access tokens of the MCP connector keep working. Keep keys on your server – never in client-side code or a public repository. ``` $ export HELPRANGE_API_KEY=hr_test_… $ curl https://www.helprange.com/api/v2/me \ -H "Authorization: Bearer $HELPRANGE_API_KEY" ``` Errors come back as JSON `{"error": "…"}` with the HTTP status: 400 invalid parameter, 401 missing, invalid, revoked or expired key, 402 not in your plan, 403 the key lacks the scope (`insufficient_scope`), 404 not found or no access, 429 usage limit. Details: [API keys, scopes and sandbox](https://www.helprange.com/developers/keys). ## Example requests ### List your latest documents ``` $ curl "https://www.helprange.com/api/v2/documents?folder_id=38" \ -H "X-API-Key: $HELPRANGE_API_KEY" ``` ### Upload a file into a folder ``` $ curl -X POST https://www.helprange.com/api/v2/files \ -H "X-API-Key: $HELPRANGE_API_KEY" \ -F "file=@proposal.pdf" \ -F "folder_id=38" ``` ### Create a protected share link ``` $ curl -X POST https://www.helprange.com/api/v2/files/250/links \ -H "X-API-Key: $HELPRANGE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"label": "ACME – Anna", "require_email": true, "watermark": true, "allow_download": false, "expires_on": "2026-12-31"}' ``` Answers `201` with the link: `id`, `url`, `label` and its settings. ### Time per page and recent views of a document ``` $ curl "https://www.helprange.com/api/v2/documents/250?recent_views=5" \ -H "X-API-Key: $HELPRANGE_API_KEY" ``` ``` { "id": 250, "name": "proposal.pdf", "pages": 12, "views": 39, "avg_seconds_per_page": [{"page": 1, "avg_seconds": 21}, {"page": 2, "avg_seconds": 64}], "recent_views": [{"viewer": "anna@client.com", "seconds_read": 312, "country": "DE", …}], … } ``` ### Invite a guest to a data room ``` $ curl -X POST https://www.helprange.com/api/v2/data-rooms/10/guests \ -H "X-API-Key: $HELPRANGE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"email": "investor@fund.com"}' ``` More: [data rooms](https://www.helprange.com/developers/api#data-rooms), [e-signature requests](https://www.helprange.com/developers/api/create-signature-request), [offers](https://www.helprange.com/developers/api/create-offer), [team activity](https://www.helprange.com/developers/api/list-activity) and polling triggers for new views and uploads (`/api/v2/views`, `/api/v2/uploads`). ## Usage limits Counted per team, for the REST API, `/public-api` and the MCP server together: | Limit | Value | |---|---| | Requests | 3,600 an hour, at most 120 a minute | | Write requests (uploads, new links, guests, offers, e-signature …) | 300 an hour | | Share links created through the API | 2,000 a day | | Guests created or invited through the API | 1,000 a day | | Requests per IP address | 4,000 an hour | Over a limit the API answers `429` with a `Retry-After` header and `{"error", "code", "retry_after"}`. E-mail and upload limits and the full table: [usage limits](https://www.helprange.com/developers/api#limits). ## Webhooks Add an https endpoint (and/or a Slack incoming webhook) in **Settings → Integrations** in the HelpRange panel – team administrators, every plan including Free. HelpRange then POSTs a signed JSON event to it, retries failed deliveries for about 3 days and keeps a 30-day delivery log where you can resend an event or send a test one. Full guide: [webhooks](https://www.helprange.com/developers/webhooks). | Event | When | |---|---| | `document.opened` | Someone opened a shared link (bots and link previews do not count). | | `document.acknowledged` | A data room guest confirmed they read a document that requires acknowledgement. | | `nda.accepted` | A visitor accepted or signed the NDA before access. | | `room.access_requested` | A verified visitor asked to join a data room. | | `file_request.uploaded` | A file arrived through a file request. | | `offer.accepted` | A client accepted an offer. | | `offer.declined` | A client declined an offer. | | `offer.contact_requested` | A client asked to be contacted about an offer. | Request HelpRange sends ``` POST https://your-endpoint.example.com/helprange Content-Type: application/json HelpRange-Event-Id: evt_3f9c2b7e0d1a4c5b8e6f7a9d0c1b2e3f HelpRange-Event-Type: document.opened HelpRange-Signature: t=unix seconds,v1=hex HMAC-SHA256 of "t.raw body" {"id": "evt_3f9c2b7e0d1a4c5b8e6f7a9d0c1b2e3f", "event": "document.opened", "api_version": "2026-11-15", "created_at": "2026-11-15T09:12:44.512345Z", "data": {"document": "proposal", "file_id": 250, "link": "ACME – Anna", "link_id": 264, "viewer": "anna@client.com", "country": "DE", "browser": "Chrome", "os": "Mac OS X", "opening_id": 91822}} ``` Verify the signature (Python) ``` import hashlib, hmac, time def verify_helprange(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool: parts = [p.split('=', 1) for p in (header or '').split(',') if '=' in p] t = next((v for k, v in parts if k == 't'), None) if t is None or not t.isdigit() or abs(time.time() - int(t)) > tolerance: return False expected = hmac.new(secret.encode(), t.encode() + b'.' + raw_body, hashlib.sha256).hexdigest() return any(k == 'v1' and hmac.compare_digest(v, expected) for k, v in parts) ``` The signing secret (`whsec_…`) is shown once in Integrations when it is generated or rotated. Answer 2xx within 10 seconds and do slow work in the background; anything else is retried (1 minute … 24 hours, 9 attempts). Delivery is at-least-once – deduplicate on `id`. The legacy `X-HelpRange-Signature` header (HMAC of the raw body only) is still sent for existing integrations. ## MCP server HelpRange runs a remote MCP server (Streamable HTTP) with OAuth 2.1 sign-in – no API key to copy. Your assistant can list documents and views, read a document's text, check data rooms, send e-signature requests, create offers and share links – with your rights in the panel. It never deletes a document. ``` https://www.helprange.com/mcp ``` 1. **Claude** (claude.ai, Desktop): Settings → Connectors → Add custom connector → paste the URL → Connect, then log in to HelpRange and click “Allow access”. 2. **ChatGPT**: Settings → Connectors (developer mode) → Create → paste the URL, authentication OAuth → log in and allow. 3. **Cursor, VS Code and others**: add a remote (Streamable HTTP) MCP server with the URL; the client discovers OAuth and opens the HelpRange sign-in page. One-click links and config snippets: [Build with AI](https://www.helprange.com/developers/ai). Included in the trial, Pro, Max, Unlimited and the Deal Room Pass. Connected apps are listed in Integrations, where you can disconnect them. All tools: [MCP server setup](https://www.helprange.com/mcp-server). ## SSO & SCIM **Single sign-on** with SAML 2.0 or OpenID Connect – Okta, Microsoft Entra ID, Google Workspace, Auth0, OneLogin, JumpCloud and other standard providers. Verified e-mail domains (DNS TXT record), just-in-time accounts, “Require SSO”, single logout and encrypted SAML assertions. **SCIM 2.0 provisioning** for Okta and Microsoft Entra ID: users are created, updated and switched off from your identity provider; switching someone off ends their sessions and keeps their documents with the team. Groups are synced but do not change roles or folder access. ``` SCIM base URL https://www.helprange.com/scim/v2// Authentication Authorization: Bearer Resources Users, Groups, ServiceProviderConfig, ResourceTypes, Schemas ``` Part of Unlimited and the Deal Room Pass. Setup: [single sign-on](https://www.helprange.com/feature-sso). ## Zapier, Make & n8n Ready-made triggers (new document view, new file from a client) and actions (upload a document, create a share link, give a buyer access) on top of the same REST API: [Zapier](https://www.helprange.com/zapier-integration), [Make](https://www.helprange.com/make-integration), [n8n](https://www.helprange.com/n8n-integration). ## Embeds The browser tools among our [free tools](https://www.helprange.com/tools) – calculators, checklists and generators – can be put on your own site with an iframe: open the tool and copy the code under “Embed this … on your website”. The tool runs in your visitors' browser; keep the credit line. ``` ```