Talon.One Achievements API

openapi: 3.2.0
info:
  title: Talon One Achievements API
  version: ''
  description: 'Operations tagged Achievements across 2 of this provider''s published API definitions: talon-one-integration-api-openapi.yml, talon-one-management-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://yourbaseurl.talon.one
tags:
- name: Achievements
  description: 'Represents achievements that reward a customer profile for performing a number of specific actions or reaching a transactional milestone within a defined period.


    For example, you can use achievements to award your customers when they purchase five cups of coffee in one week or when they purchase items worth $3000 in three months.

    '
paths:
  /v1/customer_profiles/{integrationId}/achievements:
    get:
      operationId: getCustomerAchievements
      summary: List customer's available achievements
      description: 'Retrieve all the achievements available to a given customer and their progress in them.

        '
      security:
      - api_key_v1: []
      tags:
      - Achievements
      parameters:
      - in: path
        required: true
        name: integrationId
        description: 'The integration identifier for this customer profile. Must be:

          - Unique within the deployment.

          - Stable for the customer. Do not use an ID that the customer can update themselves. For example, you can use a database ID.


          Once set, you cannot update this identifier.

          '
        example: customer1
        schema:
          type: string
      - name: campaignIds
        in: query
        required: false
        description: 'Filter by one or more Campaign IDs, separated by a comma.


          **Note:** If no campaigns are specified, data for all the campaigns in the Application is returned.

          '
        example:
        - '11'
        - '20'
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: achievementIds
        in: query
        required: false
        description: 'Filter by one or more Achievement IDs, separated by a comma.


          **Note:** If no achievements are specified, data for all the achievements in the Application is returned.

          '
        example:
        - '11'
        - '20'
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: achievementStatus
        in: query
        required: false
        description: 'Filter by status of the achievement.


          **Note:** If the achievement status is not specified, only data for all active achievements in the Application is returned.

          '
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - active
            - scheduled
        example:
        - active
        - scheduled
      - name: currentProgressStatus
        in: query
        required: false
        description: 'Filter by customer progress status in the achievement.

          '
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - inprogress
            - completed
            - not_started
        example:
        - inprogress
        - completed
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/skip'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - totalResultSize
                - data
                properties:
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AchievementStatusEntry'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
    servers:
    - url: https://yourbaseurl.talon.one
  /v1/customer_profiles/{integrationId}/achievements/{achievementId}:
    get:
      operationId: getCustomerAchievementHistory
      summary: List customer's achievement history
      description: 'Retrieve all progress history of a given customer in the given achievement.

        '
      security:
      - api_key_v1: []
      tags:
      - Achievements
      parameters:
      - in: path
        required: true
        name: integrationId
        description: 'The integration identifier for this customer profile. Must be:

          - Unique within the deployment.

          - Stable for the customer. Do not use an ID that the customer can update themselves. For example, you can use a database ID.


          Once set, you cannot update this identifier.

          '
        example: customer1
        schema:
          type: string
      - in: path
        required: true
        name: achievementId
        description: 'The achievement identifier.

          '
        example: 321
        schema:
          type: integer
      - name: progressStatus
        in: query
        required: false
        description: 'Filter by customer progress status in the achievement.

          '
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - inprogress
            - completed
            - expired
        example:
        - inprogress
        - completed
      - name: startDate
        description: Timestamp that filters the results to only contain achievements created on or after the start date.
        in: query
        example: '2024-05-29T15:04:05+07:00'
        schema:
          type: string
          format: date-time
      - name: endDate
        description: Timestamp that filters the results to only contain achievements created before or on the end date.
        in: query
        example: '2024-05-29T15:04:05+07:00'
        schema:
          type: string
          format: date-time
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/skip'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - totalResultSize
                - data
                properties:
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AchievementProgress'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
    servers:
    - url: https://yourbaseurl.talon.one
  /v1/applications/{applicationId}/campaigns/{campaignId}/achievements:
    post:
      deprecated: true
      operationId: createAchievement
      summary: Create achievement
      description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.


        Create a new achievement in a specific campaign.'
      tags:
      - Achievements
      parameters:
      - $ref: '#/components/parameters/applicationId'
      - $ref: '#/components/parameters/campaignId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAchievement'
        description: body
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Achievement'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '409':
          description: Conflict. An achievement with this name or title already exists.
      security:
      - manager_auth: []
      - management_key: []
    get:
      deprecated: true
      operationId: listAchievements
      summary: List achievements
      description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.


        List all the achievements for a specific campaign.'
      tags:
      - Achievements
      parameters:
      - $ref: '#/components/parameters/applicationId'
      - $ref: '#/components/parameters/campaignId'
      - name: pageSize
        in: query
        required: false
        description: The number of items in the response.
        example: 50
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 50
      - $ref: '#/components/parameters/skip'
      - name: title
        in: query
        description: 'Filter by the display name for the achievement in the campaign manager.


          **Note**: If no `title` is provided, all the achievements from the campaign are returned.

          '
        example: achievement1
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  hasMore:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Achievement'
      security:
      - manager_auth: []
      - management_key: []
    servers:
    - url: https://yourbaseurl.talon.one
  /v1/applications/{applicationId}/campaigns/{campaignId}/achievements/{achievementId}:
    get:
      deprecated: true
      operationId: getAchievement
      summary: Get achievement
      description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.


        Get the details of a specific achievement.'
      tags:
      - Achievements
      parameters:
      - $ref: '#/components/parameters/applicationId'
      - $ref: '#/components/parameters/campaignId'
      - name: achievementId
        in: path
        description: The ID of the achievement. You can get this ID with the [List achievement](https://docs.talon.one/management-api#tag/Achievements/operation/listAchievements) endpoint.
        example: 45
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Achievement'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
      security:
      - manager_auth: []
      - management_key: []
    put:
      deprecated: true
      operationId: updateAchievement
      summary: Update achievement
      description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.


        Update the details of a specific achievement.'
      tags:
      - Achievements
      parameters:
      - $ref: '#/components/parameters/applicationId'
      - $ref: '#/components/parameters/campaignId'
      - name: achievementId
        in: path
        description: The ID of the achievement. You can get this ID with the [List achievement](https://docs.talon.one/management-api#tag/Achievements/operation/listAchievements) endpoint.
        example: 45
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAchievement'
        description: body
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Achievement'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
      security:
      - manager_auth: []
      - management_key: []
    delete:
      deprecated: true
      operationId: deleteAchievement
      summary: Delete achievement
      description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.


        Delete the specified achievement.'
      tags:
      - Achievements
      parameters:
      - $ref: '#/components/parameters/applicationId'
      - $ref: '#/components/parameters/campaignId'
      - name: achievementId
        in: path
        description: The ID of the achievement. You can get this ID with the [List achievement](https://docs.talon.one/management-api#tag/Achievements/operation/listAchievements) endpoint.
        example: 45
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: No Content
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
      security:
      - manager_auth: []
      - management_key: []
    servers:
    - url: https://yourbaseurl.talon.one
  /v1/applications/{applicationId}/campaigns/{campaignId}/achievements/{achievementId}/export:
    get:
      deprecated: true
      operationId: exportAchievements
      summary: Export achievement customer data
      description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.


        Download a CSV file containing a list of all the customers who have participated in and are currently participating in the given achievement.


        The CSV file contains the following columns:

        - `profileIntegrationID`: The integration ID of the customer profile participating in the achievement.

        - `title`: The display name of the achievement in the Campaign Manager.

        - `target`: The required number of actions or the transactional milestone to complete the achievement.

        - `progress`: The current progress of the customer in the achievement.

        - `status`: The status of the achievement. Can be one of: [''inprogress'', ''completed'', ''expired''].

        - `startDate`: The date on which the customer profile started the achievement in RFC3339.

        - `endDate`: The date on which the achievement ends and resets for the customer profile in RFC3339.

        - `completionDate`: The date on which the customer profile completed the achievement in RFC3339.

        '
      tags:
      - Achievements
      parameters:
      - $ref: '#/components/parameters/applicationId'
      - $ref: '#/components/parameters/campaignId'
      - name: achievementId
        in: path
        description: The ID of the achievement. You can get this ID with the [List achievement](https://docs.talon.one/management-api#tag/Achievements/operation/listAchievements) endpoint.
        example: 45
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/csv:
              schema:
                type: string
                format: csv
              examples:
                response:
                  value: 'profileIntegrationID,title,target,progress,status,startDate,endDate,completionDate

                    user1231,CoffeeFree10Orders,10.00,5,inprogress,2023-12-10T11:42:25+01:00,2024-01-10T11:42:25+01:00,

                    user341,CoffeeFree10Orders,10.00,10,completed,2023-12-10T11:42:25+01:00,2024-01-10T11:42:25+01:00,2023-12-20T10:24:34+01:00

                    '
        '400':
          description: Bad request
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '401':
          description: Unauthorized
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '404':
          description: Not found
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
      security:
      - manager_auth: []
      - management_key: []
    servers:
    - url: https://yourbaseurl.talon.one
  /v2/achievements:
    get:
      operationId: listAchievementsV2
      summary: List achievements
      description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.


        List all achievements.

        '
      tags:
      - Achievements
      parameters:
      - name: pageSize
        in: query
        required: false
        description: The number of items in the response.
        example: 50
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 50
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/sort'
      - name: title
        in: query
        description: Filter by the display name of the achievement.
        example: achievement1
        required: false
        schema:
          type: string
      - name: applicationId
        in: query
        description: Filter by the ID of an Application connected to the achievement.
        example: 42
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  hasMore:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AchievementV2'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
      security:
      - manager_auth: []
      - management_key: []
    post:
      operationId: createAchievementV2
      summary: Create achievement
      description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.


        Create a new account-level achievement.'
      tags:
      - Achievements
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAchievementV2'
        description: body
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AchievementV2'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '409':
          description: Conflict. An achievement with this name already exists.
      security:
      - manager_auth: []
      - management_key: []
    servers:
    - url: https://yourbaseurl.talon.one
  /v2/achievements/{achievementId}:
    get:
      operationId: getAchievementV2
      summary: Get achievement
      description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.


        Retrieve the details of a specific achievement.'
      tags:
      - Achievements
      parameters:
      - name: achievementId
        in: path
        required: true
        description: 'The ID of the achievement.  You can get this ID with the [List achievement](https://docs.talon.one/management-api#tag/Achievements/operation/listAchievementsV2) endpoint.

          '
        example: 45
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AchievementV2'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
      security:
      - manager_auth: []
      - management_key: []
    put:
      operationId: updateAchievementV2
      summary: Update achievement
      description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.


        Update the details of a specific achievement.'
      tags:
      - Achievements
      parameters:
      - name: achievementId
        in: path
        required: true
        description: The ID of the achievement. You can get this ID with the [List achievement](https://docs.talon.one/management-api#tag/Achievements/operation/listAchievementsV2) endpoint.
        example: 45
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAchievementV2'
        description: body
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AchievementV2'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
      security:
      - manager_auth: []
      - management_key: []
    delete:
      operationId: deleteAchievementV2
      summary: Delete achievement
      description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.


        Delete a specific achievement.'
      tags:
      - Achievements
      parameters:
      - name: achievementId
        in: path
        required: true
        description: The ID of the achievement. You can get this ID with the [List achievement](https://docs.talon.one/management-api#tag/Achievements/operation/listAchievementsV2) endpoint.
        example: 45
        schema:
          type: integer
      responses:
        '204':
          description: No Content
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
      security:
      - manager_auth: []
      - management_key: []
    servers:
    - url: https://yourbaseurl.talon.one
  /v2/achievements/{achievementId}/export:
    get:
      operationId: exportAchievementV2
      summary: Export achievement customer data
      description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.


        Download a CSV file containing a list of all the customers who have participated in and are currently participating in the given achievement.


        The CSV file contains the following columns:

        - `profileIntegrationID`: The integration ID of the customer profile participating in the achievement.

        - `title`: The display name of the achievement in the Campaign Manager.

        - `target`: The required number of actions or the transactional milestone to complete the achievement.

        - `progress`: The current progress of the customer in the achievement.

        - `status`: The status of the achievement. Can be one of: [''inprogress'', ''completed'', ''expired''].

        - `startDate`: The date on which the customer profile started the achievement in RFC3339.

        - `endDate`: The date on which the achievement ends and resets for the customer profile in RFC3339.

        - `completionDate`: The date on which the customer profile completed the achievement in RFC3339.

        '
      tags:
      - Achievements
      parameters:
      - name: achievementId
        in: path
        description: The ID of the achievement. You can get this ID with the [List achievements](https://docs.talon.one/management-api#tag/Achievements/operation/listAchievementsV2) endpoint.
        example: 45
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/csv:
              schema:
                type: string
                format: csv
              examples:
                response:
                  value: 'profileIntegrationID,title,target,progress,status,startDate,endDate,completionDate

                    user1231,CoffeeFree10Orders,10.00,5,inprogress,2023-12-10T11:42:25+01:00,2024-01-10T11:42:25+01:00,

                    user341,CoffeeFree10Orders,10.00,10,completed,2023-12-10T11:42:25+01:00,2024-01-10T11:42:25+01:00,2023-12-20T10:24:34+01:00

                    '
        '400':
          description: Bad request
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '401':
          description: Unauthorized
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '404':
          description: Not found
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
      security:
      - manager_auth: []
      - management_key: []
    servers:
    - url: https://yourbaseurl.talon.one
  /v1/applications/{applicationId}/achievement_progress/{integrationId}:
    get:
      operationId: getCustomerProfileAchievementProgress
      summary: List customer achievements
      description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.


        For the given customer profile, list all the achievements that match your filter criteria.

        '
      tags:
      - Achievements
      parameters:
      - $ref: '#/components/parameters/applicationId'
      - in: path
        required: true
        name: integrationId
        description: 'The integration identifier for this customer profile. Must be:

          - Unique within the deployment.

          - Stable for the customer. Do not use an ID that the customer can update themselves. For example, you can use a database ID.


          Once set, you cannot update this identifier.

          '
        example: customer1
        schema:
          type: string
      - name: pageSize
        in: query
        required: false
        description: The number of items in the response.
        example: 50
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 50
      - $ref: '#/components/parameters/skip'
      - name: achievementId
        in: query
        description: The ID of the achievement. You can get this ID with the [List achievement](https://docs.talon.one/management-api#tag/Achievements/operation/listAchievements) endpoint.
        example: 41
        required: false
        schema:
          type: integer
      - name: title
        in: query
        required: false
        description: Filter results by the `title` of an achievement.
        example: achievement1
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - hasMore
                - data
                properties:
                  hasMore:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AchievementProgressWithDefinition'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
      security:
      - manager_auth: []
      - management_key: []
    servers:
    - url: https://yourbaseurl.talon.one
components:
  schemas:
    AchievementSta

# --- truncated at 32 KB (57 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/talon-one/refs/heads/main/openapi/talon-one-achievements-api-openapi.yml