DOCS/API Reference/Players API

Players API

Manage player profiles, attributes, and segments via the Players API.

12 min read

Overview

The Players API allows you to create and manage player profiles, track sessions and purchases, and access player data.

Endpoint	Method	Description
`/players/players`	POST	Register/update player
`/players/players/{id}`	GET	Get player by ID
`/players/players/external/{external_id}`	GET	Get player by external ID
`/players/players/{id}`	PATCH	Update player attributes
`/players/players/{id}/session`	POST	Record session
`/players/players/{id}/purchase`	POST	Record purchase
`/players/players/{id}/lifecycle`	GET	Get player lifecycle
`/players/players/{id}/churn-risk`	GET	Get churn risk

Register Player

Creates a new player or updates an existing one based on external_id.

POST /v1/players/players

bash

curl -X POST class="code-string">"https:class="code-commentclass="code-string">">//api.ilara.ai/v1/players/players" \
  -H class="code-string">"X-API-Key: pk_live_xxx" \
  -H class="code-string">"Content-Type: application/json" \
  -d '{
    class="code-string">"external_id": class="code-string">"player_123",
    class="code-string">"device_id": class="code-string">"device_abc",
    class="code-string">"email": class="code-string">"[email protected]",
    class="code-string">"attributes": {
      class="code-string">"level": 45,
      class="code-string">"country": class="code-string">"US",
      class="code-string">"language": class="code-string">"en",
      class="code-string">"is_vip": true
    }
  }'

Parameters

Parameter	Type	Required	Description
`external_id`	string	Yes	Your unique player identifier
`device_id`	string	No	Device identifier
`email`	string	No	Player email (for campaigns)
`attributes`	object	No	Custom player attributes

Response

Player Response

json

{
  class="code-string">"success": true,
  class="code-string">"data": {
    class="code-string">"id": class="code-string">"550e8400-e29b-41d4-a716-446655440000",
    class="code-string">"external_id": class="code-string">"player_123",
    class="code-string">"device_id": class="code-string">"device_abc",
    class="code-string">"email": class="code-string">"[email protected]",
    class="code-string">"lifecycle_stage": class="code-string">"active",
    class="code-string">"session_count": 12,
    class="code-string">"total_revenue": 49.99,
    class="code-string">"is_payer": true,
    class="code-string">"first_seen_at": class="code-string">"2025-01-01T00:00:00Z",
    class="code-string">"last_seen_at": class="code-string">"2025-01-25T14:30:00Z",
    class="code-string">"attributes": {
      class="code-string">"level": 45,
      class="code-string">"country": class="code-string">"US",
      class="code-string">"language": class="code-string">"en",
      class="code-string">"is_vip": true
    }
  }
}

Get Player

GET /v1/players/players/{id}

bash

curl -X GET class="code-string">"https:class="code-commentclass="code-string">">//api.ilara.ai/v1/players/players/550e8400-e29b-41d4-a716-446655440000" \
  -H class="code-string">"X-API-Key: pk_live_xxx"

Lookup by External ID

You can also look up by external_id using the dedicated endpoint: /players/players/external/{external_id}

GET /v1/players/players/external/{external_id}

bash

curl -X GET class="code-string">"https:class="code-commentclass="code-string">">//api.ilara.ai/v1/players/players/external/player_123" \
  -H class="code-string">"X-API-Key: pk_live_xxx"

Update Player

Update player attributes for an existing player.

PATCH /v1/players/players/{id}

bash

curl -X PATCH class="code-string">"https:class="code-commentclass="code-string">">//api.ilara.ai/v1/players/players/550e8400-e29b-41d4-a716-446655440000" \
  -H class="code-string">"X-API-Key: pk_live_xxx" \
  -H class="code-string">"Content-Type: application/json" \
  -d '{
    class="code-string">"email": class="code-string">"[email protected]",
    class="code-string">"attributes": {
      class="code-string">"level": 50,
      class="code-string">"is_vip": true
    }
  }'

Record Session

