Talon.One Attributes API

openapi: 3.2.0
info:
  title: Management Attributes API
  version: ''
  description: "The Management API allows you to programmatically do what the Campaign Manager\ndoes. Use this API for back-office operations such as campaign\nand coupon management, maintenance jobs, and bulk operations.\n\nFor more background information about this API, see\n[Management API overview](https://docs.talon.one/docs/dev/management-api/overview).\n\n> [!note] **Are you looking for a different API?**\n> - To integrate with Talon.One directly and send real-time data, see the [Integration API](https://docs.talon.one/integration-api).\n> - To integrate with Talon.One from a CEP or CDP platform, see the [Third-party API](https://docs.talon.one/third-party-api).\n\n## Authentication\n\nManagement API keys are scoped to a user account and become invalid if the user is\ndeactivated or removed from the organization. Use a dedicated service account to\ncreate keys for production integrations.\n\nFor details on generating and managing API keys, see\n[Manage Management API keys](https://docs.talon.one/docs/product/account/dev-tools/manage-mapi-keys).\n\n## Security\n\nConsider the following recommendations:\n- Store API keys securely via environment variables or by using a secret management system.\n- Only call this API from backend services.\n- Implement HTTPS for all communication with the API to ensure data privacy and security.\n- Create [user roles](https://docs.talon.one/docs/product/account/account-settings/manage-roles)\n  reflecting your own company hierarchies.\n\n## Response codes and error handling\n\nTalon.One uses conventional HTTP response codes to indicate the success or failure of an API request.\nCodes in the `2xx` range indicate success. Codes in the `4xx` range indicate the request failed based\non the information provided. Codes in the `5xx` range indicate an error with Talon.One servers.\n\nError responses include a `message` that summarizes what went wrong. Use it for logging and debugging.\n\nWhen a request has one or more specific problems, the `errors` array lists each one separately:\n- `title` gives a short description of the problem\n- `source` shows where the error originated, for example, using a `pointer` property indicating the\n  problematic property in the request body.\n\n| Code | Description | Action |\n|------|-------------|--------|\n| `2xx` | Success | None. |\n| `400` | Bad request | Fix the request (for example, a missing or invalid parameter). Not retryable. |\n| `401` | Unauthorized | Provide a valid API key. Not retryable. |\n| `404` | Not found | Check the resource path or ID. Not retryable. |\n| `409` | Conflict | If you are creating a resource, use a unique resource name/ID. Generally not retryable. |\n| `429` | Rate limit exceeded | Retry with exponential backoff. |\n| `5xx` | Server error | Retry with exponential backoff. |\n\n## URL encoding\n\nEncode all path and query parameter values that contain special characters. This applies to\ncustomer profile IDs, session IDs, coupon codes, and any other user-supplied string passed as\na URL segment or query parameter.\n\nFor example, encode a `10$OFF_NOW` coupon code as `10%24OFF_NOW` before\nincluding it in a request URL.\n\nRequests with unencoded special characters may be misrouted or return unexpected errors.\n\nFor more information, see [HTML URL Encoding Reference](https://www.w3schools.com/tags/ref_urlencode.asp).\n\n## MCP server (closed beta)\n\nTalon.One provides an MCP server that gives AI agents\nread-only access to your campaigns, customers, coupons, and loyalty programs,\nso they can answer questions about your campaigns and customers in plain language.\n\nAgents can explain campaign rule logic, check campaign status and budgets, analyze customer point\nbalances and tier status, and investigate failed API requests.\n\nTo connect, append `/v1/mcp/entrypoint` to your Talon.One deployment URL and authenticate with an MCP\nconnection API key generated in **Campaign Manager > Account > Tools > MCP Connections**.\n\nThe server is compatible with Claude Desktop, Claude Code, Cursor, Gemini CLI, ChatGPT CLI,\nCodex CLI, and other stdio-compatible MCP clients.\n\nFor more information, see [Talon.One MCP server](https://docs.talon.one/docs/dev/mcp).\n\n## Rate limiting\n\nThis API is **not** meant to be used in real-time integrations that directly serve your end users.\nIt supports a maximum of **3 requests per second** for each of these endpoints.\nFor real-time integrations use the [Integration API](https://docs.talon.one/integration-api).\n"
