# Grupify for developers

Integrate registrations, results, payments and statistics of your events with Grupify's public API. REST, JSON, scoped API keys and an OpenAPI specification you can load into any client or agent.

## What you can do

- Read your organization's events and their configuration (distances, categories, prices).
- List paid participants and look them up by bib, chip or document.
- Query aggregate figures: registrations, revenue and breakdown by distance.
- List your organization's payments, one row per transaction.
- Upload results by bib, as JSON or CSV, from your timing system.

## Authentication

Every request carries an API key from your organization. You create it from the organization dashboard on the platform (Settings → API keys) with the scopes each integration needs. Send it as `Authorization: Bearer cok_live_…` or as `X-API-Key: cok_live_…`. Without a key the API answers 401; with a key that lacks the scope, 403 INSUFFICIENT_SCOPE.

Production keys start with `cok_live_`. Treat them as passwords: keep them out of front-ends and repositories.

## Quickstart in three calls

1. Create an API key in your organization dashboard with the `events:read` and `stats:read` scopes.
2. Store it in an environment variable, for example `COK`.
3. Run the calls below. Lists are paginated with `page` and `page_size`; errors come with a stable `code`.

```bash
# 1. Listar los eventos de tu organización
curl -s "https://api.grupify.app/public/v1/events?page=1&page_size=20" \
  -H "Authorization: Bearer $COK"

# 2. Estadísticas de un evento
curl -s "https://api.grupify.app/public/v1/events/EVENT_ID/stats" \
  -H "X-API-Key: $COK"

# 3. Buscar una inscripción por dorsal
curl -s "https://api.grupify.app/public/v1/events/EVENT_ID/participants/lookup?bib=1024" \
  -H "Authorization: Bearer $COK"
```

## Scopes

| Scope | Qué permite |
| --- | --- |
| `events:read` | The organization's events and their configuration. |
| `participants:read` | Paid participants: bib, category, document. This is PII. |
| `stats:read` | Aggregate figures per event: registrations, revenue, by distance. |
| `payments:read` | The organization's payments, one row per transaction. |
| `results:write` | Upload times by bib (JSON or CSV). The only write scope. |

## Test environment

There is no separate public sandbox today. We recommend creating a test organization on the platform and an API key with read-only scopes: none of them modify data. The only write scope, `results:write`, upserts by bib, so a repeated upload does not duplicate rows.

## Resources

- [API documentation](https://www.grupify.com/docs/api): Authentication, scopes, rate limits, error envelope and every endpoint with examples.
- [OpenAPI 3.1 specification](https://www.grupify.com/openapi.json): Generate clients, import into Postman, or hand it to an agent as its tool definitions.
- [llms.txt](https://www.grupify.com/llms.txt): What Grupify is, when to use it and how to call it, in the format language models read.
- [Markdown per route](https://www.grupify.com/md/en/developers.md): Every public page also exists as text/markdown: request it with `Accept: text/markdown` or at /md/{es,en}/…

API base URL: `https://api.grupify.app`

---

HTML version: https://www.grupify.com/en/developers · Agent guide: https://www.grupify.com/llms.txt · API: https://www.grupify.com/openapi.json · GRUPIFY S.A.S. (tax ID 901929426), Bucaramanga, Colombia.