NAV

Introduction

Welcome to the Avvoka API V1 documentation.

Our flexible API allows clients to integrate their own systems with the Avvoka platform to allow them to manage the creation, negotiation and e-signature of documents as well as the creation and management of users.

Authentication

Curl authenticated request example

curl --request GET \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/organisation"

API requests must be authenticated by including your API Token as an Authorization HTTP request header:

Authorization: Bearer $TOKEN Where $TOKEN is your API token.

You can create an API Token from
Support > Organisations > *Your Organisation* > Third party integrations > API tokens

Pagination

Example of pagination metadata

"meta": {
  "pagination": {
    "total_items": 100,
    "items_per_page": 10,
    "total_pages": 10,
    "current_page": 2,
    "links": {
      "previous": "https://<your-instance-domain>/api/v1/templates?page=1&per_page=10",
      "current": "https://<your-instance-domain>/api/v1/templates?page=2&per_page=10",
      "next": "https://<your-instance-domain>/api/v1/templates?page=3&per_page=10"
    }
  }
}

API Endpoints that return a list of objects may include a meta object as part of the response body, this object contains the pagination details of the list. By default all list results are paginated in sets of 50 objects per page but can accept between 1 and 250 objects per page by providing the per_page query parameter. A specific page can be accessed by passing the page number in the page query parameter.

Example:

GET /api/v1/documents?per_page=10&page=2

These are the available attributes inside a meta pagination object.

Attribute Description
total_items The total count of available records on the endpoint
items_per_page The amount of available records on each page
total_pages The amount of total pages
current_page The current page of the returned set of records
links An object with links to navigate through the current,previous and next pages when available.

Filters and sorting

API Endpoints that return a list of objects, for example api/v1/templates, can accept query parameters to filter and sort records based on one or more attributes.

Let's say we want to list all Templates that belong to a specific Profile and sort the results by name in ascending order. Our request path would look like this:

GET /api/v1/templates?profile_id=123sort_by=name&sort_direction=asc

The details of all the available filters and sorting parameters are listed under the Query parameters section of each endpoint.

Errors

Example error response body

{
  "error": {
    "code": "resource_not_saved_error",
    "message": "the resource could not be saved",
    "detail": {
      "user_id": [
        "is invalid"
      ]
    }
  }
}

Avvoka's API specifies several errors that are returned inside an error object in the response body. All errors have a code and message. A detail attribute may also be included to explain the specific reason of the error.

List of Error codes

Code Status Description
bad_request 400 The request body is malformed or is not valid
cannot_modify_document 422 The target document has been finalised and cannot be modified
internal_server_error 500 An unexpected error happened on our side. Our technical team is immediatly notified when this type of error happens notified
invalid_api_token 401 The provided authentication API token header is not valid or it is missing
invalid_document_export 400 The document could not be exported because of missing or wrong parameters. This error includes a detail attribute with information about which specific parameters prevented the document from being exported
resource_not_found 404 The target resource does not exist or the provided resource ID is invalid
resource_not_saved 422 The resource could not be saved because of missing or wrong parameters. This error includes a detail attribute with information about which specific parameters prevented the resource from being saved
unauthorized_endpoint 403 The provided API token is read-only and cannot access this endpoint

Changelog

2024-07-17

2024-06-13

2023-09-08

2023-08-04

2023-05-26

2023-02-23

2023-01-09

2022-12-15

2022-11-25

2022-10-26

2022-10-12

2022-10-07

2022-08-30

2022-07-25

2022-07-19

2022-06-06

2022-06-02

2022-03-31

Added Forms and Form Responses.

2022-02-16

2021-10-12

Added the hint attribute to the Entry definition object.

2021-10-11

Added new filters for listing Templates.

2021-10-04

Updated the Create a User endpoint: new users are not added to a default profile automatically.

2021-09-01

Added Update a Document endpoint.

2021-07-26

Added Webhook Payloads endpoints.

2021-07-07

Initial release.

Documents

The Document object

The Document object represents a Document in your Organisation.

Attribute Type Description
id Number The ID of the document
name String The name of the document
template_id Number The ID of the Template (due to the backward compatibility, it is now the Template Version ID, that is returned by Templates APIv1) that was used to create the document.
user_id Number The ID of the User who owns the document
profile_id Number The ID of the Profile to which the Document belongs
parties Document Party Array The parties of the document
participants Participant Array The participants of the document
entries Object An entries object where each key is an entry definition attribute name and each value is the answer provided for that particular attribute in the Document (Explanatory texts beginning with explanatory_ are included as well)
operations Object An operations object where each key is an operation name and each value is the computed value
activity_log Array Log of all activities on the document (each activity is an object containing message and at keys)
links Object The links associated with the Document on the Avvoka Platform
processing_entries Boolean Indicates if there are any unprocessed updates of entries
created_at String ISO8601 formatted date and time indicating when the Document was created
updated_at String ISO8601 formatted date and time indicating when the Document was updated for the last time
signed_at String ISO8601 formatted date and time indicating when the Document was signed

The Document Party object

The Document Party object represents a party within a Document.

Attribute Type Description
id String The ID of the Party
name String The name of the Party
roles Document Role Array The roles of the Party

The Document Role object

The Document Role object represents a party within a Document party.

Attribute Type Description
id String The ID of the Role
name String The name of the Role
default_sign_rights String The sign rights that will be assigned by default to each participant with this Role. Possible values are "sign", "sign_and_witness" and "no_sign"
default_invite_rights String The invite rights that will be assigned by default to each participant with this Role. Possible values are "document_admin", "party_admin" and "view_only"
default_edit_rights String The edit rights that will be assigned by default to each participant with this Role. Possible values are "edit", "questionnaire", "comment" and "view_only"
default_approve_rights String The approve rights that will be assigned by default to each participant with this Role. Possible values are "approve" and "no_approve"

The Participant object

The Participant object represents a Participant (User) in a Document.

Attribute Type Description
id Number The ID of the Participant
document_id Number The ID of the Document to which the Participant belongs
user_id String The ID of the User associated with the Participant
party_id String The ID of the Document Party to which the Participant belongs
role_id String The ID of the Document Party Role to which the Participant belongs
email String The email of the User associated with the Participant
display_name String The display name of the Participant
sign_rights String The sign rights of the Participant. Possible values are "sign", "sign_and_witness" and no_sign
invite_rights String The invite rights of the Participant. Possible values are "document_admin", "party_admin" and "view_only"
edit_rights String The edit rights of the Participant. Possible values are "edit", "questionnaire", "comment" and "view_only"
approve_rights String The approve rights of the Participant. Possible values are "approve" and "no_approve"

List all Documents

Curl request example

curl --request GET \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/documents"

Response body

{
  "documents": [
    {
      "id": 43881,
      "name": "Employment agreement",
      "template_id": 22567,
      "user_id": 4679,
      "profile_id": 4121,
      "status": "created",
      "parties": [
        {
          "id": "Company",
          "name": "Company",
          "roles": [
            {
              "id": "Role",
              "name": "Role",
              "author": true,
              "default_sign_rights": "no_sign",
              "default_edit_rights": "edit",
              "default_invite_rights": "document_admin",
              "default_approve_rights": "approve"
            }
          ]
        }
      ],
      "participants": [
        {
          "id": 54032,
          "document_id": 43881,
          "user_id": 4721,
          "party_id": "Company",
          "role_id": "Role",
          "email": "hr@example.com",
          "display_name": "John Doe",
          "sign_rights": "no_sign",
          "edit_rights": "edit",
          "invite_rights": "document_admin",
          "approve_rights": "approve"
        }
      ],
      "links": {
        "avvoka_document_url": "https://<your-instance-domain>/documents/43881/continue"
      },
      "processing_entries": false,
      "created_at": "2021-07-05T15:50:08Z",
      "updated_at": "2021-07-05T15:50:39Z",
      "signed_at": null
    }
  ],
  "meta": {
    "pagination": {
      "total_items": 1,
      "items_per_page": 50,
      "total_pages": 1,
      "current_page": 1,
      "links": {
        "current": "https://<your-instance-domain>/api/v1/documents?page=1&per_page=50"
      }
    }
  }
}

Retrieves all Documents in your organisation. Please note that the entries attribute of each Document is not included in the response of this endpoint, entries are only included when retrieving a specific Document.

HTTP Request

GET /api/v1/documents

Query Parameteres

Parameter Description
template_id Filter Documents by template_id
profile_id Filter Documents by profile_id
user_id Filter Documents by user_id
status Filter results status. Accepted values are "created", "unlocked", "locked", "deleted", "pending_external_signaure", "completed", "partially_signed", "signed" and "ready_to_sign"
exclude_deleted When set to "true", deleted Documents will be excluded from the list
sort_by Sort Templates by a specific attribute. Accepted values are "id", "name" and "updated_at". Defaults to "id".
sort_direction Specifies the order applied to the sorted Templates. Accepted values are "asc" and "desc". Defaults to "desc".

