## Overview

Get familliar with Talli API fundamentals, including how the API is organised, how authentication works, and how we handle errors, pagination, rate limiting and versioning.

Talli API is built on **REST** principles, lets you programmatically manage **Distributions to beneficiaries** - this includes creating distributions, sending payout instructions, querying balances and bank accounts and pulling reports

It is a machine-to-machine (M2M) API. Your app calls Talli directly over HTTPS with no browser or end-user in the loop.

### Conventions

- **Transport**: HTTPS only, Plain HTTP requests are rejected.
- **Encoding**: All requests and responses use 'UTF-8'.
- **Content type**: 'application/json' for request and response bodies, unless an endpoint explicitly accepts or returns another type (e.g. report endponts accept 'text/csv' to stream a CSV file)
- **Timestamps**: ISO 8601 in UTC
- **ID's**: Resource identifiers are UUID strings
- **Monetary Format**: Amounts are returned as decimal numbers in the currency's major unit (e.g '12.50' for USD $12.50), as of this moment, only USD is supported


### Base URL

| Environment | Base URL |
|  --- | --- |
| Production | `https://api.talli.ai` |
| Sandbox | Provided by your Talli representative |


All requests are made against the base URL plus the versioned-prefixed path of the API surface that you're using.

### API surfaces

Talli exposes a single public API surface for customer-facing integrations:

| Surface | Base path |
|  --- | --- |
| **Distribution Manager (v3)** | `/v3/distribution-manager/` |


## Authentication

Talli API uses the **OAuth 2.0 Client Credentials Flow** for authentication. This process involves exchanging your Client ID and Client Secret for a temporary bearer access token. Authentication is identical across all Talli API surfaces

### Credentials

Your Talli representative will provide you with the following:

| Credential | Description | Example (for illustration only) |
|  --- | --- | --- |
| `Token URL` | The endpoint for requesting access tokens. | `https://[your-tenant].us.auth0.com/oauth/token` |
| `Client ID` | Your application's unique public identifier. | `aBcDeFgHiJkLmNoPqRsTuVwXyZ` |
| `Client Secret` | Your application's secret key. **Treat this like a password.** | `123-very-secret-key-456` |
| `Audience` | The unique identifier for the Talli API. | `https://api.talli.ai` |


Keep secrets out of source control. Store them in a dedicated secret management service (e.x. AWS Secrets Manager, Vault, or Google Secret Manager) and inject them into your application at runtime.

### Requesting an access token

To get your token, make a `POST` request to the `Token URL`.

br
**Example:**

cURL
```bash
curl --request POST \
  --url https://<your-tenant>.us.auth0.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "https://api.talli.ai",
    "grant_type": "client_credentials"
  }'
```

Python
```python
import requests

response = requests.post(
    "https://<your-tenant>.us.auth0.com/oauth/token",
    json={
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET",
        "audience": "https://api.talli.ai",
        "grant_type": "client_credentials",
    },
    timeout=10,
)
response.raise_for_status()
token = response.json()["access_token"]
```

Node
```javascript
const response = await fetch(
  "https://<your-tenant>.us.auth0.com/oauth/token",
  {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({
      client_id: "YOUR_CLIENT_ID",
      client_secret: "YOUR_CLIENT_SECRET",
      audience: "https://api.talli.ai",
      grant_type: "client_credentials",
    }),
  }
);
const { access_token: token } = await response.json();
```

**Response:**

