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.

• 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

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

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

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

Your Talli representative will provide you with the following:

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.

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

Example:

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

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

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

HTTP Status code summary

Error responses are returned as ProblemDetails objects, the format defined by RFC 7807. Every error body includes type, title, status, and detail. 5xx responses also include a requestId, which you can send over to support.

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

A 500 never carries the underlying error text - the body is always the fixed shape below, and the requestId is what lets support find the failing request:

{
    "type": "https://tools.ietf.org/html/rfc9110#section-15.6.1",
    "title": "An error occurred",
    "status": 500,
    "detail": "An unexpected error occurred. Quote requestId when contacting Talli support.",
    "errorCode": "INTERNAL_ERROR",
    "requestId": "0HN7Q9V2D2L0J:00000004"
}

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:

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

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.

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.

  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.

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

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.

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

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.

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 body, consistent with the API's other error responses:

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

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.

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.

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:

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

You can check most recent changes done to the API in the Changelog