User

Overview

Base URL: https://api.idosgames.com

HTTP Method: GET / POST

Route: /api/v2/{TitleTemplateId}/{TitleId}/Client/User/{Action}/{UserID}

Documentation: LiveOps Configuration & Logic

Actions (UserAction):

• GetClientState

• GetUserInventory

• GetCustomUserData

• UpdateCustomUserData

• TransferVirtualCurrency

• SubtractVirtualCurrency

• ConsumeItem

• DeleteUserAccount

• GetUsageTime

• AddUsageTime

Authentication

Required Headers

• Authorization: Bearer <SessionTicket>

• Content-Type: application/json

Unauthorized (401)

Returned when:

• Authorization header is missing

• Bearer token is missing/invalid

• Session validation failed

Response Envelope (Server Standard)

All responses are wrapped with OperationResult<T>:

Success

{
  "Success": true,
  "Error": null,
  "Data": { }
}

Failure

{
  "Success": false,
  "Error": "Some error message",
  "Data": null
}

SuccessResponse

Used by operations like UpdateCustomUserData and DeleteUserAccount:

{
  "IsCompleted": true,
  "ServerTime": "2026-02-09T12:34:56.789Z"
}

---

Quick Reference (Action Table)

Action	Request Body Fields	Response Data Type
GetClientState	(none)	ClientStateResponse
GetUserInventory	(none)	GetUserInventoryResult
GetCustomUserData	(none)	GetCustomUserDataResult
UpdateCustomUserData	Key, Value	SuccessResponse
TransferVirtualCurrency	FromCurrencyID, ToCurrencyID, TransferAmount	CurrencyTransferResponse
SubtractVirtualCurrency	CurrencyID, SubtractAmount	CurrencyUpdateResponse
ConsumeItem	ItemInstanceID or ItemID (+CatalogVersion), SubtractAmount	ConsumeItemResponse
DeleteUserAccount	(none)	SuccessResponse
GetUsageTime	(none)	UsageTimeStats
AddUsageTime	UsageTime	UsageTimeStats

Request body can be {} for actions without arguments.

---

Endpoints

1) GetClientState

Returns the full client state for the player. This is the primary bootstrap call — it returns user data, inventory, currencies, configuration, characters, quests, premium state, and more.

Request

Route POST /api/v2/{TitleTemplateId}/{TitleId}/Client/User/GetClientState/{UserID}

Body

{}

Response (OperationResult<ClientStateResponse>)

{
  "Success": true,
  "Error": null,
  "Data": {
    /* ClientStateResponse — full client state object.
       Typically includes: user profile, inventory, virtual currencies,
       custom user data, title configuration, characters, quests,
       premium state, leaderboard data, social state, etc. */
  }
}

Implementation note: The exact shape of ClientStateResponse is produced by the server's internal aggregation logic. It combines multiple data sources into a single payload. Refer to the SDK documentation for the full ClientStateResponse schema.

Common Errors

{ "Success": false, "Error": "User data not found", "Data": null }

{ "Success": false, "Error": "Get Client State returned null", "Data": null }

{ "Success": false, "Error": "Get Client State error: <exception message>", "Data": null }

---

2) GetUserInventory

Returns the player's current inventory, including items and virtual currency balances.

Request

Route POST /api/v2/{TitleTemplateId}/{TitleId}/Client/User/GetUserInventory/{UserID}

Body

{}

Response (OperationResult<GetUserInventoryResult>)

{
  "Success": true,
  "Error": null,
  "Data": {
    "Inventory": [
      {
        "ItemInstanceId": "I_001",
        "ItemId": "sword_01",
        "CatalogVersion": "Item",
        "RemainingUses": 1,
        "IsEquipped": false
      }
    ],
    "VirtualCurrency": {
      "CO": 1500,
      "IG": 250
    },
    "VirtualCurrencyRechargeTimes": {}
  }
}

Note: The exact fields of GetUserInventoryResult are defined by the SDK's ServerModels. The sample above shows typical fields.

Common Errors

{ "Success": false, "Error": "Inventory is null", "Data": null }

{ "Success": false, "Error": "GetUserInventory error: <exception message>", "Data": null }

---

3) GetCustomUserData

Returns the player's custom user data (key-value pairs), excluding internal/system keys.

Request

Route POST /api/v2/{TitleTemplateId}/{TitleId}/Client/User/GetCustomUserData/{UserID}

Body

{}

Response (OperationResult<GetCustomUserDataResult>)

