# API Best Practices

These best practices ensure you get a seamless experience with our PDF Insights API.

## Recommended Integration

We **strongly recommend** using our all-in-one `/uploadpdfs` endpoint with the following process:

1. Call [`GET /authenticate`](https://docs.moneythumb.com/pdf-insights/api-reference/other/authenticate) with a username and password.  Cache the returned token and use it for 24hrs.
2. Call [`POST /uploadpdfs`](https://docs.moneythumb.com/pdf-insights/api-reference/other/uploadpdfs) with the token, all your documents, and a webhook URL.
3. Receive our webhook with all of your results.


Our all-in-one `/uploadpdfs` endpoint:

* Creates an application.
* Uploads documents.
* Returns the results and scorecard.


## Alternative Integration

If you’re unable to send all your documents at the same time, then use the following process instead (after obtaining the token):

1. Call [`POST /makecsv`](https://docs.moneythumb.com/pdf-insights/api-reference/other/makecsv) with the token, a single document, and a webhook URL.
2. Receive our webhook with your results for the single file.
3. Repeat steps 1 and 2 as necessary.
4. After you have received the webhooks for all submitted documents:
  * Call [`POST /scorecard`](https://docs.moneythumb.com/pdf-insights/api-reference/other/scorecard) to get the scorecard results.
  * Call [`POST /transactions`](https://docs.moneythumb.com/pdf-insights/api-reference/other/transactions) to get the full transactions list.


⚠️ **Warning:** While we fully support this approach, be aware that it’s significantly less efficient and is prone to race conditions.  Specifically, if you send overlapping calls to `/makecsv`, `/scorecard`, or `/transactions`, you may receive either incomplete or inaccurate results.

## Platform Integrations

If you’re a SaaS platform, please send a MT-Partner header with your company or product name in all API calls.  This informs us that we should contact you directly about any technical issues rather than the end-user.

## Timeouts and Retries

We recommend you use the following timeouts with our endpoints:

* For `/makecsv` and `/uploadpdfs`, use 30 minutes.
* For `/scorecard` and `/getresults`, use 1 minute.
* For all other calls, use 30 seconds.


**Note:** We encourage you to retry failed API calls but please set a limit of three retries.

## Security

To keep the API secure, we recommend the following practices:

* Use the [latest version](https://docs.moneythumb.com/pdf-insights/api-reference) of our API.
* Authenticate by username/password and then use the returned session token.
* Create a sub-user in your account specifically for API integrations.
* [Whitelist your IP addresses](https://docs.moneythumb.com/pdf-insights/2_authentication#cidr-whitelisting) with us by emailing your CIDRs to [support@moneythumb.com](https://www.moneythumb.com/contact/).
* Include a unique short-lived token in each webhook URL and validate it upon receipt.