Retrieve a Document

Curl request example

curl --request GET \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/documents/43881"

Response body

{
  "document": {
    "id": 43881,
    "name": "Employment agreement",
    "template_id": 22567,
    "user_id": 4679,
    "profile_id": 4121,
    "status": "created",
    "parties": [
      {
        "id": "Company",
        "name": "Company",
        "roles": [
          {
            "id": "Role",
            "name": "Role",
            "author": true,
            "default_sign_rights": "no_sign",
            "default_edit_rights": "edit",
            "default_invite_rights": "document_admin",
            "default_approve_rights": "approve"
          }
        ]
      }
    ],
    "participants": [
      {
        "id": 54032,
        "document_id": 43881,
        "user_id": 4721,
        "party_id": "Company",
        "role_id": "Role",
        "email": "hr@example.com",
        "display_name": "hr@example.com",
        "sign_rights": "no_sign",
        "edit_rights": "edit",
        "invite_rights": "document_admin",
        "approve_rights": "approve"
      }
    ],
    "entries": {
      "employee_name": "Bobby Tables"
    },
    "activity_log": [
      {
        "message": "Created by <b>Hey Bye</b>.",
        "at": "2021-05-02T10:33:14Z"
      },
      {
        "message": "<b>Hey Bye</b> assigned as author.",
        "at": "2021-05-02T10:33:14Z"
      }
    ],
    "links": {
      "avvoka_document_url": "https://<your-instance-domain>/documents/43881/continue"
    },
    "created_at": "2021-07-05T15:50:08Z",
    "updated_at": "2021-07-05T15:50:39Z",
    "signed_at": null
  }
}

Retrieves an existing Document in your Organisation.

HTTP Request

GET /api/v1/documents/${document_id}

Create a Document

Curl example

curl --request POST \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/documents"

Request body

{
  "document": {
    "template_id": 22567,
    "profile_id": 4121,
    "user_id": 4679,
    "name": "Employment offer for Bobby Tables",
    "accept_entries_changes": false,
    "participants": [
      {
        "party_id": "Company",
        "role_id": "Recruiter",
        "display_name": "Jane Doe",
        "email": "recruiter@example.com"
      }
    ],
    "entries": {
      "candidate_name": "Bobby Tables"
    }
  }
}

Response body

{
  "document": {
    "id": 43861,
    "name": "Employment offer",
    "template_id": 22567,
    "user_id": 4679,
    "profile_id": 4122,
    "status": "created",
    "parties": [
      {
        "id": "Company",
        "name": "Company",
        "roles": [
          {
            "id": "Recruiter",
            "name": "Recruiter",
            "author": true,
            "default_sign_rights": "sign",
            "default_edit_rights": "edit",
            "default_invite_rights": "document_admin",
            "default_approve_rights": "approve"
          }
        ]
      }
    ],
    "participants": [
      {
        "id": 54012,
        "party_id": "Company",
        "role_id": "Recruiter",
        "email": "recruiter@example.com",
        "display_name": "Hey Bye",
        "sign_rights": "sign",
        "edit_rights": "edit",
        "invite_rights": "document_admin",
        "approve_rights": "approve"
      }
    ],
    "entries": {
      "employee_name": "Bobby Tables"
    },
    "activity_log": [
      {
        "message": "Created by <b>Hey Bye</b>.",
        "at": "2021-05-02T10:33:14Z"
      },
      {
        "message": "<b>Hey Bye</b> assigned as author.",
        "at": "2021-05-02T10:33:14Z"
      }
    ],
    "processing_entries": true,
    "created_at": "2021-05-02T10:32:54Z",
    "updated_at": "2021-05-02T10:33:14Z",
    "signed_at": null
  }
}

Creates a new Document in your Organisation.

HTTP Request

POST /api/v1/documents

Request body parameters

Attribute Type Description
template_id (required) Number The ID of the associated Template (due to the backward compatibility, it is now the Template Version ID, that is returned by Templates APIv1) that is used to create the Document
profile_id (required) Number The ID of Profile to which the Document belongs
user_id (required) Number The ID of the owner user of the Document
name String The title of the document. It defaults to the name of the associated Template if the attribute is not provided
participants (required) Participant Array The Participants of the document. At least one Participant must be provided.
accept_entries_changes Boolean Default false. Mark any entries (and text) changes as accepted.
accept_questionnaire Boolean Default false. Mark the author's questionnaire as done.
entries Object An object where each key must be a valid attribute name from an Entry Definition in the associated Template and each value is the provided answer for that Entry. Example: { "employee_name": "Bobby Tables" }
notifications Object An object that allows you to disable certain email notifications. Accepted keys are party (Added to party) and user (Account created) where omitted keys have default value of true.

Example: { "party": false } prevents Added to party email from being sent.

These are the accepted parameters for each Participant object

