openapi: 3.0.3
info:
  title: PureClarity Capture API
  description: >
    The PureClarity Capture API provides endpoints for server-side integration
    with the PureClarity

    personalization platform. Use these endpoints to submit tracking events,
    retrieve personalized

    recommendations, manage product data feeds, and handle GDPR compliance.


    ## Authentication


    All endpoints require your **Access Key** (`appKey` / `appId` / `AccessKey`)
    to identify your store.

    Server-side endpoints also require a **Secret Key** (`secretKey` /
    `SecretKey`) for authentication.


    You can find both keys in the PureClarity Admin console under **My Account >
    Integrations**.


    <Warning>Never expose your Secret Key in client-side code or public
    repositories.</Warning>


    ## Regional Endpoints


    PureClarity operates in two regions. Use the base URL for the region your
    account is provisioned in:


    | Region | Base URL |

    |--------|----------|

    | EU (Ireland) | `https://api-eu-w-1.pureclarity.net` |

    | US (Virginia) | `https://api-us-e-1.pureclarity.net` |


    For data feed operations via SFTP streaming, use the SFTP regional endpoints
    on port 443:


    | Region | SFTP Base URL |

    |--------|---------------|

    | EU (Ireland) | `https://sftp-eu-w-1.pureclarity.net` |

    | US (Virginia) | `https://sftp-us-e-1.pureclarity.net` |
  version: 1.0.0
  contact:
    name: PureClarity Support
    email: support@pureclarity.com
    url: https://pureclarity.com
  license:
    name: Proprietary
servers:
  - url: https://api-eu-w-1.pureclarity.net
    description: EU Region (Ireland)
  - url: https://api-us-e-1.pureclarity.net
    description: US Region (Virginia)
tags:
  - name: Server-side
    description: Server-side personalization and event tracking
  - name: Data Feeds
    description: Product, category, brand, and user data feed management
  - name: GDPR
    description: GDPR compliance endpoints for user data management
