Skip to content
/payout-instructions

Talli Campaign Manager API (v2)

The Talli Campaign Manager API provides programmatic access to create and manage payout campaigns, payout instructions, and reports. This API powers the Talli console interface and can be integrated with third-party systems to automate workflows.

Key Resources

  • Campaigns: Create and manage fund distribution campaigns.
  • Campaign drafts: Create and manage campaign drafts.
  • Payout Instructions: Send and track payments to beneficiaries.
  • Payout Methods: View available payment methods (PayPal, ACH, gift cards, etc.).
  • Payouts: Details about selected payout
    • Gift Cards: View details of a gift card requested by the beneficiary
    • Prepaid Cards: View details of a prepaid card requested by the beneficiary
    • Transfers: View details of Paypal, Venmo or ACH transfer requested by the beneficiary
  • Reports: Access analytics and statistics about campaign performance.
  • Funds holders: Create and manage funds holders.
  • Templates: Create and manage templates.
  • Users: View members of your organization
  • Roles: View roles that can be assigned to members of your organization
  • Invitation: Create and manage invitations to your organization
  • Bank Accounts: Create and manage bank accounts.

Authentication

All requests require OAuth 2.0 authentication using Auth0 with appropriate scopes.

Download OpenAPI description
swagger.json
swagger.yaml
Overview
Talli API Support
api-support@talli.ai
License
Proprietary and Confidential
Languages
Servers
Mock server
https://docs.talli.ai/_mock/reference/swagger

campaigns

Endpoints for creating and managing campaigns. A campaign represents a distribution of funds to multiple beneficiaries.

Operations

payout-instructions

Endpoints for creating and managing payout instructions. A payout instruction represents an intention to pay a specific amount of money to a beneficiary.It is associated with one and only one campaign.

Operations

Get Payout Instructions

Request

Retrieves a paginated list of payout instructions, optionally filtered by campaign id, status, external id, or email. A payout instruction represents an intention to pay a specific amount of money to a beneficiary and is associated with exactly one campaign.

Security
oauth2(Required scopes:
Auth0Policy
payoutInstructions:view
)
Query
campaignIdstring(uuid)
statusinteger(int32)(Talli.Campaigns.Contracts.PayoutInstructionStatus)
Enum"Draft""Ready""PushInitiated""Initiated""InitiationFailed""PayoutMethodSelected""Requested""Restored""Reinitiated""ExpiryRequested"
externalIdstring
emailstring
pageNumberinteger(int32)required
pageSizeinteger(int32)required
curl -i -X GET \
  'https://docs.talli.ai/_mock/reference/swagger/v2/campaign-manager/payout-instructions?campaignId=497f6eca-6276-4993-bfeb-53cbbbba6f08&status=Draft&externalId=string&email=string&pageNumber=0&pageSize=0' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
pageNumberinteger(int32)
pageSizeinteger(int32)
totalPagesinteger(int32)read-only
totalItemsinteger(int32)
dataArray of objects(Talli.Api.Contracts.PayoutInstructions.PayoutInstructionResponse)
Response
application/json
{
  "pageNumber": 0,
  "pageSize": 0,
  "totalPages": 0,
  "totalItems": 0,
  "data": [
    { … }
  ]
}

Create Payout Instruction

Request

Creates a new payout instruction with the specified campaign and recipient details. Note that creating a payout instruction does not automatically send it to the beneficiary or allocate funds; it only records the intention to pay. The payout instruction must be explicitly initiated in a separate step to notify the beneficiary.

Security
oauth2(Required scopes:
Auth0Policy
payoutInstructions:create
)
Bodyapplication/jsonrequired
campaignIdstring(uuid)

The unique identifier of the campaign this payout instruction belongs to.

externalIdstring

An external identifier for this payout instruction, used for integration with client systems.

firstNamestring or null

The first name of the beneficiary.

lastNamestring or null

The last name of the beneficiary.

amountnumber or null(double)

The monetary amount of the payout instruction.

emailstring or null

The email address of the beneficiary. This is the primary contact method.

phoneNumberstring or null

The phone number of the beneficiary. May be required for certain payout methods.

curl -i -X POST \
  https://docs.talli.ai/_mock/reference/swagger/v2/campaign-manager/payout-instructions \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "campaignId": "13f8bf6d-dc27-4a04-bffe-6e5b13c19ddf",
    "externalId": "string",
    "firstName": "string",
    "lastName": "string",
    "amount": 0.1,
    "email": "string",
    "phoneNumber": "string"
  }'

Responses

Accepted

Response
No content

Get Payout Instruction

Request

Retrieves a single payout instruction based on provided identifier. Creating a payout instruction does not automatically distribute funds to the beneficiary; it requires subsequent initiation.

Security
oauth2(Required scopes:
Auth0Policy
payoutInstructions:view
)
Path
idstring(uuid)required
curl -i -X GET \
  'https://docs.talli.ai/_mock/reference/swagger/v2/campaign-manager/payout-instructions/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