Attribute Type Description
party_id (required) String The ID of the Template Party the Participant belongs to. You can get the IDs of the available Parties by retrieving the parent Template and looking at the parties attribute
role_id (required) String The ID of the Template Role the Participant belongs to. You can get the IDs of the available Roles by [retrieving the parent Template] and looking at the roles attribute on each Party(#retrieve-a-template)
email (required) String The email of the Participant
display_name String The full name of the Participant that will be displayed in the Document parties section
sign_rights String The sign rights of the Participant. Possible values are "sign", "sign_and_witness" and no_sign. It defaults to the default_sign_rights of the Template Role
invite_rights String The invite rights of the Participant. Possible values are "document_admin", "party_admin" and "view_only". It defaults to the default_invite_rights of the Template Role
edit_rights String The edit rights of the Participant. Possible values are "edit", "questionnaire", "comment" and "view_only". It defaults to the default_edit_rights of the Template Role
approve_rights String The approve rights of the Participant. Possible values are "approve" and "no_approve". It defaults to the default_approve_rights of the Template Role

Update a Document

Curl example

curl --request PUT \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/documents/43861"

Request body

{
  "document": {
    "name": "I decided to change the name",
    "entries": {
      "candidate_name": "Louis"
    },
    "participants": [
      {
        "id": 54012,
        "party_id": "Company",
        "role_id": "Recruiter",
        "email": "recruiter@example.com",
        "display_name": "Hey Bye",
        "sign_rights": "sign",
        "edit_rights": "edit",
        "invite_rights": "document_admin",
        "approve_rights": "no_approve"
      },
      {
        "party_id": "Company",
        "role_id": "Recruiter",
        "display_name": "James Doe",
        "email": "recruiter2@example.com"
      }
    ],
    "accept_entries_changes": true
  }
}

Response body

{
  "document": {
    "id": 43861,
    "name": "I decided to change the name",
    "template_id": 22567,
    "user_id": 4679,
    "profile_id": 4122,
    "status": "created",
    "parties": [
      {
        "id": "Company",
        "name": "Company",
        "roles": [
          {
            "id": "Recruiter",
            "name": "Recruiter",
            "author": true,
            "default_sign_rights": "sign",
            "default_edit_rights": "edit",
            "default_invite_rights": "document_admin",
            "default_approve_rights": "approve"
          }
        ]
      }
    ],
    "participants": [
      {
        "id": 54012,
        "party_id": "Company",
        "role_id": "Recruiter",
        "email": "recruiter@example.com",
        "display_name": "Hey Bye",
        "sign_rights": "sign",
        "edit_rights": "edit",
        "invite_rights": "document_admin",
        "approve_rights": "no_approve"
      },
      {
        "id": 54013,
        "party_id": "Company",
        "role_id": "Recruiter",
        "email": "recruiter2@example.com",
        "display_name": "Bye Hey",
        "sign_rights": "sign",
        "edit_rights": "edit",
        "invite_rights": "document_admin",
        "approve_rights": "approve"
      },
    ],
    "entries": {
      "employee_name": "Louis"
    },
    "activity_log": [
      {
        "message": "Created by <b>Hey Bye</b>.",
        "at": "2021-05-02T10:33:14Z"
      },
      {
        "message": "<b>Hey Bye</b> assigned as author.",
        "at": "2021-05-02T10:33:14Z"
      }
    ],
    "created_at": "2021-05-02T10:32:54Z",
    "updated_at": "2021-05-02T10:33:14Z",
    "signed_at": null
  }
}

Updates an existing Document in your Organisation. Your request will be rejected if document cannot be locked to author party.

HTTP Request

PUT /api/v1/documents/${document_id}

Request body parameters

Attribute Type Description
profile_id Number The ID of Profile to which the Document belongs
user_id Number The ID of the owner user of the Document
name String The title of the document. It defaults to the name of the associated Template if the attribute is not provided
participants (optional) Participant Array The participants to be added or updated. In order to update existing participant please supply his id.
entries Object An object where each key must be a valid attribute name from an Entry Definition in the associated Template and each value is the provided answer for that Entry. Example: { "employee_name": "Bobby Tables" }
accept_entries_changes Boolean Default false. Mark any entries (and text) changes as accepted.
accept_questionnaire Boolean Default false. Mark the author's questionnaire as done.
notifications Object An object that allows you to disable certain email notifications. Accepted keys are party (Added to party) and user (Account created) where omitted keys have default value of true.

Example: { "party": false } prevents Added to party email from being sent.

Publish a Document

Curl example

curl --request POST \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/documents/43861/publish"

Request body (with custom email message)

{
  "document": {
      "custom_email": {
          "subject": "Publish email",
          "message": "Your document has been published",
          "html": true
      }
  }
}

Response body

{
    "document": {
        "id": 43861,
        "published_at": "2023-01-09T13:24:39Z",
        "published_by": "Party A",
        "publish_count": 2
    }
}

Publishes an existing Document in your Organisation. Your request will be rejected if document cannot be published or locked to author party.

HTTP Request

POST /api/v1/documents/${document_id}/publish

Request body parameters

Attribute Type Description
custom_email (optional) The Custom email object An object that allows you to add custom message to emails sent to couter-parties.

The Custom Email object

Attribute Type Description
subject (optional) String Custom email subject
message (optional) String Custom email message
html (optional) Boolean Default is false. Determines whether email message should be treated as html or plain text

The Document Publish object

Attribute Type Description
id Number The ID of the published document
published_at String ISO8601 formatted date and time indicating when the document was published
published_by String The name of the party that published the document
publish_count Number The amount of times the document was published

Export a Document

Curl request example for saving a Document export into a file

curl --request GET \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  --output "my_file.pdf" \
  "https://<your-instance-domain>/api/v1/documents/43881/export?participant_id=54032&format=pdf"

Exports a Document in .pdf or .docx format.

HTTP Request

GET /api/v1/documents/${document_id}/export

Query Parameteres

Parameter Description
format (required) The format of the Document export. Accepted values are "pdf" and "docx"
participant_id (required) The ID of the Participant requesting the Document export

Delete a Document

Curl request example

curl --request DELETE \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/documents/43881"

Marks a Document as deleted.

HTTP Request

DELETE /api/v1/documents/${document_id}

Document Participants

The Participant object

The Participant object represents a Participant (User) in a Document.

Attribute Type Description
id Number The ID of the Participant
document_id Number The ID of the Document to which the Participant belongs
user_id String The ID of the User associated with the Participant
party_id String The ID of the Document Party to which the Participant belongs
role_id String The ID of the Document Party Role to which the Participant belongs
email String The email of the User associated with the Participant
display_name String The display name of the Participant
sign_rights String The sign rights of the Participant. Possible values are "sign", "sign_and_witness" and no_sign
invite_rights String The invite rights of the Participant. Possible values are "document_admin", "party_admin" and "view_only"
edit_rights String The edit rights of the Participant. Possible values are "edit", "questionnaire", "comment" and "view_only"
approve_rights String The approve rights of the Participant. Possible values are "approve" and "no_approve"

List all Participants

Curl request example

curl --request GET \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/documents/123/participants"

Response body

{
  "participants": [
    {
      "id": 456,
      "document_id": 123,
      "user_id": 4721,
      "party_id": "Company",
      "role_id": "Role",
      "email": "hr@example.com",
      "display_name": "John Doe",
      "sign_rights": "no_sign",
      "edit_rights": "edit",
      "invite_rights": "document_admin",
      "approve_rights": "approve"
    }
  ],
  "meta": {
    "pagination": {
      "total_items": 1,
      "items_per_page": 50,
      "total_pages": 1,
      "current_page": 1,
      "links": {
        "current": "https://<your-instance-domain>/api/v1/documents/123/participants?page=1&per_page=50"
      }
    }
  }
}

Lists all Participants for an existing Document in your Organisation.

HTTP Request

GET /api/v1/documents/${document_id}/participants

Delete a Participant

Curl request example

curl --request DELETE \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/documents/123/participants/456"

Curl request example (multiple participants)

curl --request DELETE \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/documents/123/participants/456,457,458"

Marks Participant(s) as deleted.

HTTP Request

DELETE /api/v1/documents/${document_id}/participants/${participant_id}

Document Attachments

The Attachment object

Attribute Type Description
id Number The ID of the attachment
name String Then name of the attachment
content_type String The MIME type of the attachment
size Number The size of the attachment in Bytes
created_at String ISO8601 formatted date and time indicating when the attachment was created
updated_at String ISO8601 formatted date and time indicating when the attachment was last updated

List all Attachments

Curl request example

curl --request GET \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/documents/1/attachments"

Response body

{
  "attachments": [
    {
      "id": 1,
      "name": "Book.xlsx",
      "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "size": 10202,
      "created_at": "2022-08-29T13:40:21Z",
      "updated_at": "2022-08-29T13:40:21Z"
    },
    {
      "id": 2,
      "name": "Text.txt",
      "content_type": "text/plain",
      "size": 1245,
      "created_at": "2022-08-30T15:11:39Z",
      "updated_at": "2022-08-30T15:11:39Z"
    }
  ],
  "meta": {
    "pagination": {
      "total_items": 1,
      "items_per_page": 50,
      "total_pages": 1,
      "current_page": 1,
      "links": {
        "current": "https://<your-instance-domain>/api/v1/documents/1/attachments?page=1&per_page=50"
      }
    }
  }
}

Lists all Attachments for an existing Document in your Organisation.

HTTP Request

GET /api/v1/documents/${document_id}/attachments

Query Parameteres

Parameter Description
sort_by Sort Attachments by a specific attribute. Accepted values are "id", "created_at" and "updated_at". Defaults to "id".
sort_direction Specifies the order applied to the sorted Attachments. Accepted values are "asc" and "desc". Defaults to "desc".

Export an Attachment

Curl request example for saving an Attachment into a file

curl --request GET \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  --output "my_attachment.pdf" \
  "https://<your-instance-domain>/api/v1/documents/1/attachments/2"

Exports an Attachment for an existing Document in your Organisation.

HTTP Request

GET /api/v1/documents/${document_id}/attachments/${attachment_id}

Export all Attachments

Curl request example for saving all Attachments into a file

curl --request GET \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  --output "my_attachments.zip" \
  "https://<your-instance-domain>/api/v1/documents/1/attachments/all"

Exports all Attachments for an existing Document in your Organisation.

HTTP Request

GET /api/v1/documents/${document_id}/attachments/all

Document Labels

The Label object

The Label object represents a Label assigned to the Document.

Attribute Type Description
id Number The ID of the Label
name String The name of the Label
description String The description of the Label
color String The color of the Label in #RRGGBB format
created_at String ISO8601 formatted date and time indicating when the Label was created
updated_at String ISO8601 formatted date and time indicating when the Label was updated for the last time

List all Labels

Curl request example

curl --request GET \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/documents/123/labels"

Response body

{
  "labels": [
    {
      "id": 1,
      "name": "Label Name",
      "description": "Label Description",
      "color": "#000000",
      "created_at": "2022-03-21T09:51:46Z",
      "updated_at": "2022-10-11T08:38:14Z"
    }
  ],
  "meta": {
    "pagination": {
      "total_items": 1,
      "items_per_page": 50,
      "total_pages": 1,
      "current_page": 1,
      "links": {
        "current": "https://<your-instance-domain>/api/v1/documents/123/labels?page=1&per_page=50"
      }
    }
  }
}

Lists all Labels for an existing Document in your Organisation.

HTTP Request

GET /api/v1/documents/${document_id}/labels

Document Questions

This API allows you to manipulate with questions on a per document basic if their configuration permits so

The Question object

Attribute Type Description
attribute Number The question's attribute name
options Object Array The question's select option array consisting of objects with label and value fields

List all Questions

Curl request example

curl --request GET \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/documents/123/questions"

Response body

{
  "questions": [
    {
      "attribute": "Document Attribute",
      "options": [
        {
          "value": "Value 1",
          "label": "Label 1"
        },
        {
          "value": "Value 2",
          "label": "Label 2"
        }
      ]
    },
    {
      "attribute": "Test Attribute",
      "options": [
        {
          "value": "Test",
          "label": "Testing"
        }
      ]
    }
  ]
}

Lists all Questions that may be manipulated via API for an existing Document in your Organisation.

HTTP Request

GET /api/v1/documents/${document_id}/questions

Retrieve a Question

Curl request example

curl --request GET \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/documents/123/questions/Document%20Attribute"

Response body

{
  "question": {
    "attribute": "Document Attribute",
    "options": [
      {
        "value": "Value 1",
        "label": "Label 1"
      },
      {
        "value": "Value 2",
        "label": "Label 2"
      }
    ]
  }
}

Retrieves a Question that may be manipulated via API for an existing Document in your Organisation.

HTTP Request

GET /api/v1/documents/${document_id}/questions/${attribute}

Update a Question

Curl request example

curl --request PUT \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/documents/123/questions/Document%20Attribute"

Request body

{
  "question": {
    "options": [
      {
        "label": "New label",
        "value": "New value"
      },
      {
        "label": "New label 2",
        "value": "New value 2"
      }
    ]
  }
}

Response body

{
  "question": {
    "attribute": "Document Attribute",
    "options": [
      {
        "label": "New label",
        "value": "New value"
      },
      {
        "label": "New label 2",
        "value": "New value 2"
      }
    ]
  }
}

Updates a Question that may be manipulated via API for an existing Document in your Organisation.

HTTP Request

PUT /api/v1/documents/${document_id}/questions/${attribute}

Forms

The Form object

The Form object represents a Form in your Organisation.

Attribute Type Description
id Number The ID of the Form
template_id Number The ID of the Template associated with the Form
party_id String The ID of the Template Party associated with the Form
submit_redirect_url String The URL where a User will be redirected after a successful Form submission
profile_id Number The ID of the Template Party associated with the Form
user_id Number The ID of the User who will set as author of the Documents created from the Form responses
title String The title of the Form
csp_frame_ancestors Array of String The list of allowed frame ancestors for the Form's CSP header
display_logo Boolean When set to true, your Organisation's logo will be displayed on top of the Form
display_title Boolean When set to true, the Form's title will be displayed on top of the Form
accept_changes Boolean When set to false, the generated documents from Form Responses will show questionnaire changes in track
expires_in_minutes Number The number of minutes before a created Form Response expires
created_at String ISO8601 formatted date and time indicating when the Form was created
updated_at String ISO8601 formatted date and time indicating when the Form was updated for the last time

List all Forms

Curl request example

curl --request GET \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/forms"

Response body

{
  "forms": [
    {
      "id": 100,
      "title": "Form test",
      "template_id": 42,
      "party_id": "Party A",
      "profile_id": 123,
      "user_id": 23,
      "csp_frame_ancestors": [],
      "submit_redirect_url": "https://example.com",
      "display_logo": true,
      "display_title": true,
      "accept_changes": true,
      "expires_in_minutes": 10080,
      "created_at": "2021-11-24T10:07:11Z",
      "updated_at": "2021-11-24T10:07:11Z"
    }
  ],
  "meta": {
    "pagination": {
      "total_items": 1,
      "items_per_page": 50,
      "total_pages": 1,
      "current_page": 1,
      "links": {
        "current": "https://<your-instance-domain>/api/v1/forms?page=1&per_page=50"
      }
    }
  }
}

Retrieves all Forms in your Organisation.

HTTP Request

GET /api/v1/forms

Query parameters

Parameter Description
title Filter Forms by title
template_id Filter Forms by template_id
profile_id Filter Forms by profile_id
user_id Filter Forms by user_id
sort_by Sort Forms by a specific attribute. Accepted values are "id", "title". Defaults to "id"
sort_direction Specifies the order applied to the sorted Forms. Accepted values are "asc" and "desc". Defaults to "desc"

Retrieve a Form

Curl request example

curl --request GET \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/forms/100"

Response body

{
  "form": {
    "id": 100,
    "title": "Form test",
    "template_id": 42,
    "party_id": "Party A",
    "profile_id": 123,
    "user_id": 23,
    "csp_frame_ancestors": [],
    "submit_redirect_url": "https://example.com",
    "display_logo": true,
    "display_title": true,
    "accept_changes": true,
    "expires_in_minutes": 10080,
    "created_at": "2021-11-24T10:07:11Z",
    "updated_at": "2021-11-24T10:07:11Z"
  }
}

Retrieves an existing Form in your Organisation.

HTTP Request

GET /api/v1/forms/${form_id}

Create a Form

Curl request example

curl --request POST \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/forms"

Request body

{
  "form": {
    "template_id": 42,
    "party_id": "Party A",
    "submit_redirect_url": "https://example.com"
  }
}

Successful response body

{
  "form": {
    "id": 100,
    "title": "Form test",
    "template_id": 42,
    "party_id": "Party A",
    "profile_id": 123,
    "user_id": 23,
    "csp_frame_ancestors": [],
    "submit_redirect_url": "https://example.com",
    "display_logo": true,
    "display_title": true,
    "accept_changes": true,
    "expires_in_minutes": 10080,
    "created_at": "2021-11-24T10:07:11Z",
    "updated_at": "2021-11-24T10:07:11Z"
  }
}

Creates a new Form in your Organisation.

HTTP Request

POST /api/v1/forms

Request body parameters

attribute type description
template_id (required) Number The ID of the Template associated with the Form.
party_id (required) String The ID of the Template Party associated with the Form.
submit_redirect_url (required) String The URL where a User will be redirected after a successful Form submission.
profile_id Number The ID of the Template Party associated with the Form. Defaults to the Template's profile_id.
user_id Number The ID of the User who will set as author of the Documents created from the Form responses. Defaults to the Template's user_id.
title String The title of the Form. Defaults to the Template's name.
expires_in_minutes Number The amount of minutes before a Form Response expires. Defaults to 10080 (1 week)
csp_frame_ancestors Array of String The list of allowed frame ancestors for the Form's CSP header. This is required if you want to display the Form embedded inside an iframe. More information at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors
display_logo boolean When set to true, your Organisation's logo will be displayed on the top of the page. Defaults to true.
display_title boolean When set to true, the Form's title will be displayed on the top of the page. Defaults to true.
accept_changes boolean When set to false, the generated documents from Form Responses will show questionnaire changes in track. Defaults to true.

Update a Form

Curl request example

curl --request PATCH \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/forms/100"

Request body

{
  "form": {
    "title": "My new title"
  }
}

Successful response body

{
  "form": {
    "id": 100,
    "title": "My new title",
    "template_id": 42,
    "party_id": "Party A",
    "profile_id": 123,
    "user_id": 23,
    "csp_frame_ancestors": [],
    "submit_redirect_url": "https://example.com",
    "display_logo": true,
    "display_title": true,
    "accept_changes": true,
    "expires_in_minutes": 10080,
    "created_at": "2021-11-24T10:07:11Z",
    "updated_at": "2021-11-26T09:04:11Z"
  }
}

Creates a new Form in your Organisation.

HTTP Request

PATCH /api/v1/forms/${form_id}

Request body parameters

attribute type description
title String The title of the Form. Defaults to the Template's name.
csp_frame_ancestors Array of String The list of allowed frame ancestors for the Form's CSP header. This is required if you want to display the Form embedded inside an iframe. More information at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors
display_logo boolean When set to true, your Organisation's logo will be displayed on the top of the page. Defaults to true.
display_title boolean When set to true, the Form's title will be displayed on the top of the page. Defaults to true.
accept_changes boolean When set to false, the generated documents from Form Responses will show questionnaire changes in track. Defaults to true.

Delete a Form

Curl request example

curl --request DELETE \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/forms/100"

Deletes an existing Form.

HTTP Request

DELETE /api/v1/forms/${form_id}

Form Responses

The Form Response object

The Form Response object represents a Form Response in your Organisation.

Attribute Type Description
id Number The ID of the Form Response
form_id Number The ID of the parent Form
document_id Number The ID of the Document associated with the Form Response. This value will only be present after the Form Response has been submitted
participant_id Number The ID of the Participant associated with the Form. This value will only be present after the Form Response has been submitted
external_id String External identifier that was provided when the Form Response was created
status String The status of the Form Respose. Possible values are created and submitted
data Object The answers of the Form Response. This value will only be present after the Form Response has been submitted
ip_address String The IP address of the client that submitted the Form Response
user_agent String The user agent of the client that submitted the Form Response
expired Boolean When set to true, it indicates that the Form Response has expired
expires_at String ISO8601 formatted date and time indicating when the Form Response expires
created_at String ISO8601 formatted date and time indicating when the Form Response was created
updated_at String ISO8601 formatted date and time indicating when the Form Response was updated for the last time
submitted_at String ISO8601 formatted date and time indicating when the Form Response was submitted

List all Form Responses

Curl request example

curl --request GET \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/form_responses"

Response body

{
  "form_responses": [
    {
      "id": 111,
      "form_id": 13,
      "document_id": 344,
      "participant_id": 2032,
      "external_id": null,
      "status": "submitted",
      "data": {
        "first_name": "Guybrush",
        "last_name": "Threepwood"
      },
      "ip_address": "123.123.123.123",
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/99.0.4844.82 Safari/537.36",
      "expired": false,
      "expires_at": "2022-04-07T15:15:59Z",
      "created_at": "2022-03-31T15:15:59Z",
      "updated_at": "2022-03-31T15:15:59Z",
      "submitted_at": "2022-03-31T14:48:39Z",
      "links": {
        "url": "https://<your-instance-domain>/forms/9f3c95e20b4d/r/d54566773d78"
      }
      }
  ],
  "meta": {
    "pagination": {
      "total_items": 1,
      "items_per_page": 50,
      "total_pages": 1,
      "current_page": 1,
      "links": {
        "current": "https://<your-instance-domain>/api/v1/form_responses?page=1&per_page=50"
      }
    }
  }
}

Retrieves all Form Responses in your Organisation.

HTTP Request

GET /api/v1/form_responses

Retrieve a Form Response

Curl request example

curl --request GET \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/form_responses/111"

Response body

{
  "form_response": {
    "id": 111,
    "form_id": 13,
    "document_id": 344,
    "participant_id": 2032,
    "external_id": null,
    "status": "submitted",
    "data": {
      "first_name": "Guybrush",
      "last_name": "Threepwood"
    },
    "ip_address": "123.123.123.123",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/99.0.4844.82 Safari/537.36",
    "expired": false,
    "expires_at": "2022-04-07T15:15:59Z",
    "created_at": "2022-03-31T15:15:59Z",
    "updated_at": "2022-03-31T15:15:59Z",
    "submitted_at": "2022-03-31T14:48:39Z",
    "links": {
      "url": "https://<your-instance-domain>/forms/9f3c95e20b4d/r/d54566773d78"
    }
  }
}

Retrieves an existing Form Response in your Organisation.

HTTP Request

GET /api/v1/form_responses/${form_response_id}

Create a Form Response

Curl request example

curl --request POST \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/form_responses"

Request body

{
  "form_response": {
    "form_id": 13,
    "email": "mail@example.com",
    "external_id": "my_id_123"
  }
}

Successful response body

{
  "form_response": {
    "id": 20,
    "form_id": 13,
    "document_id": null,
    "participant_id": null,
    "external_id": "my_id_123",
    "status": "created",
    "data": null,
    "ip_address": null,
    "user_agent": null,
    "expired": false,
    "expires_at": "2022-04-07T15:15:59Z",
    "created_at": "2022-03-31T15:15:59Z",
    "updated_at": "2022-03-31T15:15:59Z",
    "submitted_at": null,
    "links": {
      "url": "https://<your-instance-domain>/forms/9f3c95e20b4d/r/d54443773d78"
    }
  }
}

Creates a new Form Response in your Organisation.

HTTP Request

POST /api/v1/form_responses

Request body parameters

attribute type description
form_id (required) Number The ID of the parent Form
email (required) String A valid email address that will be associated with the Form Response
external_id String An optional identifier that can be used to associate the Form Response with an external system

Organisations

The Organisation object

The Organisation object represents the Organisation associated with your API token.

Attribute Type Description
id Number The ID of the Organisation
name String The name of the Organisation
created_at String ISO8601 formatted date and time indicating when the Organisation was created
updated_at String ISO8601 formatted date and time indicating when the Organisation was updated for the last time

Retrieve your Organisation

Curl request example

curl --request GET \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/organisation"

Response body

{
  "organisation": {
    "id": 144,
    "name": "Stan's Previously Owned Vessels",
    "created_at": "1990-10-15T22:00:00Z",
    "updated_at": "1990-10-15T22:00:00Z"
  }
}

HTTP Request

Retrieves your Organisation.

GET /api/v1/organisation

Profiles

The Profile object

The Profile object represents a Profile in your Organisation.

Attribute Type Description
id Number The ID of the Profile
name String The name of the Profile
created_at String ISO8601 formatted date and time indicating when the Profile was created
updated_at String ISO8601 formatted date and time indicating when the Profile was updated for the last time

List all Profiles

Curl request example

curl --request GET \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/profiles"

Response body

{
  "profiles": [
    {
      "id": 4170,
      "name": "Administrators",
      "active": true,
      "created_at": "2021-07-06T08:35:59Z",
      "updated_at": "2021-07-06T08:35:59Z"
    }
  ],
  "meta": {
    "pagination": {
      "total_items": 1,
      "items_per_page": 50,
      "total_pages": 1,
      "current_page": 1,
      "links": {
        "current": "https://<your-instance-domain>/api/v1/profiles?page=1&per_page=50"
      }
    }
  }
}

Retrieves all Profiles in your Organisation.

HTTP Request

GET /api/v1/profiles

Query parameters

Parameter Description
active Filter Profiles by active. Accepted values are "true" and "false"
sort_by Sort Profiles by a specific attribute. Accepted values are "id", "name" and "updated_at". Defaults to "id".
sort_direction Specifies the order applied to the sorted Profiles. Accepted values are "asc" and "desc". Defaults to "desc".

Retrieve a Profile

Curl request example

curl --request GET \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/profiles/4170"

Response body

{
  "profile": {
     "id": 4170,
      "name": "Administrators",
      "active": true,
      "created_at": "2021-07-06T08:35:59Z",
      "updated_at": "2021-07-06T08:35:59Z"
  }
}

Retrieves an existing Profile in your Organisation.

HTTP Request

GET /api/v1/profiles/${profile_id}

Create a Profile

Curl request example

curl --request POST \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/profiles"

Request body

{
  "profile": {
    "name": "Avengers"
  }
}

Successful response body

{
  "profile": {
    "id": 4121,
    "name": "Avengers",
    "active": true,
    "created_at": "2021-04-13T07:09:11Z",
    "updated_at": "2021-04-13T07:09:11Z"
  }
}

Creates a new Profile in your Organisation.

HTTP Request

POST /api/v1/profiles

Request body parameters

Attribute Type Description
name (required) String The name of the Profile
active Boolean Indicates if the Profile is active. Defaults to true

Update a Profile

Curl request example

curl --request PATCH \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/profiles/4121"

Request body

{
  "profile": {
    "name": "Avengers"
  }
}

Successful response body

{
  "profile": {
    "id": 4121,
    "name": "Avengers",
    "active": true,
    "created_at": "2021-04-13T07:09:11Z",
    "updated_at": "2021-04-15T05:09:11Z"
  }
}

Updates an existing Profile in your Organisation.

HTTP Request

PATCH /api/v1/profiles/${profile_id}

Request body parameters

Attribute Type Description
name String The name of the Profile
active Boolean Indicates if the Profile is active.

Profile Memberships

The Profile Membership object

The Profile Membership object represents a User membership within a Profile.

Attribute Type Description
id Number The ID of the Profile Membership
profile_id Number The ID of the Profile associated with the Profile Membership
user_id Number The ID of the User associated with the Profile Membership
role String The role of the User in the Profile. Possible values are "Onboard", "New document" or "View"
admin Boolean Indicates if the User has admin rights in the Profile
manager Boolean Indicates if the User has manager rights in the Profile
created_at String ISO8601 formatted date and time indicating when the Profile Membership was created
updated_at String ISO8601 formatted date and time indicating when the Profile Membership was updated for the last time

List all Profile Memberships

Curl request example

curl --request GET \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/profile_memberships"

Response body

{
  "profile_memberships": [
    {
      "id": 6659,
      "profile_id": 4121,
      "user_id": 4679,
      "role": "Onboard",
      "admin": true,
      "manager": false,
      "created_at": "2021-04-14T13:03:12Z",
      "updated_at": "2021-04-14T13:03:12Z"
    }
  ],
  "meta": {
    "pagination": {
      "total_items": 1,
      "items_per_page": 50,
      "total_pages": 1,
      "current_page": 1,
      "links": {
        "current": "https://<your-instance-domain>/api/v1/profile_memberships?page=1&per_page=50"
      }
    }
  }
}

Retrieves all Profiles in your Organisation.

HTTP Request

GET /api/v1/profile_memberships

Query parameters

Parameter Description
profile_id Filter Profile Memberships by profile_id
user_id Filter Profile Memberships by user_id
role Filter Profile Memberships by role. Accepted values are "Onboard", "New document" and "View"
admin Filter Profile Memberships by admin. Accepted values are "true" and "false"
manager Filter Profile Memberships by manager. Accepted values are "true" and "false"
sort_by Sort Profile Memberships by a specific attribute. Accepted values are "id" and "updated_at". Defaults to "id".
sort_direction Specifies the order applied to the sorted Profile Memberships. Accepted values are "asc" and "desc". Defaults to "desc".

Retrieve a Profile Membership

Curl request example

curl --request GET \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/profile_memberships/6659"

Response body

{
  "profile_membership": {
    "id": 6659,
    "profile_id": 4121,
    "user_id": 4679,
    "role": "Onboard",
    "admin": true,
    "manager": false,
    "created_at": "2021-04-14T13:03:12Z",
    "updated_at": "2021-04-14T13:03:12Z"
  }
}

Retrieves an existing Profile Membership in your Organisation.

HTTP Request

GET /api/v1/profile_memberships/${profile_membership_id}

Create a Profile Membership

Curl request example

curl --request POST \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/profile_memberships"

Request body

{
  "profile_membership": {
    "profile_id": 4121,
    "user_id": 4679,
    "role": "Onboard",
    "admin": true,
    "manager": false,
  }
}

Successful response body

{
  "profile_membership": {
    "id": 6659,
    "profile_id": 4121,
    "user_id": 4679,
    "role": "Onboard",
    "admin": true,
    "manager": false,
    "created_at": "2021-04-14T13:03:12Z",
    "updated_at": "2021-04-14T13:03:12Z"
  }
}

Creates a new Profile Membership in your Organisation.

HTTP Request

POST /api/v1/profile_memberships

Request body parameters

Attribute Type Description
user_id (required) Number The ID of the User
profile_id (required) Number The ID of the Profile
role String The role of the User in the Profile. Accepted values are "Onboard", "New document" or "View"
admin Boolean Indicates if the User has admin rights in the Profile
manager Boolean Indicates if the User has manager rights in the Profile

Delete a Profile Membership

Curl request example

curl --request DELETE \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/profile_memberships/43881"

Deletes an existing Profile Membership.

HTTP Request

DELETE /api/v1/profile_memberships/${profile_membership_id}

Templates

Templates were refactored into a better DB structure, where each template version has its own ID and they are related to a parent Template object. For keeping backward compatibility, all template_id in this API version is using the Template Version ID. This will be changed in APIv2.

The Template object

The Template object represents a Document Template in your Organisation.

Attribute Type Description
id Number The ID of the Template (due to the backward compatibility, it is now the Template Version ID)
name String The name of the Template
version String The version of the Template
draft Boolean Indicates whether the Template is a draft or not
private Boolean Indicates whether the Template is private or not
profile_id Number The ID of the Profile to which the Template belongs
user_id Number The ID of the User who owns the Template
original_id Number The ID of the first version of the Template
parent_id Number The ID of the previous version of the Template
published Boolean Indicates whether this version of the Template is currently published
published_at String ISO8601 formatted date and time indicating when the Template was published
publish_message String The associated message with the update or publishing of this version of the Template
current_version Boolean Indicates whether this version of the Template is the last available version
parties Template Party Array The Parties of the Template
entry_definitions Entry Definition Array The details of the entries a Document will accept when created from this Template
links Object The links associated with the Template on the Avvoka Platform
created_at String ISO8601 formatted date and time indicating when the Template was created
updated_at String ISO8601 formatted date and time indicating when the Template was updated for the last time
archived_at String ISO8601 formatted date and time indicating when the Template was archived

The Template Party object

The Template Party object represents a party within a Template.

Attribute Type Description
id String The ID of the Party
name String The name of the Party
roles Template Role Array The roles of the Party

The Template Role object

The Template Role object represents a party within a Template Party.

Attribute Type Description
id String The ID of the Role
name String The name of the Role
default_sign_rights String The sign rights that will be assigned by default to each participant with this Role. Possible values are sign, sign_and_witness and no_sign
default_invite_rights String The invite rights that will be assigned by default to each participant with this Role. Possible values are document_admin, party_admin and view_only
default_edit_rights String The edit rights that will be assigned by default to each participant with this Role. Possible values are edit, questionnaire, comment and view_only
default_approve_rights String The approve rights that will be assigned by default to each participant with this Role. Possible values are approve and no_approve

The Entry Definition object

The Entry Definition object represents an input, question or explanatory text specified in a Template. A group of Entry Definitions become a Document Questionnaire when a Document is created from a Template.

Attribute Type Description
attribute String The attribute key of the Entry Definition
type String The form input type of the Entry Definition
position String The position of the input in the Document questionnaire
party_id String The ID of the Document Party that will provide the answer for the Entry Definition
default_value String The default value that will be assigned to the entry
question String The label of the form input
hint String The hint (placeholder) of the form input
required Boolean Indicates whether it is a required field
color String The hexadecimal color code of the form input
condition Object AST object indicating when the form input should be displayed
options Array List of available options for the form input
list_name String The name of a (dependent) list that contains values for the form input
dependent_attribute String The attribute key to filter dependent list values by
loop_name String The name of a loop for looped attributes
master_loop_name String The name of a master loop for looped attributes subject to another loop
range Object An object indicating the range of possible values for the form input. Both minimum and maximum values can appear in following formats:
For number entry type:
- null for no value
- any number for specific number value
For date entry type:
- null for no value
- dd/mm/yy for specific date
- creation[+-]\d+[d|bd|m|y] for a creation offset that specifies the amount of days, business days, months or years, before or after the document creation

List all Templates

Curl request example

curl --request GET \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/templates"

Response body

{
  "templates": [
    {
      "id": 1323,
      "name": "Employment agreement",
      "version": "1",
      "draft": false,
      "private": false,
      "profile_id": 4534,
      "user_id": 3444,
      "original_id": 1300,
      "parent_id": 1320,
      "published": true,
      "published_at": "2021-09-15T16:59:14Z",
      "publish_message": "first version",
      "current_version": true,
      "parties": [
        {
          "id": "Company",
          "name": "Company",
          "roles": [
            {
              "id": "Recruiter",
              "name": "Recruiter",
              "author": true,
              "default_sign_rights": "sign",
              "default_edit_rights": "edit",
              "default_invite_rights": "document_admin",
              "default_approve_rights": "approve"
            }
          ]
        }
      ],
      "entry_definitions": [
        {
          "attribute": "employee_name",
          "type": "text",
          "position": 0,
          "party_id": "company",
          "default_value": null,
          "question": "Please provide the name of the employee",
          "required": null,
          "hint": "This is a hint",
          "color": null,
          "condition": null,
          "options": [],
          "loop_name": null,
          "master_loop_name": null
        }
      ],
      "links": {
        "avvoka_template_url": "https://<your-instance-domain>/templates/1323/edit"
      },
      "created_at": "2020-06-30T13:59:16Z",
      "updated_at": "2020-07-01T14:08:53Z",
      "archived_at": null
    }
  ],
  "meta": {
    "pagination": {
      "total_items": 1,
      "items_per_page": 50,
      "total_pages": 1,
      "current_page": 1,
      "links": {
        "current": "https://<your-instance-domain>/api/v1/templates?page=1&per_page=50"
      }
    }
  }
}

Retrieves all Templates in your Organisation. Please note that the entry_definitions attribute of each Template is not included in the response of this endpoint, Entry Definitions are only included when retrieving a specific Template.

HTTP Request

GET /api/v1/templates

Query parameters

Parameter Description
name Filter Templates by name
name_like Filter Templates by name (partial match)
profile_id Filter Templates by profile_id
user_id Filter Templates by user_id
original_id Filter Templates by original_id
published Filter Templates by published
current_version Filter Templates by current_version
current_published_version Display only current published version of each template
user_id Filter Templates by user_id
exclude_archived When set to "true", archived Templates will be excluded from the list.
sort_by Sort Templates by a specific attribute. Accepted values are "id", "name" and "updated_at". Defaults to "id".
sort_direction Specifies the order applied to the sorted Templates. Accepted values are "asc" and "desc". Defaults to "desc".

Retrieve a Template

Curl request example

curl --request GET \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/templates/1323"

Response body

{
  "template": {
    "id": 1323,
    "name": "Employment agreement",
    "version": "1",
    "draft": false,
    "private": false,
    "profile_id": 4534,
    "user_id": 3444,
    "original_id": 1300,
    "parent_id": 1320,
    "published": true,
    "published_at": "2021-09-15T16:59:14Z",
    "publish_message": "first version",
    "current_version": true,
    "parties": [
      {
        "id": "Company",
        "name": "Company",
        "roles": [
          {
            "id": "Recruiter",
            "name": "Recruiter",
            "author": true,
            "default_sign_rights": "sign",
            "default_edit_rights": "edit",
            "default_invite_rights": "document_admin",
            "default_approve_rights": "approve"
          }
        ]
      }
    ],
    "entry_definitions": [
      {
        "attribute": "employee_name",
        "type": "text",
        "position": 0,
        "party_id": "company",
        "default_value": null,
        "question": "Please provide the name of the employee",
        "hint": "This is a hint",
        "required": null,
        "color": null,
        "condition": null,
        "options": [],
        "loop_name": null,
        "master_loop_name": null
      }
    ],
    "links": {
      "avvoka_template_url": "https://<your-instance-domain>/templates/1323/edit"
    },
    "created_at": "2020-06-30T13:59:16Z",
    "updated_at": "2020-07-01T14:08:53Z",
    "archived_at": null
  }
}

Retrieves an existing Template in your Organisation.

HTTP Request

GET /api/v1/templates/${template_id}

Template Packs

The Template Pack object

The Template Pack object represents pack of Templates in your Organisation.

Attribute Type Description
id Number The ID of the Template Pack
name String The name of the Template Pack
profile_id Number The ID of the Profile to which the Template Pack belongs
number_of_templates Number The amount of Templates in the Template Pack
templates Template Pack Item Array The details about Templates in the Template Pack
created_at String ISO8601 formatted date and time indicating when the Template was created
updated_at String ISO8601 formatted date and time indicating when the Template was updated for the last time

The Template Pack Item object

The Template Pack Item object represents a template within a Template Pack.

Attribute Type Description
id String The ID of the Template
name String The name of the Template
entry_definitions Entry Definition Array The details of the entries a Document will accept when created from the Template

List all Template Packs

Curl request example

curl --request GET \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/template_packs"

Response body

{
  "template_packs": [
    {
      "id": 1323,
      "name": "Employment agreements",
      "profile_id": 4534,
      "number_of_templates": 2,
      "templates": [
        {
          "id": 1300,
          "name": "Employment agreement"
        },
        {
          "id": 2600,
          "name": "Employment agreement 2"
        }
      ],
      "created_at": "2020-06-30T13:59:16Z",
      "updated_at": "2020-07-01T14:08:53Z"
    }
  ],
  "meta": {
    "pagination": {
      "total_items": 1,
      "items_per_page": 50,
      "total_pages": 1,
      "current_page": 1,
      "links": {
        "current": "https://<your-instance-domain>/api/v1/template_packs?page=1&per_page=50"
      }
    }
  }
}

Retrieves all Template Packs in your Organisation. Please note that the entry_definitions attribute of each Template Pack Item is not included in the response of this endpoint, Entry Definitions are only included when retrieving a specific Template Pack.

HTTP Request

GET /api/v1/template_packs

Query parameters

Parameter Description
name Filter Template Packs by name
profile_id Filter Template Packs by profile_id
sort_by Sort Template Packs by a specific attribute. Accepted values are "id", "name" and "updated_at". Defaults to "id".
sort_direction Specifies the order applied to the sorted Template Packs. Accepted values are "asc" and "desc". Defaults to "desc".

Retrieve a Template Pack

Curl request example

curl --request GET \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/template_packs/1323"

Response body

{
  "template_pack": {
    "id": 1323,
    "name": "Employment agreements",
    "profile_id": 4534,
    "number_of_templates": 2,
    "templates": [
      {
        "id": 1300,
        "name": "Employment agreement",
        "entry_definitions": [
          {
            "attribute": "employee_name",
            "type": "text",
            "position": 0,
            "party_id": "company",
            "default_value": null,
            "question": "Please provide the name of the employee",
            "hint": "This is a hint",
            "required": null,
            "color": null,
            "condition": null,
            "options": [],
            "loop_name": null,
            "master_loop_name": null
          }
        ],
      },
      {
        "id": 2600,
        "name": "Employment agreement 2",
        "entry_definitions": [
          {
            "attribute": "employee_name",
            "type": "text",
            "position": 0,
            "party_id": "company",
            "default_value": null,
            "question": "Please provide the name of the employee",
            "hint": "This is a hint",
            "required": null,
            "color": null,
            "condition": null,
            "options": [],
            "loop_name": null,
            "master_loop_name": null
          }
        ]
      }
    ],
    "created_at": "2020-06-30T13:59:16Z",
    "updated_at": "2020-07-01T14:08:53Z"
  }
}

Retrieves an existing Template Pack in your Organisation.

HTTP Request

GET /api/v1/template_packs/${template_pack_id}

List Items

Retrieve a List Item

Curl request example

curl --request GET \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/lists/items?name=List1"

Response body (List)

{
  "items": [
    {
      "id": 1,
      "value": "Value 1"
    }
  ],
  "meta": {
    "pagination": {
      "total_items": 1,
      "items_per_page": 50,
      "total_pages": 1,
      "current_page": 1,
      "links": {
        "current": "https://<your-instance-domain>/api/v1/lists/items?name=List1&page=1&per_page=50"
      }
    }
  }
}

Response body (Dependent List)

{
  "items": [
    {
      "id": 1,
      "key": "Key 1",
      "value": "Value 1"
    }
  ],
  "meta": {
    "pagination": {
      "total_items": 1,
      "items_per_page": 50,
      "total_pages": 1,
      "current_page": 1,
      "links": {
        "current": "https://<your-instance-domain>/api/v1/lists/items?name=List1&page=1&per_page=50"
      }
    }
  }
}

Retrieves all List Items in your List or Dependent List.

HTTP Request

GET /api/v1/lists/items

Query parameters

Parameter Description
name (required) Specifies the name of the list to source items from

Users

The User object

The User object represents a User account in your Organisation.

Attribute Type Description
id Number The ID of the User
email String The email of the User
firstname String The first name of the User
lastname String The last name of the User
locale String The locale of the User
time_zone String The time zone of the User (if set)
confirmed_at String ISO8601 formatted date and time indicating when the User's acount was confirmed
created_at String ISO8601 formatted date and time indicating when the User was created
updated_at String ISO8601 formatted date and time indicating when the User was updated for the last time
last_sign_in_at String ISO8601 formatted date and time indicating when the User signed to Avvoka for the last time
deleted_at String ISO8601 formatted date and time indicating when the User was marked as deleted

List all Users

Curl request example

curl --request GET \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/users"

Response body

{
  "users": [
    {
      "id": 4679,
      "email": "elaine@monkeyisland.dev",
      "firstname": "Elaine",
      "lastname": "Marley",
      "locale": "en",
      "time_zone": "Europe/London",
      "confirmed_at": "2021-01-22T15:33:37Z",
      "created_at": "2021-01-22T15:33:37Z",
      "updated_at": "2021-07-06T12:52:46Z",
      "last_sign_in_at": "2021-07-06T11:05:36Z",
      "deleted_at": null
    }
  ],
  "meta": {
    "pagination": {
      "total_items": 1,
      "items_per_page": 50,
      "total_pages": 1,
      "current_page": 1,
      "links": {
        "current": "https://<your-instance-domain>/api/v1/users?page=1&per_page=50"
      }
    }
  }
}

Retrieves all Users in your Organisation.

HTTP Request

GET /api/v1/users

Query parameters

Parameter Description
firstname Filter Users by firstname
lastname Filter Users by lastname
email Filter Users by email
exclude_deleted When set to "true", deleted Users will be excluded from the list
sort_by Sort Users by a specific attribute. Accepted values are "id", "email", "firstname", "lastname" and "updated_at". Defaults to "id".
sort_direction Specifies the order applied to the sorted Users. Accepted values are "asc" and "desc". Defaults to "desc".

Retrieve a User

Curl request example

curl --request GET \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/users/4170"

Response body

{
  "user": {
    "id": 4679,
    "email": "elaine@monkeyisland.dev",
    "firstname": "Elaine",
    "lastname": "Marley",
    "locale": "en",
    "time_zone": "Europe/London",
    "confirmed_at": "2021-01-22T15:33:37Z",
    "created_at": "2021-01-22T15:33:37Z",
    "updated_at": "2021-07-06T12:52:46Z",
    "last_sign_in_at": "2021-07-06T11:05:36Z",
    "deleted_at": null
  }
}

Retrieves an existing User in your Organisation.

HTTP Request

GET /api/v1/users/${user_id}

Create a User

Curl request example

curl --request POST \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/users"

Request body

{
  "user": {
    "email": "elaine@monkeyisland.dev",
    "firstname": "Elaine",
    "lastname": "Marley"
  }
}

Successful response body

{
  "user": {
    "id": 4679,
    "email": "elaine@monkeyisland.dev",
    "firstname": "Elaine",
    "lastname": "Marley",
    "locale": "en",
    "time_zone": "Europe/London",
    "confirmed_at": null,
    "created_at": "2021-01-22T15:33:37Z",
    "updated_at": "2021-07-06T12:52:46Z",
    "last_sign_in_at": null,
    "deleted_at": null
  }
}

Creates a new User account in your Organisation.

Please note that every User must be a member of at least one Profile in order to login. This can be achieved by creating a Profile Membership after the User has been created.

HTTP Request

POST /api/v1/users

Request body parameters

Attribute Type Description
email (required) String The email of the User
firstname String The first name of the User
lastname String The last name of the User

Webhook Payloads

The Webhook Payload object

The Webhook Payload object represents the state of the object when the webhook was triggered.

Attribute Type Description
uuid UUID The ID of the Webhook Payload
webhook_id Number The ID of the Webhook which Webhook Payload belongs
payload Object The content of the Payload (different per a webhook source)
created_at String ISO8601 formatted date and time indicating when the Payload was created

List all Webhook Payloads

Curl request example

curl --request GET \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/webhooks/payloads"

Response body

{
  "webhook_payloads": [
    {
      "uuid": "9a043b5c-8d38-4f23-a4b3-277635e6801d",
      "webhook_id": 1,
      "payload": {
        "data": {
          "id": 1,
          "template_id": 1,
          "title": "Document Name",
          "draft": false,
          "state": "created",
          "publish_count": 0,
          "first_published_at": null,
          "signed_at": null,
          "finished_at": null,
          "user_id": 3,
          "created_at": "2021-07-23T08:37:55Z",
          "updated_at": "2021-07-23T08:37:55Z"
        },
        "event": "document_created",
        "triggered_by_type": "User",
        "triggered_by_id": 1,
        "meta": null
      },
      "created_at": "2021-07-23T08:37:56Z"
    }
  ],
  "meta": {
    "pagination": {
      "total_items": 1,
      "items_per_page": 50,
      "total_pages": 1,
      "current_page": 1,
      "links": {
        "current": "https://<your-instance-domain>/api/v1/webhooks/payloads?page=1&per_page=50"
      }
    }
  }
}

Retrieves all Webhook Payloads in your Organisation.

HTTP Request

GET /api/v1/webhooks/payloads

Query parameters

Parameter Description
webhook_id Filter Webhook Payloads by webhook_id
sort_by Sort Users by a specific attribute. Accepted values are "webhook_id" and "created_at". Defaults to "created_at".
sort_direction Specifies the order applied to the sorted Users. Accepted values are "asc" and "desc". Defaults to "desc".

Retrieve a Webhook Payload

Curl request example

curl --request GET \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/webhooks/payloads/9a043b5c-8d38-4f23-a4b3-277635e6801d"

Response body

{
  "webhook_payload": {
    "uuid": "9a043b5c-8d38-4f23-a4b3-277635e6801d",
    "webhook_id": 1,
    "payload": {
      "data": {
        "id": 1,
        "template_id": 1,
        "title": "Document Name",
        "draft": false,
        "state": "created",
        "publish_count": 0,
        "first_published_at": null,
        "signed_at": null,
        "finished_at": null,
        "user_id": 3,
        "created_at": "2021-07-23T08:37:55Z",
        "updated_at": "2021-07-23T08:37:55Z"
      },
      "event": "document_created",
      "triggered_by_type": "User",
      "triggered_by_id": 1,
      "meta": null
    },
    "created_at": "2021-07-23T08:37:56Z"
  }
}

Retrieves an existing Webhook Payload in your Organisation.

HTTP Request

GET /api/v1/webhooks/payloads/${uuid}

Datasheets

The Datasheet object

The datasheet object represents a datasheet in your organisation

Attribute Type Description
id Number The ID of the Datasheet
name String The name of the Datasheet
profile_id Number The ID of the Profile the Datasheet is in
headers Datasheet Header Array An array of headers within the datasheet
created_at String ISO8601 formatted date and time indicating when the Datasheet was created
updated_at String ISO8601 formatted date and time indicating when the Datasheet was updated for the last time

The Datasheet Header object

The datasheet header object represents a single header (column) in your datasheet

Attribute Type Description
id Number The ID of the Datasheet Header
name String The name of the Datasheet Header
type String The type of the values. Possible values are text, text_area, select, radio, date, open_select or number.
format String The format of the values. Only applicable to date type.
options Array List of all possible values within this header. Only applicable to select, radio or open_select type.
constraints Array List of all value constraints. Possible values are unique or unique_warning.

The Datasheet Record object

The datasheet record object represents a single record (row) in your datasheet

Attribute Type Description
id Number The ID of the Datasheet Record
values Object An object that contains the values of the record. The keys of this object are the IDs of the Datasheet Headers.
created_at String ISO8601 formatted date and time indicating when the Datasheet Record was created
updated_at String ISO8601 formatted date and time indicating when the Datasheet Record was updated for the last time

List all Datasheets

Curl request example

curl --request GET \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/datasheets"

Response body

{
  "datasheets": [
    {
      "id": 123,
      "profile_id": 33,
      "name": "My Datasheet",
      "created_at": "2021-07-05T15:50:08Z",
      "updated_at": "2021-07-05T15:50:39Z"
    },
    {
      "id": 456,
      "profile_id": 35,
      "name": "My Datasheet 2",
      "created_at": "2021-07-05T15:50:08Z",
      "updated_at": "2021-07-05T15:50:39Z"
    }
  ],
  "meta": {
    "pagination": {
      "total_items": 1,
      "items_per_page": 50,
      "total_pages": 1,
      "current_page": 1,
      "links": {
        "current": "https://<your-instance-domain>/api/v1/datasheets?page=1&per_page=50"
      }
    }
  }
}

Retrieves all Datasheets in your organisation. Please note that the headers attribute of each Datasheet is not included in the response of this endpoint, entries are only included when retrieving a specific Datasheet.

HTTP Request

GET /api/v1/datasheets

Retrieve a Datasheet

Curl request example

curl --request GET \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/datasheets/123"

Response body

{
  "datasheet": {
    "id": 123,
    "profile_id": 33,
    "name": "My Datasheet",
    "headers": [
      {
        "id": 55,
        "name": "Column A",
        "type": "text",
        "constraints": []
      },
      {
        "id": 56,
        "name": "Column B",
        "type": "select",
        "options": ["A", "B", "C"],
        "constraints": []
      }
    ],
    "created_at": "2021-07-05T15:50:08Z",
    "updated_at": "2021-07-05T15:50:39Z"
  }
}

Retrieves an existing Datasheet in your Organisation.

HTTP Request

GET /api/v1/datasheets/${datasheet_id}

Datasheet Records

List all Datasheet Records

Curl request example

curl --request GET \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/datasheets/123/records"

Response body

{
  "records": [
    {
      "id": 1000,
      "values": {
        "55": "Value 1",
        "56": "A"
      },
      "created_at": "2021-07-05T15:50:08Z",
      "updated_at": "2021-07-05T15:50:39Z"
    },
    {
      "id": 1002,
      "values": {
        "55": "Value 2",
        "56": "B"
      },
      "created_at": "2021-07-05T15:50:08Z",
      "updated_at": "2021-07-05T15:50:39Z"
    }
  ],
  "meta": {
    "pagination": {
      "total_items": 1,
      "items_per_page": 50,
      "total_pages": 1,
      "current_page": 1,
      "links": {
        "current": "https://<your-instance-domain>/api/v1/datasheets/123/records?page=1&per_page=50"
      }
    }
  }
}

Retrieves all Datasheet Records for your Datasheet

HTTP Request

GET /api/v1/datasheets/${datasheet_id}/records

Create a Datasheet Record

Curl example

curl --request POST \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/datasheets/123/records"

Request body

{
  "record": {
    "values": {
      "55": "Value 3",
      "56": "C"
    }
  }
}

Response body

{
  "record": {
    "id": 1003,
     "values": {
      "55": "Value 3",
      "56": "C"
    },
    "created_at": "2021-05-02T10:33:14Z",
    "updated_at": "2021-05-02T10:33:14Z"
  }
}

Creates a new Datasheet Record in your Datasheet.

HTTP Request

POST /api/v1/datasheets/${datasheet_id}/records

Request body parameters

Attribute Type Description
values Object An object that contains the values of the record. The keys of this object are the IDs of the Datasheet Headers.

Update a Datasheet Record

Curl example

curl --request PUT \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/datasheets/123/records/1000"

Request body

{
  "record": {
    "values": {
      "55": "Value 3",
      "56": "C"
    }
  }
}

Response body

{
  "record": {
    "id": 1000,
     "values": {
      "55": "Value 3",
      "56": "C"
    },
    "created_at": "2021-05-02T10:32:54Z",
    "updated_at": "2021-05-02T10:33:14Z"
  }
}

Updates an existing Datasheet Record in your Datasheet.

HTTP Request

PUT /api/v1/datasheets/${datasheet_id}/records/${record_id}

Request body parameters

Attribute Type Description
values Object An object that contains the values of the record. The keys of this object are the IDs of the Datasheet Headers.

Delete a Datasheet Record

Curl request example

curl --request DELETE \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/datasheets/123/records/1000"

Permanently deletes a Datasheet Record from your Datasheet.

HTTP Request

DELETE /api/v1/datasheets/${datasheet_id}/records/${record_id}