Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Management Giveaways API
version: ''
description: "The Management API allows you to programmatically do what the Campaign Manager\ndoes. Use this API for back-office operations such as campaign\nand coupon management, maintenance jobs, and bulk operations.\n\nFor more background information about this API, see\n[Management API overview](https://docs.talon.one/docs/dev/management-api/overview).\n\n> [!note] **Are you looking for a different API?**\n> - To integrate with Talon.One directly and send real-time data, see the [Integration API](https://docs.talon.one/integration-api).\n> - To integrate with Talon.One from a CEP or CDP platform, see the [Third-party API](https://docs.talon.one/third-party-api).\n\n## Authentication\n\nManagement API keys are scoped to a user account and become invalid if the user is\ndeactivated or removed from the organization. Use a dedicated service account to\ncreate keys for production integrations.\n\nFor details on generating and managing API keys, see\n[Manage Management API keys](https://docs.talon.one/docs/product/account/dev-tools/manage-mapi-keys).\n\n## Security\n\nConsider the following recommendations:\n- Store API keys securely via environment variables or by using a secret management system.\n- Only call this API from backend services.\n- Implement HTTPS for all communication with the API to ensure data privacy and security.\n- Create [user roles](https://docs.talon.one/docs/product/account/account-settings/manage-roles)\n reflecting your own company hierarchies.\n\n## Response codes and error handling\n\nTalon.One uses conventional HTTP response codes to indicate the success or failure of an API request.\nCodes in the `2xx` range indicate success. Codes in the `4xx` range indicate the request failed based\non the information provided. Codes in the `5xx` range indicate an error with Talon.One servers.\n\nError responses include a `message` that summarizes what went wrong. Use it for logging and debugging.\n\nWhen a request has one or more specific problems, the `errors` array lists each one separately:\n- `title` gives a short description of the problem\n- `source` shows where the error originated, for example, using a `pointer` property indicating the\n problematic property in the request body.\n\n| Code | Description | Action |\n|------|-------------|--------|\n| `2xx` | Success | None. |\n| `400` | Bad request | Fix the request (for example, a missing or invalid parameter). Not retryable. |\n| `401` | Unauthorized | Provide a valid API key. Not retryable. |\n| `404` | Not found | Check the resource path or ID. Not retryable. |\n| `409` | Conflict | If you are creating a resource, use a unique resource name/ID. Generally not retryable. |\n| `429` | Rate limit exceeded | Retry with exponential backoff. |\n| `5xx` | Server error | Retry with exponential backoff. |\n\n## URL encoding\n\nEncode all path and query parameter values that contain special characters. This applies to\ncustomer profile IDs, session IDs, coupon codes, and any other user-supplied string passed as\na URL segment or query parameter.\n\nFor example, encode a `10$OFF_NOW` coupon code as `10%24OFF_NOW` before\nincluding it in a request URL.\n\nRequests with unencoded special characters may be misrouted or return unexpected errors.\n\nFor more information, see [HTML URL Encoding Reference](https://www.w3schools.com/tags/ref_urlencode.asp).\n\n## MCP server (closed beta)\n\nTalon.One provides an MCP server that gives AI agents\nread-only access to your campaigns, customers, coupons, and loyalty programs,\nso they can answer questions about your campaigns and customers in plain language.\n\nAgents can explain campaign rule logic, check campaign status and budgets, analyze customer point\nbalances and tier status, and investigate failed API requests.\n\nTo connect, append `/v1/mcp/entrypoint` to your Talon.One deployment URL and authenticate with an MCP\nconnection API key generated in **Campaign Manager > Account > Tools > MCP Connections**.\n\nThe server is compatible with Claude Desktop, Claude Code, Cursor, Gemini CLI, ChatGPT CLI,\nCodex CLI, and other stdio-compatible MCP clients.\n\nFor more information, see [Talon.One MCP server](https://docs.talon.one/docs/dev/mcp).\n\n## Rate limiting\n\nThis API is **not** meant to be used in real-time integrations that directly serve your end users.\nIt supports a maximum of **3 requests per second** for each of these endpoints.\nFor real-time integrations use the [Integration API](https://docs.talon.one/integration-api).\n"
servers:
- url: https://yourbaseurl.talon.one
security:
- manager_auth: []
- management_key: []
tags:
- 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).
'
paths:
/v1/giveaways/pools/{poolId}/import:
post:
operationId: importPoolGiveaways
summary: Import giveaway codes into a giveaway pool
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.\n\nUpload a CSV file containing the giveaway codes that should be created. Send\nthe file as multipart data.\n\nThe CSV file contains the following columns:\n\n- `code` (required): The code of your giveaway, for instance, a gift card redemption code.\n- `startdate`: The start date in RFC3339 of the code redemption period.\n- `enddate`: The last date in RFC3339 of the code redemption period.\n- `attributes`: A JSON object describing _custom_ giveaway attribute names and their values, enclosed with double quotation marks.<br />\n For example, if you created a [custom attribute](https://docs.talon.one/docs/dev/concepts/attributes#custom-attributes)\n called `provider` associated with the giveaway entity, the object in the CSV file, when opened in a text editor, must be: `\"{\"provider\": \"myPartnerCompany\"}\"`.\n\nThe `startdate` and `enddate` have nothing to do with the _validity_ of the\ncodes. They are only used by the Rule Engine to award the codes or not.\n\nYou can use the time zone setting of your choice. The values are converted\nto UTC internally by Talon.One.\n\n> [!note] **Note**\n> - We recommend limiting your file size to 500MB.\n> - You can import the same code multiple times. Duplicate codes are treated and distributed to customers as unique codes.\n\n## Example\n\n```text\ncode,startdate,enddate,attributes\nGIVEAWAY1,2020-11-10T23:00:00Z,2022-11-11T23:00:00Z,\"{\"\"provider\"\":\n\"\"Amazon\"\"}\"\nGIVEAWAY2,2020-11-10T23:00:00Z,2022-11-11T23:00:00Z,\"{\"\"provider\"\":\n\"\"Amazon\"\"}\"\nGIVEAWAY3,2021-01-10T23:00:00Z,2022-11-11T23:00:00Z,\"{\"\"provider\"\":\n\"\"Aliexpress\"\"}\"\n```\n"
tags:
- Giveaways
parameters:
- name: poolId
description: The ID of the pool. You can find it in the Campaign Manager, in the **Giveaways** section.
in: path
example: 8
required: true
schema:
type: integer
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
upFile:
description: The CSV file containing the data that is being imported.
type: string
format: binary
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Import'
/v1/giveaways/pools/{poolId}/export:
get:
operationId: exportPoolGiveaways
summary: Export giveaway codes of a giveaway pool
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.\n\nDownload a CSV file containing the giveaway codes of a specific giveaway\npool.\n\n> [!tip] If the exported CSV file is too large to view, you can\n> [split it into multiple files](https://www.google.com/search?q=split+CSV+into+multiple+files).\n\nThe CSV file contains the following columns:\n\n- `id`: The internal ID of the giveaway.\n- `poolid`: The internal ID of the giveaway pool.\n- `code`: The giveaway code.\n- `startdate`: The validity start date in RFC3339 of the giveaway (can be empty).\n- `enddate`: The validity end date in RFC3339 of the giveaway (can be empty).\n- `attributes`: Any custom attributes associated with the giveaway code (can be empty).\n- `used`: An indication of whether the giveaway is already awarded.\n- `importid`: The ID of the import which created the giveaway.\n- `created`: The creation time of the giveaway code.\n- `profileintegrationid`: The third-party integration ID of the customer\n profile that was awarded the giveaway. Can be empty if the giveaway was not\n awarded.\n- `profileid`: The internal ID of the customer profile that was awarded the\n giveaway. Can be empty if the giveaway was not awarded or an internal ID\n does not exist.\n"
tags:
- Giveaways
parameters:
- name: poolId
description: The ID of the pool. You can find it in the Campaign Manager, in the **Giveaways** section.
in: path
example: 8
required: true
schema:
type: integer
- name: createdBefore
description: Timestamp that filters the results to only contain giveaways created before this date. Must be an RFC3339 timestamp string.
in: query
example: '2024-05-29T15:04:05+07:00'
schema:
type: string
format: date-time
- name: createdAfter
description: Timestamp that filters the results to only contain giveaways created after this date. Must be an RFC3339 timestamp string.
in: query
example: '2024-05-29T15:04:05+07:00'
schema:
type: string
format: date-time
responses:
'200':
description: OK
content:
application/csv:
schema:
type: string
format: csv
examples:
response:
value: 'id,poolid,code,startdate,enddate,attributes,used,importid,created,profileintegrationid,profileid
1,7,af18bc3839799451fb6d6b6467cf4c25e,2023-04-11T12:47:47Z,2024-04-11T12:47:47Z,"{""attribute"": ""value""}",true,2,2023-04-11T12:47:47Z,R195412,35
'
'400':
description: Bad request
content:
application/csv:
schema:
$ref: '#/components/schemas/ErrorResponseWithStatus'
components:
schemas:
ErrorResponseWithStatus:
type: object
properties:
message:
type: string
errors:
type: array
description: An array of individual problems encountered during the request.
items:
$ref: '#/components/schemas/APIError'
StatusCode:
type: integer
description: The error code
APIError:
type: object
required:
- source
- title
properties:
title:
type: string
description: Short description of the problem.
details:
type: string
description: Longer description of this specific instance of the problem.
source:
$ref: '#/components/schemas/ErrorSource'
AccountEntity:
type: object
required:
- accountId
properties:
accountId:
type: integer
description: The ID of the account that owns this entity.
example: 3886
Entity:
type: object
required:
- id
- created
properties:
id:
type: integer
description: The internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
UserEntity:
type: object
required:
- userId
properties:
userId:
type: integer
description: The ID of the user associated with this entity.
example: 388
ErrorSource:
type: object
description: 'The source of the current error, exactly one of `pointer`, `parameter` or `line` will be defined.
'
properties:
pointer:
type: string
description: Pointer to the path in the payload that caused this error.
parameter:
type: string
description: Query parameter that caused this error.
line:
type: string
description: Line number in uploaded multipart file that caused this error. 'N/A' if unknown.
resource:
type: string
description: Pointer to the resource that caused this error.
Import:
allOf:
- $ref: '#/components/schemas/Entity'
- $ref: '#/components/schemas/AccountEntity'
- $ref: '#/components/schemas/UserEntity'
- type: object
required:
- amount
- entity
properties:
entity:
type: string
example: AttributeAllowedList
description: 'The name of the entity that was imported.
'
amount:
type: integer
minimum: 0
example: 10
description: The number of values that were imported.
securitySchemes:
manager_auth:
type: apiKey
name: Authorization
in: header
description: 'This authentication scheme relies on a bearer token that you can use to
access all the endpoints of the Management API.
To create the token:
1. Get a bearer token by calling the
[createSession](#tag/Sessions/operation/createSession) endpoint.
1. Use the `token` property of the response in the HTTP header of your
next queries: `Authorization: Bearer $TOKEN`.
A token is valid for 3 months. In accordance with best pratices, use
your generated token for all your API requests. Do **not** regenerate a token for each
request.
> [!note]
> We recommend that you use a [Management API key](https://docs.talon.one/management-api#section/Authentication/management_key)
> instead of a bearer token.
'
management_key:
type: apiKey
name: Authorization
in: header
description: "The API key authentication gives you access to the endpoints selected by\nthe admin who created the key.\n\nUsing an API key is the recommended authentication method.\n\nThe key must be generated by an admin and given to the developer that\nrequires it:\n\n1. Sign in to the Campaign Manager and click **Account** > **Tools** >\n**Management API Keys**.\n1. Click **Create Key** and give it a name.\n1. Set an expiration date.\n **Tip**: Avoid choosing expiration dates that fall at the end of the year or during other high-traffic periods.\n1. Choose the endpoints the key should give access to.\n1. Click **Create Key**.\n1. Share it with your developer.\n\nThe developer can now use the API key in the HTTP header, prefixing it\nwith `ManagementKey-v1`:\n\n```\nAuthorization: ManagementKey-v1 bd9479c59e16f9dbc644d33aa74d58270fe13bf3\n```\n"