{
  "Success": true,
  "Error": null,
  "Data": {
    "Data": {
      "preferred_language": { "Value": "en", "LastUpdated": "2026-02-09T12:00:00Z", "Permission": "Private" },
      "tutorial_step": { "Value": "5", "LastUpdated": "2026-02-09T12:30:00Z", "Permission": "Private" }
    }
  }
}

Common Errors

{ "Success": false, "Error": "CustomUserData is null", "Data": null }

{ "Success": false, "Error": "GetCustomUserData error: <exception message>", "Data": null }

---

4) UpdateCustomUserData

Updates a single key-value pair in the player's custom user data. System keys (matching SystemCustomUserDataKey enum values) are forbidden.

Request

Route POST /api/v2/{TitleTemplateId}/{TitleId}/Client/User/UpdateCustomUserData/{UserID}

Body

{
  "Key": "preferred_language",
  "Value": "en"
}

Response (OperationResult<SuccessResponse>)

{
  "Success": true,
  "Error": null,
  "Data": {
    "IsCompleted": true,
    "ServerTime": "2026-02-09T12:34:56.789Z"
  }
}

Common Errors

Missing key or value

{ "Success": false, "Error": "key or value is null", "Data": null }

System key rejected

{ "Success": false, "Error": "Incorrect key (system key)", "Data": null }

Database update failed

{ "Success": false, "Error": "Failed to update Custom User Data", "Data": null }

{ "Success": false, "Error": "UpdateCustomUserData error: <exception message>", "Data": null }

---

5) TransferVirtualCurrency

Transfers an amount of one virtual currency to another. Both currencies must form an allowed pair in AllowedCurrencyTransferPairs from the title configuration. System currencies (Coin, CoinLimit, Token, TokenLimit) are forbidden.

Request

Route POST /api/v2/{TitleTemplateId}/{TitleId}/Client/User/TransferVirtualCurrency/{UserID}

Body

{
  "FromCurrencyID": "DICE",
  "ToCurrencyID": "CO",
  "TransferAmount": 100
}

TransferAmount defaults to 1 if not provided or ≤ 0.

Response (OperationResult<CurrencyTransferResponse>)

{
  "Success": true,
  "Error": null,
  "Data": {
    "FromCurrencyID": "DICE",
    "ToCurrencyID": "CO",
    "TransferAmount": 100,
    "UpdatedVirtualCurrencies": {
      "DICE": 400,
      "CO": 1600
    }
  }
}

Common Errors

Missing arguments

{ "Success": false, "Error": "args is null", "Data": null }

Missing currency IDs

{ "Success": false, "Error": "fromCurrencyID or toCurrencyID is null", "Data": null }

Same currency

{ "Success": false, "Error": "fromCurrencyID and toCurrencyID cannot be the same", "Data": null }

System currency blocked

{ "Success": false, "Error": "Forbidden currency id", "Data": null }

Amount too small

{ "Success": false, "Error": "Amount is less than the minimum allowed amount", "Data": null }

Config not found

{ "Success": false, "Error": "TitlePublicConfiguration is null", "Data": null }

Transfer pairs not configured

{ "Success": false, "Error": "AllowedCurrencyTransferPairs is not configured", "Data": null }

Pair not in whitelist

{ "Success": false, "Error": "Transfer pair is not allowed", "Data": null }

Inventory unavailable

{ "Success": false, "Error": "Inventory.VirtualCurrency is null", "Data": null }

Not enough balance

{ "Success": false, "Error": "Insufficient funds", "Data": null }

Transfer operation failed

{ "Success": false, "Error": "Failed to transfer virtual currency", "Data": null }

Post-transfer inventory error

{ "Success": false, "Error": "Inventory.VirtualCurrency is null after transfer", "Data": null }

{ "Success": false, "Error": "TransferVirtualCurrency error: <exception message>", "Data": null }

---

6) SubtractVirtualCurrency

Subtracts (burns) a specified amount of virtual currency from the player's balance.

Request

Route POST /api/v2/{TitleTemplateId}/{TitleId}/Client/User/SubtractVirtualCurrency/{UserID}

Body

{
  "CurrencyID": "CO",
  "SubtractAmount": 50
}

Response (OperationResult<CurrencyUpdateResponse>)

{
  "Success": true,
  "Error": null,
  "Data": {
    "CurrencyID": "CO",
    "NewBalance": 1450
  }
}

Common Errors

Missing arguments

{ "Success": false, "Error": "args, currencyId or amount is null", "Data": null }

