---
title: HelpRange: Next-Gen Data Room For Documents Protection & Analytics
description: HelpRange is a cutting-edge virtual data room platform for document access controls and in-depth analytics, ensuring superior management and usage insights for your documents.
url: https://www.helprange.com/api-documentation
---

Developers

# Public HelpRange API Documentation

Upload files, create secure links and data room access, and pull analytics into your own systems with a simple REST API.

[API reference](https://www.helprange.com/developers/api) – every operation with code samples and a console to try it · [OpenAPI 3.1 file](https://www.helprange.com/developers/openapi.json)

## What's new

**2026-11-21 · Delete files, full link URLs, per-session links.** [Delete file](#delete-file) (`POST /public-api/file/<id>/delete`, v2: `POST /api/v2/documents/<id>/delete`). Link responses now carry `url`, the full address to give readers, and [List of files](#files) returns every labelled link with its URL. One link per recipient or session: a different `label` each time; a label already used answers 409 with the existing link. `onlyIpAddresses` on [Create directory](#directory) is optional – it limits who can open the folder's documents, not who can call the API. Existing fields are unchanged.

**2026-11-12 · Usage limits.** One set of [usage limits](#limits) now applies to `/public-api`, REST API v2 and the MCP server, counted per team (not per key) and per IP address. Over a limit the API answers 429 Too Many Requests with a `Retry-After` header; every response shows the remaining hourly budget in `X-RateLimit-Remaining`. An integration that keeps failing is paused for 15 minutes. The old limit of 600 requests per hour per IP address on REST API v2 is gone.

**2026-11-11 · Subfolders and data room folders.** [Subfolders](#v2-subfolders) group the documents of a folder (list, create, rename, delete, [move documents](#v2-subfolders-move)); [data room folders](#v2-room-folders) group a room's documents (list, create, rename, delete, [move](#v2-room-folders-move)), and you can [add documents from any of your folders to a room](#v2-room-documents), straight into a room folder. Deleting a subfolder or a room folder never deletes a document – they go back to the top. New fields only: documents carry `subfolder_id`, `subfolder` and `path` (“Folder › Subfolder”), `/api/v2/documents` takes `subfolder`, data room documents and index nodes carry `room_folder_id`.

**2026-11-11 · Offers.** [List](#v2-offer-list), [create](#v2-offer-create), [read](#v2-offer) and [update](#v2-offer-update) offers (texts, client, buttons incl. “Decline”, passcode, screenshot protection, one viewer at a time, status – also reopening), [add or remove their documents](#v2-offer-files) and read [the responses to one offer](#v2-offer-responses). The API never e-mails the client – it returns the offer’s link to send yourself. [Offer responses](#v2-offers) now also list declines (`type`, `offer_id` added).

**2026-11-10 · REST API v2 extended.** New endpoints for [e-signature requests](#v2-signatures) (send, status, audit trail, reminders, void, signed PDF), [data rooms](#v2-rooms) (details, [index numbering](#v2-room-index), freeze status and closing archives, [guest invitations](#v2-room-guests), access requests, signature requests), data room [Q&A](#v2-room-questions) and [due diligence request lists](#v2-room-requests), [team activity](#v2-activity), [per-document statistics](#v2-document) and [link settings](#v2-document-links), [offer responses](#v2-offers), [store sales](#v2-store), [lead magnet forms](#v2-landing) and [plan limits](#v2-plan). Nothing existing changed: every endpoint below keeps its URL, parameters and response format. REST API v2 also accepts the bare API key in `Authorization`, like the endpoints under `/public-api`.

**2026-11-15 · Plans.** The REST API (`/api/v2` and `/public-api`) is now available from the **Pro** plan, like the [MCP server](https://www.helprange.com/mcp-server): Pro, Max, Unlimited, the Deal Room Pass and the trial. The Free plan answers 402 Payment Required.

**2026-11-10 · Plans.** The API under `/public-api` now follows the same plan rule as REST API v2: Max plan and higher (also during the trial). On other plans every endpoint answers 402 Payment Required with `{"error": "…"}`, the same JSON as REST API v2; on Max, Unlimited, the Deal Room Pass and the trial nothing changed. The [MCP server](https://www.helprange.com/mcp-server) for AI assistants stays on Pro and higher (and the trial).

**2026-11-10 · Security.** The API key of a person removed from the team (or of a deleted account) no longer works on `/public-api`, as on REST API v2. `GET /public-api/directory` lists the folders you can open in the panel (administrators: every folder of the team).

## Introduction

HelpRange provides API for uploading files and obtaining analytics data. The HelpRange API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors.

Base URL

```
https://www.helprange.com/public-api
```

The API is available on the **Pro plan and higher (also during the trial)**: Pro, Max, Unlimited and the Deal Room Pass (since 2026-11-15; before: Max and higher). On the Free plan every endpoint answers `402` with `{"error": "…"}`.

## Authentication

Authenticate your account by including your API Key in every API request. Your API key carries many privileges, so be sure to keep it secure! Do not share your API key in publicly accessible areas such GitHub, client-side code, and so forth.

### Where is my API Key?

Go to your account's profile. There you will find your **API Key**.

### How to include it in request?

You need to put value of your API Key in HTTP header `Authorization`.

Example

```
$ curl -X GET https://www.helprange.com/public-api/directory \
  -H 'Authorization: t7ktuxyzb7emijofz9o8852i'
```

## Error codes

HelpRange API uses HTTP response codes to indicate API errors.

| Code | Meaning |
|---|---|
| 403 Forbidden | You do not have permission to use this endpoint. Probably you are using invalid API Key or trying to use directory or file of someone else. |
| 402 Payment Required | Your plan does not include the REST API – it is part of the Pro plan and higher (also during the trial). JSON body: `{"error": "…"}`. |
| 404 Not Found | Resource related to your request was not found. |
| 400 Bad Request | Your request is invalid probably because you are not passing valid parameters. |
| 429 Too Many Requests | A [usage limit](#limits) was reached. Wait the number of seconds in the `Retry-After` header. |

## Usage limits

The limits protect your integration and everyone else's from a script that loops or retries without a pause. They apply to `/public-api`, REST API v2 and the [MCP server](https://www.helprange.com/mcp-server) together, and are counted per team – all API keys and connected AI apps of your team share them. Windows are the clock hour and the clock minute (UTC); daily limits reset at midnight UTC.

| Limit | Value |
|---|---|
| Requests per team | 3,600 an hour, and at most 120 a minute |
| Write requests per team (POST, PUT, PATCH, DELETE – uploads, new links, guests, offers, e-signature …; MCP tools that change something) | 300 an hour |
| Share links created through the API per team | 2,000 a day |
| Guests created or invited to data rooms through the API per team | 1,000 a day |
| E-mails to other people sent because of API requests per team – data room invitations, e-signature requests, reminders and voids, buyer access; counted per recipient, separately from the request limits | 100 an hour and 500 a day |
| E-mail recipients of one request (e.g. adding documents to a data room e-mails every guest) | at most 50 |
| Uploads per team | the daily upload limit of your plan |
| Requests per IP address | 4,000 an hour |
| Requests with a missing or invalid API key per IP address | 60 an hour |
| Failed requests per team (4xx except 404, and 5xx) | more than 300 in an hour pause the team's API for 15 minutes |

Over a limit the API answers 429 Too Many Requests, does not carry out the request, and sends a `Retry-After` header with the seconds to wait. The JSON body:

```
{"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}
```

`code` is `RATE_LIMITED` (an hourly or per-minute limit), `DAILY_LIMIT` (links, guests or e-mails of the day) or `PAUSED` (“Too many failed requests – your integration may be looping. Paused until <time> UTC.”). A request that would e-mail more people than the e-mail budget has left is refused as a whole before anything is sent – never only some of the e-mails. A request with more than 50 recipients is answered with 400 and `"code": "TOO_MANY_RECIPIENTS"` (no `retry_after` – waiting does not help; use the HelpRange panel or turn off the data room's e-mail notifications). On the MCP server a daily or e-mail limit comes back as a tool error with the same message. Every authenticated response carries the team's hourly budget: `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (Unix time when the hour ends). The first time in a day your team hits a limit, its administrators get one e-mail.

## Endpoints

GET

### List of directories assigned to you

`/public-api/directory`

Request

```
$ curl -X GET https://www.helprange.com/public-api/directory \
  -H 'Authorization: t7ktuxyzb7emijofz9o8852i'
```

Response

```
{
  "directories": [
    {"id": 17, "name": "sales_documents"},
    {"id": 28, "name": "marketing_documents"}
  ]
}
```

GET

### List of files in directory

`/public-api/directory/<directory_id>/file`

Request

```
$ curl -X GET https://www.helprange.com/public-api/directory/243/file \
  -H 'Authorization: t7ktuxyzb7emijofz9o8852i'
```

Response

```
{
  "files": [
    {
      "id": 250,
      "name": "marketing_copy.pdf",
      "file_links": [
        {
          "id": 264,
          "uuid": "471dcc98874d4d0cb7c3eb1874c4e3db",
          "link": "/view/471dcc98874d4d0cb7c3eb1874c4e3db",
          "url": "https://acme.helprange.com/view/471dcc98874d4d0cb7c3eb1874c4e3db/marketing_copy",
          "name": "default"
        },
        {
          "id": 265,
          "uuid": "9b2e41f07c3d4a1e8f5b6c7d8e9f0a1b",
          "link": "/view/9b2e41f07c3d4a1e8f5b6c7d8e9f0a1b",
          "url": "https://acme.helprange.com/view/9b2e41f07c3d4a1e8f5b6c7d8e9f0a1b/marketing_copy",
          "name": "session-7f3a"
        }
      ]
    }
  ]
}
```

GET

### Statistics of file

`/public-api/file/<file_id>/statistics`

Request

```
$ curl -X GET https://www.helprange.com/public-api/file/124/statistics \
  -H 'Authorization: t7ktuxyzb7emijofz9o8852i'
```

Response

```
{
  "engagement_score": 11.57,
  "total_views": 39,
  "avg_time_seconds": 24,
  "avg_time_per_page_seconds": [10, 6, 4, 9, 15, 2, 78, 73, 0, 4, 0, 0, 0, 0, 0, 82, 0, 0, 0, 0, 0, 0, 0, 0, 0],
  "recordings": [
    {
      "time": "2022-10-24 10:34:56",
      "ip": "134.34.12.56",
      "country": "US",
      "referrer_url": "https://www.facebook.com",
      "read_time_sec": 100
    }
  ]
}
```

POST

### Upload file to directory

`/public-api/directory/<directory_id>/upload/<file_name>`

**Hint:** using the same <file_name> and uploading different file results in overwriting old file in HelpRange.

Request

```
$ curl -X POST https://www.helprange.com/public-api/directory/38/upload/filenewname.pdf \
  -H 'Authorization: t7ktuxyzb7emijofz9o8852i' \
  -H 'content-type: multipart/form-data' \
  -F "file=@/upload/my_sales_document.pdf;type=application/pdf"
```

Response · id of uploaded file and default link to document

```
{
  "id": 260,
  "default_link": "/view/8956d1e7b91b47e196a8040b1d4894f8",
  "default_url": "https://acme.helprange.com/view/8956d1e7b91b47e196a8040b1d4894f8/filenewname"
}
```

Size limit: **100 MB per file**. Large files above it (Pro: up to 200 MB, Max: 500 MB, Unlimited and the Deal Room Pass: 5 GB – download only, no viewer or watermark) can be uploaded in the panel and the data room page only for now, not through the API. A refused upload answers JSON `{"result": "failure", "reason": "…"}` – 400 for a file that is too large or a bad name, 429 when the team's daily upload limit is reached, 500 for an error on our side.

POST

### Create directory

`/public-api/directory`

A new directory starts with the same defaults as one made in the panel: watermark on (on plans that include it) and downloading off (on Free, downloading stays allowed).

Request · readers on any network (recommended)

```
$ curl -X POST https://www.helprange.com/public-api/directory \
  -H 'Authorization: t7ktuxyzb7emijofz9o8852i' \
  -H 'Content-Type: application/json' \
  --data-binary '{"name": "my directory"}'
```

Response

```
{
  "id": 260,
  "link": "/room/8956d1e7b91b47e196a8040b1d4894f8/"
}
```

**onlyIpAddresses** (optional) does **not** limit who can call the API. It limits who can **open** the folder's documents: every link of the folder answers 403 "This document isn't available from your network" to a reader outside the list. Set it only when every reader is on known networks, e.g. `{"name": "board pack", "onlyIpAddresses": "203.0.113.0/24"}` for your office. `GET /public-api/directory` shows each folder's list; change or clear it in the folder's settings in the panel.

POST

### Create link for file

`/public-api/file/<file_id>/link`

Booleans accept `true` / `false` (also 1 / 0 and "true" / "false"). `viewsLimit`: a whole number, `null` or 0 = no limit. `expirationDate`: `YYYY-MM-DD`, today or later. A passcode of only spaces means no passcode. Files the viewer cannot show (zip, CAD and other files) are always downloadable; screenshot protection applies to documents only. Invalid values answer 400 with `{"result": "failure", "reason": "…"}`.

**One link per recipient or session.** Labels are unique per document (at most 200 characters). Send a different `label` for each link – e.g. the recipient's e-mail or your session id – and every call makes a new link with its own URL and its own views in the statistics. A label the document already has answers 409 with `"code": "LINK_LABEL_EXISTS"` and the existing link in `existing_link` (id, link, url, state): reuse it, or pick another label. Give readers `url`, the full address; `link` is its path.

Request · no password, no expiration date, no views limit

```
$ curl -X POST https://www.helprange.com/public-api/file/124/link \
  -H 'Authorization: t7ktuxyzb7emijofz9o8852i' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "label": "someLabel",
    "isAllowDownloadingAndPrint": true,
    "isOnlyOneUserViewing": false,
    "isForwardable": true,
    "isScreenshotMask": false,
    "isWatermark": false,
    "passcode": null,
    "expirationDate": null,
    "viewsLimit": null
  }'
```

Response

```
{
  "id": 260,
  "link": "/view/8956d1e7b91b47e196a8040b1d4894f8",
  "url": "https://acme.helprange.com/view/8956d1e7b91b47e196a8040b1d4894f8/proposal"
}
```

Request · with password, expiration date and views limit

```
$ curl -X POST https://www.helprange.com/public-api/file/124/link \
  -H 'Authorization: t7ktuxyzb7emijofz9o8852i' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "label": "someLabel",
    "isAllowDownloadingAndPrint": true,
    "isOnlyOneUserViewing": false,
    "isForwardable": true,
    "isScreenshotMask": false,
    "isWatermark": false,
    "passcode": "abcd",
    "expirationDate": "2027-12-24",
    "viewsLimit": 10
  }'
```

Response

```
{
  "id": 261,
  "link": "/view/8956d1e7b91b47e1asd67a8040b1d4894f8",
  "url": "https://acme.helprange.com/view/8956d1e7b91b47e1asd67a8040b1d4894f8/proposal"
}
```

Response · 409, the label is taken

```
{
  "status": "Conflict Error",
  "message": "This document already has a link labelled \"someLabel\". …",
  "code": "LINK_LABEL_EXISTS",
  "existing_link": {"id": 261, "link": "/view/8956d1e7b91b47e1asd67a8040b1d4894f8", "url": "https://acme.helprange.com/view/8956d1e7b91b47e1asd67a8040b1d4894f8/proposal", "label": "someLabel", "state": "active"}
}
```

POST

### Delete file

`/public-api/file/<file_id>/delete`

Deletes a document like Document → Delete in the panel: it leaves its folder and data rooms and every link of it stops working at once. The body must carry `"confirm": true` (otherwise 400, nothing deleted). 409 with a `code` when an e-signature request, a store product, a frozen data room or a live offer needs the document (offers: add `"confirm_offers": true` to delete it anyway). Logged in Activity → Team. REST API v2: `POST /api/v2/documents/<id>/delete`.

Request

```
$ curl -X POST https://www.helprange.com/public-api/file/124/delete \
  -H 'Authorization: t7ktuxyzb7emijofz9o8852i' \
  -H 'Content-Type: application/json' \
  --data-binary '{"confirm": true}'
```

Response

```
{
  "result": "success",
  "deleted": true,
  "id": 124,
  "name": "proposal.pdf",
  "folder_id": 38,
  "links_deactivated": 3
}
```

POST

### Add guest

`/public-api/guest`

Request · with email

```
$ curl -X POST https://www.helprange.com/public-api/guest \
  -H 'Authorization: t7ktuxyzb7emijofz9o8852i' \
  -H 'Content-Type: application/json' \
  --data-binary '{"email": "john@company.com"}'
```

Response

```
{
  "id": 5
}
```

POST

### Assign guest to data room

`/public-api/guest/<guest_id>/assign/<data_room_id>`

Request · assigning guest with id 7 to data room of id 10

```
$ curl -X POST https://www.helprange.com/public-api/guest/7/assign/10 \
  -H 'Authorization: t7ktuxyzb7emijofz9o8852i'
```

Response

```
{
  "result": "success"
}
```

## REST API v2

REST API v2 is the API behind our Zapier, Make and n8n integrations, open to your own scripts as well. It works with the same API key and returns JSON; ids are the same as in the endpoints above.

Base URL

```
https://www.helprange.com/api/v2
```

### Authentication

Send your API key in the `X-API-Key` header, as `Authorization: Api-Key <key>`, or as the bare key in `Authorization`. OAuth access tokens (`Authorization: Bearer …`) from the HelpRange MCP connector work too.

```
$ curl https://www.helprange.com/api/v2/data-rooms \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i'
```

### Plans and permissions

REST API v2 is part of the **Pro**, **Max** and **Unlimited** plans, the **Deal Room Pass** and the trial. The API key acts as you, with your rights in the panel: administrators see every folder, data room and e-signature request of the team; members see the folders they belong to, the data rooms they created and the e-signature requests they created or sent. A setting your plan does not include is refused with the plan that has it. E-mails the API makes HelpRange send (signature requests, reminders, data room invitations) count towards the same daily sending limits as the panel. Offers are never e-mailed through the API: it returns the offer's link, and “Send by e-mail” stays in the panel with its explicit confirmation.

### Errors

Errors come back as JSON: `{"error": "…"}`.

| Code | Meaning |
|---|---|
| 400 Bad Request | A parameter is missing or invalid – the message says which. |
| 401 Unauthorized | Missing or invalid API key / OAuth token. |
| 402 Payment Required | Your plan does not include the REST API (or this feature – e.g. NDA before access needs Max). |
| 404 Not Found | New endpoints: the document, folder, subfolder, data room (folder), e-signature request or offer does not exist or you have no access to it. |
| 405 Method Not Allowed | Wrong HTTP method for this endpoint. |
| 409 Conflict | The data room is frozen (no changes), or the signed PDF is not ready yet. |
| 429 Too Many Requests | A usage limit was reached – JSON `{"error", "code", "retry_after"}` and a `Retry-After` header. |

The same [usage limits](#limits) as above apply: 3,600 requests an hour per team (120 a minute), 300 write requests an hour, 2,000 new links and 1,000 guests a day, 4,000 requests an hour per IP address.

## Files, links and triggers

| Method | Path | What it does |
|---|---|---|
| GET | `/api/v2/me` | Who is connected: e-mail, name, team, plan. |
| GET | `/api/v2/folders` | Folders you can open. |
| POST | `/api/v2/folders/<id>` | Turn [subfolders](#v2-subfolders) on or off for a folder (`subfolders_enabled`); **GET** shows the folder with the setting. |
| GET | `/api/v2/documents` | Your latest 100 documents (optional `folder_id`; `subfolder` = a subfolder id or `none`). Each with `subfolder_id`, `subfolder` and `path`. |
| POST | `/api/v2/files` | Upload: multipart `file`, or `file_url`, or `content_base64` + `filename`; optional `folder_id`. [Size limits](#v2-upload-limits). |
| POST | `/api/v2/files/<id>/links` | New share link: `label`, `allow_download`, `passcode`, `expires_on`, `views_limit`, `watermark`, `require_email`, `disallow_forwarding`, `one_viewer_at_a_time`. |
| GET | `/api/v2/views` | The latest 50 document views (polling trigger). |
| GET | `/api/v2/uploads` | The latest 50 files uploaded by clients (polling trigger). |
| POST | `/api/v2/folders/<id>/buyers` | Give a buyer access to a product folder (`email`, `buyer_id`); `…/buyers/remove` takes it away. |

### Upload size limits

| How the file is sent | Limit |
|---|---|
| multipart `file` (recommended) | 100 MB per file. |
| `file_url` | The same: 100 MB. HelpRange downloads the file within 30 seconds per request. |
| `content_base64` in a JSON body | The same file limit; the JSON body may be up to 4/3 of it (base64) – about 134 MB for a 100 MB file. A whole request over 310 MB is refused by our web server with an HTML 413 page, so with a raised limit send files over ~230 MB as multipart or `file_url`. |

A file over the limit answers **413** with `{"error": "…", "code": "FILE_TOO_LARGE"}` (a JSON body over the limit: `"code": "REQUEST_TOO_LARGE"` or `"FILE_TOO_LARGE"`); the team's daily upload limit answers **429** with `"code": "UPLOAD_LIMIT"`; a frozen data room **423** with `"code": "ROOM_FROZEN"`. The MCP tool `upload_file` has the same limits; a request body over them gets a JSON-RPC error (code `-32002`, HTTP 413), a refused file a tool error with the reason. Large files (over the 100 MB limit) are uploaded in the panel or on the data room page, straight to storage – the REST API and MCP do not take them yet.

## New in REST API v2

GET

### Plan, features and limits

`/api/v2/plan`

Request

```
$ curl https://www.helprange.com/api/v2/plan \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i'
```

Response

```
{
  "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"},
  "data_rooms_left": null, "mcp_server": true, "rest_api": true,
  "pricing_url": "https://www.helprange.com/pricing"
}
```

GET

### Document statistics and recent views

`/api/v2/documents/<document_id>`

| Parameter | In | Description |
|---|---|---|
| `recent_views` | query | How many latest views to return, 1–100 (default 20). |

Request

```
$ curl https://www.helprange.com/api/v2/documents/250?recent_views=5 \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i'
```

Response

```
{
  "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",
  "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}]
}
```

GET

### Share links of a document and their settings

`/api/v2/documents/<document_id>/links`

Request

```
$ curl https://www.helprange.com/api/v2/documents/250/links \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i'
```

Response

```
{
  "document": "proposal.pdf",
  "links": [{"id": 264, "url": "https://www.helprange.com/view/471dcc98…/proposal", "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}]
}
```

GET

### Team activity feed

`/api/v2/activity`

| Parameter | In | Description |
|---|---|---|
| `type` | query | views, sharing, rooms, offers, esign, store, uploads or team (administrators only). |
| `limit` | query | 1–200 (default 30). |
| `before` | query | Page back: pass next_before of the previous response. |
| `member_id` | query | Administrators: only this team member's events. |

Request

```
$ curl https://www.helprange.com/api/v2/activity?type=esign&limit=2 \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i'
```

Response

```
{
  "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=…"}],
  "more": true, "next_before": "2026-11-10T09:12:40.123456+00:00"
}
```

GET

### List e-signature requests

`/api/v2/signature-requests`

| Parameter | In | Description |
|---|---|---|
| `status` | query | draft, sent, expired, completed, declined or voided. |
| `query` | query | Words in the title or a recipient's name / e-mail. |
| `limit` | query | 1–200 (default 50). |

Request

```
$ curl https://www.helprange.com/api/v2/signature-requests?status=sent \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i'
```

Response

```
{
  "signature_requests": [{
    "id": "9f1c2e…", "title": "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=9f1c2e…"
  }]
}
```

POST

### Send a document for e-signature

`/api/v2/signature-requests`

A signature page with a block per signer is added at the end of the document; recipients get an e-mail with their signing link. Responds **201**.

| Parameter | In | Description |
|---|---|---|
| `document_id` | body | Required. A document in a folder you can open. |
| `signers` | body | Required. 1–20 recipients in signing order: {"name", "email", "action": "sign" / "review"}. |
| `title` | body | Default: the file name. |
| `message` | body | Shown in the e-mail. |
| `sequential` | body | true: sign one after another. |
| `expires_on` | body | YYYY-MM-DD (default: 30 days). |

Request

```
$ curl -X POST https://www.helprange.com/api/v2/signature-requests \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "document_id": 250,
    "title": "Mutual NDA",
    "signers": [{"name": "Anna Client", "email": "anna@client.com"},
                {"name": "Legal", "email": "legal@client.com", "action": "review"}],
    "sequential": true
  }'
```

Response

```
{"id": "9f1c2e…", "title": "Mutual NDA", "status": "sent", "signed": 0, "recipients_count": 2, "sent": true, …}
```

GET

### E-signature request details and audit trail

`/api/v2/signature-requests/<id>`

Request

```
$ curl https://www.helprange.com/api/v2/signature-requests/9f1c2e \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i'
```

Response

```
{
  "id": "9f1c2e…", "title": "Mutual NDA", "status": "sent", "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, …
}
```

POST

### Remind signers

`/api/v2/signature-requests/<id>/remind`

At most once an hour per request (400 otherwise).

Request

```
$ curl -X POST https://www.helprange.com/api/v2/signature-requests/9f1c2e/remind \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i' \
  -H 'Content-Type: application/json' \
  --data-binary '{}'
```

Response

```
{"id": "9f1c2e…", "reminded": ["anna@client.com"]}
```

POST

### Void an e-signature request

`/api/v2/signature-requests/<id>/void`

Cannot be undone.

| Parameter | In | Description |
|---|---|---|
| `reason` | body | Optional, shown to the waiting recipients. |

Request

```
$ curl -X POST https://www.helprange.com/api/v2/signature-requests/9f1c2e/void \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i' \
  -H 'Content-Type: application/json' \
  --data-binary '{"reason": "Wrong version"}'
```

Response

```
{"id": "9f1c2e…", "status": "voided", …}
```

GET

### Download link of the signed PDF

`/api/v2/signature-requests/<id>/signed-pdf`

The signed PDF carries the certificate of completion (audit trail). **409** while not everyone has signed.

Request

```
$ curl https://www.helprange.com/api/v2/signature-requests/9f1c2e/signed-pdf \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i'
```

Response

```
{
  "id": "9f1c2e…", "url": "https://www.helprange.com/esign/download/…/", "valid_days": 30,
  "sha256": "5e88489…", "sealed": true
}
```

GET

### List data rooms

`/api/v2/data-rooms`

Request

```
$ curl https://www.helprange.com/api/v2/data-rooms \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i'
```

Response

```
{
  "data_rooms": [{"id": 10, "name": "Project Falcon", "guests": 4, "documents": 37, "pending_access_requests": 1,
                  "expires_at": null, "frozen": false, "index_numbering": true}]
}
```

GET

### Data room details: guests, NDA, freeze, Q&A

`/api/v2/data-rooms/<data_room_id>`

When a room is frozen, `freeze.archives` lists the closing archives (ZIP with index, documents and audit report) with a `download_url` once ready.

Request

```
$ curl https://www.helprange.com/api/v2/data-rooms/10 \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i'
```

Response

```
{
  "id": 10, "name": "Project Falcon", "nda_required": "Falcon NDA", "expires_at": null,
  "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}],
  "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}
}
```

GET

### Data room index (numbered folders and documents)

`/api/v2/data-rooms/<data_room_id>/index`

The index has the structure guests see – always one level of folders. With [data room folders](#v2-room-folders) on (`folders_enabled`), the folder nodes are only the room's folders (`room_folder_id`, `folder_id` null) and every other document is at the top level. Otherwise, with “Show Folders” on, a folder node is the folder the documents come from (`folder_id`) or, for documents in one of its [subfolders](#v2-subfolders), “Folder / Subfolder” (`folder_id` and `subfolder_id`). With both off the index is a flat list.

Request

```
$ curl https://www.helprange.com/api/v2/data-rooms/10/index \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i'
```

Response

```
{
  "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": "folder", "number": "2", "name": "Legal", "folder_id": null, "room_folder_id": 6, "children": [
      {"type": "document", "number": "2.1", "name": "articles.pdf", "document_id": 252, "room_link_id": 903, "room_folder_id": 6}
    ]},
    {"type": "document", "number": "3", "name": "teaser.pdf", "document_id": 250, "room_link_id": 901, "room_folder_id": null}
  ]
}
```

POST

### Invite a guest to a data room

`/api/v2/data-rooms/<data_room_id>/guests`

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.

| Parameter | In | Description |
|---|---|---|
| `email` | body | Required. The guest's e-mail address. |

Request

```
$ curl -X POST https://www.helprange.com/api/v2/data-rooms/10/guests \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i' \
  -H 'Content-Type: application/json' \
  --data-binary '{"email": "buyer@bidco.com"}'
```

Response

```
{"id": 77, "email": "buyer@bidco.com", "data_room_id": 10, "invited": true, "already_a_guest": false}
```

GET

### Access requests of a data room

`/api/v2/data-rooms/<data_room_id>/access-requests`

| Parameter | In | Description |
|---|---|---|
| `status` | query | pending (default), approved, denied or all. |
| `limit` | query | 1–200 (default 50). |

Request

```
$ curl https://www.helprange.com/api/v2/data-rooms/10/access-requests \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i'
```

Response

```
{
  "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/"}]
}
```

GET

### Signature requests of a data room

`/api/v2/data-rooms/<data_room_id>/signature-requests`

Request

```
$ curl https://www.helprange.com/api/v2/data-rooms/10/signature-requests \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i'
```

Response

```
{
  "data_room": "Project Falcon",
  "signature_requests": [{"envelope_id": "9f1c2e…", "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"}]}]
}
```

GET

### Q&A questions of a data room

`/api/v2/data-rooms/<data_room_id>/questions`

| Parameter | In | Description |
|---|---|---|
| `status` | query | all (default), open, published, new, assigned, answered (waiting for approval), approved or declined. |
| `category` | query | legal, financial, tax, hr, commercial, it or other. |
| `limit` | query | 1–500 (default 100). |

Request

```
$ curl https://www.helprange.com/api/v2/data-rooms/10/questions?status=open \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i'
```

Response

```
{
  "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}]
}
```

POST

### Add a question (e.g. from a buyer's list)

`/api/v2/data-rooms/<data_room_id>/questions`

Like importing a buyer's question list in the panel: nobody is e-mailed. Answer and approve in the panel. **201**; **409** when the room is frozen.

| Parameter | In | Description |
|---|---|---|
| `text` | body | Required, up to 4000 characters. |
| `category` | body | legal, financial, tax, hr, commercial, it or other (default). |
| `document_id` | body | A document of the room the question is about … |
| `index` | body | … or its index number, e.g. "2.1". |
| `page` | body | Page number. |
| `all_guests` | body | true: published to the room's FAQ once answered. |

Request

```
$ curl -X POST https://www.helprange.com/api/v2/data-rooms/10/questions \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i' \
  -H 'Content-Type: application/json' \
  --data-binary '{"text": "Any pending litigation?", "category": "legal", "index": "2.1", "page": 4}'
