# PDF Insights Quickstart

This Quickstart applies to:

* PDF Insights
* PDF Insights w/Thumbprint


## 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

Call `GET https://insights.moneythumb.com/api/v1.5/authenticate`.

Include the following headers:

| Header | Value |
|  --- | --- |
| `Authorization` | `Basic [base64-encoded username:password]` |
| `MT-Product` | Either`pdfinsights` (PDF Insights), or `pdfinsightstp` (PDF Insights w/Thumbprint) |


No request body is required.

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

For further 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

Call `POST https://insights.moneythumb.com/api/v1.5/uploadpdfs`.

Include the following headers:

| Header | Value |
|  --- | --- |
| `Authorization` | `Bearer [session token]` |
| `MT-Product` | Either`pdfinsights` (PDF Insights), or `pdfinsightstp` (PDF Insights w/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

Repeat the same `/uploadpdfs` call from 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.

#### 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.

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

Repeat the same `/uploadpdfs` call from 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: []
}
```

## 6. Next Steps

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