Public HelpRange API Documentation

Topics

Introduction
Authentication
Error codes
Endpoints

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.

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

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.

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.

Endpoints

[GET] List of directories assigned to you

URL:

/public-api/directory

Example of request:

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

JSON Response:

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

[GET] List of files in directory

URL:

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

Example of request:

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

JSON Response:

{ "files": [
  {
    "id": 250,
    "name": "marketing_copy.pdf",
    "file_links": [
        {
          "id": 264,
          "uuid": "471dcc98874d4d0cb7c3eb1874c4e3db",
          "link": "/view/471dcc98874d4d0cb7c3eb1874c4e3db",
          "name": "default"
        }
    ]
]}

[GET] Statistics of file

URL:

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

Example of request:

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

JSON 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

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

URL:

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

Example of 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"

JSON Response (id of uploaded file and default link to document):

{
  "id": 260,
  "default_link": "/view/8956d1e7b91b47e196a8040b1d4894f8"
}

[POST] Create directory

URL:

/public-api/directory

Example of request with name and set of allowed IP addresses

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

JSON Response:

{
  "id": 260,
  "link": "/view-directory/8956d1e7b91b47e196a8040b1d4894f8"
}

Example of request with name and no set of allowed IP addresses:

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

JSON Response:

{
  "id": 260,
  "link": "/view-directory/8956d1e7b91b47e196a8040b1d4894f8"
}

URL:

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

Example of request with no password and no expiration date and 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}'

JSON Response:

{
  "id": 260,
  "link": "/view/8956d1e7b91b47e196a8040b1d4894f8"
}

Example of request with password and 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":"2024-12-24",
"viewsLimit": 10}'

JSON Response:

{
  "id": 261,
  "link": "/view/8956d1e7b91b47e1asd67a8040b1d4894f8"
}

[POST] Add guest

URL:

/public-api/guest

Example of 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"}'

JSON Response:

{
  "id": 5,
}

[POST] Assign guest to group

URL:

/public-api/guest/<guest_id>/assign/<group_id>

Assigning guest with id 7 to guests group of id 10

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

JSON Response:

{
  "result": "success",
}