```

Response

```
{"id": 42, "number": "Q8", "status": "new", "source": "import", "index": "2.1", …}
```

GET

### Due diligence request list of a data room

`/api/v2/data-rooms/<data_room_id>/requests`

| Parameter | In | Description |
|---|---|---|
| `status` | query | open, in_progress, provided or na. |

Request

```
$ curl https://www.helprange.com/api/v2/data-rooms/10/requests \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i'
```

Response

```
{
  "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"}]
}
```

POST

### Add a request list item

`/api/v2/data-rooms/<data_room_id>/requests`

**201**; **409** when the room is frozen.

| Parameter | In | Description |
|---|---|---|
| `description` | body | Required. |
| `number` | body | Your numbering, e.g. "1.1". |
| `category` | body | Free text, e.g. "Legal". |
| `priority` | body | high, medium (default) or low. |
| `due_date` | body | YYYY-MM-DD. |
| `assignee` | body | E-mail of a team member who manages the room. |
| `status` | body | open (default), in_progress, provided or na. |
| `documents` | body | Documents that answer it: index numbers as strings ("2.1") and / or document ids as numbers. |

Request

```
$ curl -X POST https://www.helprange.com/api/v2/data-rooms/10/requests \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i' \
  -H 'Content-Type: application/json' \
  --data-binary '{"description": "Articles of association", "number": "1.1", "priority": "high", "due_date": "2026-12-01", "documents": ["2.1"]}'
