/players

Players represent the recipients in your system. Each player can have multiple channels associated with them (phone number, device token, email address, etc.).

Endpoints

Register or update a player

POST https://api.smooven.io/v1/players/register

Get a player

GET https://api.smooven.io/v1/players/{player_id}

Batch import players

POST https://api.smooven.io/v1/players/batch

Delete a player

DELETE https://api.smooven.io/v1/players/{player_id}

---

Register or update a player

Creates a new player or updates an existing player’s channel information.

Request

POST /v1/players/register
{
  "external_id": "user_123",
  "channels": {
    "sms": "+61400000000",
    "email": "user@example.com",
    "push": {
      "platform": "android",
      "device_token": "fcm_token_here"
    }
  },
  "tags": ["premium", "au-region"],
  "preferences": {
    "preferred_channel": "push",
    "quiet_hours": { "start": "22:00", "end": "07:00", "timezone": "Australia/Sydney" }
  }
}

Parameters

Parameter	Type	Required	Description
external_id	string	Yes	Your internal user identifier
channels	object	Yes	Available channels and their addresses
channels.sms	string	No	Phone number in E.164 format
channels.email	string	No	Email address
channels.push	object	No	Push notification token and platform
tags	array	No	Labels for segmentation
preferences	object	No	User-level delivery preferences
preferences.preferred_channel	string	No	Default channel for this user
preferences.quiet_hours	object	No	Time window during which notifications are held

Response

{
  "success": true,
  "player_id": "ply_abc123",
  "external_id": "user_123",
  "channels_registered": ["sms", "email", "push"],
  "created": false
}

---

Batch import

Import up to 1000 players in a single request.

POST /v1/players/batch
{
  "players": [
    {
      "external_id": "user_001",
      "channels": { "email": "alice@example.com", "sms": "+61400000001" }
    },
    {
      "external_id": "user_002",
      "channels": { "email": "bob@example.com" }
    }
  ]
}

Response

{
  "success": true,
  "imported": 2,
  "errors": []
}