Uploading Data

Uploading data to RoBall can come in numerous forms. This article will primarily cover data which can be uploaded directly from your game's server (allowing for the most data). This will mean that you (and your league's developers) may need to write an additional script or 2 to support making submissions to RoBall when you desire.

If attempting to make a submission via the website, please ensure that:

You have a Roblox account linked to your RoBall account, see here on how to do this
That you have access to the league's RoBall dashboard (liaise with your League's admins if you are unsure)

To make the submission, head to https://roball.xyz/app/submissions (while logged in) and follow the guide given.

When making a submssion via your game server, there is some information that we will need about your experience in the submission that can help us identify you.

warning

For leagues that do not have a submissions or Pro license, submissions can only come from approved users OR users with a roblox account linked to their RoBall account!!

When making a submission from in game, you will need to set the content type to application/json and set your Authorization header to your stored API key (imported using the HTTPService in Roblox Studio).

    Url = "api.roball.xyz/submissions/game_server",
    Method = "POST",
    Headers = { 
        ["Content-Type"] = "application/json",
        ["Authorization"] = Key:AddPrefix("Bearer ")
    },
    Body = Data

    -- An example in Luau using HttpService:RequestAsync

Inside the body which contains your data, 4 seperate JSON objects are required,

{
  "submissionData": { ... },
  "TargetedEventData": [ ... ],
  "playerData": { ... }
}

Submission Data

  "submissionData": {
    "submitter_id": 12345678,   
    "submitter_name": "ExampleUser",
    "submission_date": "2025-08-16T12:34:56Z",
    "place_id": 987654321,
    "server_instance": "abcdef12-3456-7890-abcd-ef1234567890",
    "place_owner_id": 87654321,
    "match_type": "League"
}

Submission Data is the key data about your Game that allows us to help maintain your limits on submitting games per day to ensure you don't breach caps. Shown above is an example of what it might look like:

Submitter ID: The ID of the person submitting the match. (Not including it? Use "N/A")
Submitter Name: The username of the person submitting the match. (Not including this? Use "N/A")
Submission Date: use DateTime.now():ToIsoDate() to get a valid timestamp
Place ID: The ID of the place you are using (this may include any hub used in getting there)
Server Instance: The Server Instance of this game (it may help in limiting the number of submissions per server), use game.JobId
Place Owner ID: This should be the owner of the game which is a group in most places, use game.CreatorId
Match Type: This is the type of match you want to submit. Bare in mind that you will need to determine how to pass this value in (it must be a string). Supported Match types are: Friendly, League Match, Cup Match, Speical Match, National Friendly, National Match.

info

It will help to have all of these fields entered correctly to speed your submission up and help you as a league attribute submissions to people!

Targeted Event Data

"TargetedEventData": [
    {
        "eventName": "Goal",
        "eventData": ["PlayerOne", "PlayerTwo", "Team Blue","81"], 
        "timestamp": "N/A"
    },
    {
        "eventName": "YellowCard",
        "eventData": ["PlayerThree"],
        "timestamp": "N/A"
    },
    {
        "eventName": "RedCard",
        "eventData": ["PlayerFour"],
        "timestamp": "N/A"
    }
]

Targeted Event Data is where your data for Targeted Events (non-targeted event support will arrive by the end of Phase 1) goes on during your game lands. It is expected to be an array of JSON objects. One for each event. Your league is required to determine which events you wish to capture with RoBall.

At present, football (soccer) is the only sport available on the site and the type of Targeted Events supported (defined by eventName) are Goal, YellowCard and RedCard. For each event, the following information is required:

eventName: The name of the event as dictated above.
eventData: An array (or table in Luau) that will contain the roblox username (or ID) of the person(s) involved as well as custom timestamps (in strings).
- For Goals, index 0 must contain the name of the person who scored. Index 1 can contain the name of the assister and index 3 can hold the Direct Team (the name of the Team which this goal occured on) while index 3 can hold the custom timestamp (which is not required).
- For Yellow Cards and Red Cards, index 0 must hold the name of the offender and index one can hold the Direct Team (the name of the Team which this card occured on) while index 2 can hold a custom timestamp if wanted
timestamp: This can be a real timestamp by use of DateTime.now():ToIsoDate() or set to "N/A" for each event if you wish to not have it.

note

If a custom timestamp is used in TargetedEventData, it will override the timestamp key provided in the object.

Non Targeted Event Data

"nonTargetedEventData": [
    {
        "eventName": "Free Kick",
        "eventData": ["Team Green"], 
        "timestamp": "N/A"
    },
    {
        "eventName": "Foul",
        "eventData": ["PlayerThree","Player Five", "Team Blue"],
        "timestamp": "N/A"
    }
]