```

Response

```
{"id": 3, "number": "1.1", "status": "open", "documents": [{"document_id": 252, "index": "2.1"}], …}
```

GET

### Subfolders of a folder

`/api/v2/folders/<folder_id>/subfolders`

**Off by default (2026-11-12):** turn subfolders on per folder with **POST** `/api/v2/folders/<folder_id>` `{"subfolders_enabled": true}` (or “Use subfolders to group files” in the folder settings; **GET** the same URL shows the setting). While they are off, creating a subfolder or moving documents into one is refused with **400** “Subfolders are off for this folder – enable them in folder settings.” Turning them off (`false`) moves the documents back to the top of the folder and deletes the subfolders – no document is deleted.

Subfolders only group the documents of a folder: the folder's protection, links, members and analytics apply to them unchanged. One level – a subfolder holds documents, never other subfolders. **POST** the same URL with `name` to create one (**201**); **POST** `/api/v2/subfolders/<id>` with `name` renames it; **POST** `/api/v2/subfolders/<id>/delete` deletes the subfolder only – its documents go back to the top of the folder, nothing is deleted.

Request

```
$ curl -X POST https://www.helprange.com/api/v2/folders/31/subfolders \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i' \
  -H 'Content-Type: application/json' --data-binary '{"name": "Contracts"}'
