Introduction

Welcome to the Docue API.

To obtain API credentials contact [email protected].

Please note that you will need a company account in our systems in order to use the API.

Production environment

Base url for the production environment is https://api.docue.com/public.

Testing environment

Currently there is no separate testing environment. Test account credentials will be provided to you which can be used for pre-production testing.

Authentication

Docue API authenticates requests with API_TOKEN.

Get access token

API tokens can be requested from our customer service.

Each workspace can have multiple API tokens. Each token has same set up permissions and capabilities, but having different API tokens for different use cases may help in debugging and auditing.

API tokens are valid until revoked.

Currently there is no API for generating or managing new API tokens.

Prerequisites

You have got your API_TOKEN from our customer service.

Authenticate requests

Add the API token in authorization header as a bearer token to all of your requests

Authorization: Bearer API_TOKEN

Signing documents

Create a new document

curl -X "POST" "/documents" \
     -H 'Authorization: Bearer API_TOKEN' \
     -H 'Content-Type: multipart/form-data; charset=utf-8;' \
     -F "document[name]=Contract of Employment" \
     -F "document[language]=fi" \
     -F "document[creatorName]=John Doe" \
     -F "document[signingMethod]=canvas" \
     -F "document[basePdf][email protected]" \
     -F "signatures[0][type]=company" \
     -F "signatures[0][firstName]=John" \
     -F "signatures[0][lastName]=Doe" \
     -F "signatures[0][email][email protected]" \
     -F "signatures[0][phoneNumber]=503230002" \
     -F "signatures[0][countryCode]=358" \
     -F "signatures[0][companyTitle]=Docue Technologies Oy" \
     -F "signatures[0][companyIdent]=2724469-7"
     -F "signatures[0][redirectUrl]=https://docue.com"
     -F "signatures[1][type]=person" \
     -F "signatures[1][firstName]=Johhny" \
     -F "signatures[1][lastName]=Deo" \
     -F "signatures[1][redirectUrl]=https://docue.com" \
     -F "signingSettings[expiresAt]=2023-12-11" \
     -F "signingSettings[remindersStart]=2023-12-01" \
     -F "signingSettings[remindersEnd]=2023-12-10" \
     -F "signingSettings[remindersDuration]=P3D" \
     -F "signingSettings[message]=Please sign this" \

{
  "status": {
    "code": 201
  },
  "data": {
    "id": "O7rmNB",
    "templateId": "0ZAW3O",
    "companyId": "8Ov7RD",
    "clientId": null,
    "name": "Contract of Employment",
    "creatorName": "John Doe",
    "signingMethod": "canvas",
    "language": "fi",
    "stage": "created",
    "createdAt": "2018-10-25T12:29:58+00:00",
    "updatedAt": "2018-10-25T12:30:00+00:00",
    "signingSettings": {
      "expiresAt": "2023-12-11T00:00:00.000000Z",
      "remindersStart": "2023-12-01T00:00:00.000000Z",
      "remindersEnd": "2023-12-10T00:00:00.000000Z",
      "remindersDuration": "P3D",
      "message": "Please sign this"
    },
    "signatures": [
      {
        "id": "EDY2vZ",
        "createdAt": "2018-10-25T12:30:00+00:00",
        "updatedAt": "2018-10-25T12:30:00+00:00",
        "state": "waiting",
        "signedAt": null,
        "firstName": "John",
        "lastName": "Doe",
        "companyTitle": "Docue Technologies Oy",
        "companyIdent": "2724469-7",
        "type": "company",
        "email": "[email protected]",
        "phone": "+358503230002",
        "redirectUrl": "https://docue.com",
        "invitation": {
          "url": "https:\/\/app.docue.com\/s?...",
          "pin": "221074"
        }
      }
    ]
  }
}

This endpoint creates a new document with one or more signing parties. You can add up to 20 parties to a single document.

HTTP Request

POST /documents

Body

Parameter	Required	Description
document[name]	Yes	Name of the document. Will be visible to signing parties.
document[creatorName]	Yes	Name of the creator (invitating party) of the document. Will be visible to signing parties.
document[signingMethod]	Yes	One of [canvas,strong]. Canvas = "Electronic signature", strong = "Electronic signature with identity verification". Read more
document[basePdf]	Yes	PDF file to be signed. Maximum file size is 5MB.
document[language]	Yes	ISO 639-1 two letter language code. Supported values: [fi,en,sv]
signatures[0][type]	Yes	One of: [person,company]. Affects mostly for small usability things when signing. If type=company, companyTitle and companyIdent will be used.
signatures[0][firstName]	Yes	First name of the signee
signatures[0][lastName]	Yes	Last name of the signee
signatures[0][email]	No	Email of the signee. Required if email invitation will be used.
signatures[0][phoneNumber]	No	Phone of the signee. Required if SMS invitation will be used. Phone number without country code and leading zero in form of "503230002".
signatures[0][countryCode]	No	Country code of the signee. Required if SMS invitation will be used. Country code of the signee's phone number without leading + sign. In form of "358".
signatures[0][companyTitle]	No	Name of the signee's company
signatures[0][companyIdent]	No	Finnish business id of the signee's company. In form of "2724469-7"
signatures[0][redirectUrl]	No	Url where to redirect the signee after signing.
signatures[0][signingGroup]	No	Signing group number
folders	No	Array of folder ids. The document will be stored in these folders.
signingSettings[expiresAt]	No	Last date when document can be signed. Unsigned documents will be automatically cancelled. Must be after today.
signingSettings[message]	No	Message to the recipient. Used when sending signing invites with email. Used if signature itself doesn't have individualized message.
signingSettings[remindersStart]	No	Starting date for sending reminders. Must be in after today.
signingSettings[remindersEnd]	No	Ending date for sending reminders. Must be after remindersStart.
signingSettings[remindersDuration]	No	ISO 8601 repeating interval in days, e.g. "P3D"

