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

2023-09-08

Updated description of Entry definition object to include better explanation of range attribute

2023-08-04

Added range attribute to Entry definition object

2023-05-26

Added Document Questions

2023-02-23

Added accept_questionnaire attribute to Create a Document and Update a Document

2023-01-09

Added Publish a Document

2022-12-15

Added notifications attribute to Create a Document and Update a Document
Added activity_log attribute to The Document object
Added Document Labels

2022-11-25

Added name_like and current_published_version parameters to List all Templates

2022-10-26

Added option to delete multiple participants at once to Delete a Participant

2022-10-12

Added Template Packs.
Added locale and time_zone attribute to The User object.
Added loop_name and master_loop_name attributes to Entry definition object.

2022-10-07

Added Participants.

2022-08-30

Added Document Attachments.

2022-07-25

Added participants to Update a Document to update document participants after document creation.

2022-07-19

Added accept_changes attribute to Forms.

2022-06-06

Added the dependent_attribute attribute to the Entry definition object.

2022-06-02

Added List Items.
Added the list_name attribute to the Entry definition object.
Updated description of Entry definition object to include explanatory text.
Updated description of the entries attribute in the The document object to include explanatory text.

2022-03-31

Added Forms and Form Responses.

2022-02-16

Added accept_entries_changes to Create a document.
Added information about new template versions.

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)
`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 retreiving 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 retreiving 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 [retreiving 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}