States

States are key-value snapshots attached to entities. Unlike events (which are append-only), states represent the current value of something — a player's balance, KYC status, or risk score. Writing a state replaces the previous value for that key.

Update a state

PUT /operator-data-api/entities/:externalId/state/:key

Path parameters

Parameter	Description
externalId	The entity's external ID
key	The state key (must be defined in your template)

Request body

The request body can be either:

• An object with a value field: { "value": ... }
• The value directly as the body

The value can be any JSON type — string, number, boolean, object, or array.

Valid state keys (iGaming template)

Key	Typical value	Description
balance	{ "amount": 145.50, "currency": "GBP" }	Current wallet balance
kyc_status	"verified"	KYC verification status
risk_score	"low"	Responsible gaming risk assessment
loyalty_tier	"gold"	Loyalty programme tier

Upsert semantics

States use upsert on the composite key (entity_id, state_key). If a state already exists for this entity and key, it is overwritten. If not, it is created.

Example: Update balance

curl -X PUT https://api.onehazel.com/operator-data-api/entities/player_12345/state/balance \
  -H "Authorization: Bearer oh_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": {
      "amount": 145.50,
      "currency": "GBP",
      "last_updated": "2026-04-06T14:30:00Z"
    }
  }'

Response:

{
  "success": true,
  "data": {
    "stateKey": "balance",
    "value": {
      "amount": 145.50,
      "currency": "GBP",
      "last_updated": "2026-04-06T14:30:00Z"
    }
  }
}

Example: Update KYC status

curl -X PUT https://api.onehazel.com/operator-data-api/entities/player_12345/state/kyc_status \
  -H "Authorization: Bearer oh_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "verified"
  }'

Example: Update risk score

curl -X PUT https://api.onehazel.com/operator-data-api/entities/player_12345/state/risk_score \
  -H "Authorization: Bearer oh_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "medium"
  }'

Get all states

GET /operator-data-api/entities/:externalId/state

Returns all current state snapshots for an entity.

Example

curl https://api.onehazel.com/operator-data-api/entities/player_12345/state \
  -H "Authorization: Bearer oh_live_YOUR_API_KEY"

Response:

{
  "success": true,
  "data": [
    {
      "state_key": "balance",
      "value": { "amount": 145.50, "currency": "GBP" },
      "updated_at": "2026-04-06T14:30:00.000Z"
    },
    {
      "state_key": "kyc_status",
      "value": "verified",
      "updated_at": "2026-04-06T11:00:00.000Z"
    },
    {
      "state_key": "risk_score",
      "value": "medium",
      "updated_at": "2026-04-06T14:35:00.000Z"
    }
  ]
}

Get a single state

GET /operator-data-api/entities/:externalId/state/:key

Example

curl https://api.onehazel.com/operator-data-api/entities/player_12345/state/balance \
  -H "Authorization: Bearer oh_live_YOUR_API_KEY"

Response:

{
  "success": true,
  "data": {
    "state_key": "balance",
    "value": { "amount": 145.50, "currency": "GBP" },
    "updated_at": "2026-04-06T14:30:00.000Z"
  }
}

Event fan-out

When a state is updated, OneHazel emits an internal event of type entity_state.updated.<key> (e.g. entity_state.updated.kyc_status). This can trigger workflows.

Error codes

HTTP Status	Error Code	Description
400	VALIDATION_FAILED	Unknown state key — check your template's state_keys list
400	TEMPLATE_NOT_CONFIGURED	No template set — call PUT /settings first
401	UNAUTHORIZED	Missing or invalid API key
404	ENTITY_NOT_FOUND	No entity with that externalId exists
404	NOT_FOUND	State key does not exist for this entity (GET only)
429	RATE_LIMITED	Rate limit exceeded
500	INTERNAL_ERROR	Server error