Appearance

API Reference v1.5 ​

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.

Want to get all latest API updates? Try our APIv2 (beta)

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 > 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.
json
{
  "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.

json
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.

ResourceDescription
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 ​

NameEndpoint
List agreementsGET /agreements
Get agreement by IDGET /agreements/{agreement_id}
Download agreementGET /agreements/{agreement_id}/download
Create agreementPOST /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

FieldTypeDescriptionRequiredDefault Value
offsetintegerSkip the records before the offset➖0
limitintegerLimits the amount of results per response➖100
order_bystring

Enum:
  • ID
  • TITLE
  • DATE_CREATED
Ordering of the results➖DATE_CREATED
sort_orderstring

Enum:
  • ASC
  • DESC
Sort order of the results➖DESC
is_templatebool

Enum:
  • True
  • False
Is the agreement a template➖➖

Example

GET /agreements?offset=0&limit=10&order_by=DATE_CREATED&sort_order=DESC

Response Body

FieldTypeDescriptionExample
agreementsarrayAn array of agreementsAgreement
results_countintegerThe total amount of results available200
next_requeststringNext request URL/agreements?offset=20?limit=10
previous_requeststringPrevious request made URL/agreements?offset=10?limit=10
View Response Example

Example

json
{
  "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"
      },
      "document_inputs": [
        {
          "id": "AbCd1234",
          "input_type": "TEXTINPUT",
          "internal_label": "Email",
          "place_holder": "Your email...",
          "default_value": "harbour@harbourshare.com",
          "is_required": true,
          "is_hidden": true
        }
      ],
      "signer_inputs": [
        {
          "id": "AbCd1234",
          "input_type": "TEXTINPUT",
          "internal_label": "Email",
          "place_holder": "Your email...",
          "default_value": "harbour@harbourshare.com",
          "is_required": true,
          "is_hidden": true,
          "url_parameter": "email"
        }
      ],
      "auth_mode": "EMAILS",
      "template_type": "TEMPLATE",
      "create_source": "API",
      "recipients": [
        {
          "name": "John Doe",
          "email": "john.doe@example.com",
          "signing_order": 1,
          "signer_index": 1
        }
      ]
    }
  ],
  "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 ​

FieldTypeDescriptionExample
idstringId of the agreementAGREE-1234
titlestringTitle of the agreementHarbour License Agreement
group_namestringThe template group it belongs toMy agreements
datetime_createdstringDate and time the agreement was created2022-01-01T23:59:59.999999Z
datetime_last_updatedstringDate and time the agreement was last updated2022-01-01T23:59:59.999999Z
created_byobjectUser that created the agreementUser
last_updated_byobjectUser that last updated the agreementUser
document_inputsarrayDocument input fields in the agreementDocument Input
signer_inputsarraySigner input fields in the agreementSigner Input
auth_modestringAuthentication mode of the agreementEMAILS
template_typestringTemplate type of the agreementTEMPLATE
create_sourcestringSource of the agreementAPI
recipientsarrayRecipients of the agreementRecipient
Agreement Example

Example

json
{
  "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"
  },
  "document_inputs": [
    {
      "id": "AbCd1234",
      "input_type": "TEXTINPUT",
      "internal_label": "Email",
      "place_holder": "Your email...",
      "default_value": "harbour@harbourshare.com",
      "is_required": true,
      "is_hidden": true,
      "value": "harbour@harbourshare.com"
    }
  ],
  "signer_inputs": [
    {
      "id": "AbCd1234",
      "input_type": "TEXTINPUT",
      "internal_label": "Email",
      "place_holder": "Your email...",
      "default_value": "harbour@harbourshare.com",
      "is_required": true,
      "is_hidden": true,
      "url_parameter": "email"
    }
  ],
  "auth_mode": "EMAILS",
  "template_type": "TEMPLATE",
  "create_source": "API"
}

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

FieldTypeDescriptionExampleRequired
agreement_idstringAgreement IDAGREE-1234✔️

Query Parameters

null

Response Body

Agreement

View Response Example

Example

