API docs by Redocly

HeySign API (v1)

Download OpenAPI specification:Download

HeySign provides a complete set of APIs to create, send and sign agreements.

Getting started

To get started with the HeySign API you need a client ID and a client secret. These are available in the HeySign user portal.

Authentication

To request a JWT compatible with the HeySign API, use your client ID and secret. The example below uses HTTPie to make the request.

$ https --form auth.heysign.co/oauth/token client_id=<id> client_secret=<secret> grant_type=client_credentials

Note: the authentication URL is different than the API URL.

The JSON response contains an access_token field which is the JWT you will use. An example response is available below.

{
  "access_token": "...",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Agreements

The Agreement object represents a single agreement between one or more parties (or Signees) in HeySign. A newly created agreement has the status Draft, and while in draft one can create and remove both signees and documents.

To submit an agreement it must have at least one signee and one primary document.

List all agreements

It is fully possible to filter agreements on your attached metadata.

If you attach an object like { "foo": "bar" } to your agreement, you can specify metadata[foo]=bar as a query parameter and only agreements matching that key-value will be returned. More than one metadata key can be specified. All key-values must match.

Authorizations:
JWT bearer
query Parameters
page.offset
integer <int32>
page.limit
integer <int32>
sort.field
string
sort.order
string (Order)
Enum: "Ascending" "Descending"
object

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "type": "string",
  • "page": {
    },
  • "total_pages": 0,
  • "total_items": 0
}

Create an agreement

Use metadata to attach key-value pairs to agreements. The metadata can be used, for example, to set a user id of a user, or any other kind of data. When listing agreements, it is possible to filter on metadata.

The agreement will be created with status Draft.

Authorizations:
JWT bearer
Request Body schema: application/json

The agreement properties

issuer
required
string non-empty
title
string or null
Array of objects or null (AgreementDocumentCreate)

A list of documents to directly attach to this agreement. This can be used if you want to create a complete agreement in one API call instead of attaching documents separately.

Array
file_id
required
string <uuid>
type
required
string (DocumentCreateType)
Enum: "Primary" "Attachment"
object or null
property name*
additional property
string
object (AgreementNotificationOptions)
type
required
string (AgreementNotificationType)
Enum: "None" "Email"
Array of objects or null (AgreementSigneeCreate)

A list of signees to directly attach to this agreement. This can be used if you want to create a complete agreement in one API call instead of attaching signees separately.

Array
email
required
string non-empty
object (AgreementSchedulingOptions)
publish_date
required
string <date-time>

A date and time when the agreement should be published. Make sure that the agreement is submitted before this date, or a validation error will occur.

redirect_url
string or null

Requires a premium subscription.

A URL where the signees are redirected after they have signed the agreement. Can be used to return them to your own site if signing is part of an outer process.

Use {AGREEMENT_ID} and {SIGNEE_ID} to render the corresponding data in the url. E.g http://example.com/return?agreement_id={AGREEMENT_ID}. The fields will be populated by HeySign.

theme_id
string or null <uuid>

Requires a premium subscription

The ID of a theme to use in the signing portal.

Responses

Request samples

Content type
application/json
{
  • "issuer": "string",
  • "title": "string",
  • "documents": [
    ],
  • "metadata": {
    },
  • "notifications": {
    },
  • "signees": [
    ],
  • "scheduling": {
    },
  • "redirect_url": "string",
  • "theme_id": "ef2b46f3-8ebb-437e-a671-272e4990fbc8"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "type": "string"
}

Get an agreement by ID

Authorizations:
JWT bearer
path Parameters
id
required
string <uuid>

ID of the agreement

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "type": "string"
}

Edit an agreement

An agreement can only be updated when it is in the Draft state. To update an agreement after it has been submitted, it needs to be cancelled - which can be done up until the last signee has signed the agreement.

Authorizations:
JWT bearer
path Parameters
id
required
string <uuid>

