openapi: 3.1.0
info:
title: Management API
version: ''
description: |
The Management API allows you to programmatically do what the Campaign Manager
does. Use this API for back-office operations such as campaign
and coupon management, maintenance jobs, and bulk operations.
For more background information about this API, see
[Management API overview](https://docs.talon.one/docs/dev/management-api/overview).
> [!note] **Are you looking for a different API?**
> - To integrate with Talon.One directly and send real-time data, see the [Integration API](https://docs.talon.one/integration-api).
> - To integrate with Talon.One from a CEP or CDP platform, see the [Third-party API](https://docs.talon.one/third-party-api).
## Authentication
Management API keys are scoped to a user account and become invalid if the user is
deactivated or removed from the organization. Use a dedicated service account to
create keys for production integrations.
For details on generating and managing API keys, see
[Manage Management API keys](https://docs.talon.one/docs/product/account/dev-tools/manage-mapi-keys).
## Security
Consider the following recommendations:
- Store API keys securely via environment variables or by using a secret management system.
- Only call this API from backend services.
- Implement HTTPS for all communication with the API to ensure data privacy and security.
- Create [user roles](https://docs.talon.one/docs/product/account/account-settings/manage-roles)
reflecting your own company hierarchies.
## Response codes and error handling
Talon.One uses conventional HTTP response codes to indicate the success or failure of an API request.
Codes in the `2xx` range indicate success. Codes in the `4xx` range indicate the request failed based
on the information provided. Codes in the `5xx` range indicate an error with Talon.One servers.
Error responses include a `message` that summarizes what went wrong. Use it for logging and debugging.
When a request has one or more specific problems, the `errors` array lists each one separately:
- `title` gives a short description of the problem
- `source` shows where the error originated, for example, using a `pointer` property indicating the
problematic property in the request body.
| Code | Description | Action |
|------|-------------|--------|
| `2xx` | Success | None. |
| `400` | Bad request | Fix the request (for example, a missing or invalid parameter). Not retryable. |
| `401` | Unauthorized | Provide a valid API key. Not retryable. |
| `404` | Not found | Check the resource path or ID. Not retryable. |
| `409` | Conflict | If you are creating a resource, use a unique resource name/ID. Generally not retryable. |
| `429` | Rate limit exceeded | Retry with exponential backoff. |
| `5xx` | Server error | Retry with exponential backoff. |
## URL encoding
Encode all path and query parameter values that contain special characters. This applies to
customer profile IDs, session IDs, coupon codes, and any other user-supplied string passed as
a URL segment or query parameter.
For example, encode a `10$OFF_NOW` coupon code as `10%24OFF_NOW` before
including it in a request URL.
Requests with unencoded special characters may be misrouted or return unexpected errors.
For more information, see [HTML URL Encoding Reference](https://www.w3schools.com/tags/ref_urlencode.asp).
## MCP server (closed beta)
Talon.One provides an MCP server that gives AI agents
read-only access to your campaigns, customers, coupons, and loyalty programs,
so they can answer questions about your campaigns and customers in plain language.
Agents can explain campaign rule logic, check campaign status and budgets, analyze customer point
balances and tier status, and investigate failed API requests.
To connect, append `/v1/mcp/entrypoint` to your Talon.One deployment URL and authenticate with an MCP
connection API key generated in **Campaign Manager > Account > Tools > MCP Connections**.
The server is compatible with Claude Desktop, Claude Code, Cursor, Gemini CLI, ChatGPT CLI,
Codex CLI, and other stdio-compatible MCP clients.
For more information, see [Talon.One MCP server](https://docs.talon.one/docs/dev/mcp).
## Rate limiting
This API is **not** meant to be used in real-time integrations that directly serve your end users.
It supports a maximum of **3 requests per second** for each of these endpoints.
For real-time integrations use the [Integration API](https://docs.talon.one/integration-api).
servers:
- url: https://yourbaseurl.talon.one
security:
- manager_auth: []
- management_key: []
tags:
- name: Accounts and users
description: |
Represents account and user management, including billing email addresses and user invitations.
- name: Achievements
description: |
Represents achievements that reward a customer profile for performing a number of specific actions or reaching a transactional milestone within a defined period.
For example, you can use achievements to award your customers when they purchase five cups of coffee in one week or when they purchase items worth $3000 in three months.
- name: Additional costs
description: |
Represents an extra fee applied to the cart, for example, shipping fees or processing fees.
See the [docs](https://docs.talon.one/docs/product/account/dev-tools/managing-additional-costs).
- name: Analytics
description: |
Represents analytics used to retrieve statistical data about the performance of campaigns within an Application.
- name: Applications
description: |
Represents an Application in the Campaign Manager.
An Application is the target of every Integration API request to Talon.One.
One Application can hold various API keys used for Integration API requests.
You may have multiple Applications within one account,
for example staging and production, or different international markets.
See the [docs](https://docs.talon.one/docs/product/applications/overview).
- name: Attributes
description: |
Represents a piece of information related to one of the entities available in the Campaign Manager. Use
them to create highly customized rules.
See the [docs](https://docs.talon.one/docs/product/account/dev-tools/managing-attributes).
- name: Audiences
description: |
Represents lists of customer profiles that allow you to target specific groups of customers in your campaigns.
Audiences can be synced from customer data platforms or created directly in Talon.One.
See the [docs](https://docs.talon.one/docs/product/audiences/overview).
- name: Campaign access groups
description: |
Represents the campaign access groups you can create in your Applications to organize your campaigns based on the type of campaign or the team in charge.
See the [docs](https://docs.talon.one/docs/product/account/account-settings/managing-campaign-groups).
- name: Campaign templates
description: |
Represents templates used to generate campaigns from.
- name: Campaigns
description: |
Represents the primary resource used to control the behavior of the Talon.One Rule Engine.
They combine rulesets, coupons, and limits into a single unit.
See the [docs](https://docs.talon.one/docs/product/campaigns/overview).
- name: Catalogs
description: |
Represents a catalog of cart items with unique SKUs. Cart item catalogs allow you to synchronize your entire inventory with Talon.One.
See the [docs](https://docs.talon.one/docs/product/account/dev-tools/managing-cart-item-catalogs).
- name: Collections
description: |
Represents a collection of arbitrary values that you can use inside rules. For example, a list of SKUs.
See the [docs](https://docs.talon.one/docs/product/campaigns/managing-collections).
- name: Coupons
description: |
Represents unique codes belonging to a particular campaign. Coupons don't define any behavior on their own.
Instead the campaign ruleset can include rules that validate coupons and carry out particular effects.
See the [docs](https://docs.talon.one/docs/product/campaigns/coupons/coupon-page-overview).
- name: Customer data
description: |
Represents the data of a customer, including sessions and events used for reporting and debugging in the Campaign Manager.
- name: Events
description: |
Represents a single occurrence of a specific customer action, for example, updating the cart or signing up for a newsletter.
There are 2 types of events:
- **Built-in events:** They are triggered by various endpoints, such as the [Update customer session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2) endpoint. [Learn more](https://docs.talon.one/docs/dev/concepts/entities/events).
- **Custom events:** They are triggered by the [Track event](https://docs.talon.one/integration-api#tag/Events/operation/trackEventV2) endpoint.
- name: Experiments
description: |
Represents an A/B testing configuration within a campaign that splits customer sessions across multiple variants to compare rule effects against each other.
- name: Giveaways
description: |
Represents a program that rewards customers with giveaways, such as free gift cards.
See the [docs](https://docs.talon.one/docs/product/giveaways/overview).
- name: Logs
description: |
Represents the Talon.One logs, which contain all incoming and outgoing requests.
- name: Loyalty
description: |
Represents loyalty programs or concepts related to them.
Loyalty programs can be _profile-based_ or _card-based_, depending on whether loyalty points are linked
to [customer profiles](https://docs.talon.one/docs/product/applications/displaying-customer-profiles) or [loyalty cards](https://docs.talon.one/docs/product/loyalty-programs/card-based/card-based-overview).
See [the Product docs](https://docs.talon.one/docs/product/loyalty-programs/overview) for more information.
- name: Loyalty cards
description: |
Represents loyalty cards.
[Loyalty cards](https://docs.talon.one/docs/product/loyalty-programs/card-based/card-based-overview) allow your customers to collect and spend loyalty points within a card-based loyalty program.
- name: Referrals
description: |
Represents a referral code shared between a customer (advocate) and a prospect (friend).
A referral is defined by:
- an advocate: person who invited their friend via referral program.
- a friend: person who receives the invite from an advocate.
- a referral code: code to be redeemed by the advocate(s) once they referred their friend.
See the [docs](https://docs.talon.one/docs/product/campaigns/referrals/referral-overview).
- name: Roles
description: |
Represents a set of permissions assigned to a user.
See the [docs](https://docs.talon.one/docs/product/account/account-settings/managing-roles).
- name: Sessions
description: |
Represents a session used for authentication purposes.
Create one with the [Create session](#tag/Sessions/operation/createSession) endpoint.
- name: Store budgets
description: Represents store budgets. You can set a store budget to limit the total amount an individual store can spend in a campaign.
- name: Stores
description: |
Represents physical or digital stores, branches, and franchises.
- name: Value maps
description: Represents the value maps that the user can create within a campaign ruleset.
- name: Webhooks
description: |
Represents webhooks, which send information from Talon.One to the URI of your choice.
See the [docs](https://docs.talon.one/docs/dev/getting-started/webhooks).
paths:
/v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}/ledger_balances:
get:
operationId: getLoyaltyLedgerBalances
summary: Get customer's loyalty balances (Management API)
description: |
> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.
Retrieve loyalty ledger balances for the given Integration ID in the
specified loyalty program.
You can filter balances by date and subledger ID, and include tier-related
information in the response.
> [!note] **Note**
> - For most use cases, especially real-time integrations, use the Integration API endpoint:
[Get customer's loyalty balances](https://docs.talon.one/integration-api#tag/Loyalty/operation/getLoyaltyBalances).
> - If no filtering options are applied, you retrieve all loyalty balances on the current date for the given integration ID.
Loyalty balances are calculated when Talon.One receives your request using
the points stored in our database, so retrieving a large number of balances
at once can impact performance.
For more information, see:
- [Managing card-based loyalty program
data](https://docs.talon.one/docs/product/loyalty-programs/card-based/managing-loyalty-cards)
- [Managing profile-based loyalty program
data](https://docs.talon.one/docs/product/loyalty-programs/profile-based/managing-pb-lp-data)
tags:
- Loyalty
parameters:
- name: loyaltyProgramId
in: path
required: true
description: |
Identifier of the profile-based loyalty program. You can get the ID with
the [List loyalty programs](https://docs.talon.one/management-api#tag/Loyalty/operation/getLoyaltyPrograms) endpoint.
example: 33
schema:
type: integer
- in: path
required: true
name: integrationId
description: |
The integration identifier for this customer profile. Must be:
- Unique within the deployment.
- Stable for the customer. Do not use an ID that the customer can update themselves. For example, you can use a database ID.
Once set, you cannot update this identifier.
example: customer1
schema:
type: string
- name: endDate
in: query
required: false
description: |
Used to return expired, active, and pending loyalty balances before this
timestamp. You can enter any past, present, or future timestamp value.
> [!note] **Note**
> - This must be an RFC3339 timestamp string.
> - You can include a time component in your string, for example, `T23:59:59` to specify the end of the day. The time zone setting
> considered is `UTC`. If you do not include a time component, a default time value of `T00:00:00` (midnight) in `UTC` is considered.
example: '2024-05-29T15:04:05+07:00'
schema:
type: string
format: date-time
- name: subledgerId
in: query
required: false
description: The ID of the subledger used to filter the data. Leave this value empty ("") to query the main ledger.
example: subledger1
schema:
type: string
- name: includeTiers
in: query
required: false
description: |
Indicates whether tier information is included in the response.
When set to `true`, the response includes information about the current tier and the number of points required to move to next tier.
example: false
schema:
type: boolean
default: false
- name: includeProjectedTier
in: query
required: false
description: |
Indicates whether the customer's projected tier information is included in the response.
When set to `true`, the response includes information about the customer's active points and the name of the projected tier.
**Note** We recommend filtering by `subledgerId` for better performance.
example: false
schema:
type: boolean
default: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/LoyaltyBalancesWithTiers'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseWithStatus'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseWithStatus'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseWithStatus'
/v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}/ledger_transactions:
get:
operationId: getLoyaltyProgramProfileLedgerTransactions
summary: List customer's loyalty transactions (Management API)
description: |
> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.
Retrieve paginated results of loyalty transaction logs for the given
Integration ID in the specified loyalty program.
You can filter transactions by date or by ledger (subledger or main ledger). If no filters are applied, the last 50
loyalty transactions for the given integration ID are returned.
> [!note] **Note**
> - For most use cases, especially real-time integrations, use the Integration API endpoint:
> [List customer's loyalty transactions](https://docs.talon.one/integration-api#tag/Loyalty/operation/getLoyaltyProgramProfileTransactions).
> - To retrieve all loyalty program transaction logs in a given loyalty program, use the
> [List loyalty program transactions](https://docs.talon.one/management-api#tag/Loyalty/operation/getLoyaltyProgramTransactions) endpoint.
tags:
- Loyalty
parameters:
- name: loyaltyProgramId
in: path
required: true
description: |
Identifier of the profile-based loyalty program. You can get the ID with
the [List loyalty programs](https://docs.talon.one/management-api#tag/Loyalty/operation/getLoyaltyPrograms) endpoint.
example: 33
schema:
type: integer
- in: path
required: true
name: integrationId
description: |
The integration identifier for this customer profile. Must be:
- Unique within the deployment.
- Stable for the customer. Do not use an ID that the customer can update themselves. For example, you can use a database ID.
Once set, you cannot update this identifier.
example: customer1
schema:
type: string
- name: customerSessionIDs
in: query
required: false
description: |
Filter the results by a list of customer session IDs.
To include multiple IDs, repeat the parameter for each one, for example,
`?customerSessionIDs=id1&customerSessionIDs=id2`.
The response contains only data associated with the specified sessions.
example:
- session_integration_id_1
- session_integration_id_1
schema:
type: array
items:
type: string
- name: transactionUUIDs
in: query
required: false
description: |
Filter the results by a list of transaction UUIDs.
To include multiple IDs, repeat the parameter for each one, for example,
`?transactionUUIDs=uuid1&transactionUUIDs=uuid2`.
The response contains only data associated with the specified transactions.
example:
- dc608634-0100-40d9-b371-e964476bbe0f
- 9e829590-05cf-407b-b4c0-5f28468a81e1
schema:
type: array
items:
type: string
- name: subledgerId
in: query
required: false
description: The ID of the subledger used to filter the data. Leave this value empty ("") to query the main ledger.
example: subledger1
schema:
type: string
- name: loyaltyTransactionType
in: query
required: false
description: |
Filter results by loyalty transaction type:
- `manual`: Loyalty transaction that was done manually.
- `session`: Loyalty transaction that resulted from a customer session.
- `import`: Loyalty transaction that was imported from a CSV file.
example: manual
schema:
type: string
enum:
- manual
- session
- import
- name: startDate
in: query
required: false
description: |
Date and time from which results are returned. Results are filtered by
transaction creation date.
> [!note] **Note**
> - This must be an RFC3339 timestamp string.
> - You can include a time component in your string, for example, `T23:59:59` to specify the end of the day. The time zone setting
> considered is `UTC`. If you do not include a time component, a default time value of `T00:00:00` (midnight) in `UTC` is considered.
example: '2024-05-29T15:04:05+07:00'
schema:
type: string
format: date-time
- name: endDate
in: query
required: false
description: |
Date and time by which results are returned. Results are filtered by
transaction creation date.
> [!note] **Note**
> - This must be an RFC3339 timestamp string.
> - You can include a time component in your string, for example, `T23:59:59` to specify the end of the day. The time zone setting
> considered is `UTC`. If you do not include a time component, a default time value of `T00:00:00` (midnight) in `UTC` is considered.
example: '2024-05-29T15:04:05+07:00'
schema:
type: string
format: date-time
- name: pageSize
in: query
required: false
description: The number of items in the response.
example: 50
schema:
type: integer
minimum: 1
maximum: 1000
default: 50
- $ref: '#/components/parameters/skip'
- name: awaitsActivation
in: query
required: false
description: |
If `true`: Filters results to include only point transactions that have action-based activation and have not expired.
If `false`: Returns a `400` response.
example: true
schema:
type: boolean
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
required:
- hasMore
- data
properties:
hasMore:
type: boolean
example: true
data:
type: array
items:
$ref: '#/components/schemas/LedgerTransactionLogEntryIntegrationAPI'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseWithStatus'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseWithStatus'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseWithStatus'
/v1/applications:
get:
operationId: getApplications
summary: List Applications
description: |-
> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.
List all the Applications in the current account.
tags:
- Applications
parameters:
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/sort'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
required:
- totalResultSize
- data
properties:
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/components/schemas/Application'
/v1/applications/{applicationId}:
get:
operationId: getApplication
summary: Get Application
description: |-
> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.
Get the Application specified by the ID.
tags:
- Applications
parameters:
- $ref: '#/components/parameters/applicationId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Application'
/v1/applications/{applicationId}/campaigns:
get:
operationId: getCampaigns
summary: List campaigns
description: |
> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.
List the campaigns of the specified application that match your filter criteria.
tags:
- Campaigns
parameters:
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/sort'
- $ref: '#/components/parameters/applicationId'
- name: campaignState
in: query
description: |
Filter results by the state of the campaign.
- `enabled`: Campaigns that are scheduled, running (activated), or expired.
- `running`: Campaigns that are running (activated).
- `disabled`: Campaigns that are disabled.
- `expired`: Campaigns that are expired.
- `archived`: Campaigns that are archived.
example: enabled
required: false
schema:
type: string
enum:
- enabled
- disabled
- archived
- scheduled
- running
- expired
- staged
- name: name
in: query
description: Filter results performing case-insensitive matching against the name of the campaign.
example: campaign1
required: false
schema:
type: string
- name: tags
in: query
description: |
Filter results performing case-insensitive matching against the tags of the campaign.
example:
- tag1
- tag2
required: false
schema:
type: array
items:
type: string
- name: createdBefore
in: query
description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the campaign creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
required: false
example: '2024-05-29T15:04:05+07:00'
schema:
type: string
format: date-time
- name: createdAfter
in: query
description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the campaign creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
required: false
example: '2024-05-29T15:04:05+07:00'
schema:
type: string
format: date-time
- name: startBefore
in: query
description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the campaign start time timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
required: false
example: '2024-05-29T15:04:05+07:00'
schema:
type: string
format: date-time
- name: startAfter
in: query
description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the campaign start time timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
required: false
example: '2024-05-29T15:04:05+07:00'
schema:
type: string
format: date-time
- name: endBefore
in: query
description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the campaign end time timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
required: false
example: '2024-05-29T15:04:05+07:00'
schema:
type: string
format: date-time
- name: endAfter
in: query
description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the campaign end time timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
required: false
example: '2024-05-29T15:04:05+07:00'
schema:
type: string
format: date-time
- name: campaignGroupId
in: query
description: Filter results to campaigns owned by the specified campaign access group ID.
example: 12
required: false
schema:
type: integer
- name: templateId
in: query
description: The ID of the campaign template this campaign was created from.
example: 18
schema:
type: integer
- name: storeId
in: query
description: Filter results to campaigns linked to the specified store ID.
example: 23
required: false
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
required:
- totalResultSize
- data
properties:
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/components/schemas/Campaign'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseWithStatus'
/v1/applications/{applicationId}/campaigns/{campaignId}:
get:
operationId: getCampaign
summary: Get campaign
description: |-
> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.
Retrieve the given campaign.
tags:
- C
# --- truncated at 32 KB (798 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/talon-one/refs/heads/main/openapi/talon-one-management-api-openapi.yml