servers:
- url: https://yourbaseurl.talon.one
security:
- manager_auth: []
- management_key: []
tags:
- name: Attributes
  description: 'Represents a piece of information related to one of the entities available in the Campaign Manager. Use

    them to create highly customized rules.


    See the [docs](https://docs.talon.one/docs/product/account/dev-tools/managing-attributes).

    '
paths:
  /v1/attributes:
    post:
      operationId: createAttribute
      summary: Create custom attribute
      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 _custom attribute_ in this account.

        [Custom attributes](https://docs.talon.one/docs/dev/concepts/attributes) allow you

        to add data to Talon.One domain entities like campaigns, coupons,

        customers and so on.


        These attributes can then be given values when creating/updating these entities, and these values can be

        used in your campaign rules.


        For example, you could define a `zipCode` field for customer sessions,

        and add a rule to your campaign that only allows certain ZIP codes.


        These attributes are shared across all Applications in your account and are never required.

        '
      tags:
      - Attributes
      requestBody:
        $ref: '#/components/requestBodies/NewAttribute'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attribute'
    get:
      operationId: getAttributes
      summary: List custom attributes
      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.


        Return all the custom attributes for the account.

        '
      tags:
      - Attributes
      parameters:
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/sort'
      - name: entity
        in: query
        required: false
        description: Returned attributes will be filtered by supplied entity.
        example: entity1
        schema:
          type: string
      - name: applicationIds
        in: query
        required: false
        description: Returned attributes will be filtered by supplied application ids
        example: 1,2,3
        schema:
          type: string
      - name: loyaltyProgramIds
        in: query
        required: false
        description: Returned attributes will be filtered by the specified loyalty program ids, separated by commas. You can only use this parameter when `entity` is `LoyaltyCard`.
        example: 1,2
        schema:
          type: string
      - name: type
        in: query
        required: false
        description: Returned attributes will be filtered by supplied type
        example: string
        schema:
          type: string
      - name: kind
        in: query
        required: false
        description: Returned attributes will be filtered by supplied kind (builtin or custom)
        example: builtin
        schema:
          type: string
          enum:
          - builtin
          - custom
          x-generate-enum-go: true
      - name: search
        in: query
        required: false
        description: Returned attributes will be filtered by searching case insensitive through Attribute name, description and type
        example: string
        schema:
          type: string
      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/Attribute'
  /v1/attributes/{attributeId}:
    get:
      operationId: getAttribute
      summary: Get custom attribute
      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 specified custom attribute.

        '
      tags:
      - Attributes
      parameters:
      - name: attributeId
        in: path
        required: true
        description: The ID of the attribute. You can find the ID in the Campaign Manager's URL when you display the details of an attribute in **Account** > **Tools** > **Attributes**.
        example: 31
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attribute'
    put:
      operationId: updateAttribute
      summary: Update custom attribute
      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 an existing custom attribute. Once created, the only property of a custom attribute that can be

        changed is the description.


        To change the `type` or `name` property of a custom attribute, create a new attribute and

        update any relevant integrations and rules to use the new attribute.

        '
      tags:
      - Attributes
      parameters:
      - name: attributeId
        in: path
        required: true
        description: The ID of the attribute. You can find the ID in the Campaign Manager's URL when you display the details of an attribute in **Account** > **Tools** > **Attributes**.
        example: 31
        schema:
          type: integer
      requestBody:
        $ref: '#/components/requestBodies/NewAttribute'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attribute'
  /v1/attributes/{attributeId}/allowed_list/import:
    post:
      operationId: importAllowedList
      summary: Import allowed values for attribute
      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 a list of [picklist

        values](https://docs.talon.one/docs/product/account/dev-tools/managing-attributes#picklist-values)

        for the specified attribute.


        The file should be sent as multipart data.


        The import **replaces** the previous list of allowed values for this

        attribute, if any.


        The CSV file **must** only contain the following column:


        - `item`: The values in your allowed list, for example a list of SKUs.


        An allowed list is limited to 500,000 items.


        ## Example


        ```text

        item

        CS-VG-04032021-UP-50D-10

        CS-DV-04042021-UP-49D-12

        CS-DG-02082021-UP-50G-07

        ```

        '
      tags:
      - Attributes
      parameters:
      - name: attributeId
        in: path
        required: true
        description: The ID of the attribute. You can find the ID in the Campaign Manager's URL when you display the details of an attribute in **Account** > **Tools** > **Attributes**.
        example: 31
        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'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
components:
  schemas:
    Attribute:
      allOf:
      - $ref: '#/components/schemas/Entity'
      - $ref: '#/components/schemas/AccountEntity'
      - $ref: '#/components/schemas/NewAttribute'
      - type: object
        properties:
          eventTypeId:
            type: integer
            example: 22
    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'
    ErrorResponse:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: A message describing the error.
        errors:
          type: array
          description: An array of individual problems encountered during the request.
          items:
            $ref: '#/components/schemas/APIError'
    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'
    UserEntity:
      type: object
      required:
      - userId
      properties:
        userId:
          type: integer
          description: The ID of the user associated with this entity.
          example: 388
    NewAttribute:
      allOf:
      - 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:
            - Application
            - Campaign
            - CustomerProfile
            - CustomerSession
            - CartItem
            - Coupon
            - Event
            - Giveaway
            - LoyaltyCard
            - Referral
            - Store
            example: Event
          eventType:
            type: string
            example: pageViewed
          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: pageViewed
          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: Page view event
          type:
            type: string
            enum:
            - string
            - number
            - boolean
            - time
            - (list string)
            - (list number)
            - (list time)
            - location
            - (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: Event triggered when a customer displays a page.
          suggestions:
            type: array
            description: A list of suggestions for the attribute.
            maxItems: 50
            items:
              type: string
              minLength: 1
          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: true
          subscribedApplicationsIds:
            type: array
            description: A list of the IDs of the applications where this attribute is available.
            items:
              type: integer
            example:
            - 1
            - 4
            - 9
          subscribedCatalogsIds:
            type: array
            description: A list of the IDs of the catalogs where this attribute is available.
            items:
              type: integer
            example:
            - 2
            - 5
          allowedSubscriptions:
            type: array
            description: 'A list of allowed subscription types for this attribute.


              **Note:** This only applies to attributes associated with the `CartItem` entity.

              '
            example:
            - application
            - catalog
            maxItems: 2
            items:
              type: string
              enum:
              - application
              - catalog
    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.
  parameters:
    sort:
      name: sort
      in: query
      required: false
      description: 'The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with `-`.


        **Note:** You may not be able to use all fields for sorting. This is due to performance limitations.

        '
      example: name
      schema:
        type: string
    pageSize:
      name: pageSize
      in: query
      required: false
      description: The number of items in the response.
      example: 1000
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 1000
    skip:
      name: skip
      in: query
      required: false
      description: The number of items to skip when paging through large result sets.
      example: 100
      schema:
        type: integer
  requestBodies:
    NewAttribute:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NewAttribute'
      description: body
      required: true
  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"