Sending Game Data

This guide walks through authorizing requests and sending a first payload to the Application Identity Profile API. For the full API reference, see the Application Identity Profile Resource.

Authorization

Before you can send game data for a player and write to your widget on their profile, they must link their Discord account to your game. See Account Linking on Web for the web-specific flow, but it is recommended to support an in-game flow as well. Follow these steps to set up authorization for game stats widgets:

Set up an application in the Developer Portal and note your application ID (client ID)
Get your bot token from the Bot section of your application dashboard
Configure your widget in the Developer Portal
Have the player link their Discord account to your game, requesting the application_identities.write scope. If you are building a Social SDK integration, the Social SDK scopes already include this scope.
After the player completes linking, store the mapping between their Discord user ID and your game’s player ID. The player’s profile record is created on Discord’s side the first time you call the Update Application Identity Profile endpoint for them.
Use the bot token to call the Update Application Identity Profile endpoint for that player

IDs Used in API Calls

The profile endpoint takes three identifiers in the path:

Identifier	Where it comes from
`application.id`	Your application ID from the Developer Portal
`user.id`	The player’s Discord user ID, returned during the OAuth2 account linking callback
`provider_issued_user_id`	The player’s ID in your game’s system (e.g. a database row ID, UUID, or username)

The provider_issued_user_id is not a Discord ID. It’s your game’s own identifier for the player, stored alongside their Discord user ID when they complete account linking. Your bot token is passed through the Authorization header:

Authorization: Bot YOUR_TOKEN

Sending Your First Payload

The minimal first call looks like this, set a username and a few primary fields for the player:

curl 'https://discord.com/api/v10/applications/1410709600545542144/users/1410709695433281536/identities/123456789123456789/profile' \
  -X PATCH \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bot YOUR_TOKEN' \
  -d '{
    "username": "johndoe123",
    "data": {
      "primary": {
        "season": "Season 3",
        "rank_name": "Silver",
        "rank_image": {"url": "https://example.com/assets/rank-images/silver.png"},
        "highest_rank": "Platinum",
        "highest_rank_image": {"url": "https://example.com/assets/rank-images/platinum.png"},
        "featured_played_character": "John Doe",
        "featured_played_character_image": {"url": "https://example.com/assets/character-images/john-doe.png"},
        "playtime_hours": 69.41,
        "total_wins": 57,
        "current_period_wins": 8,
        "total_games": 100,
        "current_period_games": 10,
        "total_kills": 253,
        "current_period_kills": 35,
        "total_assists": 478,
        "current_period_assists": 68,
        "total_deaths": 561,
        "current_period_deaths": 21
      }
    }
  }'

Returns 201 Created on first write, 204 No Content on subsequent updates.

The data field is fully replaced on every PATCH. If you include data in your request body, the entire previous data payload is overwritten and any fields you omit are lost. Always send the complete set of data you want stored. If you omit data from the request body entirely, existing data is left untouched.

For the complete payload shape, available primary fields, dynamic field types, request limits, and error responses, see the Application Identity Profile Resource.

Reading the Profile Back

After a successful write, you can read the player’s stored profile back with the Get Application Identity Profile endpoint:

curl 'https://discord.com/api/v10/applications/1410709600545542144/users/1410709695433281536/identities/123456789123456789/profile' \
  -H 'Authorization: Bot YOUR_TOKEN'

{
  "username": "johndoe123",
  "metadata": null,
  "data": {
    "primary": {
      "season": "Season 3",
      "rank_name": "Silver",
      "rank_image": {"url": "https://example.com/assets/rank-images/silver.png"},
      "highest_rank": "Platinum",
      "highest_rank_image": {"url": "https://example.com/assets/rank-images/platinum.png"},
      "featured_played_character": "John Doe",
      "featured_played_character_image": {"url": "https://example.com/assets/character-images/john-doe.png"},
      "playtime_hours": 69.41,
      "total_wins": 57,
      "current_period_wins": 8,
      "total_games": 100,
      "current_period_games": 10,
      "total_kills": 253,
      "current_period_kills": 35,
      "total_assists": 478,
      "current_period_assists": 68,
      "total_deaths": 561,
      "current_period_deaths": 21
    }
  }
}

Discord Social SDK

Core Concepts

Getting Started

Design Foundations

Provisional Accounts

Discord Account Linking

Friends & Relationships

Rich Presence & User Status

Game Invites

Direct Messages

Lobbies & Voice

Game Stats Widgets

How To

Authorization

IDs Used in API Calls

Sending Your First Payload

Reading the Profile Back

​Authorization

​IDs Used in API Calls

​Sending Your First Payload

​Reading the Profile Back

Authorization

IDs Used in API Calls

Sending Your First Payload

Reading the Profile Back