Amount too small

{ "Success": false, "Error": "Amount is less than the minimum allowed amount", "Data": null }

Insufficient balance

{ "Success": false, "Error": "Insufficient funds", "Data": null }

Subtraction failed

{ "Success": false, "Error": "Failed to subtract virtual currency", "Data": null }

Note: On unexpected exceptions, this action throws rather than returning a failure envelope. The error will be: "Error for UserID: {userId}: <exception message>".

---

7) ConsumeItem

Consumes (reduces uses / removes quantity) of an item from the player's inventory. Supports two modes:

• By ItemInstanceID — targets a specific item instance

• By ItemID (+ optional CatalogVersion) — targets items across all instances of that item type

Equipped items cannot be reduced to 0.

Request

Route POST /api/v2/{TitleTemplateId}/{TitleId}/Client/User/ConsumeItem/{UserID}

Body (by ItemInstanceID)

{
  "ItemInstanceID": "I_001",
  "SubtractAmount": 1
}

Body (by ItemID)

{
  "ItemID": "potion_hp",
  "CatalogVersion": "Item",
  "SubtractAmount": 5
}

SubtractAmount defaults to 1 if not provided or ≤ 0. If CatalogVersion is omitted, it defaults to "Item".

Response (OperationResult<ConsumeItemResponse>)

By ItemInstanceID:

{
  "Success": true,
  "Error": null,
  "Data": {
    "ItemInstanceID": "I_001",
    "ItemID": null,
    "CatalogVersion": null,
    "ConsumedAmount": 1
  }
}

By ItemID:

{
  "Success": true,
  "Error": null,
  "Data": {
    "ItemID": "potion_hp",
    "ItemInstanceID": null,
    "CatalogVersion": "Item",
    "ConsumedAmount": 5
  }
}

Common Errors

Missing arguments

{ "Success": false, "Error": "args is null", "Data": null }

No identifier provided

{ "Success": false, "Error": "ItemID or ItemInstanceID is required", "Data": null }

Item not found / insufficient / equipped

{ "Success": false, "Error": "Item not found / not enough amount / equipped item cannot be reduced to 0", "Data": null }

Consume by ItemID failed

{ "Success": false, "Error": "Not enough items / equipped rule prevented consume / database error", "Data": null }

{ "Success": false, "Error": "ConsumeItem error: <exception message>", "Data": null }

---

8) DeleteUserAccount

Permanently deletes the player's account and all associated data.

Request

Route POST /api/v2/{TitleTemplateId}/{TitleId}/Client/User/DeleteUserAccount/{UserID}

Body

{}

Response (OperationResult<SuccessResponse>)

{
  "Success": true,
  "Error": null,
  "Data": {
    "IsCompleted": true,
    "ServerTime": "2026-02-09T12:34:56.789Z"
  }
}

Common Errors

{ "Success": false, "Error": "Failed to Delete User Account", "Data": null }

---

9) GetUsageTime

Returns aggregated usage time statistics for the player.

Request

Route POST /api/v2/{TitleTemplateId}/{TitleId}/Client/User/GetUsageTime/{UserID}

Body

{}

Response (OperationResult<UsageTimeStats>)

{
  "Success": true,
  "Error": null,
  "Data": {
    "Today": 45,
    "Yesterday": 120,
    "CurrentWeek": 380,
    "CurrentMonth": 1540,
    "Total": 12500,
    "History": {
      "2026-02-08T00:00:00Z": 120,
      "2026-02-09T00:00:00Z": 45
    }
  }
}

Common Errors

{ "Success": false, "Error": "Data is null", "Data": null }

{ "Success": false, "Error": "GetUserInventory error: <exception message>", "Data": null }

Note: The error message references "GetUserInventory" — this is a copy-paste artifact in the source code. The actual action is GetUsageTime.

---

10) AddUsageTime

Records additional usage time for the player and returns updated statistics.

Request

Route POST /api/v2/{TitleTemplateId}/{TitleId}/Client/User/AddUsageTime/{UserID}

Body

{
  "UsageTime": 15
}

UsageTime — the amount of time to add (defined in the base IGSRequest class; typically in minutes or seconds — see server implementation).

Response (OperationResult<UsageTimeStats>)

{
  "Success": true,
  "Error": null,
  "Data": {
    "Today": 60,
    "Yesterday": 120,
    "CurrentWeek": 395,
    "CurrentMonth": 1555,
    "Total": 12515,
    "History": {
      "2026-02-08T00:00:00Z": 120,
      "2026-02-09T00:00:00Z": 60
    }
  }
}

