Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Management Accounts and users 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: Accounts and users
description: 'Represents account and user management, including billing email addresses and user invitations.
'
paths:
/v1/users:
get:
operationId: getUsers
summary: List users in account
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 all users in your account.
'
tags:
- Accounts and users
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/User'
/v1/users/{userId}:
get:
operationId: getUser
summary: Get user
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 data (including an invitation code) for a user. Non-admin users can only get their own profile.
'
tags:
- Accounts and users
parameters:
- name: userId
in: path
description: The ID of the user.
example: 33
required: true
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/User'
put:
operationId: updateUser
summary: Update user
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.
Update the details of a specific user.'
tags:
- Accounts and users
parameters:
- name: userId
in: path
description: The ID of the user.
example: 33
required: true
schema:
type: integer
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateUser'
description: body
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/User'
delete:
operationId: deleteUser
summary: Delete user
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.
Delete a specific user.'
tags:
- Accounts and users
parameters:
- name: userId
in: path
description: The ID of the user.
example: 33
required: true
schema:
type: integer
responses:
'204':
description: No Content
/v1/provisioning/okta:
get:
operationId: oktaEventHandlerChallenge
summary: Validate Okta API ownership
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.
Validate the ownership of the API through a challenge-response mechanism.
This challenger endpoint is used by Okta to confirm that communication between Talon.One and Okta is correctly configured and accessible
for provisioning and deprovisioning of Talon.One users, and that only Talon.One can receive and respond to events from Okta.
'
tags:
- Accounts and users
responses:
'200':
description: OK
/v1/provisioning/scim/Groups:
get:
operationId: scimGetGroups
summary: List SCIM groups
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 a paginated list of groups created using the SCIM protocol with an identity provider, for example, Microsoft Entra ID.
In Talon.One, a `Group` corresponds to a [role](https://docs.talon.one/docs/product/account/account-settings/managing-roles), and `members` are the [users](https://docs.talon.one/docs/product/account/account-settings/managing-users) assigned to that role.'
tags:
- Accounts and users
responses:
'200':
description: List of SCIM groups
content:
application/json:
schema:
$ref: '#/components/schemas/ScimGroupsListResponse'
post:
operationId: scimCreateGroup
summary: Create SCIM group
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.
Create a new Talon.One group using the SCIM Group provisioning protocol with an identity provider, for example, Microsoft Entra ID, and assign members from the payload to the new group.
In Talon.One, a `Group` corresponds to a [role](https://docs.talon.one/docs/product/account/account-settings/managing-roles), and `members` are the [users](https://docs.talon.one/docs/product/account/account-settings/managing-users) assigned to that role.'
tags:
- Accounts and users
requestBody:
$ref: '#/components/requestBodies/ScimNewGroup'
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/ScimGroup'
/v1/provisioning/scim/Groups/{groupId}:
get:
operationId: scimGetGroup
summary: Get SCIM group
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 data for a specific group created using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID.
In Talon.One, a `Group` corresponds to a [role](https://docs.talon.one/docs/product/account/account-settings/managing-roles), and `members` are the [users](https://docs.talon.one/docs/product/account/account-settings/managing-users) assigned to that role.'
tags:
- Accounts and users
parameters:
- name: groupId
in: path
description: The ID of the group.
example: 44
required: true
schema:
type: integer
responses:
'200':
description: Group details
content:
application/json:
schema:
$ref: '#/components/schemas/ScimGroup'
delete:
operationId: scimDeleteGroup
summary: Delete SCIM group
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.
Delete a specific group created using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID.
In Talon.One, a `Group` corresponds to a [role](https://docs.talon.one/docs/product/account/account-settings/managing-roles), and `members` are the [users](https://docs.talon.one/docs/product/account/account-settings/managing-users) assigned to that role.'
tags:
- Accounts and users
parameters:
- name: groupId
in: path
description: The ID of the group.
example: 44
required: true
schema:
type: integer
responses:
'204':
description: No Content
put:
operationId: scimReplaceGroupAttributes
summary: Update SCIM group
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.
Update the details of a specific group created using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID. This endpoint replaces all attributes of the given group with the attributes provided in the request payload.
In Talon.One, a `Group` corresponds to a [role](https://docs.talon.one/docs/product/account/account-settings/managing-roles), and `members` are the [users](https://docs.talon.one/docs/product/account/account-settings/managing-users) assigned to that role.
'
tags:
- Accounts and users
parameters:
- name: groupId
in: path
description: The ID of the group.
example: 44
required: true
schema:
type: integer
requestBody:
$ref: '#/components/requestBodies/ScimNewGroup'
responses:
'200':
description: Group details
content:
application/json:
schema:
$ref: '#/components/schemas/ScimGroup'
patch:
operationId: scimPatchGroup
summary: Update SCIM group attributes
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.
Update certain attributes of a group created using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID. This endpoint allows for selective adding, removing, or replacing of specific group attributes while other attributes remain unchanged.
In Talon.One, a `Group` corresponds to a [role](https://docs.talon.one/docs/product/account/account-settings/managing-roles), and `members` are the [users](https://docs.talon.one/docs/product/account/account-settings/managing-users) assigned to that role.
'
tags:
- Accounts and users
parameters:
- name: groupId
in: path
description: The ID of the group.
example: 44
required: true
schema:
type: integer
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ScimPatchRequest'
description: body
required: true
responses:
'200':
description: Group details
content:
application/json:
schema:
$ref: '#/components/schemas/ScimGroup'
/v1/provisioning/scim/Users:
get:
operationId: scimGetUsers
summary: List SCIM users
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 a paginated list of users that have been provisioned using the SCIM protocol with an identity provider, for example, Microsoft Entra ID.'
tags:
- Accounts and users
responses:
'200':
description: List of SCIM users
content:
application/json:
schema:
$ref: '#/components/schemas/ScimUsersListResponse'
post:
operationId: scimCreateUser
summary: Create SCIM user
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.
Create a new Talon.One user using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID.'
tags:
- Accounts and users
requestBody:
$ref: '#/components/requestBodies/ScimNewUser'
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/ScimUser'
/v1/provisioning/scim/Users/{userId}:
get:
operationId: scimGetUser
summary: Get SCIM user
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 data for a specific Talon.One user created using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID.'
tags:
- Accounts and users
parameters:
- name: userId
in: path
description: The ID of the user.
example: 33
required: true
schema:
type: integer
responses:
'200':
description: User details
content:
application/json:
schema:
$ref: '#/components/schemas/ScimUser'
delete:
operationId: scimDeleteUser
summary: Delete SCIM user
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.
Delete a specific Talon.One user created using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID.'
tags:
- Accounts and users
parameters:
- name: userId
in: path
description: The ID of the user.
example: 33
required: true
schema:
type: integer
responses:
'204':
description: No Content
put:
operationId: scimReplaceUserAttributes
summary: Update SCIM user
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.
Update the details of a specific Talon.One user created using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID.
This endpoint replaces all attributes of the specific user with the attributes provided in the request payload.
'
tags:
- Accounts and users
parameters:
- name: userId
in: path
description: The ID of the user.
example: 33
required: true
schema:
type: integer
requestBody:
$ref: '#/components/requestBodies/ScimNewUser'
responses:
'200':
description: User details
content:
application/json:
schema:
$ref: '#/components/schemas/ScimUser'
patch:
operationId: scimPatchUser
summary: Update SCIM user attributes
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.
Update certain attributes of a specific Talon.One user created using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID.
This endpoint allows for selective adding, removing, or replacing specific attributes while leaving other attributes unchanged.
'
tags:
- Accounts and users
parameters:
- name: userId
in: path
description: The ID of the user.
example: 33
required: true
schema:
type: integer
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ScimPatchRequest'
description: body
required: true
responses:
'200':
description: User details
content:
application/json:
schema:
$ref: '#/components/schemas/ScimUser'
/v1/provisioning/scim/ResourceTypes:
get:
operationId: scimGetResourceTypes
summary: List supported SCIM resource types
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 a list of resource types supported by the SCIM provisioning protocol.
Resource types define the various kinds of resources that can be managed via the SCIM API, such as users, groups, or custom-defined resources.
'
tags:
- Accounts and users
responses:
'200':
description: List of resource types
content:
application/json:
schema:
$ref: '#/components/schemas/ScimResourceTypesListResponse'
/v1/provisioning/scim/ServiceProviderConfig:
get:
operationId: scimGetServiceProviderConfig
summary: Get SCIM service provider configuration
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 configuration settings of the SCIM service provider. It provides details about the features and capabilities supported by the SCIM API, such as the different operation settings.
'
tags:
- Accounts and users
responses:
'200':
description: Service configuration
content:
application/json:
schema:
$ref: '#/components/schemas/ScimServiceProviderConfigResponse'
/v1/provisioning/scim/Schemas:
get:
operationId: scimGetSchemas
summary: List supported SCIM schemas
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 a list of schemas supported by the SCIM provisioning protocol.
Schemas define the structure and attributes of the different resources that can be managed via the SCIM API, such as users, groups, and any custom-defined resources.
'
tags:
- Accounts and users
responses:
'200':
description: List of schemas supported by the SCIM provisioning protocol
content:
application/json:
schema:
$ref: '#/components/schemas/ScimSchemasListResponse'
/v1/users/delete:
post:
operationId: deleteUserByEmail
summary: Delete user by email address
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.
[Delete a specific user](https://docs.talon.one/docs/product/account/account-settings/managing-users#deleting-a-user) by their email address.
'
tags:
- Accounts and users
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteUserRequest'
description: body
required: true
responses:
'204':
description: No Content
/v1/users/activate:
post:
operationId: activateUserByEmail
summary: Enable user by email address
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.
Enable a [disabled user](https://docs.talon.one/docs/product/account/account-settings/managing-users#disabling-a-user) by their email address.
'
tags:
- Accounts and users
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ActivateUserRequest'
description: body
required: true
responses:
'204':
description: No Content
/v1/users/deactivate:
post:
operationId: deactivateUserByEmail
summary: Disable user by email address
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.
[Disable a specific user](https://docs.talon.one/docs/product/account/account-settings/managing-users#disabling-a-user) by their email address.
'
tags:
- Accounts and users
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DeactivateUserRequest'
description: body
required: true
responses:
'204':
description: No Content
/v1/users/invite:
post:
operationId: inviteUserExternal
summary: Invite user from identity provider
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.
[Invite a user](https://docs.talon.one/docs/product/account/account-settings/managing-users#inviting-a-user) from an external identity provider to Talon.One by sending an invitation to their email address.
'
tags:
- Accounts and users
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/NewExternalInvitation'
description: body
required: true
responses:
'204':
description: Invitation email sent
/v2/invites:
post:
operationId: createInviteV2
summary: Invite user
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.
Create a new user in the account and send an invitation to their email
address.
> [!note] The invitation token is valid for 24 hours after the email has
> been sent. You can resend an invitation to a user with the [Resend
> invitation email](https://docs.talon.one/management-api#tag/Accounts-and-users/operation/createInviteEmail)
> endpoint.
'
tags:
- Accounts and users
requestBody:
$ref: '#/components/requestBodies/NewInvitation'
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/User'
/v1/invite_emails:
post:
operationId: createInviteEmail
summary: Resend invitation email
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.
Resend an email invitation to an existing user.
> [!note] The invitation token is valid for 24 hours after the email has been sent.
'
tags:
- Accounts and users
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/NewInviteEmail'
description: body
required: true
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/NewInviteEmail'
/v1/password_recovery_emails:
post:
operationId: createPasswordRecoveryEmail
summary: Request a password reset
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.
Send an email with a password recovery link to the email address of an
existing account.
> [!note] The password recovery link expires 30 minutes after this endpoint is triggered.
'
tags:
- Accounts and users
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/NewPasswordEmail'
description: body
required: true
responses:
'204':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/NewPasswordEmail'
/v1/reset_password:
post:
operationId: resetPassword
summary: Reset password
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.
Consumes the supplied password reset token and updates the password for
the associated account.
'
tags:
- Accounts and users
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/NewPassword'
description: body
required: true
responses:
'204':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/NewPassword'
/v1/accounts/{accountId}:
get:
operationId: getAccount
summary: Get account details
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.
Return the details of your companies Talon.One account.
'
tags:
- Accounts and users
parameters:
- name: accountId
in: path
description: 'The identifier of the account. Retrieve it via the
[List users in account](https://docs.talon.one/management-api#tag/Accounts-and-users/operation/getUsers) endpoint in the `accountId`
property.
'
example: 28
required: true
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Account'
/v1/accounts/{accountId}/analytics:
get:
operationId: getAccountAnalytics
summary: Get account analytics
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.
Return the analytics of your Talon.One account.
'
tags:
- Accounts and users
parameters:
- name: accountId
in: path
description: 'The identifier of the account. Retrieve it via the
[List users in account](https://docs.talon.one/management-api#tag/Accounts-and-users/operation/getUsers) endpoint in the `accountId`
property.
'
example: 28
required: true
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AccountAnalytics'
components:
schemas:
ScimResourceTypesListResponse:
type: object
description: List of resource types supported by the SCIM provisioning protocol.
required:
- Resources
properties:
Resources:
type: array
items:
$ref: '#/components/schemas/ScimResource'
AccountEntity:
type: object
required:
- accountId
properties:
accountId:
type: integer
description: The ID of the account that owns this entity.
example: 3886
NewInviteEmail:
type: object
required:
- email
- token
proper
# --- truncated at 32 KB (60 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/talon-one/refs/heads/main/openapi/talon-one-accounts-and-users-api-openapi.yml