# Talli Campaign Manager API

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.
- **Funding sources**: Create and manage funding sources.
- **Templates**: Create and manage templates.

## Authentication

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

Version: v2
License: Proprietary and Confidential

## Security

### oauth2

Auth0 Authentication (OAuth2, Authorization Code Flow)

Type: oauth2

### oauth2-token-only

Standard Authorization header using the Bearer scheme. Example: "bearer {token}"

Type: apiKey
In: header
Name: Authorization

## Download OpenAPI description

[Talli Campaign Manager API](https://docs.talli.ai/_spec/Reference/swagger.yaml)

## campaigns

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

### Get Campaigns

 - [GET /v2/campaign-manager/campaigns](https://docs.talli.ai/reference/swagger/campaigns/paths/~1v2~1campaign-manager~1campaigns/get.md): 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.

### Create Campaign

 - [POST /v2/campaign-manager/campaigns](https://docs.talli.ai/reference/swagger/campaigns/paths/~1v2~1campaign-manager~1campaigns/post.md): Creates a new campaign with the specified data.

### Patch Campaign

 - [PATCH /v2/campaign-manager/campaigns/{id}](https://docs.talli.ai/reference/swagger/campaigns/paths/~1v2~1campaign-manager~1campaigns~1%7Bid%7D/patch.md): Patches an existing campaign with the provided data.
Note: The icon needs to be patched separately.

### Get Campaign

 - [GET /v2/campaign-manager/campaigns/{id}](https://docs.talli.ai/reference/swagger/campaigns/paths/~1v2~1campaign-manager~1campaigns~1%7Bid%7D/get.md): Retrieves a single campaign based on provided identifier

### Patch Campaign icon

 - [PATCH /v2/campaign-manager/campaigns/{id}/campaign-icon](https://docs.talli.ai/reference/swagger/campaigns/paths/~1v2~1campaign-manager~1campaigns~1%7Bid%7D~1campaign-icon/patch.md): Patches an existing campaign with the provided icon file.

### Upload a file with payout instructions

 - [POST /v2/campaign-manager/campaigns/{id}/payout-instructions/:upload](https://docs.talli.ai/reference/swagger/campaigns/paths/~1v2~1campaign-manager~1campaigns~1%7Bid%7D~1payout-instructions~1:upload/post.md): Uploads a file with payout instructions to the given campaign. The maximum size of the file is 262144000 bytes

### Download a sample beneficiaries file

 - [GET /v2/campaign-manager/campaigns/payout-instructions/:get-sample-file](https://docs.talli.ai/reference/swagger/campaigns/paths/~1v2~1campaign-manager~1campaigns~1payout-instructions~1:get-sample-file/get.md): Retrieves a sample beneficiaries file in the expected format

### Send reminders for given campaign

 - [POST /v2/campaign-manager/campaigns/{campaignId}/payout-instructions/:send-reminders](https://docs.talli.ai/reference/swagger/campaigns/paths/~1v2~1campaign-manager~1campaigns~1%7Bcampaignid%7D~1payout-instructions~1:send-reminders/post.md): 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.

### Set password for given campaign

 - [POST /v2/campaign-manager/campaigns/{campaignId}/:set-password](https://docs.talli.ai/reference/swagger/campaigns/paths/~1v2~1campaign-manager~1campaigns~1%7Bcampaignid%7D~1:set-password/post.md): 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.

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

### Get Payout Instructions

 - [GET /v2/campaign-manager/payout-instructions](https://docs.talli.ai/reference/swagger/payout-instructions/paths/~1v2~1campaign-manager~1payout-instructions/get.md): 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.

### Create Payout Instruction

 - [POST /v2/campaign-manager/payout-instructions](https://docs.talli.ai/reference/swagger/payout-instructions/paths/~1v2~1campaign-manager~1payout-instructions/post.md): 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.

### Get Payout Instruction

 - [GET /v2/campaign-manager/payout-instructions/{id}](https://docs.talli.ai/reference/swagger/payout-instructions/paths/~1v2~1campaign-manager~1payout-instructions~1%7Bid%7D/get.md): 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.

### Update Payout Instruction

 - [PATCH /v2/campaign-manager/payout-instructions/{id}](https://docs.talli.ai/reference/swagger/payout-instructions/paths/~1v2~1campaign-manager~1payout-instructions~1%7Bid%7D/patch.md): 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.

### Get Payout Instruction Activity

 - [GET /v2/campaign-manager/payout-instructions/{id}/activity](https://docs.talli.ai/reference/swagger/payout-instructions/paths/~1v2~1campaign-manager~1payout-instructions~1%7Bid%7D~1activity/get.md): Retrieves the complete activity history for a specific payout instruction, including status changes, notifications sent, and actions performed by both administrators and beneficiaries.

### Get Payout Instruction Payout

 - [GET /v2/campaign-manager/payout-instructions/{id}/payout](https://docs.talli.ai/reference/swagger/payout-instructions/paths/~1v2~1campaign-manager~1payout-instructions~1%7Bid%7D~1payout/get.md): 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.

### Initiate Payout Instruction

 - [POST /v2/campaign-manager/payout-instructions/{id}/:initiate](https://docs.talli.ai/reference/swagger/payout-instructions/paths/~1v2~1campaign-manager~1payout-instructions~1%7Bid%7D~1:initiate/post.md): 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.

### Cancel Payout Instruction

 - [POST /v2/campaign-manager/payout-instructions/{id}/:cancel](https://docs.talli.ai/reference/swagger/payout-instructions/paths/~1v2~1campaign-manager~1payout-instructions~1%7Bid%7D~1:cancel/post.md): 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.

### Try Restore Payout Instruction

 - [POST /v2/campaign-manager/payout-instructions/{id}/:try-restore](https://docs.talli.ai/reference/swagger/payout-instructions/paths/~1v2~1campaign-manager~1payout-instructions~1%7Bid%7D~1:try-restore/post.md): 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.

### Send Payout Instruction Reminder

 - [POST /v2/campaign-manager/payout-instructions/{id}/:send-reminder](https://docs.talli.ai/reference/swagger/payout-instructions/paths/~1v2~1campaign-manager~1payout-instructions~1%7Bid%7D~1:send-reminder/post.md): 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.

## payout-methods

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

### Get Payout Methods

 - [GET /v2/campaign-manager/payout-methods](https://docs.talli.ai/reference/swagger/payout-methods/paths/~1v2~1campaign-manager~1payout-methods/get.md): Retrieves the list of available payout methods that can be used to distribute funds to beneficiaries. 
                Each payout method represents a different way for beneficiaries to receive their funds, such as gift cards, 
                bank transfers, or digital payment options.

### Get Payout Method

 - [GET /v2/campaign-manager/payout-methods/{id}](https://docs.talli.ai/reference/swagger/payout-methods/paths/~1v2~1campaign-manager~1payout-methods~1%7Bid%7D/get.md): Retrieves a specific payout method by its unique identifier. 
                This endpoint provides detailed information about a single payout method, 
                including its name, category, requirements, and transaction limits.

## reports

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

### Get Campaign Payout Methods Report

 - [GET /v2/campaign-manager/reports/campaigns/{campaignId}/payout-methods](https://docs.talli.ai/reference/swagger/reports/paths/~1v2~1campaign-manager~1reports~1campaigns~1%7Bcampaignid%7D~1payout-methods/get.md): Retrieves a report detailing the distribution of payout methods selected by beneficiaries for a specific campaign.

### Get Campaign Conversion Report

 - [GET /v2/campaign-manager/reports/campaigns/{campaignId}/conversion](https://docs.talli.ai/reference/swagger/reports/paths/~1v2~1campaign-manager~1reports~1campaigns~1%7Bcampaignid%7D~1conversion/get.md): Retrieves a report analyzing conversion metrics for a specific campaign, including notification delivery and payout claim rates.

### Get Campaign Statistics Report

 - [GET /v2/campaign-manager/reports/campaigns/{campaignId}/statistics](https://docs.talli.ai/reference/swagger/reports/paths/~1v2~1campaign-manager~1reports~1campaigns~1%7Bcampaignid%7D~1statistics/get.md): Retrieves comprehensive statistics for a specific campaign, including overall performance metrics, budget utilization, and timeline analysis.

### Get Campaign Payouts History Report

 - [GET /v2/campaign-manager/reports/campaigns/{campaignId}/payouts-history](https://docs.talli.ai/reference/swagger/reports/paths/~1v2~1campaign-manager~1reports~1campaigns~1%7Bcampaignid%7D~1payouts-history/get.md): Retrieves a historical record of all payouts processed for a specific campaign, including timestamps, amounts, and status changes.

### Get Campaign Basic Report

 - [GET /v2/campaign-manager/reports/campaigns/{campaignId}/basic](https://docs.talli.ai/reference/swagger/reports/paths/~1v2~1campaign-manager~1reports~1campaigns~1%7Bcampaignid%7D~1basic/get.md): Retrieves a basic CSV report for a specific campaign with sorting and pagination options. The report contains fundamental information about payout instructions and their current status.

## ach-transfers

Endpoints for managing ACH bank transfers as a payout method.

### Get ACH Transfer

 - [GET /v2/campaign-manager/ach-transfers/{id}](https://docs.talli.ai/reference/swagger/ach-transfers/paths/~1v2~1campaign-manager~1ach-transfers~1%7Bid%7D/get.md): Retrieves an ACH transfer by its unique identifier. Returns 404 if no valid transfer is found.

### Get ACH Transfer by Payout Instruction ID

 - [GET /v2/campaign-manager/ach-transfers](https://docs.talli.ai/reference/swagger/ach-transfers/paths/~1v2~1campaign-manager~1ach-transfers/get.md): Retrieves an ACH transfer by its associated payout instruction ID. Returns 404 if no valid transfer is found for the given payout instruction.

## gift-cards

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

### Get Gift Card

 - [GET /v2/campaign-manager/gift-cards/{id}](https://docs.talli.ai/reference/swagger/gift-cards/paths/~1v2~1campaign-manager~1gift-cards~1%7Bid%7D/get.md): Retrieves a gift card by its unique identifier. Returns 404 if there is no valid card.

### Get Gift Card by Payout Instruction ID

 - [GET /v2/campaign-manager/gift-cards](https://docs.talli.ai/reference/swagger/gift-cards/paths/~1v2~1campaign-manager~1gift-cards/get.md): Retrieves a gift card by its associated payout instruction ID. Returns 404 if no valid card is found for the given payout instruction.

## paypal-transfers

Endpoints for managing PayPal payouts and retrieving PayPal transfer details.

### Get PayPal Transfer

 - [GET /v2/campaign-manager/paypal-transfers/{id}](https://docs.talli.ai/reference/swagger/paypal-transfers/paths/~1v2~1campaign-manager~1paypal-transfers~1%7Bid%7D/get.md): Retrieves a PayPal transfer by its unique identifier. Returns 404 if no valid transfer is found.

### Get PayPal Transfer by Payout Instruction ID

 - [GET /v2/campaign-manager/paypal-transfers](https://docs.talli.ai/reference/swagger/paypal-transfers/paths/~1v2~1campaign-manager~1paypal-transfers/get.md): Retrieves a PayPal transfer by its associated payout instruction ID. Returns 404 if no valid transfer is found for the given payout instruction.

## prepaid-cards

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

### Get Prepaid Card

 - [GET /v2/campaign-manager/prepaid-cards/{id}](https://docs.talli.ai/reference/swagger/prepaid-cards/paths/~1v2~1campaign-manager~1prepaid-cards~1%7Bid%7D/get.md): Retrieves a prepaid card by its unique identifier. Returns 404 if no valid card is found.

### Get Prepaid Card by Payout Instruction ID

 - [GET /v2/campaign-manager/prepaid-cards](https://docs.talli.ai/reference/swagger/prepaid-cards/paths/~1v2~1campaign-manager~1prepaid-cards/get.md): Retrieves a prepaid card by its associated payout instruction ID. Returns 404 if no valid card is found for the given payout instruction.

## venmo-transfers

Endpoints for managing Venmo transfers and retrieving Venmo transaction details.

### Get Venmo Transfer

 - [GET /v2/campaign-manager/venmo-transfers/{id}](https://docs.talli.ai/reference/swagger/venmo-transfers/paths/~1v2~1campaign-manager~1venmo-transfers~1%7Bid%7D/get.md): Retrieves a Venmo transfer by its unique identifier. Returns 404 if no valid transfer is found.

### Get Venmo Transfer by Payout Instruction ID

 - [GET /v2/campaign-manager/venmo-transfers](https://docs.talli.ai/reference/swagger/venmo-transfers/paths/~1v2~1campaign-manager~1venmo-transfers/get.md): Retrieves a Venmo transfer by its associated payout instruction ID. Returns 404 if no valid transfer is found for the given payout instruction.

## funding-sources

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

### List Funding Sources

 - [GET /v2/campaign-manager/funding-sources](https://docs.talli.ai/reference/swagger/funding-sources/paths/~1v2~1campaign-manager~1funding-sources/get.md): Retrieves a paginated list of funding sources for the organization. 
                Funding sources represent accounts that can be used to fund campaigns, 
                including the primary organization account and settlement funds.

### Create Settlement Fund

 - [POST /v2/campaign-manager/funding-sources](https://docs.talli.ai/reference/swagger/funding-sources/paths/~1v2~1campaign-manager~1funding-sources/post.md): Creates a new settlement fund (FBO account) for the organization. 
                The settlement fund inherits business details from the organization's primary account 
                and requires a settlement fund name plus optional supporting documents.

### Get Funding Source

 - [GET /v2/campaign-manager/funding-sources/{id}](https://docs.talli.ai/reference/swagger/funding-sources/paths/~1v2~1campaign-manager~1funding-sources~1%7Bid%7D/get.md): Retrieves a specific funding source by its unique identifier. 
                Returns the funding source details including banking information and current status.

## campaign-drafts

### Get Campaign Drafts

 - [GET /v2/campaign-manager/campaign-drafts](https://docs.talli.ai/reference/swagger/campaign-drafts/paths/~1v2~1campaign-manager~1campaign-drafts/get.md): Retrieves a paginated list of campaign drafts, optionally filtered by funding source ID.

### Create Campaign Draft

 - [POST /v2/campaign-manager/campaign-drafts](https://docs.talli.ai/reference/swagger/campaign-drafts/paths/~1v2~1campaign-manager~1campaign-drafts/post.md): Creates a new campaign draft. All fields are optional as drafts can be saved in incomplete state.

### Get Campaign Draft

 - [GET /v2/campaign-manager/campaign-drafts/{id}](https://docs.talli.ai/reference/swagger/campaign-drafts/paths/~1v2~1campaign-manager~1campaign-drafts~1%7Bid%7D/get.md)

### Patch Campaign Draft

 - [PATCH /v2/campaign-manager/campaign-drafts/{id}](https://docs.talli.ai/reference/swagger/campaign-drafts/paths/~1v2~1campaign-manager~1campaign-drafts~1%7Bid%7D/patch.md)

### Delete Campaign Draft

 - [DELETE /v2/campaign-manager/campaign-drafts/{id}](https://docs.talli.ai/reference/swagger/campaign-drafts/paths/~1v2~1campaign-manager~1campaign-drafts~1%7Bid%7D/delete.md): Deletes a campaign draft by ID.

### Update Campaign Draft Icon

 - [PATCH /v2/campaign-manager/campaign-drafts/{id}/campaign-icon](https://docs.talli.ai/reference/swagger/campaign-drafts/paths/~1v2~1campaign-manager~1campaign-drafts~1%7Bid%7D~1campaign-icon/patch.md): Updates the icon for an existing campaign draft.

### Promote Campaign Draft to Campaign

 - [POST /v2/campaign-manager/campaign-drafts/{id}/:promote](https://docs.talli.ai/reference/swagger/campaign-drafts/paths/~1v2~1campaign-manager~1campaign-drafts~1%7Bid%7D~1:promote/post.md)

## templates

### Get template types

 - [GET /v2/campaign-manager/templates/template-type-schemas](https://docs.talli.ai/reference/swagger/templates/paths/~1v2~1campaign-manager~1templates~1template-type-schemas/get.md): Retrieves a list of template types.

### Get template

 - [GET /v2/campaign-manager/templates/{id}](https://docs.talli.ai/reference/swagger/templates/paths/~1v2~1campaign-manager~1templates~1%7Bid%7D/get.md): Retrieves a single template based on provided identifier.

### Update template

 - [PUT /v2/campaign-manager/templates/{id}](https://docs.talli.ai/reference/swagger/templates/paths/~1v2~1campaign-manager~1templates~1%7Bid%7D/put.md): Updates an existing template with the provided template.

### Get templates

 - [GET /v2/campaign-manager/templates](https://docs.talli.ai/reference/swagger/templates/paths/~1v2~1campaign-manager~1templates/get.md): Retrieves a paginated list of templates, optionally filtered by template type.

### Create template

 - [POST /v2/campaign-manager/templates](https://docs.talli.ai/reference/swagger/templates/paths/~1v2~1campaign-manager~1templates/post.md): Creates a new template with the specified details.

### Send notification preview

 - [POST /v2/campaign-manager/templates/:send-preview](https://docs.talli.ai/reference/swagger/templates/paths/~1v2~1campaign-manager~1templates~1:send-preview/post.md): Sends a notification preview to the specified recipient using the provided template model.