```

Response · GET

```
{
  "folder_id": 31, "folder": "Legal", "subfolders_available": true, "subfolders_enabled": true, "documents_at_top": 4,
  "subfolders": [{"id": 7, "name": "Contracts", "position": 0, "folder_id": 31, "documents_count": 12}]
}
```

POST

### Move documents to a subfolder

`/api/v2/folders/<folder_id>/subfolders/move`

| Parameter | In | Description |
|---|---|---|
| `document_ids` | body | Required. Documents of this folder (up to 100); others are listed in `not_in_folder`. |
| `subfolder_id` | body | A subfolder of this folder; `null` or missing = back to the top of the folder. |

Request

```
$ curl -X POST https://www.helprange.com/api/v2/folders/31/subfolders/move \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i' \
  -H 'Content-Type: application/json' --data-binary '{"document_ids": [252, 253], "subfolder_id": 7}'
```

Response

```
{"moved": 2, "folder_id": 31, "subfolder_id": 7, "subfolder": "Contracts", "not_in_folder": []}
```

GET

### Folders of a data room

`/api/v2/data-rooms/<data_room_id>/folders`

**Off by default (2026-11-12):** turn folders on per data room with **POST** `/api/v2/data-rooms/<data_room_id>` `{"folders_enabled": true}` (or “Use folders to group documents” in the data room settings). While they are off, creating a room folder or moving documents into one is refused with **400** “Folders are off for this data room – enable them in data room settings.” Turning them off (`false`) deletes the room's folders – their documents stay in the room, at the top level.

A data room folder groups the room's documents (one level); the files stay in the folders they come from, so one room folder can hold documents from many of your folders. **POST** the same URL with `name` to create one (**201**); **POST** `…/folders/<folder_id>` with `name` renames it; **POST** `…/folders/<folder_id>/delete` deletes the room folder only – its documents stay in the room, at the top level. **409** when the room is frozen.

Request

```
$ curl https://www.helprange.com/api/v2/data-rooms/10/folders \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i'
```

Response

```
{
  "data_room_id": 10, "data_room": "Project Falcon", "frozen": false,
  "folders": [{"id": 5, "name": "Financials", "position": 0, "data_room_id": 10, "documents_count": 3}]
}
```

POST

### Move data room documents

`/api/v2/data-rooms/<data_room_id>/folders/move`

| Parameter | In | Description |
|---|---|---|
| `room_link_ids` | body | Room documents (`room_link_id` from [the room's documents](#v2-room-documents) or the index) … |
| `document_ids` | body | … and / or document ids. Ids not in the room are listed in `not_in_room`. |
| `folder_id` | body | A folder of this room; `null` or missing = the room's top level. |

Request

```
$ curl -X POST https://www.helprange.com/api/v2/data-rooms/10/folders/move \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i' \
  -H 'Content-Type: application/json' --data-binary '{"room_link_ids": [910, 911], "folder_id": 5}'
