> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rocky.global/llms.txt
> Use this file to discover all available pages before exploring further.

# Timing integration

# Timing integration (API)

This guide explains how to connect Rocky Global with third-party timing platforms (Chronotrack, MyLaps, and future integrations) using the participants API.

## Design principle

Rocky Global uses the **bib number (BIB)** as the participant's primary identifier during check-in and operational exports. Mapping to external timing chip numbers is handled **outside the check-in flow**, typically by adding an extra column in Excel when exporting participants.

This avoids duplicate records and keeps a single source of truth for registrations and kit delivery.

## Authentication

The API uses **Bearer Token** (Laravel Sanctum) with scope `organizer-api` or `supervisor-api`.

```bash theme={null}
curl -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  "https://YOUR_DOMAIN/api/v1/organizer/participants?event_id=456&per_page=2000"
```

See [Enable API access](/en/roles/organizador/api-organizador) and [Organizer API](/en/apis/organizer-api).

## Timing-relevant endpoints

### GET /api/v1/organizer/participants

Returns participants for the authenticated organizer. Useful filters for timing:

| Parameter           | Use                                       |
| ------------------- | ----------------------------------------- |
| `event_id`          | Limit to one event                        |
| `bib`               | Search by bib number                      |
| `status`            | Filter by registration status             |
| `per_page`          | Page size (up to configured maximum)      |
| `pagination=cursor` | Cursor pagination for large events (20k+) |

Relevant returned fields (via `ParticipantResource`):

* `id` — Internal participant ID
* `bib` — Bib number
* `locator` — Registration locator (unchanged on transfers)
* `details` — Form data (name, ID, gender, category, etc.)
* `competition_results` — Competition results (JSON, if already loaded)
* `observations` / `participation_notes` — Operational notes

### POST /api/v1/organizer/participants

Bulk participant updates. Fields allowed for timing providers:

* `bib` — Adjust bib if the external provider renumbered
* `competition_results` — Load times, positions, splits (JSON)
* `observations` / `participation_notes` — Notes
* `details` — Additional fields (e.g. `chip_id` column)

**Forbidden** fields (rejected): `evento_id`, `locator`, `order_id`, `user_id`, `status`.

```bash theme={null}
curl -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{
    "updates": [
      {
        "id": 123,
        "competition_results": {
          "chip_time": "00:45:12",
          "gun_time": "00:45:18",
          "overall_position": 42
        },
        "details": {
          "chip_id": "CT-987654"
        }
      }
    ]
  }' \
  "https://YOUR_DOMAIN/api/v1/organizer/participants"
```

For batches over 1000 records, the API returns `202 Accepted` and processes in the background.

## Recommended Chronotrack flow

```mermaid theme={null}
sequenceDiagram
    participant RG as Rocky Global
    participant API as Participants API
    participant CT as Chronotrack

    RG->>API: GET participants (event_id, bib, details)
    API-->>CT: Export / sync (bib, name, category)
    Note over CT: Race + chip reads
    CT->>API: POST competition_results + chip_id
    API-->>RG: Results available in platform
```

1. **Before the event:** export participants with assigned bibs via API or Excel.
2. **In Chronotrack:** import the list using the bib as the primary key.
3. **After the race:** send times and positions back with `POST /participants`, mapping `chip_id` in `details` if needed.

## Excel export flow (without API)

If you prefer not to integrate via API:

1. Export participants from **Registrations** or **Reports**.
2. Add a `chip_id` column (or similar) for the timing provider.
3. After the race, import results manually or via API POST.

## Security considerations

* API tokens are restricted to the token owner's `organizador_id`.
* Optional: IP allowlist in `organizer_api_settings`.
* Configurable rate limit (default 60 req/min).
* Every request is logged in API usage logs.

## Support for new integrations

For **MyLaps** or other platforms, the same API contract applies: bib as key, `competition_results` for times, `details` for chip metadata.

Contact [soporte@rocky.global](mailto:soporte@rocky.global) if you need help with a specific connector or volumes above 20,000 participants.

## References

* [Organizer API](/en/apis/organizer-api)
* [Bib assignment](/en/roles/organizador/gestion-participantes)
* [Event check-in](/en/roles/organizador/gestion-participantes)