paths:
  /api/serverside:
    post:
      operationId: serverSideRequest
      summary: Server-side personalization request
      description: >
        Submit tracking events and retrieve personalized zone content from the
        server side.

        This endpoint combines event tracking with zone content retrieval in a
        single request,

        making it suitable for server-side rendered applications.


        Visitor and session IDs should be persisted as cookies on the end user's
        browser:

        - `pc_v_{access_key}` for the visitor ID

        - `pc_sessid_{access_key}` for the session ID
      tags:
        - Server-side
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServerSideRequest'
            example:
              appId: your-access-key
              secretKey: your-secret-key
              currentUrl: https://www.example.com/products/shoes
              userAgent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)
              ip: 203.0.113.50
              currency: GBP
              events:
                - name: page_view
                  data:
                    page_type: product_page
                - name: product_view
                  data:
                    id: PROD-001
              zones:
                - HP-01
                - PP-01
      responses:
        '200':
          description: Successful response with personalized zone content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerSideResponse'
              example:
                visitorId: abc123-visitor-id
                sessionId: xyz789-session-id
                zones:
                  HP-01:
                    title: Recommended for you
                    type: recommender-product
                    items:
                      - Id: PROD-001
                        Title: Running Shoes
                        Price: 59.99
                        Link: /products/running-shoes
                        Image: https://cdn.example.com/shoes.jpg
        '400':
          description: Validation error (e.g. missing required fields)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Invalid or unrecognised access key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/productfeed:
    post:
      operationId: submitProductFeed
      summary: Submit a product feed URL
      description: |
        Submit a URL where PureClarity can download a full JSON product feed.
        The feed is processed asynchronously, so the URL must remain accessible
        for at least 24 hours after submission.
      tags:
        - Data Feeds
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductFeedRequest'
            example:
              appKey: your-access-key
              secretKey: your-secret-key
              url: https://yourdomain.com/feeds/pureclarity-products.json
      responses:
        '200':
          description: Feed submission accepted
          content:
            text/plain:
              schema:
                type: string
                example: The request was submitted successfully
        '400':
          description: Validation error or invalid access key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedErrorResponse'
  /api/delta:
    post:
      operationId: submitDelta
      summary: Submit a product delta update
      description: |
        Submit incremental product updates without resubmitting a full feed.
        Use this endpoint to add, update, or delete products, manage category
        assignments, update account-specific pricing, and update user data.

        Returns a token that can be used to check the processing status via
        the `/api/deltastatus` endpoint.
      tags:
        - Data Feeds
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeltaRequest'
            example:
              AppKey: your-access-key
              SecretKey: your-secret-key
              Products:
                - Id: PROD-001
                  Title: Running Shoes - Updated
                  Prices:
                    - 59.99 GBP
                    - 74.99 USD
                  Categories:
                    - shoes
                    - running
                  Link: /products/running-shoes
                  Image: https://cdn.example.com/shoes.jpg
              DeleteProducts:
                - PROD-OLD-001
      responses:
        '200':
          description: Delta accepted for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
              example:
                Token: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        '400':
          description: Validation error or invalid access key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedErrorResponse'
        '413':
          description: Delta payload too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedErrorResponse'
  /api/deltastatus:
    post:
      operationId: getDeltaStatus
      summary: Check delta processing status
      description: >
        Check the processing status of one or more previously submitted delta
        updates

        using the tokens returned from the `/api/delta` endpoint.
      tags:
        - Data Feeds
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeltaStatusRequest'
            example:
              AppKey: your-access-key
              SecretKey: your-secret-key
              Tokens:
                - a1b2c3d4-e5f6-7890-abcd-ef1234567890
      responses:
        '200':
          description: Status of each requested token
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DeltaStatusItem'
              example:
                - Token: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  Status: 1
        '400':
          description: Validation error or invalid access key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedErrorResponse'
  /api/productfeedstatus:
    post:
      operationId: getProductFeedStatus
      summary: Check product feed processing status
      description: |
        Check the processing status of previously submitted product feed imports
        using the tokens returned from the feed submission endpoints.
      tags:
        - Data Feeds
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeedStatusRequest'
            example:
              AppKey: your-access-key
              Tokens:
                - a1b2c3d4-e5f6-7890-abcd-ef1234567890
      responses:
        '200':
          description: Status of each requested token
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FeedStatusItem'
              example:
                - Token: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  Status: Complete
        '400':
          description: Validation error or invalid access key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedErrorResponse'
  /api/user/forget:
    post:
      operationId: forgetUser
      summary: Forget a user (GDPR)
      description: |
        Submit a request to remove all identifiable data for a specific user
        from PureClarity. This supports GDPR right-to-erasure compliance.

        Once submitted, PureClarity schedules a task to remove all potentially
        identifiable data, including any associated email addresses. Forgotten
        email addresses are stored as hashed values for deduplication purposes.

        **This action is irreversible.** Once a user has been forgotten, their
        data cannot be restored.
      tags:
        - GDPR
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ForgetUserRequest'
            example:
              AccessKey: your-access-key
              SecretKey: your-secret-key
              Identifier: user@example.com
      responses:
        '200':
          description: Forget request submitted successfully
          content:
            text/plain:
              schema:
                type: string
                example: The request was submitted successfully
        '400':
          description: Validation error or missing required fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedErrorResponse'
        '403':
          description: Invalid access key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedErrorResponse'
        '404':
          description: Identifier not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedErrorResponse'
