openapi: 3.0.1 info: version: '' title: Third-party API reference docs description: | Use the Third-party API to exchange data between Talon.One and one of the supported [technology partners](https://docs.talon.one/docs/dev/technology-partners/overview). For example, use the Braze-specific endpoints from your Braze campaigns to interact with Talon.One. If the CDP or CEP you are using isn't listed here, use the generic [Customer Data Platforms](#tag/Customer-data-platforms) and [Customer Engagement Platform](#tag/Customer-engagement-platforms) endpoints.

All endpoints of this API start with https://integration.talon.one.

You must specify the base URL of your deployment in the headers or parameters.

Looking for a different API?

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