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.

2. Prerequisites

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

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):

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.

{
  "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.

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:

{
  "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.

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.

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.