If your credentials are correct, you will receive a JSON response containing your access token.

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIs...",
  "expires_in": 36000,
  "token_type": "Bearer"
}
```

**Important: Handling Your Access Token**

* **Store it securely:** The `access_token` is the key to accessing the API. Store it in a secure but temporary location (e.g., in-memory cache).
* **It's a Bearer Token:** You will use this token in the `Authorization` header of all subsequent API requests.
* **It Expires:** The `expires_in` field indicates the token's lifetime in seconds (e.g., 36000 seconds = 10 hours). Your application should reuse this token until it is close to expiring, at which point you should request a new one. **Please do not request a new token for every API call.**


## Error Handling

Talli API uses standard HTTP response codes to indicate the success or failure of an API request.

**HTTP Status code summary**

| Code | Meaning |
|  --- | --- |
| `200 OK` | Request succeeded. |
| `201 Created` | A 'POST' that creates the resource. The response body contains the created resource |
| `202 Accepted` | The request was validated and queued for asynchronous processing. |
| `204 No Content` | A successful write that returns no body, typically a delete or an update without a response payload. |
| `400 Bad Request` | The request is malformed, fails validation, or violates a business rule (e.g. invalid paging, missing required field) |
| `401 Unauthorized` | Your access token is missing, expired, or wasn't issued by Talli. Re-authenticate at the token endpoint. |
| `403 Forbidden` | Token is valid but lacks the permission required for this endpoint. |
| `404 Not Found` | The resource does not exist, **or** it exists but belongs to a different organization. |
| `409 Conflict` | Request conflicts with the resource's current state (e.g. payout instruction cannot transition from its current state). |
| `429 Too Many Requests` | Rate limit exceeded - see [Rate Limits](#15-rate-limits). |
| `500 Internal Server Error` | Something went wrong on our side. The response body includes a `requestId` - share it with support and we can trace the request. |


Error responses are returned as ProblemDetails objects, the format defined by [RFC 7807](https://www.rfc-editor.org/rfc/rfc7807). Every error body includes type, title, status, and detail. 5xx responses also include a requestId, which you can send over to support.

```json
{
    "type": "Not Found",
    "title": "An error occurred while processing your request.",
    "status": 404,
    "detail": "Payout instruction with id 1a2b3c4d-e5f6-7890-1234-567890abcdef was not found"
}
```

| Field | Description |
|  --- | --- |
| `type` | Stable URI identifying the error class. |
| `title` | Short, human-readable summary. |
| `status` | HTTP status code. |
| `detail` | Readable explanation of *this* occurrence. |
| `requestId` | Correlates to a single request in Talli's logs. **Include in support tickets.** |
| `traceId` | Distributed-trace identifier across our services. |


**Validation errors**

For 400 validation failures from invalid request bodies/query strings, the response follows RFC 7807's validation extension and includes per-field error messages under errors:

```json
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"errors": {
    "bankAccountId": [
    "Bank account is still Pending — wait for activation before promoting the draft."
    ],
    "description": [
    "The 'description' field must not exceed 512 characters."
    ]
},
"requestId": "0HN7Q9V2D2L0J:00000004"
}
```

br
**Reporting errors to support**

Capture and include the requestId (and traceId when present) when contacting support@talli.ai, it lets us jump directly to the failing request in our logs.

## Pagination

Talli API list methods let you retrieve collections of resources, e.g. such as listing distributions, payout instructions or bank accounts. These methods share a common structure, taking at least 'pageNumber' and 'pageSize' as query parameters.

### Request parameters

| Parameter | Type | Default | Description |
|  --- | --- | --- | --- |
| `pageNumber` | integer | `1` | 1-indexed page to return. |
| `pageSize` | integer | `20` | Items per page. Max varies by endpoint (commonly `100`; `1000` for report exports). |


```bash
  curl --request GET \
    --url 'https://api.talli.ai/v3/distribution-manager/distributions?pageNumber=1&pageSize=20' \
    --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Both parameters are typically required, meaning callers should always specify them.
Some list methods additionally accept sortBy and sortDirection (Asc | Desc); valid sortBy values are per-endpoint enums documented in the API Reference.

### Response structure

| Field | Description |
|  --- | --- |
| `pageNumber` | Derived from the request. |
| `pageSize` | Derived from the request. |
| `totalPages` | Total pages available for the current filter set. |
| `totalItems` | Total items across all pages. |
| `data` | The page contents, an array of the resource type for that endpoint. |


