Harbour Developers

# API Guide v1.2

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

{
  "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 Requests error.

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
Create agreement POST /agreements

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 string

Enum:
  • ID
  • TITLE
  • DATE_CREATED
 Ordering of the results ➖ DATE_CREATED
sort_order string

Enum:
  • ASC
  • DESC
 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": [
        {
          "id": "AbCd1234",
          "input_type": "TEXTINPUT",
          "record_label": "Email",
          "place_holder": "Your email...",
          "default_value": "harbour@harbourshare.com",
          "is_required": true,
          "value": "harbour@harbourshare.com",
          "annotations": [
            {
              "id": "annotation-AbCd1234",
              "page": 0,
              "font_size": 9,
              "coordinates": [100, 100, 100, 100]
            }
          ]
        }
      ]
    }
  ],
  "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"
}

# 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": [
    {
      "id": "AbCd1234",
      "input_type": "TEXTINPUT",
      "record_label": "Email",
      "place_holder": "Your email...",
      "default_value": "harbour@harbourshare.com",
      "is_required": true,
      "value": "harbour@harbourshare.com",
      "annotations": [
        {
          "id": "annotation-AbCd1234",
          "page": 0,
          "font_size": 9,
          "coordinates": [100, 100, 100, 100]
        }
      ]
    }
  ]
}

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

Agreement

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": [
    {
      "id": "AbCd1234",
      "input_type": "TEXTINPUT",
      "record_label": "Email",
      "place_holder": "Your email...",
      "default_value": "harbour@harbourshare.com",
      "is_required": true,
      "value": "harbour@harbourshare.com",
      "annotations": [
        {
          "id": "annotation-AbCd1234",
          "page": 0,
          "font_size": 9,
          "coordinates": [100, 100, 100, 100]
        }
      ]
    }
  ]
}

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

Create agreement

This endpoint creates an agreement template from scratch by receiving a PDF file in base64 format and the location where the input and annotations will be placed.

What are the use cases for this?

When there is a need to dynamically create agreements coming from different sources

Endpoint

POST /agreements

Path Parameters

null

Query Parameters

null

Request Body:

Field Type Description
file_upload File Upload Agreement file to be uploaded
agreement_data Agreement Data Agreement data to be inserted

File Upload

Field Type Description Required Default Value
name string Name of the file ✔️ AbCd1234
base64 string Base64 string of the agreement file ✔️ TEXTINPUT

Agreement Data

Field Type Description Required Default Value
title string Title of the agreement ➖ Agreement
subheader string Subheader of the agreement ➖ Please review and complete
document_inputs Document Input Document input fields in the agreement ➖
signer_inputs Signer Input Document input fields in the agreement ➖
is_template boolean Is the agreement a template ➖ True
template_settings Template Settings Template settings

Template Settings

Field Type Description Required Default Value
is_private boolean Is the agreement private ➖ False
group_label string Group which the template will be part of ➖ My agreements
Request Body Example

Example

{
  "file_upload": {
    "name": "Agreement",
    "base64": "...4NgolJUVPRgo="
  },
  "agreement_data": {
    "title": "Agreement",
    "subheader": "Please review and complete",
    "document_inputs": [
      {
        "id": "AbCd1234",
        "input_type": "TEXTINPUT",
        "display_label": "Enter your email",
        "default_value": "harbour@harbourshare.com",
        "is_required": true,
        "place_holder": "Your email...",
        "input_description": "Please enter your valid email address.",
        "internal_label": "Email",
        "date_source": "SIGNDATE",
        "date_timezone": "LOSANGELES",
        "currency_type": "USD",
        "duration_type": "DAYS",
        "value": "harbour@harbourshare.com",
        "annotations": [
          {
            "id": "annotation-AbCd1234",
            "render_page": 0,
            "font_size": 9,
            "coordinates": [100, 100],
            "height": 20,
            "width": 350,
            "render_stages": ["ALL", "AGREELINKSIGN"]
          }
        ]
      }
    ],
    "signer_inputs": [
      {
        "id": "AbCd1234",
        "input_type": "TEXTINPUT",
        "display_label": "Enter your email",
        "default_value": "harbour@harbourshare.com",
        "is_required": true,
        "place_holder": "Your email...",
        "input_description": "Please enter your valid email address.",
        "internal_label": "Email",
        "date_source": "SIGNDATE",
        "date_timezone": "LOSANGELES",
        "currency_type": "USD",
        "duration_type": "DAYS",
        "value": "harbour@harbourshare.com",
        "annotations": [
          {
            "id": "annotation-AbCd1234",
            "render_page": 0,
            "font_size": 9,
            "coordinates": [100, 100],
            "height": 20,
            "width": 350,
            "render_stages": ["ALL", "AGREELINKSIGN"]
          }
        ]
      }
    ],
    "is_template": true,
    "template_settings": {
      "is_private": true,
      "group_label": "My agreements"
    }
  }
}

