Getting Started with Personalize APIs

An operational Optimove Personalize integration has two connected data flows:

Inventory tells Personalize what can be recommended.
Real-Time Events tell Personalize which identified customer acted, and which inventory item they acted on.

Recommendations depend on both flows. A successful API response alone does not prove that the inventory was processed or that event identifiers join to inventory.

Before you build

The Inventory API base URLs are:

API	Base URL
Gaming Inventory	`https://api.opti-x.optimove.net/inventory/v1`
Sports Inventory	`https://api.opti-x.optimove.net/sports-inventory/v1`

Your Optimove onboarding contact confirms the base URLs that apply to your brand.

Ask your Optimove integration contact for the values provisioned for your brand:

Value	Used for
`{{service_api_key}}`	Inventory API authentication
`{{brand_key}}`	Routes inventory to the correct brand
Server-Side Events endpoint and signing details	Real-Time Event delivery
`tenant` value	Routes events to the correct Optimove tenant

Keep credentials in a secrets manager. Do not place real keys in source code, examples, logs, tickets, or documentation.

Decide the source of truth

Before sending data, name the system that owns each identifier and attribute.

For Gaming, the most important contract is:

Gaming Inventory game_code = Game Launch context.ootb_game_code

For Sports, every hierarchy key sent in Bet Placement and Bet Settled must use the same value as its matching inventory key. See Identifiers and data flow for the full map.

Treat identifiers as opaque, case-sensitive strings. Do not translate, trim, reformat, or recycle them.

Build in this order

1. Prepare representative inventory

Use production-shaped test data that includes:

active and inactive or hidden items;
translated and optional content where you plan to use it;
all channels, jurisdictions, skins, or other availability rules you operate;
realistic hierarchy depth and prices for Sports;
additions, changes, and removals.

2. Load inventory through the API

Choose the relevant guide:

Gaming is a full-file snapshot workflow. Sports is a record API with create/upsert, update, and delete operations. Do not apply the operating assumptions from one API to the other.

3. Verify processing, not just receipt

For Gaming, capture the upload trace identifier and poll the log endpoints until processing reaches a terminal state. After COMPLETED, reconcile the exported game-code set and keep monitoring identifier joins; the trace alone is not proof of an atomic full-snapshot replacement. Your production service should alert on failed, overdue, or unreconciled runs.

For Sports, an accepted response means the request entered the asynchronous ingestion path; it is not a record-level processing confirmation. Preserve request metadata and response bodies in your own operational logs and verify representative records through the agreed onboarding checks.

4. Send required Real-Time Events

Deliver events through Optimove's Server-Side Events API.

Vertical	Event	Requirement
Gaming	Game Launch	Required
Gaming	Game Session	Optional; needed for financial and value-aware methods
Sports	Bet Placement	Required
Sports	Bet Settled	Optional; needed for Prior Win and settlement-aware methods

These are Personalize integration requirements, not a list of every event Optimove can receive.

5. Prove the joins

For at least one identified test customer:

send inventory containing known item identifiers;
wait for confirmed inventory processing where confirmation is available;
send the required event using those exact identifiers;
verify that the event is accepted by the Server-Side Events API;
confirm with your Optimove onboarding contact that the item and customer resolve as expected in Personalize;
repeat with an invalid identifier and confirm your monitoring detects the problem.

6. Operationalise the integration

Your integration service should:

schedule inventory publication at the agreed cadence;
prevent overlapping Gaming uploads;
retain trace IDs, request IDs where available, timestamps, counts, and checksums;
retry only according to the API-specific guidance;
alert on failures, missing runs, unusual count changes, and prolonged processing;
make reconciliation and safe replay possible;
monitor required Real-Time Event volume and identifier-match health.

Before you go live

Confirm each of these before your first production run:

credentials and environment URLs are managed as secrets and configuration;
required fields and data types pass validation;
event-to-inventory identifiers match exactly;
Gaming snapshot replacement behaviour has been tested;
Sports create, update, and delete behaviour has been tested;
monitoring detects failed, missing, delayed, and unexpectedly small inventory loads;
required events arrive for identified customers;
optional events are enabled for every recommendation method that depends on them;
your team has an on-call runbook and replay procedure.