Common Errors

{ "Success": false, "Error": "AddUsageTime error: <exception message>", "Data": null }

---

Models (Contracts)

UserRequest

The shared request DTO for all User actions. Each action reads only the fields it needs.

{
  "Key": "string",
  "Value": "any",
  "CurrencyID": "string",
  "SubtractAmount": 0,
  "FromCurrencyID": "string",
  "ToCurrencyID": "string",
  "TransferAmount": 1,
  "ItemInstanceID": "string",
  "ItemID": "string",
  "CatalogVersion": "string",
  "UsageTime": 0
}

UserRequest extends IGSRequest. Fields ItemID, CatalogVersion, and UsageTime are inherited from the base class. TransferAmount defaults to 1. Value accepts any JSON type (string, number, object, etc.).

Field	Type	Used by	Description
Key	string	UpdateCustomUserData	Custom data key to update
Value	any	UpdateCustomUserData	Value to set for the key (serialized to string server-side)
CurrencyID	string	SubtractVirtualCurrency	Virtual currency ID to subtract from
SubtractAmount	long	SubtractVirtualCurrency, ConsumeItem	Amount to subtract/consume. Defaults to 1 if ≤ 0 in ConsumeItem
FromCurrencyID	string	TransferVirtualCurrency	Source currency ID
ToCurrencyID	string	TransferVirtualCurrency	Destination currency ID
TransferAmount	long	TransferVirtualCurrency	Amount to transfer (default: 1)
ItemInstanceID	string	ConsumeItem	Specific item instance to consume
ItemID	string	ConsumeItem	Item ID to consume (across all instances)
CatalogVersion	string	ConsumeItem	Catalog version (defaults to "Item" if omitted)
UsageTime	int	AddUsageTime	Usage time value to record

CurrencyTransferResponse

{
  "FromCurrencyID": "string",
  "ToCurrencyID": "string",
  "TransferAmount": 0,
  "UpdatedVirtualCurrencies": {
    "<CurrencyID>": 0
  }
}

CurrencyUpdateResponse

{
  "CurrencyID": "string",
  "NewBalance": 0
}

ConsumeItemResponse

{
  "ItemID": "string",
  "ItemInstanceID": "string",
  "CatalogVersion": "string",
  "ConsumedAmount": 0
}

Notes:

• When consuming by ItemInstanceID: ItemID and CatalogVersion will be null.

• When consuming by ItemID: ItemInstanceID will be null.

UsageTimeStats

{
  "Today": 0,
  "Yesterday": 0,
  "CurrentWeek": 0,
  "CurrentMonth": 0,
  "Total": 0,
  "History": {
    "<DateTime>": 0
  }
}

SuccessResponse

{
  "IsCompleted": true,
  "ServerTime": "2026-02-09T12:34:56.789Z"
}

CurrencyTransferPair

Used in TitlePublicConfiguration.AllowedCurrencyTransferPairs to define permitted transfer directions.

{
  "FromCurrencyID": "string",
  "ToCurrencyID": "string"
}

---

Client Flow (Recommended)

A) Bootstrap (App Launch / Login)

1. GetClientState

This single call returns the complete client state. Use it to populate the main screen, inventory, characters, shop, etc.

B) Refresh Inventory

1. GetUserInventory

Call after any purchase, consumption, or equipment change to get up-to-date item and currency data.

C) Update Custom Data

1. UpdateCustomUserData (Key, Value)

For saving player preferences, tutorial progress, UI state, etc.

D) Transfer Currency

1. TransferVirtualCurrency (FromCurrencyID, ToCurrencyID, TransferAmount)

2. (optional) GetUserInventory (refresh balances)

E) Spend Currency

1. SubtractVirtualCurrency (CurrencyID, SubtractAmount)

2. (optional) GetUserInventory (refresh balances)

F) Consume Item

1. ConsumeItem (ItemInstanceID or ItemID + CatalogVersion, SubtractAmount)

2. (optional) GetUserInventory (refresh inventory)

G) Track Usage Time

1. AddUsageTime (UsageTime) — call periodically (e.g., every minute)

2. GetUsageTime — call to display stats in profile/settings

H) Delete Account

1. DeleteUserAccount

⚠️ This action is irreversible. Show a confirmation dialog before calling.

---

Config Usage Guide (Client)

Currency Transfer Whitelist

