# Document API

Users can create a document based on a template by filling out a form. These documents are stored by fillthedoc and given a 32 byte unique (unguessable) hash as identifier. The document can only be fetched using this hash as JSON data, HTML or PDF.

## Create a document

<mark style="color:green;">`POST`</mark> `https://fillthedoc.com/api/documents`

Create a new document based on a template.

#### Headers

| Name         | Type   | Description        |
| ------------ | ------ | ------------------ |
| Content-Type | string | "application/json" |

#### Request Body

| Name     | Type   | Description                                               |
| -------- | ------ | --------------------------------------------------------- |
| template | string | Template id or reference                                  |
| values   | object | Data to prefill the document                              |
| callback | string | Webhook URL that's called when the document is filled out |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "id": "o00wocs44sksk0008kw0kc08cwcs0s8sc0k8owgggc0g0os8swg400c00gc8cosg",
    "template": {
        "version": "2019-08-19T22:07:51",
        "id": "43448bea-42ad-4c68-9962-2475bec7ecec",
        "reference": "cao-employee",
        "published": true,
        "name": "CAO Employee",
        "description": "CAO for employees in the IT industry",
        "categories": [],
        "folder": "hr/contracts",
        "disclaimer": "",
        "locale": "nl_NL",
        "section": "",
        "last_modified": {
            "user": null,
            "date": "2019-08-19T22:07:51+00:00",
            "etag": null
        },
        "import_master_date": null,
        "type": "template"
    },
    "values": {
        "cao_name": "CAO Employee Pension",
        "pension_fund": "P.A."
    },
    "created": {
        "user_id": "a29bf252685445cdc66e1be76403304a296645e7e1d5cf27ff5c7cb8cf4d7c00",
        "date": "2019-08-27T00:52:10+00:00"
    },
    "locale": "nl_NL",
    "step": null,
    "hash": null,
    "links": {
        "edit": "https://fillthedoc.io/jasny/o00wocs44sksk0008kw0kc08cwcs0s8sc0k8owgggc0g0os8swg400c00gc8cosg",
        "pdf": "https://www.fillthedoc.com/api/documents/o00wocs44sksk0008kw0kc08cwcs0s8sc0k8owgggc0g0os8swg400c00gc8cosg.pdf",
        "html": "https://www.fillthedoc.com/api/documents/o00wocs44sksk0008kw0kc08cwcs0s8sc0k8owgggc0g0os8swg400c00gc8cosg.html"
    }
}
```

{% endtab %}
{% endtabs %}

{% code title="Example request body" %}

```
{
    "template": "cao-employee",
    "values": {
        "cao_name": "CAO Employee Pension",
        "pension_fund": "P.A."
    }
}
```

{% endcode %}

The `template` property is required and can be a template id or template reference. When creating a new document, the latest version of the template is always used. Only published templates can be used to create a document.

The document can be prefilled by adding a `values` property in the request. The data should match the structure defined by the template's form.

The response contains an `edit_url` property. If the end user needs to complete the information for the document, send him to this URL. The document id is a unique and unguessable 32 bit random value. The user doesn't need any information other than this URL.

If a `callback` URL was specified when creating the document, it will be called when the end user completes filling out the document. The request body is a JSON representation of the document and similar to the response body when creating a document.

The document will automatically be locked after the user has completed the form. You may update the document to unlock it.

## Retrieve a document

<mark style="color:blue;">`GET`</mark> `https://fillthedoc.com/api/documents/{id}`

Get a document as PDF, HTML or JSON.

#### Path Parameters

| Name | Type   | Description                 |
| ---- | ------ | --------------------------- |
| id   | string | Unique (32 bit) document id |

#### Headers

| Name   | Type   | Description                                          |
| ------ | ------ | ---------------------------------------------------- |
| Accept | string | "application/pdf", "text/html" or "application/json" |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "id": "o00wocs44sksk0008kw0kc08cwcs0s8sc0k8owgggc0g0os8swg400c00gc8cosg",
    "template": {
        "version": "2019-08-19T22:07:51",
        "id": "43448bea-42ad-4c68-9962-2475bec7ecec",
        "reference": "cao-employee",
        "published": true,
        "name": "CAO Employee",
        "description": "CAO for employees in the IT industry",
        "categories": [],
        "folder": "hr/contracts",
        "disclaimer": "",
        "locale": "nl_NL",
        "section": "",
        "last_modified": {
            "user": null,
            "date": "2019-08-19T22:07:51+00:00",
            "etag": null
        },
        "import_master_date": null,
        "type": "template"
    },
    "values": {
        "cao_name": "CAO Employee Pension",
        "pension_fund": "P.A.",
        "first_name": "John",
        "last_name": "Doe",
        "address": "Dam 1",
        "postalcode": "1012JS",
        "city": "Amsterdam"
    },
    "created": {
        "user_id": "a29bf252685445cdc66e1be76403304a296645e7e1d5cf27ff5c7cb8cf4d7c00",
        "date": "2019-08-27T00:52:10+00:00"
    },
    "last_update": {
        "user": null,
        "date": "2019-08-27T00:59:21+00:00"
    },
    "locale": "nl_NL",
    "step": "finished",
    "hash": "39415add5f65a556772bf3490a6cb49b7dfe110ea4333bfb412981b6a3871c56",
    "links": {
        "edit": "https://fillthedoc.io/jasny/o00wocs44sksk0008kw0kc08cwcs0s8sc0k8owgggc0g0os8swg400c00gc8cosg",
        "pdf": "https://www.fillthedoc.com/api/documents/o00wocs44sksk0008kw0kc08cwcs0s8sc0k8owgggc0g0os8swg400c00gc8cosg.pdf",
        "html": "https://www.fillthedoc.com/api/documents/o00wocs44sksk0008kw0kc08cwcs0s8sc0k8owgggc0g0os8swg400c00gc8cosg.html"
    }
}
```

{% endtab %}
{% endtabs %}

Use the `Accept` header to specify if you'd like to receive the document data and metadata as JSON or just contents as PDF or HTML.

Do not send the URL for generating the PDF directly to the end user. It will not be accessible without the API key. Instead, use the API to download the PDF, store it locally, and allow the user to download it from your system.

## Update a document

<mark style="color:green;">`POST`</mark> `https://fillthedoc.com/api/documents/{id}`

