> For the complete documentation index, see [llms.txt](https://typless.gitbook.io/typlessapi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://typless.gitbook.io/typlessapi/quick-start.md).

# Quick start

***

Typless is an AI-powered document extraction platform for automating manual data entry from any document. With an easy-to-use API, you can extract data with a single call in a matter of seconds.

## 1. Create a new document type

Before you start extracting data, you need to define a document type. 

1. Navigate to the [**Dashboard page**](https://app.typless.com) and click on the **New document type** button in the top right corner of the table. 
2. For this tutorial, we will use a document type with a **Trainable model,** but you can do the same with the **Pretrained model**. Click on the **Trainable model** card, and then on **Use a Predefined Template**.
3. Next, select the **Simple invoice** template and click **Create document type**.\
   This will create a new **document type** with the name **simple-invoice** and the following fields:

* **`supplier_name`**
* **`invoice_number`**
* **`pay_due_date`**
* **`issue_date`**
* **`total_amount`**

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FePXqOCeLb4FOuZhmYG8X%2Fuploads%2FGeoKwJWSdml08ZFfCOCZ%2FREC-20260515111217.mp4?alt=media&token=b0344fab-6402-4ef3-acfe-ec3dfbd1b4f2>" %}
Creating a new document type
{% endembed %}

## 2. Get your API key

To use the Typless API, you need to authorize your requests with an API key.\
The Authorization header for your API key is:  `Token YOUR-API-KEY` ([**Login**](https://app.typless.com/login/?redirect=https://docs.typless.com/) if you do not see one)\
To obtain the **API key**, click on **Settings,** and then visit the [**API Keys page**](https://app.typless.com/settings/api-keys)**.**

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FePXqOCeLb4FOuZhmYG8X%2Fuploads%2FXwpyvlMgoIW7PXZKkPwE%2FREC-20260515112641.mp4?alt=media&token=810fbc33-d3d7-4687-b49c-62abae6c7029>" %}
Getting your API key
{% endembed %}

## 3. Adding a new supplier

Typless is a tool for automation. That's why you need to fill the **dataset** and **train it first**. To automate a new supplier, you need first to add its invoices to the data set. Download an invoice from Amazing Company:

[**Amazing company - download**](https://typless-public.s3-eu-west-1.amazonaws.com/use_cases/metadata-invoice/amazing_company_1.pdf).

{% hint style="success" %}
To add a document to the dataset, use the **`add-document`** endpoint or use the [**training room**](/typlessapi/typless-hub/document-type.md#training-room)**,** where you can easily upload a file and fill out the necessary information.
{% endhint %}

The dataset is created by uploading an original file with the correct value for each field defined inside the document type:

<details>

<summary><strong>1 Open file as base64 string</strong> <em><mark style="color:green;">(Lines 1-7)</mark></em></summary>

Open the file and encode it as a base64 String. Make sure you are pointing to the directory with the file.

</details>

<details>

<summary>2 <strong>Specify your payload with the needed fields</strong> <em><mark style="color:green;">(Lines 11-38)</mark></em></summary>

* `file` - base64 encoded file
* `file_name` - Name of the file
* `document_type_name` - the name of the document type we want to add the supplier to
* `learning_fields` - fields with the correct values used for training

</details>

<details>

<summary>3 <strong>Specify headers</strong> <em><mark style="color:green;">(Lines 34-38)</mark></em></summary>

Add all the needed request headers.

</details>

<details>

<summary>4 <strong>Send the request</strong> <em><mark style="color:green;">(Lines 46-48)</mark></em></summary>

Send the request and make sure that everything went smoothly.

</details>

{% tabs %}
{% tab title="Python" %}
{% code overflow="wrap" lineNumbers="true" %}

```python
import requests
import base64

file_name = 'amazing_company_1.pdf'
# Make sure that you are pointing to the directory with file
with open(file_name, 'rb') as file:
    base64_data = base64.b64encode(file.read()).decode('utf-8')

url = "https://developers.typless.com/api/add-document"

payload = {
    "learning_fields": [
        {
            "name": "supplier_name",
            "value": "Amazing Company"
        },
        {
            "name": "invoice_number",
            "value": "333"
        },
        {
            "name": "issue_date",
            "value": "2021-02-01"
        },
        {
            "name": "pay_due_date",
            "value": "2021-03-31"
        },
        {
            "name": "total_amount",
            "value": "15.0000"
        }
    ],
    "line_items": [],
    "file": base64_data,
    "file_name": file_name,
    "document_type_name": "simple-invoice"
}

headers = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "<<apikey>>"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.json())
```

{% endcode %}
{% endtab %}

{% tab title="Node" %}

```javascript
const fetch = require('node-fetch');
const fs = require('fs');

const fileName = 'amazing_company_1.pdf';
const base64File = fs.readFileSync(fileName, {encoding: 'base64'});

let url = 'https://developers.typless.com/api/add-document';

const payload = {
  file: base64File,
  file_name: fileName,
  document_type_name: "simple-invoice",
  learning_fields: [
    {
        name: "supplier_name",
       value: "Amazing Company"
    },
    {
        name: "invoice_number",
        value: "333"
    },
    {
        name: "pay_due_date",
        value: "2021-03-31"
    },
    {
        name: "issue_date",
        value: "2021-02-01"
    },
    {
        name: "total_amount",
        value: "15.00"
    }
  ]
};


const headers = {
  'Accept': 'application/json',
  'Content-Type': 'application/json',
  'Authorization': '<<apikey>>'
}

let options = {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(payload)
};

 fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));
```

{% endtab %}

{% tab title="Java" %}

```java
import java.io.File;
import java.io.IOException;
import java.nio.file.Files;
import java.util.Base64;
import com.squareup.okhttp.*;


public class AddSupplier {
    public static void main(String[] args) {
        String apiUrl = "https://developers.typless.com/api/add-document";
        String apiKey = "<<apiKey>>";

        String fileName = "amazing_company_1.pdf";
        String resourcesDirectory = "src/main/resources";
        File file = new File(resourcesDirectory, fileName);
        String base64File = encodeFileToBase64(file);

        String jsonString = "{\"file\":\"" + base64File + "\",\"file_name\":\"" + fileName + "\",\"document_type_name\":\"simple-invoice\",\"learning_fields\":[{\"name\":\"supplier_name\",\"value\":\"Amazing Company\"},{\"name\":\"invoice_number\",\"value\":\"333\"},{\"name\":\"issue_date\",\"value\":\"2021-02-01\"},{\"name\":\"pay_due_date\",\"value\":\"2021-03-31\"},{\"name\":\"total_amount\",\"value\":\"15.0000\"}]}";

        try {
            String response = addDocumentFeedback(apiUrl, apiKey, jsonString);
            System.out.println(response);
        } catch (IOException e) {
            System.out.println(e);
        }
    }

    private static String addDocumentFeedback(String apiUrl, String token, String json) throws IOException {
        MediaType JSON = MediaType.parse("application/json");
        OkHttpClient client = new OkHttpClient();
        RequestBody body = RequestBody.create(JSON, json);
        Request request = new Request.Builder()
                .url(apiUrl)
                .post(body)
                .addHeader("Accept", "application/json")
                .addHeader("Content-Type", "application/json")
                .addHeader("Authorization", token)
                .build();
        Response response = client.newCall(request).execute();
        return response.body().string();
    }

    private static String encodeFileToBase64(File file) {
        try {
            byte[] fileContent = Files.readAllBytes(file.toPath());
            return Base64.getEncoder().encodeToString(fileContent);
        } catch (IOException e) {
            throw new IllegalStateException("could not read file " + file, e);
        }
    }
}

```

{% endtab %}

{% tab title="C#" %}

```csharp
using System;
using System.IO;
using RestSharp;

class AddDocument
{

  static void Main(string[] args)
  {

    String apiUrl = "https://developers.typless.com/api/add-document";
    String apiKey = "<<apiKey>>";

    String fileName = "amazing_company_1.pdf";
    String path = Path.Combine("path/to/file", fileName);
    String base64File = encodeFileToBase64(path);

    String jsonString = "{\"file\":\"" + base64File + "\",\"file_name\":\"" + fileName + "\",\"document_type_name\":\"simple-invoice\",\"learning_fields\":[{\"name\":\"supplier_name\",\"value\":\"Amazing Company\"},{\"name\":\"invoice_number\",\"value\":\"333\"},{\"name\":\"issue_date\",\"value\":\"2021-02-01\"},{\"name\":\"pay_due_date\",\"value\":\"2021-03-31\"},{\"name\":\"total_amount\",\"value\":\"15.0000\"}]}";

    String response = addDocumentToDataset(apiUrl, apiKey, jsonString);
    Console.WriteLine(response);
  }


  private static String addDocumentToDataset(String apiUrl, String apiKey, String payload)
  {
    var client = new RestClient(apiUrl);
    var request = new RestRequest(Method.POST);
    request.AddHeader("Accept", "application/json");
    request.AddHeader("Content-Type", "application/json");
    request.AddHeader("Authorization", apiKey);
    request.AddJsonBody(payload);
    return client.Execute(request).Content;
  }

  private static String encodeFileToBase64(String filePath)
  {
    Byte[] bytes = File.ReadAllBytes(filePath);
    return Convert.ToBase64String(bytes);
  }
}
```

{% endtab %}
{% endtabs %}

Response:

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

```json
{
    'details': ['0cbabe33bc9f0f093d2bd06ae3f86240368b6937'], 
    'message': 'Document added successfully.'
}
```

{% endtab %}
{% endtabs %}

You have just added your first document to your data set!

## 4. Execute training

To build the model for extraction, you need to trigger the training. Go to the [**Dashboard page**](https://app.typless.com), look for the **simple-invoice** document type in the list, and click on the ⚙️ settings icon.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FePXqOCeLb4FOuZhmYG8X%2Fuploads%2FolMhzaqbCIbeaTBQBOB7%2FREC-20260515113701.mp4?alt=media&token=a0983923-3d3e-43c0-abac-b1d5aeedbf54>" %}
Starting model training of document type *simple-invoice*
{% endembed %}

Wait a few moments for the training to finish. You can refresh the status by clicking on the **refresh button** in the top left part of the table.\
After the training status says **Models trained**, the model is ready for data extraction.<br>

## 5. Extract data from documents

After the training is finished, you can start precisely extracting data from documents from trained suppliers. Download another invoice from Amazing Company:

[**Amazing company - download**](https://typless-public.s3-eu-west-1.amazonaws.com/use_cases/metadata-invoice/amazing_company_2.pdf).

{% hint style="info" %}
**Need a more in-depth explanation of the response?**\
You can read about it [**here**](/typlessapi/typless/data-extraction.md).
{% endhint %}

#### Extract the data:

<details>

<summary>1 <strong>Open file as base 64 string</strong> <em><mark style="color:green;">(Lines 4-7)</mark></em></summary>

Open the file in a binary mode and correctly decode it into a base64 string. Make sure that your file is in the same directory as the script.

</details>

<details>

<summary>2 <strong>Create Request Payload</strong> <em><mark style="color:green;">(Lines 11-15)</mark></em></summary>

Create request payload with all the required parameters:

* file
* file\_name
* document\_type\_name

</details>

<details>

<summary>3 <strong>Specify headers</strong> <em><mark style="color:green;">(Lines 16-20)</mark></em></summary>

Make sure that the Content-Type is set as application/json

</details>

<details>

<summary>4 <strong>Authorize with your API key</strong> <em><mark style="color:green;">(Line 19)</mark></em></summary>

If the API key is not filled in, you can get it at <https://app.typless.com/settings/profile>

</details>

<details>

<summary>5 <strong>Execute the request</strong> <em><mark style="color:green;">(Lines 24-25)</mark></em></summary>

</details>

{% tabs %}
{% tab title="Python" %}
{% code lineNumbers="true" %}

```python
import requests
import base64

file_name = 'amazing_company_2.pdf'
# Make sure that you are pointing to the directory with file
with open(file_name, 'rb') as file:
    base64_data = base64.b64encode(file.read()).decode('utf-8')

url = "https://developers.typless.com/api/extract-data"

payload = {
    "file": base64_data,
    "file_name": file_name,
    "document_type_name": "simple-invoice"
}
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "<<apikey>>"
}

response = requests.request("POST", url, json=payload, headers=headers)

for field in response.json()['extracted_fields']:
    print(f'{field["name"]}: {field["values"][0]["value"]}')
```

{% endcode %}
{% endtab %}

{% tab title="Node" %}

```javascript
const fetch = require('node-fetch');
const fs = require('fs');

const fileName = 'amazing_company_2.pdf';
const base64File = fs.readFileSync(fileName, {encoding: 'base64'});

const url = 'https://developers.typless.com/api/extract-data';

const payload = {
  file: base64File,
  file_name: fileName,
  document_type_name: "simple-invoice"
}

const headers = {
  'Accept': 'application/json',
  'Content-Type': 'application/json',
  'Authorization': '<<apikey>>'
}

let options = {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(payload)
};

fetch(url, options)
  .then(res => res.json())
  .then(json => {
    json.extracted_fields.forEach(field => console.log(`${field.name}: ${field.values[0].value}`))
  })
  .catch(err => console.error('error:' + err));
```

{% endtab %}

{% tab title="Java" %}

```java
import java.io.File;
import java.io.IOException;
import java.nio.file.Files;
import java.util.Base64;
import com.squareup.okhttp.*;

public class ExtractData {

    public static void main(String[] args) {
        String apiUrl = "https://developers.typless.com/api/extract-data";
        String apiKey = "<<apiKey>>";

        String fileName = "amazing_company_2.pdf";
        String resourcesDirectory = "src/main/resources";
        File file = new File(resourcesDirectory, fileName);
        String base64File = encodeFileToBase64(file);

        String jsonString = "{\"file\":\""+base64File+"\",\"file_name\":\""+fileName+"\",\"document_type_name\":\"simple-invoice\"}";

        try {
            String response = getExtractedData(apiUrl, apiKey,jsonString);
            System.out.println(response);
        } catch (IOException e) {
            System.out.println(e);
        }
    }

    private static String getExtractedData(String apiUrl, String apiKey, String json) throws IOException {
        MediaType JSON = MediaType.parse("application/json");
        OkHttpClient client = new OkHttpClient();
        RequestBody body = RequestBody.create(JSON, json);
        Request request = new Request.Builder()
                .url(apiUrl)
                .post(body)
                .addHeader("Accept", "application/json")
                .addHeader("Content-Type", "application/json")
                .addHeader("Authorization", apiKey)
                .build();
        Response response = client.newCall(request).execute();
        return response.body().string();
    }

    private static String encodeFileToBase64(File file) {
        try {
            byte[] fileContent = Files.readAllBytes(file.toPath());
            return Base64.getEncoder().encodeToString(fileContent);
        } catch (IOException e) {
            throw new IllegalStateException("could not read file " + file, e);
        }
    }
}

```

{% endtab %}

{% tab title="C#" %}

```csharp
using System;
using System.IO;
using RestSharp;

class ExtractData
{
  static void Main(string[] args)
  {
    String apiUrl = "https://developers.typless.com/api/extract-data";
    String apiKey = "<<apiKey>>";

    String fileName = "amazing_company_2.pdf";
    String examplesPath = "path/to/your/file";
    String path = Path.Combine(examplesPath, fileName);
    String base64File = encodeFileToBase64(path);

    String jsonString = "{\"file\":\"" + base64File + "\",\"file_name\":\"" + fileName + "\",\"document_type_name\":\"simple-invoice\"}";
    String response = getExtractedData(apiUrl, apiKey, jsonString);
    Console.WriteLine(response);
  }

  private static String getExtractedData(String apiUrl, String apiKey, object payload)
  {
    var client = new RestClient(apiUrl);
    var request = new RestRequest(Method.POST);
    request.AddHeader("Accept", "application/json");
    request.AddHeader("Content-Type", "application/json");
    request.AddHeader("Authorization", apiKey);
    request.AddJsonBody(payload);
    return client.Execute(request).Content;
  }
  private static String encodeFileToBase64(String filePath)
  {
    Byte[] bytes = File.ReadAllBytes(filePath);
    return Convert.ToBase64String(bytes);
  }
}
```

{% endtab %}
{% endtabs %}

Response:

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

```json
// Example extraction response - the provided recipe will not produce equal results
{
    "file_name": "invoice_2.pdf",
    "object_id": "1cb25cc8-c9fa-4149-9a83-b4ed6a2173b9",
    "extracted_fields": [
        {
            "name": "supplier_name",
            "values": [
                {
                    "x": -1,
                    "y": -1,
                    "width": -1,
                    "height": -1,
                    "value": "ScaleGrid",
                    "confidence_score": "0.968",
                    "page_number": -1
                }
            ],
            "data_type": "AUTHOR"
        },
        {
            "name": "invoice_number",
            "values": [
                {
                    "x": 1989,
                    "y": 545,
                    "width": 323,
                    "height": 54,
                    "value": "20190500005890",
                    "confidence_score": "0.250",
                    "page_number": 0
                },
                {
                    "x": 167,
                    "y": 574,
                    "width": 391,
                    "height": 54,
                    "value": "GB123456789",
                    "confidence_score": "0.250",
                    "page_number": 0
                }
            ],
            "data_type": "STRING"
        },
        {
            "name": "issue_date",
            "values": [
                {
                    "x": 2072,
                    "y": 628,
                    "width": 240,
                    "height": 54,
                    "value": "2019-06-05",
                    "confidence_score": "0.358",
                    "page_number": 0
                }
            ],
            "data_type": "DATE"
        },
      	{
            "name": "pay_due_date",
            "values": [
                {
                    "x": 2072,
                    "y": 628,
                    "width": 240,
                    "height": 54,
                    "value": "2019-06-05",
                    "confidence_score": "0.358",
                    "page_number": 0
                }
            ],
            "data_type": "DATE"
        },
        {
            "name": "total_amount",
            "values": [
                {
                    "x": 2146,
                    "y": 1196,
                    "width": 126,
                    "height": 54,
                    "value": "47.5300",
                    "confidence_score": "0.990",
                    "page_number": 0
                }
            ],
            "data_type": "NUMBER"
        }
    ],
    "line_items": []
}
    "customer": null
}
```

{% endtab %}
{% endtabs %}

For each of the defined fields, you get an object inside `extracted_fields`.\
Every field has up to 5 best-predicted value blocks with **coordinates**, **recognized value**, and **confidence score**.\
The values are always in a string format.

{% hint style="success" %}
📘 For simple layouts, one invoice in your data set is enough, but for more complex ones, you may need around 5 from the same supplier.
{% endhint %}

> <mark style="color:green;">**Congratulations!**</mark>\
> You just successfully trained and extracted data with Typless. You can now use it to automate manual data entry from any of your invoices.

What’s Next

Now you know the basic concepts of Typless, you can search for some pre-made use cases with examples that can help you satisfy your project requirements and get up and running in a couple of minutes!

[**Overview →**](/typlessapi/automation-use-cases/overview.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://typless.gitbook.io/typlessapi/quick-start.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.