To maintain backwards compatibility, signingSettings will not be present in the response if no values were configured.

Finalize a document

curl -X "POST" "/documents/<document-id>/finalize" \
     -H 'Authorization: Bearer API_TOKEN' \
     -H 'Content-Type: application/json; charset=utf-8'

{
  "status": {
    "code": 200
  },
  "data": {
    "id": "jZN4WO",
    "templateId": "0ZAW3O",
    "name": "Contract of Employment",
    "creatorName": "John Doe",
    "signingMethod": "canvas",
    "stage": "finalized",
    "createdAt": "2018-08-10T08:29:40+00:00",
    "updatedAt": "2018-08-10T08:31:55+00:00",
    "date": "2018-08-10T08:29:40+00:00"
  }
}

This endpoint finalizes specific document. You will need to finalize document before sending invitations. Document cannot be modified after it has been finalized.

HTTP Request

POST /documents/<document-id>/finalize

URL Parameters

Parameter	Description
document-id	The ID of the document to finalize

Get a document status

curl "/documents/<document-id>" \
     -H 'Authorization: Bearer API_TOKEN' \
     -H 'Content-Type: application/json; charset=utf-8'

{
  "status": {
    "code": 200
  },
  "data": {
    "id": "jZN4WO",
    "templateId": "0ZAW3O",
    "name": "Contract of Employment",
    "creatorName": "John Doe",
    "signingMethod": "canvas",
    "stage": "finalized",
    "createdAt": "2018-08-10T08:29:40+00:00",
    "updatedAt": "2018-08-10T08:31:55+00:00",
    "date": "2018-08-10T08:29:40+00:00"
  }
}

This endpoint returns status of the document.

HTTP Request

GET /documents/<document-id>

URL Parameters

Parameter	Description
document-id	The ID of the document to retrieve

Document stages

Status	Description
created	Document has been created and can be modified
finalized	Document cannot be modified and signing invites can be sent
completed	Document has been signed

Get signature statuses

curl "/documents/<document-id>/signatures" \
     -H 'Authorization: Bearer API_TOKEN' \
     -H 'Content-Type: application/json; charset=utf-8'

{
  "status": {
    "code": 200
  },
  "data": [
    {
      "id": "Ma2pnD",
      "createdAt": "2018-08-13T10:20:13+00:00",
      "updatedAt": "2018-08-13T10:20:13+00:00",
      "state": "waiting",
      "signedAt": null,
      "firstName": "John",
      "lastName": "Doe",
      "phoneNumber": "503230002",
      "countryCode": "358",
      "email": "[email protected]",
      "companyTitle": "Docue Technologies Oy",
      "companyIdent": "2724469-7"
    },
    {
      "id": "Ma2pnD",
      "createdAt": "2018-08-13T10:20:13+00:00",
      "updatedAt": "2018-08-13T10:20:13+00:00",
      "state": "completed",
      "signedAt": "2018-08-13T10:20:13+00:00",
      "firstName": "Johnny",
      "lastName": "Deo",
      "phoneNumber": null,
      "countryCode": null,
      "email": null,
      "companyTitle": null,
      "companyIdent": null
    }
  ]
}

This endpoint returns signatures attached to the document.

HTTP Request

GET /documents/<document-id>/signatures

URL Parameters

Parameter	Description
document-id	The ID of the document to retrieve the signatures

Signature statuses

Status	Description
waiting	Signature is created and ready to be fulfilled
completed	Signature has been fulfilled

Send signing invitation

curl -X "POST" "/documents/<document-id>/signatures/<signature-id>/invite" \
     -H 'Authorization: Bearer API_TOKEN' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d '{"deliveryChannel":"email","language":"fi"}'

{
  "status": {
    "code": 200
  }
}

This sends signing invitation to a signee.

HTTP Request

POST /documents/<document-id>/signatures/<signature-id>/invite

URL Parameters

