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

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 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
links Object The links associated with the Document on the Avvoka Platform
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 Participan 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 Participan belongs
role_id String The ID of the Document Party Role to which the Participan 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 tmL********TC9S4Vti2e0ShFCLbyAEx" \
  --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"
      },
      "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 `d
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 tmL********TC9S4Vti2e0ShFCLbyAEx" \
  --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"
    },
    "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 tmL********TC9S4Vti2e0ShFCLbyAEx" \
  --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",
    "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"
    },
    "created_at": "2021-05-02T10:32:54Z",
    "updated_at": "2021-05-02T10:33:14Z",
    "signed_at": null
  }
}

Creates a new Profile in an Organisation.

HTTP Request

POST /api/v1/documents

Request body parameters

Attribute Type Description
template_id (required) Number The ID of the associated Template 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.
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" }

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 tmL********TC9S4Vti2e0ShFCLbyAEx" \
  --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"
    }
  }
}

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": "approve"
      }
    ],
    "entries": {
      "employee_name": "Louis"
    },
    "created_at": "2021-05-02T10:32:54Z",
    "updated_at": "2021-05-02T10:33:14Z",
    "signed_at": null
  }
}

Updates an existing Document in your Organisation.

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
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" }

Export a Document

Curl request example for saving a Document export into a file

curl --request GET \
  --header "Authorization: Bearer tmL********TC9S4Vti2e0ShFCLbyAEx" \
  --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 tmL********TC9S4Vti2e0ShFCLbyAEx" \
  --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}

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 tmL********TC9S4Vti2e0ShFCLbyAEx" \
  --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 tmL********TC9S4Vti2e0ShFCLbyAEx" \
  --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 Templates 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 tmL********TC9S4Vti2e0ShFCLbyAEx" \
  --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 tmL********TC9S4Vti2e0ShFCLbyAEx" \
  --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 tmL********TC9S4Vti2e0ShFCLbyAEx" \
  --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 tmL********TC9S4Vti2e0ShFCLbyAEx" \
  --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 tmL********TC9S4Vti2e0ShFCLbyAEx" \
  --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 tmL********TC9S4Vti2e0ShFCLbyAEx" \
  --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 tmL********TC9S4Vti2e0ShFCLbyAEx" \
  --header "Content-Type: application/json" \
  "https://<your-instance-domain>/api/v1/documents/43881" 

Deletes an existing Profile Membership.

HTTP Request

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

Templates

The Template object

The Template object represents a Document Template in your Organisation.

Attribute Type Description
id Number The ID of the Template
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 or question 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 only for the form input

List all Templates

Curl request example

curl --request GET \
  --header "Authorization: Bearer tmL********TC9S4Vti2e0ShFCLbyAEx" \
  --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": []
        }
      ],
      "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 retreiving a specific Template.

HTTP Request

GET /api/v1/templates

Query parameters

Parameter Description
name Filter Templates by name
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
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 tmL********TC9S4Vti2e0ShFCLbyAEx" \
  --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": []
      }
    ],
    "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}

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
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 tmL********TC9S4Vti2e0ShFCLbyAEx" \
  --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",
      "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 email
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 tmL********TC9S4Vti2e0ShFCLbyAEx" \
  --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",
    "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 tmL********TC9S4Vti2e0ShFCLbyAEx" \
  --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",
    "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 tmL********TC9S4Vti2e0ShFCLbyAEx" \
  --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 tmL********TC9S4Vti2e0ShFCLbyAEx" \
  --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}