# Talli Campaign Manager API: Getting Started Guide

## 1. Overview

Welcome to the Talli Campaign Manager API! This API provides programmatic access to create and manage payout campaigns, payout instructions, and reports. It is designed for machine-to-machine (M2M) communication to integrate your systems with the Talli platform and automate your workflows.

This guide will walk you through the essential steps to authenticate and make your first API calls.

### Key API Resources

The Campaign Manager API is organized around several key resources:

* **Campaigns**: Create and manage fund distribution campaigns.
* **Payout Instructions**: Send, manage, and track individual payments to beneficiaries.
* **Payout Methods**: View available payment methods (e.g., PayPal, ACH, Gift Cards).
* **Payouts**: Get details about a specific payout once a beneficiary has selected a method (e.g., gift card codes, transfer status).
* **Reports**: Access analytics and statistics about your campaign performance.


For a complete list of endpoints and detailed schema information, please refer to our interactive **[API Reference](https://docs.talli.ai/getting-started)**.

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


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

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

### Example: Listing Your Campaigns

This `cURL` command retrieves a paginated list of your campaigns.


```bash
curl --request GET \
  --url [Your API Base URL]/v2/campaign-manager/campaigns \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

A successful response will look like this:


```json
{
  "pageNumber": 1,
  "pageSize": 20,
  "totalItems": 1,
  "data": [
    {
      "id": "1a2b3c4d-e5f6-7890-1234-567890abcdef",
      "name": "Your Campaign Name",
      "businessEntity": "Talli",
      // ... other campaign fields
    }
  ]
}
```

## 5. A Complete Workflow: Downloading a Report

Here is a practical, multi-step example of how to download a basic CSV report for a specific campaign.

#### A. Get Your Access Token

Follow the process in **Request an Access Token** to get a valid `access_token`.

#### B. Find Your Campaign ID

First, list your campaigns to find the ID of the one you want a report for.


```bash
curl --request GET \
  --url [Your API Base URL]/v2/campaign-manager/campaigns \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

From the response, copy the `id` of the desired campaign (e.g., `1a2b3c4d-e5f6-7890-1234-567890abcdef`).

#### C. Download the Campaign Report

Now, use that campaign ID to request the report. Note the use of `--output` to save the file and the `accept` header to specify the CSV format.


```bash
curl --request GET \
  --url '[Your API Base URL]/v2/campaign-manager/reports/campaigns/YOUR_CAMPAIGN_ID/basic?pageNumber=1&pageSize=1000' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: text/csv' \
  --output campaign_report.csv
```

*Replace `YOUR_CAMPAIGN_ID` with the ID you copied.*

This will save a `campaign_report.csv` file in your current directory.

## 6. 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 (e.g., a specific campaign) 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.


## 7. Support

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