Upload Users

Once you have authenticated with the SplitScreen API, you can start uploading your users to the platform. This allows the system to build user profiles and generate personalized recommendations.

User Data Format

Users can be uploaded in batches of up to 100 users per request. Each user should include the following information:

{
  "user_id": "user123",
  "display_name": "PlayerOne",
  "steam_id": "76561198000000000",
  "genres": ["fps", "strategy"],
  "games": [
    {
      "name": "Counter-Strike 2",
      "playtime_minutes": 1200,
      "achievements_count": 15
    }
  ],
  "schedule": {
    "timezone": "America/New_York",
    "slots": [
      {
        "day": "monday",
        "start_time": "19:00",
        "end_time": "22:00"
      }
    ]
  },
  "location": {
    "country_code": "US",
    "region": "NY"
  },
  "personality": {
    "type": "mbti",
    "value": "INTJ"
  },
  "custom_attributes": {
    "skill_level": "expert",
    "preferred_team_size": 5
  }
}

Uploading Users

Make a POST request to the /v1/import/users endpoint with an array of user profiles.

Request:

curl -X POST \
  https://api.splitscreen-example.com/v1/users \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "user_id": "user123",
      "display_name": "PlayerOne",
      "genres": ["fps", "strategy"],
      "games": [
        {
          "name": "Counter-Strike 2",
          "playtime_minutes": 1200,
          "achievements_count": 15
        }
      ],
      "schedule": {
        "timezone": "America/New_York",
        "slots": [
          {
            "day": "monday",
            "start_time": "19:00",
            "end_time": "22:00"
          }
        ]
      },
      "location": {
        "country_code": "US",
        "region": "NY"
      },
      "personality": {
        "type": "mbti",
        "value": "INTJ"
      },
      "custom_attributes": {
        "skill_level": "expert",
        "preferred_team_size": 5
      }
    },
    {
      "user_id": "user456",
      "display_name": "PlayerTwo",
      "genres": ["rpg", "puzzle"],
      "games": [
        {
          "name": "Baldur\'s Gate 3",
          "playtime_minutes": 800,
          "achievements_count": 8
        }
      ],
      "schedule": {
        "timezone": "America/Los_Angeles",
        "slots": [
          {
            "day": "friday",
            "start_time": "20:00",
            "end_time": "23:00"
          }
        ]
      },
      "location": {
        "country_code": "US",
        "region": "CA"
      },
      "personality": {
        "type": "mbti",
        "value": "ENFP"
      },
      "custom_attributes": {
        "skill_level": "intermediate",
        "preferred_team_size": 1
      }
    }
  ]'

Response:

{
  "message": "Users imported successfully",
  "imported_count": 2
}

Required Fields

//TO-DO needs checking for docs

user_id (required): A unique identifier for the user within your system
display_name (required): The user's display name

Steam Integration

When you provide a Steam ID, SplitScreen will automatically:

Fetch the user's Steam game library and playtime data
Analyze game genres and preferences from Steam
Use Steam data to improve recommendation accuracy
Provide richer user profiles for better matching

Note: Steam integration must be enabled for your client to use this feature. See Client Platform Configuration for setup instructions.

Yee's Gamer Motivation Model

For enhanced matchmaking accuracy, you can include Yee's Gamer Motivation Model scores in your user profiles. This model analyzes 12 key gaming motivations that influence player behavior and preferences.

What It Measures

The model measures gaming motivations across 12 dimensions:

Power: Desire for status, control, and dominance
Story: Interest in narrative and character development
Design: Appreciation for aesthetics and creativity
Fantasy: Desire for escapism and role-playing
Strategy: Preference for tactical thinking and planning
Challenge: Seeking difficulty and skill mastery
Community: Desire for social interaction and teamwork
Discovery: Interest in exploration and learning
Completion: Drive to finish games and collect achievements
Excitement: Seeking adrenaline and fast-paced action
Competition: Desire to win and outperform others
Destruction: Enjoyment of chaos and mayhem

Integration with Quantic Foundry