Parameter	Description
document-id	The ID of the document to retrieve the signatures
signature-id	The ID of the signature

Body parameters

Parameter	Description
deliveryChannel	One of [email,sms]
language	One of [fi,en,sv,de]
message	Optional custom message to the recipient

Sending invitation from your system

Take invitation.url and invitation.pin from document data and send them to the recipient.

Fulfill signature via API

curl -X "POST" "/documents/<document-id>/signatures/<signature-id>/signature" \
     -H 'Authorization: Bearer API_TOKEN' \
     -H 'Content-Type: multipart/form-data; charset=utf-8;' \
     -F "signature="

{
  "status": {
    "code": 200
  }
}

This fulfills signature request. Can be used only if contract's signing method is canvas.

HTTP Request

POST /documents/<document-id>/signatures/<signature-id>/signature

URL Parameters

Parameter	Description
document-id	The ID of the document to retrieve the signatures
signature-id	The ID of the signature

Body parameters

Parameter	Description
signature	Image of the signature in PNG format. Should be exactly 300x150px or multiply of that (1-3x).

Retrieve signed PDF

curl "/documents/<document-id>/pdf" \
     -H 'Authorization: Bearer API_TOKEN'

<pdf binary>

Retrieve PDF file of signed document. Can be used only after contract's stage is completed.

HTTP Request

GET /documents/<document-id>/pdf

URL Parameters

Parameter	Description
document-id	The ID of the document to retrieve the signatures

Document builder

In order to use the document builder API, you will need the id of the template you want to use. Usually, the template will be tailored specifically for your use case so you will receive the id of the template from our customer service.

You can also create copies of existing templates, prefill them partially in document builder, and then fill the remaining fields and complete the document through the API.

There are three types of flows supported:

1. Fill all data using the API

Create a document based on a template
Put data based on template data structure
Finalize document to lock data and determine signing parties
Send signing invites
Receive signed document after all parties have signed the document

2. Fill partial data using the API and complete the document in builder

Create a document based on selected template
Fetch the data structure for the template
Put data based on template data structure
Create a document builder link and redirect user to builder for finalizing document and sending signing invites
Receive signed document via api after all parties have signed the document.

3. Prefill a user template and finalized it using the API

Create a prefilled template using the GUI
Create a document based on prefilled user template
Fill in rest of the required data based on document data structure
Finalize document to lock data and determine signing parties
Send signing invites
Receive signed document after all parties have signed the document

Retrieve user templates

curl "/user-templates" \
    -H 'Authorization: Bearer API_TOKEN'  \
    -H 'Content-Type: application/json; charset=utf-8'

{
  "status": {
    "code": 200,
    "total": 3
  },
  "data": [
    {
      "id": "ED5MDl",
      "createdAt": "2023-03-01T11:15:24+00:00",
      "updatedAt": "2023-03-01T11:15:55+00:00",
      "name": "My template",
      "contractName": "My template",
      "description": "Template description",
      "descriptionHtml": "<p>Template description</p>\n"
    },
    {
      "id": "5aP1O0",
      "createdAt": "2023-03-10T14:22:47+00:00",
      "updatedAt": "2023-03-10T14:22:53+00:00",
      "name": "My prefilled user template",
      "contractName": "My prefilled user template",
      "description": "Template description",
      "descriptionHtml": "<p>Template description</p>\n"
    },
    {
      "id": "JZnQDl",
      "createdAt": "2023-03-10T14:23:50+00:00",
      "updatedAt": "2023-03-10T14:24:02+00:00",
      "name": "Another user template",
      "contractName": "Another user template",
      "description": "Template description",
      "descriptionHtml": "<p>Template description</p>\n"
    }
  ]
}

Endpoint returns the account's customized and/or prefilled templates (user templates).

URL Query Parameters

Parameter	Required	Description
limit	No	Specify the maximum number of items returned by an API endpoint (defaults to 25)
offset	No	Specify the number of items that should be skipped from the beginning of the data set before retrieving the next set of items.

Retrieve available folders

curl "/folders" \
    -H 'Authorization: Bearer API_TOKEN'  \
    -H 'Content-Type: application/json; charset=utf-8'

{
    "status": {
        "code": 200
    },
    "data": [
        {
            "id": "KOqKWZ",
            "title": "Marriage and cohabitation",
            "groupTitle": "Asiakirjatyyppi"
        },
        {
            "id": "ED5YMD",
            "title": "Administration",
            "groupTitle": "Asiakirjatyyppi"
        }
    ]
}

Endpoint returns the workspace's available folders.

URL Query Parameters

None

Retrieve template data structure

curl "/templates/<template-id>/structure" \
     -H 'Authorization: Bearer API_TOKEN'