json
{
  "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"
  },
  "document_inputs": [
    {
      "id": "AbCd1234",
      "input_type": "TEXTINPUT",
      "internal_label": "Email",
      "place_holder": "Your email...",
      "default_value": "harbour@harbourshare.com",
      "is_required": true,
      "is_hidden": true
    }
  ],
  "signer_inputs": [
    {
      "id": "AbCd1234",
      "input_type": "TEXTINPUT",
      "internal_label": "Email",
      "place_holder": "Your email...",
      "default_value": "harbour@harbourshare.com",
      "is_required": true,
      "is_hidden": true,
      "url_parameter": "email"
    }
  ],
  "auth_mode": "EMAILS",
  "template_type": "TEMPLATE",
  "create_source": "API"
}

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

FieldTypeDescriptionExampleRequired
agreement_idstringAgreement IDAGREE-1234✔️

Query Parameters

null

Response Body

FieldTypeDescriptionExample
original_filestringBase64 of the original agreement file0M8R4KGx...
pdf_filearrayBase64 of the agreement PDF fileJVBERi0x...
View Response Example

Example

json
{
  "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:

FieldTypeDescription
file_uploadFile UploadAgreement file to be uploaded
agreement_dataAgreement DataAgreement data to be inserted

File Upload

FieldTypeDescriptionRequiredDefault Value
namestringName of the file✔️AbCd1234
base64stringBase64 string of the agreement file✔️TEXTINPUT

Agreement Data

FieldTypeDescriptionRequiredDefault Value
titlestringTitle of the agreement➖Agreement
subheaderstringSubheader of the agreement➖Please review and complete
document_inputsDocument InputDocument input fields in the agreement➖
signer_inputsSigner InputDocument input fields in the agreement➖
is_templatebooleanIs the agreement a template➖True
template_settingsTemplate SettingsTemplate settings

Template Settings

FieldTypeDescriptionRequiredDefault Value
is_privatebooleanIs the agreement private➖False
group_labelstringGroup which the template will be part of➖My agreements
Request Body Example

Example

json
{
  "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,
        "is_hidden": 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,
        "is_hidden": true,
        "url_parameter": "email",
        "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

FieldTypeDescriptionExample
idstringId of the newly created agreementAGREE-AbCd1234...
datetime_createdstringDate and time the agreement link was created2022-01-01T23:59:59.999999Z
View Response Example

Example

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

Explore it further 🕵🏼‍♂️

Want to get started creating agreement from scratch?

Methods ​

NameEndpoint
List agreement linksGET /agreement_links
Get agreement link by IDGET /agreement_links/{agreement_link_id}
Download agreement linkGET /agreement_links/{agreement_link_id}/download
Create agreement linkPOST /agreement_links
Delete agreement linkDELETE /agreement_links/{agreement_link_id}
List agreement link submissionsGET /agreement_links/{agreement_link_id}/submissions
Get agreement link submissionGET /agreement_links/{agreement_link_id}/submissions/{submission_id}

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

FieldTypeDescriptionRequiredDefault Value
offsetintegerSkip the records before the offset➖0
limitintegerLimits the amount of results per response➖100
order_bystring

Enum:
  • ID
  • TITLE
  • DATE_CREATED
Ordering of the results➖DATE_CREATED
sort_orderstring

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

FieldTypeDescriptionExample
agreement_linksarrayAn array of agreement linksAgreement Link
results_countintegerThe total amount of results available200
next_requeststringNext request URL/agreement_links?offset=20?limit=10
previous_requeststringPrevious request made URL/agreement_links?offset=10?limit=10
View Response Example

Example

json
{
  "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",
          "signing_order": 1,
          "signer_index": 1,
          "datetime_viewed": "2022-01-01T23:59:59.999999Z",
          "datetime_signed": "2022-01-01T23:59:59.999999Z",
          "inputs": [
            {
              "id": "AbCd1234",
              "input_type": "TEXTINPUT",
              "internal_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",
          "internal_label": "Email",
          "place_holder": "Your email...",
          "default_value": "harbour@harbourshare.com",
          "is_required": true,
          "is_hidden": 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

FieldTypeDescriptionExampleRequired
agreement_link_idstringAgreement link IDAGREE-1234✔️

Query Parameters

null

Agreement Link Body ​

FieldTypeDescriptionExample
idstringId of the agreement linkAbCd1234
request_titlestringRequest title of the agreement link (shown in the signature page)Harbour License Agreement
brandobjectOrganization's brand used for this agreement linkBrand
agreementobjectOriginal agreement where agreement link was generated fromAgreement
statusstringStatus of the agreement link
  • PENDING
  • COMPLETED
datetime_createdstringDate and time the agreement link was created2022-01-01T23:59:59.999999Z
datetime_last_updatedstringDate and time the agreement link was updated for the last time2022-01-01T23:59:59.999999Z
datetime_completedstringDate and time the agreement link was completed for the last time2022-01-01T23:59:59.999999Z
auth_modeenumAuthentication mode of the agreement link
  • PASSCODE
  • EMAILS
  • PUBLIC
is_activebooleanActive status of the agreement linkTrue
link_urlstringAgreement link URLhttps://hrbr.co/AbCd1234
created_byobjectUser that created the agreementUser
recipientsarrayRecipients of the agreement link (signer or reviewers)Recipients
document_inputsarrayDocument inputs inserted when building the agreement linkDocument Input
Agreement Link Example

Example

json
{
  "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",
      "signing_order": 1,
      "signer_index": 1,
      "datetime_viewed": "2022-01-01T23:59:59.999999Z",
      "datetime_signed": "2022-01-01T23:59:59.999999Z",
      "inputs": [
        {
          "id": "AbCd1234",
          "input_type": "TEXTINPUT",
          "internal_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",
      "internal_label": "Email",
      "place_holder": "Your email...",
      "default_value": "harbour@harbourshare.com",
      "is_required": true,
      "is_hidden": true,
      "value": "harbour@harbourshare.com",
      "annotations": [
        {
          "id": "annotation-AbCd1234",
          "page": 0,
          "font_size": 9,
          "coordinates": [100, 100, 100, 100]
        }
      ]
    }
  ]
}

Test it live

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

FieldTypeDescriptionRequired
agreement_idstringUnique identifier of an agreement template.✔️

Example

POST /agreement_links?agreement_id=AGREE-AbCd1234

Request Body

FieldTypeDescriptionRequiredDefault Value
brand_idstringBrand id to be used in the agreement link➖Organization's banner and logo (from Harbour WebApp)
link_namestringLink name for internal control➖{agreement_title} - {current_date}
request_titlestringTitle of the agreement link (shown in the signature page)➖Agreement
personal_messagestringPersonal message for recipient (shown in the signature page)➖
custom_tagsarrayCustom tags to identify your agreement link inside Harbour➖
destination_folder_idstringFolder id where the completed agreement will be saved✔️
attached_contentarrayArray of base64 content to be attached within the agreement link➖
document_inputsarray of

Document Input		Value for the document inputs*
auth_modestring

Enum:
  • PASSCODE
  • EMAILS
  • PUBLIC
Authentication mode of the agreement link➖PUBLIC
passcodestringPasscode value (when auth_mode is set to PASSCODE)**
recipientsarray of

Recipient		Recipients of the agreement link (signer or reviewers)***
enforce_signing_orderbooleanEnforce signing order of the signers (when auth_mode is set to EMAILS)➖False
automated_remindersbooleanSend automated reminders (when auth_mode is set to EMAILS)➖
creator_emailstringEmail that will receive all the configured notifications****
notification_settingsobject Notification SettingsSettings for agreement link notifications➖
is_activebooleanActive 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

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

FieldTypeDescriptionExample
idstringId of the agreement linkAbCd1234
datetime_createdstringDate and time the agreement link was created2022-01-01T23:59:59.999999Z
link_urlstringAgreement link URLhttps://hrbr.co/AbCd1234
qr_code_imagestringBase64 of the QR code link image...4NgolJUVPRgo=
View Response Example

Example

json
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

This endpoint deletes an existing agreement link.

Endpoint

DELETE /agreement_links/{agreement_link_id}

Path Parameters

FieldTypeDescriptionRequired
agreement_link_idstringUnique identifier of an agreement link✔️

Query Parametersnull

Response Body

FieldTypeDescriptionExample
agreement_link_idstringThe ID of the deleted agreement linkAGREELINK-123456
event_datetimestringDate and time when the agreement link was deleted2024-03-20 15:30:45

Example Response

json
{
  "agreement_link_id": "AGREELINK-123456",
  "event_datetime": "2024-03-20 15:30:45"
}

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

FieldTypeDescriptionExampleRequired
agreement_link_idstringAgreement link IDng3E2dsKK✔️

Query Parametersnull

Example

GET /agreement_links/AbCd1234/submissions

Response Body

FieldTypeDescriptionExample
submissionsarrayAn array of link submissionsLink Submission
results_countintegerThe total amount of results available200
View Response Example

Example

json
{
  "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

This endpoint returns a specific submission for an agreement link.

What can you do with this information?

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

Endpoint

GET /agreement_links/{agreement_link_id}/submissions/{submission_id}

Path Parameters

FieldTypeDescriptionExampleRequired
agreement_link_idstringAgreement link IDng3E2dsKK✔️
submission_idstringSubmission IDAGREESUBMISSION-123✔️

Query Parametersnull

Example

GET /agreement_links/AbCd1234/submissions/AGREESUBMISSION-123

Link Submission Body ​

FieldTypeDescriptionExample
agreement_download_expires_atdatetimeDate time expiration of the signed url2022-01-01T23:59:59Z
agreement_download_urlstringSigned URL to download fully signed agreementhttps://storage.googleapis.com/signed-url
audit_trail_download_urlstringSigned URL to download base64-encoded audit trail pdfhttps://storage.googleapis.com/signed-url
agreement_reference_idstringReference ID for the fully completed documentHBRREF-1234
agreement_reference_urlstringURL to access fully completed document in Harbourhttps://sandboxdemo.myharbourshare.com/folders
agreement_titlestringTitle of the agreement documenttestpdf.pdf
attached_contentsarray of stringList of attach contents to the signed document[]
datetime_signeddatetimeDate and time the agreement link was signed2022-01-01T23:59:59.999999Z
document_inputsarray of objectList of document inputsDocument Input
signer_emailstringEmail of the signeruser@example.com
signer_inputsarray of objectList of the signer responsesSigner Input
submission_idstringId of the submissionAGREESUBMISSION-123
Agreement Link Submission Example

Example

json
{
  "agreement_download_expires_at": "2022-01-01T23:59:59Z",
  "agreement_download_url": "https://storage.googleapis.com/signed-url",
  "audit_trail_download_url": "https://storage.googleapis.com/signed-url",
  "agreement_reference_id": "HBRREF-1234",
  "agreement_reference_url": "https://sandboxdemo.myharbourshare.com/folders",
  "agreement_title": "testpdf.pdf",
  "attached_contents": [],
  "datetime_signed": "2022-01-01T23:59:59.999999Z",
  "document_inputs": [],
  "signer_email": "user@example.com",
  "signer_inputs": [
    {
      "display_label": "Have you read and do you accept the terms of the document?",
      "field_type": "YESNOINPUT",
      "id": "agreementinput-readagreedocumentyesno-1234",
      "internal_label": "Read document and agreed to terms",
      "value": "YES"
    },
    {
      "field_type": "CHECKBOX",
      "id": "agreementinput-1234",
      "internal_label": "E-sign consent",
      "value": "YES"
    }
  ],
  "submission_id": "AGREESUBMISSION-123"
}

Items ​

Methods ​

NameEndpoint
List itemsGET /items
Get item by IDGET /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

FieldTypeDescriptionRequiredDefault Value
offsetintegerSkip the records before the offset➖0
limitintegerLimits the amount of results per response➖100
order_bystring

Enum:
  • ID
  • TITLE
  • DATE_CREATED
Ordering of the results➖DATE_CREATED
sort_orderstring

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

FieldTypeDescriptionExample
itemsarrayAn array of itemsItem
results_countintegerThe total amount of results available200
next_requeststringNext request URL/items?offset=20?limit=10
previous_requeststringPrevious request made URL/items?offset=10?limit=10
View Response Example

Example

json
{
  "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",
          "internal_label": "Email",
          "place_holder": "Your email...",
          "default_value": "harbour@harbourshare.com",
          "is_required": true,
          "is_hidden": 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",
          "internal_label": "Email",
          "place_holder": "Your email...",
          "default_value": "harbour@harbourshare.com",
          "is_required": true,
          "is_hidden": true,
          "url_parameter": "email",
          "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

FieldTypeDescriptionExampleRequired
item_idstringItem IDPr6GqXoA✔️

Query Parameters

null

Response Body

Item

View Response Example

Example

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

Test it live

Item Body ​

FieldTypeDescriptionExample
idstringId of the itemAbCd1234
namestringName of the itemHappy Puppy
datetime_createdstringDate and time the item was created2022-01-01T23:59:59.999999Z
vision_tagsstringVision AI auto generated tags from the item['Tag1', 'Tag2', 'Tag3']
web_matchesstringWeb matches from the item appears in the internet['Match1, 'Match2', 'Match3']
preview_imgstringBase64 preview image of the item...4NgolJUVPRgo=
media_categorystringMedia category of the itemIMAGE
file_extensionstringFile extension of the itemjpg
size_bytesintegerSize of the item in bytes1290984
width_pxintegerWidth of the item in px500
height_pxintegerHeight of the item in px500
duration_secondsnumberDuration of the item in seconds2.1
agreement_linkstringAgreement link more info url from where item was attached tohttps://api.harbourshare.com/v1/agreement_links/AbCd1234
folderstringFolder more info url from where item was attached tohttps://api.harbourshare.com/v1/folders/AbCd1234
document_inputsarrayDocument input fields for the completed agreementDocument Inputs
signer_inputsarraySigner input fields for the completed agreementSigner Inputs
Item Example

Example

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

Folders ​

Methods ​

NameEndpoint
List foldersGET /folders
Get folder by IDGET /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

FieldTypeDescriptionRequiredDefault Value
offsetintegerSkip the records before the offset➖0
limitintegerLimits the amount of results per response➖100
order_bystring

Enum:
  • ID
  • TITLE
  • DATE_CREATED
Ordering of the results➖DATE_CREATED
sort_orderstring

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

FieldTypeDescriptionExample
foldersarrayAn array of foldersFolder
results_countintegerThe total amount of results available200
next_requeststringNext request URL/folders?offset=20?limit=10
previous_requeststringPrevious request made URL/folders?offset=10?limit=10
View Response Example

Example

json
{
  "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

FieldTypeDescriptionExampleRequired
folder_idstringFolder Idfolder-AbCd✔️

Query Parameters

null

Response Body

Folder

View Response Example

Example

json
{
  "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 ​

FieldTypeDescriptionExample
idstringId of the folderAbCd1234
namestringName of the folderMy agreements
datetime_createdstringDate and time the folder was created2022-01-01T23:59:59.999999Z
created_byobjectUser that created the the folderUser
viewersarrayPeople that have view access to the folder["viewer1@harbourshare.com", "viewer2@harbourshare.com", "viewer3@harbourshare.com"]
collaboratorsarrayPeople that have edit access to the folder ["colab1@harbourshare.com", "colab2@harbourshare.com", "colab3@harbourshare.com"]
location_urlstringLocation URL of the folderhttps://harbour.myharbourshare.com/library#folder-AbCd1234
Folder Example

Example

json
{
  "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 ​

NameEndpoint
List organizationsGET /organizations
List brandsGET /organizations/brands
Get brand by IDGET /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

FieldTypeDescriptionRequiredDefault Value
offsetintegerSkip the records before the offset➖0
limitintegerLimits the amount of results per response➖100
order_bystring

Enum:
  • ID
  • TITLE
  • DATE_CREATED
Ordering of the results➖DATE_CREATED
sort_orderstring

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

FieldTypeDescriptionExample
organizationsarrayAn array of organizationsOrganization
results_countintegerThe total amount of results available200
next_requeststringNext request URL/organizations?offset=20?limit=10
previous_requeststringPrevious request made URL/organizations?offset=10?limit=10
View Response Example

Example

json
{
  "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 ​

FieldTypeDescriptionExample
idstringId of the organizationAbCd1234
namestringName of the organizationHarbour
subdomainstringOrganization's subdomainharbour
websitestringOrganization's websitehttps://harbourshare.com
descriptionstringOrganization's descriptionSend and sign in seconds
brandsarrayBrands endpoint URL arrayhttps://api.harbourshare.com/v1/organizations/brands/BRAND-AbCd
Organization Example

Example

json
{
  "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

FieldTypeDescriptionRequiredDefault Value
offsetintegerSkip the records before the offset➖0
limitintegerLimits the amount of results per response➖100
order_bystring

Enum:
  • ID
  • TITLE
  • DATE_CREATED
Ordering of the results➖DATE_CREATED
sort_orderstring

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

FieldTypeDescriptionExample
brandsarrayAn array of brandsBrand
results_countintegerThe total amount of results available200
next_requeststringNext request URL/organizations/brands?offset=20?limit=10
previous_requeststringPrevious request made URL/organizations/brands?offset=10?limit=10
View Response Example

Example

json
{
  "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

FieldTypeDescriptionExampleRequired
brand_idstringBrand IdBRAND-AbCd✔️

Query Parameters

null

Response Body

Brand

View Response Example

Example

json
{
  "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 ​

FieldTypeDescriptionExample
idstringId of the brandAbCd1234
namestringName of the brandHarbour
groupstringGroup brand belongs toDefault
datetime_createdstringDate and time the brand was created2022-01-01T23:59:59.999999Z
created_byobjectUser who created the brandUser
datetime_last_updatedstringDate and time the brand was last updated2022-01-01T23:59:59.999999Z
last_updated_byobjectUser who last updated the brandUser
color_themestringColor theme used by the brandBLUE-DARK
logo_imgstringBase64 of the logo image...4NgolJUVPRgo=
background_imgstringBase64 of the backgroung image...4NgolJUVPRgo=
Brand Example

Example

json
{
  "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 ​

FieldTypeDescriptionExample
idstringId of the userAbCd1234
emailstringEmail of the userlucius@harbourshare.com
User Example

Example

json
{
  "id": "AbCd1234",
  "email": "harbour@harbourshare.com"
}

Recipients

Recipient Body ​

FieldTypeDescriptionExample
namestringRecipient's full nameJane Doe
emailstringRecipient's emailjanedoe@harbourshare.com
signing_orderintegerRecipient signing order (if exists)1
signer_indexintegerRecipient signer index (if exists)1
datetime_viewedstringDate and time the agreement was viewed by the recipient2022-01-01T23:59:59.999999Z
datetime_signedstringDate and time the agreement was completed by the recipient2022-01-01T23:59:59.999999Z
inputsarraySigner inputs for the agreementFieldInputs
itemsarrayItems attached to the agreement linkRecipientItem
                                 |
Recipient Example

Example

json
{
  "name": "Jane Doe",
  "email": "janedoe@harbourshare.com",
  "signing_order": 1,
  "signer_index": 1,
  "datetime_viewed": "2022-01-01T23:59:59.999999Z",
  "datetime_signed": "2022-01-01T23:59:59.999999Z",
  "inputs": [
    {
      "id": "AbCd1234",
      "input_type": "TEXTINPUT",
      "internal_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 ​

FieldTypeDescriptionExample
idstringId of the itemAbCd1234
idstringMore info about the itemhttps://api.harbourshare.com/items/AbCd1234
Recipient Example

Example

json
{
  "id": "AbCd1234",
  "more_info": "https://api.harbourshare.com/items/AbCd1234"
}

Input

Input Body ​

FieldTypeDescriptionExample
idstringId of the fieldAbCd1234
input_typestringType of the field inputTEXTINPUT
internal_labelstringInternal record label of the inputEmail
place_holderstringPlace holder text of the inputYour email...
default_valuestringDefault value of the inputharbour@harbourshare.com
is_requiredstringIs required inputtrue
valuestringInput responseharbour@harbourshare.com
annotationsarrayDocument annotation of the inputAnnotation
is_hiddenbooleanIs hidden inputtrue
url_parameterstringURL parameter of the inputemail
Input Example

Example

json
{
  "id": "AbCd1234",
  "input_type": "TEXTINPUT",
  "internal_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]
    }
  ],
  "is_hidden": true,
  "url_parameter": "email"
}

Annotation

Annotation Body ​

FieldTypeDescriptionExample
idstringId of the annotationannotation-AbCd1234
pageintegerPage where annotation is located0
font_sizeintegerId of the annotation9
coordinatesarrayCoordinates where annotation will be placed inside the document[100, 100, 100, 100]
Annotation Example

Example

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

Agreement Link Agreement

Agreement Link Agreement Body ​

FieldTypeDescriptionExample
idstringId of the agreementAbCd1234
more_infostringMore info about the agreementhttps://api.harbourshare.com/agreements/AbCd1234
Agreement Link Agreement Example

Example

json
{
  "id": "AbCd1234",
  "more_info": "https://api.harbourshare.com/agreements/AbCd1234"
}

Agreement Agreement Link

Agreement Agreement Link Body ​

FieldTypeDescriptionExample
idstringId of the agreement linkAbCd1234
is_activebooleanActive status of the agreement linktrue
statusstringCompletition status of the agreement linkPENDING
link_urlstringAgreement link URLhttps://hrbr.co/AbCd1234
more_infostringMore info about the agreement linkhttps://api.harbourshare.com/agreement_links/AbCd1234
Agreement Agreement Link Example

Example

json
{
  "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 ​

FieldTypeDescriptionExample
idstringId of the agreement linkAbCd1234
more_infostringMore info about the agreement linkhttps://api.harbourshare.com/agreement_links/AbCd1234
Item Agreement Link Example

Example

json
{
  "id": "AbCd1234",
  "more_info": "https://api.harbourshare.com/agreement_links/AbCd1234"
}

Agreement Link Download Item

Agreement Link Download Item Body ​

FieldTypeDescriptionExample
idstringId of the itemAbCd1234
download_urlstringA signed URL from where the item can be downloadedhttps://storage.googleapis.com/...
expires_atstringExpiration datetime for the signed URL2022-01-01T23:59:59.999999Z
more_infostringMore info about the itemhttps://api.harbourshare.com/items/AbCd1234
Agreement Link Download Item Example

Example

json
{
  "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 ​

FieldTypeDescription
notify_on_viewbooleanSend an email notification to creator on each signer view
notify_on_signaturebooleanSend an email notification to creator on each signer signature
notify_on_completionbooleanSend an email notification to creator on completed final agreement
notify_signer_on_completionbooleanSend an email notification to signer on completed final agreement
audit_trailbooleanSend audit trail to creator on completed final agreement
signer_audit_trailbooleanSend audit trail to signer on completed final agreement
bcc_on_completionarrayCopy the completed agreement to other people
Notification Settings Example

Example

json
{
  "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 CodeDescription
400 Bad RequestMake sure your request is formatted correctly.
401 UnauthorizedMake sure you've entered your API key correctly.
404 Not FoundMake sure you've entered parameters and/or data payload correctly.
405 Method Not AllowedMethod not allowed by the API.
429 Too Many RequestsThe rate limit has been reached. Please try again later.
500 Internal Server ErrorThe 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

bash
curl -X GET 'https://api.harbourshare.com/v1/agreements' \
-H 'X-API-KEY: {your_api_key}'

Checking response

json
{
  "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

bash
curl -X GET 'https://api.harbourshare.com/v1/agreements' \
-H 'X-API-KEY: {your_api_key}'

Checking response

json
{
  "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

bash
curl -X GET 'https://api.harbourshare.com/v1/agreement_links' \
-H 'X-API-KEY: {your_api_key}'

Checking response

json
{
  "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

bash
curl -X GET 'https://api.harbourshare.com/v1/agreements' \
-H 'X-API-KEY: {your_api_key}'

Checking response

json
{
  "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

bash
curl -X GET 'https://api.harbourshare.com/v1/items' \
-H 'X-API-KEY: {your_api_key}'

Checking response

json
{
  "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

bash
curl -X GET 'https://api.harbourshare.com/v1/folders' \
-H 'X-API-KEY: {your_api_key}'

Checking response

json
{
  "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

bash
curl -X GET 'https://api.harbourshare.com/v1/organizations/brands' \
-H 'X-API-KEY: {your_api_key}'

Checking response

json
{
  "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 🔗

NameEndpoint
Create agreement linkPOST /agreement_links

Folders methods 📂

NameEndpoint
List foldersGET /folders
Get folder by IDGET /folders/{folder_id}

Organizations methods 🏢

NameEndpoint
List organizationsGET /organizations
List brandsGET /organizations/brands
Get brand by IDGET /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 🔗

NameEndpoint
List agreement linksGET /agreement_links
Get agreement link by IDGET /agreement_links/{agreement_link_id}

Items methods 📹

NameEndpoint
List itemsGET /items
Get item by IDGET /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:

NameEndpoint
List agreementsGET /agreements
Get agreement by IDGET /agreements/{agreement_id}
Download agreementGET /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.

© 2025 Harbour Enterprises, Inc. 💙💛