```json
{
    "pageNumber": 1,
    "pageSize": 20,
    "totalPages": 5,
    "totalItems": 87,
    "data": [
      {
        "id": "1a2b3c4d-e5f6-7890-1234-567890abcdef",
        "name": "Q2 Field Marketing Distribution",
        "businessEntity": "Talli"
      }
    ]
  }
```

## Rate Limits

The Talli API enforces rate limits to protect the platform from accidental overload and abuse. Limits are applied **per organization**, so other customer's traffic never affects your budget. Rate limits are scoped **per endpoint group** — different endpoints can have different limits.

### Reading your usage

Every response from a rate-limited endpoint includes these headers, so you can monitor your usage proactively without waiting to be throttled:

| Header | Description |
|  --- | --- |
| `X-RateLimit-Limit` | The maximum number of requests allowed in the current window for this endpoint. |
| `X-RateLimit-Remaining` | The number of requests still available in the current window. |
| `X-RateLimit-Reset` | The time the window resets, as a Unix timestamp (seconds since the epoch, UTC). |


We recommend reading `X-RateLimit-Remaining` and backing off as it approaches `0`, rather than waiting for a `429`.

> The exact limit for any endpoint is always reported in its `X-RateLimit-Limit` header — treat that
header as the source of truth rather than hard-coding the values above, as limits may be tuned over time.


### Exceeding the limit

If you exceed a limit, the API responds with **`429 Too Many Requests`**. The response includes:

- A **`Retry-After`** header - the number of seconds to wait before retrying.
- The same `X-RateLimit-` headers (with `X-RateLimit-Remaining: 0`).
- A [Problem Details](https://www.rfc-editor.org/rfc/rfc9457) body, consistent with the API's other error responses:


```json
{
  "type": "https://tools.ietf.org/html/rfc6585#section-4",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded. Please retry later.",
  "instance": "POST /v3/distribution-manager/payout-instructions/{id}/:initiate",
  "requestId": "0HN…"
}
```

### Endpoint limits

The table below lists the **current** limits. All limits are per organization and use a **sliding
window** (e.g. "60 / minute" means no more than 60 requests in any rolling 60-second period). In the
routes below, `…` stands for `/v3/distribution-manager` Url prefix.

| Endpoint(s) | Limit |
|  --- | --- |
| **Default** — every public API endpoint not listed below | **60 / minute** |
| `POST …/payout-instructions/{id}/:initiate` | **20 / minute** |
| `POST …/payout-instructions/{id}/:reinitiate` | **20 / minute** |
| `POST …/payout-instructions/{id}/:send-reminder` | **20 / minute** |
| `POST …/templates/:send-preview` | **50 / day** |


**Singular live-send endpoints** (`:initiate` / `:reinitiate` / `:send-reminder`) carry the tighter
**20 / minute** limit because each call triggers an outbound email to a beneficiary. The
`templates/:send-preview` endpoint, which sends a live test email, is capped at **50 / day**.

For high-volume distribution, use the **bulk** endpoints (`…/payout-instructions/:initiate` and
`…/:send-reminders` at the distribution level) rather than scripting many singular calls.

## Versioning

Talli versions the API in the URL path segment. Versions are major-version-only, meaning there are no minor versions like v3.1.

**Currently** supported versions:

| Version | Surface | Status |
|  --- | --- | --- |
| `v3` | Distribution Manager | **Current** and recommended. |


### Backwards-compatible changes

We may make the following changes within a major version without advance notice:

- Adding new endpoints.
- Adding new optional request fields.
- Adding new fields to response bodies.
- Adding new enum values.
- Adding new HTTP headers.
- Adding new optional query parameters.



> Tip: Build your integration to ignore fields it does not recognize.


### Breaking changes

Breaking changes require a new major version. We treat the following as **breaking**:

- Removing or renaming an endpoint, field, or enum value.
- Changing the type of an existing field.
- Changing authentication or authorization requirements.


br
> You can check most recent changes done to the API in the [Changelog](/docs/changelog/changelog)