Update the document data or unlock the document.

#### Path Parameters

| Name | Type   | Description                 |
| ---- | ------ | --------------------------- |
| id   | string | Unique (32 bit) document id |

#### Headers

| Name                | Type   | Description                 |
| ------------------- | ------ | --------------------------- |
| If-Unmodified-Since | string | Used for optimistic locking |

#### Request Body

| Name   | Type   | Description                                 |
| ------ | ------ | ------------------------------------------- |
| step   | string | Step the user is on or "finished" when done |
| values | object | Data of the document                        |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "id": "o00wocs44sksk0008kw0kc08cwcs0s8sc0k8owgggc0g0os8swg400c00gc8cosg",
    "template": {
        "version": "2019-08-19T22:07:51",
        "id": "43448bea-42ad-4c68-9962-2475bec7ecec",
        "reference": "cao-employee",
        "published": true,
        "name": "CAO Employee",
        "description": "CAO for employees in the IT industry",
        "categories": [],
        "folder": "hr/contracts",
        "disclaimer": "",
        "locale": "nl_NL",
        "section": "",
        "last_modified": {
            "user": null,
            "date": "2019-08-19T22:07:51+00:00",
            "etag": null
        },
        "import_master_date": null,
        "type": "template"
    },
    "values": {
        "cao_name": "CAO Employee Pension",
        "pension_fund": "P.A.",
        "first_name": "John",
        "last_name": "Doe",
        "address": "Dam 1",
        "postalcode": "1012JS",
        "city": "Amsterdam",
        "country": "Netherlands"
    },
    "created": {
        "user_id": "a29bf252685445cdc66e1be76403304a296645e7e1d5cf27ff5c7cb8cf4d7c00",
        "date": "2019-08-27T00:52:10+00:00"
    },
    "last_update": {
        "user": "a29bf252685445cdc66e1be76403304a296645e7e1d5cf27ff5c7cb8cf4d7c00",
        "date": "2019-08-27T01:03:52+00:00"
    },
    "locale": "nl_NL",
    "step": null,
    "hash": null,
    "links": {
        "edit": "https://fillthedoc.io/jasny/o00wocs44sksk0008kw0kc08cwcs0s8sc0k8owgggc0g0os8swg400c00gc8cosg",
        "pdf": "https://www.fillthedoc.com/api/documents/o00wocs44sksk0008kw0kc08cwcs0s8sc0k8owgggc0g0os8swg400c00gc8cosg.pdf",
        "html": "https://www.fillthedoc.com/api/documents/o00wocs44sksk0008kw0kc08cwcs0s8sc0k8owgggc0g0os8swg400c00gc8cosg.html"
    }
}
```

{% endtab %}
{% endtabs %}

{% code title="Example request body" %}

```
{
    "step": null,
    "values": {
        "country": "Netherlands"
    }
}
```

{% endcode %}

Documents are automatically be locked after the user has completed the form. This is indicated by the `step` property which is set to `finished`. Set the `step` property to `null` to allow the user to modify the document. The edit url remains unchanged. Once the end user is finished, the webhook (specified as `callback` when the document was created) will be called again.

It's possible to modify the data, prior to generating the PDF or HTML document, via the `values` property. The values are merged, even for nested data, as specified by [RFC 7396](https://tools.ietf.org/html/rfc7396) *(regardless of the `Content-Type`)*.

You should send an `If-Unmodified-Since` header for [optimistic locking](http://en.wikipedia.org/wiki/Optimistic_concurrency_control). This prevents overwriting the document data, which may have been modified by the user is the document is not locked.

## Delete a document

<mark style="color:red;">`DELETE`</mark> `https://fillthedoc.com/api/documents/{id}`

Delete a document from fillthedoc.

#### Path Parameters

| Name | Type   | Description                 |
| ---- | ------ | --------------------------- |
| id   | string | Unique (32 bit) document id |

{% tabs %}
{% tab title="204 " %}

```
```

{% endtab %}
{% endtabs %}