How to design and deploy your first document parsing API
Published: 2021-02-25 21:55:27

---
title: How to design and deploy your first document parsing API
published: true
description: 
tags: 
//cover_image: https://direct_url_to_image.jpg
canonical_url: https://mindee.com/documentation/beta-api-builder/getting-started
---


<p><strong>This tutorial describes the steps required to create a custom document data extraction API using Mindee.</strong></p>

<p>&nbsp;</p>

<p>Over the course of this tutorial, you will learn how to train a deep learning model that can parse and extract the data of your choice in your documents.</p>

<p>&nbsp;</p>

<p>Once the ML model is trained, you will be able to use the custom REST API backed by that model in your application code using the language of your choice.</p>

<p>&nbsp;</p>

<p>Let&rsquo;s see how to build and deploy your first document data extraction REST API using the following, fictitious scenario: as a developer, you want to extract the name of any burger food store that delivers orders to your door, along with its address, average user rating, user votes count as well as its first menu item name and price.</p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<h2>Set up your API</h2>



<h2>Prerequisites</h2>

<p>&nbsp;</p>

<ol>
	<li style="list-style-type:decimal">You will need a free beta account.<a href="https://beta.mindee.net" style="text-decoration:none"> <u>Sign up</u></a> and confirm your email address before proceeding.</li>
	<li style="list-style-type:decimal">Download this <a href="https://mindee-public-website-dev.s3.amazonaws.com/blog/2021/01/13/burger-stores_config.json" style="text-decoration:none" target="_blank"><u>data model configuration file</u></a>.</li>
	<li>Download this <a href="https://mindee-public-website-dev.s3.amazonaws.com/blog/2021/01/13/burger-stores.zip" style="text-decoration:none" target="_blank"><u>sample training set</u></a>.</li>
</ol>
<p>&nbsp;</p>

<p>Once you have signed up and logged in at <a href="https://beta.mindee.net" style="text-decoration:none"> <u>https://beta.mindee.net</u></a>, press the <strong><em>I&rsquo;m ready, start building</em></strong> button, as shown below:</p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p><img src="https://mindee-public-website-dev.s3.amazonaws.com/blog/2021/01/14/apibuilder-apihub-homepage.png" /></p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p>First, we need some basic information about your new, custom document scanning API. That info will help us highlight your API in your Mindee API Hub (and in other users&rsquo; API Hubs if you choose to share your API with them). The requested properties are:</p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<ul>
	<li><strong>Document type: </strong>The common name of the document type your API will be trained on.<br />
	<em>Examples: 1040 US Tax Form, Pay Stub, Bank Statement </em></li>
	<li><strong>API name: </strong>The resource name of your API URL.<br />
	We automatically generate one for you based on your document type but you can customize it at your own convenience. Note however that you can&rsquo;t use special or accented characters. The format of your API URL complies with the following scheme: <code>https://api-beta.mindee.net/[<em>username</em>]/[<em>API_name</em>]</code></li>
	<li><strong>Description: </strong>An optional, short blurb aimed at conveying the purpose of the API. This description will appear below the image in your API Hub (and others if you choose to share your API with other users). We suggest you make it as clear and concise as possible to maximize its effectiveness.</li>
	<li><strong>Image: </strong>An uploaded image that appropriately illustrates your API. Other users may see it in their API Hub if you choose to share it with them.</li>
</ul>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p>Here is a possible configuration for our first burger stores API:</p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p><img alt="" src="https://mindee-public-website-staging.s3.amazonaws.com/blog/2021/01/14/api-builder-api-setup.png" /></p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p>Fill out the form with the following values (or pick your own):</p>

<p>&nbsp;</p>

<ul>
	<li style="list-style-type:disc"><strong>Document type</strong>: Burger Stores and Menus</li>
	<li style="list-style-type:disc"><strong>API Name</strong>: burger_stores</li>
	<li style="list-style-type:disc"><strong>Description</strong>: An API used to extract data (such as store name, ratings and address) from popular burger stores</li>
	<li style="list-style-type:disc"><strong>Image</strong>: upload <a href="https://mindee-public-website-dev.s3.amazonaws.com/blog/2021/01/13/burger_api.jpg" style="text-decoration:none" target="_blank"><u>this image</u></a></li>
</ul>

<p>&nbsp;</p>

<p>Once you&rsquo;re done setting up your API, press the <strong><em>Next step: define your data model</em></strong> button to create the list of fields we&rsquo;d like to extract from our burger stores documents.</p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<h2>Define your document data model</h2>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p>The following page shows up:</p>