```

Response

```
{"moved": 2, "data_room_id": 10, "room_folder_id": 5, "room_folder": "Financials", "not_in_room": []}
```

POST

### Add documents to a data room

`/api/v2/data-rooms/<data_room_id>/documents`

Like “Add existing documents” on the room page: `document_ids` (up to 100) from folders you can open – not data room storage folders – optionally straight into a room folder (`folder_id`). The files stay in their folders. When the room sends e-mail notifications, its guests get one e-mail for the batch. **201**; **409** when the room is frozen. **GET** the same URL lists 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 (null at the top level).

Request

```
$ curl -X POST https://www.helprange.com/api/v2/data-rooms/10/documents \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i' \
  -H 'Content-Type: application/json' --data-binary '{"document_ids": [260, 261], "folder_id": 5}'
```

Response · GET

```
{"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"}
]}
```

GET

### Offer responses

`/api/v2/offer-responses`

| Parameter | In | Description |
|---|---|---|
| `kind` | query | accept, contact or decline. |
| `days` | query | 1–3650 (default 90). |
| `limit` | query | 1–200 (default 50). |

Request

```
$ curl https://www.helprange.com/api/v2/offer-responses \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i'
```

Response

```
{
  "responses": [{"kind": "accepted the offer", "type": "accept", "offer_id": 31, "email": "anna@client.com", "email_verified": true, "offer": "Proposal Q4",
                 "comment": "Let's go", "document_id": 250, "engagement": 87, "country": "DE",
                 "at": "2026-11-10T10:00:00+00:00"}]
}
```

GET

### List offers

`/api/v2/offers`

Administrators see every offer of the team; members the offers they created and those whose documents they can open – as in Offers in the panel.

| Parameter | In | Description |
|---|---|---|
| `status` | query | open (default: everything but archived), all, active, expired, accepted, declined, draft, closed (archived). |
| `search` | query | Words in the title, the client's name, company or e-mail. |
| `limit`, `page` | query | 1–200 (default 50); page from 1. The answer has `total` and `next_page` (null on the last page). |

Request

```
$ curl 'https://www.helprange.com/api/v2/offers?status=active&search=acme' \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i'
```

Response

```
{
  "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/Xk2…/", "document_views": 4, "page_visits": 2,
              "last_viewed_at": "2026-11-11T09:12:00+00:00", "sent_at": null, "created_at": "…", "updated_at": "…"}],
  "page": 1, "limit": 50, "total": 1, "next_page": null
}
```

POST

### Create an offer

`/api/v2/offers`

Based on a folder (`folder_id` – new files show up in the offer), from documents (`file_ids`: a JSON list, repeated form fields or "1,2"), or empty with just a title and client (upload documents later with [/api/v2/files](#v2-basics) and add them). Offers without a folder get their own folder “Offer – <title>”. Responds **201** with the offer as in [Offer details](#v2-offer).

**No e-mail.** The API never sends the offer to the client. Send the returned `url` yourself, or use “Send by e-mail” on the offer page in HelpRange – it shows the e-mail and asks you to confirm.

| Field | In | Description |
|---|---|---|
| `title` | body | What the client sees as the title. Create: default the folder's / first document's name. |
| `client_first_name`, `client_last_name`, `client_company`, `client_email` | body | All optional. The client's e-mail is never e-mailed by the API. |
| `message`, `price_summary` | body | Message on the offer page (up to 2000 characters) and one price line. |
| `show_accept`, `accept_label` | body | “Accept offer” button (default on) and its own label. |
| `show_contact`, `contact_label` | body | “Request contact” button (default on). |
| `show_decline`, `decline_label` | body | “Decline” button with an optional reason (default off). A decline marks the offer declined and e-mails you. |
| `require_email_verification`, `access` | body | The client verifies their e-mail with a one-time code (default on); access: `any`, `email` (only client_email) or `domain` (client_email and colleagues at the same domain). |
| `passcode` | body | Asked before the offer opens; also set on each of its documents' links. `""` removes it. Responses show only whether one is set. |
| `screenshot_protection` | body | Pro and higher (else 402). |
| `one_viewer_at_a_time`, `allow_download`, `watermark` | body | true / false. |
| `expires_on` | body | Last day, YYYY-MM-DD (`""` removes it). After it the offer shows as `expired`. |
| `open_directly` | body | One-file offers: open the document directly instead of the offer page (default off). |
| `layout` | body | classic, split, cover or minimal. |
| `status` | body | Create: active (default) or draft. Update: active (also to reopen an accepted or declined offer), draft, accepted, declined, closed (archived). |

Request

```
$ curl -X POST https://www.helprange.com/api/v2/offers \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i' \
  -H 'Content-Type: application/json' \
  --data-binary '{"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"}'