Non Targeted Event Data is where your data for ** Non Targeted Events** goes on during your game lands. It is expected to be an array of JSON objects. One for each event. Your league is required to determine which non-targeted events you wish to capture with RoBall.

At present, football (soccer) is the only sport available on the site and the type of Non Targeted Events supported (defined by eventName) are set pieces (Free Kick, Corner Kick, Goal Kick, Penalties etc), fouls and saves. For each event, the following information is required:

eventName: The name of the event as dictated above.
eventData: An array (or table in Luau) that will contain the roblox username of the person(s) involved as well as custom timestamps (in strings).
- For all events excluding Saves and Fouls, index 0 must contain the name of the team reciving the set piece. Index 1 can contain the custom timestamp (which is not required).
- For Foul, index 0 must hold the name of the offender while index 1 must hold the name of the person being fouled, index 2 must hold the team of the person committing the foul. The custom timestamp and be stored in index 3 (which is not required).
- For Saves, index 0 must carry the name of the person making the save while index one must hold the name of the team the player was on when the save is made. The custom timestamp and be stored in index 2 (which is not required).
timestamp: This can be a real timestamp by use of DateTime.now():ToIsoDate() or set to "N/A" for each event if you wish to not have it.

note

If a custom timestamp is used in TargetedEventData, it will override the timestamp key provided in the object. Timestamp support for Non Targeted Events will arrive in Phase 2.

tip

For Targeted and Non Targeted Events, it is recommened to use Roblox usernames when required!

Player Data

"playerData": {
    "Blue": {
        "team_name": "Team Blue",
        "players": {
                "name": "PlayerOne",
                "displayName": "Player One",
                "id": 123456,
                "isGK": false
            },
            {
                "name": "PlayerTwo",
                "displayName": "Player Two",
                "id": 234567,
                "isGK": false
            }
        }
    ,
    "Green": {
        "team_name": "Team Green",
        "players": {
            {
                "name": "PlayerThree",
                "displayName": "Player Three",
                "id": 345678,
                "isGK": false
            },
            {
                "name": "PlayerFour",
                "displayName": "Player Four",
                "id": 456789,
                "isGK": false
            }

        }
    }
}

Player Data is where information about who has participated in your match is held. In here, 2 Seperate key value pairs are required. The names of each key should either be Blue or Green. The values in this object are arrays which store a json object for each player on said team.

warning

Note that if 2 or more key value pairs are present, the 2 largest values (or array lengths in this case) will be used and generalised. This will not be useful if the game server has extra teams in your game server (such as spectators/fans or officials/referees).

Each object within each team's array must contain the following:

A team name (stored as team_name) which carries the name of the team you wish to see on the website.
A players object with one object per each player on the given team. Each object should contain the following:
- Name: The player's unique Roblox Username
- DisplayName: The player's Roblox display name (Not including this? Use "N/A" for each player)
- Id: The player's roblox ID (player.userId)
- isGk: A boolean value dictating whether or not this player was a Goalkeeper in the match. This may be useful if:
  - Your Goalkeeper teams are seperate from the rest of your teams (by which you will need to loop over the goalkeeper teams seperately to correctly identify them)
  - You have seperate means for determing goal keepers

warning

There is no limit on how many players that can be held here (at present) but it's important to remember that each player here will carry their own record on the match page on the website (this can slow down submission speed and make it more difficult to read if including players who had no interaction).

Sending and Results

Once the data has been placed in one large JSON Object and encoded (using the HTTPService), the request can be made. It is recommened to use pcall to catch any errors (such as an authorization failure or server failure).

The endpoint to use for game server submissions is: https.//api.roball.xyz/submissions/game_server, with the method set to POST.

Different response codes can mean different things here:

Status	Meaning	When it happens
`200`	OK	Submission was sucess, you should recieve a JSON object back containing a `match_id` field holding the New match ID.
`400`	Bad Request	Some of the required data was missing.
`401`	Unauthorized	This could mean numerous errors: Missing API Key, Key did not match any league, the user making the submission is not permitted to do so (This is important for leagues without the Pro licence).
`500`	Internal Server Error	Something went wrong on our end. Please try again and reach out to the Support Server if it persists.

tip

Regardless of the outcome, you should recieve a JSON object with a ```error`` field. The value to said field can help you debug your submission and determine what went wrong.

danger

Please note: SubmissionData, playerData and TargetedEventData are all required otherwise the submission will fail on the spot.

Submission Data​

Targeted Event Data​

Non Targeted Event Data​

Player Data​

Sending and Results​

Submission Data

Targeted Event Data

Non Targeted Event Data

Player Data

Sending and Results