payoutInstructionIdstring(uuid)

The unique identifier for the payout instruction.

campaignIdstring(uuid)

The identifier of the campaign this payout instruction belongs to.

amountnumber or null(double)

The monetary amount of the payout instruction.

firstNamestring or null

The first name of the beneficiary.

lastNamestring or null

The last name of the beneficiary.

emailstringrequired

The email address of the beneficiary. This is the primary contact method.

phoneNumberstring or null

The phone number of the beneficiary. May be required for certain payout methods.

statusinteger(int32)(Talli.Campaigns.Contracts.PayoutInstructionStatus)
Enum"Draft""Ready""PushInitiated""Initiated""InitiationFailed""PayoutMethodSelected""Requested""Restored""Reinitiated""ExpiryRequested"
cancellationReasoninteger(int32)(Talli.Common.Contracts.CancellationReason)
Enum"Unknown""BeneficiaryRequest""CampaignManagerRequest""EmailHardBounce""EmailSpamComplaint""UnsubscribedFromEmails""EmailScreeningFailed""CheckRequest"
selectedPayoutMethodIdstring or null(uuid)

The identifier of the payout method selected by the beneficiary, if any.

fulfilledOnstring or null(date-time)

The redemption date for this payout instruction if in fulfilled status

externalIdstringrequired

An external identifier for this payout instruction, used for integration with client systems.

nextReminderDatestring or null(date-time)

The next reminder date for this payout instruction if automatic reminders are enabled, otherwise null.

Response
application/json
{
  "payoutInstructionId": "50bfd130-22aa-4d88-8f54-fdfd65edbebb",
  "campaignId": "13f8bf6d-dc27-4a04-bffe-6e5b13c19ddf",
  "amount": 0.1,
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "phoneNumber": "string",
  "status": "Draft",
  "cancellationReason": "Unknown",
  "selectedPayoutMethodId": "16383abb-1273-48c1-bb89-96e94b64474f",
  "fulfilledOn": "2019-08-24T14:15:22Z",
  "externalId": "string",
  "nextReminderDate": "2019-08-24T14:15:22Z"
}

Update Payout Instruction

Request

Patches an existing payout instruction with the provided data. Note: This operation might be pefrormed only for payout instructions that have not been redeemed or requested. Note2: If the email is changed then the previous links get invalidated and the payout instruction moves back to Restored status.

Security
oauth2(Required scopes:
Auth0Policy
payoutInstructions:update
)
Path
idstring(uuid)required
Bodyapplication/jsonrequired
operationsArray of objects(Json.Patch.PatchOperation)
curl -i -X PATCH \
  'https://docs.talli.ai/_mock/reference/swagger/v2/campaign-manager/payout-instructions/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "operations": [
      {
        "op": "Unknown",
        "value": {
          "options": {
            "propertyNameCaseInsensitive": true
          },
          "parent": {},
          "root": {}
        }
      }
    ]
  }'

Responses

Accepted

Response
No content

Get Payout Instruction Activity

Request

Retrieves the complete activity history for a specific payout instruction, including status changes, notifications sent, and actions performed by both administrators and beneficiaries.

Security
oauth2(Required scopes:
Auth0Policy
payoutInstructions:view
)
Path
idstring(uuid)required
curl -i -X GET \
  'https://docs.talli.ai/_mock/reference/swagger/v2/campaign-manager/payout-instructions/{id}/activity' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/jsonArray [
messageIdstring or null(uuid)

Unique identifier for the activity message.

messageTypestring

Type of message associated with this activity.

timestampstring or null(date-time)

Date and time when the activity occurred.

typestring

Category or classification of the activity.

descriptionstring

Human-readable description of the activity.

detailsobject or null

Additional contextual information about the activity as key-value pairs.

]
Response
application/json
[
  {
    "messageId": "8540d774-4863-4d2b-b788-4ecb19412e85",
    "messageType": "string",
    "timestamp": "2019-08-24T14:15:22Z",
    "type": "string",
    "description": "string",
    "details": { … }
  }
]

Get Payout Instruction Payout

Request

Retrieves the payout details for a specific payout instruction. A payout is created when a beneficiary acts on a payout instruction and selects a specific payout method to receive their funds. The payout contains additional details specific to the chosen method, such as gift card identifiers or transaction references.

Security
oauth2(Required scopes:
Auth0Policy
payoutInstructions:view
)
Path
idstring(uuid)required
curl -i -X GET \
  'https://docs.talli.ai/_mock/reference/swagger/v2/campaign-manager/payout-instructions/{id}/payout' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
payoutInstructionIdstring(uuid)

The unique identifier of the payout instruction associated with this payout.

payoutMethodIdstring(uuid)

The unique identifier of the payout method used for this payout.

statusinteger(int32)(Talli.Campaigns.Contracts.PayoutInstructionStatus)
Enum"Draft""Ready""PushInitiated""Initiated""InitiationFailed""PayoutMethodSelected""Requested""Restored""Reinitiated""ExpiryRequested"
requestedOnstring or null(date-time)

