Personalize Gaming Inventory

The Gaming Inventory API lets you provide Optimove Personalize with the complete catalog of games that can be recommended to your customers.

Personalize uses the catalog to:

• identify games by a stable game_code;
• connect Game Launch and Game Session events to the correct game;
• create game tags and recommendation filters;
• prevent recommendations for games that are unavailable in a customer's context;
• enrich recommendation responses with names, descriptions, images, and other metadata; and
• build models using attributes such as category, supplier, theme, RTP, and launch date.

Before you begin

You need the following values from Optimove:

The base URL is https://api.opti-x.optimove.net/inventory/v1. Your Optimove onboarding
contact confirms the base URL that applies to your brand.

Send the credentials on every Gaming Inventory API request:

x-api-key: {{service_api_key}}
x-brand-key: {{brand_key}}

Keep the service API key in a server-side secret store. Do not put it in browser code, a mobile application or a public repository.

The integration lifecycle

Gaming Inventory is a full-snapshot integration. Each upload states what the complete catalogue for one brand should be after processing.

Build complete snapshot
        |
        v
Validate complete snapshot --> Fix validation errors
        |
        v
Request temporary upload form
        |
        v
Upload JSON file
        |
        v
Capture trace ID and poll processing logs
        |
        +--> COMPLETED: reconcile the exported game-code set
        |
        +--> FAILED: diagnose, rebuild the full snapshot and upload again

The upload is asynchronous. A successful file transfer does not mean that Personalize has processed the catalogue. Your integration must monitor every upload until its main log reaches COMPLETED or FAILED.

Full-snapshot replacement semantics

Every file must contain all games that should remain in the brand's catalogue—not just new or changed games.

If a game exists in the current processed catalogue but its game_code is missing from a later snapshot, the game becomes a deletion candidate. Treat omission as a destructive change.

Before every upload:

1. Generate the file from your authoritative game catalogue.
2. Compare its game-code count and set with the most recent successful snapshot.
3. Review unexpected additions and removals.
4. Validate the complete final file, not a sample.
5. Keep the exact submitted file and its trace ID for audit and recovery.

Large removals may be stopped by platform safety controls even when the processing trace reaches COMPLETED. Do not rely on that protection: it can leave the processed catalogue inconsistent with your intended state. Block any snapshot that would remove more than half of the current games and coordinate a planned large removal with Optimove before upload.

File shape

The uploaded file is one JSON object. Each top-level property is a game code, and its value is that game's metadata.

{
  "SLOT001": {
    "game_code": "SLOT001",
    "game_name": "Adventure Quest",
    "desktop": 1,
    "mobile": 1,
    "tablet": 1,
    "supplier": "Example Games"
  },
  "TABLE007": {
    "game_code": "TABLE007",
    "game_name": "Classic Blackjack",
    "desktop": 1,
    "mobile": 1,
    "tablet": 0,
    "supplier": "Example Live"
  }
}

For every entry, the top-level key must exactly equal the nested game_code. Matching is case-sensitive. The same code must be sent as ootb_game_code in Personalize Game Launch and Game Session events.

See Gaming Inventory file schema for all supported fields and examples.

API endpoints

The base URL placeholder below includes the API's versioned base path.

The two tag endpoints are optional inspection tools, not part of the upload workflow. Use your own catalogue and retained successful snapshots as the system of record. The /download export is useful for reconciliation, but it does not round-trip every source field or prove that your full inventory is being served.

What to implement in production

A production integration must do more than transfer a file. It should:

• generate one complete snapshot per brand;
• enforce the target file contract locally;
• reject an empty catalogue or an unexpected reduction before calling the API;
• call /validate with the complete snapshot;
• upload using every field returned by /upload without changing those fields;
• record the upload time, file checksum, game count and trace ID;
• poll the trace until COMPLETED or FAILED;
• after COMPLETED, reconcile the exported game_code count and set before marking the run successful;
• alert on failure, an unknown trace or an excessive processing duration;
• prevent another upload for that brand while one is in progress; and
• retain the exact file and monitoring result for each run.

Next steps

1. Read the file schema and field dictionary.
2. Complete the Gaming Inventory quickstart.
3. Implement monitoring and recovery.
4. Use troubleshooting when a request or processing trace fails.