{
  "status": {
    "code": 200
  },
  "data": [
    {
      "id": "ZgM1zO",
      "name": "Perustiedot",
      "description": "",
      "position": 0,
      "items": [
        {
          "id": "Oqe7gO",
          "name": "osapuoli1",
          "title": " Osapuolet\/Laatija",
          "type": "entity",
          "description": "Sopimus sitoo sen allekirjoittaneita osapuolia.",
          "position": 3,
          "value": [],
          "default_value": null,
          "inherit_value": "",
          "meta": {
            "is_choosable": true,
            "is_multiple": true,
            "is_optional_phone": true,
            "is_optional_title": false,
            "is_optional_ident": true,
            "is_optional_company_ident": false,
            "is_optional_email": true,
            "is_optional_address": true,
            "is_warnable_phone": false,
            "is_warnable_title": false,
            "is_warnable_ident": false,
            "is_warnable_company_ident": false,
            "is_warnable_email": false,
            "is_warnable_address": false,
            "view_address": true,
            "view_email": true,
            "view_ident": true,
            "view_company_ident": true,
            "view_phone": true,
            "view_title": false,
            "types": [
              "person",
              "company"
            ],
            "types_default": "company",
            "is_signable": true,
            "credit_rating_enabled": true,
            "additional_fields": []
          },
          "couplings": "",
          "options": []
        }
      ]
    },
    {
      "id": "ZVwR8a",
      "name": "Sopimuksen sis\u00e4lt\u00f6",
      "description": "",
      "position": 1,
      "items": [
        {
          "id": "D5eKpD",
          "name": "sopimuksen_sisalto",
          "title": "Sopimuksen sis\u00e4lt\u00f6",
          "type": "editor",
          "description": "",
          "position": 8,
          "value": "",
          "default_value": "",
          "inherit_value": "",
          "meta": {
            "is_optional": true
          },
          "couplings": "",
          "options": []
        }
      ]
    },
    {
      "id": "aBJLEa",
      "name": "Paikka ja aika",
      "description": "",
      "position": 2,
      "items": [
        {
          "id": "Ow0LBD",
          "name": "paja",
          "title": " ",
          "type": "date_and_place",
          "description": "",
          "position": 2,
          "value": {
            "date": "07.11.2018",
            "city": ""
          },
          "default_value": "",
          "inherit_value": "",
          "meta": {
            "is_optional": true
          },
          "couplings": "",
          "options": []
        }
      ]
    }
  ]
}

This endpoint returns data structure for given template id. The data contains array of groups. Every group will contain array of items. You will need group id and item id later in patch data.

HTTP Request

GET /templates/<template-id>/structure

URL Parameters

Parameter	Required	Description
template-id	Yes	Id of the template

Create a new document based on template

curl -X "POST" "/documents" \
     -H 'Authorization: Bearer API_TOKEN' \
     -H 'Content-Type: application/json; charset=utf-8;' \
     -d '{ \
          "templateId": "2O4MQD",  \
          "document": {  \
            "name": "Contract of Employment",  \
            "creatorName": "John Doe",  \
            "signingMethod": "canvas",  \
            "language": "fi",  \
            "folders": ["KOqKWZ"],  \
            "signingSettings": {  \
              "expiresAt": "2023-12-16",  \
              "remindersStart": "2023-12-14",  \
              "remindersEnd": "2023-12-15",  \
              "remindersDuration": "P3D",  \
              "message": "Please sign this"  \
            }
          }
        }'

{
  "status": {
    "code": 201
  },
  "data": {
    "id": "O7rmNB",
    "templateId": "2O4MQD",
    "companyId": "8Ov7RD",
    "clientId": null,
    "name": "Contract of Employment",
    "creatorName": "John Doe",
    "signingMethod": "canvas",
    "language": "fi",
    "stage": "created",
    "createdAt": "2018-10-25T12:29:58+00:00",
    "updatedAt": "2018-10-25T12:30:00+00:00",
    "signatures": [],
    "signingSettings": {
      "expiresAt": "2023-12-11T00:00:00.000000Z",
      "remindersStart": "2023-12-01T00:00:00.000000Z",
      "remindersEnd": "2023-12-10T00:00:00.000000Z",
      "remindersDuration": "P3D",
      "message": "Please sign this"
    }
  }
}

This endpoint creates a new document based on custom template.

HTTP Request

POST /documents

Body

Parameter	Required	Description
templateId	Yes	Id of the template which will be used
templateType	No	Type of template: `template` or `userTemplate`. Defaults to `template`
document[name]	Yes	Name of the document. Will be visible to signing parties.
document[creatorName]	Yes	Name of the creator (invitating party) of the document. Will be visible to signing parties.
document[signingMethod]	Yes	One of [canvas,strong]. canvas = "Electronic signature", strong = "Electronic signature with identity verification". Read more
document[language]	Yes	ISO 639-1 two letter language code. Supported values: [fi,en,sv]
folders	No	Array of folder ids. The document will be stored in these folders.
signingSettings[expiresAt]	No	Last date when document can be signed. Unsigned documents will be automatically cancelled. Must be after today.
signingSettings[message]	No	Message to the recipient. Used when sending signing invites with email. Used if signature itself doesn't have individualized message.
signingSettings[remindersStart]	No	Starting date for sending reminders. Must be after today-
signingSettings[remindersEnd]	No	* Ending date for sending reminders. ;ust be after remindersStart.
signingSettings[remindersDuration]	No	ISO 8601 repeating interval in days, e.g. "P3D"