The date and time when the payout was requested by the beneficiary.

completedOnstring or null(date-time)

The date and time when the payout was completed successfully.

externalIdentifiersobject or null

External identifiers related to the payout, specific to the payment method (e.g., transaction IDs, payment references).

Response
application/json
{
  "payoutInstructionId": "50bfd130-22aa-4d88-8f54-fdfd65edbebb",
  "payoutMethodId": "fff005d3-ebdd-48cc-8c82-62336a6c32d0",
  "status": "Draft",
  "requestedOn": "2019-08-24T14:15:22Z",
  "completedOn": "2019-08-24T14:15:22Z",
  "externalIdentifiers": {
    "property1": "string",
    "property2": "string"
  }
}

Initiate Payout Instruction

Request

Initiates the payout process for a specific payout instruction using the specified notification channel. This action allocates funds from the associated campaign to this payout instruction and sends the initial notification to the beneficiary, allowing them to claim their funds.

Security
oauth2(Required scopes:
Auth0Policy
payoutInstructions:initiate
)
Path
idstring(uuid)required
Bodyapplication/jsonrequired
channelstring

A channel that is used to deliver the Payout Instruction. Valid values are 'email' and 'none' (none will not actually perform any action)

curl -i -X POST \
  'https://docs.talli.ai/_mock/reference/swagger/v2/campaign-manager/payout-instructions/{id}/:initiate' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "channel": "string"
  }'

Responses

Accepted

Response
No content

Cancel Payout Instruction

Request

Cancels a specific payout instruction with the provided cancellation reason. This halts the payout process and prevents the beneficiary from claiming the funds. If funds were already allocated, they will be returned to the campaign budget.

Security
oauth2(Required scopes:
Auth0Policy
payoutInstructions:cancel
)
Path
idstring(uuid)required
Bodyapplication/jsonrequired
cancellationReasonstring

Reason for Payout Instruction Cancelation, valid values are: BeneficiaryRequest, CampaignManagerRequest, 'EmailHardBounce', 'EmailSpamComplaint', 'UnsubscribedFromEmails', 'EmailScreeningFailed'

curl -i -X POST \
  'https://docs.talli.ai/_mock/reference/swagger/v2/campaign-manager/payout-instructions/{id}/:cancel' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "cancellationReason": "string"
  }'

Responses

Accepted

Response
No content

Try Restore Payout Instruction

Request

Attempts to restore a payout instruction when a payment was requested but not successfully processed (e.g., a PayPal transfer that the beneficiary hasn't accepted). This action attempts to cancel the pending external payout and return the beneficiary to a state where they can select a different payout method and process their payout again.

Security
oauth2(Required scopes:
Auth0Policy
payoutInstructions:tryRestore
)
Path
idstring(uuid)required
curl -i -X POST \
  'https://docs.talli.ai/_mock/reference/swagger/v2/campaign-manager/payout-instructions/{id}/:try-restore' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Accepted

Response
No content

Send Payout Instruction Reminder

Request

Sends a reminder notification to the beneficiary about their pending payout instruction. This can be used when a beneficiary has not claimed their funds after the initial notification was sent.

Security
oauth2(Required scopes:
Auth0Policy
payoutInstructions:sendReminder
)
Path
idstring(uuid)required
Bodyapplication/jsonrequired
object(Talli.App.Models.Requests.SendPayoutInstructionReminderRequest)
curl -i -X POST \
  'https://docs.talli.ai/_mock/reference/swagger/v2/campaign-manager/payout-instructions/{id}/:send-reminder' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

Accepted

Response
No content

payout-methods

Endpoints for viewing and managing available payout methods, such as ACH, PayPal, and gift cards.

Operations

reports

Endpoints for accessing analytics and reporting data about campaigns and payouts.

Operations

ach-transfers

Endpoints for managing ACH bank transfers as a payout method.

Operations

gift-cards

Endpoints for managing gift card payouts and retrieving gift card details.

Operations

paypal-transfers

Endpoints for managing PayPal payouts and retrieving PayPal transfer details.

Operations

prepaid-cards

Endpoints for managing prepaid card payouts and retrieving prepaid card details.

Operations

venmo-transfers

Endpoints for managing Venmo transfers and retrieving Venmo transaction details.

Operations

funds-holders

Represents an account connected to a business entity that can be used as a source of funds for one or multiple campaigns. Each funds holder corresponds to a separate bank account in our payment system and maintains it's own banking details and fund management capabilities

Operations

users

Endpoints to view members of your organization

Operations

roles

Endpoints to view roles that can be assigned to members of your organization

Operations

invitations

Endpoints used to send invite emails to members of your organizationpayment system and maintains it's own banking details and fund management capabilities.

Operations

bank-accounts

Endpoints for creating and managing bank accounts.

Operations

campaign-drafts

Operations

templates

Operations