Talon.One Customer data API

openapi: 3.2.0
info:
  title: Management Customer data 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: Customer data
  description: 'Represents the data of a customer, including sessions and events used for reporting and debugging in the Campaign Manager.

    '
paths:
  /v1/applications/{applicationId}/customers:
    get:
      operationId: getApplicationCustomers
      summary: List application's customers
      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 customers of the specified application.'
      tags:
      - Customer data
      parameters:
      - $ref: '#/components/parameters/applicationId'
      - name: integrationId
        in: query
        description: Filter results performing an exact matching against the profile integration identifier.
        example: customer1
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/skip'
      - name: withTotalResultSize
        in: query
        description: 'When this flag is set, the result includes the total number of results for this query. This might decrease performance on large data sets.


          - When `true`: `totalResultSize` contains the total number of results for this query.

          - When `false`: Only `hasMore` is returned, and it is set to `true` when there are more results than shown on the page.

          '
        example: false
        schema:
          type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  totalResultSize:
                    type: integer
                    example: 1
                  hasMore:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApplicationCustomer'
  /v1/applications/{applicationId}/customer_search:
    post:
      operationId: getApplicationCustomersByAttributes
      summary: List application customers matching the given 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.


        Get a list of the application customers matching the provided criteria.


        The match is successful if all the attributes of the request are found in a profile, even if the profile has more attributes that are not present on the request.

        '
      tags:
      - Customer data
      parameters:
      - $ref: '#/components/parameters/applicationId'
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/skip'
      - name: withTotalResultSize
        in: query
        description: 'When this flag is set, the result includes the total number of results for this query. This might decrease performance on large data sets.


          - When `true`: `totalResultSize` contains the total number of results for this query.

          - When `false`: Only `hasMore` is returned, and it is set to `true` when there are more results than shown on the page.

          '
        example: false
        schema:
          type: boolean
      requestBody:
        $ref: '#/components/requestBodies/CustomerProfileSearchQuery'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  hasMore:
                    type: boolean
                  totalResultSize:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApplicationCustomer'
  /v1/customer_search/no_total:
    post:
      operationId: getCustomersByAttributes
      summary: List customer profiles matching the given 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.


        Get a list of the customer profiles matching the provided criteria.


        The match is successful if all the attributes of the request are found in a profile, even if the profile has more attributes that are not present on the request.

        '
      tags:
      - Customer data
      parameters:
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/skip'
      - name: sandbox
        in: query
        description: Indicates whether you are pointing to a sandbox or live customer.
        example: false
        required: false
        schema:
          type: boolean
          default: false
      requestBody:
        $ref: '#/components/requestBodies/CustomerProfileSearchQuery'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  hasMore:
                    type: boolean
                  totalResultSize:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomerProfile'
  /v1/customers/{customerId}:
    get:
      operationId: getCustomerProfile
      summary: Get customer profile
      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 the details of the specified customer profile.


        > [!note]

        > You can retrieve the same information via the Integration API, which can save you extra API requests. Consider these options:

        > - Request the customer profile to be part of the response content using

        >   [Update Customer Session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2).

        > - Send an empty update with the [Update Customer Profile](https://docs.talon.one/integration-api#tag/Customer-profiles/operation/updateCustomerProfileV2) endpoint with `runRuleEngine=false`.

        '
      tags:
      - Customer data
      parameters:
      - name: customerId
        in: path
        description: 'The value of the `id` property of a customer profile. Get it with the

          [List Application''s customers](https://docs.talon.one/management-api#tag/Customer-data/operation/getApplicationCustomers) endpoint.

          '
        example: 3778
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerProfile'
  /v1/customers/no_total:
    get:
      operationId: getCustomerProfiles
      summary: List customer profiles
      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 customer profiles.'
      tags:
      - Customer data
      parameters:
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/skip'
      - name: sandbox
        in: query
        description: Indicates whether you are pointing to a sandbox or live customer.
        example: false
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - hasMore
                - data
                properties:
                  hasMore:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomerProfile'
  /v1/applications/{applicationId}/customers/{customerId}:
    get:
      operationId: getApplicationCustomer
      summary: Get application's customer
      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 customers of the specified application.

        '
      tags:
      - Customer data
      parameters:
      - $ref: '#/components/parameters/applicationId'
      - name: customerId
        in: path
        description: 'The value of the `id` property of a customer profile. Get it with the

          [List Application''s customers](https://docs.talon.one/management-api#tag/Customer-data/operation/getApplicationCustomers) endpoint.

          '
        example: 3778
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationCustomer'
  /v1/applications/{applicationId}/customer_activity_reports/no_total:
    get:
      operationId: getCustomerActivityReportsWithoutTotalCount
      summary: Get Activity Reports for Application Customers
      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.


        Fetch summary reports for all application customers based on a time range. Instead of having the total number of results

        in the response, this endpoint only mentions whether there are more results.

        '
      tags:
      - Customer data
      parameters:
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/sort'
      - name: rangeStart
        in: query
        required: true
        description: 'Only return results from after this timestamp.


          > [!note] **Note**

          > - This must be an RFC3339 timestamp string.

          > - You can include a time component in your string, for example, `T23:59:59` to specify the end of the day. The time zone setting

          >   considered is `UTC`. If you do not include a time component, a default time value of `T00:00:00` (midnight) in `UTC` is considered.

          '
        example: '2024-05-29T15:04:05+07:00'
        schema:
          type: string
          format: date-time
      - name: rangeEnd
        in: query
        required: true
        description: 'Only return results from before this timestamp.


          > [!note] **Note**

          > - This must be an RFC3339 timestamp string.

          > - You can include a time component in your string, for example, `T23:59:59` to specify the end of the day. The time zone setting

          >   considered is `UTC`. If you do not include a time component, a default time value of `T00:00:00` (midnight) in `UTC` is considered.

          '
        example: '2024-05-29T15:04:05+07:00'
        schema:
          type: string
          format: date-time
      - $ref: '#/components/parameters/applicationId'
      - name: name
        in: query
        description: Only return reports matching the customer name.
        example: customer1
        required: false
        schema:
          type: string
      - name: integrationId
        in: query
        description: Filter results performing an exact matching against the profile integration identifier.
        example: customer1
        required: false
        schema:
          type: string
      - name: campaignName
        in: query
        description: Only return reports matching the campaign name.
        example: campaign1
        required: false
        schema:
          type: string
      - name: advocateName
        in: query
        description: Only return reports matching the current customer referrer name.
        example: advocate1
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - hasMore
                - data
                properties:
                  hasMore:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomerActivityReport'
  /v1/applications/{applicationId}/customer_activity_reports/{customerId}:
    get:
      operationId: getCustomerActivityReport
      summary: Get customer's activity report
      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.


        Fetch the summary report of a given customer in the given application, in a time range.'
      tags:
      - Customer data
      parameters:
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/skip'
      - name: rangeStart
        in: query
        required: true
        description: 'Only return results from after this timestamp.


          > [!note] **Note**

          > - This must be an RFC3339 timestamp string.

          > - You can include a time component in your string, for example, `T23:59:59` to specify the end of the day. The time zone setting

          >   considered is `UTC`. If you do not include a time component, a default time value of `T00:00:00` (midnight) in `UTC` is considered.

          '
        example: '2024-05-29T15:04:05+07:00'
        schema:
          type: string
          format: date-time
      - name: rangeEnd
        in: query
        required: true
        description: 'Only return results from before this timestamp.


          > [!note] **Note**

          > - This must be an RFC3339 timestamp string.

          > - You can include a time component in your string, for example, `T23:59:59` to specify the end of the day. The time zone setting

          >   considered is `UTC`. If you do not include a time component, a default time value of `T00:00:00` (midnight) in `UTC` is considered.

          '
        example: '2024-05-29T15:04:05+07:00'
        schema:
          type: string
          format: date-time
      - $ref: '#/components/parameters/applicationId'
      - name: customerId
        in: path
        description: 'The value of the `id` property of a customer profile. Get it with the

          [List Application''s customers](https://docs.talon.one/management-api#tag/Customer-data/operation/getApplicationCustomers) endpoint.

          '
        example: 3778
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerActivityReport'
  /v1/applications/{applicationId}/customers/{customerId}/analytics:
    get:
      operationId: getCustomerAnalytics
      summary: Get customer's analytics report
      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.


        Fetch analytics for a given customer in the given application.'
      tags:
      - Customer data
      parameters:
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/sort'
      - $ref: '#/components/parameters/applicationId'
      - name: customerId
        in: path
        description: 'The value of the `id` property of a customer profile. Get it with the

          [List Application''s customers](https://docs.talon.one/management-api#tag/Customer-data/operation/getApplicationCustomers) endpoint.

          '
        example: 3778
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerAnalytics'
  /v1/applications/{applicationId}/sessions:
    get:
      operationId: getApplicationSessions
      summary: List Application sessions
      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 sessions of the specified Application.

        '
      tags:
      - Customer data
      parameters:
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/sort'
      - name: partialMatch
        in: query
        required: false
        description: 'Enables partial matching for a single text search field. When enabled, the search term matches anywhere within the field value (case-insensitive). Minimum 3 characters required for partial matches; shorter inputs automatically fall back to exact match.


          **Note:** Use with one of: `integrationId`, `profile`, `coupon`, `referral`, or `storeIntegrationId`.'
        example: false
        schema:
          type: boolean
          default: false
      - name: profile
        in: query
        required: false
        description: Filter by sessions with this profile integration ID. By default, requires exact match. Use `partialMatch=true` to search for partial matches (minimum 3 characters).
        example: customer1
        schema:
          type: string
      - name: state
        in: query
        required: false
        description: Filter by sessions with this state. Must be exact match.
        example: open
        schema:
          type: string
          enum:
          - open
          - closed
          - partially_returned
          - cancelled
      - name: createdBefore
        in: query
        description: Only return events created before this date. You can use any time zone setting. Talon.One will convert to UTC internally.
        required: false
        example: '2024-05-29T15:04:05+07:00'
        schema:
          type: string
          format: date-time
      - name: createdAfter
        in: query
        description: Only return events created after this date. You can use any time zone setting. Talon.One will convert to UTC internally.
        required: false
        example: '2024-05-29T15:04:05+07:00'
        schema:
          type: string
          format: date-time
      - name: coupon
        in: query
        required: false
        description: Filter by sessions with this coupon. By default, requires exact match. Use `partialMatch=true` to search for partial matches (minimum 3 characters).
        example: SUMMER10
        schema:
          type: string
      - name: referral
        in: query
        required: false
        description: Filter by sessions with this referral. By default, requires exact match. Use `partialMatch=true` to search for partial matches (minimum 3 characters).
        example: WPCNAQ5C
        schema:
          type: string
      - name: integrationId
        in: query
        required: false
        description: Filter by sessions with this integration ID. By default, requires exact match. Use `partialMatch=true` to search for partial matches (minimum 3 characters).
        example: STORE-123-REGION-WEST
        schema:
          type: string
      - name: storeIntegrationId
        in: query
        required: false
        description: The integration ID of the store. You choose this ID when you create a store. By default, requires exact match. Use `partialMatch=true` to search for partial matches (minimum 3 characters).
        example: store1
        schema:
          type: string
      - $ref: '#/components/parameters/applicationId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  hasMore:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApplicationSession'
  /v1/applications/{applicationId}/sessions_search:
    post:
      operationId: getApplicationSessionsByCustomerAttributes
      summary: List Application sessions matching the given customer 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.


        Get a list of the Application sessions matching the provided customer profile

        attributes.


        The match is successful if all the attributes of the request are found in a

        profile, even if the profile has more attributes that are not present on the

        request.

        '
      tags:
      - Customer data
      parameters:
      - $ref: '#/components/parameters/applicationId'
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/skip'
      - name: withTotalResultSize
        in: query
        description: 'When this flag is set, the result includes the total number of results for this query. This might decrease performance on large data sets.

          - When `true`: `totalResultSize` contains the total number of results for this query.

          - When `false`: Only `hasMore` is returned, and it is set to `true` when there are more results than shown on the page.

          '
        example: false
        schema:
          type: boolean
      requestBody:
        $ref: '#/components/requestBodies/CustomerProfileSearchQuery'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  hasMore:
                    type: boolean
                  totalResultSize:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApplicationSession'
  /v1/applications/{applicationId}/sessions/{sessionId}:
    get:
      operationId: getApplicationSession
      summary: Get Application session
      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 the given session.

        You can list the sessions with the [List Application sessions](https://docs.talon.one/management-api#tag/Customer-data/operation/getApplicationSessions) endpoint.

        '
      tags:
      - Customer data
      parameters:
      - $ref: '#/components/parameters/applicationId'
      - name: sessionId
        in: path
        description: 'The **internal** ID of the session. You can get the ID with the [List Application sessions](https://docs.talon.one/management-api#tag/Customer-data/operation/getApplicationSessions) endpoint.

          '
        example: 2533
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationSession'
  /v1/applications/{applicationId}/events/no_total:
    get:
      operationId: getApplicationEventsWithoutTotalCount
      summary: List Applications events
      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.


        Lists all events recorded for an application. Instead of having the total number of results in the response, this endpoint only mentions whether there are more results.

        '
      tags:
      - Customer data
      parameters:
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/sort'
      - name: type
        in: query
        required: false
        description: Comma-separated list of types by which to filter events. Must be exact match(es).
        example: talon_session_created,talon_session_updated
        schema:
          type: string
      - name: createdBefore
        in: query
        description: Only return events created before this date. You can use any time zone setting. Talon.One will convert to UTC internally.
        required: false
        example: '2024-05-29T15:04:05+07:00'
        schema:
          type: string
          format: date-time
      - name: createdAfter
        in: query
        description: Only return events created after this date. You can use any time zone setting. Talon.One will convert to UTC internally.
        required: false
        example: '2024-05-29T15:04:05+07:00'
        schema:
          type: string
          format: date-time
      - name: session
        in: query
        required: false
        description: Session integration ID filter for events. Must be exact match.
        example: session1
        schema:
          type: string
      - name: profile
        in: query
        required: false
        description: Profile integration ID filter for events. Must be exact match.
        example: profile1
        schema:
          type: string
      - name: customerName
        in: query
        required: false
        description: Customer name filter for events. Will match substrings case-insensitively.
        example: customer1
        schema:
          type: string
          minLength: 2
      - name: customerEmail
        in: query
        required: false
        description: Customer e-mail address filter for events. Will match substrings case-insensitively.
        example: john@doe.com
        schema:
          type: string
          minLength: 2
      - name: couponCode
        in: query
        required: false
        description: Coupon code
        example: SUMMER10
        schema:
          type: string
      - name: referralCode
        in: query
        required: false
        description: Referral code
        example: WPCNAQ5C
        schema:
          type: string
      - name: ruleQuery
        in: query
        description: Rule name filter for events
        example: rule1
        required: false
        schema:
          type: string
      - name: campaignQuery
        in: query
        description: Campaign name filter for events
        example: campaign1
        required: false
        schema:
          type: string
      - name: effectType
        in: query
        description: The type of effect that was triggered. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
        example: rejectCoupon
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/applicationId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - hasMore
                - data
                properties:
                  hasMore:
                    type: boolean
                  data:
                    type: array
   

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