Personalize Sports Inventory

The Sports Inventory API lets a sportsbook send its current sports catalog to Optimove Personalize. Personalize uses that inventory to resolve the hierarchy around a selection, filter unavailable content, build recommendation candidates, order results, and return useful display metadata.

This guide covers the standard Sports Inventory integration only. Your Optimove implementation team will provide the environment-specific base URL and credentials.

At a glance

Inventory hierarchy

Every record belongs to one of six levels:

Category
└── Class
    └── Type
        └── Event
            └── Market
                └── Selection

Example:

Football
└── England
    └── Premier League
        └── Arsenal v Chelsea
            └── Match Result
                └── Arsenal

The keys linking these levels must be stable and consistent within a brand. Create parents before their children, and order a mixed POST batch as Category, Class, Type, Event, Market, then Selection.

The same keys must appear in Bet Placement and Bet Settled events. Review the shared Identifiers and data flow crosswalk before finalising your source mappings.

How requests are processed

Your integration
  → authenticated API request
  → synchronous request validation
  → asynchronous processing
  → Personalize inventory used by recommendation and search experiences

202 Accepted confirms that the request was accepted for asynchronous processing. It does not confirm that every entity is already available to Personalize. There is currently no public processing-status endpoint.

Important behavioral rules

• Treat every entity key as immutable. To change a key, create the replacement and remove the old entity.
• POST is a full-row upsert. Posting an existing key replaces its stored row; omitted optional fields are not preserved.
• PUT changes only supplied top-level fields. If a supplied field is an object, such as extra or a translation map, the object replaces the previous object rather than merging individual nested keys.
• PUT does not create a missing entity. Create it with POST first.
• Avoid duplicate records with the same entity type and key in one batch. The first occurrence wins.
• For parent deletes, send one parent record per DELETE request. This is the safe way to preserve descendant cascading behavior.
• A request may be retried after an ambiguous transport failure, but concurrent or out-of-order retries can overwrite newer state.

Documentation map

1. Quickstart—send a complete six-level example.
2. Hierarchy: concepts and conventions—what each entity means, how Personalize uses it, and the conventions and gotchas. (The field-by-field contract, including POST/PUT/DELETE behavior, is in the API Reference.)
3. Reliability and troubleshooting—asynchronous acceptance, retries, errors, and diagnostics.
4. Identifiers and data flow—the Inventory-to-Real-Time Event key crosswalk.

Values that require onboarding agreement

The API accepts several provider-specific fields without publishing a universal vocabulary. Agree these with your Optimove implementation team before relying on them:

• the serialized format of participants;
• allowed selectionPriceType values;
• the meaning and allowed values of classSortCode, eventSort, marketSort, and outcomeMeaningMajorCode;
• locale codes used as keys in translation objects;
• permitted content, size, and privacy rules for extra.

Only fields listed in this guide form the supported public contract. Do not rely on undeclared properties even if a test request appears to accept them.