<p>&nbsp;</p>

<p><br />
<img alt="" src="https://mindee-public-website-dev.s3.amazonaws.com/blog/2021/01/14/api-builder-design-empty.png" width:1792px="" /></p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p>You can either manually add each field or upload a json-formatted file, typically generated from an existing data model someone previously built (and exported).</p>

<p>&nbsp;</p>

<p>The following information is required for each field:</p>

<p>&nbsp;</p>

<ul>
	<li style="list-style-type:disc"><strong>Field name: </strong>The legible field name used in your API documentation</li>
	<li style="list-style-type:disc"><strong>Api response key: </strong>The field key available in your API response to carry the extracted field value for each document</li>
	<li style="list-style-type:disc"><strong>Field type: </strong>The data type of the field you are trying to extract.<br />
	The supported data types currently are: strings, numbers, dates, email addresses, phone numbers and URLs.<br />
	Specifying a field type helps our deep learning selector better understand the data you&rsquo;re looking for by restricting the number of potential candidates for each field. <a href="https://mindee.com/documentation/api-builder/data-model" style="text-decoration:none"><u>Learn more about the data types</u></a> we support.</li>
</ul>

<p>&nbsp;</p>

<p>For the purpose of this tutorial, we want to extract the following information from our image or PDF documents:</p>

<p>&nbsp;</p>

<ul>
	<li style="list-style-type:disc">The burger store name (a string)</li>
	<li style="list-style-type:disc">The burger store address (a string)</li>
	<li style="list-style-type:disc">The store average user rating (a floating number)</li>
	<li style="list-style-type:disc">The votes count number (an integer)</li>
	<li style="list-style-type:disc">The name of the first item on the menu (a string)</li>
	<li style="list-style-type:disc">The price of the first item (an amount)</li>
</ul>

<p>&nbsp;</p>

<p>Below is a screenshot of one of our training files with each field above highlighted in green:</p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p><img src="https://mindee-public-website-staging.s3.amazonaws.com/blog/2021/01/14/api-builder-fields.png" /></p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p>The Mindee representation of these fields after setting them up one by one is the following:</p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p><img alt="" src="https://mindee-public-website-dev.s3.amazonaws.com/blog/2021/01/14/api-builder-design-burger-stores-model.png" width:1202px="" /></p>

<p><br />
&nbsp;</p>

<p>You can manually add them one by one or you can upload a configuration file to automatically populate your data model (this file is typically generated using the Config Export feature available to existing models in the Settings section of your API dashboard).</p>

<p>&nbsp;</p>

<p>Press the <strong>Choose file</strong> button to upload the <a href="http://mindee-public-website-dev.s3.amazonaws.com/blog/2021/01/13/burger-stores_config.json" style="text-decoration:none" target="_blank"><u>json-formatted config file</u></a> (the one mentioned in the Prerequisites section above):</p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p><img alt="" src="https://mindee-public-website-dev.s3.amazonaws.com/blog/2021/01/14/api-builder-design-choose-file.png" width:579px="" /></p>

<p>&nbsp;</p>

<p>Once you&rsquo;re done setting up your data model, press the <strong><em>Data model ready? start training</em></strong> button at the top of the screen:</p>

<p>&nbsp;</p>

<p><br />
<img alt="" src="https://mindee-public-website-dev.s3.amazonaws.com/blog/2021/01/14/api-builder-design-ready.png" width:1167px="" /></p>

<p>&nbsp;</p>

<h2>&nbsp;</h2>

<h2>&nbsp;</h2>

<h2>Train the model</h2>

<p>&nbsp;</p>

<p>Now is the time to train our Burger Stores deep learning model in the Training section of our API:</p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p><img alt="" src="https://mindee-public-website-dev.s3.amazonaws.com/blog/2021/01/14/api-builder-training-empty.png" width:1792px="" /></p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p>For each of our documents we must assign a value to each field by selecting a box (or several consecutive boxes) displayed in the uploaded document. The Mindee selector highlights all the potential candidates for each field in blue, as shown below:</p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p><br />
<img alt="" src="https://mindee-public-website-dev.s3.amazonaws.com/blog/2021/01/14/api-builder-training-burger-stores-onedoc.png" width:1792px="" /></p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p>When you find the blue box that matches the field you are looking for, simply click that box. This populates the field text box with the selected value and shows the selected box in an identifiable color. For instance, the screenshot below highlights the box we selected for the <em>average_rating</em> field in orange:</p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p><img alt="" src="https://mindee-public-website-dev.s3.amazonaws.com/blog/2021/01/14/api-builder-training-selected-box.png" width:1792px="" /></p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p>If the content you are looking for is composed of more than one box, simply select all the consecutive boxes that match your field (non-consecutive boxes may result in an inefficient model). For example, he screenshot below shows the <em>address</em> field populated with 9 consecutive boxes:</p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p><br />
<img alt="" src="https://mindee-public-website-dev.s3.amazonaws.com/blog/2021/01/14/api-builder-training-multiple-boxes.png" width:1254px="" /></p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p>You can<a href="http://mindee-public-website-dev.s3.amazonaws.com/blog/2021/01/13/burger-stores.zip" style="text-decoration:none" target="_blank"> <u>download this sample dataset</u></a> to train your Burger Stores deep learning model. Unzip the file into a folder and upload each file in that folder one-by-one to the <em>Training</em> page.</p>

