> ## Documentation Index
> Fetch the complete documentation index at: https://docs.treasuryprime.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Overview
Welcome to the official reference documentation for the Treasury Prime API. Our APIs are designed to be the best way to automate your company's banking needs.
These APIs are designed to be familiar and easy to work with. They are designed around the principles of [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer), meaning that they use [HTTP](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol) and rely on HTTP's built-in features. They use resource-oriented URLs and HTTP verbs, response codes, and authentication. Request and response bodies are encoded as [JSON](http://www.json.org/) data.
## Live and Test Environments
Treasury Prime API is available in two separate environments. There is a live (production) environment, and a test (sandbox) environment. Requests made to the sandbox environment will never hit banking networks, meaning they can't affect your account balances and will never incur costs.
```
Production: https://api.treasuryprime.com
Sandbox: https://api.sandbox.treasuryprime.com
```
Your developer account will have different API keys for each environment. Each environment has its own URL endpoint to avoid any confusion.
## Authentication
Your API key is used to authenticate each request. API keys are included in requests using [HTTP Basic Auth](http://en.wikipedia.org/wiki/Basic_access_authentication). Provide your API key ID as the basic auth username value, and the API key value as the password.
##### Example Request
```bash bash theme={null}
$ curl -u $API_KEY_ID:$API_KEY_VALUE https://api.treasuryprime.com
```
The API is served exclusively over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure) so all data stays safe and secure. Any requests made over plain HTTP will fail. Any requests made without authentication will also fail.
Anyone who gains access to your keys will be able to impersonate you and could take money out of your bank accounts. **Never** expose your API keys in any publicly accessible areas, including GitHub, client-side code, or even a plain HTTP request. If you are ever in doubt that your API keys may have been exposed, **[contact us immediately!](mailto:security@treasuryprime.com)**
## Ledger & Core Direct Products
These pages document the **Treasury Prime Ledger** Product.
Treasury Prime offers two similar API products depending on the underlying core/ledger.
* **Core Direct**: Bank accounts are direct banking core accounts. These are the exact same accounts that are created if you walk into a branch to create a bank account.
* **Treasury Prime Ledger**: Bank accounts are held in the Treasury Prime ledger and all interaction with the account is done using this API.
The two products have different behaviors and are documented separately.
Please note that Treasury Prime has real-time connections to the cores of each partner bank. Real-time access is essential to move money safely and all our of systems use these low level connections regardless of the product.
You may also view the [**Core Direct**](https://direct.treasuryprime.com/reference/overview) documentation.
## Testing in Sandbox
Before going live you should get familiar with our APIs and test your integration in sandbox. First, you will need to [create a sandbox account](https://app.sandbox.treasuryprime.com/sign_up), and [generate your API keys](/docs/getting-started#2-create-api-keys) in the Developer Dashboard. Then you can do your testing as in command line or using our [Postman Collection](/reference/simulation-endpoint#postman-collection) to speed up your initial exploration of our APIs.
See our [Testing](/reference/simulation-endpoint) section to learn more about testing in our sandbox environment.
## Health Check
A health check can be performed on the API calling the `/ping` endpoint.
##### Definition
```bash bash theme={null}
GET https://api.treasuryprime.com/ping
```
Returns an HTTP status 200 if the API is available.
##### Example Request
```bash bash theme={null}
$ curl -u "$API_KEY_ID:$API_KEY_VALUE" https://api.treasuryprime.com/ping
```
##### Example Response
```bash bash theme={null}
{
"api_version": "1",
"version": "1.10.165-g284f828c",
"time": "2020-12-08T06:27:07.204Z"
}
```
## Idempotency
The API has support for [idempotent](https://en.wikipedia.org/wiki/Idempotence) requests. When you send a request with the idempotency key set, the server will ensure that the request will only be processed once, no matter how many times the request is sent or received. This is useful in preventing duplicate operations in the face of errors or network disruption.
The idempotency key itself may be any arbitrary string. Because the server identifies each unique request by a unique idempotency key, be sure to choose a string that will not be reused in subsequent requests. Choosing a large random string, such as a [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier), is a good idea.
To make a request idempotent, generate an idempotency key and send it in the `X-Idempotency-Key` header.
##### Example Request
```bash bash theme={null}
$ curl https://api.treasuryprime.com/ach \
-u "$API_KEY_ID:$API_KEY_VALUE" \
-H "X-Idempotency-Key: $RANDOM_STRING" \
-H 'Content-Type: application/json' \
-d '{
"account_id": "acct_123456",
"amount": "100.00",
"counterparty_id": "cp_098765",
"direction": "credit",
"sec_code": "ccd"
}'
```
## Request and Response Payloads
The payloads consumed and produced by the API are strictly [JSON](http://www.json.org/) encoded data or HTTP query parameters. To reflect this, you must provide `application/json` in the `Content-Type` HTTP header for most `POST` and `PUT` calls.
## Undocumented Fields
Treasury Prime follows the common practice of sometimes returning *more* JSON fields in the response than are shown in the documentation.
We do not recommend relying on the use of any undocumented fields that are returned in the API. These fields may be under deevelopment or may have restricted use cases that are subject to change.
## Filtering
When listing all existing API objects, the returned list appears in reverse chronological order, with the most recently created accounts appearing first. Optional filtering parameters are described below.
#### Listing and filtering objects
An API may have filterable fields that can be used to refine the listing of all given objects. For example, to find all ACH objects where the `status` field is set to `pending`, the corresponding field and value can be filtered using a query string in `parameter=value` format.
##### Definition
```bash bash theme={null}
GET <>/$OBJECT_PATH
```
Returns a list of objects with the optional filtering parameters applied.
##### Example Request
```bash bash theme={null}
$ curl https://api.treasuryprime.com/ach?status=pending" \
-u $API_KEY_ID:$API_KEY_VALUE
```
##### Example Response
```bash bash theme={null}
{
"data": [
{
"account_id": "acct_123",
"amount": "10.00",
"counterparty_id": "cp_123",
"created_at": "2018-10-30T23:57:11Z",
"description": null,
"direction": "credit",
"effective_date": "2018-10-30T23:57:11Z",
"id": "ach_1234567890",
"sec_code": "ccd",
"service": "standard",
"status": "pending",
"updated_at": "2018-10-30T23:57:11Z",
"userdata": null
},
{
"account_id": "acct_456",
"amount": "1.00",
"counterparty_id": "cp_456",
"created_at": "2018-10-30T23:57:09Z",
"description": null,
"direction": "credit",
"effective_date": "2018-10-30T23:57:09Z",
"id": "ach_1234567891",
"sec_code": "ccd",
"service": "standard",
"status": "pending",
"updated_at": "2018-10-30T23:57:09Z",
"userdata": null
}
],
"page_next": "https://api.treasuryprime.com/ach?page_cursor=acct_456"
}
```
## Pagination
When listing all existing API objects, the returned list appears in reverse chronological order, with the most recently created accounts appearing first. Optional pagination parameters are described below.
##### Definition
```bash bash theme={null}
GET https://api.treasuryprime.com/$OBJECT_PATH
```
| Parameter | Type | Required? | Description |
| ------------ | ------ | --------- | ------------------------------------------------------------------------------------------------------------------------ |
| page\_cursor | string | | Pagination cursor, value is the object ID. |
| page\_size | number | | Limits the number of objects in the returned list, value must be a number greater than or equal to 1. Defaults to `100`. |
| from\_date | string | | Lists the objects created on the date provided and onwards. Date must be in ISO 8601 format ("YYYY-MM-DD"). |
| to\_date | string | | Lists the objects created before the date provided. Date must be in ISO 8601 format ("YYYY-MM-DD"). |
Returns a list of objects with the optional pagination parameters applied.
##### Example Request
```bash bash theme={null}
$ curl "https://api.treasuryprime.com/counterparty?page_size=2&page_cursor=cp_10" \
-u $API_KEY_ID:$API_KEY_VALUE
```
##### Example Response
```bash bash theme={null}
{
"data": [
{
"ach": {
"account_number": "64141601",
"account_type": "checking",
"routing_number": "021001208"
},
"created_at": "2018-10-30T22:30:09Z",
"id": "cp_9",
"name": "John Smith",
"updated_at": "2018-10-30T22:30:09Z",
"userdata": null,
"wire": null
},
{
"ach": {
"account_number": "54545454",
"account_type": "checking",
"routing_number": "021001208"
},
"created_at": "2018-10-30T22:20:09Z",
"id": "cp_8",
"name": "Jane Doe",
"updated_at": "2018-10-30T22:20:09Z",
"userdata": null,
"wire": null
}
],
"page_next": "https://api.treasuryprime.com/counterparty?page_cursor=cp_8"
}
```
## User Data
All API resources have a field where you can attach arbitrary data. We refer to this arbitrary data as "user data," and you can access it via the `userdata` parameter.
User data is useful for storing additional, structured data along side an API object. For example, you may wish to store an ID or key that correlates an API object with a unique ID in your own application or database. User data is not used by Treasury Prime and won't be visible to your users (unless you expose it to them in your own application).
You may pass any arbitrary JSON object for `userdata`. The total size of the object, serialized, must be less than 1KB in size.
## Errors
The API uses [HTTP response codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) to indicate the success or failure of a request. Codes in the `2xx` range indicate success, codes in the `4xx` range indicate an error in your request, and codes in the `5xx` range indicate an error with Treasury Prime's servers or the backing bank systems. In particular, an HTTP 502 error most often indicates that the bank's core system is offline due to maintenance. Any asynchronous actions, such as book transfers, will be completed once the core system is back online. Please note that some API endpoints may return a `429` status code during times of high request volume, your application should be expected to implement some basic backoff and retry logic for this scenario. Some endpoints will return this status code as part of exceeding an account limit though, instances of this will be covered in those endpoints respectively.
In addition to the HTTP response code, most errors also include more detailed information about the problem in the response body. The detailed error message will be encoded in a JSON response under the `error` key.
##### Example Response
```bash bash theme={null}
{
"error": "Parameter 'amount' must be greater than '0'.
}
```