components:
  schemas:
    ServerSideRequest:
      type: object
      required:
        - appId
        - secretKey
        - currentUrl
        - userAgent
        - ip
      properties:
        appId:
          type: string
          description: Your store's unique access key
        secretKey:
          type: string
          description: Your store's secret key for server-side authentication
        currentUrl:
          type: string
          format: uri
          description: The full URL of the page being rendered
        userAgent:
          type: string
          description: The end user's browser user agent string
        ip:
          type: string
          description: The end user's IP address
        visitorId:
          type: string
          description: >-
            Persistent visitor identifier. If omitted, a new one is generated
            and returned in the response.
        sessionId:
          type: string
          description: >-
            Session identifier. If omitted, a new one is generated and returned
            in the response.
        referer:
          type: string
          description: The HTTP referer header value from the end user's request
        currency:
          type: string
          description: ISO 4217 currency code (e.g. GBP, USD, EUR)
          example: GBP
        events:
          type: array
          description: Array of tracking events to record
          items:
            $ref: '#/components/schemas/TrackingEvent'
        zones:
          type: array
          description: Array of zone IDs to retrieve personalized content for
          items:
            type: string
          example:
            - HP-01
            - PP-01
    TrackingEvent:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: |
            The event type name. Supported event types:
            - `page_view` - Page view tracking
            - `product_view` - Product page view
            - `product_rate` - Product rating
            - `set_basket` - Update basket contents
            - `order` - Order completion
            - `customer_details` - Customer identification
          enum:
            - page_view
            - product_view
            - product_rate
            - set_basket
            - order
            - customer_details
        data:
          description: Event-specific data. Structure varies by event type.
          oneOf:
            - $ref: '#/components/schemas/PageViewEvent'
            - $ref: '#/components/schemas/ProductViewEvent'
            - $ref: '#/components/schemas/ProductRateEvent'
            - $ref: '#/components/schemas/SetBasketEvent'
            - $ref: '#/components/schemas/OrderEvent'
            - $ref: '#/components/schemas/CustomerDetailsEvent'
    PageViewEvent:
      type: object
      description: Data for a `page_view` event
      required:
        - page_type
      properties:
        page_type:
          type: string
          description: The type of page being viewed
          enum:
            - homepage
            - search_results
            - category_listing_page
            - product_page
            - basket_page
            - order_complete_page
            - other
        product_id:
          type: string
          description: Product ID when on a product page
        category_id:
          type: string
          description: Category ID when on a category listing page
        brand_id:
          type: string
          description: Brand ID when on a brand page
    ProductViewEvent:
      type: object
      description: Data for a `product_view` event
      required:
        - id
      properties:
        id:
          type: string
          description: The unique product ID
    ProductRateEvent:
      type: object
      description: Data for a `product_rate` event
      required:
        - id
        - rating
      properties:
        id:
          type: string
          description: The unique product ID
        rating:
          type: number
          description: The rating value
    SetBasketEvent:
      type: object
      description: |
        Data for a `set_basket` event. Pass the `items` property containing the
        full current basket contents. Send an empty array to clear the basket.
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/BasketItem'
    BasketItem:
      type: object
      required:
        - id
        - qty
        - unitprice
      properties:
        id:
          type: string
          description: Product ID
        qty:
          type: number
          description: Quantity in the basket
        unitprice:
          type: number
          description: Unit price (use `.` as decimal separator)
    OrderEvent:
      type: object
      description: |
        Data for an `order` event. At least one customer identifier
        (`userid`, `email`, or `accid`) is required.
      required:
        - orderid
        - items
      properties:
        orderid:
          type: string
          description: Unique order identifier. Each order ID should only be sent once.
        ordertotal:
          type: number
          description: Total order value in base currency
        userid:
          type: string
          description: Unique user identifier
        email:
          type: string
          format: email
          description: Customer email address
        accid:
          type: string
          description: B2B account identifier
        groupid:
          type: string
          description: User group for price banding
        title:
          type: string
          description: Customer title (e.g. Mr, Mrs)
        firstname:
          type: string
          description: Customer first name
        lastname:
          type: string
          description: Customer last name
        zipcode:
          type: string
          description: Delivery zip/postal code
        postcode:
          type: string
          description: Delivery postal code (alias for zipcode)
        dob:
          type: string
          description: Date of birth in YYYY-MM-DD format
          example: '1990-01-15'
        items:
          type: array
          description: Order line items
          items:
            $ref: '#/components/schemas/BasketItem'
    CustomerDetailsEvent:
      type: object
      description: |
        Data for a `customer_details` event. At least one identifier
        (`userid`, `email`, or `accid`) is required.
      properties:
        userid:
          type: string
          description: Unique user identifier
        email:
          type: string
          format: email
          description: Customer email address
        accid:
          type: string
          description: B2B account identifier
        firstname:
          type: string
          description: Customer first name
        lastname:
          type: string
          description: Customer last name
        title:
          type: string
          description: Customer title (e.g. Mr, Mrs)
        group_id:
          type: string
          description: User group identifier
    ServerSideResponse:
      type: object
      properties:
        visitorId:
          type: string
          description: >
            Visitor identifier. Store as a persistent cookie named
            `pc_v_{access_key}`

            on the end user's browser.
        sessionId:
          type: string
          description: >
            Session identifier. Store as a session cookie named
            `pc_sessid_{access_key}`

            on the end user's browser.
        errors:
          type: array
          description: Array of error messages, if any
          items:
            type: string
        zones:
          type: object
          description: >
            Map of zone IDs to their personalized content. Each zone contains

            content based on the zone type configured in the PureClarity
            dashboard.
          additionalProperties:
            $ref: '#/components/schemas/ZoneContent'
    ZoneContent:
      type: object
      description: Personalized content for a single zone
      properties:
        title:
          type: string
          description: Display title for the zone
        type:
          type: string
          description: The content type of the zone
          enum:
            - recommender-product
            - recommender-category
            - recommender-brand
            - image-carousel
            - image
            - html
        items:
          type: array
          description: Array of items for recommender zones
          items:
            $ref: '#/components/schemas/ProductRecommenderItem'
        html:
          type: string
          description: Pre-rendered HTML content (for html zone type)
    ProductRecommenderItem:
      type: object
      description: A product item returned in a recommender zone
      properties:
        Id:
          type: string
          description: Product ID
        Sku:
          type: string
          description: Product SKU
        Title:
          type: string
          description: Product title
        Description:
          type: string
          description: Product description
        Link:
          type: string
          description: Product page URL
        Image:
          type: string
          description: Product image URL
        ImageOverlay:
          type: string
          description: Overlay image URL
        AllImages:
          type: array
          description: All product images
          items:
            type: string
        Price:
          type: number
          description: Current price
        WasPrice:
          type: number
          description: Original price before discount
        SavingPrice:
          type: number
          description: Amount saved
        DisplayPrice:
          type: string
          description: Formatted display price with currency symbol
        DisplayWasPrice:
          type: string
          description: Formatted original price
        SavingDisplayPrice:
          type: string
          description: Formatted saving amount
        CurrencySymbol:
          type: string
          description: Currency symbol
        SavingPercent:
          type: string
          description: Percentage saving
        Categories:
          type: array
          description: Product category IDs
          items:
            type: string
        Brand:
          type: object
          description: Brand information
        SearchTags:
          type: array
          description: Product search tags
          items:
            type: string
        OnOffer:
          type: boolean
          description: Whether the product is on offer
        NewArrival:
          type: boolean
          description: Whether the product is a new arrival
    ProductFeedRequest:
      type: object
      required:
        - appKey
        - secretKey
        - url
      properties:
        appKey:
          type: string
          description: Your store's unique access key
        secretKey:
          type: string
          description: Your store's secret key
        url:
          type: string
          format: uri
          description: |
            URL where PureClarity can download the full JSON feed.
            The feed must remain accessible for at least 24 hours.
    DeltaRequest:
      type: object
      required:
        - AppKey
        - SecretKey
      properties:
        AppKey:
          type: string
          description: Your store's unique access key
        SecretKey:
          type: string
          description: Your store's secret key
        Products:
          type: array
          description: Products to add or update
          items:
            $ref: '#/components/schemas/Product'
        DeleteProducts:
          type: array
          description: Product IDs to remove
          items:
            type: string
        SetCategoryOnProducts:
          type: array
          description: Category assignments to add
          items:
            $ref: '#/components/schemas/CategoryAssignment'
        RemoveCategoryFromProducts:
          type: array
          description: Category assignments to remove
          items:
            $ref: '#/components/schemas/CategoryAssignment'
        AccountPrices:
          type: array
          description: Account-specific prices to add or update
          items:
            $ref: '#/components/schemas/AccountPrice'
        DeleteAccountPrices:
          type: array
          description: Account-specific prices to remove
          items:
            $ref: '#/components/schemas/AccountPrice'
        Users:
          type: array
          description: User records to add or update
          items:
            $ref: '#/components/schemas/User'
    Product:
      type: object
      description: Product data record
      required:
        - Id
        - Title
        - Prices
        - Categories
        - Link
        - Image
      properties:
        Id:
          type: string
          description: Unique product identifier
        Sku:
          type: string
          description: Product SKU
        Title:
          type: string
          description: Product title
        Description:
          type: string
          description: Product description
        Brand:
          type: string
          description: Brand name
        Prices:
          type: array
          description: Product prices in the format "amount currency" (e.g. "1.00 GBP")
          items:
            type: string
          example:
            - 59.99 GBP
            - 74.99 USD
        SalePrices:
          type: array
          description: Sale prices in the same format as Prices
          items:
            type: string
        Categories:
          type: array
          description: Category IDs this product belongs to
          items:
            type: string
        Link:
          type: string
          description: Product page URL (relative or absolute)
        Image:
          type: string
          description: Main product image URL
        ImageOverlay:
          type: string
          description: Overlay image URL
        SearchTags:
          type: array
          description: Additional search terms for this product
          items:
            type: string
        AssociatedSkus:
          type: array
          description: Associated product SKUs
          items:
            type: string
        AssociatedIds:
          type: array
          description: Associated product IDs
          items:
            type: string
        AccountInclusions:
          type: array
          description: Account IDs that can see this product
          items:
            type: string
        AccountExclusions:
          type: array
          description: Account IDs that cannot see this product
          items:
            type: string
        ExcludeFromRecommenders:
          type: boolean
          description: Whether to exclude this product from recommendations
        OnOffer:
          type: boolean
          description: Whether the product is on offer
        NewArrival:
          type: boolean
          description: Whether the product is a new arrival
        RelatedProducts:
          type: array
          description: Related product IDs
          items:
            type: string
    CategoryAssignment:
      type: object
      required:
        - Category
        - Products
      properties:
        Category:
          type: string
          description: Category ID
        Products:
          type: array
          description: Product IDs to assign to or remove from the category
          items:
            type: string
    AccountPrice:
      type: object
      required:
        - AccountId
        - Id
        - Prices
      properties:
        AccountId:
          type: string
          description: Unique account identifier
        Id:
          type: string
          description: Product ID
        Prices:
          type: array
          description: Account-specific prices in "amount currency" format
          items:
            type: string
        SalePrices:
          type: array
          description: Account-specific sale prices in "amount currency" format
          items:
            type: string
    User:
      type: object
      description: User data record
      required:
        - UserId
      properties:
        UserId:
          type: string
          description: Unique user identifier
        Email:
          type: string
          format: email
          description: User email address
        FirstName:
          type: string
          description: User first name
        LastName:
          type: string
          description: User last name
        Title:
          type: string
          description: User title (e.g. Mr, Mrs)
        DOB:
          type: string
          description: Date of birth in YYYY-MM-DD format
        Gender:
          type: string
          description: User gender
        City:
          type: string
          description: User city
        State:
          type: string
          description: User state or region
        Country:
          type: string
          description: User country
        GroupId:
          type: string
          description: User group identifier
    TokenResponse:
      type: object
      properties:
        Token:
          type: string
          description: Processing token for status tracking
    DeltaStatusRequest:
      type: object
      required:
        - AppKey
        - SecretKey
        - Tokens
      properties:
        AppKey:
          type: string
          description: Your store's unique access key
        SecretKey:
          type: string
          description: Your store's secret key
        Tokens:
          type: array
          description: Array of delta tokens to check
          items:
            type: string
    DeltaStatusItem:
      type: object
      properties:
        Token:
          type: string
          description: The delta token
        Status:
          type: integer
          description: |
            Processing status:
            - `0` - Pending (not yet processed)
            - `1` - Success (processed successfully)
            - `2` - Error (processing failed)
          enum:
            - 0
            - 1
            - 2
        Reason:
          type: string
          description: Error reason (only present when Status is 2)
    FeedStatusRequest:
      type: object
      required:
        - AppKey
        - Tokens
      properties:
        AppKey:
          type: string
          description: Your store's unique access key
        Tokens:
          type: array
          description: Array of feed tokens to check
          items:
            type: string
    FeedStatusItem:
      type: object
      properties:
        Token:
          type: string
          description: The feed token
        Status:
          type: string
          description: Processing status (e.g. "Complete", "Processing", "Error")
        Error:
          type: string
          description: Error message (only present when status indicates an error)
    ForgetUserRequest:
      type: object
      required:
        - AccessKey
        - SecretKey
        - Identifier
      properties:
        AccessKey:
          type: string
          description: Your store's unique access key
        SecretKey:
          type: string
          description: Your store's secret key
        Identifier:
          type: string
          description: |
            The user identifier to forget. This can be an email address,
            user ID, or any other identifier associated with the user in
            PureClarity.
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          description: Array of error messages
          items:
            type: string
    FeedErrorResponse:
      type: object
      properties:
        Error:
          type: string
          description: Error message describing what went wrong