Skip to content

Change History Polling Integrations

Overview

This document outlines how to integrate with VibeIQ using a pull-based approach via the /change-history API. This pattern allows external systems to periodically poll for changes to entities within a specified time range, making it ideal for batch synchronization workflows.

Unlike the Assortment Publish Integration which is event-driven, this approach gives you full control over when and how frequently you retrieve changes.

Use Cases

  • Batch synchronization - Sync changes on a scheduled basis (hourly, daily, etc.)
  • Historical data retrieval - Pull changes from a specific date range
  • Multi-entity monitoring - Track changes across different entity types (Items, Colors, Custom Entities, etc.)
  • Audit - View an audit trail of changes to entities and by whom

Polling Data Flow Pattern

On some cadence, your system will poll the /change-history endpoint for changes to entities within a specified time range. You may specify criteria to filter on specific entity types or properties. You may also provide order to sort the results, typically by timestamp.

sequenceDiagram participant ExternalSystem participant VibeIQ as VibeIQ Rest API participant Database as Your Database loop Every N minutes ExternalSystem->>Database: Get last sync timestamp Database->>ExternalSystem: Return timestamp ExternalSystem->>ExternalSystem: Build criteria with date range ExternalSystem->>VibeIQ: GET /change-history?entityType=item&criteria=... VibeIQ->>ExternalSystem: Return change records ExternalSystem->>ExternalSystem: Process changes ExternalSystem->>Database: Update entities ExternalSystem->>Database: Store new sync timestamp end

Authentication

See the Authentication & API Access guide for details on setting up your API credentials and authenticating with VibeIQ.

Change History API

Endpoint

GET /api/change-history

Query Parameters

Query parameters support encoded objects you can use to filter down the change objects you want in response. This objects supports two syntaxes:

  • jsurl - A NodeJS-specific URL encoding format for JSON objects.
    • You can learn more on how to use this syntax here: jsurl
  • URL-encoded JSON - Standard URL-encoded JSON. You may encode a JSON using URL-encoding.
    • You may take a literal JSON object and url-encode it. Example: { hello: "world" } becomes %7B%20hello%3A%20"world"%20%7D

criteria

entityType

The root type path of the entity you want to track changes for. This corresponds to the typePath visible in the Admin Console for each entity type.

Common entity types:

  • item - Item entities (Products, Materials, etc.)
  • project-item - ProjectItem entities (seasonal data)
  • assortment-item - AssortmentItem entities
  • color - Color entities
  • custom-entity - Custom entities

Example Use:

{ "entityType": "item" }

/api/change-history?criteria~(entityType~'item)

/api/change-history?criteria=%7B%22entityType%22%3A%20%22item%22%7D
entityReference

Each change object has a specific entityReference property that stores a concatenation of the entityType and its id with a colon :. You may use this to search for all changes of a specific entity.

Example Use:

{ "entityReference": "item:12345" }

/api/change-history?criteria~(entityReference~'item:12345)

/api/change-history?criteria=%7B%22entityReference%22%3A%20%22item%3A12345%22%7D
createdOn

Allows you to specify a BETWEEN syntax to filter changes by a date range.

Example Use:

{ "createdOn": "BETWEEN 2024-01-01 and 2024-12-31" }

/api/change-history?criteria~(createdOn~'BETWEEN*202024-01-01*20and*202024-12-31)

/api/change-history?criteria=%7B%22createdOn%22%3A%22BETWEEN%202024-01-01%20and%202024-12-31%22%7D

order

Allows you to sort the results by a specific field. The default is createdOn in descending order.

Example Use:

{"orderField": "createdOn", "order": "desc"}

/api/change-history?~(orderField~'createdOn~order~'desc)

/api/change-history?order=%7B%22orderField%22%3A%20%22createdOn%22%2C%20%22order%22%3A%20%22desc%22%7D

Additional Resources