openapi: 3.0.1
info:
version: ''
title: Third-party API
description: |
Use the Third-party API to exchange data between Talon.One and one of the supported [technology partners](https://docs.talon.one/docs/dev/technology-partners/overview).
For example, use the Braze-specific endpoints from your Braze campaigns to interact with Talon.One.
If the CDP or CEP you are using isn't listed here, use the generic
[Customer Data Platforms](#tag/Customer-data-platforms) and [Customer Engagement Platform](#tag/Customer-engagement-platforms) endpoints.
> [!note]
> All endpoints of this API start with `https://integration.talon.one`.
> You must specify the base URL of your deployment in the headers or parameters.
> [!note] **Are you looking for a different API?**
> - To implement use cases that aren't covered by the Third-party API, see the [Integration API](https://docs.talon.one/management-api).
> - To interact with the Campaign Manager for back-office operations, see the [Management API](https://docs.talon.one/management-api).
servers:
- url: https://integration.talon.one
security:
- ApiKeyAuth: []
tags:
- name: Braze
description: |
[Braze](https://www.braze.com/) is a customer engagement platform to manage customer-centric interactions between consumers and brands in real-time.
Use these endpoints to automate the creation of coupon and referral codes
and deliver them to specific customer segments. To send requests to these endpoints, use the
[connected content feature](https://www.braze.com/docs/user_guide/personalization_and_dynamic_content/connected_content/connected_content_retries) in Braze.
For more information, see our integration examples in [the developer docs](https://docs.talon.one/docs/dev/technology-partners/braze).
- name: Customer data platforms
description: |
You can integrate with any customer data platform, or CDP, using the following endpoints designed for third-party tools, rather than your own integration layer.
Use these endpoints to automate the creation of coupon and referral codes and deliver them to specific customer segments.
- name: Customer engagement platforms
description: |
You can integrate with any customer engagement platform, or CEP, using the following endpoints designed for third-party tools, rather than your own integration layer.
Use these endpoints to automate the creation of coupon and referral codes and deliver them to specific customer segments.
For more information, see our integration examples in [the developer docs](https://docs.talon.one/docs/dev/technology-partners/cep/integrating-cep).
- name: Emarsys
description: |
Emarsys is a customer engagement platform that enables marketers to build, launch, and scale personalized cross-channel promotional campaigns that have measurable impact.
Use these endpoints to integrate with Talon.One.
- name: Iterable
description: |
[Iterable](https://iterable.com/) is a cross-channel marketing platform that powers unified customer experiences
and empowers you to create, optimize and measure every interaction across the entire customer journey.
Use these endpoints to automate the creation of coupon and referral codes
and deliver them to specific customer segments. To send requests to these endpoints, use the
[data feed feature](https://support.iterable.com/hc/en-us/articles/360044425931#enable-template-generation-using-data-feeds) in Iterable.
For more information, see our integration examples in [the developer docs](https://docs.talon.one/docs/dev/technology-partners/iterable).
- name: mParticle
description: |
[mParticle](https://www.mparticle.com/) is the customer data platform that helps unify data and simplify partner integrations with enterprise-class security and reliability.
For more information, see our integration examples in [the developer docs](https://docs.talon.one/docs/dev/technology-partners/mparticle).
- name: Segment
description: |
[Segment](https://segment.com/) is a customer data platform that collects events from your web & mobile apps.
Use these endpoints to integrate with Talon.One.
paths:
/braze/referral:
post:
tags:
- Braze
summary: Create referral (Braze)
operationId: braze/createReferral
description: |
Create a referral code in Talon.One. To use it in your Braze deployment, see [the tutorial](https://docs.talon.one/docs/dev/technology-partners/braze/creating-referrals-braze).
parameters:
- $ref: '#/components/parameters/dryRun'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ReferralRequest'
examples:
default:
$ref: '#/components/examples/ReferralRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ReferralResponse'
examples:
default:
$ref: '#/components/examples/ReferralResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/braze/coupon:
post:
tags:
- Braze
summary: Create coupon (Braze)
operationId: braze/createCoupon
description: |
Create a coupon code in Talon.One. To use it in your Braze deployment, see [the tutorial](https://docs.talon.one/docs/dev/technology-partners/braze/creating-coupons-braze).
You can also use this endpoint to get an existing coupon's details by setting the `identifier` property to a value you previously used.
> [!tip]
> You can edit the default coupon code format in the [campaign's settings](https://docs.talon.one/docs/product/campaigns/coupons/coupon-page-overview#editing-coupon-format).
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BrazeCouponRequest'
examples:
default:
$ref: '#/components/examples/BrazeCouponRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BrazeCouponResponse'
examples:
default:
$ref: '#/components/examples/BrazeCouponResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/braze/coupon_reservation:
post:
tags:
- Braze
summary: Create coupon reservation (Braze)
operationId: braze/createCouponReservation
description: |
Create a coupon reservation for a specified customer profile on the specified coupon.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CouponReservationRequest'
examples:
default:
$ref: '#/components/examples/CouponReservationRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CouponReservationResponse'
examples:
default:
$ref: '#/components/examples/CouponReservationResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/braze/event:
post:
tags:
- Braze
summary: Track event (Braze)
operationId: braze/trackEvent
description: |
Triggers a custom event inside Talon.One. You can then trigger rules when this event is received.
An event is a type of custom attribute. You must create it first in the Campaign Manager. See [creating custom events](https://docs.talon.one/docs/dev/concepts/entities/events#custom-events).
To see the events received by your Application in Talon.One, open the Application and click **Events**.
For more information, see [the tutorial](https://docs.talon.one/docs/dev/technology-partners/braze/adding-loyalty-points-braze).
parameters:
- $ref: '#/components/parameters/destinationHostname'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BrazeTrackEventRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationStateV2'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/iterable/coupon:
get:
tags:
- Iterable
summary: Create coupon (Iterable)
operationId: iterable/createCoupon
description: |
Create a coupon code in Talon.One. To use it in your Iterable deployment and generate
the request, see [the tutorial](https://docs.talon.one/docs/dev/technology-partners/iterable/creating-coupons-iterable).
> [!tip]
> You can edit the default coupon code format in the [campaign's settings](https://docs.talon.one/docs/product/campaigns/coupons/coupon-page-overview#editing-coupon-format).
parameters:
- $ref: '#/components/parameters/deployment'
- $ref: '#/components/parameters/applicationId'
- $ref: '#/components/parameters/campaignId'
- $ref: '#/components/parameters/startDate'
- $ref: '#/components/parameters/expiryDate'
- $ref: '#/components/parameters/discountLimit'
- $ref: '#/components/parameters/iterableCampaignId'
- $ref: '#/components/parameters/recipientIntegrationId'
- $ref: '#/components/parameters/usageLimitCoupons'
- $ref: '#/components/parameters/attributes'
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/CouponResponse'
examples:
default:
$ref: '#/components/examples/CouponResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/iterable/referral:
get:
tags:
- Iterable
summary: Create referral (Iterable)
operationId: iterable/createReferral
description: |
Create a referral code in Talon.One. To use it in your Iterable deployment and generate
the request, see [the tutorial](https://docs.talon.one/docs/dev/technology-partners/iterable/creating-referral-iterable).
parameters:
- $ref: '#/components/parameters/deployment'
- $ref: '#/components/parameters/campaignId'
- $ref: '#/components/parameters/advocateProfileIntegrationId'
- $ref: '#/components/parameters/friendProfileIntegrationId'
- $ref: '#/components/parameters/startDate'
- $ref: '#/components/parameters/expiryDate'
- $ref: '#/components/parameters/usageLimit'
- $ref: '#/components/parameters/attributes'
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/ReferralResponse'
examples:
default:
$ref: '#/components/examples/ReferralResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/iterable/loyalty:
get:
tags:
- Iterable
summary: Get loyalty ledger (Iterable)
operationId: iterable/loyalty
description: |
Get the loyalty ledger information of the given customer profile from Talon.One. To use it in your Iterable deployment and generate
the request, see [the tutorial](https://docs.talon.one/docs/dev/technology-partners/iterable/getting-loyalty-iterable).
This endpoint only works with [profile-based](https://docs.talon.one/docs/product/loyalty-programs/profile-based/profile-based-overview) loyalty programs.
parameters:
- $ref: '#/components/parameters/deployment'
- $ref: '#/components/parameters/profileIntegrationId'
- $ref: '#/components/parameters/loyaltyProgramId'
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/LoyaltyResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/segment/customer_profile/{customerProfileId}:
put:
tags:
- Segment
parameters:
- $ref: '#/components/parameters/destinationHostname'
- name: customerProfileId
in: path
description: The integration ID of the customer profile. If the customer profile does not exist, it will be created.
example: customer1
required: true
schema:
type: string
summary: Upsert customer profile v1 (Segment)
operationId: segment/updateCustomerProfile
deprecated: true
description: |
> [!warning] **This endpoint is deprecated.**
> We recommend you use the current [Update customer profile](#tag/Segment/operation/segment/v2/updateCustomerProfile) endpoint.
Create or update the given customer profile, and creates or set the specified attributes. You can also
use this endpoint to specify which audiences this customer has joined or left.
> [!note] **Note**
> The audiences must be created first using [Create audience](#tag/Segment/operation/segment/createAudience).
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentCustomerProfileRequest'
examples:
default:
$ref: '#/components/examples/SegmentCustomerProfileRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerProfileResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/SegmentTooManyRequestsOrParallel'
/segment/customer_profile_v2/{customerProfileId}:
put:
tags:
- Segment
parameters:
- $ref: '#/components/parameters/destinationHostname'
- name: customerProfileId
in: path
description: The integration ID of the customer profile.
example: customer1
required: true
schema:
type: string
summary: Upsert customer profile v2 (Segment)
operationId: segment/updateCustomerProfileV2
deprecated: true
description: |
> [!warning] **This endpoint is deprecated.**
> We recommend you use the current [Update customer profile](#tag/Segment/operation/segment/v2/updateCustomerProfile) endpoint.
Create or update the given customer profile, and also creates or set the specified attributes and audiences.
You **do not** have to create attributes or audiences before using this endpoint.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentCustomerProfileRequestV2'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerProfileResponseV2'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/SegmentTooManyRequestsOrParallel'
/segment/v2/customer_profiles/{customerProfileId}:
put:
tags:
- Segment
parameters:
- $ref: '#/components/parameters/destinationHostname'
- $ref: '#/components/parameters/skipNonExistingAttributes'
- name: customerProfileId
in: path
description: The integration ID of the customer profile. If the customer profile does not exist, it will be created.
example: customer1
required: true
schema:
type: string
summary: Update customer profile (Segment)
operationId: segment/v2/updateCustomerProfile
description: |
Update or create a [customer profile](https://docs.talon.one/docs/dev/concepts/entities/customer-profiles). This endpoint triggers the Rule Builder.
You can use this endpoint for the following tasks:
- Set attributes for the given customer profile. Ensure you create the attributes in the Campaign Manager first.
- Add the customer profile to audiences or remove it from audiences.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentCustomerProfileV2Request'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerProfileIntegrationResponseV2'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/SegmentTooManyRequestsOrParallel'
/segment/customer_profiles/{customerProfileId}/audiences:
put:
tags:
- Segment
parameters:
- $ref: '#/components/parameters/destinationHostname'
- name: customerProfileId
in: path
description: The integration ID of the customer profile. If the customer profile does not exist, it will be created.
required: true
example: customer1
schema:
type: string
summary: Update customer profile audiences using external ID (Segment)
operationId: segment/updateCustomerProfileAudiences
description: |
Add a [customer profile](https://docs.talon.one/docs/dev/concepts/entities/customer-profiles) to or remove it from a list of audiences. This endpoint triggers the Rule Builder.
To identify the audience, you can use its ID in Segment.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SingleCustomerProfileIntegrationAudiencesRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationStateV2'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/segment/customer_profiles/audiences:
parameters:
- $ref: '#/components/parameters/destinationHostname'
put:
tags:
- Segment
summary: Update audiences in multiple customer profiles (Segment)
operationId: segment/updateCustomerProfilesAudiences
description: |
Update the specified audiences for the specified profiles.
If a provided customer profile doesn't exist, it will be created.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerProfilesAudiencesRequest'
responses:
'204':
description: No Content
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/SegmentTooManyRequests'
/segment/v2/customer_profiles/audiences:
parameters:
- $ref: '#/components/parameters/destinationHostname'
put:
tags:
- Segment
summary: Update audiences in multiple customer profiles using external ID (Segment)
operationId: segment/v2/updateCustomerProfilesAudiences
description: |
Update the specified audiences for the specified profiles. To identify the audience, you can use its ID in the third-party integration.
If a provided customer profile doesn't exist, it will be created.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerProfilesIntegrationAudiencesRequest'
responses:
'204':
description: No Content
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/segment/event:
parameters:
- $ref: '#/components/parameters/destinationHostname'
put:
tags:
- Segment
summary: Track event v1 (Segment)
operationId: segment/trackEvent
deprecated: true
description: |
**Important:** This endpoint is deprecated. We recommend you use the current [Track Event](#tag/Segment/operation/segment/trackEventV2) endpoint.
Triggers a custom event inside Talon.One. You can then trigger rules when this event is received.
An event is a type of custom attribute, you must create it first in the Campaign Manager. See [creating custom events](https://docs.talon.one/docs/dev/concepts/entities/events#custom-events).
To see the events received by your Application in Talon.One, open the Application and click **Events**.
If the specified session already exists, it must belong to the same `profileId` or an error will be returned.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentTrackEventRequest'
examples:
default:
$ref: '#/components/examples/SegmentTrackEventRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationStateV2'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/SegmentTooManyRequestsOrParallel'
/segment/v2/events:
parameters:
- $ref: '#/components/parameters/destinationHostname'
- $ref: '#/components/parameters/skipNonExistingAttributes'
put:
tags:
- Segment
summary: Track event v2 (Segment)
operationId: segment/trackEventV2
description: |
Trigger a custom event inside Talon.One. You can then trigger rules when this event is received.
An event is a type of custom attribute, you must create it first in the Campaign Manager. See [creating custom events](https://docs.talon.one/docs/dev/concepts/entities/events#custom-events).
To see the events received by your Application in Talon.One, open the Application and click **Events**.
If the specified session already exists, it must belong to the same `profileId`, or else an error is returned.
> [!note] **Note**
> - Create the event and all the required attributes before using this endpoint.
> - This `v2` version replaces the previous `v1` version of this endpoint.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentTrackEventV2Request'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationStateV2'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/SegmentTooManyRequestsOrParallel'
/segment/audiences:
parameters:
- $ref: '#/components/parameters/destinationHostname'
post:
tags:
- Segment
summary: Create audience (Segment)
operationId: segment/createAudience
description: |
Create an audience. The audience can be created directly from scratch or can come from Segment.
Once you create your first audience, audience-specific rule conditions are enabled in the Rule Builder
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAndUpdateAudienceRequest'
responses:
'201':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAndUpdateResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/AudienceAlreadyExist'
'429':
$ref: '#/components/responses/SegmentTooManyRequests'
/segment/audiences/{audienceId}:
parameters:
- $ref: '#/components/parameters/audienceId'
- $ref: '#/components/parameters/destinationHostname'
put:
tags:
- Segment
summary: Update audience (Segment)
operationId: segment/updateAudience
description: |
Update an audience.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAndUpdateAudienceRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAndUpdateResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/SegmentTooManyRequests'
delete:
tags:
- Segment
summary: Delete audience (Segment)
operationId: segment/deleteAudience
description: |
Delete the audience.
**Warning:** This endpoint also removes any associations recorded between a customer profile and this audience.
responses:
'204':
description: No Content
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/SegmentTooManyRequests'
/segment/customer_sessions/{customerSessionId}:
put:
tags:
- Segment
summary: Update customer session v1 (Segment)
operationId: segment/updateCustomerSession
deprecated: true
description: |
**Important:** This endpoint is deprecated. We recommend you use the current [Update customer session](#tag/Segment/operation/segment/v2/updateCustomerSession) endpoint.
Update the given customer session, or creates it if it doesn't exist.
Customer sessions are a key concept in Talon.One, see the [documentation](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions).
This endpoint also allows you to define a callback where the response will be sent. See the **Header parameters** section below.
parameters:
- $ref: '#/components/parameters/destinationHostname'
- $ref: '#/components/parameters/callbackDestinationURI'
- $ref: '#/components/parameters/callbackAPIKey'
- $ref: '#/components/parameters/contentFields'
- $ref: '#/components/parameters/correlationID'
- name: customerSessionId
in: path
description: |
The `integration ID` of the customer session. You set this ID when you create a customer session.
You can see existing customer session integration IDs in the Campaign Manager's **Sessions** menu, or via the
[List Application session endpoint](https://docs.talon.one/management-api#operation/getApplicationSessions).
example: session1
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCustomerSessionRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationStateV2'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/SegmentTooManyRequestsOrParallel'
/segment/v2/customer_sessions/{customerSessionId}:
put:
tags:
- Segment
summary: Update customer session v2 (Segment)
operationId: segment/v2/updateCustomerSession
description: |
Update the given customer session, or create a customer session if it doesn't exist.
Customer sessions are a key concept in Talon.One, see the [documentation](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions).
This endpoint also allows you to define a callback where the response will be sent. See the **Header parameters** section below.
> [!note] **Note**
> - Create the all the required attributes before using this endpoint.
> - This `v2` version replaces the previous `v1` version of this endpoint.
parameters:
- $ref: '#/components/parameters/destinationHostname'
- $ref: '#/components/parameters/callbackDestinationURI'
- $ref: '#/components/parameters/callbackAPIKey'
- $ref: '#/components/parameters/contentFields'
- $ref: '#/components/parameters/correlationID'
- $ref: '#/components/parameters/skipNonExistingAttributes'
- name: customerSessionId
in: path
description: |
The `integration ID` of the customer session. You set this ID when you create a customer session.
You can see the existing customer session integration IDs in the Campaign Manager's **Sessions** menu, or via the
[List Application session](https://docs.talon.one/management-api#operation/getApplicationSessions) endpoint.
example: session1
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/newCustomerSessionV2'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationStateV2'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/SegmentTooManyRequestsOrParallel'
/cdp/customer_profile/{customerProfileId}:
parameters:
- $ref: '#/components/parameters/customerDataPlatformName'
- $ref: '#/components/parameters/destinationHostname'
- $ref: '#/components/parameters/skipNonExistingAttributes'
put:
tags:
- Customer data platforms
parameters:
- name: customerProfileId
in: path
description: The integration ID of the customer profile. If the customer profile does not exist, it will be created.
required: true
example: customer1
schema:
type: string
summary: Update customer profile (CDP)
operationId: cdp/updateCustomerProfile
description: |
Update or create a [customer profile](https://docs.talon.one/docs/dev/concepts/entities/customer-profiles). This endpoint triggers the Rule Builder.
You can use this endpoint for the following tasks:
- Set attributes for the given customer profile. Ensure you create the attributes in the Campaign Manager first.
- Add the customer profile to audiences or remove it from audiences.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CDPCustomerProfileRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationStateV2'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/cdp/customer_profile/{customerProfileId}/audiences:
parameters:
- $ref: '#/components/parameters/customerDataPlatformName'
- $ref: '#/components/parameters/destinationHostname'
put:
tags:
- Customer data platforms
parameters:
- name: customerProfileId
in: path
description: The integration ID of the customer profile. If the customer profile does not exist, it will be created.
required: true
example: customer1
schema:
type: string
summary: Update customer profile audiences using external ID (CDP)
operationId: cdp/updateCustomerProfileAudiences
description: |
Add a [customer profile](https://docs.talon.one/docs/dev/concepts/entities/customer-profiles) to or remove it from a list of audiences. This endpoint triggers the Rule Builder.
To identify the audience, you can use its ID in the third-party integration.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SingleCustomerProfileIntegrationAudiencesRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationStateV2'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/cdp/customer_profiles/audiences:
parameters:
- $ref: '#/components/parameters/customerDataPlatformName'
- $ref: '#/components/parameters/destinationHostname'
put:
tags:
- Customer data platforms
summary: Update audiences in multiple customer profiles (CDP)
operationId: cdp/updateCustomerProfilesAudiences
description: |
Update the specified audiences for the specified profiles.
If a provided customer profile doesn't exist, it will be created.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerProfilesAudiencesRequest'
responses:
'204':
description: No Content
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/cdp/v2/customer_profiles/audiences:
parameters:
- $ref: '#/components/parameters/customerDataPlatformName'
- $ref: '#/components/parameters/destinationHostname'
put:
tags:
- Customer data platforms
summary: Update audiences in multiple customer profiles using external ID (CDP)
operationId: cdp/v2/updateCustomerProfilesAudiences
description: |
Update the specified audiences for the specified profiles. To identify the audience, you can use its ID in the third-party integration.
If a provided customer profile doesn't exist, it will be created.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerProfilesIntegrationAudiencesRequest'
responses:
'204':
description: No Content
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/cdp/audiences:
parameters:
- $ref: '#/components/parameters/customerDataPlatformName'
- $ref: '#/components/parameters/destinationHostname'
post:
tags:
- Customer data platforms
summary: Create audience (CDP)
operationId: cdp/createAudience
description: |
Create an audience. The audience can be created directly from scratch or can come from third party platforms.
Once you create your first audience, audience-specific rule conditions are enabled in the Rule Builder.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAndUpdateAudienceRequest'
responses:
'201':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAndUpdateResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/AudienceAlreadyExist'
'429':
$ref: '#/components/responses/TooManyRequests'
/cdp/audiences/{audienceId}:
parameters:
- $ref: '#/components/parameters/audienceId'
- $ref: '#/components/parameters/customerDataPlatformName'
- $ref: '#/components/parameters/destinationHostname'
put:
tags:
- Customer data platforms
summary: Update audience (CDP)
operationId: cdp/updateAudience
description: |
Update an audience created by a third-party integration.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAndUpdateAudienceRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAndUpdateResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
delete:
tags:
- Customer data platforms
summary: Delete audience (CDP)
operationId: cdp/deleteAudience
description: |
Delete an audience created by a third-party integration.
**Warning:** This endpoint also removes any associations recorded between a customer profile and this audience.
responses:
'204':
description: No Content
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/customer_engagement/coupon:
get:
tags:
- Customer engagement platforms
summary: Create coupon (CEP)
operationId: cep/createCoupon
description: |
Create a coupon code in Talon.One. See [the tutorial](https://docs.talon.one/docs/dev/technology-partners/cep/integrating-cep).
> [!tip]
> You can edit the default coupon code format in the [campaign's settings](https://docs.talon.one/docs/product/campaigns/coupons/coupon-page-overview#editing-coupon-format).
parameters:
- $ref: '#/components/parameters/customerEngagementPlatformName'
- $ref: '#/components/parameters/destinationHostname'
- $ref: '#/components/parameters/applicationId'
- $ref: '#/components/parameters/campaignId'
- $ref: '#/components/parameters/externalCampaignId'
- $ref: '#/components/parameters/startDate'
- $ref: '#/components/parameters/expiryDate'
- $ref: '#/components/parameters/dryRun'
- $ref: '#/components/parameters/discountLimit'
- $ref: '#/components/parameters/recipientIntegrationId'
- $ref: '#/components/parameters/usageLimitCoupons'
- $ref: '#/components/parameters/attributes'
- $ref: '#/components/parameters/identifier'
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/CouponResponse'
examples:
default:
$ref: '#/components/examples/CouponResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/customer_engagement/referral:
get:
tags:
- Customer engagement platforms
summary: Create referral (CEP)
operationId: cep/createReferral
description: |
Create a referral code in Talon.One. See [the tutorial](https://docs.talon.one/docs/dev/technology-partners/cep/integrating-cep).
parameters:
- $ref: '#/components/parameters/customerEngagementPlatformName'
- $ref: '#/components/parameters/destinationHostname'
- $ref: '#/components/parameters/dryRun'
- $ref: '#/components/parameters/campaignId'
- $ref: '#/components/parameters/advocateProfileIntegrationId'
- $ref: '#/components/parameters/friendProfileIntegrationId'
- $ref: '#/components/parameters/startDate'
- $ref: '#/components/parameters/expiryDate'
- $ref: '#/components/parameters/usageLimit'
- $ref: '#/components/parameters/attributes'
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/ReferralResponse'
examples:
default:
$ref: '#/components/examples/ReferralResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/customer_engagement/loyalty:
get:
tags:
- Customer engagement platforms
summary: Get loyalty ledger (CEP)
operationId: cep/loyalty
description: |
Get the loyalty ledger information of the given customer profile from Talon.One. See [the tutorial](https://docs.talon.one/docs/dev/technology-partners/cep/integrating-cep).
This endpoint only works with [profile-based](https://docs.talon.one/docs/product/loyalty-programs/profile-based/profile-based-overview) loyalty programs.
parameters:
- $ref: '#/components/parameters/customerEngagementPlatformName'
- $ref: '#/components/parameters/destinationHostname'
- $ref: '#/components/parameters/profileIntegrationId'
- $ref: '#/components/parameters/loyaltyProgramId'
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/LoyaltyResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/customer_engagement/add_loyalty_points:
post:
tags:
- Customer engagement platforms
summary: Add loyalty points (CEP)
operationId: cep/addLoyaltyPoints
description: |
Add points in the specified loyalty program for the given customer.
This endpoint only works with [profile-based](https://docs.talon.one/docs/product/loyalty-programs/profile-based/profile-based-overview) loyalty programs.
parameters:
- $ref: '#/components/parameters/customerEngagementPlatformName'
- $ref: '#/components/parameters/destinationHostname'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AddLoyaltyPointsRequest'
responses:
'204':
description: No Content
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/mparticle:
post:
tags:
- mParticle
summary: Send event (mParticle)
operationId: mparticle/sendevent
description: |
Send an mParticle event to Talon.One.
This endpoint supports the following mParticle events:
- `module_registration_request`: A new client has set up the Talon.One integration in mParticle.
- `audience_membership_change_request`: Customers have been added to or removed from an audience in mParticle.
- `audience_subscription_request`: An audience has been added, updated, or deleted in mParticle.
- `event_processing_request`: One or more events have been triggered in mParticle.
> [!warning]
> This endpoint is not meant to be triggered manually. The above events are handled internally when using mParticle's feed inputs, event outputs, and audience outputs.
security: []
requestBody:
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ModuleRegistrationRequest'
- $ref: '#/components/schemas/AudienceMembershipChangeRequest'
- $ref: '#/components/schemas/AudienceSubscriptionRequest'
- $ref: '#/components/schemas/EventProcessingRequest'
examples:
moduleRegistrationRequest:
$ref: '#/components/examples/ModuleRegistrationRequest'
audienceMembershipChangeRequest:
$ref: '#/components/examples/AudienceMembershipChangeRequest'
audienceSubscriptionRequest:
$ref: '#/components/examples/AudienceSubscriptionRequest'
eventProcessingRequest:
$ref: '#/components/examples/EventProcessingRequest'
responses:
'200':
description: Response
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ModuleRegistrationResponse'
- $ref: '#/components/schemas/AudienceSubscriptionResponse'
- $ref: '#/components/schemas/AudienceMembershipChangeResponse'
- $ref: '#/components/schemas/EventProcessingResponse'
examples:
moduleRegistrationResponse:
$ref: '#/components/examples/ModuleRegistrationResponse'
audienceSubscriptionResponse:
$ref: '#/components/examples/AudienceSubscriptionResponse'
audienceMembershipChangeResponse:
$ref: '#/components/examples/AudienceMembershipChangeResponse'
eventProcessingResponse:
$ref: '#/components/examples/EventProcessingResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'409':
$ref: '#/components/responses/AudienceAlreadyExist'
'429':
$ref: '#/components/responses/TooManyRequests'
/emarsys/customer_profiles/coupons:
post:
security:
- ApiKeyBasicAuth: []
tags:
- Emarsys
summary: Get coupon (Emarsys)
operationId: emarsys/getCoupon
description: |
Retrieve a coupon code from Talon.One.
parameters:
- $ref: '#/components/parameters/deployment'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EmarsysCouponRequest'
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/EmarsysCouponResponse'
examples:
default:
$ref: '#/components/examples/EmarsysCouponResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/emarsys/loyalty_programs/profile/balance:
post:
security:
- ApiKeyBasicAuth: []
tags:
- Emarsys
summary: Get loyalty balance (Emarsys)
operationId: emarsys/getLoyaltyProgramBalance
description: |
Retrieve the loyalty balance of a customer profile from Talon.One.
This endpoint only works with [profile-based](https://docs.talon.one/docs/product/loyalty-programs/profile-based/profile-based-overview) loyalty programs.
parameters:
- $ref: '#/components/parameters/deployment'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EmarsysLoyaltyBalanceRequest'
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/EmarsysLoyaltyBalanceResponse'
examples:
default:
$ref: '#/components/examples/EmarsysLoyaltyBalanceResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/emarsys/customer_profiles/audiences:
post:
security:
- ApiKeyBasicAuth: []
tags:
- Emarsys
summary: Update audiences in multiple customer profiles (Emarsys)
operationId: emarsys/v2/updateCustomerProfilesAudiences
description: |
Update the specified audiences for the specified profiles. To identify the audience, you can use its ID in the third-party integration.
If a provided customer profile doesn't exist, it will be created.
parameters:
- $ref: '#/components/parameters/deployment'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EmarsysCustomerProfilesAudiencesRequest'
examples:
default:
$ref: '#/components/examples/EmarsysCustomerProfilesAudiencesRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmarsysUpdateAudiencesResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
components:
parameters:
audienceId:
name: audienceId
in: path
description: The integration ID of the audience.
required: true
schema:
type: string
example: audience1
customerDataPlatformName:
name: customer-data-platform-name
in: header
description: The name of the CDP platform.
required: true
schema:
type: string
format: string
example: My CDP platform
deployment:
name: deployment
in: query
description: The base URL of your Talon.One deployment.
schema:
type: string
required: true
example: mycompany.europe-west1.talon.one
campaignId:
name: campaignId
in: query
description: The ID of the campaign in Talon.One. It is displayed in your Talon.One deployment URL.
schema:
type: integer
format: int64
required: true
example: 5843
applicationId:
name: applicationId
in: query
description: The ID of the Application in Talon.One. It is displayed in your Talon.One deployment URL.
schema:
type: integer
format: int64
required: true
example: 316
startDate:
description: The date when the code becomes usable.
name: startDate
in: query
schema:
type: string
format: date-time
example: '2022-09-30T15:35:02Z'
expiryDate:
description: The date when the code becomes unusable.
name: expiryDate
in: query
schema:
type: string
format: date-time
example: '2022-10-30T15:35:02Z'
advocateProfileIntegrationId:
name: advocateProfileIntegrationId
in: query
description: The integration ID of the advocate.
schema:
type: string
required: true
example: testAdvocateProfile
friendProfileIntegrationId:
name: friendProfileIntegrationId
in: query
description: The profile ID of the referred customer.
schema:
type: string
example: testFriendProfile
usageLimit:
name: usageLimit
in: query
description: Number of times a referral code can be used. This can be set to 0 for no limit, but any campaign usage limits will still apply.
schema:
type: integer
format: int64
example: 1
usageLimitCoupons:
name: usageLimit
in: query
description: The number of times the coupon code can be redeemed. 0 means unlimited redemptions but any campaign usage limits will still apply. The default value is 1.
schema:
type: integer
format: int64
default: 1
example: 1
discountLimit:
name: discountLimit
in: query
description: The discount amount the coupon is worth. Can be blank if, for example, the coupon provides a 10% discount, or something other than a fixed value of discounts.
schema:
type: integer
format: int64
example: 155
iterableCampaignId:
name: iterableCampaignId
in: query
description: The ID of the campaign in Iterable.
schema:
type: string
required: true
example: iterableCampaign
recipientIntegrationId:
name: recipientIntegrationId
in: query
description: The integration ID of the only customer that can use the generated coupon code. Leave blank to allow any user to use the coupon.
schema:
type: string
example: URN-GV8294NV
profileIntegrationId:
name: profileIntegrationId
in: query
description: The integration ID of the customer profile in Talon.One.
schema:
type: string
required: true
example: URN-GV8294NV
loyaltyProgramId:
name: loyaltyProgramId
in: query
description: The ID of the profile-based loyalty program in Talon.One.
schema:
type: integer
format: int64
required: true
example: 25
customerEngagementPlatformName:
name: customer-engagement-platform-name
in: header
description: The name of the third-party platform.
schema:
type: string
required: true
example: My CEP platform
destinationHostname:
name: destination-hostname
in: header
description: The base URL of your Talon.One deployment.
required: true
schema:
type: string
format: hostname
example: mycompany.europe-west1.talon.one
dryRun:
name: X-DRY-RUN
in: header
description: Indicates whether to persist the changes. Changes are ignored when `X-DRY-RUN=true`.
schema:
type: boolean
example: true
externalCampaignId:
name: externalCampaignId
in: query
description: The ID of the campaign in the third-party platform.
schema:
type: string
example: testCampaignId
required: true
attributes:
name: attributes
in: query
description: |
Optional parameter to set the value of custom attributes. They are defined in the Campaign Manager,
see [Managing attributes](https://docs.talon.one/docs/product/account/dev-tools/managing-attributes).
Prefix each attribute name with `.` or `_`.
Certain attributes can also be set to _mandatory_ in your Application [settings](https://docs.talon.one/docs/product/applications/using-attributes#making-attributes-mandatory).
If your Application uses mandatory attributes, you must use this parameter to set their value.
The type of the value must match the type of the attribute. If you provide an integer value, the attribute must also be of type Integer in Talon.One.
If the types do not match, and the attribute in Talon.One is of type String, put the value in quotes. For example, if you provide a Boolean value for a String attribute, use `"true"` and `"false"`.
Full URI example: `https://?applicationId=5&.myIntegerAttribute=1234&.myStringAttribute1=Text&.myStringAttribute2="1234"&.myStringAttribute3="true"`.
schema:
type: object
additionalProperties: true
style: form
explode: true
example:
.firstName: john
.country: DE
callbackDestinationURI:
name: X-Callback-Destination-URI
in: header
description: |
The **full** URI where Talon.One sends the response content. The callback is a `POST` request.
schema:
type: string
format: hostname
example: http://mydomain.com/api/callbacks
callbackAPIKey:
name: X-Callback-API-Key
in: header
description: |
The header and the API key, separated by a space. The first space marks the header.
For example:
- To set `Authorization: 3aa74d582bd94`, use `Authorization 3aa74d582bd94`.
- To set `Authorization: ApiKey-v1 3aa74d582bd94`, use `Authorization ApiKey-v1 3aa74d582bd94`.
The minimal length of the API key is 32 characters.
example: Authorization 3aa74d582bd9479c59e16f970fe13bf3
schema:
type: string
contentFields:
name: X-Content-Fields
in: header
description: |
A comma-separated list of field names from the Update customer endpoint's response that you want to receive.
If omitted, all the fields will be sent to the callback destination URI.
example: customerProfile
schema:
type: string
enum:
- customerSession
- customerProfile
- coupons
- triggeredCampaigns
- referral
- loyalty
- event
- awardedGiveaways
- ruleFailureReasons
- previousReturns
- createdAttributes
- createdCoupons
- createdReferrals
- effects
correlationID:
name: X-Correlation-ID
in: header
description: |
An arbitrary ID assigned to the callback request. You can use it to track the callbacks you receive from Talon.One.
If omitted, the callback request does not include `X-Correlation-ID`.
schema:
type: string
example: abc123
identifier:
name: identifier
in: query
description: |
The identifier of the request. Providing a new value creates a new coupon. Providing an existing value retrieves the existing coupon of that ID and does not create a new coupon.
schema:
type: string
example: 3495-4323
skipNonExistingAttributes:
name: skipNonExistingAttributes
in: query
schema:
type: boolean
default: false
example: true
description: |
Indicates whether to skip non-existing attributes.
If `true`, the non-existing attributes are skipped and a 400 error is not returned.
If `false`, a 400 error is returned in case of non-existing attributes.
schemas:
CouponReservationRequest:
type: object
required:
- deploymentUrl
- couponValue
- integrationId
properties:
deploymentUrl:
type: string
description: The base url of your deployment.
example: mycompany.europe-west1.talon.one
couponValue:
type: string
description: The coupon code.
integrationId:
type: string
description: The integration ID of the customer profile.
CouponReservationResponse:
type: object
required:
- id
- campaignId
- value
- usageLimit
- usageCounter
- created
properties:
id:
type: integer
format: int64
example: 20190408
description: The internal ID of this entity.
campaignId:
type: integer
format: int64
example: 30
description: The ID of the campaign that owns this entity.
value:
type: string
example: SUMMER-####-2022
description: The coupon code.
usageLimit:
type: integer
format: int64
example: 1
description: The number of times the coupon code can be redeemed. `0` means unlimited redemptions but any campaign usage limits will still apply.
usageCounter:
type: integer
description: The number of times the coupon has been successfully redeemed.
example: 1
created:
type: string
format: date-time
description: The time this entity was created.
example: '2022-03-02T16:46:17.758585Z'
attributes:
type: object
description: Custom attributes associated with this coupon.
additionalProperties: true
batchId:
type: string
description: The ID of the batch the coupon belongs to.
example: 32535-43255
isReservationMandatory:
type: boolean
example: false
description: Indicates whether the code can be redeemed only if it has been reserved first.
implicitlyReserved:
description: Indicates whether the coupon is implicitly reserved for all customers.
type: boolean
example: false
reservation:
type: boolean
example: false
description: |
Defines the reservation type:
- `true`: The coupon can be reserved for multiple customers.
- `false`: The coupon can be reserved only for one customer. It is a personal code.
ReferralRequest:
type: object
required:
- deploymentUrl
- campaignId
- advocateProfileIntegrationId
properties:
deploymentUrl:
type: string
description: The base url of your deployment.
example: mycompany.europe-west1.talon.one
campaignId:
type: integer
format: int64
minimum: 1
example: 3
description: The ID of the campaign in Talon.One. It is displayed in your Talon.One deployment URL.
advocateProfileIntegrationId:
type: string
minLength: 1
example: URN-GV8294NV
description: The customer integration ID of the advocate.
friendProfileIntegrationId:
type: string
minLength: 1
example: PKBR-G06449OELK
description: The customer integration ID of the person being referred.
startDate:
type: string
format: date-time
example: '2021-09-30T15:35:02.371569+02:00'
description: The date when the code becomes usable.
expiryDate:
type: string
format: date-time
example: '2021-10-03T15:35:02.371569+02:00'
description: The date when the code becomes unsable.
usageLimit:
type: integer
format: int64
minimum: 0
default: 0
example: 1
description: Set the usage limit of the referral to unlimited.
attributes:
type: object
description: |
An object containing the value of each attributes to set.
New attributes are created automatically. For more information, see [Attributes](https://docs.talon.one/docs/dev/concepts/attributes).
ReferralResponse:
type: object
properties:
id:
type: integer
format: int64
example: 32
created:
type: string
format: date-time
example: '2020-02-08T14:15:20Z'
startDate:
type: string
format: date-time
example: '2020-02-12T11:00:00Z'
expiryDate:
type: string
format: date-time
example: '2021-02-12T11:00:00Z'
usageLimit:
type: integer
format: int64
example: 1
campaignId:
type: integer
format: int64
example: 23
advocateProfileIntegrationId:
type: string
minLength: 1
example: URN-GV8294NV
friendProfileIntegrationId:
type: string
minLength: 1
example: PKBR-G06449OELK
attributes:
type: object
example:
phone: 555-555-555
language: english
code:
type: string
example: XMAS-2020
usageCounter:
type: integer
format: int64
example: 0
dryRun:
type: boolean
example: true
BrazeCouponRequest:
type: object
required:
- deploymentUrl
- applicationId
- campaignId
- identifier
properties:
deploymentUrl:
type: string
description: The base URL of your Talon.One deployment.
example: mycompany.europe-west1.talon.one
applicationId:
type: integer
format: int64
minimum: 1
description: The ID of the Application in Talon.One. It is displayed in your Talon.One deployment URL.
example: 2
campaignId:
type: integer
format: int64
minimum: 1
description: The ID of the campaign in Talon.One. It is displayed in your Talon.One deployment URL.
example: 34
identifier:
type: string
minLength: 1
description: |
The identifier of the request. Providing a new value creates a new coupon. Providing an existing value retrieves the existing coupon of that ID and does not create a new coupon.
In general, you should set it to a variable controlled by Braze. Usual values include:
- `message_api_id`
- `variant_api_id`
- `dispatch_id`
See [Supported personalization tags](https://www.braze.com/docs/user_guide/personalization_and_dynamic_content/liquid/supported_personalization_tags/)
and [dispatch ID](https://www.braze.com/docs/help/help_articles/data/dispatch_id/) behavior.
example: 3495-4323
usageLimit:
type: integer
format: int64
default: 1
description: The usage limit of the coupon.
example: 1
discountLimit:
type: number
minimum: 0
maximum: 999999
example: 30
description: |
The discount amount the coupon is worth. Can be blank if, for example, the coupon provides a 10% discount, or something other than a fixed value of discounts.
reservationLimit:
type: integer
format: int64
minimum: 0
maximum: 999999
example: 45
description: |
The number of reservations that can be made with this coupon code.
isReservationMandatory:
type: boolean
example: true
description: |
Indicates whether the code can be redeemed only if it has been reserved first.
limits:
type: array
description: |
Limits configuration for a coupon. These limits will override the limits
set from the campaign.
**Note:** Only usable when creating a single coupon which is not tied to a specific recipient.
Only per-profile limits are allowed to be configured.
items:
type: object
required:
- action
- limit
- entities
properties:
action:
type: string
description: |
The limitable action to which this limit applies. Must be set to `redeemCoupon`.
example: redeemCoupon
limit:
type: number
minimum: 0
example: 1000
description: The number of times a coupon can be redeemed per customer.
entities:
type: array
description: The entities that this limit applies to. Must be set to `["Coupon", "Profile"]`.
example:
- Coupon
- Profile
items:
type: string
enum:
- Coupon
- Profile
integrationId:
type: string
description: The integration ID of the customer profile. When specified, only that customer will be able to use the coupon.
example: URNGV8294NV
startDate:
type: string
format: date-time
description: The start date of the coupon.
example: '2021-09-30T15:35:02.371569+02:00'
expiryDate:
type: string
format: date-time
description: The expiry date of the coupon.
example: '2022-02-28T11:00:00.569+02:00'
validCharacters:
type: array
items:
type: string
description: The list of allowed characters to be used when generating the code.
example:
- S
- U
- M
- E
- R
couponPattern:
type: string
description: The coupon pattern to use. Use `#` to represent a random character picked from `validCharacters`.
example: SUMMER-####-2022
attributes:
type: object
description: Arbitrary properties associated with item.
example:
language: english
CouponResponse:
type: object
required:
- ID
- ApplicationID
- CampaignID
- Value
- UsageLimit
properties:
ID:
type: integer
format: int64
example: 20190408
ApplicationID:
type: integer
format: int64
example: 2
CampaignID:
type: integer
format: int64
example: 30
Value:
type: string
example: SUMMER-####-2022
DiscountLimit:
type: integer
format: int64
description: The discount amount the coupon is worth. Can be blank if, for example, the coupon provides a 10% discount, or something other than a fixed value of discounts.
example: 100
ReservationLimit:
type: integer
format: int64
minimum: 0
maximum: 999999
example: 45
description: The number of reservations that can be made with this coupon code.
IsReservationMandatory:
type: boolean
example: true
description: |
Indicates whether the code can be redeemed only if it has been reserved first.
StartDate:
type: string
format: date-time
example: '2021-09-30T15:35:02.371569+02:00'
ExpiryDate:
type: string
format: date-time
example: '2022-02-28T11:00:00.569+02:00'
RecipientIntegrationID:
type: string
example: URN-GV8294NV
UsageLimit:
type: integer
format: int64
example: 1
Attributes:
type: object
example:
language: english
BrazeCouponResponse:
type: object
properties:
ID:
type: integer
format: int64
example: 20190408
ApplicationID:
type: integer
format: int64
example: 2
CampaignID:
type: integer
format: int64
example: 30
Value:
type: string
example: SUMMER-####-2022
DiscountLimit:
type: integer
format: int64
description: The discount amount the coupon is worth. Can be blank if, for example, the coupon provides a 10% discount, or something other than a fixed value of discounts.
example: 100
ReservationLimit:
type: integer
format: int64
minimum: 0
maximum: 999999
example: 45
description: The number of reservations that can be made with this coupon code.
IsReservationMandatory:
type: boolean
example: true
description: |
Indicates whether the code can be redeemed only if it has been reserved first.
Limits:
type: array
items:
type: object
properties:
action:
type: string
description: |
The limitable action to which this limit applies. For example:
- `redeemCoupon`
example: redeemCoupon
limit:
type: number
minimum: 0
example: 1000
description: The value to set for the limit.
entities:
type: array
description: The entity that this limit applies to.
example:
- Coupon, Profile
items:
type: string
enum:
- Coupon
- Profile
StartDate:
type: string
format: date-time
example: '2021-09-30T15:35:02.371569+02:00'
ExpiryDate:
type: string
format: date-time
example: '2022-02-28T11:00:00.569+02:00'
RecipientIntegrationID:
type: string
example: URN-GV8294NV
UsageLimit:
type: integer
format: int64
example: 1
Attributes:
type: object
example:
language: english
CustomerProfileRequest:
type: object
properties:
attributes:
$ref: '#/components/schemas/attributeValuePairs'
runRuleEngine:
type: boolean
default: false
description: |
Indicates whether to run the Rule Engine.
If `true`, the rules are run and their effects are applied, and audience changes are applied.
If `false`:
- The rules are not executed.
- The response time improves.
- Audience changes are not applied.
example: false
audiencesChanges:
$ref: '#/components/schemas/audienceChange'
CDPCustomerProfileRequest:
type: object
properties:
attributes:
type: object
description: |
Property to set the attributes of your choice to the values of your choice.
**Note:** If set to `null`, the attribute is deleted from the customer profile.
additionalProperties: true
example:
Language: english
ShippingCountry: DE
ProductClicked: true
runRuleEngine:
type: boolean
default: false
description: |
Indicates whether to run the Rule Engine.
If `true`, the rules are run and their effects are applied.
If `false`:
- The rules are not executed.
- The response time improves.
**Note:** If the `audiencesChanges` request parameter is not empty, this value is automatically set to `true`.
example: false
audiencesChanges:
$ref: '#/components/schemas/audienceChange'
CustomerProfileRequestV2:
type: object
properties:
attributes:
$ref: '#/components/schemas/attributeValuePairs'
runRuleEngine:
type: boolean
default: false
description: |
Indicates whether to run the Rule Engine.
If `true`, the rules are run and their effects are applied, and audience changes are applied.
If `false`:
- The rules are not executed.
- The response time improves.
- Audience changes are not applied.
example: false
audiencesChanges:
$ref: '#/components/schemas/audienceChangeV2'
CustomerProfilesAudiencesRequest:
type: object
properties:
data:
type: array
description: |
Indicates audience changes for a selected profile.
**Note:** The total number of `adds` and `deletes` items should be equal to or less than `1000`.
items:
$ref: '#/components/schemas/multipleAudienceChanges'
CustomerProfilesIntegrationAudiencesRequest:
type: object
properties:
data:
type: array
description: |
Indicates audience changes for a selected profile.
**Note:** The total number of `adds` and `deletes` items should be equal to or less than `1000`.
items:
$ref: '#/components/schemas/multipleIntegrationAudienceChanges'
SingleCustomerProfileIntegrationAudiencesRequest:
type: object
properties:
data:
$ref: '#/components/schemas/integrationAudienceChange'
description: |
Indicates integration ids of the audience changes for a selected profile.
**Note:** The total number of `adds` and `deletes` items should be equal to or less than `1000`.
CustomerProfileResponse:
type: object
description: |
Contains all entities that might interest Talon.One integrations.
properties:
customerProfile:
$ref: '#/components/schemas/customerProfile'
createdAttributes:
$ref: '#/components/schemas/multipleAttributes'
CustomerProfileResponseV2:
allOf:
- $ref: '#/components/schemas/CustomerProfileResponse'
- type: object
properties:
audiences:
type: array
description: The flat list of audiences in Talon.One used in the request after they were processed.
items:
$ref: '#/components/schemas/MultipleAudiencesItem'
MultipleAudiencesItem:
allOf:
- $ref: '#/components/schemas/entity'
- $ref: '#/components/schemas/newAudience'
- type: object
required:
- name
- integrationId
- status
description: |
Audience item that contains the status of the action applied and its related properties.
properties:
status:
type: string
description: |
Indicates whether the audience is new, updated or unmodified by the request.
enum:
- unmodified
- updated
- new
example: new
CreateAndUpdateAudienceRequest:
type: object
required:
- audienceId
- audienceName
properties:
audienceId:
$ref: '#/components/schemas/audienceId'
audienceName:
$ref: '#/components/schemas/audienceName'
CreateAndUpdateResponse:
allOf:
- $ref: '#/components/schemas/entity'
- $ref: '#/components/schemas/accountEntity'
- $ref: '#/components/schemas/newAudience'
TrackEventRequest:
type: object
required:
- eventType
- type
- customerProfileId
properties:
eventType:
type: string
format: string
description: The event type, as defined in Talon.One when you created the custom attribute representing this event.
example: myBrazeEvent
type:
type: string
format: string
enum:
- string
- time
- number
- boolean
- location
- (list string)
- (list number)
- (list time)
- (list location)
description: The data type of the event, as defined in Talon.One when you created the custom attribute representing this event.
example: string
eventAttributes:
$ref: '#/components/schemas/attributeValuePairs'
customerProfileId:
$ref: '#/components/schemas/customerProfileID'
BrazeTrackEventRequest:
allOf:
- $ref: '#/components/schemas/TrackEventRequest'
- type: object
required:
- identifier
properties:
identifier:
$ref: '#/components/schemas/identifier'
SegmentTrackEventV2Request:
type: object
required:
- eventType
properties:
eventType:
type: string
format: string
description: The event type, as defined in Talon.One when you created the custom attribute representing this event.
example: mySegmentEvent
eventAttributes:
$ref: '#/components/schemas/attributeValuePairs'
customerProfileId:
$ref: '#/components/schemas/customerProfileID'
SegmentTrackEventRequest:
allOf:
- $ref: '#/components/schemas/TrackEventRequest'
- type: object
properties:
attributesInfo:
$ref: '#/components/schemas/attributesInfo'
SegmentCustomerProfileRequest:
allOf:
- $ref: '#/components/schemas/CustomerProfileRequest'
- type: object
properties:
attributesInfo:
$ref: '#/components/schemas/attributesInfo'
SegmentCustomerProfileRequestV2:
allOf:
- $ref: '#/components/schemas/CustomerProfileRequestV2'
- type: object
properties:
attributesInfo:
$ref: '#/components/schemas/attributesInfo'
SegmentCustomerProfileV2Request:
type: object
properties:
attributes:
$ref: '#/components/schemas/attributeValuePairs'
runRuleEngine:
type: boolean
default: false
description: |
Indicates whether to run the Rule Engine.
If `true`, the rules are run and their effects are applied, and audience changes are applied.
If `false`:
- The rules are not executed.
- The response time improves.
- Audience changes are not applied.
example: false
audiencesChanges:
$ref: '#/components/schemas/audienceChange'
CustomerProfileIntegrationResponseV2:
type: object
description: |
This is the response type returned by the updateCustomerProfileV2 endpoint.
required:
- effects
- createdCoupons
- createdReferrals
properties:
customerProfile:
$ref: '#/components/schemas/customerProfile'
event:
$ref: '#/components/schemas/event'
loyalty:
$ref: '#/components/schemas/loyalty'
triggeredCampaigns:
type: array
items:
$ref: '#/components/schemas/campaign'
ruleFailureReasons:
type: array
items:
$ref: '#/components/schemas/ruleFailureReason'
awardedGiveaways:
type: array
items:
$ref: '#/components/schemas/giveaway'
effects:
type: array
description: The effects generated by the rules in your running campaigns. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
items:
$ref: '#/components/schemas/effect'
createdCoupons:
type: array
items:
$ref: '#/components/schemas/coupon'
createdReferrals:
type: array
items:
$ref: '#/components/schemas/referral'
LoyaltyResponse:
type: object
properties:
id:
type: integer
format: int64
example: 302
title:
type: string
example: My loyalty program
name:
type: string
example: myloyaltyprogram
ledger:
allOf:
- $ref: '#/components/schemas/ledgerInfo'
subLedgers:
type: object
additionalProperties:
$ref: '#/components/schemas/ledgerInfo'
UpdateCustomerSessionRequest:
type: object
properties:
customerSession:
$ref: '#/components/schemas/newCustomerSessionV2'
sessionAttributesInfo:
$ref: '#/components/schemas/attributesInfo'
cartItemAttributesInfo:
$ref: '#/components/schemas/attributesInfo'
IntegrationStateV2:
type: object
description: |
Contains all entities that might interest Talon.One integrations. This is the response type returned by the v2 PUT customer_session endpoint.
required:
- effects
- createdCoupons
- createdReferrals
properties:
customerSession:
$ref: '#/components/schemas/customerSessionV2'
customerProfile:
$ref: '#/components/schemas/customerProfile'
event:
$ref: '#/components/schemas/event'
loyalty:
$ref: '#/components/schemas/loyalty'
referral:
$ref: '#/components/schemas/inventoryReferral'
coupons:
type: array
items:
$ref: '#/components/schemas/coupon'
triggeredCampaigns:
type: array
items:
$ref: '#/components/schemas/campaign'
effects:
type: array
items:
$ref: '#/components/schemas/effect'
ruleFailureReasons:
type: array
items:
$ref: '#/components/schemas/ruleFailureReason'
createdCoupons:
type: array
items:
$ref: '#/components/schemas/coupon'
createdReferrals:
type: array
items:
$ref: '#/components/schemas/referral'
awardedGiveaways:
type: array
items:
$ref: '#/components/schemas/giveaway'
return:
$ref: '#/components/schemas/return'
previousReturns:
type: array
items:
$ref: '#/components/schemas/return'
ModuleRegistrationRequest:
allOf:
- type: object
required:
- type
properties:
type:
type: string
description: The type of the mParticle request. Must be set to `module_registration_request`.
example: module_registration_request
- $ref: '#/components/schemas/mparticleBaseFields'
- $ref: '#/components/schemas/mparticleAccount'
ModuleRegistrationResponse:
allOf:
- $ref: '#/components/schemas/mparticleResponseType'
- $ref: '#/components/schemas/mparticleBaseFields'
- type: object
properties:
name:
type: string
description: The name of the Talon.One integration.
example: Talon.One
description:
type: string
description: The description of the Talon.One integration.
example: Talon.One is the world's most flexible Promotion Engine. Create, manage and track coupon codes, discount campaigns, loyalty programs and referrals in one system.
version:
type: string
description: The version of the Talon.One integration.
example: 0.0.1
permissions:
$ref: '#/components/schemas/mparticlePermissions'
audience_processing_registration:
$ref: '#/components/schemas/mparticleAudienceProcessingRegistration'
event_processing_registration:
$ref: '#/components/schemas/mparticleEventProcessingRegistration'
AudienceMembershipChangeRequest:
allOf:
- type: object
required:
- type
properties:
type:
type: string
description: The type of the mParticle request. Must be set to `audience_membership_change_request`.
example: audience_membership_change_request
- $ref: '#/components/schemas/mparticleBaseFields'
- $ref: '#/components/schemas/mparticleAccount'
- type: object
properties:
user_profiles:
type: array
description: The customer profiles to add to or remove from an audience.
items:
$ref: '#/components/schemas/mparticleUserProfiles'
AudienceMembershipChangeResponse:
allOf:
- $ref: '#/components/schemas/mparticleResponseType'
- $ref: '#/components/schemas/mparticleBaseFields'
AudienceSubscriptionRequest:
allOf:
- type: object
required:
- type
properties:
type:
type: string
description: The type of the mParticle request. Must be set to `audience_subscription_request`.
example: audience_subscription_request
- $ref: '#/components/schemas/mparticleBaseFields'
- $ref: '#/components/schemas/mparticleAccount'
- type: object
required:
- audience_id
- audience_name
- action
properties:
audience_id:
type: integer
description: The ID of the audience to add, update, or delete.
example: 29
audience_name:
type: string
description: The name of the audience.
example: Travel audience
action:
description: The action to perform on the audience.
example: add
enum:
- add
- update
- remove
audience_subscription_settings:
type: object
description: Additional settings for the audience.
additionalProperties: true
user_attributes:
description: Additional user attributes to add, update, or delete.
type: array
items:
$ref: '#/components/schemas/mparticleUserAttribute'
AudienceSubscriptionResponse:
allOf:
- $ref: '#/components/schemas/mparticleResponseType'
- $ref: '#/components/schemas/mparticleBaseFields'
- type: object
properties:
audience_subscription_settings:
type: object
additionalProperties: true
EventProcessingRequest:
allOf:
- type: object
required:
- type
properties:
type:
type: string
description: The type of the mParticle request. Must be set to `event_processing_request`.
example: event_processing_request
- $ref: '#/components/schemas/mparticleBaseFields'
- $ref: '#/components/schemas/mparticleAccount'
- type: object
required:
- mpid
- events
properties:
mpid:
type: string
description: The mParticle ID.
example: 6423PSJVY7492
user_identities:
type: array
description: The customer identity data associated with this event. Required if `account.account_settings.userIdField` is set to `email` or `customerId`.
items:
$ref: '#/components/schemas/mparticleUserIdentity'
events:
type: array
description: The event data.
items:
$ref: '#/components/schemas/mparticleEvent'
EventProcessingResponse:
allOf:
- $ref: '#/components/schemas/mparticleResponseType'
- $ref: '#/components/schemas/mparticleBaseFields'
EmarsysCouponRequest:
type: object
required:
- fields
- limit
- parameters
properties:
parameters:
type: array
items:
properties:
campaignId:
type: string
description: The ID of the campaign in Talon.One. It is displayed in your Talon.One deployment URL.
example: '34'
integrationId:
type: string
description: The integration ID of the customer profile.
example: URNGV8294NV
fields:
type: array
description: |
Any additional data we want in the response.
**Note:** For the supported `fields`, see the [List customer data](https://docs.talon.one/integration-api#tag/Customer-profiles/operation/getCustomerInventory) response (any nested arrays and objects are discarded from the response).
In addition to this, custom attributes are supported.
example:
- id
- created
items:
type: string
limit:
type: number
minimum: 0
example: 1000
description: The value to set for the limit.
EmarsysCouponResponse:
properties:
content:
type: array
description: |
The relevant coupon-related content, including the properties passed in the `fields` array of the request.
items:
type: object
required:
- campaignId
- integrationId
properties:
campaignId:
type: string
description: The ID of the campaign in Talon.One. It is displayed in your Talon.One deployment URL.
example: '34'
integrationId:
type: string
description: The integration ID of the customer profile.
example: URNGV8294NV
EmarsysLoyaltyBalanceRequest:
type: object
required:
- fields
- limit
- parameters
properties:
parameters:
type: array
items:
properties:
loyaltyProgramId:
type: string
description: The ID of the loyalty program in Talon.One.
example: '34'
integrationId:
type: string
description: The integration ID of the customer profile.
example: URNGV8294NV
subledgerId:
type: string
description: The ID of the subledger from which to retrieve the loyalty balance. If not provided, the loyalty balance is retrieved from the main ledger.
example: subledger-123
required:
- loyaltyProgramId
- integrationId
fields:
type: array
description: |
Additional fields to include in the response.
Valid fields are `activeBalance`, `pendingBalance`, `expiredBalance`, and `spentBalance`.
example:
- activeBalance
- pendingBalance
items:
type: string
EmarsysLoyaltyBalanceResponse:
properties:
content:
type: array
description: |
The requested loyalty balance, including the properties specified in the `fields` parameter.
items:
type: object
required:
- loyaltyProgramId
- integrationId
properties:
loyaltyProgramId:
type: string
description: The ID of the loyalty program in Talon.One.
example: '34'
integrationId:
type: string
description: The integration ID of the customer profile.
example: URNGV8294NV
subledgerId:
type: string
description: The ID of the subledger from which the loyalty balance was retrieved. Returned only if a subledger ID was provided in the request.
example: subledger-123
activeBalance:
type: number
description: Total amount of points awarded to this customer and available to spend.
example: 100
pendingBalance:
type: number
description: Total amount of points awarded to this customer but not available until their start date.
example: 50
expiredBalance:
type: number
description: Total amount of points awarded but never redeemed. They cannot be used anymore.
example: 0
spentBalance:
type: number
description: Total amount of points already spent by this customer.
example: 50
EmarsysUpdateAudiencesResponse:
type: object
properties:
content:
type: array
items:
type: object
properties:
customerProfileId:
type: string
example: profile-1
audienceId:
type: string
example: '1'
actionType:
type: string
example: add
AddLoyaltyPointsRequest:
type: object
required:
- loyaltyProgramId
- profileIntegrationId
- points
properties:
profileIntegrationId:
description: The integration ID of the customer profile in Talon.One.
type: string
example: URN-GV8294NV
loyaltyProgramId:
description: The ID of the profile-based loyalty program in Talon.One.
type: integer
example: 25
points:
type: number
minimum: 0
exclusiveMinimum: true
maximum: 999999999999.99
exclusiveMaximum: false
description: Amount of loyalty points.
example: 300
name:
type: string
description: Name / reason for the point addition.
example: Compensation
validityDuration:
type: string
description: |
The time format is either:
- `immediate` or,
- an **integer** followed by one letter indicating the time unit.
Examples: `immediate`, `30s`, `40m`, `1h`, `5D`, `7W`, `10M`, `15Y`.
Available units:
- `s`: seconds
- `m`: minutes
- `h`: hours
- `D`: days
- `W`: weeks
- `M`: months
- `Y`: years
You can round certain units up or down:
- `_D` for rounding down days only. Signifies the start of the day.
- `_U` for rounding up days, weeks, months and years. Signifies the end of the day, week, month or year.
If passed, `validUntil` should be omitted.
example: 5D
validUntil:
type: string
format: date-time
description: |
Date and time when points should expire. The value should be provided in RFC 3339 format.
If passed, `validityDuration` should be omitted.
example: '2021-07-20T22:00:00Z'
pendingDuration:
type: string
description: |
The amount of time before the points are considered valid.
The time format is either:
- `immediate` or,
- an **integer** followed by one letter indicating the time unit.
Examples: `immediate`, `30s`, `40m`, `1h`, `5D`, `7W`, `10M`, `15Y`.
Available units:
- `s`: seconds
- `m`: minutes
- `h`: hours
- `D`: days
- `W`: weeks
- `M`: months
- `Y`: years
You can round certain units up or down:
- `_D` for rounding down days only. Signifies the start of the day.
- `_U` for rounding up days, weeks, months and years. Signifies the end of the day, week, month or year.
example: 12h
pendingUntil:
type: string
format: date-time
description: |
Date and time after the points are considered valid. The value should be provided in RFC 3339 format.
If passed, `pendingDuration` should be omitted.
example: '2021-07-20T22:00:00Z'
subledgerId:
type: string
description: ID of the subledger the points are added to. If there is no existing subledger with this ID, the subledger is created automatically.
example: sub-123
applicationId:
type: integer
description: ID of the Application that is connected to the loyalty program. It is displayed in your Talon.One deployment URL.
example: 322
id:
type: integer
title: ID
description: Unique ID for this entity.
format: int64
example: 6
minimum: 1
audienceId:
type: string
format: string
minLength: 1
maxLength: 1000
description: The integration ID of this audience. If the audience comes from a third-party platform, set this property to the ID given by the third-party platform.
example: 382370BKDB946
audienceName:
type: string
format: string
maxLength: 1000
minLength: 1
description: The human-friendly display name for this audience.
example: Travel audience
newAudience:
type: object
required:
- name
properties:
name:
$ref: '#/components/schemas/audienceName'
integration:
type: string
description: The third-party platform that this audience was created in.
example: My platform name
integrationId:
$ref: '#/components/schemas/audienceId'
event:
allOf:
- $ref: '#/components/schemas/entity'
- $ref: '#/components/schemas/applicationEntity'
- $ref: '#/components/schemas/integrationEvent'
- type: object
required:
- effects
- ledgerEntries
properties:
sessionId:
type: string
title: Session ID of Event
description: The ID of the session that this event occurred in.
example: 175KJPS947296
effects:
type: array
description: |
An array of "effects" that must be applied in response to this event.
See the list of [effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
items:
type: array
example:
- 4208
- 20095
- 0
- - showNotification
- Info
- My title
- My content
ledgerEntries:
type: array
description: Ledger entries for the event.
items:
$ref: '#/components/schemas/ledgerEntry'
meta:
$ref: '#/components/schemas/meta'
meta:
type: object
properties:
campaigns:
description: Maps each evaluated campaign ID to a key-value list of that campaigns attributes. Campaigns without attributes will be omitted.
type: object
additionalProperties: true
coupons:
description: Maps the coupon value to a key-value list of that coupons attributes.
type: object
additionalProperties: true
couponRejectionReason:
$ref: '#/components/schemas/couponRejectionReason'
referralRejectionReason:
$ref: '#/components/schemas/referralRejectionReason'
warnings:
description: Contains warnings about possible misuse.
type: object
additionalProperties: true
couponRejectionReason:
description: Holds a reference to the campaign, the coupon and the reason for which that coupon was rejected. Should only be present when there is a 'rejectCoupon' effect.
type: object
required:
- campaignId
- couponId
- reason
properties:
campaignId:
type: integer
example: 244
couponId:
type: integer
example: 4928
reason:
type: string
enum:
- CouponNotFound
- CouponPartOfNotRunningCampaign
- CouponLimitReached
- CampaignLimitReached
- ProfileLimitReached
- CouponRecipientDoesNotMatch
- CouponExpired
- CouponStartDateInFuture
- CouponRejectedByCondition
- EffectCouldNotBeApplied
example: CouponNotFound
referralRejectionReason:
description: Holds a reference to the campaign, the referral and the reason for which that referral was rejected. Should only be present when there is a 'rejectReferral' effect.
type: object
required:
- campaignId
- referralId
- reason
properties:
campaignId:
type: integer
example: 20
referralId:
type: integer
example: 4
reason:
type: string
example: ReferralNotFound
enum:
- ReferralNotFound
- ReferralRecipientIdSameAsAdvocate
- ReferralPartOfNotRunningCampaign
- ReferralLimitReached
- CampaignLimitReached
- ProfileLimitReached
- ReferralRecipientDoesNotMatch
- ReferralExpired
- ReferralStartDateInFuture
- ReferralRejectedByCondition
- EffectCouldNotBeApplied
ledgerEntry:
allOf:
- $ref: '#/components/schemas/entity'
- $ref: '#/components/schemas/integrationProfileEntity'
- type: object
description: Entry in the point ledger
required:
- eventId
- accountId
- profileId
- loyaltyProgramId
- amount
- reason
- expiryDate
properties:
accountId:
type: integer
description: The ID of the Talon.One account that owns this profile.
example: 23
loyaltyProgramId:
type: integer
description: ID of the ledger
example: 323414846
eventId:
type: integer
description: ID of the related event
example: 3
amount:
type: integer
description: Amount of loyalty points
example: 100
reason:
type: string
description: reason for awarding/deducting points
example: customer appeasment
expiryDate:
type: string
format: date-time
description: Expiry date of the points
example: '2021-06-10T09:05:27.993483Z'
referenceId:
type: integer
description: The ID of the balancing ledgerEntry
example: 5
applicationEntity:
type: object
required:
- applicationId
properties:
applicationId:
type: integer
description: The ID of the application that owns this entity.
example: 322
integrationEvent:
allOf:
- $ref: '#/components/schemas/integrationProfileEntity'
- type: object
properties:
type:
type: string
title: Event Type
description: A string representing the event. Must not be a reserved event name.
minLength: 1
example: pageViews
attributes:
$ref: '#/components/schemas/attributeValuePairs'
required:
- type
- attributes
integrationProfileEntity:
type: object
properties:
profileId:
type: string
description: |
ID of the customers profile as used within this Talon.One account.
example: URN-GV8294NV
customerProfile:
allOf:
- $ref: '#/components/schemas/entity'
- $ref: '#/components/schemas/accountEntity'
- properties:
attributes:
$ref: '#/components/schemas/attributeValuePairs'
integrationId:
type: string
format: string
example: URNGV8294NV
maxLength: 1000
description: The integration ID for this entity sent to and used in the Talon.One system.
closedSessions:
type: integer
title: Closed sessions
description: The total amount of closed sessions by a customer. A closed session is a successful purchase.
example: 3
totalSales:
type: number
description: Sum of all purchases made by this customer
example: 299.99
title: Total Sales
audienceMemberships:
type: array
description: A list of audiences the customer belongs to
items:
type: object
required:
- id
- name
properties:
id:
$ref: '#/components/schemas/id'
name:
type: string
title: Audience Name
description: The Name of the audience belonging to this entity.
example: audience1
title: Audience memberships
lastActivity:
type: string
format: date-time
description: |
Timestamp of the most recent event received from this customer.
This field is updated on calls that trigger the rule-engine and that are
not [dry requests](https://docs.talon.one/docs/dev/integration-api/dry-requests#overlay).
For example, [reserving a coupon](https://docs.talon.one/integration-api#operation/createCouponReservation)
for a customer doesn't impact this field.
example: '2020-02-08T14:15:20Z'
addAudienceIds:
type: array
description: The IDs of the audiences for the customer to join.
example:
- 1
- 2
- 3
items:
$ref: '#/components/schemas/id'
deleteAudienceIds:
type: array
description: The IDs of the audiences for the customer to leave.
example:
- 4
- 5
- 6
items:
$ref: '#/components/schemas/id'
addIntegrationAudienceIds:
type: array
description: The external IDs of the audiences for the customer to join.
example:
- external_id_1
- external_id_2
- external_id_3
items:
type: string
minLength: 1
deleteIntegrationAudienceIds:
type: array
description: The external IDs of the audiences for the customer to leave.
example:
- external_id_4
- external_id_5
- external_id_6
items:
type: string
minLength: 1
addAudienceItems:
type: array
description: The audiences for the customer to join.
items:
$ref: '#/components/schemas/audienceItem'
deleteAudienceItems:
type: array
description: The audiences for the customer to leave.
items:
$ref: '#/components/schemas/audienceItem'
audienceItem:
type: object
required:
- name
properties:
integrationId:
type: string
minLength: 1
description: |
The integration ID of the audience. You can either use an existing audience ID, or assign a new one.
When you specify a new integration ID with this property, all A-Z, a-z and 0-9 characters are
preserved and all other characters are replaced by `_`. For example, `My Travel audience1` becomes `My_Travel_audience1`
example: My_Travel_audience1
name:
type: string
title: Audience Name
description: The name of the audience belonging to this entity.
example: Travel audience 18-25
attributeValuePairs:
type: object
description: |
Property to set the attributes of your choice to the values of your choice.
You can use [built-in attributes](https://docs.talon.one/docs/dev/concepts/attributes#built-in-attributes) or [custom ones](https://docs.talon.one/docs/dev/concepts/attributes#custom-attributes).
Custom attributes must be created in the Campaign Manager before you set them with this property.
additionalProperties: true
example:
Language: english
ShippingCountry: DE
ProductClicked: true
multipleAttributes:
type: array
items:
$ref: '#/components/schemas/attribute'
attribute:
allOf:
- $ref: '#/components/schemas/entity'
- $ref: '#/components/schemas/accountEntity'
- type: object
required:
- entity
- name
- title
- type
- description
- suggestions
- editable
properties:
entity:
type: string
description: The name of the entity that can have this attribute. When creating or updating the entities of a given type, you can include an `attributes` object with keys corresponding to the `name` of the custom attributes for that type.
enum:
- Account
- Application
- Campaign
- CustomerProfile
- CustomerSession
- CartItem
- Coupon
- Event
- Giveaway
- Referral
example: CustomerProfile
eventType:
type: string
example: event
name:
type: string
pattern: ^[A-Za-z]\w*$
description: The attribute name that will be used in API requests and Talang. E.g. if `name == "region"` then you would set the region attribute by including an `attributes.region` property in your request payload.
example: country
title:
type: string
pattern: ^[A-Za-z][A-Za-z0-9_.!~*'() -]*$
description: The human-readable name for the attribute that will be shown in the Campaign Manager. Like `name`, the combination of entity and title must also be unique.
example: Country
type:
type: string
enum:
- string
- time
- number
- boolean
- location
- (list string)
- (list number)
- (list time)
- (list location)
description: The data type of the attribute, a `time` attribute must be sent as a string that conforms to the [RFC3339](https://www.ietf.org/rfc/rfc3339.txt) timestamp format.
example: string
description:
type: string
description: A description of this attribute.
example: a description
suggestions:
type: array
description: A list of suggestions for the attribute.
maxItems: 50
example:
- suggestion1
- suggestion2
items:
type: string
minLength: 1
example: suggestion
hasAllowedList:
type: boolean
description: Whether or not this attribute has an allowed list of values associated with it.
default: false
example: false
restrictedBySuggestions:
type: boolean
description: |
Whether or not this attribute's value is restricted by suggestions (`suggestions` property)
or by an allowed list of value (`hasAllowedList` property).
default: false
example: false
editable:
type: boolean
description: Whether or not this attribute can be edited.
example: false
subscribedApplicationsIds:
type: array
description: A list of the IDs of the applications that are subscribed to this attribute
example:
- 10
- 20
- 100
items:
type: integer
eventTypeId:
type: integer
format: int64
example: 22
multipleAudienceChanges:
allOf:
- $ref: '#/components/schemas/audienceChange'
- type: object
properties:
customerProfileId:
$ref: '#/components/schemas/customerProfileID'
multipleIntegrationAudienceChanges:
allOf:
- $ref: '#/components/schemas/integrationAudienceChange'
- type: object
properties:
customerProfileId:
$ref: '#/components/schemas/customerProfileID'
customerProfileID:
type: string
format: string
example: URN-GV8294NV
maxLength: 1000
description: The integration ID of the customer profile. If the customer profile does not exist, it will be created.
audienceChange:
type: object
description: A list of audiences where the customer should be removed or added.
properties:
adds:
$ref: '#/components/schemas/addAudienceIds'
deletes:
$ref: '#/components/schemas/deleteAudienceIds'
integrationAudienceChange:
type: object
description: A list of external IDs of the audiences where the customer should be removed or added.
properties:
adds:
$ref: '#/components/schemas/addIntegrationAudienceIds'
deletes:
$ref: '#/components/schemas/deleteIntegrationAudienceIds'
audienceChangeV2:
type: object
properties:
adds:
$ref: '#/components/schemas/addAudienceItems'
deletes:
$ref: '#/components/schemas/deleteAudienceItems'
accountEntity:
type: object
required:
- accountId
properties:
accountId:
$ref: '#/components/schemas/id'
entity:
type: object
required:
- id
- created
properties:
id:
$ref: '#/components/schemas/id'
created:
type: string
format: date-time
description: The moment this entity was created.
example: '2020-06-10T09:05:27.993483Z'
ledgerInfo:
type: object
properties:
currentBalance:
type: number
example: 10.5
pendingBalance:
type: number
example: 5.1
expiredBalance:
type: number
example: 2
spentBalance:
type: number
example: 0
tentativeCurrentBalance:
type: number
example: 0
pointsToNextTier:
type: number
example: 10
currentTier:
type: object
properties:
id:
type: integer
format: int64
example: 112345
name:
type: string
example: silver-tier
mparticlePermissions:
type: object
description: The identities the integration requires access to.
properties:
allow_consent_state:
type: boolean
example: true
allow_access_mpid:
type: boolean
example: true
allow_user_attributes:
type: boolean
example: true
allow_audience_user_attributes:
type: boolean
example: true
user_identities:
type: array
items:
$ref: '#/components/schemas/mparticleUserIdentity'
mparticleAudienceProcessingRegistration:
type: object
description: The configuration required to process audiences.
properties:
account_settings:
type: array
items:
$ref: '#/components/schemas/mparticleAccountSettings'
audience_subscription_settings:
type: array
items:
$ref: '#/components/schemas/mparticleAudienceSubscriptionSettings'
mparticleAudienceSubscriptionSettings:
type: object
description: The audience-specific configuration.
properties:
type:
type: string
example: integer
id:
type: string
example: t1AudienceID
name:
type: string
example: Talon.One Audience ID
visible:
type: boolean
example: false
required:
type: boolean
example: false
mparticleAccountSettings:
type: object
description: The configuration to be set by the client.
properties:
type:
type: string
example: text
id:
type: string
example: deploymentURL
name:
type: string
example: Deployment URL
description:
type: string
example: The URL of your Talon.One deployment.
visible:
type: boolean
example: true
required:
type: boolean
example: true
confidential:
type: boolean
example: true
default_value:
type: string
example: ''
mparticleEventProcessingRegistration:
type: object
description: The configuration required to process events.
properties:
account_settings:
type: array
items:
$ref: '#/components/schemas/mparticleAccountSettings'
supported_event_types:
type: array
items:
type: string
example: custom_event
supported_runtime_environments:
type: array
items:
type: string
example: android
supported_system_notification_types:
type: array
items:
type: string
max_data_age_hours:
type: integer
example: -1
firehoseVersion:
type: string
description: The internal mParticle API version.
example: 2.4.0
timestampMS:
type: integer
description: The timestamp of the request (in milliseconds).
example: 1586980879793
mparticleId:
type: string
description: The ID of the request.
example: dd33f-dd-b3fb3-def0000
mparticleUserIdentity:
type: object
properties:
type:
type: string
description: The type of customer identity data.
enum:
- email
- customer
example: customer
encoding:
type: string
enum:
- raw
- md5
- sha1
- sha256
example: raw
description: The format used to encode the customer identity data.
value:
type: string
description: The customer identity data. Can be a customer ID or an email address.
example: RGV6358UYY
mparticleAudience:
type: object
required:
- action
- audience_id
- audience_name
properties:
audience_id:
type: integer
description: The ID of the audience.
example: 234
audience_name:
type: string
description: The name of the audience.
example: Travel audience
action:
$ref: '#/components/schemas/actionMembershipChange'
audience_subscription_settings:
type: object
description: Additional settings for the audience.
additionalProperties: true
user_attributes:
type: array
description: Additional user attributes to add, update, or delete.
items:
$ref: '#/components/schemas/mparticleUserAttribute'
actionMembershipChange:
type: string
description: The action to perform on the customer in the audience.
example: add
enum:
- add
- delete
- attribute_update
mparticleUserAttribute:
type: object
properties:
key:
type: string
description: The name of the user attribute.
example: country
value:
description: The value of the user attribute.
example: DE
action:
type: string
description: The action to perform on the user attribute (add/update or delete).
example: upsert
enum:
- upsert
- delete
mparticleAccount:
type: object
required:
- account
properties:
account:
type: object
description: The account settings for your Talon.One integration.
properties:
account_id:
type: integer
description: The mParticle account ID.
example: 1234567
account_settings:
type: object
required:
- apiKey
- deploymentURL
- userIdField
properties:
apiKey:
type: string
description: The mParticle API key you created in Talon.One.
example: someapikey
deploymentURL:
type: string
description: The base URL of your Talon.One deployment.
example: mycompany.europe-west1.talon.one
userIdField:
type: string
description: Indicates how to identify customer profiles. If set to `email` or `customerId`, you must provide customer data in `user_identities`.
example: email
enum:
- email
- customerId
- mpid
runRuleEngine:
type: boolean
description: Indicates whether to run the Rule Engine.
example: false
mparticleEvent:
type: object
required:
- name
- type
properties:
name:
type: string
description: The name of the event.
example: click_event
type:
type: string
description: The type of the event. Must be set to `custom_event`.
enum:
- custom_event
example: custom_event
session_id:
type: integer
description: The session ID of the event.
example: 109
id:
type: string
description: The event ID.
example: 342PV86540CR
source_id:
type: string
description: The event source ID.
example: B5720CRPPN7
attributes:
type: object
description: Additional attributes to submit to Talon.One.
additionalProperties: true
mparticleBaseFields:
type: object
properties:
id:
$ref: '#/components/schemas/mparticleId'
timestamp_ms:
$ref: '#/components/schemas/timestampMS'
firehose_version:
$ref: '#/components/schemas/firehoseVersion'
mparticleResponseType:
type: object
properties:
type:
type: string
enum:
- module_registration_response
- audience_membership_change_response
- audience_subscription_response
- event_processing_response
description: The type of the mParticle response.
example: module_registration_response
mparticleUserProfiles:
type: object
required:
- mpid
properties:
mpid:
type: string
description: The mParticle ID.
example: c314b207-f3ae-4d21-9ae7-5983af40876a
audiences:
type: array
description: The audiences to modify.
items:
$ref: '#/components/schemas/mparticleAudience'
user_identities:
type: array
description: The customers to add to or remove from an audience.
items:
$ref: '#/components/schemas/mparticleUserIdentity'
identifier:
type: string
minLength: 1
description: |
The identifier of the request. Providing a new value sends a new event to Talon.One. Providing an existing value retrieves the existing event of that id.
In general, you should set it to a `dispatch_id` variable controlled by Braze.
See [dispatch ID](https://www.braze.com/docs/help/help_articles/data/dispatch_id/) behavior.
example: NNjETb6XxDV7hQhLMA
attributeInfo:
type: object
properties:
name:
type: string
description: Attribute name
example: ProductClicked
type:
type: string
enum:
- string
- time
- number
- boolean
- location
description: The data type of the attribute. When using `time`, send the attribute value as a string conforming to the [RFC3339](https://www.ietf.org/rfc/rfc3339.txt) timestamp format.
example: boolean
attributesInfo:
description: |
Allows you to set the type of the attribute to create instead of relying on auto-type detection.
For example, if you have a `hasClickedProduct` attribute set to `false` (boolean) in the `attributes` property,
it will be created as `boolean` automatically. But to force it to be of type `string`,
use the `attributesInfo` field to declare it at as a `string`.
**Note:** List types cannot be converted. A `listOfSomething` attribute set to `(list string)` type,)
must not be declared as `string` in `attributesInfo` field.
type: array
items:
$ref: '#/components/schemas/attributeInfo'
newCustomerSessionV2:
allOf:
- $ref: '#/components/schemas/integrationProfileEntity'
- type: object
properties:
couponCodes:
type: array
items:
type: string
maxLength: 100
description: |
Any coupon codes entered.
**Important**: If you [create a coupon budget](https://docs.talon.one/docs/product/campaigns/settings/managing-campaign-budgets#budget-types)
for your campaign, ensure the session contains a coupon code by the time you close it.
title: Coupons entered in session
example:
- XMAS-20-2021
referralCode:
type: string
description: |
Any referral code entered.
**Important**: If you [create a referral budget](https://docs.talon.one/docs/product/campaigns/settings/managing-campaign-budgets#budget-types)
for your campaign, ensure the session contains a referral code by the time you close it.
title: Referral code entered in session
maxLength: 100
example: NT2K54D9
loyaltyCards:
type: array
maxItems: 1
items:
type: string
description: Any loyalty cards used.
example:
- loyalty-card-1
state:
type: string
enum:
- open
- closed
- partially_returned
- cancelled
default: open
example: open
description: |
Indicates the current state of the session. Sessions can be created as `open` or `closed`. The state transitions are:
1. `open` -> `closed`
2. `open` -> `cancelled`
3. Either:
- `closed` -> `cancelled` (**only** via [Update customer session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2)) or
- `closed` -> `partially_returned` (**only** via [Return cart items](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/returnCartItems))
4. `partially_returned` -> `cancelled`
For more information, see [Customer session states](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions).
title: Customer's session state
cartItems:
type: array
description: |
The items to add to this sessions.
- If cart item flattening is disabled: **Do not exceed 1000 items** (regardless of their `quantity`) per request.
- If cart item flattening is enabled: **Do not exceed 1000 items** and ensure the sum of all cart item's `quantity` **does not exceed 10.000** per request.
title: Customer session's cart items
items:
$ref: '#/components/schemas/cartItem'
additionalCosts:
type: object
description: |
Use this property to set a value for the additional costs of this session, such as a shipping cost.
They must be created in the Campaign Manager
before you set them with this property. See [Managing additional costs](https://docs.talon.one/docs/product/account/dev-tools/managing-additional-costs).
additionalProperties:
$ref: '#/components/schemas/additionalCost'
example:
shipping:
price: 9
identifiers:
type: array
maxItems: 5
items:
type: string
description: |
Session custom identifiers that you can set limits on or use inside your rules.
For example, you can use IP addresses as identifiers to potentially identify devices
and limit discounts abuse in case of customers creating multiple accounts.
See the [tutorial](https://docs.talon.one/docs/dev/tutorials/using-identifiers).
**Important**: If you [create a unique identifier budget](https://docs.talon.one/docs/product/campaigns/settings/managing-campaign-budgets#budget-types)
for your campaign, ensure the session contains an identifier by the time you close it.
example:
- 91.11.156.141
attributes:
type: object
description: |
Use this property to set a value for the attributes of your choice. Attributes represent any information to attach to your session, like the shipping city.
You can use [built-in attributes](https://docs.talon.one/docs/dev/concepts/attributes#built-in-attributes) or [custom ones](https://docs.talon.one/docs/dev/concepts/attributes#custom-attributes).
Custom attributes must be created in the Campaign Manager before you set them with this property.
**Note:** If `null`, the attribute is deleted from the customer session.
additionalProperties: true
example:
ShippingCity: Berlin
cartItem:
type: object
required:
- sku
- quantity
x-attributable: true
properties:
name:
title: Name of item
type: string
description: Name of item.
minLength: 1
example: Air Glide
sku:
title: SKU of item
type: string
description: Stock keeping unit of item.
minLength: 1
example: SKU1241028
quantity:
title: Quantity of item
type: integer
description: |
Quantity of item. **Important:** If you enabled [cart item flattening](https://docs.talon.one/docs/product/rules/understanding-cart-item-flattening),
the quantity is always one and the same cart item might receive multiple per-item discounts. Ensure you can process multiple discounts on one cart item correctly.
minimum: 1
example: 1
returnedQuantity:
title: Returned quantity of item
type: integer
description: Number of returned items, calculated internally based on returns of this item.
example: 1
remainingQuantity:
title: Remaining quantity of item
type: integer
description: Remaining quantity of the item, calculated internally based on returns of this item.
example: 1
price:
title: Price of item
type: number
description: Price of the item in the currency defined by your Application. This field is required if this item is not part of a [catalog](https://docs.talon.one/docs/product/account/dev-tools/managing-cart-item-catalogs). If it is part of a catalog, setting a price here overrides the price from the catalog.
example: 99.99
category:
title: Item category
type: string
description: Type, group or model of the item.
example: shoes
weight:
title: Weight of item
type: number
description: Weight of item in grams.
example: 1130
height:
title: Height of item
type: number
description: Height of item in mm.
width:
title: Width of item
type: number
description: Width of item in mm.
length:
title: Length of item
type: number
description: Length of item in mm.
position:
title: Position of Cart Item
type: number
description: Position of the Cart Item in the Cart (calculated internally).
attributes:
title: Item attributes
type: object
description: |
Use this property to set a value for the attributes of your choice. [Attributes](https://docs.talon.one/docs/dev/concepts/attributes) represent any information to attach to this cart item.
Custom _cart item_ attributes must be created in the Campaign Manager before you set them with this property.
additionalProperties: true
example:
image: 11.jpeg
material: leather
additionalCosts:
type: object
description: |
Use this property to set a value for the additional costs of this item, such as a shipping cost. They must be created in the Campaign Manager
before you set them with this property. See [Managing additional costs](https://docs.talon.one/docs/product/account/dev-tools/managing-additional-costs).
additionalProperties:
$ref: '#/components/schemas/additionalCost'
example:
shipping:
price: 9
additionalCost:
type: object
properties:
price:
description: Price of the additional cost.
type: number
example: 4.5
return:
allOf:
- $ref: '#/components/schemas/entity'
- $ref: '#/components/schemas/applicationEntity'
- $ref: '#/components/schemas/accountEntity'
- $ref: '#/components/schemas/newReturn'
- type: object
required:
- eventId
- sessionId
- sessionIntegrationId
properties:
eventId:
title: Event ID
type: integer
description: The event ID of that was generated for this return.
example: 123
sessionId:
title: Session ID
type: integer
description: The internal ID of the session this return was requested on.
example: 123
sessionIntegrationId:
title: Session Integration ID
type: string
maxLength: 1000
description: The integration ID of the session this return was requested on.
example: 0c0e0207-eb30-4e06-a56c-2b7c8a64953c
profileId:
title: Profile ID
type: integer
description: The internal ID of the profile this return was requested on.
example: 123
profileIntegrationId:
title: Profile Integration ID
type: string
maxLength: 1000
description: The integration ID of the profile this return was requested on.
example: 0c0e0207-eb30-4e06-a56c-2b7c8a64953c
createdBy:
title: Created By
type: integer
description: ID of the user who requested this return.
example: 123
newReturn:
type: object
required:
- returnedCartItems
properties:
returnedCartItems:
type: array
description: List of cart items to be returned.
items:
$ref: '#/components/schemas/returnedCartItem'
returnedCartItem:
type: object
required:
- position
properties:
position:
description: The index of the cart item in the provided customer session's `cartItems` property.
type: integer
example: 2
quantity:
description: |
Number of cart items to return. It is only available when [cart item flattening](https://docs.talon.one/docs/product/campaigns/campaign-evaluation#flattened-cart-items)
is enabled. If cart item flattening is disabled, the cart item can only be returned in its entirety.
type: integer
example: 1
giveaway:
allOf:
- $ref: '#/components/schemas/entity'
- type: object
required:
- id
- created
- code
- poolId
properties:
code:
type: string
description: The code value of this giveaway.
poolId:
type: integer
description: The ID of the pool to return giveaway codes from.
startDate:
format: date-time
description: Timestamp at which point the giveaway becomes valid.
type: string
endDate:
format: date-time
description: Timestamp at which point the giveaway becomes invalid.
type: string
attributes:
type: object
description: Arbitrary properties associated with this giveaway.
additionalProperties: true
used:
type: boolean
description: Indicates whether this giveaway code was given before.
importId:
type: integer
description: The ID of the Import which created this giveaway.
ruleFailureReason:
type: object
description: Details about why a rule failed.
required:
- campaignID
- campaignName
- rulesetID
- ruleIndex
- ruleName
properties:
campaignID:
type: integer
description: The ID of the campaign that contains the rule that failed.
campaignName:
type: string
description: The name of the campaign that contains the rule that failed.
rulesetID:
type: integer
description: The ID of the ruleset that contains the rule that failed.
couponID:
type: integer
description: The ID of the coupon that was being evaluated at the time of the rule failure.
example: 4928
couponValue:
type: string
description: The code of the coupon that was being evaluated at the time of the rule failure.
referralID:
type: integer
description: The ID of the referral that was being evaluated at the time of the rule failure.
referralValue:
type: string
description: The code of the referral that was being evaluated at the time of the rule failure.
ruleIndex:
type: integer
description: The index of the rule that failed within the ruleset.
ruleName:
type: string
description: The name of the rule that failed within the ruleset.
conditionIndex:
type: integer
description: The index of the condition that failed.
effectIndex:
type: integer
description: The index of the effect that failed.
details:
type: string
description: More details about the failure.
inventoryReferral:
allOf:
- $ref: '#/components/schemas/referral'
- type: object
x-attributable: true
required:
- referredCustomers
properties:
referredCustomers:
type: array
description: An array of referred customers.
items:
type: string
customerSessionV2:
allOf:
- $ref: '#/components/schemas/entity'
- $ref: '#/components/schemas/integrationEntity'
- $ref: '#/components/schemas/applicationEntity'
- $ref: '#/components/schemas/newCustomerSessionV2'
- type: object
x-attributable: true
properties:
firstSession:
type: boolean
description: Indicates whether this is the first session for the customer's profile. Will always be true for anonymous sessions.
title: First session ever?
example: true
total:
type: number
title: Session Total
description: The total sum of cart-items, as well as additional costs, before any discounts applied.
example: 119.99
cartItemTotal:
type: number
title: Cart Items Total
description: The total sum of cart-items before any discounts applied.
example: 99.99
additionalCostTotal:
type: number
title: Additional Costs Total
description: The total sum of additional costs before any discounts applied.
example: 20
updated:
type: string
format: date-time
description: Timestamp of the most recent event received on this session.
title: Last activity on the session
example: '2020-02-08T14:15:22Z'
required:
- profileId
- firstSession
- coupon
- referral
- state
- cartItems
- integrationId
- applicationId
- attributes
- total
- cartItemTotal
- additionalCostTotal
- updated
integrationEntity:
type: object
required:
- integrationId
- created
properties:
integrationId:
type: string
format: string
example: URNGV8294NV
maxLength: 1000
description: The integration ID set by your integration layer.
created:
type: string
format: date-time
description: The exact moment this entity was created.
example: '2020-02-07T08:15:22Z'
loyalty:
type: object
description: Customer specific information about loyalty points.
required:
- programs
properties:
cards:
title: Point balances of the loyalty cards used.
description: Displays information about the balances of the loyalty cards.
type: array
items:
$ref: '#/components/schemas/loyaltyCard'
programs:
type: object
title: Customer's current loyalty program balance.
description: Displays information about point balances in profile-based programs.
additionalProperties:
$ref: '#/components/schemas/loyaltyProgramLedgers'
loyaltyCard:
allOf:
- $ref: '#/components/schemas/entity'
- $ref: '#/components/schemas/loyaltyProgramEntity'
- $ref: '#/components/schemas/updateLoyaltyCard'
- type: object
required:
- identifier
- usersPerCardLimit
properties:
identifier:
type: string
description: The alphanumeric identifier of the loyalty card.
usersPerCardLimit:
type: integer
minimum: 0
example: 111
description: |
The max amount of user profiles a card can be shared with. 0 means unlimited.
profiles:
type: array
description: Integration IDs of the customers associated with the card.
items:
$ref: '#/components/schemas/loyaltyCardProfileRegistration'
ledger:
$ref: '#/components/schemas/ledgerInfo'
subledgers:
type: object
description: Displays point balances of the card in the subledgers of the loyalty program.
additionalProperties:
$ref: '#/components/schemas/ledgerInfo'
modified:
type: string
format: date-time
description: Timestamp of the most recent update of the loyalty card.
example: '2021-09-12T10:12:42Z'
loyaltyProgramEntity:
type: object
required:
- programID
properties:
programID:
type: integer
description: The ID of the loyalty program that owns this entity.
example: 125
updateLoyaltyCard:
type: object
required:
- status
properties:
status:
type: string
description: |
Status of the loyalty card. Can be one of: ['active', 'disabled'].
loyaltyCardProfileRegistration:
type: object
required:
- integrationId
- timestamp
properties:
integrationId:
type: string
maxLength: 1000
description: Integration ID of the customer associated with the card.
timestamp:
type: string
format: date-time
description: Timestamp of the registration to the card.
example: '2021-09-12T10:12:42Z'
loyaltyProgramLedgers:
type: object
description: Customer specific information about loyalty points.
required:
- ledger
- title
- name
- id
properties:
id:
type: integer
description: The internal ID of loyalty program.
example: 5
title:
description: Visible name of loyalty program.
type: string
example: My loyalty program
name:
description: Internal name of loyalty program.
type: string
example: program1
ledger:
$ref: '#/components/schemas/ledgerInfo'
subLedgers:
type: object
description: A map containing information about each loyalty subledger.
additionalProperties:
$ref: '#/components/schemas/ledgerInfo'
campaign:
allOf:
- $ref: '#/components/schemas/entityWithTalangVisibleID'
- $ref: '#/components/schemas/applicationEntity'
- $ref: '#/components/schemas/userEntity'
- $ref: '#/components/schemas/newCampaign'
- type: object
properties:
couponRedemptionCount:
type: integer
description: Number of coupons redeemed in the campaign.
example: 163
referralRedemptionCount:
type: integer
description: Number of referral codes redeemed in the campaign.
example: 3
discountCount:
type: number
description: Total amount of discounts redeemed in the campaign.
example: 288
discountEffectCount:
type: integer
description: Total number of times discounts were redeemed in this campaign.
example: 343
couponCreationCount:
type: integer
description: Total number of coupons created by rules in this campaign.
example: 16
customEffectCount:
type: integer
description: Total number of custom effects triggered by rules in this campaign.
example: 0
referralCreationCount:
type: integer
description: Total number of referrals created by rules in this campaign.
example: 8
addFreeItemEffectCount:
type: integer
description: Total number of times triggering add free item effext is allowed in this campaign.
example: 0
awardedGiveawaysCount:
type: integer
description: Total number of giveaways awarded by rules in this campaign.
example: 9
createdLoyaltyPointsCount:
type: number
description: Total number of loyalty points created by rules in this campaign.
example: 9
createdLoyaltyPointsEffectCount:
type: integer
description: Total number of loyalty point creation effects triggered by rules in this campaign.
example: 2
redeemedLoyaltyPointsCount:
type: number
description: Total number of loyalty points redeemed by rules in this campaign.
example: 8
redeemedLoyaltyPointsEffectCount:
type: integer
description: Total number of loyalty point redemption effects triggered by rules in this campaign.
example: 9
callApiEffectCount:
type: integer
description: Total number of webhook triggered by rules in this campaign.
example: 0
lastActivity:
type: string
format: date-time
example: '2022-11-10T23:00:00Z'
description: Timestamp of the most recent event received by this campaign.
updated:
type: string
format: date-time
example: '2022-10-07T11:00:00Z'
description: |
Timestamp of the most recent update to the campaign's property. Updates to external entities used in this campaign
are **not** registered by this property, such as collection or coupon updates.
createdBy:
type: string
description: Name of the user who created this campaign if available.
example: John Doe
updatedBy:
type: string
description: Name of the user who last updated this campaign if available.
example: Jane Doe
templateId:
type: integer
description: The ID of the Campaign Template this Campaign was created from.
example: 3
required:
- state
- description
newCampaign:
type: object
properties:
name:
type: string
title: Campaign Name
description: A user-facing name for this campaign.
minLength: 1
example: Summer promotions
description:
type: string
title: Campaign Description
description: A detailed description of the campaign.
example: Campaign for all summer 2021 promotions
startTime:
type: string
format: date-time
description: Timestamp when the campaign will become active.
example: '2021-07-20T22:00:00Z'
endTime:
type: string
format: date-time
description: Timestamp the campaign will become inactive.
example: '2021-09-22T22:00:00Z'
attributes:
type: object
description: Arbitrary properties associated with this campaign.
additionalProperties: true
state:
type: string
enum:
- enabled
- disabled
- archived
default: enabled
description: |
A disabled or archived campaign is not evaluated for rules or coupons.
activeRulesetId:
type: integer
description: |
[ID of Ruleset](https://docs.talon.one/management-api#operation/getRulesets) this
campaign applies on customer session evaluation.
tags:
type: array
description: A list of tags for the campaign.
example:
- summer
maxItems: 50
items:
type: string
minLength: 1
maxLength: 50
features:
type: array
description: The features enabled in this campaign.
example:
- coupons
- referrals
items:
type: string
enum:
- coupons
- referrals
- loyalty
- giveaways
couponSettings:
$ref: '#/components/schemas/codeGeneratorSettings'
referralSettings:
$ref: '#/components/schemas/codeGeneratorSettings'
limits:
type: array
description: |
The set of [budget limits](https://docs.talon.one/docs/product/campaigns/settings/managing-campaign-budgets) for this campaign.
items:
$ref: '#/components/schemas/limitConfig'
campaignGroups:
type: array
description: |
The IDs of the [campaign groups](https://docs.talon.one/docs/product/account/managing-campaign-groups) this campaign belongs to.
example:
- 1
- 3
items:
type: integer
required:
- name
- state
- tags
- limits
- features
codeGeneratorSettings:
type: object
properties:
validCharacters:
type: array
description: |
List of characters used to generate the random parts of a code. Defaults to a list equivalent to the
`[A-Z, 0-9]` regexp.
example:
- A
- B
- C
- D
- E
- '2'
- '0'
items:
type: string
couponPattern:
type: string
description: |
The pattern used to generate coupon codes. The character `#` is a placeholder and is replaced by a random character from the `validCharacters` set.
maxLength: 100
minLength: 3
example: SUMMER-####-####
additionalProperties: false
required:
- couponPattern
- validCharacters
entityWithTalangVisibleID:
type: object
required:
- id
- created
properties:
id:
type: integer
description: Unique ID for this entity.
created:
type: string
format: date-time
description: The exact moment this entity was created.
userEntity:
type: object
required:
- userId
properties:
userId:
type: integer
description: The ID of the account that owns this entity.
referral:
allOf:
- $ref: '#/components/schemas/entity'
- $ref: '#/components/schemas/newReferral'
- $ref: '#/components/schemas/importEntity'
- type: object
x-attributable: true
required:
- code
- usageCounter
- usageLimit
properties:
code:
type: string
title: Referral code
description: The referral code.
minLength: 4
example: 27G47Y54VH9L
usageCounter:
type: integer
title: Referral code Usages
description: The number of times this referral code has been successfully used.
example: 1
batchId:
type: string
title: Batch ID
description: The ID of the batch the referrals belong to.
example: tqyrgahe
newReferral:
allOf:
- $ref: '#/components/schemas/referralConstraints'
- type: object
required:
- campaignId
- advocateProfileIntegrationId
properties:
campaignId:
type: integer
title: Referral's Campaign ID
description: ID of the campaign from which the referral received the referral code.
example: 78
advocateProfileIntegrationId:
type: string
title: Advocate's Profile ID
description: The Integration ID of the Advocate's Profile.
maxLength: 1000
example: URNGV8294NV
friendProfileIntegrationId:
type: string
title: Friend's Profile ID
description: An optional Integration ID of the Friend's Profile.
example: BZGGC2454PA
attributes:
type: object
description: Arbitrary properties associated with this item.
additionalProperties: true
referralConstraints:
type: object
required:
- campaignId
properties:
startDate:
type: string
format: date-time
minimum: 0
title: Referral code valid from
description: Timestamp at which point the referral code becomes valid.
example: '2020-11-10T23:00:00Z'
expiryDate:
type: string
format: date-time
minimum: 0
title: Referral code valid until
description: Expiry date of the referral code. Referral never expires if this is omitted, zero, or negative.
example: '2021-11-10T23:00:00Z'
usageLimit:
type: integer
title: Referral code Usage Limit
description: |
The number of times a referral code can be used. `0` means no limit but any campaign usage limits will still apply.
minimum: 0
maximum: 999999
example: 1
importEntity:
type: object
required:
- id
properties:
importId:
type: integer
description: The ID of the Import which created this referral.
coupon:
allOf:
- $ref: '#/components/schemas/entity'
- $ref: '#/components/schemas/campaignEntity'
- $ref: '#/components/schemas/couponValue'
- $ref: '#/components/schemas/couponConstraints'
- $ref: '#/components/schemas/couponLimitConfigs'
- type: object
x-attributable: true
required:
- value
- usageCounter
- usageLimit
properties:
usageCounter:
type: integer
title: Number of coupon usages
example: 10
description: The number of times this coupon has been successfully used.
discountCounter:
type: number
title: Discounts Given
description: The amount of discounts given on rules redeeming this coupon. Only usable if a coupon discount budget was set for this coupon.
discountRemainder:
type: number
title: Coupon Discount Remainder
description: The remaining discount this coupon can give.
attributes:
type: object
title: Attributes of coupon
description: Custom attributes associated with this coupon.
additionalProperties: true
referralId:
type: integer
title: Advocate ID
description: The integration ID of the referring customer (if any) for whom this coupon was created as an effect.
example: 326632952
recipientIntegrationId:
title: Recipient ID
example: URNGV8294NV
type: string
maxLength: 1000
description: The Integration ID of the customer that is allowed to redeem this coupon.
importId:
title: Import ID
type: integer
description: The ID of the Import which created this coupon.
reservation:
title: Reservation Type
type: boolean
example: false
description: |
Defines the reservation type:
- `true`: The coupon can be reserved for multiple customers.
- `false`: The coupon can be reserved only for one customer. It is a personal code.
default: true
batchId:
title: Batch ID
type: string
description: The id of the batch the coupon belongs to.
example: 32535-43255
campaignEntity:
type: object
required:
- campaignId
properties:
campaignId:
type: integer
title: Campaign ID
description: The ID of the campaign that owns this entity.
example: 211
couponValue:
type: object
properties:
value:
type: string
title: Coupon Code
description: The coupon code.
minLength: 4
example: XMAS-20-2021
couponConstraints:
type: object
properties:
usageLimit:
type: integer
minimum: 0
maximum: 999999
example: 100
description: |
The number of times the coupon code can be redeemed. `0` means unlimited redemptions but any campaign usage limits will still apply.
discountLimit:
type: number
minimum: 0
maximum: 999999
example: 30
description: |
The amount of discounts that can be given with this coupon code.
startDate:
type: string
format: date-time
minimum: 0
description: Timestamp at which point the coupon becomes valid.
expiryDate:
type: string
format: date-time
minimum: 0
description: Expiry date of the coupon. Coupon never expires if this is omitted, zero, or negative.
couponLimitConfigs:
type: object
properties:
limits:
type: array
description: |
Limits configuration for a coupon. These limits will override the limits
set from the campaign.
**Note:** Only usable when creating a single coupon which is not tied to a specific recipient.
Only per-profile limits are allowed to be configured.
items:
$ref: '#/components/schemas/limitConfig'
limitConfig:
type: object
required:
- action
- limit
- entities
properties:
action:
type: string
description: |
The limitable action to which this limit applies. For example:
- `setDiscount`
- `setDiscountEffect`
- `redeemCoupon`
- `createCoupon`
example: createCoupon
limit:
type: number
minimum: 0
example: 1000
description: The value to set for the limit.
period:
description: The period on which the budget limit recurs.
type: string
enum:
- daily
- weekly
- monthly
- yearly
example: yearly
entities:
type: array
description: The entity that this limit applies to.
example:
- Coupon
items:
type: string
enum:
- Coupon
- Referral
- Profile
- Identifier
effect:
allOf:
- $ref: '#/components/schemas/effectEntity'
- type: object
description: A generic effect that is fired by a triggered campaign. The props property will contain information specific to the specific effect type.
required:
- props
properties:
props:
$ref: '#/components/schemas/effectProps'
effectEntity:
type: object
description: Definition of all properties that are present on all effects, independent of their type.
required:
- campaignId
- rulesetId
- ruleIndex
- ruleName
- effectType
properties:
campaignId:
type: integer
description: The ID of the campaign that triggered this effect.
example: 244
rulesetId:
type: integer
description: The ID of the ruleset that was active in the campaign when this effect was triggered.
example: 73
ruleIndex:
type: integer
description: The position of the rule that triggered this effect within the ruleset.
example: 2
ruleName:
type: string
description: The name of the rule that triggered this effect.
example: Give 20% discount
effectType:
type: string
description: The type of effect that was triggered.
example: rejectCoupon
triggeredByCoupon:
type: integer
example: 4928
description: The ID of the coupon that was being evaluated when this effect was triggered.
effectProps:
type: object
oneOf:
- $ref: '#/components/schemas/acceptCouponEffectProps'
- $ref: '#/components/schemas/acceptReferralEffectProps'
- $ref: '#/components/schemas/redeemReferralEffectProps'
- $ref: '#/components/schemas/rejectCouponEffectProps'
- $ref: '#/components/schemas/rejectReferralEffectProps'
- $ref: '#/components/schemas/couponCreatedEffectProps'
- $ref: '#/components/schemas/referralCreatedEffectProps'
- $ref: '#/components/schemas/setDiscountEffectProps'
- $ref: '#/components/schemas/setDiscountPerItemEffectProps'
- $ref: '#/components/schemas/setDiscountPerAdditionalCostEffectProps'
- $ref: '#/components/schemas/triggerWebhookEffectProps'
- $ref: '#/components/schemas/addLoyaltyPointsEffectProps'
- $ref: '#/components/schemas/deductLoyaltyPointsEffectProps'
- $ref: '#/components/schemas/addFreeItemEffectProps'
- $ref: '#/components/schemas/showNotificationEffectProps'
- $ref: '#/components/schemas/updateAttributeEffectProps'
- $ref: '#/components/schemas/rollbackCouponEffectProps'
- $ref: '#/components/schemas/rollbackReferralEffectProps'
- $ref: '#/components/schemas/rollbackDiscountEffectProps'
- $ref: '#/components/schemas/rollbackAddedLoyaltyPointsEffectProps'
- $ref: '#/components/schemas/rollbackDeductedLoyaltyPointsEffectProps'
- $ref: '#/components/schemas/showBundleMetadataEffectProps'
- $ref: '#/components/schemas/awardGiveawayEffectProps'
- $ref: '#/components/schemas/willAwardGiveawayEffectProps'
- $ref: '#/components/schemas/errorEffectProps'
- $ref: '#/components/schemas/customEffectProps'
- $ref: '#/components/schemas/setDiscountPerAdditionalCostPerItemEffectProps'
acceptCouponEffectProps:
type: object
description: The properties specific to the "acceptCoupon" effect. This gets triggered whenever the coupon is valid and all other conditions in the rules of its campaign are met.
required:
- value
properties:
value:
type: string
description: The coupon code that was accepted.
acceptReferralEffectProps:
type: object
description: The properties specific to the "acceptReferral" effect. TThis gets triggered whenever the referral code is valid and all other conditions in the rules of its campaign are met.
required:
- value
properties:
value:
type: string
description: The referral code that was accepted.
redeemReferralEffectProps:
type: object
description: The properties specific to the "redeemReferral" effect. This gets triggered whenever the referral code is valid, and a rule was triggered that contains a "redeem referral" effect.
required:
- id
- value
properties:
id:
type: integer
description: The id of the referral code that was redeemed.
value:
type: string
description: The referral code that was redeemed.
rejectCouponEffectProps:
type: object
description: The properties specific to the "rejectCoupon" effect. This gets triggered whenever the coupon was rejected. See rejectionReason for more info on why.
required:
- value
- rejectionReason
properties:
value:
type: string
description: The coupon code that was rejected.
rejectionReason:
type: string
description: The reason why this coupon was rejected.
conditionIndex:
type: integer
description: The index of the condition that caused the rejection of the coupon.
effectIndex:
type: integer
description: The index of the effect that caused the rejection of the coupon.
details:
type: string
description: More details about the failure.
rejectReferralEffectProps:
type: object
description: The properties specific to the "rejectReferral" effect. This gets triggered whenever the referral code was rejected. See rejectionReason for more info on why.
required:
- value
- rejectionReason
properties:
value:
type: string
description: The referral code that was rejected.
rejectionReason:
type: string
description: The reason why this referral code was rejected.
conditionIndex:
type: integer
description: The index of the condition that caused the rejection of the referral.
effectIndex:
type: integer
description: The index of the effect that caused the rejection of the referral.
details:
type: string
description: More details about the failure.
couponCreatedEffectProps:
type: object
description: The properties specific to the "couponCreated" effect. This gets triggered whenever a validated rule contained a "create coupon" effect, and a coupon was created for a customer. See "createdCoupons" on the response for all details of this coupon.
required:
- value
- profileId
properties:
value:
type: string
description: The coupon code that was created.
profileId:
type: string
description: The integration identifier of the customer for whom this coupon was created.
referralCreatedEffectProps:
type: object
description: The properties specific to the "referralCreated" effect. This gets triggered whenever a validated rule contained a "create referral" effect, and a referral code was created for a customer. See "createdReferrals" on the response for all details of this referral code.
required:
- value
properties:
value:
type: string
description: The referral code that was created.
setDiscountEffectProps:
type: object
description: The properties specific to the "setDiscount" effect. This gets triggered whenever a validated rule contained a "set discount" effect. This is a discount that should be applied on the scope of defined with it.
required:
- name
- value
properties:
name:
type: string
description: The name/description of this discount.
value:
type: number
description: The total monetary value of the discount.
scope:
type: string
description: The scope which the discount was applied on, can be one of (cartItems,additionalCosts,sessionTotal).
desiredValue:
type: number
description: The original value of the discount.
setDiscountPerItemEffectProps:
type: object
description: |
The properties specific to the `setDiscountPerItem` effect, triggered whenever a validated rule contained a
"set per item discount" effect.
This is a discount that will be applied either on a specific item, on a specific item + additional cost or on all additional costs per item.
This depends on the chosen scope.
required:
- name
- value
- position
properties:
name:
type: string
description: |
The name of the discount. Contains a hashtag character indicating the index of the position of the item the discount applies
to. It is identical to the value of the `position` property.
value:
type: number
description: The total monetary value of the discount.
position:
type: number
description: The index of the item in the cart items list on which this discount should be applied.
subPosition:
type: number
description: |
Only used when [cart item flattening](https://docs.talon.one/docs/product/campaigns/campaign-evaluation#flattened-cart-items) is enabled.
Indicates which item the discount applies to for cart items with `quantity` > 1.
desiredValue:
type: number
description: The original value of the discount.
scope:
type: string
description: |
The scope of the discount:
- `additionalCosts`: The discount applies to all the additional costs of the item.
- `itemTotal`: The discount applies to the price of the item + the additional costs of the item.
- `price`: The discount applies to the price of the item.
totalDiscount:
type: number
description: The total discount given if this effect is a result of a prorated discount.
desiredTotalDiscount:
type: number
description: The original total discount to give if this effect is a result of a prorated discount.
bundleIndex:
type: integer
description: The position of the bundle in a list of item bundles created from the same bundle definition.
bundleName:
type: string
description: The name of the bundle binding.
setDiscountPerAdditionalCostEffectProps:
type: object
description: The properties specific to the "setDiscountPerAdditionalCost" effect. This gets triggered whenever a validated rule contained a "set per additional cost discount" effect. This is a discount that should be applied on a specific additional cost.
required:
- name
- value
- additionalCostId
- additionalCost
properties:
name:
type: string
description: The name/description of this discount.
additionalCostId:
type: integer
description: The ID of the additional cost.
additionalCost:
type: string
description: The name of the additional cost.
value:
type: number
description: The total monetary value of the discount.
desiredValue:
type: number
description: The original value of the discount.
triggerWebhookEffectProps:
type: object
description: The properties specific to the "triggerWebhook" effect. This gets triggered whenever a validated rule contained a "trigger webhook" effect. This is communicated as an FYI and should usually not require action on your side.
required:
- webhookId
- webhookName
properties:
webhookId:
type: number
description: The ID of the webhook that was triggered.
webhookName:
type: string
description: The name of the webhook that was triggered.
addLoyaltyPointsEffectProps:
type: object
description: |
The properties specific to the "addLoyaltyPoints" effect. This gets triggered whenever a validated rule contained an "add loyalty" effect. These points are automatically stored and managed inside Talon.One.
required:
- name
- programId
- subLedgerId
- value
- recipientIntegrationId
- transactionUUID
properties:
name:
type: string
description: The name/description of this loyalty point addition.
programId:
type: integer
description: The ID of the loyalty program where these points were added.
subLedgerId:
type: string
description: The ID of the subledger within the loyalty program where these points were added.
value:
type: number
description: The amount of points that were added.
desiredValue:
type: number
description: The original amount of loyalty points to be awarded.
recipientIntegrationId:
type: string
maxLength: 1000
description: The user for whom these points were added.
startDate:
type: string
format: date-time
description: Date after which points will be valid.
expiryDate:
type: string
format: date-time
description: Date after which points will expire.
transactionUUID:
type: string
description: The identifier of this addition in the loyalty ledger.
cartItemPosition:
type: number
description: The index of the item in the cart items list on which the loyal points addition should be applied.
cartItemSubPosition:
type: number
description: |
The sub position is triggered when application flattening is enabled.
It indicates to which item the loyalty points addition applies, for cart items with `quantity` > 1.
cardIdentifier:
type: string
description: The card on which these points were added.
deductLoyaltyPointsEffectProps:
type: object
description: The properties specific to the "deductLoyaltyPoints" effect. This gets triggered whenever a validated rule contained a condition to only trigger when the given number of loyalty points could be deduced. These points are automatically stored and managed inside Talon.One.
required:
- ruleTitle
- programId
- subLedgerId
- value
- transactionUUID
- name
properties:
ruleTitle:
type: string
description: The title of the rule that contained triggered this points deduction.
programId:
type: integer
description: The ID of the loyalty program where these points were added.
subLedgerId:
type: string
description: The ID of the subledger within the loyalty program where these points were added.
value:
type: number
description: The amount of points that were deducted.
transactionUUID:
type: string
description: The identifier of this deduction in the loyalty ledger.
name:
type: string
description: |
The name property gets one of the following two values. It can be the loyalty program name or it can represent a reason for the respective deduction of loyalty points. The latter is an optional value defined in a deduction rule.
cardIdentifier:
type: string
description: The card on which these points were added.
addFreeItemEffectProps:
type: object
description: The properties specific to the "addFreeItem" effect. This gets triggered whenever a validated rule contained an "add free item" effect.
required:
- sku
- name
properties:
sku:
type: string
description: SKU of the item that needs to be added.
example: SKU1241028
name:
type: string
description: The name/description of the effect.
showNotificationEffectProps:
type: object
description: The properties specific to the "showNotification" effect. This gets triggered whenever a validated rule contained a "show notification" effect.
required:
- notificationType
- title
- body
properties:
notificationType:
type: string
description: The type of notification that should be shown (e.g. error/warning/info).
title:
type: string
description: Title of the notification.
body:
type: string
description: Body of the notification.
updateAttributeEffectProps:
type: object
description: The properties specific to the "updateAttribute" effect. This gets triggered whenever a validated rule contained an "update an attribute" effect.
required:
- path
- value
properties:
path:
type: string
description: The exact path of the attribute that was updated.
value:
anyOf:
- type: string
- type: number
- type: integer
- type: boolean
- type: array
items: {}
- type: object
description: The new value of this attribute. Value can be any of the following types (string, time, number, boolean, location, (list string), (list number), (list time), (list location)) or a list of any of those types
rollbackCouponEffectProps:
type: object
description: The properties specific to the "rollbackCoupon" effect. This gets triggered whenever previously closed session is now cancelled and a coupon redemption was cancelled on our internal usage limit counters.
required:
- value
properties:
value:
type: string
description: The coupon code whose usage has been rolled back.
rollbackReferralEffectProps:
type: object
description: The properties specific to the "rollbackReferral" effect. This gets triggered whenever previously closed session is now cancelled and a referral redemption was cancelled on our internal usage limit counters.
required:
- value
properties:
value:
type: string
description: The referral code whose usage has been rolled back.
rollbackDiscountEffectProps:
type: object
description: The properties specific to the "rollbackDiscount" effect. This gets triggered whenever previously closed session is now cancelled or partially returned and a setDiscount effect was cancelled on our internal discount limit counters.
required:
- name
- value
properties:
name:
type: string
description: The name of the "setDiscount" effect that was rolled back.
value:
type: number
description: The value of the discount that was rolled back.
cartItemPosition:
type: number
description: The index of the item in the cart items for which the discount was rolled back.
cartItemSubPosition:
type: number
description: |
The index of the item unit in its line item. It is only used for cart items with `quantity` > 1 and is
only returned when cart item flattening is enabled.
additionalCostId:
type: integer
description: The ID of the additional cost that was rolled back.
additionalCost:
type: string
description: The name of the additional cost that was rolled back.
scope:
type: string
description: |
The scope of the rolled back discount
- For a discount per session, it can be one of `cartItems`, `additionalCosts` or `sessionTotal`
- For a discount per item, it can be one of `price`, `additionalCosts` or `itemTotal`
rollbackAddedLoyaltyPointsEffectProps:
type: object
description: The properties specific to the "rollbackAddedLoyaltyPoints" effect. This gets triggered whenever previously a closed session with an addLoyaltyPoints effect is cancelled.
required:
- name
- programId
- subLedgerId
- value
- recipientIntegrationId
- transactionUUID
properties:
programId:
type: integer
description: The ID of the loyalty program where the points were originally added.
subLedgerId:
type: string
description: The ID of the subledger within the loyalty program where these points were originally added.
value:
type: number
description: The amount of points that were rolled back.
recipientIntegrationId:
type: string
maxLength: 1000
description: The user for whom these points were originally added.
transactionUUID:
type: string
description: |
The identifier of `deduction` entry added to the ledger as the `addLoyaltyPoints` effect is rolled back.
cartItemPosition:
type: number
description: The index of the item in the cart items for which the loyalty points were rolled back.
cartItemSubPosition:
type: number
description: |
The sub-position is returned when [cart item flattening](https://docs.talon.one/docs/product/campaigns/campaign-evaluation#flattened-cart-items) is enabled.
It indicates to which item the loyalty points were rolled back, for cart items with `quantity` > 1.
cardIdentifier:
type: string
description: The card on which these points were originally added.
rollbackDeductedLoyaltyPointsEffectProps:
type: object
description: The properties specific to the "rollbackDeductedLoyaltyPoints" effect. This effect is triggered whenever a previously closed session is cancelled and a deductLoyaltyPoints effect was revoked.
required:
- name
- programId
- subLedgerId
- value
- recipientIntegrationId
- transactionUUID
properties:
programId:
type: integer
description: The ID of the loyalty program where these points were reimbursed.
subLedgerId:
type: string
description: The ID of the subledger within the loyalty program where these points were reimbursed.
value:
type: number
description: The amount of reimbursed points that were added.
recipientIntegrationId:
type: string
maxLength: 1000
description: The user for whom these points were reimbursed.
startDate:
type: string
format: date-time
description: Date after which the reimbursed points will be valid.
expiryDate:
type: string
format: date-time
description: Date after which the reimbursed points will expire.
transactionUUID:
type: string
description: The identifier of 'addition' entries added to the ledger as the `deductLoyaltyPoints` effect is rolled back.
cardIdentifier:
type: string
description: The card on which these points were added.
showBundleMetadataEffectProps:
type: object
description: The properties specific to the "ShowBundleMetadata" effect. This effect contains information that allows you to associate the discounts from a rule in a bundle campaign with specific cart items. This way you can distinguish from "normal" discounts that were not the result of a product bundle.
required:
- description
- bundleAttributes
- itemsIndices
properties:
description:
type: string
description: Description of the product bundle.
bundleAttributes:
type: array
items:
type: string
description: The cart item attributes that determined which items are being bundled together.
itemsIndices:
type: array
items:
type: number
description: The indices in the cart items array of the bundled items.
awardGiveawayEffectProps:
type: object
description: The properties specific to the "awardGiveaway" effect. This effect contains information on the giveaway item, and which profile it was awarded to.
required:
- poolId
- poolName
- recipientIntegrationId
- giveawayId
- code
properties:
poolId:
type: integer
description: The ID of the giveaways pool the code was taken from.
poolName:
type: string
description: The name of the giveaways pool the code was taken from.
recipientIntegrationId:
type: string
maxLength: 1000
description: The integration ID of the profile that was awarded the giveaway.
giveawayId:
type: integer
description: The internal ID for the giveaway that was awarded.
code:
type: string
description: The giveaway code that was awarded.
willAwardGiveawayEffectProps:
type: object
description: The properties specific to the "awardGiveaway" effect when the session is not closed yet. This effect replaces "awardGiveaway" only when updating a session with any state other than "closed". This is to ensure no giveaway codes are leaked when they are still not guaranteed to be awarded.
required:
- poolId
- poolName
- recipientIntegrationId
properties:
poolId:
type: integer
description: The ID of the giveaways pool the code will be taken from.
poolName:
type: string
description: The name of the giveaways pool the code will be taken from.
recipientIntegrationId:
type: string
maxLength: 1000
description: The integration ID of the profile that will be awarded the giveaway.
errorEffectProps:
type: object
description: Whenever an error occurred during evaluation, we return an error effect. This should never happen for rules created in the rule builder.
required:
- message
properties:
message:
type: string
description: The error message.
customEffectProps:
type: object
description: Effect containing custom payload.
required:
- effectId
- name
- payload
properties:
effectId:
type: integer
description: The ID of the custom effect that was triggered.
name:
type: string
description: The type of the custom effect.
payload:
description: The JSON payload of the custom effect.
type: object
additionalProperties: true
x-arbitraryJSON: true
setDiscountPerAdditionalCostPerItemEffectProps:
type: object
description: The properties specific to the "setDiscountPerAdditionalCostPerItem" effect. This gets triggered whenever a validated rule contained a "set discount per additional cost per item" effect. This is a discount that should be applied on a specific additional cost in a specific item.
required:
- name
- value
- additionalCostId
- additionalCost
- position
properties:
name:
type: string
description: The name/description of this discount.
additionalCostId:
type: integer
description: The ID of the additional cost.
value:
type: number
description: The total monetary value of the discount.
position:
type: number
description: The index of the item in the cart item list containing the additional cost to be discounted.
subPosition:
type: number
description: |
Only used when [cart item flattening](https://docs.talon.one/docs/product/campaigns/campaign-evaluation#flattened-cart-items) is enabled.
Indicates which item the discount applies to for cart items with `quantity` > 1.
additionalCost:
type: string
description: The name of the additional cost.
desiredValue:
type: number
description: |
Only with [partial discounts enabled](https://docs.talon.one/docs/product/campaigns/campaign-evaluation#partial-discounts).
Represents the monetary value of the discount to be applied to additional discount without considering budget limitations.
errorResponseWithStatus:
type: object
properties:
StatusCode:
type: integer
description: The error code.
example: 400
Error:
type: string
example: Bad request
RequestUUID:
type: string
example: 51fad142-3563-4fe2-b4aa-41ab20be31d911
EmarsysCustomerProfilesAudiencesRequest:
type: object
required:
- parameters
properties:
parameters:
type: array
maxItems: 1000
items:
type: object
required:
- customerProfileId
- audienceId
- actionType
properties:
customerProfileId:
type: string
description: The integration ID of the customer profile.
example: customer123
audienceId:
type: string
description: The internal ID of the audience. Must be a string containing the numeric ID of an existing audience.
example: '1'
actionType:
type: string
description: The action to perform.
enum:
- add
- delete
example: add
examples:
CouponReservationRequest:
value:
deploymentUrl: mycompany.europe-west1.talon.one
couponValue: EW-1BC2
integrationId: URN-GV8294NV
CouponReservationResponse:
value:
id: 1
campaignId: 1
created: '2022-03-02T16:46:17.758585Z'
value: EW-1BC2
usageCounter: 0
usageLimit: 1
BrazeCouponRequest:
value:
deploymentUrl: mycompany.europe-west1.talon.one
applicationId: 398
campaignId: 5671
identifier: test-coupon
usageLimit: 4
discountLimit: 30
reservationLimit: 45
integrationId: URN-GV8294NV
startDate: '2021-09-30T15:35:02.371569+02:00'
expiryDate: '2024-10-03T15:35:02.371569+02:00'
validCharacters:
- A
- B
- C
- '1'
- '2'
couponPattern: ew-####
isReservationMandatory: false
limits:
- entities:
- Coupon
- Profile
limit: 1
action: redeemCoupon
attributes:
venueId: BER4271
venueName: Admiralspalast
CouponResponse:
value:
ID: 20190408
ApplicationID: 398
CampaignID: 5671
Value: EW-1BC2
StartDate: '2021-09-30T15:35:02.371569+02:00'
ExpiryDate: '2024-10-03T15:35:02.371569+02:00'
RecipientIntegrationID: URN-GV8294NV
UsageLimit: 1
Attributes:
email: user@mailbox.com
country: DE
BrazeCouponResponse:
value:
ID: 20190408
ApplicationID: 398
CampaignID: 5671
Value: EW-1BC2
StartDate: '2021-09-30T15:35:02.371569+02:00'
ExpiryDate: '2024-10-03T15:35:02.371569+02:00'
RecipientIntegrationID: URN-GV8294NV
UsageLimit: 1
IsReservationMandatory: false
Limits:
- entities:
- Coupon
- Profile
limit: 1
action: redeemCoupon
Attributes:
email: user@mailbox.com
country: DE
EmarsysCustomerProfilesAudiencesRequest:
value:
parameters:
- customerProfileId: customer123
audienceId: 1
actionType: add
EmarsysCouponResponse:
value:
content:
- integrationId: test-user-4zoj1c
campaignId: '8431'
id: 26443683
created: '2024-01-03T11:28:25.648154Z'
value: QQ4R-C3BQ
usageLimit: 1
usageCounter: 0
recipientIntegrationId: test-user-4zoj1c
reservation: false
batchId: qndflqqd
profileRedemptionCount: 0
state: active
EmarsysLoyaltyBalanceResponse:
value:
content:
- integrationId: test-user-4zoj1c
loyaltyProgramId: '8431'
activeBalance: 100
pendingBalance: 0
expiredBalance: 0
totalBalance: 100
ReferralRequest:
value:
deploymentUrl: mycompany.europe-west1.talon.one
campaignId: 5672
advocateProfileIntegrationId: '2'
friendProfileIntegrationId: '3'
startDate: '2021-09-30T15:35:02.371569+02:00'
expiryDate: '2021-10-03T15:35:02.371569+02:00'
usageLimit: 3
attributes:
welcome_message: Welcome!
ReferralResponse:
value:
id: 1374
created: '2022-04-01T16:46:36.625152002Z'
startDate: '2021-09-30T15:35:02.371569+02:00'
expiryDate: '2021-10-03T15:35:02.371569+02:00'
usageLimit: 0
campaignId: 5672
advocateProfileIntegrationId: URN-GV8294NV
friendProfileIntegrationId: PKBR-G06449OELK
attributes:
welcome_message: Welcome!
code: P8BN-4T5V
usageCounter: 0
AudienceSubscriptionRequest:
value:
type: audience_subscription_request
id: 62cdcd11-3913-4c66-a2c7-01ae7a445a61
timestamp_ms: 1586980879793
firehose_version: 2.4.0
account:
account_id: 1234567
account_settings:
apiKey: someapikey
deploymentURL: mycompany.europe-west1.talon.one
userIdField: email
audience_id: 234
audience_name: Travel audience
action: add
audience_subscription_settings:
customField: 1
user_attributes:
- key: email
value: john@doe.com
AudienceMembershipChangeRequest:
value:
type: audience_membership_change_request
id: 62cdcd11-3913-4c66-a2c7-01ae7a445a61
timestamp_ms: 1586980879793
firehose_version: 2.4.0
account:
account_id: 1234567
account_settings:
apiKey: someapikey
deploymentURL: mycompany.europe-west1.talon.one
userIdField: customerId
runRuleEngine: true
user_profiles:
- mpid: c314b207-f3ae-4d21-9ae7-5983af40876a
audiences:
- audience_id: 234
audience_name: Travel audience
action: add
user_attributes:
- key: currency
value: USD
action: upsert
user_identities:
- type: customerId
encoding: raw
required: true
value: 0a7e3eb4-911d-4b8b
EventProcessingRequest:
value:
type: event_processing_request
id: 62cdcd11-3913-4c66-a2c7-01ae7a445a61
timestamp_ms: 1586980879793
firehose_version: 2.4.0
account:
account_settings:
apiKey: someapikey
deploymentURL: mycompany.europe-west1.talon.one
userIdField: customerId
runRuleEngine: true
user_identities:
- type: customerId
encoding: raw
required: true
value: 0a7e3eb4-911d-4b8b
mpid: c314b207-f3ae-4d21-9ae7-5983af40876a
events:
- name: click_event
type: custom_event
session_id: 109
attributes:
platform: iOS
ModuleRegistrationRequest:
value:
type: module_registration_request
id: 62cdcd11-3913-4c66-a2c7-01ae7a445a61
timestamp_ms: 1586980879793
firehose_version: 2.4.0
account:
account_id: 1234567
account_settings:
apiKey: someapikey
deploymentURL: mycompany.europe-west1.talon.one
userIdField: email
EventProcessingResponse:
value:
type: event_processing_response
id: 62cdcd11-3913-4c66-a2c7-01ae7a445a61
timestamp_ms: 1586980879793
firehose_version: 2.4.0
AudienceSubscriptionResponse:
value:
type: audience_subscription_response
id: 62cdcd11-3913-4c66-a2c7-01ae7a445a61
timestamp_ms: 1586980879793
firehose_version: 2.4.0
AudienceMembershipChangeResponse:
value:
type: audience_membership_change_response
id: 62cdcd11-3913-4c66-a2c7-01ae7a445a61
timestamp_ms: 1586980879793
firehose_version: 2.4.0
ModuleRegistrationResponse:
value:
type: module_registration_response
id: 62cdcd11-3913-4c66-a2c7-01ae7a445a61
timestamp_ms: 1586980879793
firehose_version: 2.4.0
name: Talon.One
description: Talon.One is the world's most flexible Promotion Engine. Create, manage and track coupon codes, discount campaigns, loyalty programs and referrals in one system.
version: 0.0.1
permissions:
allow_consent_state: true
allow_access_mpid: true
allow_user_attributes: true
allow_audience_user_attributes: true
user_identities:
- type: email
encoding: raw
required: false
value: john@doe.com
- type: customerId
encoding: raw
required: false
value: 0a7e3eb4-911d-4b8b
audience_processing_registration:
account_settings:
- type: text
id: deploymentURL
name: Deployment URL
description: URL of your Talon.One deployment
visible: true
required: true
confidential: true
default_value: ''
- type: text
id: apiKey
name: API Key
description: API Key to be used for requests to your Talon.One deployment
visible: true
required: true
confidential: true
default_value: ''
- type: text
id: userIdField
name: User ID
description: Select which user identity to forward to Talon.One as your customer's user ID.
visible: true
required: true
confidential: true
default_value: customerId
- type: boolean
id: runRuleEngine
name: Run Rule Engine
description: Dictates whether the Rule Engine should be run after each membership change.
visible: true
required: true
confidential: false
default_value: false
audience_subscription_settings:
- type: integer
id: t1AudienceID
name: Talon.One Audience ID
visible: false
required: false
event_processing_registration:
account_settings:
- type: text
id: deploymentURL
name: Deployment URL
description: URL of your Talon.One deployment
visible: true
required: true
confidential: true
default_value: ''
- type: text
id: apiKey
name: API Key
description: API Key to be used for requests to your Talon.One deployment
visible: true
required: true
confidential: true
default_value: ''
- type: text
id: userIdField
name: User ID
description: Select which user identity to forward to Talon.One as your customer's user ID.
visible: true
required: true
confidential: true
default_value: customerId
- type: boolean
id: runRuleEngine
name: Run Rule Engine
description: Dictates whether the Rule Engine should be run after each membership change.
visible: true
required: true
confidential: false
default_value: false
supported_event_types:
- custom_event
supported_runtime_environments:
- unknown
- android
- ios
- tvos
- mobileweb
- roku
- xbox
- firetv
- alexa
- smarttv
supported_system_notification_types: []
max_data_age_hours: -1
SegmentTrackEventRequest:
value:
customerProfileId: URN-GV8294NV
eventType: mySegmentEvent
type: string
eventAttributes:
Language: english
ShippingCountry: DE
ProductClicked: true
attributesInfo:
- name: ProductClicked
type: boolean
SegmentCustomerProfileRequest:
value:
runRuleEngine: false
audiencesChanges:
adds:
- 1
- 2
- 3
deletes:
- 4
- 5
- 6
attributes:
Language: english
ShippingCountry: DE
ProductClicked: true
attributesInfo:
- name: ProductClicked
type: boolean
responses:
BadRequest:
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponseWithStatus'
examples:
default:
value:
StatusCode: 400
Error: No Deployment URL specified
RequestUUID: fd2f7c55-d064-46e1-ab87-a39cb877cd82
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponseWithStatus'
examples:
default:
value:
StatusCode: 401
Error: Missing Session Token
RequestUUID: fd2f7c55-d064-46e1-ab87-a39cb877cd82
NotFound:
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponseWithStatus'
examples:
default:
value:
StatusCode: 404
Error: Not Found
RequestUUID: fd2f7c55-d064-46e1-ab87-a39cb877cd82
AudienceAlreadyExist:
description: The audience with the ID already exists.
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponseWithStatus'
examples:
default:
value:
StatusCode: 409
Error: The audience with the ID '382370BKDB946' already exists
RequestUUID: 80322e41-d7d2-48eb-b6c5-c458e13b4b65
TooManyRequests:
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponseWithStatus'
examples:
default:
value:
StatusCode: 429
Error: Too many requests
RequestUUID: fd2f7c55-d064-46e1-ab87-a39cb877cd82
SegmentTooManyRequestsOrParallel:
description: Rate limit of 60 requests per second exceeded or too many [parallel requests](https://docs.talon.one/docs/dev/tutorials/integrating-talon-one#managing-parallel-requests).
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponseWithStatus'
examples:
default:
value:
StatusCode: 429
Error: Too many requests
RequestUUID: fd2f7c55-d064-46e1-ab87-a39cb877cd82
SegmentTooManyRequests:
description: Rate limit of 60 requests per second exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponseWithStatus'
examples:
default:
value:
StatusCode: 429
Error: Too many requests
RequestUUID: fd2f7c55-d064-46e1-ab87-a39cb877cd82
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: |
To authenticate to use these endpoints, create a Third-party API key in the Campaign Manager:
1. Sign in to the Campaign Manager, and open the [Application](https://docs.talon.one/docs/product/applications/overview) of your choice.
2. Click **Settings** > **Integration API Keys**.
3. Click **Create API Key**.
4. In the **Create API Key** drawer, if you are asked for a key type, select **Production**.
5. In **Key name**, type a name to identify the key.
6. In **Key expiration date**, select a date.
**Tip**: Avoid choosing expiration dates that fall at the end of
the year or during other high-traffic periods.
7. In **Third-party integration**, select **Yes** and the platform to integrate with.
8. Click **Create API Key**, and copy the generated value for use.
You can now use the API key in the `Authorization` HTTP header of your requests, prefixing it with `ApiKey-v1 `:
```
Authorization: ApiKey-v1 dbc644d33aa74d582bd9479c59e16f970fe13bf3
```
ApiKeyBasicAuth:
type: http
scheme: basic
description: |
To authenticate to use these endpoints, create a Third-party API key in the Campaign Manager:
1. Sign in to the Campaign Manager, and open the [Application](https://docs.talon.one/docs/product/applications/overview) of your choice.
2. Click **Settings** > **Integration API Keys**.
3. Click **Create API Key**.
4. In the **Create API Key** drawer, if you are asked for a key type, select **Production**.
5. In **Key name**, type a name to identify the key.
6. In **Key expiration date**, select a date.
**Tip**: Avoid choosing expiration dates that fall at the end of
the year or during other high-traffic periods.
7. In **Third-party integration**, select **Yes** and the platform to integrate with.
8. Click **Create API Key**, and copy the generated value for use.
9. Modify the generated value by prefixing it with `ApiKey-v1 ` and suffixing it with `:`. For example: `ApiKey-v1 :`.
10. Encode this modified value to Base64.
You can now use the API key, prefixing the Base64-encoded string with `Authorization: Basic `:
```
Authorization: Basic YmFzZTY0ZW5vZGV0aGlzcGxlYXNlYXNhcDQzMjE0MTI=
```