Set player fields

POST /v1/games/{game}/player-fields · requires players:write

Call it from your server whenever values about players change: a league position, a club, the day a player last played. The values are stored on the member the player is connected to, shown on their profile, and usable in segments and filters. Player data explains how the values are checked and what a result means, and the field map how a name your game uses becomes a field.

Path parameters

Body parameters

Each entry of players holds:

Returns

A batch with problems still returns 200. Only a body that is not shaped right is refused as a whole.

This list may grow: handle unknown values. An entry that names the player by discordId gets discordId only in its result, and one that names the player by playerId gets playerId only.

Each item of problems has field, the name you sent, and a code:

Example

curl -X POST https://ceejay.communitystudios.xyz/api/v1/games/rugby_manager/player-fields \
  -H "Authorization: Bearer $CEEJAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "players": [
      {
        "playerId": "p_19",
        "fields": {
          "league_position": 3,
          "club": "Harbour Town",
          "last_played": "2026-10-07T21:10:00+02:00",
          "coach_notes": "Ready for the cup"
        }
      },
      {
        "playerId": "p_77",
        "fields": { "league_position": 9 }
      }
    ],
    "dryRun": false
  }'

The TypeScript tab calls ceejay.players.setFields from the TypeScript SDK. It returns the data of the response below.

{
  "success": true,
  "data": {
    "results": [
      {
        "index": 0,
        "playerId": "p_19",
        "status": "written",
        "written": 2,
        "unchanged": 1,
        "cleared": 0,
        "problems": [{ "field": "coach_notes", "code": "not_approved" }]
      },
      {
        "index": 1,
        "playerId": "p_77",
        "status": "not_connected",
        "written": 0,
        "unchanged": 0,
        "cleared": 0,
        "problems": []
      }
    ],
    "summary": {
      "players": 2,
      "written": 2,
      "unchanged": 1,
      "cleared": 0,
      "held": 0,
      "refused": 1
    }
  }
}

How values are checked

• Set, not added. A value equal to the current one is not a new history entry. null clears a field. A field that is not in the object is left as it is.
• The name. It is matched to the name your game uses for the field first (the sourceKey of the field map), then to the field's key, case-insensitively. A name nothing matches is added to the field map as a proposal, up to 50 at a time, and returns not_approved. Seven standard fields that need no choices are approved by the first value. All other fields need approval from the community's team.
• Numbers beyond 1e15 either way are refused. A number is multiplied by the field's scale and rounded to 6 places: a scale of 0.01 turns cents into dollars.
• Dates are YYYY-MM-DD, or a full time with an offset, which becomes its UTC day. Anything else is bad_value.
• Dropdowns pass your value through the field's value map, and it must then be one of the choices. A value that is not is offered to the team and returns not_a_choice.
• Text is up to 500 characters. An object or a list is bad_value.
• Sharing. A connection a member made through Connect stores the categories the member consented to, and a field of another category is not_consented. A connection your own server created stores none, and your server is responsible for the consent.
• Verification. A player connected at the basic level, where the game supplied an unverified player ID, does not accept fields of the purchases or location category: each is a problem with the code needs_verified_proof, and the player's other fields are still written. progress fields, and players your own server linked, are not affected.
• Under age. underAge: true on a player needs the key to hold players:connect as well. Without it the whole call returns 403 with the code insufficient_scope and required: ["players:connect"], and nothing is written. A call can carry at most 50 such players, or it returns 400 with the code bad_request.

Values are stored for members only. Nothing here creates a member profile.

Body size

The body is read before it is parsed, up to 512 KB. A larger one is refused with 413 and the code body_too_large, in the usual error shape, and nothing is processed. Send fewer players in one call.

Safe to repeat

Sending the same values again changes nothing, so the request takes no idempotencyKey. The SDK does not retry automatically; retrying it yourself is safe.

The scope

players:write is part of *, so a Full Access key can call this. A call that says underAge: true for a player also needs players:connect, which * does not include.

Limits

This request is counted against the key's own requests per minute: 60 unless a higher limit was set on it, and never more than 600. Rate limits has the numbers and the headers.

A batch of 500 players is one request, so 60 calls a minute is 30,000 players.

Errors

Every error body also carries requestId, and a 400 with the code bad_request names the invalid field in field. Match on code, not on the message text, which can change.

The errors every request shares (401, 403 for a missing scope, 405, 429, 500) are on the Errors page.