```

Response

```
{"id": 31, "title": "Fit-out Q1", "status": "active", "url": "https://www.helprange.com/o/Xk2…/", …,
 "send_by_email": "HelpRange does not e-mail offers through the API or MCP. …"}
```

GET

### Offer details

`/api/v2/offers/<id>`

Texts, client, buttons, protection, layout, its documents (each with the offer's own link and its views), visits, people, 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.

Request

```
$ curl https://www.helprange.com/api/v2/offers/31 \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i'
```

Response

```
{
  "id": 31, "title": "Fit-out Q1", "status": "active", "stored_status": "active", "expired": false,
  "url": "https://www.helprange.com/o/Xk2…/", "panel_url": "https://www.helprange.com/user/offers/31/",
  "message": "…", "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",
  "files": [{"id": 250, "name": "proposal.pdf", "folder_id": 12, "source": "picked",
             "view_url": "https://www.helprange.com/view/…/proposal.pdf", "views": 3}],
  "document_views": 4, "page_visits": 2, "people": 1, "engagement": 82,
  "responses_count": 1, "responses": [{"type": "decline", "kind": "declined the offer", "comment": "Too expensive", …}],
  "send_by_email": "HelpRange does not e-mail offers through the API or MCP. …"
}
```

PATCH

### Update an offer

`/api/v2/offers/<id>` (PATCH or POST)

Changes only the fields you send (see [Create an offer](#v2-offer-create)). The offer's links follow at once (protection, expiry, status). `"status": "active"` reopens an accepted, declined or archived offer. Answers with the offer.

Request

```
$ curl -X PATCH https://www.helprange.com/api/v2/offers/31 \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i' \
  -H 'Content-Type: application/json' \
  --data-binary '{"status": "active", "expires_on": "2027-01-31", "one_viewer_at_a_time": true}'
