# Quickstart

This quickstart applies to:

* PDF Insights
* PDF Insights w/Thumbprint
* Thumbprint


Please design your integration to handle additive API changes, such as new fields, without breaking. MoneyThumb makes frequent additions to the API without advance notice. We won't change or remove existing fields or endpoints without prior notice.

> **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).