Talli API: Getting Started Guide

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.

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

The two surfaces share the same underlying data and authentication.

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

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

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.

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"
}

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

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

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 — recommended for new integrations
• Campaign Manager (v2) Quickstart

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

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