Response Body

Field Type Description Example
id string Id of the newly created agreement AGREE-AbCd1234...
datetime_created string Date and time the agreement link was created 2022-01-01T23:59:59.999999Z
View Response Example

Example

{
  "id": "AGREE-AbCd1234",
  "datetime_created": "2022-01-01T23:59:59.999999Z"
}

Explore it further 🕵🏼‍♂️

Want to get started creating agreement from scratch?

# 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 link submissions GET /agreement_links/{agreement_link_id}/submissions

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 string

Enum:
  • ID
  • TITLE
  • DATE_CREATED
 Ordering of the results ➖ DATE_CREATED
sort_order string

Enum:
  • ASC
  • DESC
 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",
          "annotations": [
            {
              "id": "annotation-AbCd1234",
              "page": 0,
              "font_size": 9,
              "coordinates": [100, 100, 100, 100]
            }
          ]
        }
      ]
    }
  ],
  "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

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

Agreement Link

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",
      "annotations": [
        {
          "id": "annotation-AbCd1234",
          "page": 0,
          "font_size": 9,
          "coordinates": [100, 100, 100, 100]
        }
      ]
    }
  ]
}

Test it live

This endpoint returns a list of submissions for a specific agreements link.

What can you do with this information?

When querying data from this endpoint you will be able to access every submission for the agreement link.

Endpoint

GET /agreement_links/{agreement_link_id}/submissions

Path Parameters

Field Type Description Example Required
agreement_link_id string Agreement link ID ng3E2dsKK ✔️

Query Parameters null

Example

GET /agreement_links/AbCd1234/submissions

Response Body

Field Type Description Example
submissions array An array of link submissions Link Submission
results_count integer The total amount of results available 200
View Response Example

Example

{
  "submissions": [
    {
      "agreement_download_expires_at": "2022-01-01T23:59:59Z",
      "agreement_download_url": "https://storage.googleapis.com/signed-url",
      "agreement_reference_id": "HBRREF-1234",
      "agreement_reference_url": "https://sandboxdemo.myharbourshare.com/folders",
      "attached_contents": [],
      "datetime_signed": "2022-01-01T23:59:59Z",
      "location_city": "san francisco",
      "location_coordinates": "-10,30",
      "location_country": "US",
      "location_region": "ca",
      "signer_inputs": [],
      "submission_id": "AGREESUBMISSION-1234"
    }
  ],
  "results_count": 200
}

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
  • PENDING
  • COMPLETED
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
  • PASSCODE
  • EMAILS
  • PUBLIC
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",
      "annotations": [
        {
          "id": "annotation-AbCd1234",
          "page": 0,
          "font_size": 9,
          "coordinates": [100, 100, 100, 100]
        }
      ]
    }
  ]
}

# Link Submission Body

Field Type Description Example
agreement_download_expires_at datetime Date time expiration of the signed url 2022-01-01T23:59:59Z
agreement_download_url string Signed URL to download fully signed agreement https://storage.googleapis.com/signed-url
agreement_reference_id string Reference ID for the fully completed document HBRREF-1234
agreement_reference_url string URL to access fully completed document in Harbour https://sandboxdemo.myharbourshare.com/folders
attached_contents array of string List of attach contents to the signed document
datetime_signed datetime Date and time the agreement link was signed 2022-01-01T23:59:59.999999Z
location_city string City where agreement link was signed san francisco
location_coordinates string Coordinates where agreement link was signed -10, 30
location_country string Country where agreement link was signed US
location_region string Region where agreement link was signed ca
signer_inputs array of object List of the signer responses Signer Input
submission_id string Id of the submission User
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",
      "annotations": [
        {
          "id": "annotation-AbCd1234",
          "page": 0,
          "font_size": 9,
          "coordinates": [100, 100, 100, 100]
        }
      ]
    }
  ]
}

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:
  • PASSCODE
  • EMAILS
  • PUBLIC
 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_completion": true,
    "bcc_on_completion": ["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? Google Sheets Demo

# 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 string

Enum:
  • ID
  • TITLE
  • DATE_CREATED
 Ordering of the results ➖ DATE_CREATED
sort_order string

Enum:
  • ASC
  • DESC
 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",
      "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",
          "annotations": [
            {
              "id": "annotation-AbCd1234",
              "page": 0,
              "font_size": 9,
              "coordinates": [100, 100, 100, 100]
            }
          ]
        }
      ],
      "signer_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",
          "annotations": [
            {
              "id": "annotation-AbCd1234",
              "page": 0,
              "font_size": 9,
              "coordinates": [100, 100, 100, 100]
            }
          ]
        }
      ]
    }
  ],
  "results_count": 200,
  "next_request": "https://api.harbourshare.com/v1/items?offset=20?limit=10",
  "previous_request": "https://api.harbourshare.com/v1/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