<p>&nbsp;</p>

<p>Once you have selected the proper box(es) for each of your fields (as displayed on the right-hand side of the document), press the <strong><em>validate</em></strong> button and repeat the tagging process for the next document.</p>

<p>&nbsp;</p>

<p>The progress bar above each picture indicates the advancement of your tagging efforts and identifies the milestones at which a new model is generated.</p>

<p>&nbsp;</p>

<p>Every 20 documents, a new model is being trained and automatically deployed into your API environment. You will receive an email whenever your latest model has been trained and is up and running:</p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p><img alt="" src="https://mindee-public-website-dev.s3.amazonaws.com/blog/2021/01/14/api-builder-training-model-ready-email.png" width:670px="" /></p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p>Note that the more documents you feed into your model, the more accurate it will be.</p>

<p>&nbsp;</p>

<p>With that being said, we will generate the first version of your trained model once you reach the 20 documents threshold (uploaded and validated).</p>

<p>&nbsp;</p>

<p>At this point, you can experience the true power of the Mindee data extraction engine every time you upload a new training file, as the model will start filling out the fields on the right-hand side with the most likely values it was able to identify in the uploaded file.</p>

<p>&nbsp;</p>

<p>From now on, the Burger Stores model will help you annotate new data in the <em>Training</em> section:</p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p><img alt="" src="https://mindee-public-website-dev.s3.amazonaws.com/blog/2021/01/14/api-builder-training-model-predictions.gif" width:1222px="" /></p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p>With a 20-documents training set, the model algorithm starts working pretty well on most fields, but still makes a few mistakes on the complex fields, such as the address field (extra words are predicted).</p>

<p>&nbsp;</p>

<p>Once again, the more data you&rsquo;re feeding to the model, the more accurate your API will get. So your job will now consists in correcting your model until you reach the next 20 documents threshold, which will kick off the generation of a new, more efficient model. You may repeat this task as often as you want.</p>

<p><br />
&nbsp;</p>

<p>&nbsp;</p>

<h2>Settings, API keys and documentation</h2>

<p>&nbsp;</p>

<p><span style="color:#000000">If you select the </span><span style="color:#000000"><strong><em>Documentation</em></strong></span><span style="color:#000000"> tab, the following page is displayed: </span></p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p><img src="https://mindee-public-website-staging.s3.amazonaws.com/blog/2021/01/14/api-builder-documentation.png" /></p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p>This page allows you to explore your API endpoints and download your API definition as an <a href="https://www.openapis.org/" target="_blank">OpenAPI</a>-formatted file.</p>

<p>&nbsp;</p>

<p>The <em><strong>API Keys</strong></em> tab allows you to create and manage your custom API tokens:</p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p><img alt="" src="https://mindee-public-website-staging.s3.amazonaws.com/blog/2021/01/14/api-builder-apikeys.png" /></p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p>The <em><strong>Settings</strong></em> tab allows you to update general information about your API such as its name or its description. It also allows you to download your data model field configuration, which can be used to create a new, enhanced data model without having to start from scratch.</p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p><img alt="" src="https://mindee-public-website-staging.s3.amazonaws.com/blog/2021/01/14/api-builder-settings.png" /></p>

<p><br />
&nbsp;</p>

<p>That&rsquo;s it! You should now be able to set up a real world use case now and build whichever document parsing API you may need.</p>

<p>&nbsp;</p>

<p>If you have any questions or feedback about this tutorial, feel free to reach out to us in the <strong>#tutorials</strong> channel of the <a href="https://mindeecommunity.slack.com" style="text-decoration:none" target="_blank"><u>Mindee Community on Slack</u></a> (the Get Started email you have received when signing up contains an invitation to join it).</p>