To maintain backwards compatibility, signingSettings will not be present in the response if no values were configured.

Get document data

curl "/documents/<document-id>/data" \
     -H 'Authorization: Bearer API_TOKEN'

{
  "status": {
    "code": 200
  },
  "data": {
    "groups": [
      {
        "hash": "Oo4EqD",
        "title": "Osapuolet",
        "description": "",
        "items": [
          {
            "hash": "DMLlAA",
            "title": "Myyj\u00e4",
            "name": "myyja",
            "description": "",
            "couplings": "",
            "type": "entity",
            "meta": {
              "is_choosable": false,
              "is_multiple": false,
              "is_optional_phone": false,
              "is_optional_title": false,
              "is_optional_ident": false,
              "is_optional_company_ident": false,
              "is_optional_email": false,
              "is_optional_address": false,
              "is_warnable_phone": false,
              "is_warnable_title": false,
              "is_warnable_ident": false,
              "is_warnable_company_ident": false,
              "is_warnable_email": false,
              "is_warnable_address": false,
              "view_address": false,
              "view_email": false,
              "view_ident": false,
              "view_company_ident": true,
              "view_phone": false,
              "view_title": false,
              "types": [
                "company"
              ],
              "types_default": "company",
              "is_signable": true,
              "credit_rating_enabled": true,
              "additional_fields": []
            },
            "inherit_value": "",
            "default_value": "",
            "value": [
              {
                "first_name": "John",
                "last_name": "Doe",
                "type": "company",
                "title": "",
                "company_title": "Docue Technologies Oy",
                "company_hash": "gD6jDw",
                "client_hash": "gD6jDw",
                "city": "",
                "address": "",
                "company_ident": "2433295-8",
                "email": "",
                "ident": "",
                "country_code": "358",
                "phone_number": "",
                "needs_signature": true,
                "post_code": ""
              }
            ],
            "is_valid": true,
            "has_warning": false
          },
          {
            "hash": "a2pkJd",
            "title": "Ostaja",
            "name": "ostaja",
            "description": "",
            "couplings": "",
            "type": "entity",
            "meta": {
              "is_choosable": false,
              "is_multiple": false,
              "is_optional_phone": false,
              "is_optional_title": false,
              "is_optional_ident": false,
              "is_optional_company_ident": false,
              "is_optional_email": false,
              "is_optional_address": false,
              "is_warnable_phone": false,
              "is_warnable_title": false,
              "is_warnable_ident": false,
              "is_warnable_company_ident": false,
              "is_warnable_email": false,
              "is_warnable_address": false,
              "view_address": false,
              "view_email": false,
              "view_ident": false,
              "view_company_ident": true,
              "view_phone": false,
              "view_title": false,
              "types": [
                "person",
                "company"
              ],
              "types_default": "company",
              "is_signable": true,
              "credit_rating_enabled": true,
              "additional_fields": []
            },
            "inherit_value": "",
            "default_value": "",
            "value": [
              {
                "first_name": "John",
                "last_name": "Doe",
                "type": "company",
                "title": "",
                "company_title": "Docue Technologies Oy",
                "company_hash": "gD6jDw",
                "client_hash": "gD6jDw",
                "city": "",
                "address": "",
                "company_ident": "2433295-8",
                "email": "",
                "ident": "",
                "country_code": "358",
                "phone_number": "",
                "needs_signature": true,
                "post_code": ""
              }
            ],
            "is_valid": true,
            "has_warning": false
          }
        ],
        "is_valid": true,
        "has_warning": false
      }
    ],
    "signature_groups": [],
    "attachments": {
      "enabled": true,
      "files": []
    },
    "folders": ["KOqKWZ"],
    "meta": {
      "electronic_sign_allowed": true,
      "use_cover": false,
      "logo_id": null,
      "footer_left": null
    }
  }
}

This endpoint returns document data.

HTTP Request

GET /documents/<document-id>/data

Patch document data

curl -X "PATCH" "/documents/<document-id>/data" \
     -H 'Authorization: Bearer API_TOKEN' \
     -H 'Content-Type: application/json; charset=utf-8;' \
     -d '{ \
          "items": [ \
            { \
              "groupId": "DMQXkD", \
              "itemId": "Z8owLx", \
              "itemValue": [ \
                {  \
                  "first_name": "John", \
                  "last_name": "Doe", \
                  "company_title": "CTO", \
                  "city": "", \
                  "address": "", \
                  "company_ident": "", \
                  "email": "[email protected]", \
                  "ident": "", \
                  "country_code": "", \
                  "phone_number": "", \
                  "type": "person" \
                } \
              ] \
            }, \
            { \
              "groupId": "112MDD", \
              "itemId": "2O4MQD", \
              "itemValue": "Test content here" \
            } \
          ] \
        }'