```

POST

### Add or remove an offer's documents

`/api/v2/offers/<id>/files` · `/api/v2/offers/<id>/files/remove`

`file_ids`: documents from folders you can open (up to 50). Removing only takes a document out of the offer – the file stays in its folder. Answers with the offer.

Request

```
$ curl -X POST https://www.helprange.com/api/v2/offers/31/files \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i' \
  -H 'Content-Type: application/json' --data-binary '{"file_ids": [252]}'
```

GET

### Responses to an offer

`/api/v2/offers/<id>/responses`

Every answer to this offer (accept, contact, decline with its reason in `comment`), newest first. Optional `kind`, `days`, `limit` as in [Offer responses](#v2-offers).

Request

```
$ curl https://www.helprange.com/api/v2/offers/31/responses \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i'
```

Response

```
{"responses": [{"kind": "declined the offer", "type": "decline", "offer_id": 31, "email": "anna@acme.com",
                "email_verified": true, "offer": "Fit-out Q1", "comment": "Too expensive", "engagement": 64,
                "country": "PL", "at": "2026-11-11T10:00:00+00:00"}]}
```

GET

### Store products and sales

`/api/v2/store/sales`

| Parameter | In | Description |
|---|---|---|
| `product_id` | query | Only this product. |
| `days` | query | Purchases of the last N days (default 90). |
| `limit` | query | 1–200 (default 50). |

Request

```
$ curl https://www.helprange.com/api/v2/store/sales \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i'
```

Response

```
{
  "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"}]
}
```

GET

### Lead magnet / landing page forms

`/api/v2/landing-templates`

`folders`: the folders (you can open) that use the form.

Request

```
$ curl https://www.helprange.com/api/v2/landing-templates \
  -H 'X-API-Key: t7ktuxyzb7emijofz9o8852i'
```

Response

```
{
  "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]}]
}
```
