Participants API — competitor records

A participant represents a competitor registered in PitPath Chrono. Each participant is linked to a license and stores personal details such as name, email, and phone number. You can also attach arbitrary extra fields via extraFieldsJson for organization-specific data. GET endpoints are public and require no authentication. POST and PATCH require a CRUD-level key.

POST /api/v1/participants is idempotent by licenseId. If a participant already exists for the given licenseId, the server returns the existing record with 200 OK instead of creating a duplicate. A new record returns 201 Created.

GET /api/v1/participants

Return all participants. Authentication: None required

curl --request GET \
  --url https://api.pitpath.de/api/v1/participants

The response is an array of participant objects.

string (UUID)

required

Unique identifier for the participant.

string (UUID)

required

UUID of the license this participant is linked to.

string

required

Human-readable name of the associated license.

string

required

Participant’s first name.

string

required

Participant’s last name.

string

required

Participant’s email address.

string

required

Participant’s phone number.

object

Arbitrary JSON object for organization-specific fields.

string (ISO 8601)

required

Timestamp when the participant was created.

string (ISO 8601)

required

Timestamp of the most recent update.

[
  {
    "id": "p1a2r3t4-i5c6-7890-abcd-ef1234567890",
    "licenseId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "licenseDisplayName": "Acme Racing Team",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "[email protected]",
    "phoneNumber": "+49 151 00000000",
    "extraFieldsJson": { "driverNumber": "42" },
    "createdAt": "2026-05-01T08:00:00Z",
    "updatedAt": "2026-05-01T08:00:00Z"
  }
]

GET /api/v1/participants/paged

Return a paginated list of participants, sorted by lastName ascending by default. Authentication: None required

number

default:"0"

Zero-based page number.

number

default:"20"

Number of participants per page.

string

default:"lastName"

Field to sort by, optionally followed by ,asc or ,desc.

curl --request GET \
  --url 'https://api.pitpath.de/api/v1/participants/paged?page=0&size=20&sort=lastName,asc'

Returns a page envelope with content, totalElements, totalPages, number, and size.

{
  "content": [
    {
      "id": "p1a2r3t4-i5c6-7890-abcd-ef1234567890",
      "licenseId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "licenseDisplayName": "Acme Racing Team",
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "[email protected]",
      "phoneNumber": "+49 151 00000000",
      "extraFieldsJson": {},
      "createdAt": "2026-05-01T08:00:00Z",
      "updatedAt": "2026-05-01T08:00:00Z"
    }
  ],
  "totalElements": 1,
  "totalPages": 1,
  "number": 0,
  "size": 20
}

GET /api/v1/participants/

Return a single participant by UUID. Authentication: None required

string (UUID)

required

UUID of the participant to retrieve.

curl --request GET \
  --url https://api.pitpath.de/api/v1/participants/p1a2r3t4-i5c6-7890-abcd-ef1234567890

Returns a single participant object with the same shape as items from GET /api/v1/participants.

{
  "id": "p1a2r3t4-i5c6-7890-abcd-ef1234567890",
  "licenseId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "licenseDisplayName": "Acme Racing Team",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "[email protected]",
  "phoneNumber": "+49 151 00000000",
  "extraFieldsJson": { "driverNumber": "42" },
  "createdAt": "2026-05-01T08:00:00Z",
  "updatedAt": "2026-05-01T08:00:00Z"
}

POST /api/v1/participants

Create a new participant. If a participant already exists for the given licenseId, the existing record is returned with 200 OK and no data is changed. A new record returns 201 Created. Required role: CRUD or higher

string (UUID)

required

UUID of the license to associate with this participant. This field drives the idempotency check.

string

required

Participant’s first name. Maximum 120 characters.

string

required

Participant’s last name. Maximum 120 characters.

string

required

Valid email address. Maximum 120 characters. Must match the pattern [email protected].

string

required

Phone number in any format. Maximum 120 characters.

string

JSON string containing arbitrary extra fields. The server parses and stores this as a JSON object.

curl --request POST \
  --url https://api.pitpath.de/api/v1/participants \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: ppk_your_api_key_here' \
  --data '{
    "licenseId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "[email protected]",
    "phoneNumber": "+49 151 00000000",
    "extraFieldsJson": "{\"driverNumber\":\"42\"}"
  }'

Returns 201 Created for a new participant, or 200 OK when the participant already exists.

{
  "id": "p1a2r3t4-i5c6-7890-abcd-ef1234567890",
  "licenseId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "licenseDisplayName": "Acme Racing Team",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "[email protected]",
  "phoneNumber": "+49 151 00000000",
  "extraFieldsJson": { "driverNumber": "42" },
  "createdAt": "2026-05-19T10:00:00Z",
  "updatedAt": "2026-05-19T10:00:00Z"
}

PATCH /api/v1/participants/

Update an existing participant. All fields are optional — only the fields you provide are changed. Required role: CRUD or higher

string (UUID)

required

UUID of the participant to update.

string (UUID)

Reassign the participant to a different license.

string

Updated first name. Maximum 120 characters.

string

Updated last name. Maximum 120 characters.

string

Updated email address. Maximum 120 characters.

string

Updated phone number. Maximum 120 characters.

object

Updated extra fields as a JSON object (not a string, unlike the POST body).

curl --request PATCH \
  --url https://api.pitpath.de/api/v1/participants/p1a2r3t4-i5c6-7890-abcd-ef1234567890 \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: ppk_your_api_key_here' \
  --data '{
    "email": "[email protected]"
  }'

Returns 200 OK with the updated participant object.

{
  "id": "p1a2r3t4-i5c6-7890-abcd-ef1234567890",
  "licenseId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "licenseDisplayName": "Acme Racing Team",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "[email protected]",
  "phoneNumber": "+49 151 00000000",
  "extraFieldsJson": { "driverNumber": "42" },
  "createdAt": "2026-05-19T10:00:00Z",
  "updatedAt": "2026-05-19T11:45:00Z"
}

Overview

Endpoints

Participants API — competitor records

GET /api/v1/participants

GET /api/v1/participants/paged

GET /api/v1/participants/

POST /api/v1/participants

PATCH /api/v1/participants/

​GET /api/v1/participants

​GET /api/v1/participants/paged

​GET /api/v1/participants/

​POST /api/v1/participants

​PATCH /api/v1/participants/

GET /api/v1/participants

GET /api/v1/participants/paged

GET /api/v1/participants/

POST /api/v1/participants

PATCH /api/v1/participants/