We have partnered with Quantic Foundry to support the integration of Yee's Gamer Motivation Model survey in your applications. This allows you to:

Collect Motivation Data: Use Quantic Foundry's validated survey to gather user motivation scores
Improve Matchmaking: Provide more accurate recommendations based on gaming psychology
Enhanced User Experience: Help users find players with compatible gaming motivations

How to Include Yee's Scores

Add the yee_gamer_motivation field to your user profiles with percentile scores (0-100) for each dimension:

{
  "yee_gamer_motivation": {
    "power": 80,
    "story": 26,
    "design": 21,
    "fantasy": 77,
    "strategy": 75,
    "challenge": 36,
    "community": 19,
    "discovery": 43,
    "completion": 10,
    "excitement": 18,
    "competition": 48,
    "destruction": 67
  }
}

Note: Scores are percentiles where 50 represents the average gamer, 80 means higher than 80% of gamers, and 20 means lower than 80% of gamers.

Finding Your Steam ID

Visit SteamID.io or SteamIDFinder.com
Enter your Steam profile URL or username
Copy the 17-digit Steam ID (e.g., 76561198000000000)

Optional Fields

steam_id (optional): The user's Steam ID for enhanced recommendations
genres (optional): Array of game genres the user enjoys
games (optional): Array of games the user plays with playtime and achievement data
schedule (optional): User's availability schedule with timezone and time slots
location (optional): User's location information for regional matching
personality (optional): Personality type data (e.g., MBTI)
yee_gamer_motivation (optional): Yee's Gamer Motivation Model scores for enhanced matchmaking
custom_attributes (optional): Additional user attributes for enhanced matching

Best Practices

Unique IDs: Ensure each user_id is unique within your system
Batch Size: Upload users in batches of 100 or fewer for optimal performance
Profile Data: Include relevant user preferences and characteristics to improve recommendation quality
Regular Updates: Update user profiles when their preferences or information changes

Error Handling

If there are issues with the upload, the API will return an error response:

{
  "error": "Invalid user data",
  "details": "Missing required field: client_user_id"
}

Common errors include:

Missing required fields
Invalid data format
Duplicate user_id values
Batch size exceeding 100 users

Updating User Profiles

To update existing user profiles, simply upload the user again with the same user_id. The system will update the user's information with the new data provided.

Example: Complete Upload Process

# 1. Get your access token (see Client Registration guide)
curl -X POST https://api.splitscreen-example.com/v1/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-client-id",
    "api_key": "your-api-key", 
    "client_secret": "your-client-secret"
  }'

# 2. Upload users
curl -X POST https://api.splitscreen-example.com/v1/users \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "user_id": "user123",
      "display_name": "PlayerOne",
      "genres": ["fps", "strategy"],
      "games": [
        {
          "name": "Counter-Strike 2",
          "playtime_minutes": 1200,
          "achievements_count": 15
        }
      ],
      "schedule": {
        "timezone": "America/New_York",
        "slots": [
          {
            "day": "monday",
            "start_time": "19:00",
            "end_time": "22:00"
          }
        ]
      },
      "location": {
        "country_code": "US",
        "region": "NY"
      },
      "personality": {
        "type": "mbti",
        "value": "INTJ"
      },
      "yee_gamer_motivation": {
        "power": 80,
        "story": 26,
        "design": 21,
        "fantasy": 77,
        "strategy": 75,
        "challenge": 36,
        "community": 19,
        "discovery": 43,
        "completion": 10,
        "excitement": 18,
        "competition": 48,
        "destruction": 67
      },
      "custom_attributes": {
        "skill_level": "expert",
        "preferred_team_size": 5
      }
    }
  ]'

User Data Format​

Uploading Users​

Required Fields​

Steam Integration​

Yee's Gamer Motivation Model​

What It Measures​

Integration with Quantic Foundry​

How to Include Yee's Scores​

Finding Your Steam ID​

Optional Fields​

Best Practices​

Error Handling​

Updating User Profiles​

Example: Complete Upload Process​