Skip to content
/campaigns

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

Get Campaigns

Request

Retrieves a paginated list of campaigns, optionally filtered by a payout instruction ID. To include details about total funds received and statistics on the statuses of the payout instructions, use 'includeDetails' flag.

Security
oauth2(Required scopes:
Auth0Policy
campaigns:view
)
Query
pageNumberinteger(int32)
Default 1
pageSizeinteger(int32)
Default 20
payoutInstructionIdstring(uuid)
includeDetailsboolean
Default false
curl -i -X GET \
  'https://docs.talli.ai/_mock/reference/swagger/v2/campaign-manager/campaigns?pageNumber=1&pageSize=20&payoutInstructionId=497f6eca-6276-4993-bfeb-53cbbbba6f08&includeDetails=false' \
  -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.Campaigns.CampaignWithDetailsResponse)
Response
application/json
{
  "pageNumber": 0,
  "pageSize": 0,
  "totalPages": 0,
  "totalItems": 0,
  "data": [
    { … }
  ]
}

Create Campaign

Request

Creates a new campaign with the specified data.

Security
oauth2(Required scopes:
Auth0Policy
campaigns:create
)
Body
namestringrequired
fundsHolderIdstring(uuid)required
welcomeHeadlinestringrequired
campaignDescriptionstring or null
campaignManagerstring or null
welcomeTextstringrequired
iconFilestring(binary)required
payoutMethodIdsArray of strings(uuid)
expiryDatestring or null(date)
displayEndDatestring or null(date)
otpThresholdAmountnumber or null(double)
emailTemplatesobject
automaticRemindersinteger(int32)(Talli.Common.Contracts.AutomaticReminders)
Enum"None""FixedIntervals"
curl -i -X POST \
  https://docs.talli.ai/_mock/reference/swagger/v2/campaign-manager/campaigns \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: multipart/form-data' \
  -F name=string \
  -F fundsHolderId=2c85db19-8b75-41b7-bf11-7a1e38a04654 \
  -F welcomeHeadline=string \
  -F campaignDescription=string \
  -F campaignManager=string \
  -F welcomeText=string \
  -F iconFile=string \
  -F payoutMethodIds=497f6eca-6276-4993-bfeb-53cbbbba6f08 \
  -F expiryDate=2019-08-24 \
  -F displayEndDate=2019-08-24 \
  -F otpThresholdAmount=0.1 \
  -F 'emailTemplates[property1]=497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -F 'emailTemplates[property2]=497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -F automaticReminders=None

Responses

Accepted

Response
No content

Patch Campaign

Request

Patches an existing campaign with the provided data. Note: The icon needs to be patched separately.

Security
oauth2(Required scopes:
Auth0Policy
campaigns:edit
)
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/campaigns/{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 Campaign

Request

Retrieves a single campaign based on provided identifier

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

Responses

OK

Bodyapplication/json
idstring(uuid)

The unique identifier for the campaign.

namestring

The name of the campaign.

fundsHolderIdstring(uuid)

The funds holder associated with the campaign.

welcomeHeadlinestring or null

The welcome headline text that will be displayed in the application welcome screen.

campaignDescriptionstring or null

The campaign description of the campaign.

campaignManagerstring or null

The name of the campaign manager.

welcomeTextstring or null

The welcome text that will be displayed in the application welcome screen.

iconUrlstring or null

URL to the campaign's icon image that will be displayed in the application welcome screen.

payoutMethodsArray of objects(Talli.Api.Contracts.Campaigns.CampaignPayoutMethodResponse)

Available payout methods for this campaign.

expiryDatestring or null(date)

The date when the campaign expires.

displayEndDatestring or null(date)

The date informing beneficiaries when is the end of the campaign.

creationDatestring(date)

The date when the campaign was created.

emailTemplatesobject

The dictionary containing the template ids for given template type.If template type is not provided, the default template will be used.

automaticRemindersinteger(int32)(Talli.Common.Contracts.AutomaticReminders)
Enum"None""FixedIntervals"
otpThresholdAmountnumber or null(double)

The threshold amount below which OTP verification is skipped. Maximum value is $250.

fromEmailstring or null
Response
application/json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "fundsHolderId": "2c85db19-8b75-41b7-bf11-7a1e38a04654",
  "welcomeHeadline": "string",
  "campaignDescription": "string",
  "campaignManager": "string",
  "welcomeText": "string",
  "iconUrl": "string",
  "payoutMethods": [
    { … }
  ],
  "expiryDate": "2019-08-24",
  "displayEndDate": "2019-08-24",
  "creationDate": "2019-08-24",
  "emailTemplates": {
    "InitiateEmail": "503f450d-21f7-4241-8734-82f102b59ff5",
    "ReminderEmail": "03f0f4e9-1347-456b-b068-11b85982c26d",
    "FailureReinitiateEmail": "207ac805-d6ae-4273-ab26-39cbfcc79f64",
    "OtpEmail": "a3326353-6367-4e5f-8f06-0ff770a372f8",
    "PushEmail": "42bd2676-4464-4f74-b80c-1dd80b6a2e4d",
    "InternalRequest": "2e712ba9-0e40-4e8e-bbf9-1bfe2bf89194"
  },
  "automaticReminders": "None",
  "otpThresholdAmount": 0.1,
  "fromEmail": "string"
}

