# Getting started fillthedoc is an advanced document engine, powered by JavaScript ## Step 1. Create a template The template consists of a form, which may be filled out by the end user, and text content. The content contains placeholders that are filled with the data of the form. More advanced functions can be used, like expressions and formatting. {% content-ref url="/pages/-LnFvB4DL3UxzFhCLvrp" %} [Templates](/templates) {% endcontent-ref %} ## Step 2. Create a document Use the API to create a new document based on a template. Send some initial data and allow the end user to fill out the rest. You may specify a callback URL to let your system know that the user is done. {% content-ref url="/pages/-LnFfjWafc59kCqSpzEj" %} [Document API](/api/document-api) {% endcontent-ref %} ## Step 3. Download the document and user data Once the user has filled out the form, use the API to generate a PDF and fetch the data so it can be processed. # Templates A template consists of a step-by-step list, the form, and the text itself. In the text is the final document in which all fields are programmed. ## Templates ![](/files/-LoVEAzqLSHleIp2wMhC) Here you can view and edit all your templates. You can create folders where templates can be dragged to in order to help sorting them. To make a new template, you can click on the green 'new' button. A template will then be made in the map that's open. ![](/files/-LoVMP6bJr-8jHq8-n_g) The template page can be divide in 3 parts On the left are all the different kinds of fields that can be added to a step. Below that are standard fields as created by the user. (See #FillTheDoc UI for info on standard fields) In the middle part, you can see the Form with all created steps and fields. Steps can be minimized, edited and deleted. You can add a field by dragging it to one of the created steps. (See #Form) In the right part of the screen, you can see the content. Here you can add all the text and design your template to your liking. Make sure you click on save from time to time. You can view your document by clicking on view, this will show the document in its final form and allows you to fill in your fields. You can go back to editing by clicking on edit again. (To see how to add your dynamic fields in the text, check out #Content) When you're done editting your template and are ready to use it, click on the green 'publish' button. ![](/files/-LoVOiz8OBejsFiEe2AJ) ## Using an existing document as template In order to digitize an existing document, it must first be converted to plain text, which is copied to an empty template. The layout needs to be reapplied manually in fillthedoc. After the layout, the ‘programming’ of the fields and options begins. This is where the document is made dynamic so that it is usable in the software. # Glossary General concepts for building templates | Document builder | The environment in which the documents/templates are created. | | | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Form | List of all steps and fields, is on the left side of a template. | | | | If-statement | An if/then condition. If X, then Y | | | | Mustaches | To dynamically create a document, mustaches `{{ }}` are used. To make a field editable in the text, the name of the field must be covered by two mustaches on both sides: `{{ field }}`. Without mustaches, the fields are not usable. | | | | Operator |

A symbol that is used with variables to perform various functions. Think of arithmetic or logical functions. The most commonly used operators are explained below:

Arithmetic operators

Comparison operators

Logical operators

String operators

With the plus symbol (+), we can combine two strings.

For example:
text1 = "Two strings "
text2 = "combined"
text3 = text1 + text2

The content of variable text 3 is now: "Two strings combined".

