Talon.One Giveaways API

openapi: 3.2.0
info:
  title: Management Giveaways API
  version: ''
  description: 'The Management API allows you to programmatically do what the Campaign Manager

    does.'
servers:
- url: https://yourbaseurl.talon.one
security:
- manager_auth: []
- management_key: []
tags:
- name: Giveaways
  description: 'Represents a program that rewards customers with giveaways, such as free gift cards.


    See the docs.'
paths:
  /v1/giveaways/pools/{poolId}/import:
    post:
      operationId: importPoolGiveaways
      summary: Import giveaway codes into a giveaway pool
      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.


        Upload a CSV file containing the giveaway codes that should be created. Send

        the file as multipart data.


        The CSV file contains the following columns:


        - `code` (required): The code of your giveaway, for instance, a gift card redemption code.

        - `startdate`: The start date in RFC3339 of the code redemption period.

        - `enddate`: The last date in RFC3339 of the code redemption period.

        - `attributes`: A JSON object describing _custom_ giveaway attribute names and their values, enclosed with double quotation marks.


        For example, if you created a custom attribute

        called `provider` associated with the giveaway entity, the object in the CSV file, when opened in a text editor, must be: `"{"provider": "myPartnerCompany"}"`.


        The `startdate` and `enddate` have nothing to do with the _validity_ of the

        codes. They are only used by the Rule Engine to award the codes or not.


        You can use the time zone setting of your choice. The values are converted

        to UTC internally by Talon.One.


        > [!note] **Note**

        > - We recommend limiting your file size to 500MB.

        > - You can import the same code multiple times. Duplicate codes are treated and distributed to customers as unique codes.


        ## Example


        ```text

        code,startdate,enddate,attributes

        GIVEAWAY1,2020-11-10T23:00:00Z,2022-11-11T23:00:00Z,"{""provider"":

        ""Amazon""}"

        GIVEAWAY2,2020-11-10T23:00:00Z,2022-11-11T23:00:00Z,"{""provider"":

        ""Amazon""}"

        GIVEAWAY3,2021-01-10T23:00:00Z,2022-11-11T23:00:00Z,"{""provider"":

        ""Aliexpress""}"

        ```'
      tags:
      - Giveaways
      parameters:
      - name: poolId
        description: The ID of the pool. You can find it in the Campaign Manager, in the **Giveaways** section.
        in: path
        example: 8
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                upFile:
                  description: The CSV file containing the data that is being imported.
                  type: string
                  format: binary
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Import'
  /v1/giveaways/pools/{poolId}/export:
    get:
      operationId: exportPoolGiveaways
      summary: Export giveaway codes of a giveaway pool
      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 the giveaway codes of a specific giveaway

        pool.


        > [!tip] If the exported CSV file is too large to view, you can

        > split it into multiple files.


        The CSV file contains the following columns:


        - `id`: The internal ID of the giveaway.

        - `poolid`: The internal ID of the giveaway pool.

        - `code`: The giveaway code.

        - `startdate`: The validity start date in RFC3339 of the giveaway (can be empty).

        - `enddate`: The validity end date in RFC3339 of the giveaway (can be empty).

        - `attributes`: Any custom attributes associated with the giveaway code (can be empty).

        - `used`: An indication of whether the giveaway is already awarded.

        - `importid`: The ID of the import which created the giveaway.

        - `created`: The creation time of the giveaway code.

        - `profileintegrationid`: The third-party integration ID of the customer

        profile that was awarded the giveaway. Can be empty if the giveaway was not

        awarded.

        - `profileid`: The internal ID of the customer profile that was awarded the

        giveaway. Can be empty if the giveaway was not awarded or an internal ID

        does not exist.'
      tags:
      - Giveaways
      parameters:
      - name: poolId
        description: The ID of the pool. You can find it in the Campaign Manager, in the **Giveaways** section.
        in: path
        example: 8
        required: true
        schema:
          type: integer
      - name: createdBefore
        description: Timestamp that filters the results to only contain giveaways created before this date. Must be an RFC3339 timestamp string.
        in: query
        example: '2024-05-29T15:04:05+07:00'
        schema:
          type: string
          format: date-time
      - name: createdAfter
        description: Timestamp that filters the results to only contain giveaways created after this date. Must be an RFC3339 timestamp string.
        in: query
        example: '2024-05-29T15:04:05+07:00'
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: OK
          content:
            application/csv:
              schema:
                type: string
                format: csv
              examples:
                response:
                  value: 'id,poolid,code,startdate,enddate,attributes,used,importid,created,profileintegrationid,profileid

                    1,7,af18bc3839799451fb6d6b6467cf4c25e,2023-04-11T12:47:47Z,2024-04-11T12:47:47Z,"{""attribute"": ""value""}",true,2,2023-04-11T12:47:47Z,R195412,35

                    '
        '400':
          description: Bad request
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
components:
  schemas:
    AccountEntity:
      type: object
      required:
      - accountId
      properties:
        accountId:
          type: integer
          description: The ID of the account that owns this entity.
          example: 3886
    Entity:
      type: object
      required:
      - id
      - created
      properties:
        id:
          type: integer
          description: The internal ID of this entity.
          example: 6
        created:
          type: string
          format: date-time
          description: The time this entity was created.
          example: '2020-06-10T09:05:27.993483Z'
    ErrorResponseWithStatus:
      type: object
      properties:
        message:
          type: string
        errors:
          type: array
          description: An array of individual problems encountered during the request.
          items:
            $ref: '#/components/schemas/APIError'
        StatusCode:
          type: integer
          description: The error code
    APIError:
      type: object
      required:
      - source
      - title
      properties:
        title:
          type: string
          description: Short description of the problem.
        details:
          type: string
          description: Longer description of this specific instance of the problem.
        source:
          $ref: '#/components/schemas/ErrorSource'
    UserEntity:
      type: object
      required:
      - userId
      properties:
        userId:
          type: integer
          description: The ID of the user associated with this entity.
          example: 388
    ErrorSource:
      type: object
      description: 'The source of the current error, exactly one of `pointer`, `parameter` or `line` will be defined.

        '
      properties:
        pointer:
          type: string
          description: Pointer to the path in the payload that caused this error.
        parameter:
          type: string
          description: Query parameter that caused this error.
        line:
          type: string
          description: Line number in uploaded multipart file that caused this error. 'N/A' if unknown.
        resource:
          type: string
          description: Pointer to the resource that caused this error.
    Import:
      allOf:
      - $ref: '#/components/schemas/Entity'
      - $ref: '#/components/schemas/AccountEntity'
      - $ref: '#/components/schemas/UserEntity'
      - type: object
        required:
        - amount
        - entity
        properties:
          entity:
            type: string
            example: AttributeAllowedList
            description: 'The name of the entity that was imported.

              '
          amount:
            type: integer
            minimum: 0
            example: 10
            description: The number of values that were imported.
  securitySchemes:
    manager_auth:
      type: apiKey
      name: Authorization
      in: header
      description: 'This authentication scheme relies on a bearer token that you can use to

        access all the endpoints of the Management API.


        To create the token:


        1. Get a bearer token by calling the

        [createSession](#tag/Sessions/operation/createSession) endpoint.

        1. Use the `token` property of the response in the HTTP header of your

        next queries: `Authorization: Bearer $TOKEN`.


        A token is valid for 3 months. In accordance with best pratices, use

        your generated token for all your API requests. Do **not** regenerate a token for each

        request.


        > [!note]

        > We recommend that you use a [Management API key](https://docs.talon.one/management-api#section/Authentication/management_key)

        > instead of a bearer token.

        '
    management_key:
      type: apiKey
      name: Authorization
      in: header
      description: "The API key authentication gives you access to the endpoints selected by\nthe admin who created the key.\n\nUsing an API key is the recommended authentication method.\n\nThe key must be generated by an admin and given to the developer that\nrequires it:\n\n1. Sign in to the Campaign Manager and click **Account** > **Tools** >\n**Management API Keys**.\n1. Click **Create Key** and give it a name.\n1. Set an expiration date.\n   **Tip**: Avoid choosing expiration dates that fall at the end of the year or during other high-traffic periods.\n1. Choose the endpoints the key should give access to.\n1. Click **Create Key**.\n1. Share it with your developer.\n\nThe developer can now use the API key in the HTTP header, prefixing it\nwith `ManagementKey-v1`:\n\n```\nAuthorization: ManagementKey-v1 bd9479c59e16f9dbc644d33aa74d58270fe13bf3\n```\n"