{
  "status": {
    "code": 200
  },
  "data": {
    "groups": [
      {
        "hash": "Oo4EqD",
        "title": "Osapuolet",
        "description": "",
        "items": [
          {
            "hash": "DMLlAA",
            "title": "Myyj\u00e4",
            "name": "myyja",
            "description": "",
            "couplings": "",
            "type": "entity",
            "meta": {
              "is_choosable": false,
              "is_multiple": false,
              "is_optional_phone": false,
              "is_optional_title": false,
              "is_optional_ident": false,
              "is_optional_company_ident": false,
              "is_optional_email": false,
              "is_optional_address": false,
              "is_warnable_phone": false,
              "is_warnable_title": false,
              "is_warnable_ident": false,
              "is_warnable_company_ident": false,
              "is_warnable_email": false,
              "is_warnable_address": false,
              "view_address": false,
              "view_email": false,
              "view_ident": false,
              "view_company_ident": true,
              "view_phone": false,
              "view_title": false,
              "types": [
                "company"
              ],
              "types_default": "company",
              "is_signable": true,
              "credit_rating_enabled": true,
              "additional_fields": []
            },
            "inherit_value": "",
            "default_value": "",
            "value": [
              {
                "first_name": "John",
                "last_name": "Doe",
                "type": "company",
                "title": "",
                "company_title": "Docue Technologies Oy",
                "company_hash": "gD6jDw",
                "client_hash": "gD6jDw",
                "city": "",
                "address": "",
                "company_ident": "2433295-8",
                "email": "",
                "ident": "",
                "country_code": "358",
                "phone_number": "",
                "needs_signature": true,
                "post_code": ""
              }
            ],
            "is_valid": true,
            "has_warning": false
          },
          {
            "hash": "a2pkJd",
            "title": "Ostaja",
            "name": "ostaja",
            "description": "",
            "couplings": "",
            "type": "entity",
            "meta": {
              "is_choosable": false,
              "is_multiple": false,
              "is_optional_phone": false,
              "is_optional_title": false,
              "is_optional_ident": false,
              "is_optional_company_ident": false,
              "is_optional_email": false,
              "is_optional_address": false,
              "is_warnable_phone": false,
              "is_warnable_title": false,
              "is_warnable_ident": false,
              "is_warnable_company_ident": false,
              "is_warnable_email": false,
              "is_warnable_address": false,
              "view_address": false,
              "view_email": false,
              "view_ident": false,
              "view_company_ident": true,
              "view_phone": false,
              "view_title": false,
              "types": [
                "person",
                "company"
              ],
              "types_default": "company",
              "is_signable": true,
              "credit_rating_enabled": true,
              "additional_fields": []
            },
            "inherit_value": "",
            "default_value": "",
            "value": [
              {
                "first_name": "John",
                "last_name": "Doe",
                "type": "company",
                "title": "",
                "company_title": "Docue Technologies Oy",
                "company_hash": "gD6jDw",
                "client_hash": "gD6jDw",
                "city": "",
                "address": "",
                "company_ident": "2433295-8",
                "email": "",
                "ident": "",
                "country_code": "358",
                "phone_number": "",
                "needs_signature": true,
                "post_code": ""
              }
            ],
            "is_valid": true,
            "has_warning": false
          }
        ],
        "is_valid": true,
        "has_warning": false
      }
    ],
    "signature_groups": [],
    "attachments": {
      "enabled": true,
      "files": []
    },
    "meta": {
      "electronic_sign_allowed": true,
      "use_cover": false,
      "logo_id": null,
      "footer_left": null
    }
  }
}

This endpoint patches document data with provided data.

HTTP Request

PATCH /documents/<document-id>/data

Body

Parameter	Required	Description
items[0][itemId]	Yes	Id of the item whose value will be updated
items[0][groupId]	Yes	Id of the group where the item is
items[0][itemValue]	Yes	Value of the item. Format is based on item type

Open document builder

curl -X "POST" "/documents/<document-id>/open-builder" \
     -H 'Authorization: Bearer API_TOKEN' \
     -H 'Content-Type: multipart/form-data; charset=utf-8;'

{
  "status":{
    "code":200
  },
  "data": {
    "url":"https://app.docue.com/builder/edit?cId=XXXX&pId=XXXX
  }
}

This endpoint returns url where to redirect user for filling out the document.

HTTP Request

POST /documents/<document-id>/open-builder

Finalize a document with custom template

curl -X "POST" "/documents/<document-id>/finalize" \
     -H 'Authorization: Bearer API_TOKEN' \
     -H 'Content-Type: application/json; charset=utf-8;'

