Talon.One Emarsys API

openapi: 3.2.0
info:
  version: ''
  title: Third-party Emarsys API
  description: "Use the Third-party API to exchange data between Talon.One and one of the supported [technology partners](https://docs.talon.one/docs/dev/technology-partners/overview).\n\nFor example, use the Braze-specific endpoints from your Braze campaigns to interact with Talon.One.\n\nIf the CDP or CEP you are using isn't listed here, use the generic\n[Customer Data Platforms](#tag/Customer-data-platforms) and [Customer Engagement Platform](#tag/Customer-engagement-platforms) endpoints.\n\n> [!note] \n> All endpoints of this API start with `https://integration.talon.one`.\n> You must specify the base URL of your deployment in the headers or parameters.\n\n> [!note] **Are you looking for a different API?**\n> - To implement use cases that aren't covered by the Third-party API, see the [Integration API](https://docs.talon.one/management-api).\n> - To interact with the Campaign Manager for back-office operations, see the [Management API](https://docs.talon.one/management-api).\n"
servers:
- url: https://integration.talon.one
security:
- ApiKeyAuth: []
tags:
- 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.

    '
paths:
  /emarsys/customer_profiles/coupons:
    post:
      security:
      - ApiKeyBasicAuth: []
      tags:
      - Emarsys
      summary: Get coupon (Emarsys)
      operationId: emarsys/getCoupon
      description: 'Retrieve a coupon code from Talon.One.

        '
      parameters:
      - $ref: '#/components/parameters/deployment'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmarsysCouponRequest'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmarsysCouponResponse'
              examples:
                default:
                  $ref: '#/components/examples/EmarsysCouponResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /emarsys/loyalty_programs/profile/balance:
    post:
      security:
      - ApiKeyBasicAuth: []
      tags:
      - Emarsys
      summary: Get loyalty balance (Emarsys)
      operationId: emarsys/getLoyaltyProgramBalance
      description: 'Retrieve the loyalty balance of a customer profile from Talon.One.


        This endpoint only works with [profile-based](https://docs.talon.one/docs/product/loyalty-programs/profile-based/profile-based-overview) loyalty programs.

        '
      parameters:
      - $ref: '#/components/parameters/deployment'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmarsysLoyaltyBalanceRequest'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmarsysLoyaltyBalanceResponse'
              examples:
                default:
                  $ref: '#/components/examples/EmarsysLoyaltyBalanceResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /emarsys/customer_profiles/audiences:
    post:
      security:
      - ApiKeyBasicAuth: []
      tags:
      - Emarsys
      summary: Update audiences in multiple customer profiles (Emarsys)
      operationId: emarsys/v2/updateCustomerProfilesAudiences
      description: 'Update the specified audiences for the specified profiles. To identify the audience, you can use its ID in the third-party integration.


        If a provided customer profile doesn''t exist, it will be created.

        '
      parameters:
      - $ref: '#/components/parameters/deployment'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmarsysCustomerProfilesAudiencesRequest'
            examples:
              default:
                $ref: '#/components/examples/EmarsysCustomerProfilesAudiencesRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmarsysUpdateAudiencesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  responses:
    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
    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
    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
    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
  parameters:
    deployment:
      name: deployment
      in: query
      description: The base URL of your Talon.One deployment.
      schema:
        type: string
      required: true
      example: mycompany.europe-west1.talon.one
  examples:
    EmarsysLoyaltyBalanceResponse:
      value:
        content:
        - integrationId: test-user-4zoj1c
          loyaltyProgramId: '8431'
          activeBalance: 100
          pendingBalance: 0
          expiredBalance: 0
          totalBalance: 100
    EmarsysCustomerProfilesAudiencesRequest:
      value:
        parameters:
        - customerProfileId: customer123
          audienceId: 1
          actionType: add
    EmarsysCouponResponse:
      value:
        content:
        - integrationId: test-user-4zoj1c
          campaignId: '8431'
          id: 26443683
          created: '2024-01-03T11:28:25.648154Z'
          value: QQ4R-C3BQ
          usageLimit: 1
          usageCounter: 0
          recipientIntegrationId: test-user-4zoj1c
          reservation: false
          batchId: qndflqqd
          profileRedemptionCount: 0
          state: active
  schemas:
    errorResponseWithStatus:
      type: object
      properties:
        StatusCode:
          type: integer
          description: The error code.
          example: 400
        Error:
          type: string
          example: Bad request
        RequestUUID:
          type: string
          example: 51fad142-3563-4fe2-b4aa-41ab20be31d911
    EmarsysCustomerProfilesAudiencesRequest:
      type: object
      required:
      - parameters
      properties:
        parameters:
          type: array
          maxItems: 1000
          items:
            type: object
            required:
            - customerProfileId
            - audienceId
            - actionType
            properties:
              customerProfileId:
                type: string
                description: The integration ID of the customer profile.
                example: customer123
              audienceId:
                type: string
                description: The internal ID of the audience. Must be a string containing the numeric ID of an existing audience.
                example: '1'
              actionType:
                type: string
                description: The action to perform.
                enum:
                - add
                - delete
                example: add
    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
    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
    EmarsysUpdateAudiencesResponse:
      type: object
      properties:
        content:
          type: array
          items:
            type: object
            properties:
              customerProfileId:
                type: string
                example: profile-1
              audienceId:
                type: string
                example: '1'
              actionType:
                type: string
                example: add
    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
    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.
  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:\n\n1. Sign in to the Campaign Manager, and open the [Application](https://docs.talon.one/docs/product/applications/overview) of your choice.\n2. Click **Settings** > **Integration API Keys**.\n3. Click **Create API Key**.\n4. In the **Create API Key** drawer, if you are asked for a key type, select **Production**.\n5. In **Key name**, type a name to identify the key.\n6. In **Key expiration date**, select a date.\n   \n   **Tip**: Avoid choosing expiration dates that fall at the end of\n   the year or during other high-traffic periods.\n\n7. In **Third-party integration**, select **Yes** and the platform to integrate with.\n8. Click **Create API Key**, and copy the generated value for use.\n\nYou can now use the API key in the `Authorization` HTTP header of your requests, prefixing it with `ApiKey-v1 `:\n\n```\nAuthorization: ApiKey-v1 dbc644d33aa74d582bd9479c59e16f970fe13bf3\n```\n"
    ApiKeyBasicAuth:
      type: http
      scheme: basic
      description: "To authenticate to use these endpoints, create a Third-party API key in the Campaign Manager:\n\n1. Sign in to the Campaign Manager, and open the [Application](https://docs.talon.one/docs/product/applications/overview) of your choice.\n2. Click **Settings** > **Integration API Keys**.\n3. Click **Create API Key**.\n4. In the **Create API Key** drawer, if you are asked for a key type, select **Production**.\n5. In **Key name**, type a name to identify the key.\n6. In **Key expiration date**, select a date.\n\n   **Tip**: Avoid choosing expiration dates that fall at the end of\n   the year or during other high-traffic periods.\n   \n7. In **Third-party integration**, select **Yes** and the platform to integrate with.\n8. Click **Create API Key**, and copy the generated value for use.\n9. Modify the generated value by prefixing it with `ApiKey-v1 ` and suffixing it with `:`. For example: `ApiKey-v1 <generated-api-key>:`.\n10. Encode this modified value to Base64.\n\nYou can now use the API key, prefixing the Base64-encoded string with `Authorization: Basic `:\n\n```\nAuthorization: Basic YmFzZTY0ZW5vZGV0aGlzcGxlYXNlYXNhcDQzMjE0MTI=\n```\n"