Item

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",
  "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",
      "annotations": [
        {
          "id": "annotation-AbCd1234",
          "page": 0,
          "font_size": 9,
          "coordinates": [100, 100, 100, 100]
        }
      ]
    }
  ],
  "signer_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",
      "annotations": [
        {
          "id": "annotation-AbCd1234",
          "page": 0,
          "font_size": 9,
          "coordinates": [100, 100, 100, 100]
        }
      ]
    }
  ]
}

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
document_inputs array Document input fields for the completed agreement Document Inputs
signer_inputs array Signer input fields for the completed agreement Signer Inputs
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",
  "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",
      "annotations": [
        {
          "id": "annotation-AbCd1234",
          "page": 0,
          "font_size": 9,
          "coordinates": [100, 100, 100, 100]
        }
      ]
    }
  ],
  "signer_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",
      "annotations": [
        {
          "id": "annotation-AbCd1234",
          "page": 0,
          "font_size": 9,
          "coordinates": [100, 100, 100, 100]
        }
      ]
    }
  ]
}

# 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 string

Enum:
  • ID
  • TITLE
  • DATE_CREATED
 Ordering of the results ➖ DATE_CREATED
sort_order string

Enum:
  • ASC
  • DESC
 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

Folder

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 string

Enum:
  • ID
  • TITLE
  • DATE_CREATED
 Ordering of the results ➖ DATE_CREATED
sort_order string

Enum:
  • ASC
  • DESC
 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 string

Enum:
  • ID
  • TITLE
  • DATE_CREATED
 Ordering of the results ➖ DATE_CREATED
sort_order string

Enum:
  • ASC
  • DESC
 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

Brand

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
email 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
email string Recipient's email janedoe@harbourshare.com
role enum Recipient's role
  • SIGNER
  • REVIEWER
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"
}

Input

# 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 Internal record label of the input Email
place_holder string Place holder text of the input Your email...
default_value string Default value of the input harbour@harbourshare.com
is_required string Is required input true
value string Input response harbour@harbourshare.com
annotations array Document annotation of the input Annotation
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",
  "annotations": [
    {
      "id": "annotation-AbCd1234",
      "page": 0,
      "font_size": 9,
      "coordinates": [100, 100, 100, 100]
    }
  ]
}

Annotation

# Annotation Body

Field Type Description Example
id string Id of the annotation annotation-AbCd1234
page integer Page where annotation is located 0
font_size integer Id of the annotation 9
coordinates array Coordinates where annotation will be placed inside the document [100, 100, 100, 100]
Annotation Example

Example

{
  "id": "annotation-AbCd1234",
  "page": 0,
  "font_size": 9,
  "coordinates": [100, 100, 100, 100]
}

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
notify_on_view boolean Send an email notification to creator on each signer view
notify_on_signature boolean Send an email notification to creator on each signer signature
notify_on_completion boolean Send an email notification to creator on completed final agreement
notify_signer_on_completion boolean Send an email notification to signer on completed final agreement
audit_trail boolean Send audit trail to creator on completed final agreement
signer_audit_trail boolean Send audit trail to signer on completed final agreement
bcc_on_completion array Copy the completed agreement to other people
Notification Settings Example

Example

{
  "notify_on_view": true,
  "notify_on_signature": true,
  "notify_on_completion": true,
  "notify_signer_on_completion": true,
  "audit_trail": true,
  "signer_audit_trail": true,
  "bcc_on_completion": ["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 implementation
  • A minor version release
  • A 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?

Google Sheets Demo

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}

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.