Skip to main content
POST
Create or get a player

Body

application/json
projectId
string
required

Project ID this player belongs to

Example:

"123e4567-e89b-12d3-a456-426614174000"

externalUserId
string
required

External user ID from the client application (unique per project)

Required string length: 1 - 255
Example:

"user_12345"

displayName
string

Player display name

Maximum string length: 255
Example:

"John Doe"

avatarUrl
string

Player avatar URL

Maximum string length: 500
Example:

"https://example.com/avatars/johndoe.png"

locale
string

Player locale (e.g., en-US, fr-FR)

Maximum string length: 10
Example:

"en-US"

metadata
object

Additional player metadata

Example:

Response

Player created or retrieved successfully

id
string
required

Unique player identifier

Example:

"123e4567-e89b-12d3-a456-426614174000"

projectId
string
required

Project ID this player belongs to

Example:

"123e4567-e89b-12d3-a456-426614174000"

externalUserId
string
required

External user ID from client application

Example:

"user_12345"

xp
number
required

Player XP

Example:

1250

level
number
required

Player level

Example:

5

lives
number
required

Current lives/energy

Example:

3

maxLives
number
required

Maximum lives

Example:

5

livesUpdatedAt
string<date-time>
required

Last time lives were updated

Example:

"2025-01-15T10:30:00Z"

currencies
object
required

Player currencies (key-value pairs)

Example:
status
enum<string>
required

Player status

Available options:
ACTIVE,
SUSPENDED,
BANNED
Example:

"ACTIVE"

isFlagged
boolean
required

Whether player is flagged for review

Example:

false

createdAt
string<date-time>
required

Creation timestamp

Example:

"2025-01-15T10:30:00Z"

updatedAt
string<date-time>
required

Last update timestamp

Example:

"2025-01-15T10:30:00Z"

lastSeenAt
string<date-time>
required

Last activity timestamp

Example:

"2025-01-15T10:30:00Z"

displayName
object

Player display name

Example:

"John Doe"

avatarUrl
object

Player avatar URL

Example:

"https://example.com/avatars/johndoe.png"

locale
object

Player locale

Example:

"en-US"

flagReason
object

Reason for flagging

Example:

null

metadata
object

Additional player metadata

Example:
deletedAt
object

Soft deletion timestamp

Example:

null