Patch Campaign icon

Request

Patches an existing campaign with the provided icon file.

Security
oauth2(Required scopes:
Auth0Policy
campaigns:edit
)
Path
idstring(uuid)required
Bodymultipart/form-data
iconFilestring(binary)required
curl -i -X PATCH \
  'https://docs.talli.ai/_mock/reference/swagger/v2/campaign-manager/campaigns/{id}/campaign-icon' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: multipart/form-data' \
  -F iconFile=string

Responses

Accepted

Response
No content

Upload a file with payout instructions

Request

Uploads a file with payout instructions to the given campaign. The maximum size of the file is 262144000 bytes

Security
oauth2(Required scopes:
Auth0Policy
payoutInstructions:create
payoutInstructions:update
)
Path
idstring(uuid)required
Bodymultipart/form-data
filestring(binary)required
curl -i -X POST \
  'https://docs.talli.ai/_mock/reference/swagger/v2/campaign-manager/campaigns/{id}/payout-instructions/:upload' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: multipart/form-data' \
  -F file=string

Responses

Accepted

Response
No content

Download a sample beneficiaries file

Request

Retrieves a sample beneficiaries file in the expected format

Security
oauth2(Required scopes:
Auth0Policy
payoutInstructions:view
campaigns:view
)
Query
sizeinteger(int32)
Default 20
curl -i -X GET \
  'https://docs.talli.ai/_mock/reference/swagger/v2/campaign-manager/campaigns/payout-instructions/:get-sample-file?size=20' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Accepted

Response
No content

Send reminders for given campaign

Request

Sends reminders for a given campaign. The endpoint allows send reminders either to the specified list of IDs or to payout instructions in the specified statuses. If neither of the above is specified, reminders will be sent to the payout instructions that have not been excluded, requested or fulfilled. If the list of ids is specified, you can also schedule the sending window with the 'distributionPeriodInSeconds' parameter. The schedule window will be automatically calculated based on the number of payout instructions found.

Security
oauth2(Required scopes:
Auth0Policy
campaigns:sendReminders
)
Path
campaignIdstring(uuid)required
Bodyapplication/jsonrequired
payoutInstructionIdsArray of strings or null(uuid)
distributionPeriodInSecondsinteger or null(int32)
numberOfPayoutInstructionsToSendinteger or null(int32)
dryRunboolean
curl -i -X POST \
  'https://docs.talli.ai/_mock/reference/swagger/v2/campaign-manager/campaigns/{campaignId}/payout-instructions/:send-reminders' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "payoutInstructionIds": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
    "distributionPeriodInSeconds": 0,
    "numberOfPayoutInstructionsToSend": 0,
    "dryRun": true
  }'

Responses

OK