POST /v1/players/players/{id}/session

bash

curl -X POST class="code-string">"https:class="code-commentclass="code-string">">//api.ilara.ai/v1/players/players/550e8400-e29b-41d4-a716-446655440000/session" \
  -H class="code-string">"X-API-Key: pk_live_xxx" \
  -H class="code-string">"Content-Type: application/json" \
  -d '{
    class="code-string">"session_id": class="code-string">"session_abc123",
    class="code-string">"duration_seconds": 1800,
    class="code-string">"start_time": class="code-string">"2025-01-25T14:00:00Z",
    class="code-string">"end_time": class="code-string">"2025-01-25T14:30:00Z"
  }'

Record Purchase

Record a player purchase and update monetization metrics. The purchase amount is passed as a query parameter.

POST /v1/players/players/{id}/purchase?amount={amount}

bash

curl -X POST class="code-string">"https:class="code-commentclass="code-string">">//api.ilara.ai/v1/players/players/550e8400-e29b-41d4-a716-446655440000/purchase?amount=9.99" \
  -H class="code-string">"X-API-Key: pk_live_xxx"

Query Parameters

Parameter	Type	Required	Description
`amount`	float	Yes	Purchase amount (must be greater than 0)

Get Churn Risk

GET /v1/players/players/{id}/churn-risk

bash

curl -X GET class="code-string">"https:class="code-commentclass="code-string">">//api.ilara.ai/v1/players/players/550e8400-e29b-41d4-a716-446655440000/churn-risk" \
  -H class="code-string">"X-API-Key: sk_live_xxx"

Churn Risk Response

json

{
  class="code-string">"success": true,
  class="code-string">"data": {
    class="code-string">"player_id": class="code-string">"550e8400-e29b-41d4-a716-446655440000",
    class="code-string">"risk_score": 0.72,
    class="code-string">"risk_level": class="code-string">"high",
    class="code-string">"factors": [
      {
        class="code-string">"factor": class="code-string">"session_decline",
        class="code-string">"description": class="code-string">"Sessions dropped 65% over 14 days",
        class="code-string">"contribution": 0.35
      },
      {
        class="code-string">"factor": class="code-string">"playtime_decline",
        class="code-string">"description": class="code-string">"Session length dropped from 25min to 8min",
        class="code-string">"contribution": 0.22
      }
    ],
    class="code-string">"prediction_date": class="code-string">"2025-01-25T00:00:00Z",
    class="code-string">"confidence": 0.85
  }
}

Get Player Lifecycle

Get a player's current lifecycle stage and activity summary.

GET /v1/players/players/{id}/lifecycle

bash

curl -X GET class="code-string">"https:class="code-commentclass="code-string">">//api.ilara.ai/v1/players/players/550e8400-e29b-41d4-a716-446655440000/lifecycle" \
  -H class="code-string">"X-API-Key: pk_live_xxx"

Lifecycle Response

json

{
  class="code-string">"success": true,
  class="code-string">"data": {
    class="code-string">"player_id": class="code-string">"550e8400-e29b-41d4-a716-446655440000",
    class="code-string">"lifecycle_stage": class="code-string">"active",
    class="code-string">"lifecycle_changed_at": class="code-string">"2025-01-20T10:00:00+00:00",
    class="code-string">"first_seen_at": class="code-string">"2025-01-01T00:00:00+00:00",
    class="code-string">"last_seen_at": class="code-string">"2025-01-25T14:30:00+00:00",
    class="code-string">"session_count": 12,
    class="code-string">"total_playtime_seconds": 54000
  }
}

Error Responses

Status	Code	Description
400	`VALIDATION_ERROR`	Invalid request data
401	`UNAUTHORIZED`	Invalid API key
404	`PLAYER_NOT_FOUND`	Player does not exist
409	`DUPLICATE_PLAYER`	Player with external_id exists

Next Steps

Events API — Track player events
Feature Flags API — Evaluate flags
Player Identification — Best practices

Events API

Feature Flags API