Bulk add players

Use this endpoint to create one or many players in SavageTech in a single call.

This is commonly used when you want to sync players from your own systems (CRM, sportsbook, wallet) into the gamification layer before you start granting missions/rewards.

When to use this

• New user signs up → create player in SavageTech
• First deposit / first bet → create player if missing
• Backfill / migration → bulk create players

High-level flow

Endpoint

• Method: POST
• Path: /api/v1/vendor/players
• Auth: User JWT or app credentials with access to the vendor.

Request body

You can send either:

• Single player object, or
• An object with a players array for bulk creation.

Player fields:

Field	Type	Required	Description
playerId	string	Yes	Your unique player identifier.
currency	string	No	Currency code (e.g. USD, EUR). Defaults to vendor base currency.
playername	string	No	Display name (max 50 characters).

Example: create a single player

curl -X POST "https://your-api/api/v1/vendor/players" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "playerId": "user-123",
    "currency": "USD",
    "playername": "Alice"
  }'

Example: bulk create players

curl -X POST "https://your-api/api/v1/vendor/players" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "players": [
      { "playerId": "user-1", "currency": "USD", "playername": "Alice" },
      { "playerId": "user-2", "currency": "EUR" },
      { "playerId": "user-3" }
    ]
  }'

Response

• 200: Always returns a players array with per-player status.

{
  "players": [
    { "playerId": "user-1", "created": true },
    { "playerId": "user-2", "created": false }
  ],
  "message": "All players already exist"
}

Notes:

• created: false means the player already existed (safe to call this endpoint repeatedly).
• message is optional and may appear when everything already exists.

Errors and edge cases

• 400: Invalid body (e.g. empty players array), invalid player fields, or one of the players is deactivated.
• 401/403: Authentication or authorization failure.

Best practices

• Treat this as a backend-to-backend sync endpoint.
• If you plan retries, make your own pipeline idempotent (e.g. using your playerId as the stable key).
• If you need to grant rewards right after creation, call this endpoint first, then use Assign rewards on-demand.