# Talli API: Getting Started Guide

## 1. Overview

Welcome to the Talli API! Talli provides programmatic access to manage payouts to beneficiaries — distributing funds, sending payout instructions, and pulling reports. The API is designed for machine-to-machine (M2M) communication to integrate your systems with the Talli platform and automate your workflows.

This guide covers the steps that apply to **any** Talli API surface — getting credentials, authenticating, making requests, and handling errors. For surface-specific examples, see the Quickstarts.

### Which API should I use?

Talli exposes two API surfaces, both backed by the same platform:

| Surface | Base path | When to use |
|  --- | --- | --- |
| **Distribution Manager** (v3) | `/v3/distribution-manager/` | **Recommended for new integrations.** Current naming and DTOs. |
| Campaign Manager (v2) | `/v2/campaign-manager/` | Existing integrations using "campaign" terminology. Fully supported. |


The two surfaces share the same underlying data and authentication. v3 renames `campaign` to `distribution` across routes, request/response fields, and required permissions; functionality is otherwise identical. Pick one — you don't need both.

### Key concepts

* **Distributions / Campaigns**: A grouping of payouts to many beneficiaries (same concept, different name in v2 vs v3).
* **Payout Instructions**: Individual payments to beneficiaries within a distribution.
* **Payout Methods**: How a beneficiary receives funds (e.g., PayPal, ACH, Gift Cards).
* **Payouts**: Concrete details of a payout once the beneficiary has chosen a method.
* **Reports**: Analytics and CSV exports of distribution performance.


For complete endpoint and schema details, see the **API Reference** section in the sidebar.

## 2. Prerequisites

Before you begin, ensure you have the following credentials provided by your Talli representative:

| Credential | Description | Example (for illustration only) |
|  --- | --- | --- |
| `API Base URL` | The root URL for all API requests. | `https://api.talli.ai` |
| `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` |


## 3. Authentication: Obtaining an Access Token

The 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 access token. Authentication is identical across all Talli API surfaces — the same token works for both v2 and v3.

### Request an Access Token

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

**Request (`cURL` example):**


```bash
curl --request POST \
  --url [Your Token URL] \
  --header 'content-type: application/json' \
  --data '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "YOUR_API_AUDIENCE",
    "grant_type": "client_credentials"
  }'
```

**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. **Do not request a new token for every API call.**


## 4. Making API Calls

Once you have an access token, you can start interacting with the Talli API.

### Include the Authorization Header

For every API request, you must include the `Authorization` header with your access token, prefixed by `Bearer `.

`Authorization: Bearer YOUR_ACCESS_TOKEN`

For your first concrete request, follow the **Quickstart** for whichever surface you've chosen:

* **[Distribution Manager (v3) Quickstart](/docs/quickstart-distributions)** — recommended for new integrations
* [Campaign Manager (v2) Quickstart](/docs/quickstart-campaigns)


## 5. Error Handling & Best Practices

* **Common Status Codes:**
  * `200 OK`: The request was successful.
  * `202 Accepted`: The request was accepted for processing (common for asynchronous operations).
  * `400 Bad Request`: The request was malformed (e.g., invalid parameters). Check the response body for details.
  * `401 Unauthorized`: Your access token is missing, invalid, or expired. Request a new token and retry.
  * `403 Forbidden`: Your token is valid, but you don't have the required permissions for this action.
  * `404 Not Found`: The resource you requested does not exist.
* **Rate Limiting:** The API is rate-limited. If you receive a `429 Too Many Requests` error, slow down your requests.
* **Best Practices:**
  * Implement retry logic with exponential backoff for transient network errors or `5xx` server errors.
  * Never hardcode your `client_id` or `client_secret` in your application's source code. Use a secure secret management system.


## 6. Support

If you have questions or require technical assistance, please contact our API support team at **support@talli.ai**.