Bodyapplication/json
dryRunboolean
detailsobject(Talli.Campaigns.Contracts.Responses.CampaignManager.SendCampaignRemindersResponseDetails)
Response
application/json
{
  "dryRun": true,
  "details": {
    "batchId": "5579c111-9c50-47e2-af92-f16d52e63189",
    "count": 0,
    "items": [ … ]
  }
}

Initiate payout instructions

Request

Initiates payout instructions from given campaign.

Security
oauth2(Required scopes:
Auth0Policy
payoutInstructions:initiate
)
Path
campaignIdstring(uuid)required
Bodyapplication/jsonrequired
countinteger or null(int32)
payoutInstructionsArray of strings or null(uuid)
channelstring
distributionPeriodInSecondsinteger or null(int32)
preventPartialEmailSelectionboolean
dryRunboolean
filterByEmailProviderstring or null
curl -i -X POST \
  'https://docs.talli.ai/_mock/reference/swagger/v2/campaign-manager/campaigns/{campaignId}/payout-instructions/:initiate' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "count": 0,
    "payoutInstructions": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
    "channel": "string",
    "distributionPeriodInSeconds": 0,
    "preventPartialEmailSelection": true,
    "dryRun": true,
    "filterByEmailProvider": "string"
  }'

Responses

OK

Bodyapplication/json
dryRunboolean
notSentobject(Talli.Campaigns.Contracts.Responses.CampaignManager.InitiateCampaignNotSentResponse)
sentobject(Talli.Campaigns.Contracts.Responses.CampaignManager.InitiateCampaignSentResponse)
totalAmountnumber(double)
Response
application/json
{
  "dryRun": true,
  "notSent": {
    "isPreventPartialEmailSelectionActive": true,
    "count": 0,
    "email": "string",
    "payoutInstructionIds": [ … ]
  },
  "sent": {
    "isScheduled": true,
    "batchId": "5579c111-9c50-47e2-af92-f16d52e63189",
    "count": 0,
    "filterByEmailProvider": "string",
    "items": [ … ]
  },
  "totalAmount": 0.1
}

Set password for given campaign

Request

Allows to set a password for the campaign. From that moment on, each beneficiary will be asked to enter the password when attempting to redeem funds. Once set, the password cannot be removed, it can only be changed.

Security
oauth2(Required scopes:
Auth0Policy
campaigns:setPassword
)
Path
campaignIdstring(uuid)required
Bodyapplication/jsonrequired
campaignPasswordstring
curl -i -X POST \
  'https://docs.talli.ai/_mock/reference/swagger/v2/campaign-manager/campaigns/{campaignId}/:set-password' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "campaignPassword": "string"
  }'

Responses

Accepted

Response
No content

Get Bank account

Request

Retrieves a single bank account based on provided campaign identifier

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

Responses

OK

Bodyapplication/json
idstring(uuid)

The unique identifier for the bank account.

campaignIdstring(uuid)

The unique identifier for the campaign.

balancenumber(double)

Total balance in the bank account.

availableBalancenumber(double)

Available balance in the bank account.

allocatedBalancenumber(double)

Allocated balance in the bank account.

unallocatedBalancenumber(double)

Unallocated balance in the bank account.

routingNumberstring

The routing number for the bank account.

accountNumberstring

The account number for the bank account.

accountNamestring

The account name for the bank account.

addressobject(Talli.Api.Contracts.Campaigns.BankAccountAddressResponse)
creationDatestring(date)

The date when the bank account was created.

Response
application/json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "campaignId": "13f8bf6d-dc27-4a04-bffe-6e5b13c19ddf",
  "balance": 0.1,
  "availableBalance": 0.1,
  "allocatedBalance": 0.1,
  "unallocatedBalance": 0.1,
  "routingNumber": "string",
  "accountNumber": "string",
  "accountName": "string",
  "address": {
    "address1": "string",
    "address2": "string",
    "city": "string",
    "state": "string",
    "postalCode": "string",
    "country": "string"
  },
  "creationDate": "2019-08-24"
}

Get Return External Accounts

Request

Retrieves a list of return external accounts for particular campaign