| | Programming | Term for making pieces of text in a template dynamic. | | | | Template | A template is a digitized document. | | | | Text | The text is understood to mean the text of a template and is to the right of the form. | | | | User | The user is understood to mean the end user of the software. | | | # Form A form consists of all fields that can be classified by the user, divided into steps. The user fills the document step by step. ## Steps The document is completed according to the steps. The steps contain all fields. To create a step, the ‘Step’ button must be clicked. The step specifications can then be entered. This looks as follows:
The label is the name of the step, visible to the user ### Field group The field group is the subdivision of the different steps. This is used to invoke the fields in the text. Suppose you give step 1 the field group 'introduction' and step 2 the field group ‘data’, then all fields from step 1 in the text are invoked with `{{introduction.date}}` and in step 2 with `{{data.field}}`. This ensures that one field can have the same field name in both step 1 and step 2 without the same being entered in both fields. ### Scroll to article If the document is divided into articles, you can put a # before each article number. This ensures that a list of the article numbers is created which the step can scroll to. This also ensures that if an article is variable, the numbering of the articles continues. For instance, to scroll article 4, a '4' must be entered in this component. This causes the user to see where the completion of the fields in the text appears. ### Conditions The conditions state when a step does or does not appear. This is further explained in the "Filling in fields" section. ### Leading text Here, the step can be clarified with the help of text, a link and/or a video. This text, a link and/or a video is displayed instead of the text of the document to the right of the step. This can help clarify difficult steps or options. ### Tip The tip is one or more sentences that appear in a ‘?’ next to the step. This is a brief clarification of the step. ## Fields There are 12 types of fields that can be used. You can add a field by dragging it from the sidebar to a step. These fields are explained below. ### Text This is the standard field for entering one or more words or a sentence. You can enter, for instance, a name of a company or person here. ### Number Only numbers can be entered in this fields, letters are not accepted. It is possible to give the number decimals. ### Number with unit Only numbers can be entered in this fields, letters are not accepted. The difference with the Number field is that a unit is also added to the number. This can be anything from % to year or month. You can also add a plural so when you, for example, enter 1, it gives you month, and when you enter 2+, it returns months. ### Price This is a Number field with a currency type in front of it. This field is mainly intended to clarify that the user must enter an amount. Standard numbers with two decimals can be entered here. ### Date This field returns a date. ### E-mail address Only an e-mail address can be entered in this field, the user may not continue if an @ is not used in the field. ### Text area This field is an extensive text field. The user can enter multiple sentences and paragraphs here. ### Choice list This field is a drop-down selection list from which the user can select one option. ### Option group This field offers the user a number of options to choose from. It is possible to have the user select multiple options by ticking the multiple selection box. ### Check box The check box gives the user one option for which they can choose to select or not. ### Likert scale This field is a rating field that is often used in surveys. Above the balls is a scale that can be entered (such as 1 to 5). To the left of the field are the subjects to be assessed. ![](/files/-LoPeRPZNwicmu1OahIs) ### Expression This field cannot be entered by the user. This field is used to program. It can be used to, among other things, automatically calculate a date, perform calculations or to combine pieces of text. This field is explained later in the manual. We will go into a few expressions in this documentation. If you need something that isn't documented, you can generally find it by googling what you need in combination with the word 'JavaScript'. You can use an If else statement by using the following syntax\ Condition ? true : false\ eg: `Calc.Answer == 5 ? Calc.total = 100 : Calc.total = 0`\ Here the value of Calc.total will be 100 if the answer of the user in calc.answer was 5. Otherwise Calc.total will hold the value 0. When you're calculation the sum of two numbers, you have to use parseNumber(x), since the program recognizes the numbers as strings, which will cause 1 + 2 to be 12.\ Use: `Result = parseNumber(x) + parseNumber(y)` instead You can always do calculations with the arithmetic operators as shows in #Glossary ## Filling in fields The options per field are discussed below. If a field is added, a menu where the field is specified appears. This menu is different per field with the exception of a few general options. The following applies to all fields except the Expression field. ### General options The options below apply to all fields: #### Label This is the name of the field. This could be a question about, for instance, what needs to be entered, such as: “What is the name of the company?”. #### Field name The field name is very important for programming the fields in the text. The field can be invoked in the text using the field name. A field is invoked in the text with a fixed format: `{{fieldgroup.fieldname}}`. The field group is explained in the ‘Steps’ section. Suppose a step has the name ‘data’ and the field name has the name ‘name\_company,’ then the field needs to be programmed in in the text in the following way: `{{data.name_company}}`. If the field is then completed, this appears in the text. It is important that the field names are not the same to prevent overlap. If the field name consists of different words, an underscore ( \_ ) always needs to be placed between the words. #### Accompanying text This is the explanation with a field. If it is necessary to clarify things about the question, this can be done in the accompanying text. This will appear next to the field as ‘?’. #### Required This tickable box ensures that the user cannot continue unless they complete this field when drawing up the contract. #### Conditions This can be used to indicate when a field should or should not be displayed. This field uses the field group, field name and an operator. Suppose there are two fields, field 1 (a selection list with option Yes or No) and field 2 (a Text field). Field 2 should only be displayed if field 1 is set to Yes, then the following is shown in field 2 (the mustaches are NOT needed for this!): `fieldgroup.field1 == “Yes”`. This means that field 2 is displayed if the selection in field 1 is Yes. In the conditions options, multiple conditions can be included using logical operators. All standard calculation rules apply to the conditions. ### Specific options #### Default value If this option is entered, then the entry appears in the field and the text by default. The user can adjust this as desired when filling in the document. Present in the following fields: Text, Number, Number with unit, Amount, E-mail address #### Masker With this option, you can give a text field a fixed content. For instance, for a postal code, ‘9999aa’ is entered here. Present in the Text field. #### Min/Max Here the minimum and maximum value that may be entered can be specified. Present in the following fields: Number, Number with unit and Amount. #### Max decimals Here you can indicate how many decimals the entered number may have. Present in the Number and Number with unit fields. #### Default current day If checked, the date of the current date is filled in by default. Present in the date field. #### Options Here, the options that can be selected for a selection list or option group can be entered. An option consists of a Value and a Text. In the Text, you enter what the uses sees as a choice. The Value is that which is linked to the text and can be displayed in the text of an agreement or used as a condition. It is possible to add additional options. Present in the selection list and option group fields. ## Standard Fields ![](/files/-LoPUM9__UK__Jw5oZ89) Standard fields are one or more fields that often occur in agreements. They can be placed in a step when creating a template. Using the ‘+ New field’ button, a standard field can be created. You can also also always safe new step or field as a standard field while you're working on a form. Standard fields often go hand in hand with standard articles. They're located under the normal fields and you can insert them by clicking.
# Content The template content is parsed as mustache and may be formatted as HTML. ## Table This section explains the options and limitations of the table.
After adding a table, the table properties can be entered. **Rows** – Number of rows of the table **Columns** – Number of columns of the table **Width** – Width of the table in percentages **Height** – Height of the rows **Edge thickness** – 0 = no edge, 1 = an edge everywhere
It is possible to adjust the properties of a cell. To do so, you need to click on a cell with the right mouse button. You then go to cell and cell properties. **Width** – Width of the column in which the cell is located **Height** – Height of the row in which the cell is located **Alignment** – Here, you can determine the alignment of the text in the cell. By default, the text is aligned top left. ## Field content FillTheDoc recognizes any text typed in the content as regular text and will read all spaces and paragraphs. When you want to add a static piece of content, based on user input, you put the location of this content in the text between mustaches. `{{}}` When you ask the user for his name in the field 'questions' and step 'name', and you want to add this to the text 'Hello (insert name), this document is for you!', you get the following text: `Hello {{questions.name}}, this document is for you!` ## Dynamic text with the help of a statement In the text of a template, words/pieces of text can be made dynamic with the help of a statement. This is possible by using fields and their outcomes. *Example:* Every dynamic piece of text is opened using the following code: `{{#condition}}` Every dynamic piece of text is closed using the following code: `{{/}}` This translates into the following statement: `{{#condition}}text{{/}}` In the above statement, text is only visible under a certain condition. Field1 is a Selection list with choices Yes and No in the case above. `{{#field1 == "Yes"}}This sentence must be made dynamic/variable{{/}}` This means that when the user puts field1 to Yes, the sentence appears, and with all other possible options, in this case just No, the sentence does not become visible. You can use `!==` to do the opposite: `{{#field1 !== "Yes"}}This sentence must be made dynamic/variable{{/}}` Now, the sentence will only NOT appear if Yes is selected with field1 and WILL appear with all other possible options. It is possible to use other operators (see concepts) besides the == symbol from the example. If the outcome of a field is a word, the word should be put in quotation marks (“). A number does not need to be put between quotation marks (“). For example: `{{#x == 5}}` and `{{#x == "cow"}}` For an **option group**, the following code needs to be used: `{{#optionsFieldName.indexOf("Option3") > -1}}Text for tickable box 3{{/}}` When a tickable box isn't ticket by the user, it returns the value -1. When it's checked, it returns the value 0 and when there is a list of things that can be checked, it will assign values increasingly: 1, 2, 3 etc.\ When you want to show a certain text under the condition that one of the tickable boxes in a field is checked, you should there check if its value is not -1 You can also use: `{{#optionsFieldName.includes("Option3")}}Text for tickable box 3{{/}}` You can refer to a **checkbox** by checking it's checked (true) or unchecked (false) like so: `{{#fieldgroup.field == true}}this is readable when box is checked{{/}}` You can refer to an answer in a **Likert Scale** as follows:\ `{{#fieldgroup.field.0 == yes}}text shows if answer to first question is yes{{/}}` Here, the text shows up if the answer to the first question is yes. ## If-statement It is possible to use an if-statement in the text. Suppose there is a Selection list (field1) with two choices: Yes and No. For an if-statement, the following code is used: `{{#field1 == "Yes"}}The Employee does receive vacation days{{/}}{{#field1 !== "Yes"}}The Employee does not receive vacation days{{/}}` What this means is that if field1 is set to Yes, then the sentence: “The Employee does receive vacation days” will appear, and otherwise, the sentence: “The Employee does not receive vacation days” is displayed. This can be done with as many choices as desired, not just with a field with two choices, since you can also use `== "No"` instead of `!== "Yes".` You can also use:`{{field1=="Yes" ? "The Employee does receive vacation days" : "The Employee does not receive vacation days"}}` Creating an if-statement is possible with the use of the following fields: Selection list, Option group, Check box, Likert scale and Number with unit. ## Creating a list of articles It is possible to create a numbered list of articles. If you put a # before each article number, the software turns these numbers into a numbered list. This means that if an article is dynamic and is not displayed, the numbers of the articles still form a consecutive list. Example: This is what the programming looks like, under ‘Edit’. > Article #1 Duration > > Piece about duration > > Article #2 Period > > Piece about period > > Article #3 Insurance > > Piece about insurance This is shown in the document as follows, under ‘View’. > Article 1 Duration > > Piece about duration > > Article 2 Period > > Piece about period > > Article 3 Insurance > > Piece about insurance If Article 2 is not dynamic and not displayed, Article 3 will be given number 2. > Article 1 Duration > > Piece about duration > > Article 2 Insurance > > Piece about insurance It is then also possible to scroll to an article, see ‘Scroll to article’ under ‘Steps’. NOTE! Sometimes the # symbol stays in the ‘View’ environment in front of the article number, to resolve this, you remove the space and the first letter after the article number and then enter it again. It is possible to, for example, have references to the article numbers change with the article number. Example: Suppose that Article 1 from the previous example contains a reference to Article 3: “See what is described in Article 3.” and Article 2 is not displayed, then the reference to Article 3 can be changed to 2 with the following code: `Article {{$[3]}}` . The sample sentence will then look as follows: “`See what is described in Article {{$[3]}}`.” So if Article 2 is not dropped, the sentence is shown as follows: “See what is described in Article 2”. ## Date A number of additional functions are possible with regard to the date. It is possible to add or subtract a period from a chosen date in a Date field and to display it in the text. This can be done with the help of the following codes: **Add** – `{{datefield.addPeriod(1, 'year')}}` Adds a year to the date `{{datefield.addPeriod(duration)}}` Here, ‘duration’ is a Number with unit field with a period as the entered value, for instance: ‘week’, ‘month’ or ‘year’. The function automatically records the period and adds it to the date. The same applies to subtractions. The periods are also recognized in English. **Subtract** – `{{datefield.substractPeriod(1, 'year')}}` Subtracts a year from the date Date fields can use the additional function by using [*moment.js*](http://momentjs.com/docs/).\ In this case, the variable date field ‘datefield’ is the field name of a Date field. This name can be changed as desired. `x.localeDateFormat()` transforms a date to the selected local standard ## Troubleshooting It may be that when entering an incorrect code or forgetting to close a statement, it is no longer possible to test the document under ‘View’. When this situation occurs, it is important to systematically find out the problem. Save the template and then remove all text first, and if this does not solve the problem, eliminates steps 1 by 1 and check whether you can use the software again under 'View'. This way, you can figure out where the problem is step by step and resolve it. ### Known problems If a statement (see ‘Dynamic text using a statement') is closed once too many, then the piece becomes fully blank under 'View'. The same happens if you forget a mustache, for instance: `{{field1}`. If a statement is not closed, then the text under the opening of the statement disappears. This can be solved by closing or removing the statement. # Settings Open the template setting by clicking this ![](/files/-Lmt5zwxdgqZryKiKrEG) icon when editing the template.
## Name The name and description are returned when fetching a list of all templates. The name is also shown in the template overview. ## Resource Identifier The template may be specified by its id, which automatically generated, or by the reference which is specified in the `Resource Identifier` field. Each template must have a unique reference. You can swap the reference from one template to another (unlike an id). ## Locale The locale specifies the number and date formatting and typically should match the document language. Currently only Dutch and English are supported. You can transform a date or number to the locale by using:\ `x.localeDateFormat()` and `x.localeNumberFormat()` ## Font A single font is used throughout the document. Any font that's available through [Google fonts](https://fonts.google.com/) may be selected. ## Header / Footer Use one of the header / footers you as described in#FillTheDoc UI. (when generating the PDF) Note that the header and footer are not displayed when filling out the form or when getting the document as HTML. ## # Example Lets use everything we've learned ### Name and date First, we create a step for our name ![](/files/-LoPJrvpr5D1RBOeBEda) Next, we have to drag a 'free text' field from the sidebar to this step ![](/files/-LoPK-_Q0_hM76fydXyr) Now we drag a date field to the same step ![](/files/-LoVg4__TfbixU1K_SeV) Add the following text \ `The date today is {{Name.answer}}` ### Options Now we have to create a step that's going to ask us to pick a value from a list of options ![](/files/-LoPKLdaNrwEZmqpBEhO) Next, we drag an option group from the sidebar to this step with the options ![](/files/-LoPKRwC2S9RhWu1tcaO) ### Choice Next, in case someone picks the second option, we want to know why, so we add the following field to the same step ![](/files/-LoPNeCW-zp_-rpQR1hy) `{{#Example.Options.indexOf("first") > -1}}I don't like that option, {{Name.yourname}}{{/}}{{#Example.Options.indexOf("second") > -1}}That's a good option!{{/}}{{#Example.Options.indexOf("third") > -1}}{{/}}` ### Calculation We can also a calculation inside the form, and have form calculate something based on the given answers.\ First we create a calculation step with three number fields.\ We call them `Calc.fav` `Calc.house` and `Calc.multiply` ![](/files/-LoLS7H7llDp8vquOqGj) Now, we drag an expression to this step and have it multiply the sum of your favorite number with your address by a number of choice, which we call Calc.total ![](/files/-LoPLWwTNJWUb30gwiXL) Under article 3, we added the following code `Your total is ({{Calc.fav}} + {{Calc.house}}) * {{Calc.multiply}} = {{Calc.total}}` Since we defined the articles, and we added 'scroll to article 3' in all steps, we will be shown this part of the text when someone has to answer the questions. ### Lets add in a variable article We're going to create a table of contents with one variable article we want to be able to take out. First we're going to create a step with a choice field. ![](/files/-LoVY1pVHg0MHzyRr0Dj) We want article 4 to show, unless someone answers 'no', and when it doesn't show, we want the other article numbers to automatically update, so we write the following text:`Table of contents`\ `Article {{$[1]}} Beginning`\ `Article {{$[2]}} Middle`\ `Article {{$[3]}} Example`\ `{{#article.answer !== "no"}}Article {{$[4]}} Article Example{{/}}`\ `Article {{$[5]}} Final`\ and we write write article 4 in the same way:
### A final check to see if we understand everything! ![](/files/-LoPa01hq0q8ylDqDuXs) ![](/files/-LoPa57HXHXY9Oit9ESJ) If someone answers no, we want to know how bad they understand it. We will use the Likert scale for that. ![](/files/-LoPaNflqzH92HER4R-c) We add the following text:`{{#understand.question == 1}}That's great!{{/}}` `{{#understand.scale == "neutral" || understand.scale == "decent" || understand.scale == "good"}}You'll get there if you keep practicing!{{/}}` `{{#understand.scale == "not at all" || understand.scale == "not good enough"}}Try reading the documentation again, follow along, and try again! :){{/}}` We now have the following text ![](/files/-LoZn_Q8k1IvrrP7zRSZ) ### Lets see how our template works! ![Date is working, no name yet](/files/-LoViAyf0uWhYywjRq0i) ![Lets try the second one](/files/-LoVibQO94wlcXS9IQDN) ![Good!](/files/-LoViIMtDXCrXLWeCGK1) ![](/files/-LoViWDd738Ydr-mzweD) ![Article 4 gets removed and 5 turns to 4](/files/-LoVim1N6OpuAlzlbyXo) ![Read again!](/files/-LoViw3XlvAmebtFa2b7) ![We'll get there!](/files/-LoVj0EeExYjl4bj7haK) ![Done!](/files/-LoVj7ENIZnK1pPtNz1H) # Customization Standard texts, Fields and Headers / Footer ## Standard texts ![](/files/-LoVFOtCR5B95-hhFjWY) You can create standard texts sorted in different groups. Standard texts can be as short as one line and as long as a complete document. You can insert these standard texts in your templates. ![](/files/-LoVFgYAxBzFY7m3vvsZ) ## Fields ![](/files/-LoVGNIQN-r12foh5MZk) Standard fields are one or more fields that you often use in your templates. You can place them in a step of your template. A new standard field can be made by clicking on the green 'new field' button or by saving a step/field in your template as standard field.
Saving as a standard field when adding a step in a template
## Headers / Footers ![](/files/-LoVINoOGzcycc7TFJvY) You can create standard Headers and Footers for your templates. A new Header / Footer design can be created by clicking on the green 'new section' button. The design won't show up in the template itself but will be shown in the final document. You can drag a text or image field in the header/footer section and design in to your liking. ![](/files/-LoVIIl-pYmEWUfRh-Nz) # API Fillthedoc provides a REST API for programmatic access. ## Authentication header The API uses bearer authentication. Add the following header to each API HTTP request; ``` Authorization: Bearer ``` ## Creating an access token Access tokens *(aka API keys)* can be created and managed via account settings. ![](/files/-LnGAzPNjvhiKoWpkWui) Press `Add token` to create a new token. When adding a token, specify a name that reflects what the token will be used for. ![](/files/-LnGCFGceRQNegX-mBsn) Copy the value of the `Key` field, which is uses for the authentication. Beware that the key is only displayed when creating an access token. If you loose this value, simply remove the token and create a new one. ![](/files/-LnGCXfj6YcxdOUrLblo) Under `Advanced options` you can limit a key to specific folders. By default a key can access templates from any folder. It's also possible to give a key super privileges, which allows you to create access tokens via the API. This is generally not recommended. # 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 `POST` `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 `GET` `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 `POST` `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 `DELETE` `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 %} # Template API ## Templates `GET` `https://fillthedoc.com/api/templates` Get a list of all published templates. #### Query Parameters | Name | Type | Description | | -------- | ------ | ---------------------------------------- | | category | string | Filter templates on category | | folder | string | Get templates from folder and subfolders | {% tabs %} {% tab title="200 " %} ```javascript [ { "id": "welcome", "name": "Welcome letter", "description": "Welcome letter for new users", "categories": [ "most-used", "hr" ] }, { "id": "labor-agreement", "name": "Labor agreement", "description": "A labor agreement for temporary or steady employees", "categories": [ "most-used", "hr" ] }, { "id": "cao-employee", "name": "CAO Employee", "description": "General CAO agreement for employees", "categories": [ "hr" ] }, { "id": "cao-offshore", "name": "CAO Off Shore", "description": "CAO agreement for offshore employees", "categories": [ "hr" ] }, { "id": "incorporation-bv", "name": "Incorporation BV", "description": "Offical document for forming a new BV", "categories": [ "most-used", "incorporation" ] }, { "id": "incorporation-holding", "name": "Incorporation Holding BV", "description": "Official document for forming a new holding BV", "categories": [ "most-used", "incorporation" ] }, { "id": "incorporation-limited-gb", "name": "Incorporation Limited (GB)", "description": "Official document for forming a British limited", "categories": [ "incorporation" ] }, { "id": "nda", "name": "Non Disclosure Agreement (NDA)", "description": "Multi-purpose, one- or two-way NDA", "categories": [ "most-used", "hr", "sales" ] }, { "id": "due-diligence", "name": "Due diligence report", "description": "A due diligence report is request when transfering >10% of the stocks of a company", "categories": [ "sales", "takeover" ] } ] ``` {% endtab %} {% endtabs %} ## Categories `GET` `https://fillthedoc.com/api/categories` Get a list of all categories. {% tabs %} {% tab title="200 " %} ```javascript [ { "id": "most-used", "name": "Most used" }, { "id": "incorporation", "name": "Incorporation" }, { "id": "hr", "name": "HR agreements" }, { "id": "sales", "name": "Sales" }, { "id": "takeover", "name": "Takeover" } ] ``` {% endtab %} {% endtabs %} Categories are used to group and filter templates. A template may be part of any number of categories. ## Folders `GET` `https://fillthedoc.com/api/folders` Get a list of all folder. {% tabs %} {% tab title="200 " %} ```javascript [ "hr", "hr/contracts", "hr/dossiers", "sales", "sales/contracts", "sales/offers" ] ``` {% endtab %} {% endtabs %} Templates may be organized in folders. Folders are nested; they may have subfolders. # Embedding With the document API you can create a new document. The response of this request will contain an `edit_url` property. This URL can be send directly to the end user or it can be used to embed filling out the document in your application. ## iframe To allow a user to edit the document in your application, embed fillthedoc using an iframe. The URL of the iframe is the `edit_url` of the document. ```markup