Insert or Update Participant #

Insert or update a single participant. Requires a valid session token and the permissions.participants.store permission.

Endpoint #

POST https://api.tracx.events/v1/connect/participant

Headers #

{
  "Accept": "application/json",
  "Authorization": "<connect-token>"
}

Example cURL Request #

curl -X POST https://api.tracx.events/v1/connect/participant \
  -H "Accept: application/json" \
  -H "Authorization: <connect-token>" \
  -d '{
        "unique_id": "1",
        "first_name": "Kris",
        "last_name": "Kuiper",
        "country_code": "nl",
        "team_name": null,
        "date_of_birth": "2001-01-01",
        "start_number": "1",
        "chip_code": "0000001",
        "gender": "male",
        "state": "before",
        "race_id": 1
      }'

Fields #

Field Name	Required	Type	Constraints / Rules
unique_id	Yes	String	- Must be an alpha-numeric string with dashes/underscores allowed (alpha_dash) - Maximum length: 100 characters
first_name	Yes	String	- Maximum length: 100 characters
last_name	Yes	String	- Maximum length: 100 characters
country_code	Optional	String	- Must be a valid ISO country code (i.e. NL)
team_name	Optional	String	- Maximum length: 100 characters
date_of_birth	Yes	Date	- Format: YYYY-MM-DD - Must be a valid date matching the format
start_number	Yes	String	- Must be alpha-numeric with dashes/underscores allowed (alpha_dash) - Maximum length: 100 characters
chip_code	Yes	String	- Must be exactly 7 characters long (this may be prefixed with leading zero’s)
gender	Optional	String	- Allowed values: male, female, neutral
state	Optional	String	- Must be one of the following: before, during, paused, resumed, after, finished, did_not_finish, disqualified, did_not_start
race_id	Yes	Integer	- Must be an integer

Sample Response #

{
    "data": {
        "id": 1,
        "unique_id": "1",
        "start_number": "1",
        "chip_code": "0000001",
        "event_id": 1,
        "race_id": 1,
        "first_name": "Kris",
        "last_name": "Kuiper",
        "full_name": "Kris Kuiper",
        "country_code": "nl",
        "team_name": null,
        "date_of_birth": "2001-01-01",
        "gender": null,
        "state": "before",
        "created_at": "2025-02-25 08:30:00",
        "updated_at": "2025-03-19 08:38:30"
    }
}

Response Fields #

Field	Type	Description
data	object	Participant data
id	int	Unique identifier of the participant
unique_id	string	External unique ID
start_number	string	Start number assigned to participant
chip_code	string	Chip code used for timing (7 characters)
event_id	int	Event ID associated with the race
race_id	int	Race ID the participant is registered for
first_name	string	First name of the participant
last_name	string	Last name of the participant
full_name	string	Full name (first_name + last_name)
country_code	string	ISO country code
team_name	string	Name of the participant’s team (nullable)
date_of_birth	string	Date of birth in YYYY-MM-DD format
gender	string	Gender of the participant (nullable, male, female, neutral)
state	string	Current state of the participant
created_at	string	Timestamp when the participant was created (YYYY-MM-DD HH:MM:SS)
updated_at	string	Timestamp when the participant was last updated (YYYY-MM-DD HH:MM:SS)

Error Handling #

Status Code	Meaning
200 OK	Request was successful
401 Unauthorized	Missing or invalid authentication token
403 Forbidden	Session Token does not have the required permission
422 Unprocessable Entity	Validation failed for one or more fields

Notes #

The request must include a valid session token.
The session token must have the permissions.participants.store permission.
The endpoint will insert or update a participant based on the unique_id.
The participant is linked to a specific race and its associated event, inferred via race_id.