Security
oauth2(Required scopes:
Auth0Policy
campaigns:view
)
Path
idstring(uuid)required
Query
pageNumberinteger(int32)
Default 1
pageSizeinteger(int32)
Default 20
curl -i -X GET \
  'https://docs.talli.ai/_mock/reference/swagger/v2/campaign-manager/campaigns/{id}/withdrawal-accounts?pageNumber=1&pageSize=20' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
linkedAccountsobject(Talli.Common.Contracts.Pagination.PagedCollection`1[Talli.Api.Contracts.Campaigns.BankAccountLinkedAccountResponse])
Response
application/json
{
  "linkedAccounts": {
    "pageNumber": 0,
    "pageSize": 0,
    "totalPages": 0,
    "totalItems": 0,
    "data": [ … ]
  }
}

Create withdrawal account for bank account

Request

Creates a new withdrawal account associated with a bank account

Security
oauth2(Required scopes:
Auth0Policy
linkedAccounts:create
)
Path
idstring(uuid)required
Bodyapplication/jsonrequired
businessNamestringrequired
routingNumberstringrequired
accountNumberstringrequired
accountTypeinteger(int32)(Talli.Common.AccountType)required
Enum"Checking""Savings"
addressLine1stringrequired
addressLine2string or null
citystringrequired
stateinteger(int32)(Talli.Common.Contracts.StateCode)required
Enum"AL""AK""AR""AZ""CA""CO""CT""DC""DE""FL"
zipCodestringrequired
curl -i -X POST \
  'https://docs.talli.ai/_mock/reference/swagger/v2/campaign-manager/campaigns/{id}/withdrawal-accounts' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "businessName": "string",
    "routingNumber": "string",
    "accountNumber": "string",
    "accountType": "Checking",
    "addressLine1": "string",
    "addressLine2": "string",
    "city": "string",
    "state": "AL",
    "zipCode": "string"
  }'

Responses

Accepted

Bodyapplication/json
idstring(uuid)
Response
application/json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Get Transactions

Request

Retrieves a list of transactions for particular campaign. When 'aggregate' is set to true, InternalTransfer transactions are aggregated by UTC date and status, while other transaction types are returned as individual transactions. The 'filterByTransactionType' parameter can be used to filter the results to a specific transaction type.

Security
oauth2(Required scopes:
Auth0Policy
campaigns:view
)
Path
idstring(uuid)required
Query
pageNumberinteger(int32)
Default 1
pageSizeinteger(int32)
Default 20
filterByTransactionTypeinteger(int32)(Talli.Api.Contracts.Campaigns.BankAccountTransactionType)
Enum"ExternalTransfer""InternalTransfer"
aggregateboolean
Default false
curl -i -X GET \
  'https://docs.talli.ai/_mock/reference/swagger/v2/campaign-manager/campaigns/{id}/transactions?pageNumber=1&pageSize=20&filterByTransactionType=ExternalTransfer&aggregate=false' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
transactionsobject(Talli.Common.Contracts.Pagination.PagedCollection`1[Talli.Api.Contracts.Campaigns.BankAccountTransactionResponse])
Response
application/json
{
  "transactions": {
    "pageNumber": 0,
    "pageSize": 0,
    "totalPages": 0,
    "totalItems": 0,
    "data": [ … ]
  }
}

Refund campaign

Request

Triggers a money movement from a campaign bank account to return external account.

Security
oauth2(Required scopes:
Auth0Policy
admin:manage
)
Path
campaignIdstring(uuid)required
Bodyapplication/jsonrequired
withdrawalAccountIdstring(uuid)
amountnumber(double)
methodinteger(int32)(Talli.Common.USBankingConstants.TransferMethod)
Enum"AchNextDay""AchSameDay"
descriptionstringrequired
curl -i -X POST \
  'https://docs.talli.ai/_mock/reference/swagger/v2/campaign-manager/campaigns/{campaignId}/:refund' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "withdrawalAccountId": "12226ed6-ccd4-4575-988a-3e792dc5c7d4",
    "amount": 0.1,
    "method": "AchNextDay",
    "description": "string"
  }'

Responses

Accepted

Bodyapplication/json
string(uuid)
Response
application/json
"497f6eca-6276-4993-bfeb-53cbbbba6f08"

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

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