The agreement ID

Request Body schema: application/json

The updated properties of the agreement

issuer
required
string or null
title
required
string or null

Responses

Request samples

Content type
application/json
{
  • "issuer": "string",
  • "title": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "type": "string"
}

Delete an agreement

You can only delete agreements that are in the Draft state. A deleted agreement will have the Deleted state for 14 days before it is purged from the database.

Authorizations:
JWT bearer
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
No sample

Submit the agreement for signing

The agreement and all signees must be in the Draft state. If this method returns successfully, the agreement and all signees have been transitioned to the Pending state, and all signees will be notified that an agreement needs to be signed.

Submitting an agreement will incur a cost, even if you later cancel or otherwise delete it.

Authorizations:
JWT bearer
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
No sample

Documents

A document is a PDF file that is attached to an agreement and meaning to be signed.

To create a Document, you need a File ID and an Agreement ID.

Creates a document

To create a document, the agreement must be in the Draft state.

Since a document is meant to be signed as part of the agreement, the file must be a PDF file. Trying to create a document from a file that is not a PDF file will produce an error.

Authorizations:
JWT bearer
Request Body schema: application/json
agreement_id
required
string <uuid>
file_id
required
string <uuid>
object or null
property name*
additional property
string
type
required
string (DocumentCreateType)
Enum: "Primary" "Attachment"

Responses

Request samples

Content type
application/json
{
  • "agreement_id": "67dd069b-637c-4b8e-8d92-17a313d06fb8",
  • "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
  • "metadata": {
    },
  • "type": "Primary"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "agreement_id": "67dd069b-637c-4b8e-8d92-17a313d06fb8",
  • "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
  • "created_date": "2019-08-24T14:15:22Z",
  • "metadata": {
    },
  • "type": "Primary"
}

List all documents

Authorizations:
JWT bearer
query Parameters
page.offset
integer <int32>
page.limit
integer <int32>
sort.field
string
sort.order
string (Order)
Enum: "Ascending" "Descending"
agreement_id
string <uuid>
object

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a document by ID

Authorizations:
JWT bearer
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "agreement_id": "67dd069b-637c-4b8e-8d92-17a313d06fb8",
  • "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
  • "created_date": "2019-08-24T14:15:22Z",
  • "metadata": {
    },
  • "type": "Primary"
}

Delete a document

The document can only be deleted if the agreement that it belongs to is in the Draft state.

Authorizations:
JWT bearer
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
No sample

Files

Files are used in various places in HeySign - you can attach them to agreements, use them in email templates as well as in the signing portal.

The default maximum size for each single file is 10MB.

You are able to use a single file in multiple agreements, as Documents.

Upload a file

Use metadata to attach your own data to a file.

The maximum file size is 10MB.

If you have a valid reason for larger files, please reach out to api@heysign.co and we can increase the limit for your tenant.

Authorizations:
JWT bearer
Request Body schema: multipart/form-data
file
required
string <binary>
object
property name*
additional property
string

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_date": "2019-08-24T14:15:22Z",
  • "metadata": {
    },
  • "name": "string",
  • "size": 0,
  • "sha256": "string",
  • "content_type": "string",
  • "url": "http://example.com"
}

List all files

Authorizations:
JWT bearer
query Parameters
page.offset
integer <int32>
page.limit
integer <int32>
sort.field
string
sort.order
string (Order)
Enum: "Ascending" "Descending"
object
query
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "type": "string",
  • "page": {
    },
  • "total_pages": 0,
  • "total_items": 0
}

Get a single file by ID.

Authorizations:
JWT bearer
path Parameters
fileId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "type": "string"
}

Signees

A signee is a participant in the signing process. The signee will be invited to sign the agreement on submission.

List all signees