Before showing a currency transfer UI, the client should check AllowedCurrencyTransferPairs from the title configuration (returned in GetClientState). Only pairs explicitly listed are permitted. The direction matters: a pair {From: "A", To: "B"} does not imply {From: "B", To: "A"} is allowed.

System Currency IDs

The following currencies are system-reserved and cannot be used in TransferVirtualCurrency:

• Coin ID (soft currency)

• CoinLimit ID

• Token ID (hard currency)

• TokenLimit ID

The exact IDs are defined by DefaultData on the server. If a transfer is attempted with any of these, the server returns "Forbidden currency id".

Custom User Data Keys

The client can store arbitrary key-value pairs via UpdateCustomUserData, with one restriction: keys that match any value in the SystemCustomUserDataKey enum are reserved by the system and will be rejected with "Incorrect key (system key)".

---

Examples (cURL)

GetClientState

curl -X POST "https://<host>/api/v2/<TitleTemplateId>/<TitleId>/Client/User/GetClientState/<UserID>" \
  -H "Authorization: Bearer <SessionTicket>" \
  -H "Content-Type: application/json" \
  -d "{}"

GetUserInventory

curl -X POST "https://<host>/api/v2/<TitleTemplateId>/<TitleId>/Client/User/GetUserInventory/<UserID>" \
  -H "Authorization: Bearer <SessionTicket>" \
  -H "Content-Type: application/json" \
  -d "{}"

GetCustomUserData

curl -X POST "https://<host>/api/v2/<TitleTemplateId>/<TitleId>/Client/User/GetCustomUserData/<UserID>" \
  -H "Authorization: Bearer <SessionTicket>" \
  -H "Content-Type: application/json" \
  -d "{}"

UpdateCustomUserData

curl -X POST "https://<host>/api/v2/<TitleTemplateId>/<TitleId>/Client/User/UpdateCustomUserData/<UserID>" \
  -H "Authorization: Bearer <SessionTicket>" \
  -H "Content-Type: application/json" \
  -d "{\"Key\":\"preferred_language\",\"Value\":\"en\"}"

TransferVirtualCurrency

curl -X POST "https://<host>/api/v2/<TitleTemplateId>/<TitleId>/Client/User/TransferVirtualCurrency/<UserID>" \
  -H "Authorization: Bearer <SessionTicket>" \
  -H "Content-Type: application/json" \
  -d "{\"FromCurrencyID\":\"DICE\",\"ToCurrencyID\":\"CO\",\"TransferAmount\":100}"

SubtractVirtualCurrency

curl -X POST "https://<host>/api/v2/<TitleTemplateId>/<TitleId>/Client/User/SubtractVirtualCurrency/<UserID>" \
  -H "Authorization: Bearer <SessionTicket>" \
  -H "Content-Type: application/json" \
  -d "{\"CurrencyID\":\"CO\",\"SubtractAmount\":50}"

ConsumeItem (by ItemInstanceID)

curl -X POST "https://<host>/api/v2/<TitleTemplateId>/<TitleId>/Client/User/ConsumeItem/<UserID>" \
  -H "Authorization: Bearer <SessionTicket>" \
  -H "Content-Type: application/json" \
  -d "{\"ItemInstanceID\":\"I_001\",\"SubtractAmount\":1}"

ConsumeItem (by ItemID)

curl -X POST "https://<host>/api/v2/<TitleTemplateId>/<TitleId>/Client/User/ConsumeItem/<UserID>" \
  -H "Authorization: Bearer <SessionTicket>" \
  -H "Content-Type: application/json" \
  -d "{\"ItemID\":\"potion_hp\",\"CatalogVersion\":\"Item\",\"SubtractAmount\":5}"

DeleteUserAccount

curl -X POST "https://<host>/api/v2/<TitleTemplateId>/<TitleId>/Client/User/DeleteUserAccount/<UserID>" \
  -H "Authorization: Bearer <SessionTicket>" \
  -H "Content-Type: application/json" \
  -d "{}"

GetUsageTime

curl -X POST "https://<host>/api/v2/<TitleTemplateId>/<TitleId>/Client/User/GetUsageTime/<UserID>" \
  -H "Authorization: Bearer <SessionTicket>" \
  -H "Content-Type: application/json" \
  -d "{}"

AddUsageTime

curl -X POST "https://<host>/api/v2/<TitleTemplateId>/<TitleId>/Client/User/AddUsageTime/<UserID>" \
  -H "Authorization: Bearer <SessionTicket>" \
  -H "Content-Type: application/json" \
  -d "{\"UsageTime\":15}"