{
  "status": {
    "code": 200
  },
  "data": {
    "id": "jZN4WO",
    "templateId": "0ZAW3O",
    "name": "Contract of Employment",
    "creatorName": "John Doe",
    "signingMethod": "canvas",
    "stage": "finalized",
    "createdAt": "2018-08-10T08:29:40+00:00",
    "updatedAt": "2018-08-10T08:31:55+00:00",
    "date": "2018-08-10T08:29:40+00:00"
  }
}

This endpoint finalizes specific document. The signing parties will be determined automatically based on document data. You will need to finalize document before sending invitations. Document cannot be modified after it has been finalized.

If there are no signing parties based on document data, document will be automatically completed and the final document can be retrieved.

HTTP Request

POST /documents/<document-id>/finalize

URL Parameters

Parameter	Description
document-id	The ID of the document to finalize

Get status for document with custom template

curl "/documents/<document-id>" \
     -H 'Authorization: Bearer API_TOKEN' \
     -H 'Content-Type: application/json; charset=utf-8'

{
  "status": {
    "code": 200
  },
  "data": {
    "id": "jZN4WO",
    "templateId": "0ZAW3O",
    "name": "Contract of Employment",
    "creatorName": "John Doe",
    "signingMethod": "canvas",
    "stage": "finalized",
    "createdAt": "2018-08-10T08:29:40+00:00",
    "updatedAt": "2018-08-10T08:31:55+00:00",
    "date": "2018-08-10T08:29:40+00:00"
  }
}

This endpoint returns status of the document.

HTTP Request

GET /documents/<document-id>

URL Parameters

Parameter	Description
document-id	The ID of the document to retrieve

Document stages

Status	Description
created	Document has been created and can be modified
finalized	Document cannot be modified and signing invites can be sent
completed	Document has been signed

Get signature statuses for document with custom template

curl "/documents/<document-id>/signatures" \
     -H 'Authorization: Bearer API_TOKEN' \
     -H 'Content-Type: application/json; charset=utf-8'

{
  "status": {
    "code": 200
  },
  "data": [
    {
      "id": "Ma2pnD",
      "createdAt": "2018-08-13T10:20:13+00:00",
      "updatedAt": "2018-08-13T10:20:13+00:00",
      "state": "waiting",
      "signedAt": null,
      "firstName": "John",
      "lastName": "Doe",
      "phoneNumber": "503230002",
      "countryCode": "358",
      "email": "[email protected]",
      "companyTitle": "Docue Technologies Oy",
      "companyIdent": "2724469-7"
    },
    {
      "id": "Ma2pnD",
      "createdAt": "2018-08-13T10:20:13+00:00",
      "updatedAt": "2018-08-13T10:20:13+00:00",
      "state": "completed",
      "signedAt": "2018-08-13T10:20:13+00:00",
      "firstName": "Johnny",
      "lastName": "Deo",
      "phoneNumber": null,
      "countryCode": null,
      "email": null,
      "companyTitle": null,
      "companyIdent": null
    }
  ]
}

This endpoint returns signatures attached to the document. Signatures will be generated automatically based on document data at the time of finalization.

HTTP Request

GET /documents/<document-id>/signatures

URL Parameters

Parameter	Description
document-id	The ID of the document to retrieve the signatures

Signature statuses for document with custom template

Status	Description
waiting	Signature is created and ready to be fulfilled
completed	Signature has been fulfilled

Send signing invitation for document with custom template

curl -X "POST" "/documents/<document-id>/signatures/<signature-id>/invite" \
     -H 'Authorization: Bearer API_TOKEN' \
     -H 'Content-Type: application/json; charset=utf-8;' \
     -d '{ \
          "deliveryChannel”: "email", \
          "language": "fi" \
        }'

{
  "status": {
    "code": 200
  }
}

This sends signing invitation to a signee.

HTTP Request

POST /documents/<document-id>/signatures/<signature-id>/invite

URL Parameters

Parameter	Description
document-id	The ID of the document to retrieve the signatures
signature-id	The ID of the signature

Body parameters

Parameter	Description
deliveryChannel	One of [email,sms]
language	One of [fi,en]

Sending invitation from your system for document with custom template

Take invitation.url and invitation.pin from document data and send them to the recipient.

Fulfill signature via API for document with custom template

curl -X "POST" "/documents/<document-id>/signatures/<signature-id>/signature" \
     -H 'Authorization: Bearer API_TOKEN' \
     -H 'Content-Type: multipart/form-data; charset=utf-8;' \
     -F "signature="

{
  "status": {
    "code": 200
  }
}

This fulfills signature request. Can be used only if contract's signing method is canvas.

HTTP Request

POST /documents/<document-id>/signatures/<signature-id>/signature

URL Parameters

Parameter	Description
document-id	The ID of the document to retrieve the signatures
signature-id	The ID of the signature

Body parameters

Parameter	Description
signature	Image of the signature in PNG format. Should be exactly 300x150px or multiply of that (1-3x).

Retrieve signed PDF for document with custom template