Authorizations:
JWT bearer
query Parameters
page.offset
integer <int32>
page.limit
integer <int32>
sort.field
string
sort.order
string (Order)
Enum: "Ascending" "Descending"
agreement_id
string <uuid>
object

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "type": "string",
  • "page": {
    },
  • "total_pages": 0,
  • "total_items": 0
}

Create a signee

A signee can only be added to an agreement if the agreement is in the Draft state.

Authorizations:
JWT bearer
Request Body schema: application/json
agreement_id
required
string <uuid>

The agreement to attach this signee to.

object or null

Signee attributes, such as email, personal number, etc. Depending on how your tenant is set up, a signee requires different attributes. In general, set an email and optionally a personal number.

If your tenant is connected to Kivra, the email and personal number will be used to match a user in Kivra.

Setting a personal number will require lock the signing process to that specific person.

email
any
se_personal_number
any
object or null
property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "agreement_id": "67dd069b-637c-4b8e-8d92-17a313d06fb8",
  • "attributes": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "type": "string"
}

Edit a signee

A signee can only be edited if the agreement it belongs to is in the Draft state.

Authorizations:
JWT bearer
path Parameters
id
required
string <uuid>
Request Body schema: application/json
object or null

Updated attributes for the signee.

If you want to remove an attribute, specify it with a null value.

email
any
se_personal_number
any

Responses

Request samples

Content type
application/json
{
  • "attributes": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "type": "string"
}

Get a signee by ID.

Authorizations:
JWT bearer
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "type": "string"
}

Delete a signee

A signee can only be deleted of the agreement it belongs to is in the Draft state.

Authorizations:
JWT bearer
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
No sample

Tenants

A tenant is used to group users and agreements. The tenant endpoints can be used to set up sub-tenants that can be managed from your own tenant, for example to isolate your own customers, business units, etc.

The tenant endpoints in the public API is available in custom price plans only. Reach out to hello@heysign.co to discuss your use case!

Create a tenant

Requires the tenants:create permission.

Authorizations:
JWT bearer
Request Body schema:
name
required
string non-empty
language_code
string or null
time_zone
string or null

Responses

Request samples

Content type
{
  • "name": "string",
  • "language_code": "string",
  • "time_zone": "string"
}

Response samples

Content type
No sample

Themes

Use themes to customize the look and feel of the signing portal. You can set primary and secondary colors as well as an icon and a logo.

/v1/themes

Authorizations:
JWT bearer
Request Body schema:
name
required
string non-empty
icon_file_id
string or null <uuid>
logo_file_id
string or null <uuid>
color_primary_hex
string or null
color_secondary_hex
string or null

Responses

Request samples

Content type
{
  • "name": "string",
  • "icon_file_id": "9a0b4f9e-4a41-4874-a537-9c56cde78be1",
  • "logo_file_id": "8a606be6-cb8e-4c20-bcd3-4ef40c89ea63",
  • "color_primary_hex": "string",
  • "color_secondary_hex": "string"
}

Webhooks

Webhooks provides a powerful way to get notified when events occur, and HeySign follows the Standard Webhooks specification. Callback URLs must be HTTPS which means setting up something like ngrok for local testing.

The order of events is not guaranteed, and it is possible that events may come out of order.

Supported events

  • agreement.completed
  • agreement.created
  • agreement.published
  • agreement.submitted
  • agreement.updated
  • document.created
  • signee.created
  • signee.signsession.created
  • signee.signsession.completed

List all webhooks

Authorizations:
JWT bearer

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "type": "string",
  • "page": {
    },
  • "total_pages": 0,
  • "total_items": 0
}

Create a webhook

The response will contain the webhook secret used for validating payloads. This needs to be stored since it is not possible to retrieve this later.

If you do not specify any events, it will be sent all events.

Authorizations:
JWT bearer
Request Body schema: application/json
url
required
string <uri>

The callback URL.

events
Array of strings or null

The events this webhook should be sent.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "type": "string"
}

Delete a webhook

Authorizations:
JWT bearer
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
No sample