openapi: 3.0.1
servers:
- url: https://integration.talon.one
info:
version: 1.0.0
title: Third-party API reference docs
description: |
Use the Third-party API from [Talon.One's 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.
Are you looking for a different API?
If you need the API to:
- Integrate with Talon.One directly and send real-time data, see [the Integration API reference docs](https://docs.talon.one/integration-api).
- Interact with the Campaign Manager for backoffice operations, see [the Management API reference docs](https://docs.talon.one/management-api).
# Authentication
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: 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: 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.
- name: Selligent
description: |
[Selligent](https://www.selligent.com/) Marketing Cloud is an AI-powered marketing automation platform that helps you make marketing personal, by activating your data to deliver unique, highly relevant experiences to your customers at every moment of interaction, across all channels and devices.
For more information, see [the developer docs](https://docs.talon.one/docs/dev/technology-partners/selligent).
- 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).
paths:
################################
# Braze Integration API Routes #
################################
/braze/referral:
post:
tags:
- Braze
summary: Create referral
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
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.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CouponRequest'
examples:
default:
$ref: '#/components/examples/CouponRequest'
responses:
200:
description: OK
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'
/braze/event:
post:
tags:
- Braze
summary: Track event
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 Integration API Routes #
###################################
/iterable/coupon:
get:
tags:
- Iterable
summary: Create coupon
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).
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
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
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).
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'
####################################
# Selligent Integration API Routes #
####################################
/selligent:
get:
tags:
- Selligent
summary: Create coupon
operationId: selligent/createCoupon
description: |
Create a coupon code in Talon.One. To use it in your Selligent deployment, see [the tutorial](https://docs.talon.one/docs/dev/technology-partners/selligent).
parameters:
- $ref: '#/components/parameters/deployment'
- $ref: '#/components/parameters/campaignId'
- $ref: '#/components/parameters/applicationId'
- $ref: '#/components/parameters/selligentCampaignId'
- $ref: '#/components/parameters/recipientIntegrationId'
- $ref: '#/components/parameters/discountLimit'
- $ref: '#/components/parameters/startDate'
- $ref: '#/components/parameters/expiryDate'
- $ref: '#/components/parameters/usageLimitCoupons'
responses:
200:
description: Response
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/CouponResponse'
- $ref: '#/components/schemas/errorResponseWithStatus'
examples:
success response:
$ref: '#/components/examples/CouponResponse'
error response:
value:
StatusCode: 200
Error: |
malformed url query: campaignID parameter is invalid or is missing
RequestUUID: fd2f7c55-d064-46e1-ab87-a39cb877cd82
401:
$ref: '#/components/responses/Unauthorized'
429:
$ref: '#/components/responses/TooManyRequests'
##################################
# Segment Integration API Routes #
##################################
/segment/customer_profile/{customerProfileId}:
put:
tags:
- Segment
parameters:
- $ref: '#/components/parameters/destinationHostname'
- name: customerProfileId
in: path
description: The integration ID of the customer profile.
required: true
schema:
type: string
summary: Upsert customer profile
operationId: segment/updateCustomerProfile
deprecated: true
description: |
**Important:** 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:**
The audiences must be created first with [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.
required: true
schema:
type: string
summary: Upsert customer profile V2
operationId: segment/updateCustomerProfileV2
deprecated: true
description: |
**Important:** 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.
required: true
schema:
type: string
summary: Update customer profile
operationId: segment/v2/updateCustomerProfile
description: |
Create or update the given customer profile.
**Note:**
- Create all the required attributes and audiences before using this endpoint.
- This endpoint replaces the [Upsert customer profile](#tag/Segment/operation/segment/updateCustomerProfile) and [Upsert customer profile V2](#tag/Segment/operation/segment/updateCustomerProfileV2) endpoints.
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/audiences:
parameters:
- $ref: '#/components/parameters/destinationHostname'
put:
tags:
- Segment
summary: Update audiences in multiple customer profiles
operationId: segment/updateCustomerProfilesAudiences
description: Update the specified audiences for the specified profiles.
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/event:
parameters:
- $ref: '#/components/parameters/destinationHostname'
put:
tags:
- Segment
summary: Track event
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
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:**
- 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
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
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
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
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).
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
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:**
- Create 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.
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 Integration API Routes #
##############################
/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.
required: true
example: URN-GV8294NV
schema:
type: string
summary: Update customer profile
operationId: cdp/updateCustomerProfile
description: |
Update the given customer profile to add or remove audiences.
**Note:** Create all the required attributes and audiences before using this endpoint.
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_profiles/audiences:
parameters:
- $ref: '#/components/parameters/customerDataPlatformName'
- $ref: '#/components/parameters/destinationHostname'
put:
tags:
- Customer data platforms
summary: Update audiences in multiple customer profiles
operationId: cdp/updateCustomerProfilesAudiences
description: Update the specified audiences for the specified profiles.
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/audiences:
parameters:
- $ref: '#/components/parameters/customerDataPlatformName'
- $ref: '#/components/parameters/destinationHostname'
post:
tags:
- Customer data platforms
summary: Create audience
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'
429:
$ref: '#/components/responses/TooManyRequests'
409:
$ref: '#/components/responses/AudienceAlreadyExist'
/cdp/audiences/{audienceId}:
parameters:
- $ref: '#/components/parameters/audienceId'
- $ref: '#/components/parameters/customerDataPlatformName'
- $ref: '#/components/parameters/destinationHostname'
put:
tags:
- Customer data platforms
summary: Update audience
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
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'
###################################
# CEP Integration API Routes #
###################################
/customer_engagement/coupon:
get:
tags:
- Customer engagement platforms
summary: Create coupon
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).
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
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
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).
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'
####################################
# mParticle Integration API Routes #
####################################
/mparticle:
post:
tags:
- mParticle
summary: Send event
operationId: mparticle/sendevent
description: |
Send an mParticle event to Talon.One.
This endpoint supports the following mParticle events:
- `module_registration_request`: A new client signs up for Talon.One in mParticle.
- `audience_subscription_request`: A client adds/deletes/edits an audience in mParticle.
- `event_processing_request`: Talon.One should process events that have been triggered in mParticle.
- `audience_membership_change_request`: Customers are added to/removed from an audience in mParticle.
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'
401:
$ref: '#/components/responses/Unauthorized'
400:
$ref: '#/components/responses/BadRequest'
409:
$ref: '#/components/responses/AudienceAlreadyExist'
429:
$ref: '#/components/responses/TooManyRequests'
components:
parameters:
audienceId:
name: audienceId
in: path
description: The ID of the audience.
required: true
schema:
type: integer
format: int64
example: 4729630
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 deployment.
schema:
type: string
required: true
example: company.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 set 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 loyalty program in Talon.One.
schema:
type: integer
format: int64
required: true
example: 25
selligentCampaignId:
name: selligentCampaignId
in: query
description: Selligent campaign id
required: true
schema:
type: string
example: someCampaignId
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 `.`.
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.
Full URI example: `https://?applicationId=5&.myAttribute1=1234&.myAttribute2=abc`.
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 enpdoint's response that you want to receive.
If omitted, all the fields will be sent to the callback destination URI.
example: effects, customerProfile, customerSession
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
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:
#####################################
# Braze Request and Response Models #
#####################################
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
CouponRequest:
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
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-30T11: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:
langugae: english
CouponResponse:
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 set value of discounts.
example: 100
StartDate:
type: string
format: date-time
example: 2021-09-30T15:35:02.371569+02:00
ExpiryDate:
type: string
format: date-time
example: 2022-02-30T11:00:00.569+02:00
RecipientIntegrationID:
type: string
example: URN-GV8294NV
UsageLimit:
type: integer
format: int64
example: 1
Attributes:
type: object
example:
language: english
#######################################
# Segment Request and Response Models #
#######################################
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.
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'
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' }
#########################################
# mParticle Request and Response Models #
#########################################
ModuleRegistrationRequest:
allOf:
- $ref: '#/components/schemas/mparticleBaseFields'
- $ref: '#/components/schemas/mparticleAccount'
ModuleRegistrationResponse:
allOf:
- $ref: '#/components/schemas/mparticleBaseFields'
- type: object
properties:
name:
type: string
description: Name of our integration.
example: Talon.One
description:
type: string
description: Description of our 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: Version of our 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:
- $ref: '#/components/schemas/mparticleBaseFields'
- $ref: '#/components/schemas/mparticleAccount'
- type: object
properties:
user_profiles:
type: array
description: The list of user profiles.
items:
$ref: '#/components/schemas/mparticleUserProfiles'
AudienceMembershipChangeResponse:
$ref: '#/components/schemas/mparticleBaseFields'
AudienceSubscriptionRequest:
allOf:
- $ref: '#/components/schemas/mparticleBaseFields'
- $ref: '#/components/schemas/mparticleAccount'
- type: object
required:
- audience_id
- audience_name
properties:
audience_id:
type: integer
description: Audience id
example: 29
audience_name:
type: string
description: Audience name
example: Travel audience
action:
description: Audience action
example: add
enum:
- add
- update
- remove
audience_subscription_settings:
type: object
additionalProperties: false
user_attributes:
type: array
items:
$ref: '#/components/schemas/mparticleUserAttribute'
AudienceSubscriptionResponse:
allOf:
- $ref: '#/components/schemas/mparticleBaseFields'
- type: object
properties:
audience_subscription_settings:
type: object
additionalProperties: true
EventProcessingRequest:
allOf:
- $ref: '#/components/schemas/mparticleBaseFields'
- $ref: '#/components/schemas/mparticleAccount'
- $ref: '#/components/schemas/mparticleUserIdentityInt'
- type: object
required:
- mpid
properties:
user_identities:
type: array
items:
$ref: '#/components/schemas/mparticleUserIdentity'
mpid:
type: string
description: mparticle id
example: 6423PSJVY7492
user_attributes:
type: array
items:
$ref: '#/components/schemas/mparticleUserAttribute'
events:
type: array
items:
$ref: '#/components/schemas/mparticleEvent'
EventProcessingResponse:
$ref: '#/components/schemas/mparticleBaseFields'
###############################################
# Reusable models for Requests and Responses #
###############################################
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 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'
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.
New attributes are created automatically. For more information, see [Attributes](https://docs.talon.one/docs/dev/concepts/attributes).
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'
customerProfileID:
type: string
format: string
example: URN-GV8294NV
maxLength: 1000
description: Unique Customer Profile ID.
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'
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: Permissions indicates which identities we require 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: AudienceSubscriptionSettings define client configuration that we require.
properties:
account_settings:
type: array
items:
$ref: '#/components/schemas/mparticleAccountSettings'
audience_subscription_settings:
type: array
items:
$ref: '#/components/schemas/mparticleAudienceSubscriptionSettings'
mparticleAudienceSubscriptionSettings:
type: object
description: AudienceSubscriptionSetting represents a 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: AccountSetting represents 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: 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: EventProcessingRegistration defines our required configuration from the client.
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: mParticle's internal API version.
example: 2.4.0
timestampMS:
type: integer
description: Timestamp of the request (in milliseconds)
example: 1586980879793
mparticleType:
type: string
description: The type of request/event coming from mParticle.
example: module_registration_request
enum:
- module_registration_request
- audience_subscription_request
- event_processing_request
- audience_membership_change_request
mparticleId:
type: string
description: The ID that is set by mParticle to identify this request.
example: dd33f-dd-b3fb3-def0000
mparticleUserIdentity:
type: object
properties:
type:
type: string
enum:
- email
- customerId
- mpid
- customer
example: customerId
encoding:
type: string
example: raw
required:
type: boolean
example: true
value:
type: string
example: ''
mparticleUserIdentityInt:
type: integer
properties:
type:
type: string
example: RGV6358UYY
mparticleAudience:
type: object
required:
- action
- audience_id
- audience_name
properties:
audience_id:
type: integer
description: Audience id
example: 234
audience_name:
type: string
description: Audience name
example: Travel audience
action:
$ref: '#/components/schemas/actionMembershipChange'
audience_subscription_settings:
type: object
description: Settings contains custom configuration per audience.
additionalProperties: true
user_attributes:
type: array
items:
$ref: '#/components/schemas/mparticleUserAttribute'
actionMembershipChange:
type: string
description: Audience action
example: add
enum:
- add
- delete
- attribute_update
mparticleUserAttribute:
type: object
properties:
key:
type: string
example: country
value:
example: DE
action:
type: string
example: upsert
enum:
- upsert
- delete
mparticleAccount:
type: object
properties:
account:
type: object
properties:
account_id:
type: integer
description: mParticle account ID
example: 1234567
account_settings:
type: object
required:
- apiKey
- deploymentURL
- userIdField
properties:
apiKey:
type: string
description: mParticle api key
example: someapikey
deploymentURL:
type: string
description: The base URL of your Talon.One deployment
example: mycompany.europe-west1.talon.one
userIdField:
type: string
description: how to identify customer profiles
example: email
enum:
- email
- customerId
- mpid
runRuleEngine:
type: boolean
description: whether to run the Rule Engine
example: false
mparticleEvent:
type: object
required:
- name
- type
- session_id
properties:
name:
type: string
description: The name of the event
example: isDogLover
type:
type: string
description: The type of the event
enum:
- custom_event
example: custom_event
session_id:
type: integer
description: The session ID of the event
example: 109
id:
type: string
description: Unique id for this entity
example: 342PV86540CR
source_id:
type: string
description: The source ID of the event
example: B5720CRPPN7
attributes:
type: array
items:
$ref: '#/components/schemas/mparticleUserAttribute'
mparticleBaseFields:
type: object
required:
- type
properties:
type:
$ref: '#/components/schemas/mparticleType'
id:
$ref: '#/components/schemas/mparticleId'
timestamp_ms:
$ref: '#/components/schemas/timestampMS'
firehose_version:
$ref: '#/components/schemas/firehoseVersion'
mparticleUserProfiles:
type: object
required:
- mpid
properties:
mpid:
type: string
description: mParticle ID
example: c314b207-f3ae-4d21-9ae7-5983af40876a
audiences:
type: array
items:
$ref: '#/components/schemas/mparticleAudience'
user_identities:
type: array
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.
additionalProperties: true
example:
"ShippingCity": "Berlin"
cartItem:
type: object
required: [ name, sku, quantity, price ]
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/campaigns/campaign-evaluation#flattened-cart-items),
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 item.
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
required: [ price ]
properties:
price:
title: Price of 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"
# these inherited properties are intentionally made required here so
# that we can validate they are present (but possibly empty) in API responses
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-97T35: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 Status
type: boolean
example: false
description: |
Defines the type of reservation:
- `true`: The reservation is a soft reservation. Any customer can use the coupon. This is done via the [Create coupon reservation endpoint](/integration-api#operation/createCouponReservation).
- `false`: The reservation is a hard reservation. Only the associated customer (`recipientIntegrationId`) can use the coupon. This is done via the Campaign Manager when you create a coupon for a given `recipientIntegrationId`, the [Create coupons endpoint](/management-api#operation/createCoupons) or [Create coupons for multiple recipients endpoint](/management-api#operation/createCouponsForMultipleRecipients).
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
# The campaign entity is intentionally left out of this enum, as for the moment
# it is always implicitly added on the Backend for all limit configurations.
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.
########################
# Error Response Model #
########################
errorResponseWithStatus:
type: object
properties:
StatusCode:
type: integer
description: The error code
example: 404
Error:
type: string
example: Not found
RequestUUID:
type: string
example: 51fad142-3563-4fe2-b4aa-41ab20be31d911
examples:
CouponRequest:
value:
deploymentUrl: mycompany.europe-west1.talon.one
applicationId: 398
campaignId: 5671
identifier: test-coupon
usageLimit: 4
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-####
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
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: deadb33f-dead-b33f-b33f-deadbeef0000
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:
custuomField: 1
user_attributes:
- key: email
value: test@email.com
AudienceMembershipChangeRequest:
value:
type: audience_membership_change_request
id: deadb33f-dead-b33f-b33f-deadbeef0000
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: customerId
value: customer3
action: upsert
user_identities:
- type: customerId
encoding: raw
required: true
value: ''
EventProcessingRequest:
value:
type: event_processing_request
id: deadb33f-dead-b33f-b33f-deadbeef0000
timestamp_ms: 1586980879793
firehose_version: 2.4.0
account:
account_id: 1234567
account_settings:
apiKey: someapikey
deploymentURL: mycompany.europe-west1.talon.one
userIdField: customerId
user_identities:
- type: customerId
encoding: raw
required: true
value: ''
mpid: c314b207-f3ae-4d21-9ae7-5983af40876a
events:
- name: isDogLover
type: custom_event
session_id: 109
ModuleRegistrationRequest:
value:
type: module_registration_request
id: deadb33f-dead-b33f-b33f-deadbeef0000
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: deadb33f-dead-b33f-b33f-deadbeef0000
timestamp_ms: 1586980879793
firehose_version: 2.4.0
AudienceSubscriptionResponse:
value:
type: audience_subscription_response
id: deadb33f-dead-b33f-b33f-deadbeef0000
timestamp_ms: 1586980879793
firehose_version: 2.4.0
AudienceMembershipChangeResponse:
value:
type: audience_membership_change_response
id: deadb33f-dead-b33f-b33f-deadbeef0000
timestamp_ms: 1586980879793
firehose_version: 2.4.0
ModuleRegistrationResponse:
value:
type: module_registration_response
id: deadb33f-dead-b33f-b33f-deadbeef0000
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: ''
- type: customer
encoding: raw
required: false
value: ''
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'
SegmentTooManyRequests:
description: Rate limit of 60 requests per second exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponseWithStatus'
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: |
To authenticate in order to use these endpoints, generate an API key in the Campaign Manager:
1. Log on to the Campaign Manager and open the Application of your choice, or create one.
1. Click **Settings** > **Developer settings**.
1. Click **Create API Key**.
1. Give it a title.
1. For **Do you want to use this API Key with a 3rd party service?**, select **Yes** and choose the platform to integrate with.
1. Set an expiration date. then click **Create API Key**.
You can now use the API key in the `Authorization` HTTP header of your requests, prefixing it with `ApiKey-v1`:
```
Authorization: ApiKey-v1 dbc644d33aa74d582bd9479c59e16f970fe13bf3
```
security:
- ApiKeyAuth: []