# Quickstart

This quickstart applies to:

* PDF Insights
* PDF Insights w/Thumbprint
* Thumbprint


> **Note:** If you're only using Thumbprint, follow the instructions marked with this icon. Otherwise, follow these steps.


## 1. Verify your credentials

Verify that you can log into the [Insights UI](https://insights.moneythumb.com) using your username and password.

## 2. Authenticate to the API

1. Call `GET https://insights.moneythumb.com/api/v1.5/authenticate`.
2. Include the following headers:


| Header | Value |
|  --- | --- |
| `Authorization` | `Basic [base64-encoded username:password]` |
| `MT-Product` | Either: `pdfinsights` `pdfinsightstp``thumbprint` |


You should receive a `200 OK` response with a session token in the response body.

For details, see:

* [/authenticate endpoint](https://docs.moneythumb.com/pdf-insights/api-reference/other/authenticate)
* [Authentication overview](https://docs.moneythumb.com/pdf-insights/2_authentication)


## 3. Convert a file

> **Note:** If you're using Thumbprint, ignore this Step. But to get the full experience of our API, upgrade to [PDF Insights](https://moneythumb.com).


1. Call `POST https://insights.moneythumb.com/api/v1.5/uploadpdfs`.
2. Include the following headers:


| Header | Value |
|  --- | --- |
| `Authorization` | `Bearer [session token]` |
| `MT-Product` | Either: `pdfinsights` `pdfinsightstp``thumbprint` |
| `Content-Type` | `multipart/form-data` |


Include the following form-data fields in the body:

| Name | Type | Value |
|  --- | --- | --- |
| `appnumber` | string | Any string to identify this application. |
| `pdf-filename` | blob | The file (i.e., bank statement) to upload. |


You should receive a `200 OK` response with a reponse body matching this structure:

```
{ 
  statement_summmaries: [],
  appinfo: {}
}
```

For details, see the [/uploadpdfs endpoint](https://docs.moneythumb.com/pdf-insights/api-reference/other/uploadpdfs).

**Note:** *You should now be able to see this deal in the UI.*

## 4. Return Scorecard and Transactions

> **Note:** If you're using Thumbprint, ignore this Step.


Repeat the same `/uploadpdfs` call from [Step 3](#step-3), but now add three additional form-data fields:

| Name | Type | Value |
|  --- | --- | --- |
| `includescorecard` | string | `true` |
| `includetransactions` | string | `true` |
| `format` | string | `jsonobject` |


You should receive a `200 OK` response with a reponse body matching this structure:

```
{ 
  statement_summmaries: [],
  appinfo: {},
  scorecard: {},
  transactions: []
}
```

## 5. Provide a callback

Image documents are converted asynchronously and their results returned by callback (aka webhook).  We **strongly encourage** you to use this approach for all documents.

> **Note:** Thumbprint scores aren't produced for image documents. OCR is not performed and image documents return with a `requires OCR` message.


#### 5a. Create the recipient

Either use a third-party service or create your own endpoint to receive the callback.  The body of the callback request will match the output you received from `/uploadpdfs` in [Step 4](#step-4).

#### 5b. Upload a document with callback

Repeat the same `/uploadpdfs` call from [Step 4](#step-4), but add one additional form-data field:

| Name | Type | Value |
|  --- | --- | --- |
| `webhook` | string | The URL to which the results should be sent.It should be in the format `https://www.mydomain.com/my-endpoint` |


You should receive a `202 ACCEPTED` response.

A few seconds to a few minutes later (depending on the size and format of the file),
your callback endpoint should receive a request.  The request body should match this structure:

```
{ 
  statement_summmaries: [],
  appinfo: {},
  scorecard: {},
  transactions: []
}
```

> **Note:** If you're using Thumbprint, make sure it matches this structure.


```
{ 
  statement_summmaries: [],
  appinfo: {}
}
```

## 6. Next Steps

> **Note:** If you're using Thumbprint, ignore step 4. But to see our recommended use of the API, check out [Best Practices](https://docs.moneythumb.com/api/pdf-insights/2_api-best-practices).


1. Explore the [/uploadpdfs documentation](https://docs.moneythumb.com/pdf-insights/api-reference/other/uploadpdfs).
2. Set the `finduntrue` form-data field to `true` to automatically identify untrue transactions.
3. Try converting multiple files at once (include as many `pdf-filename` form-data fields as you like).
4. Customize which scorecard sections you want returned with the `sections` form-data field.
5. Add retry logic to your API calls (but please include a retry limit).