# API Guide v1.1
Easily and securely integrate Harbour with any system
Our API is REST-based JSON-encoded service that uses standard HTTP response codes and API key authentication - you can use this to easily query agreement data, create a new agreement, and more.
# Start here
# 1. Try it out
Test how our API respond to a specific request using our sandbox demo account. The example below lists all of the available agreements to the organization linked to the API key.
# 2. Get your keys
You can generate new credentials and find your existing ones inside your Harbour Account (opens new window) > Settings > Integrations (or contact support@harbourshare.com in case you need help)
p.s. It requires an Organization Admin role to perform the mentioned steps
⚠️ Heads Up
You should never use API tokens in the frontend of your application or malicious users could discover them in your source code. You should only use them on your server.
You should limit API credentials access to only the minimum number of people necessary.
You should not embed API credentials in your backend code even if it’s not public - this increases the risk that they will be discovered. Instead, you should store them in configuration files or environment variables.
# 3. Know the basics
Request, response format
Token-based authentication. API keys must be included in the header of all requests made to the API.
You should use a Content-Type: application/json header with all requests and responses will also return JSON with a consistent structure.
You must make all your requests to the API over HTTPS. Any requests made over HTTP will fail.
Text fields support UTF-8, but do not allow certain special characters.
Errors
- All errors follows the same structure using a parcial implementation of RFC7807 (opens new window).
{
"detail": "Please, make sure your request HEADER contains the API key and it is a valid one.",
"error": 2002,
"message": "Unauthorized access.",
"more_info": "https://knowledgebase.harbourshare.com/knowledge/errors/2002"
}
Rate limits
Harbour advice a maximum volume of 100 requests per minute.
Any request over the limit could return a
429 Too Many Requestserror.
HTTP/2 429 Too Many Requests
Content-Type: application/json
{
"detail": "Your requests are over the maximum volume per minute. Please check our recommendations and try again later.",
"error": 2003,
"message": "Rate limit exceeded.",
"more_info": "https://knowledgebase.harbourshare.com/knowledge/errors/2003"
}
# Core resources
Below all are available Core Resources within Harbour's API. For each resource there should be an available endpoint to make requests to.
| Resource | Description |
|---|---|
| Agreements 📄 | Retrieve information or create agreement documents |
| Agreement Links 🔗 | Retrieve status or create agreement links to collect signatures |
| Items 📷 | Retrieve data on every media file that is stored inside Harbour |
| Folders 📂 | List and review all information about the folders created inside Harbour |
| Organizations 🏢 | Retrieve every information regarding your organization (inc. brands, users...) |
# Agreements
# Methods
| Name | Endpoint |
|---|---|
| List agreements | GET /agreements |
| Get agreement by ID | GET /agreements/{agreement_id} |
| Download agreement | GET /agreements/{agreement_id}/download |
List agreements
This endpoint returns a list of agreements under a specific organization.
What can you do with this information?
When querying data from this endpoint you will be able to access all the agreements available on your organization meaning not only the completed ones but also the ones that haven't been signed yet.
Endpoint
GET /agreements
Path Parameters
null
Query Parameters
| Field | Type | Description | Required | Default Value |
|---|---|---|---|---|
| offset | integer | Skip the records before the offset | ➖ | 0 |
| limit | integer | Limits the amount of results per response | ➖ | 100 |
| order_by | stringEnum:
| Ordering of the results | ➖ | DATE_CREATED |
| sort_order | stringEnum:
| Sort order of the results | ➖ | DESC |
Example
GET /agreements?offset=0&limit=10&order_by=DATE_CREATED&sort_order=DESC
Response Body
| Field | Type | Description | Example |
|---|---|---|---|
| agreements | array | An array of agreements | Agreement |
| results_count | integer | The total amount of results available | 200 |
| next_request | string | Next request URL | /agreements?offset=20?limit=10 |
| previous_request | string | Previous request made URL | /agreements?offset=10?limit=10 |
View Response Example
Example
{
"agreements": [
{
"id": "AbCd1234",
"title": "Harbour License Agreement",
"group_name": "My agreements",
"datetime_created": "2022-01-01T23:59:59.999999Z",
"datetime_last_updated": "2022-01-01T23:59:59.999999Z",
"created_by": {
"id": "AbCd1234",
"email": "harbour@harbourshare.com"
},
"last_updated_by": {
"id": "AbCd1234",
"email": "harbour@harbourshare.com"
},
"agreement_links": [
{
"id": "AbCd1234",
"is_active": true,
"status": "PENDING",
"link_url": "https://hrbr.co/AbCd1234",
"more_info": "https://api.harbourshare.com/agreementlinks/AbCd1234"
}
],
"document_inputs": [
{
"default_value": "harbour@harbourshare.com",
"id": "AbCd1234",
"input_type": "TEXTINPUT",
"is_required": true,
"place_holder": "Your email...",
"record_label": "Email",
"value": "harbour@harbourshare.com"
}
]
}
],
"results_count": 200,
"next_request": "https://api.harbourshare.com/agreements?offset=20?limit=10",
"previous_request": "https://api.harbourshare.com/agreements?offset=10?limit=10"
}
Test it live
Get agreement by ID
This endpoint returns the details of an specific agreement.
What can you do with this information?
When querying data from this endpoint you will be able retrieve information from a specific agreement by passing its unique identifier.
Endpoint
GET /agreements/{agreement_id}
Path Parameters
| Field | Type | Description | Example | Required |
|---|---|---|---|---|
| agreement_id | string | Agreement ID | AGREE-1234 | ✔️ |
Query Parameters
null
Response Body
View Response Example
Example
{
"id": "AbCd1234",
"title": "Harbour License Agreement",
"group_name": "My agreements",
"datetime_created": "2022-01-01T23:59:59.999999Z",
"datetime_last_updated": "2022-01-01T23:59:59.999999Z",
"created_by": {
"id": "AbCd1234",
"email": "harbour@harbourshare.com"
},
"last_updated_by": {
"id": "AbCd1234",
"email": "harbour@harbourshare.com"
},
"agreement_links": [
{
"id": "AbCd1234",
"is_active": true,
"status": "PENDING",
"link_url": "https://hrbr.co/AbCd1234",
"more_info": "https://api.harbourshare.com/agreementlinks/AbCd1234"
}
],
"document_inputs": [
{
"default_value": "harbour@harbourshare.com",
"id": "AbCd1234",
"input_type": "TEXTINPUT",
"is_required": true,
"place_holder": "Your email...",
"record_label": "Email",
"value": "harbour@harbourshare.com"
}
]
}
Test it live
Download agreement
This endpoint returns the base64 string of the original (if exists) and PDF files for a specific agreement
What can you do with this information?
When querying data from this endpoint you will be able to download the original file (e.g. Word doc) and the PDF file for a specific agreement.
Endpoint
GET /agreements/{agreement_id}/download
Path Parameters
| Field | Type | Description | Example | Required |
|---|---|---|---|---|
| agreement_id | string | Agreement ID | AGREE-1234 | ✔️ |
Query Parameters
null
Response Body
| Field | Type | Description | Example |
|---|---|---|---|
| original_file | string | Base64 of the original agreement file | 0M8R4KGx... |
| pdf_file | array | Base64 of the agreement PDF file | JVBERi0x... |
View Response Example
Example
{
"original_file": "0M8R4KGx...",
"pdf_file": "JVBERi0x..."
}
Test it live
# Agreement Body
| Field | Type | Description | Example |
|---|---|---|---|
| id | string | Id of the agreement | AGREE-1234 |
| title | string | Title of the agreement | Harbour License Agreement |
| group_name | string | The template group it belongs to | My agreements |
| datetime_created | string | Date and time the agreement was created | 2022-01-01T23:59:59.999999Z |
| datetime_last_updated | string | Date and time the agreement was last updated | 2022-01-01T23:59:59.999999Z |
| created_by | object | User that created the agreement | User |
| last_updated_by | object | User that last updated the agreement | User |
| agreement_links | array | Agreement links that were generated from the agreement | Agreement Link |
| document_inputs | array | Document input fields in the agreement | Document Input |
Agreement Example
Example
{
"id": "AbCd1234",
"title": "Harbour License Agreement",
"group_name": "My agreements",
"datetime_created": "2022-01-01T23:59:59.999999Z",
"datetime_last_updated": "2022-01-01T23:59:59.999999Z",
"created_by": {
"id": "AbCd1234",
"email": "harbour@harbourshare.com"
},
"last_updated_by": {
"id": "AbCd1234",
"email": "harbour@harbourshare.com"
},
"agreement_links": [
{
"id": "AbCd1234",
"is_active": true,
"status": "PENDING",
"link_url": "https://hrbr.co/AbCd1234",
"more_info": "https://api.harbourshare.com/agreementlinks/AbCd1234"
}
],
"document_inputs": [
{
"default_value": "harbour@harbourshare.com",
"id": "AbCd1234",
"input_type": "TEXTINPUT",
"is_required": true,
"place_holder": "Your email...",
"record_label": "Email",
"value": "harbour@harbourshare.com"
}
]
}
# Agreement Links
# Methods
| Name | Endpoint |
|---|---|
| List agreement links | GET /agreement_links |
| Get agreement link by ID | GET /agreement_links/{agreement_link_id} |
| Download agreement link | GET /agreement_links/{agreement_link_id}/download |
| Create agreement link | POST /agreement_links |
List agreement links
This endpoint returns a list of agreements links under a specific organization.
What can you do with this information?
When querying data from this endpoint you will be able to access all the agreement links that have been created inside your organization (the COMPLETED ones and also the ones still IN PROGRESS).
Endpoint
GET /agreement_links
Path Parameters
null
Query Parameters
| Field | Type | Description | Required | Default Value |
|---|---|---|---|---|
| offset | integer | Skip the records before the offset | ➖ | 0 |
| limit | integer | Limits the amount of results per response | ➖ | 100 |
| order_by | stringEnum:
| Ordering of the results | ➖ | DATE_CREATED |
| sort_order | stringEnum:
| Sort order of the results | ➖ | DESC |
Example
GET /agreements?offset=0&limit=10&order_by=DATE_CREATED&sort_order=DESC
Response Body
| Field | Type | Description | Example |
|---|---|---|---|
| agreement_links | array | An array of agreement links | Agreement Link |
| results_count | integer | The total amount of results available | 200 |
| next_request | string | Next request URL | /agreement_links?offset=20?limit=10 |
| previous_request | string | Previous request made URL | /agreement_links?offset=10?limit=10 |
View Response Example
Example
{
"agreement_links": [
{
"id": "AbCd1234",
"request_title": "Harbour License Agreement",
"brand": {
"id": "AbCd1234",
"name": "Harbour",
"group": "Default"
},
"agreement": {
"id": "AbCd1234",
"more_info": "https://api.harbourshare.com/agreements/AbCd1234"
},
"status": "PENDING",
"datetime_created": "2022-01-01T23:59:59.999999Z",
"datetime_last_updated": "2022-01-01T23:59:59.999999Z",
"datetime_completed": "2022-01-01T23:59:59.999999Z",
"auth_mode": "PUBLIC",
"is_active": true,
"link_url": "https://hrbr.co/AbCd1234",
"created_by": {
"id": "AbCd1234",
"email": "harbour@harbourshare.com"
},
"recipients": [
{
"name": "Jane Doe",
"email": "janedoe@harbourshare.com",
"role": "SIGNER",
"signing_order": 1,
"datetime_viewed": "2022-01-01T23:59:59.999999Z",
"datetime_signed": "2022-01-01T23:59:59.999999Z",
"inputs": [
{
"id": "AbCd1234",
"input_type": "TEXTINPUT",
"record_label": "Email",
"place_holder": "Your email...",
"default_value": "harbour@harbourshare.com",
"is_required": true,
"value": "harbour@harbourshare.com"
}
],
"items": [
{
"id": "AbCd1234",
"more_info": "https://api.harbourshare.com/items/AbCd1234"
}
]
}
],
"document_inputs": [
{
"id": "AbCd1234",
"input_type": "TEXTINPUT",
"record_label": "Email",
"place_holder": "Your email...",
"default_value": "harbour@harbourshare.com",
"is_required": true,
"value": "harbour@harbourshare.com"
}
]
}
],
"results_count": 200,
"next_request": "https://api.harbourshare.com/agreementlinks?offset=20?limit=10",
"previous_request": "https://api.harbourshare.com/agreementlinks?offset=10?limit=10"
}
Test it live
Get agreement link by ID
This endpoint returns an agreement link under its specific id.
What can you do with this information?
When querying data from this endpoint you will be able retrieve information from a specific agreement link by passing its unique identifier.
Endpoint
GET /agreement_links/{agreement_link_id}
Path Parameters
| Field | Type | Description | Example | Required |
|---|---|---|---|---|
| agreement_link_id | string | Agreement link ID | AGREE-1234 | ✔️ |
Query Parameters
null
Response Body
View Response Example
Example
{
"id": "AbCd1234",
"request_title": "Harbour License Agreement",
"brand": {
"id": "AbCd1234",
"name": "Harbour",
"group": "Default"
},
"agreement": {
"id": "AbCd1234",
"more_info": "https://api.harbourshare.com/agreements/AbCd1234"
},
"status": "PENDING",
"datetime_created": "2022-01-01T23:59:59.999999Z",
"datetime_last_updated": "2022-01-01T23:59:59.999999Z",
"datetime_completed": "2022-01-01T23:59:59.999999Z",
"auth_mode": "PUBLIC",
"is_active": true,
"link_url": "https://hrbr.co/AbCd1234",
"created_by": {
"id": "AbCd1234",
"email": "harbour@harbourshare.com"
},
"recipients": [
{
"name": "Jane Doe",
"email": "janedoe@harbourshare.com",
"role": "SIGNER",
"signing_order": 1,
"datetime_viewed": "2022-01-01T23:59:59.999999Z",
"datetime_signed": "2022-01-01T23:59:59.999999Z",
"inputs": [
{
"id": "AbCd1234",
"input_type": "TEXTINPUT",
"record_label": "Email",
"place_holder": "Your email...",
"default_value": "harbour@harbourshare.com",
"is_required": true,
"value": "harbour@harbourshare.com"
}
],
"items": [
{
"id": "AbCd1234",
"more_info": "https://api.harbourshare.com/items/AbCd1234"
}
]
}
],
"document_inputs": [
{
"id": "AbCd1234",
"input_type": "TEXTINPUT",
"record_label": "Email",
"place_holder": "Your email...",
"default_value": "harbour@harbourshare.com",
"is_required": true,
"value": "harbour@harbourshare.com"
}
]
}
Test it live
Download agreement link
This endpoint returns all the completed agreements and any attached item within the agreement link.
What can you do with this information?
When querying data from this endpoint you will be able to download completed agreements and any attached item.
Endpoint
GET /agreement_links/{agreement_link_id}/download
Path Parameters
| Field | Type | Description | Example | Required |
|---|---|---|---|---|
| agreement_link_id | string | Agreement link ID | ng3E2dsKK | ✔️ |
Query Parameters
| Field | Type | Description | Required | Default Value |
|---|---|---|---|---|
| download_type | stringEnum:
| Agreement link ID | ➖ | ONLY_FILE |
| offset | integer | Skip the records before the offset | ➖ | 0 |
Example
GET /agreement_links/{agreement_link_id}/download?download_type=ONLY_FILE&offset=0
Response Body
| Field | Type | Description | Example |
|---|---|---|---|
| completed_agreement | string | Base64 of the completed agreement PDF file | 0M8R4KGx... |
| items | array | Items attached to the agreement link | Item |
| results_count | integer | The total amount of results available | 200 |
| next_request | string | Next request URL | /agreementlinks?offset=1 |
| previous_request | string | Previous request made URL | /agreementlinks?offset=0 |
View Response Example
Example
{
"completed_agreement": "...4NgolJUVPRgo=",
"items": [
{
"id": "AbCd1234",
"download_url": "https://storage.googleapis.com/",
"expires_at": "2022-01-01T23:59:59.999999Z",
"more_info": "https://api.harbourshare.com/items/AbCd1234"
}
],
"results_count": 200,
"next_request": "https://api.harbourshare.com/agreementlinks?offset=1",
"previous_request": "https://api.harbourshare.com/agreementlinks?offset=0"
}
Test it live
# Agreement Link Body
| Field | Type | Description | Example |
|---|---|---|---|
| id | string | Id of the agreement link | AbCd1234 |
| request_title | string | Request title of the agreement link (shown in the signature page) | Harbour License Agreement |
| brand | object | Organization's brand used for this agreement link | Brand |
| agreement | object | Original agreement where agreement link was generated from | Agreement |
| status | string | Status of the agreement link |
|
| datetime_created | string | Date and time the agreement link was created | 2022-01-01T23:59:59.999999Z |
| datetime_last_updated | string | Date and time the agreement link was updated for the last time | 2022-01-01T23:59:59.999999Z |
| datetime_completed | string | Date and time the agreement link was completed for the last time | 2022-01-01T23:59:59.999999Z |
| auth_mode | enum | Authentication mode of the agreement link |
|
| is_active | boolean | Active status of the agreement link | True |
| link_url | string | Agreement link URL | https://hrbr.co/AbCd1234 |
| created_by | object | User that created the agreement | User |
| recipients | array | Recipients of the agreement link (signer or reviewers) | Recipients |
| document_inputs | array | Document inputs inserted when building the agreement link | Document Input |
Agreement Link Example
Example
{
"id": "AbCd1234",
"request_title": "Harbour License Agreement",
"brand": {
"id": "AbCd1234",
"name": "Harbour",
"group": "Default"
},
"agreement": {
"id": "AbCd1234",
"more_info": "https://api.harbourshare.com/agreements/AbCd1234"
},
"status": "PENDING",
"datetime_created": "2022-01-01T23:59:59.999999Z",
"datetime_last_updated": "2022-01-01T23:59:59.999999Z",
"datetime_completed": "2022-01-01T23:59:59.999999Z",
"auth_mode": "PUBLIC",
"is_active": true,
"link_url": "https://hrbr.co/AbCd1234",
"created_by": {
"id": "AbCd1234",
"email": "harbour@harbourshare.com"
},
"recipients": [
{
"name": "Jane Doe",
"email": "janedoe@harbourshare.com",
"role": "SIGNER",
"signing_order": 1,
"datetime_viewed": "2022-01-01T23:59:59.999999Z",
"datetime_signed": "2022-01-01T23:59:59.999999Z",
"inputs": [
{
"id": "AbCd1234",
"input_type": "TEXTINPUT",
"record_label": "Email",
"place_holder": "Your email...",
"default_value": "harbour@harbourshare.com",
"is_required": true,
"value": "harbour@harbourshare.com"
}
],
"items": [
{
"id": "AbCd1234",
"more_info": "https://api.harbourshare.com/items/AbCd1234"
}
]
}
],
"document_inputs": [
{
"id": "AbCd1234",
"input_type": "TEXTINPUT",
"record_label": "Email",
"place_holder": "Your email...",
"default_value": "harbour@harbourshare.com",
"is_required": true,
"value": "harbour@harbourshare.com"
}
]
}
Create agreement link
This endpoint creates an agreement link through the API.
Where could you use it?
When bulk creating agreement links or even automating e-signature processes.
Endpoint
POST /agreement_links
Path Parameters
null
Query Parameters
| Field | Type | Description | Required |
|---|---|---|---|
| agreement_id | string | Unique identifier of an agreement template. | ✔️ |
Example
POST /agreement_links?agreement_id=AGREE-AbCd1234
Request Body
| Field | Type | Description | Required | Default Value |
|---|---|---|---|---|
| brand_id | string | Brand id to be used in the agreement link | ✔️ | |
| link_name | string | Link name for internal control | ➖ | {agreement_title} - {current_date} |
| request_title | string | Title of the agreement link (shown in the signature page) | ➖ | Agreement |
| personal_message | string | Personal message for recipient (shown in the signature page) | ➖ | |
| custom_tags | array | Custom tags to identify your agreement link inside Harbour | ➖ | |
| destination_folder_id | string | Folder id where the completed agreement will be saved | ✔️ | |
| attached_content | array | Array of base64 content to be attached within the agreement link | ➖ | |
| document_inputs | array of Document Input | Value for the document inputs | * | |
| auth_mode | string Enum:
| Authentication mode of the agreement link | ➖ | PUBLIC |
| passcode | string | Passcode value (when auth_mode is set to PASSCODE) | ** | |
| recipients | array of Recipient | Recipients of the agreement link (signer or reviewers) | *** | |
| enforce_signing_order | boolean | Enforce signing order of the signers (when auth_mode is set to EMAILS) | ➖ | False |
| automated_reminders | boolean | Send automated reminders (when auth_mode is set to EMAILS) | ➖ | |
| creator_email | string | Email that will receive all the configured notifications | **** | |
| notification_settings | object Notification Settings | Settings for agreement link notifications | ➖ | |
| is_active | boolean | Active status of the agreement link | ➖ | True |
Note
* Required, when at least one 'required' document input exists for the agreement template
** Required, when auth_mode is set to "PASSCODE"
*** Required, when auth_mode is set to "EMAILS"
**** Required, when nofitication_settings are sent
View Request Example
Example
{
"brand_id": "BRAND-AbCd1234",
"link_name": "Agreement - Apr 28 2022",
"request_title": "Agreement",
"personal_message": "Thanks for your business",
"custom_tags": [
"tag1",
"tag2",
"tag3"
],
"destination_folder_id": "folder-AbCd1234",
"attached_content": [
"...4NgolJUVPRgo=",
"...4NgolJUVPRgo="
],
"document_inputs": [
{
"id": "AbCd1234",
"value": "harbour@harbourshare.com"
}
],
"auth_mode": "PUBLIC",
"passcode": "1234",
"recipients": [
{
"name": "John Doe",
"email": "john@harbourshare.com",
"role": "SIGNER"
}
],
"enforce_signing_order": true,
"automated_reminders": true,
"creator_email": "harbour@harbourshare.com",
"notification_settings": {
"notify_on_view": true,
"notify_on_completition": true,
"bcc_on_completition": [
"jane@harbourshare.com",
"roger@harbourshare.com"
]
},
"is_active": true
}
Response Body
| Field | Type | Description | Example |
|---|---|---|---|
| id | string | Id of the agreement link | AbCd1234 |
| datetime_created | string | Date and time the agreement link was created | 2022-01-01T23:59:59.999999Z |
| link_url | string | Agreement link URL | https://hrbr.co/AbCd1234 |
| qr_code_image | string | Base64 of the QR code link image | ...4NgolJUVPRgo= |
View Response Example
Example
HTTP/2 201 Created
Content-Type: application/json
{
"id": "AbCd1234",
"datetime_created": "2022-01-01T23:59:59.999999Z",
"link_url": "https://hrbr.co/AbCd1234",
"qr_code_image": "...4NgolJUVPRgo="
}
Explore it further 🕵🏼♂️
Ever imagined bulk creating Agreement Links inside your team favorite tool?
# Items
# Methods
| Name | Endpoint |
|---|---|
| List items | GET /items |
| Get item by ID | GET /items/{item_id} |
List items
This endpoint returns a list of items under a specific organization.
What can you do with this information?
When querying data from this endpoint you will be able to access all the items that have been created inside your organization.
Endpoint
GET /items
Path Parameters
null
Query Parameters
| Field | Type | Description | Required | Default Value |
|---|---|---|---|---|
| offset | integer | Skip the records before the offset | ➖ | 0 |
| limit | integer | Limits the amount of results per response | ➖ | 100 |
| order_by | stringEnum:
| Ordering of the results | ➖ | DATE_CREATED |
| sort_order | stringEnum:
| Sort order of the results | ➖ | DESC |
Example
GET /agreements?offset=0&limit=10&order_by=DATE_CREATED&sort_order=DESC
Response Body
| Field | Type | Description | Example |
|---|---|---|---|
| items | array | An array of items | Item |
| results_count | integer | The total amount of results available | 200 |
| next_request | string | Next request URL | /items?offset=20?limit=10 |
| previous_request | string | Previous request made URL | /items?offset=10?limit=10 |
View Response Example
Example
{
"items": [
{
"id": "AbCd1234",
"name": "Happy Puppy",
"datetime_created": "2022-01-01T23:59:59.999999Z",
"vision_tags": "['Tag1', 'Tag2', 'Tag3']",
"web_matches": "['Match1, 'Match2', 'Match3']",
"preview_img": "...4NgolJUVPRgo=",
"media_category": "IMAGE",
"file_extension": "mp4",
"size_bytes": 1290984,
"width_px": 500,
"height_px": 500,
"duration_seconds": 2.1,
"agreement_link": "https://api.harbourshare.com/v1/agreement_links/AbCd1234",
"folder": "https://api.harbourshare.com/v1/folders/AbCd1234"
}
],
"results_count": 200,
"next_request": "https://api.harbourshare.com/items?offset=20?limit=10",
"previous_request": "https://api.harbourshare.com/items?offset=10?limit=10"
}
Test it live
Get item by id
This endpoint returns an item its specific id.
What can you do with this information?
When querying data from this endpoint you will be able retrieve information from a specific item by passing its unique identifier.
Endpoint
GET /items/{item_id}
Path Parameters
| Field | Type | Description | Example | Required |
|---|---|---|---|---|
| item_id | string | Item ID | Pr6GqXoA | ✔️ |
Query Parameters
null
Response Body
View Response Example
Example
{
"id": "AbCd1234",
"name": "Happy Puppy",
"datetime_created": "2022-01-01T23:59:59.999999Z",
"vision_tags": "['Tag1', 'Tag2', 'Tag3']",
"web_matches": "['Match1, 'Match2', 'Match3']",
"preview_img": "...4NgolJUVPRgo=",
"media_category": "IMAGE",
"file_extension": "mp4",
"size_bytes": 1290984,
"width_px": 500,
"height_px": 500,
"duration_seconds": 2.1,
"agreement_link": "https://api.harbourshare.com/v1/agreement_links/AbCd1234",
"folder": "https://api.harbourshare.com/v1/folders/AbCd1234"
}
Test it live
# Item Body
| Field | Type | Description | Example |
|---|---|---|---|
| id | string | Id of the item | AbCd1234 |
| name | string | Name of the item | Happy Puppy |
| datetime_created | string | Date and time the item was created | 2022-01-01T23:59:59.999999Z |
| vision_tags | string | Vision AI auto generated tags from the item | ['Tag1', 'Tag2', 'Tag3'] |
| web_matches | string | Web matches from the item appears in the internet | ['Match1, 'Match2', 'Match3'] |
| preview_img | string | Base64 preview image of the item | ...4NgolJUVPRgo= |
| media_category | string | Media category of the item | IMAGE |
| file_extension | string | File extension of the item | jpg |
| size_bytes | integer | Size of the item in bytes | 1290984 |
| width_px | integer | Width of the item in px | 500 |
| height_px | integer | Height of the item in px | 500 |
| duration_seconds | number | Duration of the item in seconds | 2.1 |
| agreement_link | string | Agreement link more info url from where item was attached to | https://api.harbourshare.com/v1/agreement_links/AbCd1234 |
| folder | string | Folder more info url from where item was attached to | https://api.harbourshare.com/v1/folders/AbCd1234 |
Item Example
Example
{
"id": "AbCd1234",
"name": "Happy Puppy",
"datetime_created": "2022-01-01T23:59:59.999999Z",
"vision_tags": "['Tag1', 'Tag2', 'Tag3']",
"web_matches": "['Match1, 'Match2', 'Match3']",
"preview_img": "...4NgolJUVPRgo=",
"media_category": "IMAGE",
"file_extension": "mp4",
"size_bytes": 1290984,
"width_px": 500,
"height_px": 500,
"duration_seconds": 2.1,
"agreement_link": "https://api.harbourshare.com/v1/agreement_links/AbCd1234",
"folder": "https://api.harbourshare.com/v1/folders/AbCd1234"
}
# Folders
# Methods
| Name | Endpoint |
|---|---|
| List folders | GET /folders |
| Get folder by ID | GET /folders/{folder_id} |
List folders
This endpoint returns a list of folders under a specific organization.
What can you do with this information?
When querying data from this endpoint you will be able to access all the folders that have been created inside your organization, who created it, when it was created and much more.
Endpoint
GET /folders
Path Parameters
null
Query Parameters
| Field | Type | Description | Required | Default Value |
|---|---|---|---|---|
| offset | integer | Skip the records before the offset | ➖ | 0 |
| limit | integer | Limits the amount of results per response | ➖ | 100 |
| order_by | stringEnum:
| Ordering of the results | ➖ | DATE_CREATED |
| sort_order | stringEnum:
| Sort order of the results | ➖ | DESC |
Example
GET /agreements?offset=0&limit=10&order_by=DATE_CREATED&sort_order=DESC
Response Body
| Field | Type | Description | Example |
|---|---|---|---|
| folders | array | An array of folders | Folder |
| results_count | integer | The total amount of results available | 200 |
| next_request | string | Next request URL | /folders?offset=20?limit=10 |
| previous_request | string | Previous request made URL | /folders?offset=10?limit=10 |
View Response Example
Example
{
"folders": [
{
"id": "AbCd1234",
"name": "My agreements",
"datetime_created": "2022-01-01T23:59:59.999999Z",
"created_by": {
"id": "AbCd1234",
"email": "harbour@harbourshare.com"
},
"viewers": [
[
"viewer1@harbourshare.com",
"viewer2@harbourshare.com",
"viewer3@harbourshare.com"
]
],
"collaborators": [
[
"colab1@harbourshare.com",
"colab2@harbourshare.com",
"colab3@harbourshare.com"
]
],
"location_url": "https://harbour.myharbourshare.com/library#folder-AbCd1234"
}
],
"results_count": 200,
"next_request": "https://api.harbourshare.com/v1/folders?offset=20?limit=10",
"previous_request": "https://api.harbourshare.com/v1/folders?offset=10?limit=10"
}
Test it live
Get folder by id
This endpoint returns a folder by its specific id.
What can you do with this information?
When querying data from this endpoint you will be able retrieve information from a specific folder by passing its unique identifier.
Endpoint
GET /folders/{folder_id}
Path Parameters
| Field | Type | Description | Example | Required |
|---|---|---|---|---|
| folder_id | string | Folder Id | folder-AbCd | ✔️ |
Query Parameters
null
Response Body
View Response Example
Example
{
"id": "AbCd1234",
"name": "My agreements",
"datetime_created": "2022-01-01T23:59:59.999999Z",
"created_by": {
"id": "AbCd1234",
"email": "harbour@harbourshare.com"
},
"viewers": [
"viewer1@harbourshare.com",
"viewer2@harbourshare.com",
"viewer3@harbourshare.com"
],
"collaborators": [
"colab1@harbourshare.com",
"colab2@harbourshare.com",
"colab3@harbourshare.com"
],
"location_url": "https://harbour.myharbourshare.com/library#folder-AbCd1234"
}
Test it live
# Folder Body
| Field | Type | Description | Example |
|---|---|---|---|
| id | string | Id of the folder | AbCd1234 |
| name | string | Name of the folder | My agreements |
| datetime_created | string | Date and time the folder was created | 2022-01-01T23:59:59.999999Z |
| created_by | object | User that created the the folder | User |
| viewers | array | People that have view access to the folder | ["viewer1@harbourshare.com", "viewer2@harbourshare.com", "viewer3@harbourshare.com"] |
| collaborators | array | People that have edit access to the folder | ["colab1@harbourshare.com", "colab2@harbourshare.com", "colab3@harbourshare.com"] |
| location_url | string | Location URL of the folder | https://harbour.myharbourshare.com/library#folder-AbCd1234 |
Folder Example
Example
{
"id": "AbCd1234",
"name": "My agreements",
"datetime_created": "2022-01-01T23:59:59.999999Z",
"created_by": {
"id": "AbCd1234",
"email": "harbour@harbourshare.com"
},
"viewers": [
"viewer1@harbourshare.com",
"viewer2@harbourshare.com",
"viewer3@harbourshare.com"
],
"collaborators": [
"colab1@harbourshare.com",
"colab2@harbourshare.com",
"colab3@harbourshare.com"
],
"location_url": "https://harbour.myharbourshare.com/library#folder-AbCd1234"
}
# Organizations
# Methods
| Name | Endpoint |
|---|---|
| List organizations | GET /organizations |
| List brands | GET /organizations/brands |
| Get brand by ID | GET /organizations/brands/{brand_id} |
List organizations
This endpoint returns a list of organizations under the API_KEY.
What can you do with this information?
When querying data from this endpoint you will be able to access all the organizations available, who created it, when it was created and much more.
Endpoint
GET /organizations
Path Parameters
null
Query Parameters
| Field | Type | Description | Required | Default Value |
|---|---|---|---|---|
| offset | integer | Skip the records before the offset | ➖ | 0 |
| limit | integer | Limits the amount of results per response | ➖ | 100 |
| order_by | stringEnum:
| Ordering of the results | ➖ | DATE_CREATED |
| sort_order | stringEnum:
| Sort order of the results | ➖ | DESC |
Example
GET /agreements?offset=0&limit=10&order_by=DATE_CREATED&sort_order=DESC
Response Body
| Field | Type | Description | Example |
|---|---|---|---|
| organizations | array | An array of organizations | Organization |
| results_count | integer | The total amount of results available | 200 |
| next_request | string | Next request URL | /organizations?offset=20?limit=10 |
| previous_request | string | Previous request made URL | /organizations?offset=10?limit=10 |
View Response Example
Example
{
"organizations": [
{
"id": "AbCd1234",
"name": "Harbour Inc.",
"subdomain": "harbour",
"website": "https://harbourshare.com",
"description": "Send and sign in seconds",
"brands": [
"https://api.harbourshare.com/v1/organizations/brands/BRAND-AbCd"
]
}
],
"results_count": 200,
"next_request": "https://api.harbourshare.com/v1/organizations?offset=20?limit=10",
"previous_request": "https://api.harbourshare.com/v1/organizations?offset=10?limit=10"
}
Test it live
# Organization Body
| Field | Type | Description | Example |
|---|---|---|---|
| id | string | Id of the organization | AbCd1234 |
| name | string | Name of the organization | Harbour |
| subdomain | string | Organization's subdomain | harbour |
| website | string | Organization's website | https://harbourshare.com |
| description | string | Organization's description | Send and sign in seconds |
| brands | array | Brands endpoint URL array | https://api.harbourshare.com/v1/organizations/brands/BRAND-AbCd |
Organization Example
Example
{
"id": "AbCd1234",
"name": "Harbour Inc.",
"subdomain": "harbour",
"website": "https://harbourshare.com",
"description": "Send and sign in seconds",
"brands": [
"https://api.harbourshare.com/v1/organizations/brands/BRAND-AbCd"
]
}
List brands
This endpoint returns a list of brands under an organization.
What can you do with this information?
When querying data from this endpoint you will be able to access all the brands available, who created it, when it was created and much more.
Endpoint
GET /organizations/brands
Path Parameters
null
Query Parameters
| Field | Type | Description | Required | Default Value |
|---|---|---|---|---|
| offset | integer | Skip the records before the offset | ➖ | 0 |
| limit | integer | Limits the amount of results per response | ➖ | 100 |
| order_by | stringEnum:
| Ordering of the results | ➖ | DATE_CREATED |
| sort_order | stringEnum:
| Sort order of the results | ➖ | DESC |
Example
GET /agreements?offset=0&limit=10&order_by=DATE_CREATED&sort_order=DESC
Response Body
| Field | Type | Description | Example |
|---|---|---|---|
| brands | array | An array of brands | Brand |
| results_count | integer | The total amount of results available | 200 |
| next_request | string | Next request URL | /organizations/brands?offset=20?limit=10 |
| previous_request | string | Previous request made URL | /organizations/brands?offset=10?limit=10 |
View Response Example
Example
{
"brands": [
{
"id": "BRAND-1234",
"title": "Harbour",
"group": "Default",
"datetime_created": "2022-01-01T23:59:59.999999Z",
"created_by": {
"id": "AbCd1234",
"email": "harbour@harbourshare.com"
},
"datetime_last_updated": "2022-01-01T23:59:59.999999Z",
"last_updated_by": {
"id": "AbCd1234",
"email": "harbour@harbourshare.com"
},
"color_theme": "BLUE-DARK",
"logo_img": "...4NgolJUVPRgo=",
"background_img": "...4NgolJUVPRgo="
}
],
"results_count": 200,
"next_request": "https://api.harbourshare.com/v1/organizations/brands?offset=20?limit=10",
"previous_request": "https://api.harbourshare.com/v1/organizations/brands?offset=10?limit=10"
}
Test it live
Get brand by id
This endpoint returns a brand by its specific id.
What can you do with this information?
When querying data from this endpoint you will be able retrieve information from a specific brand by passing its unique identifier.
Endpoint
GET /organizations/brands/{brand_id}
Path Parameters
| Field | Type | Description | Example | Required |
|---|---|---|---|---|
| brand_id | string | Brand Id | BRAND-AbCd | ✔️ |
Query Parameters
null
Response Body
View Response Example
Example
{
"id": "BRAND-1234",
"title": "Harbour",
"group": "Default",
"datetime_created": "2022-01-01T23:59:59.999999Z",
"created_by": {
"id": "AbCd1234",
"email": "harbour@harbourshare.com"
},
"datetime_last_updated": "2022-01-01T23:59:59.999999Z",
"last_updated_by": {
"id": "AbCd1234",
"email": "harbour@harbourshare.com"
},
"color_theme": "BLUE-DARK",
"logo_img": "...4NgolJUVPRgo=",
"background_img": "...4NgolJUVPRgo="
}
Test it live
# Brand Body
| Field | Type | Description | Example |
|---|---|---|---|
| id | string | Id of the brand | AbCd1234 |
| name | string | Name of the brand | Harbour |
| group | string | Group brand belongs to | Default |
| datetime_created | string | Date and time the brand was created | 2022-01-01T23:59:59.999999Z |
| created_by | object | User who created the brand | User |
| datetime_last_updated | string | Date and time the brand was last updated | 2022-01-01T23:59:59.999999Z |
| last_updated_by | object | User who last updated the brand | User |
| color_theme | string | Color theme used by the brand | BLUE-DARK |
| logo_img | string | Base64 of the logo image | ...4NgolJUVPRgo= |
| background_img | string | Base64 of the backgroung image | ...4NgolJUVPRgo= |
Brand Example
Example
{
"id": "BRAND-1234",
"title": "Harbour",
"group": "Default",
"datetime_created": "2022-01-01T23:59:59.999999Z",
"created_by": {
"id": "AbCd1234",
"email": "harbour@harbourshare.com"
},
"datetime_last_updated": "2022-01-01T23:59:59.999999Z",
"last_updated_by": {
"id": "AbCd1234",
"email": "harbour@harbourshare.com"
},
"color_theme": "BLUE-DARK",
"logo_img": "...4NgolJUVPRgo=",
"background_img": "...4NgolJUVPRgo="
}
Users
# User Body
| Field | Type | Description | Example |
|---|---|---|---|
| id | string | Id of the user | AbCd1234 |
string | Email of the user | lucius@harbourshare.com |
User Example
Example
{
"id": "AbCd1234",
"email": "harbour@harbourshare.com"
}
Recipients
# Recipient Body
| Field | Type | Description | Example |
|---|---|---|---|
| name | string | Recipient's full name | Jane Doe |
string | Recipient's email | janedoe@harbourshare.com | |
| role | enum | Recipient's role |
|
| signing_order | integer | Recipient signing order (if exists) | 1 |
| datetime_viewed | string | Date and time the agreement was viewed by the recipient | 2022-01-01T23:59:59.999999Z |
| datetime_signed | string | Date and time the agreement was completed by the recipient | 2022-01-01T23:59:59.999999Z |
| inputs | array | Signer inputs for the agreement | FieldInputs |
| items | array | Items attached to the agreement link | RecipientItem |
Recipient Example
Example
{
"name": "Jane Doe",
"email": "janedoe@harbourshare.com",
"role": "SIGNER",
"signing_order": 1,
"datetime_viewed": "2022-01-01T23:59:59.999999Z",
"datetime_signed": "2022-01-01T23:59:59.999999Z",
"inputs": [
{
"id": "AbCd1234",
"input_type": "TEXTINPUT",
"record_label": "Email",
"place_holder": "Your email...",
"default_value": "harbour@harbourshare.com",
"is_required": true,
"value": "harbour@harbourshare.com"
}
],
"items": [
{
"id": "AbCd1234",
"more_info": "https://api.harbourshare.com/items/AbCd1234"
}
]
}
Recipient Item
# Recipient Item Body
| Field | Type | Description | Example |
|---|---|---|---|
| id | string | Id of the item | AbCd1234 |
| id | string | More info about the item | https://api.harbourshare.com/items/AbCd1234 |
Recipient Example
Example
{
"id": "AbCd1234",
"more_info": "https://api.harbourshare.com/items/AbCd1234"
}
Field Input
# Field Input Body
| Field | Type | Description | Example |
|---|---|---|---|
| id | string | Id of the field | AbCd1234 |
| input_type | string | Type of the field input | TEXTINPUT |
| record_label | string | Field's internal record label | Email |
| place_holder | string | Field's place holder text | Your email... |
| default_value | string | Field's default value | harbour@harbourshare.com |
| is_required | string | Is it a mandatory field | true |
| value | string | Response for the specific field | harbour@harbourshare.com |
Field Input Example
Example
{
"id": "AbCd1234",
"input_type": "TEXTINPUT",
"record_label": "Email",
"place_holder": "Your email...",
"default_value": "harbour@harbourshare.com",
"is_required": true,
"value": "harbour@harbourshare.com"
}
Agreement Link Agreement
# Agreement Link Agreement Body
| Field | Type | Description | Example |
|---|---|---|---|
| id | string | Id of the agreement | AbCd1234 |
| more_info | string | More info about the agreement | https://api.harbourshare.com/agreements/AbCd1234 |
Agreement Link Agreement Example
Example
{
"id": "AbCd1234",
"more_info": "https://api.harbourshare.com/agreements/AbCd1234"
}
Agreement Agreement Link
# Agreement Agreement Link Body
| Field | Type | Description | Example |
|---|---|---|---|
| id | string | Id of the agreement link | AbCd1234 |
| is_active | boolean | Active status of the agreement link | true |
| status | string | Completition status of the agreement link | PENDING |
| link_url | string | Agreement link URL | https://hrbr.co/AbCd1234 |
| more_info | string | More info about the agreement link | https://api.harbourshare.com/agreement_links/AbCd1234 |
Agreement Agreement Link Example
Example
{
"id": "AbCd1234",
"is_active": "true",
"status": "PENDING",
"link_url": "https://hrbr.co/AbCd1234",
"more_info": "https://api.harbourshare.com/agreement_links/AbCd1234"
}
Item Agreement Link
# Item Agreement Link Body
| Field | Type | Description | Example |
|---|---|---|---|
| id | string | Id of the agreement link | AbCd1234 |
| more_info | string | More info about the agreement link | https://api.harbourshare.com/agreement_links/AbCd1234 |
Item Agreement Link Example
Example
{
"id": "AbCd1234",
"more_info": "https://api.harbourshare.com/agreement_links/AbCd1234"
}
Agreement Link Download Item
# Agreement Link Download Item Body
| Field | Type | Description | Example |
|---|---|---|---|
| id | string | Id of the item | AbCd1234 |
| download_url | string | A signed URL from where the item can be downloaded | https://storage.googleapis.com/... |
| expires_at | string | Expiration datetime for the signed URL | 2022-01-01T23:59:59.999999Z |
| more_info | string | More info about the item | https://api.harbourshare.com/items/AbCd1234 |
Agreement Link Download Item Example
Example
{
"id": "AbCd1234",
"download_url": "https://storage.googleapis.com/...",
"expires_at": "2022-01-01T23:59:59.999999Z",
"more_info": "https://api.harbourshare.com/items/AbCd1234"
}
Notification Settings
# Notification Settings Body
| Field | Type | Description | Example |
|---|---|---|---|
| notify_on_view | boolean | Id of the item | True |
| notify_on_completition | boolean | A signed URL from where the item can be downloaded | True |
| bcc_on_completition | array | Expiration datetime for the signed URL | ["jane@harbourshare.com"] |
Notification Settings Example
Example
{
"notify_on_view": true,
"notify_on_completition": true,
"bcc_on_completition": [
"jane@harbourshare.com",
"roger@harbourshare.com"
]
}
# Errors
This section lists the used HTTP response codes and specific internal error codes that could be faced while using the API. Each error entry contains a description of the error, the probable cause, and the recommended action.
ⓘ Note
In case you need any extra help, please feel free to contact us at support@harbourshare.com or book a time with Caio (our Head of API and DX)
HTTP response codes
| Status Code | Description |
|---|---|
| 400 Bad Request | Make sure your request is formatted correctly. |
| 401 Unauthorized | Make sure you've entered your API key correctly. |
| 404 Not Found | Make sure you've entered parameters and/or data payload correctly. |
| 405 Method Not Allowed | Method not allowed by the API. |
| 429 Too Many Requests | The rate limit has been reached. Please try again later. |
| 500 Internal Server Error | The server encountered an error. If this persists, please contact support@harbourshare.com |
Internal error codes
Error code: 0
UNKNOWN_AGREEMENT_ERROR
Cause: Unknown Agreement Error
Action: This error has not been handled. Please contact support@harbourshare.com for more info.
Error code: 1
NOT_ABLE_TO_LIST_AGREEMENTS
Probable cause: There are no agreements created for the specific organization.
What to do: To be able to query agreements using the API, first, you need to create agreements (through Platform or API). Once there is at least one agreement created, you will be able to list them.
Error code: 2
NOT_ABLE_TO_GET_AGREEMENT
Probable cause: Specific agreement doesn't exists for the particular organization or the entered id is wrong.
What to do: To be able to query a specific agreement using the API, first, you need to make sure you entered the correct id and if it actually belongs to the organization where the API key was created from.
How to do it: List all agreements available in your organization and make sure the id you are querying for is also listed.
Listing agreements
curl -X GET 'https://api.harbourshare.com/v1/agreements' \
-H 'X-API-KEY: {your_api_key}'
Checking response
{
"agreements": [
{
>> "id": "AbCd1234", <<
.
.
.
}
],
"results_count": 200,
"next_request": "https://api.harbourshare.com/agreements?offset=20?limit=10",
"previous_request": "https://api.harbourshare.com/agreements?offset=10?limit=10"
}
Error code: 3
NOT_ABLE_TO_DOWNLOAD_AGREEMENT
Probable cause: Specific agreement doesn't exists for the particular organization or the entered id is wrong.
What to do: To be able to download a specific agreement using the API, first, you need to make sure you entered the correct id and if it actually belongs to the organization where the API key was created from.
How to do it: List all agreements available in your organization and make sure the id you are querying for is also listed.
Listing agreements
curl -X GET 'https://api.harbourshare.com/v1/agreements' \
-H 'X-API-KEY: {your_api_key}'
Checking response
{
"agreements": [
{
>> "id": "AbCd1234", <<
.
.
.
}
],
"results_count": 200,
"next_request": "https://api.harbourshare.com/agreements?offset=20?limit=10",
"previous_request": "https://api.harbourshare.com/agreements?offset=10?limit=10"
}
Error code: 100
UNKNOWN_AGREEMENT_LINK_ERROR
Cause: Unknown Agreement Link Error
Action: This error has not been handled. Please contact support@harbourshare.com for more info.
Error code: 101
NOT_ABLE_TO_LIST_AGREEMENT_LINKS
Probable cause: There are no agreements links created for the specific organization.
What to do: To be able to query agreements links using the API, first, you need to create agreement links (through Platform or API). Once there is at least one agreement created, you will be able to list them.
Error code: 102
NOT_ABLE_TO_GET_AGREEMENT_LINK
Probable cause: Specific agreement link doesn't exists for the particular organization or the entered id is wrong.
What to do: To be able to query a specific agreement link using the API, first, you need to make sure you entered the correct id and if it actually belongs to the organization where the API key was created from.
How to do it: List all agreements links available in your organization and make sure the id you are querying for is also listed.
Listing agreement links
curl -X GET 'https://api.harbourshare.com/v1/agreement_links' \
-H 'X-API-KEY: {your_api_key}'
Checking response
{
"agreement_links": [
{
>> "id": "AbCd1234", <<
.
.
.
}
],
"results_count": 200,
"next_request": "https://api.harbourshare.com/agreementlinks?offset=20?limit=10",
"previous_request": "https://api.harbourshare.com/agreementlinks?offset=10?limit=10"
}
Error code: 103
NOT_ABLE_TO_DOWNLOAD_AGREEMENT_LINK
Probable cause: Specific agreement link doesn't exists for the particular organization or the entered id is wrong.
What to do: To be able to download a completed agreement for a specific agreement link using the API, first, you need to make sure you entered the correct id and if it actually belongs to the organization where the API key was created from.
How to do it: List all agreements available in your organization and make sure the id you are querying for is also listed.
Listing agreement links
curl -X GET 'https://api.harbourshare.com/v1/agreements' \
-H 'X-API-KEY: {your_api_key}'
Checking response
{
"agreement_links": [
{
>> "id": "AbCd1234", <<
.
.
.
}
],
"results_count": 200,
"next_request": "https://api.harbourshare.com/agreementlinks?offset=20?limit=10",
"previous_request": "https://api.harbourshare.com/agreementlinks?offset=10?limit=10"
}
Error code: 200
UNKNOWN_ITEM_ERROR
Cause: Unknown Item Error
Action: This error has not been handled. Please contact support@harbourshare.com for more info.
Error code: 201
NOT_ABLE_TO_LIST_ITEMS
Probable cause: There are no items created for the specific organization.
What to do: To be able to query items using the API, first, you need to create an item (through Platform or API). Once there is at least one agreement created, you will be able to list them.
Error code: 202
NOT_ABLE_TO_GET_ITEM
Probable cause: Specific item exists for the particular organization or the entered id is wrong.
What to do: To be able to query a specific item using the API, first, you need to make sure you entered the correct id and if it actually belongs to the organization where the API key was created from.
How to do it: List all item available in your organization and make sure the id you are querying for is also listed.
Listing items
curl -X GET 'https://api.harbourshare.com/v1/items' \
-H 'X-API-KEY: {your_api_key}'
Checking response
{
"items": [
{
>> "id": "AbCd1234", <<
.
.
.
}
],
"results_count": 200,
"next_request": "https://api.harbourshare.com/items?offset=20?limit=10",
"previous_request": "https://api.harbourshare.com/items?offset=10?limit=10"
}
Error code: 300
UNKNOWN_FOLDER_ERROR
Cause: Unknown Folder Error
Action: This error has not been handled. Please contact support@harbourshare.com for more info.
Error code: 301
NOT_ABLE_TO_LIST_FOLDERS
Probable cause: There are no active folders for the specific organization.
What to do: To be able to query folders using the API, first, you need to make sure you have at least one active folder inside your Harbour Organization. Contact your Organization Admin or support@harbourshare.com if you're not sure how to check it.
Error code: 302
NOT_ABLE_TO_GET_FOLDER
Probable cause: Specific folder doesn't exist for the particular organization or the entered id is wrong.
What to do: To be able to query a specific folder using the API, first, yot acu need to make sure you entered the correct folder_id and if actually belongs to the organization where the API key was created from.
How to do it: List all folders available under your organization and make sure the id you are querying for is present in the returned list.
Listing folders
curl -X GET 'https://api.harbourshare.com/v1/folders' \
-H 'X-API-KEY: {your_api_key}'
Checking response
{
"folders": [
{
>> "id": "AbCd1234", <<
.
.
.
}
],
"results_count": 200,
"next_request": "https://api.harbourshare.com/folders?offset=20?limit=10",
"previous_request": "https://api.harbourshare.com/folders?offset=10?limit=10"
}
Error code: 400
UNKNOWN_ORGANIZATION_ERROR
Cause: Unknown Organization Error
Action: This error has not been handled. Please contact support@harbourshare.com for more info.
Error code: 401
NOT_ABLE_TO_LIST_ORGANIZATIONS
Probable cause: There are no active organizations.
What to do: To be able to query organizations using the API, first, you need to make sure you have at least one active organization inside your Harbour Account. Contact your Organization Admin or support@harbourshare.com if you're not sure how to check it.
Error code: 500
UNKNOWN_BRAND_ERROR
Cause: Unknown Brand Error
Action: This error has not been handled. Please contact support@harbourshare.com for more info.
Error code: 501
NOT_ABLE_TO_LIST_BRANDS
Probable cause: There are no active brands for the specific organization.
What to do: To be able to query brands using the API, first, you need to make sure you have at least one active brands inside your Harbour Organization. Contact your Organization Admin or support@harbourshare.com if you're not sure how to check it.
Error code: 502
NOT_ABLE_TO_GET_BRAND
Probable cause: Specific brand doesn't exist for the particular organization or the entered id is wrong.
What to do: To be able to query a specific brand using the API, first, you need to make sure you entered the correct brand_id and if actually belongs to the organization where the API key was created from.
How to do it: List all brands available under your organization and make sure the id you are querying for is present in the returned list.
Listing brands
curl -X GET 'https://api.harbourshare.com/v1/organizations/brands' \
-H 'X-API-KEY: {your_api_key}'
Checking response
{
"brands": [
{
>> "id": "AbCd1234", <<
.
.
.
}
],
"results_count": 200,
"next_request": "https://api.harbourshare.com/organizations/brands?offset=20?limit=10",
"previous_request": "https://api.harbourshare.com/organizations/brands?offset=10?limit=10"
}
# Versioning Policy
The following section explains in detail Harbour's API versioning policy.
This policy is used to support the evolution and improvement of our services without impacting our current clients' integrations. It also creates a continuous and predictable release pattern for our API.
# How we version
Harbour introduces new changes to the API in 3 ways depending on the changes being implemented:
Current version implementationA minor version releaseA major version release
When Harbour releases a new API version, you can choose to upgrade to gain access to new features. When changes are implemented into the current API version, these features will become available to customers using this version, without needing an upgrade.
The most recent product improvements will be included in the latest version of the API. We recommend upgrading to the latest version in order to take advantage of new functionality and optimize for the best user experience.
ⓘ Note
A publicly released version of an Harbour API will never change in any way that could impact your integration.
Current version implementation
Harbour will implement changes into current API version, without a new version release, when the changes being introduced will not interfere with your integration. These changes represent independent features which do not alter pre-existing logic. For example:
- Adding new API endpoints
- Adding optional request parameters to existing API endpoints
- Reordering properties returned from existing API endpoints
- Adding a new Core Resource
In this case, you can use these changes immediately without having to upgrade API version (if you are currently on the API version in which the changes were introduced).
Minor releases
Harbour will release a minor API version when the changes being introduced are considered backwards compatible, i.e. additive changes. For example:
- Adding new properties to the responses from existing API endpoints
- Altering the message attributes returned by validation failures or other errors
- Adding new values to existing properties in responses from existing API endpoints
In this case, it is safe for you to move from one minor version to another (unless you consider additive changes to be backwards incompatible). Minor versions are released more frequently, and contain incremental changes to the API.
Major releases
Harbour will release a major API version if any of the changes being introduced are backwards incompatible. In this case, if you would like to move to a new major version you will likely need to update your integration.
Major versions are released less frequently.
Harbour considers the following changes to be backwards incompatible:
- Removing a feature of the API
- Removing or renaming a resource, field, method or an enum value
- Changing the type of a field (eg. integer becomes string or float)
- Changing the URL format
- Adding a new or modifying an existing validation to an existing resource
- Changing existing error response codes/messages
- Changing authentication mechanism
# Release Notes
# API v1.2 🔗
May 23rd 2022
API v1.2 made possible to query any folder and/or organization information within Harbour and also enabling the ability to create Agreement Links on the fly.
Agreement links methods 🔗
| Name | Endpoint |
|---|---|
| Create agreement link | POST /agreement_links |
Folders methods 📂
| Name | Endpoint |
|---|---|
| List folders | GET /folders |
| Get folder by ID | GET /folders/{folder_id} |
Organizations methods 🏢
| Name | Endpoint |
|---|---|
| List organizations | GET /organizations |
| List brands | GET /organizations/brands |
| Get brand by ID | GET /organizations/brands/{brand_id} |
Explore it further 🕵🏼♂️
Ever imagined bulk creating Agreement Links inside your team favorite tool?
API v1.1 ⚡
April 26th 2022
In this version of the API we enabled more resources to be queried within the API. Now besides querying data from Agreements endpoint you will be able to:
- Query data from our agreement links endpoint and all its available methods
- Query data from our items endpoint and all its available methods
Agreement links methods 🔗
| Name | Endpoint |
|---|---|
| List agreement links | GET /agreement_links |
| Get agreement link by ID | GET /agreement_links/{agreement_link_id} |
| Download agreement link | GET /agreement_links/{agreement_link_id}/download |
Items methods 📹
| Name | Endpoint |
|---|---|
| List items | GET /items |
| Get item by ID | GET /items/{item_id} |
Those endpoints enable our users to retrieve most of the information available in Harbour and related any agreement, signed agreement or any attached media.
API v1.0 🎉
April 12th 2022
print("Hello World")
- Agreements endpoint 📄
The first version of Harbour's API includes three methods for querying Agreements within your organization using our API:
| Name | Endpoint |
|---|---|
| List agreements | GET /agreements |
| Get agreement by ID | GET /agreements/{agreement_id} |
| Download agreement | GET /agreements/{agreement_id}/download |
Giving the users the hability to list all agreements available, query a specific agreement by its ID or even downloading the original file (if exists) and PDF file.
ⓘ Note
Let's build brilliant, automated signing experiences together 🤝
Feel free to contact us if you have any feedback regarding the API.