curl "/documents/<document-id>/pdf" \
     -H 'Authorization: Bearer API_TOKEN'

<pdf binary>

Retrieve PDF file of signed document. Can be used only after contract's stage is completed.

HTTP Request

GET /documents/<document-id>/pdf

URL Parameters

Parameter	Description
document-id	The ID of the document to retrieve the signatures

Webhooks

Create a new webhook listener

curl -X "POST" "/webhooks" \
     -H 'Authorization: Bearer API_TOKEN' \
     -H 'Content-Type: application/json; charset=utf-8;' \
     -d '{ \
        "webhook": {
          "url":"https://webhook.site/bd192ead-1d46-4ba6-942b-230f77b5d0bb", \
          "description":"Signature handler", \
          "retry":1, \
          "active":1, \
          "scope":[
            "signature-submitted", \
            "document-completed" \
          ] \
        } \
     }'

{
  "status": {
    "code": 201
  },
  "data": {
    "id": "0ZABao",
    "createdAt": "2018-10-25T12:43:26+00:00",
    "updatedAt": "2018-10-25T12:43:26+00:00",
    "url": "https:\/\/webhook.site\/bd192ead-1d46-4ba6-942b-230f77b5d0bb",
    "description": "Signature handler",
    "scope": [
      "signature-submitted",
      "document-completed"
    ],
    "retry": true,
    "active": true,
    "messagesCount": 0
  }
}

This endpoint creates a new webhook listener.

HTTP Request

POST /webhooks

Body

Parameter	Required	Description
webhook[url]	Yes	URL of the service which will handle incoming POST requests.
webhook[description]	Yes	Description for the handler for your internal use.
webhook[retry]	Yes	Boolean value. If true, our webhook service will try again if the status code of the response to webhook is not 200.
webhook[active]	Yes	Boolean value. If the listener is active or not. Only active handlers will be called in case of event.
webhook[scope][0]	Yes	Array of scopes. Supported values: "signature-submitted", "document-completed"

Test webhook

curl -X "POST" "/webhooks/0ZABao/test" \
     -H 'Authorization: Bearer API_TOKEN'

{
  "status": {
    "code": 200
  }
}

Our system will call your webhook handler after calling this endpoint.

HTTP Request

POST /webhooks/<webhook-id>/test

URL Parameters

Parameter	Description
webhook-id	The ID of the webhook to test

List webhooks

curl "/webhooks" \
     -H 'Authorization: Bearer API_TOKEN'

{
  "status": {
    "code": 200,
    "total": 2
  },
  "data": [
    {
      "id": "0ZABao",
      "createdAt": "2018-10-25T12:43:26+00:00",
      "updatedAt": "2018-10-25T12:43:26+00:00",
      "url": "https:\/\/webhook.site\/bd192ead-1d46-4ba6-942b-230f77b5d0bb",
      "description": "Signature handler",
      "scope": [
        "signature-submitted",
        "document-completed"
      ],
      "retry": true,
      "active": true,
      "messagesCount": 1
    }
  ]
}

This endpoint lists all added webhook handlers.

HTTP Request

GET /webhooks

Delete webhook

curl -X "DELETE" "/webhooks/0ZABao" \
     -H 'Authorization: Bearer API_TOKEN'

{
  "status": {
    "code": 200
  }
}

This endpoint deleted webhook listener.

HTTP Request

DELETE /webhooks/<webhook-id>

URL Parameters

Parameter	Description
webhook-id	The ID of the webhook to delete

Available scopes

Available webhook scopes are signature-submitted and document-completed

{
  "type": "signature-submitted",
  "data": {
    "signature": {
      "id": "8OvPZK",
      "createdAt": "2018-07-30T12:50:17+00:00",
      "updatedAt": "2018-08-03T13:39:03+00:00",
      "state": "completed",
      "signedAt": null,
      "firstName": "John",
      "lastName": "Smith",
      "companyTitle": null,
      "companyIdent": null
    },
    "document": {
      "id": "Ma2Jna",
      "templateId": "Ma2naY",
      "name": "Document #1",
      "creatorName": "John Smith",
      "signingMethod": "canvas",
      "stage": "finalized",
      "createdAt": "2018-07-27T12:01:26+00:00",
      "updatedAt": "2018-08-03T13:27:39+00:00",
      "date": "2018-07-27T12:01:26+00:00"
    }
  }
}

{
  "type": "document-completed",
  "data": {
    "document": {
      "id": "a0l9qK",
      "templateId": "JZnq6D",
      "companyId": "8Ov7RD",
      "clientId": "Ma2Jna",
      "name": "Oma sopimus",
      "creatorName": "Docue Technologies Oy (api)",
      "signingMethod": "canvas",
      "language": "fi",
      "stage": "completed",
      "createdAt": "2018-10-25T13:15:34+00:00",
      "updatedAt": "2018-10-25T13:22:12+00:00"
    }
  }
}