Booking platform data requirements

This is a quick overview of the booking data Authic needs to reward players in your clubs’ loyalty programs. We intentionally keep it short: we only ask for what is needed to award points correctly, never award them twice, and show players and clubs a clear activity history.

Field names don’t have to match ours. If your data is shaped differently, we map it on our side and provide the necessary help.

Delivery methods

We support two ways of receiving events. Both use the same data structure described in this document.

Nightly sync with API

Every night after 12 AM, usually around 2–3 AM in the club’s timezone, we send a request to your backend to fetch the events of the previous day. For example GET /events?startDate=DATE&endDate=DATE. The endpoint should support pagination for clubs with many events.

Webhooks

We can also listen to webhooks. Your system sends a POST request to an endpoint we provide as soon as an event is completed or cancelled. Webhooks are authenticated with the same tenant credentials used for user login (x-perks-tenant and x-perks-tenant-secret headers), so there are no extra keys to manage.

• Points are awarded in real time instead of the next morning.
• You can send one request per event with all participants, or one request per participant.
• Because we deduplicate on eventId, retries and repeated deliveries never award points twice.

curl -X POST https://api-perks.authic.io/v1/webhooks/<platform> \
     -H "x-perks-tenant: UNIQUE_UUID" \
     -H "x-perks-tenant-secret: UNIQUE_SECRET" \
     -H "Content-Type: application/json" \
     -d '{ ...event payload... }'
# Response: 200 OK

Note: The credentials and the webhook endpoint will be provided by us.

Data structure

Each event contains the event details and a list of its participants. The field names and values below are examples: they can differ per platform, and we map them on our side.

Event

• eventId (String): Unique id of the event or tournament, so the same event never earns points twice.
• eventName (String): The event’s name, shown to players in their activity history.
• clubId (String): A fixed club id, used to link the event to the club in our system.
• clubName (String): The club’s name, so the event is easy to recognise in the Authic dashboard.
• startDate / endDate (ISO 8601 datetime): When the event took place. Also used to work out its duration.
• status (String): scheduled, completed or cancelled. Only completed events earn points.
• eventType (String): The kind of event, so clubs can set different point rules per type. The values depend on your platform; for example booking, tournament, social, clinic or league.
• sport (String): The sport played (e.g. padel, tennis, pickleball), so multi-sport clubs can set point rules and challenges per sport.
• price (Number): Total price of the event, used for spend-based programs. We split it across participants.
• priceCurrency (String): ISO 4217 currency code (e.g. EUR), so prices are read correctly across countries.
• hostId (String): The host’s user id, used to award host points.
• participants (Array): The players who took part in the event (see below).

Participant

• userId (String): The player’s id on your platform. Our primary key to match the player to their Authic account.
• email (String): The player’s email, used as a fallback to match the player.
• name (String): The player’s name, used to greet them and to recognise members in the dashboard.
• isHost (Boolean): Whether this participant is the host.

Example payload

A completed court booking with two participants, one of them the host.

{
  "eventId": "evt_8f21c",
  "eventName": "Court 3 booking",
  "clubId": "club_102",
  "clubName": "Example Padel Club",
  "startDate": "2026-11-11T18:00:00Z",
  "endDate": "2026-11-11T20:00:00Z",
  "status": "completed",
  "eventType": "booking",
  "sport": "padel",
  "price": 48.00,
  "priceCurrency": "EUR",
  "hostId": "usr_441",
  "participants": [
    {
      "userId": "usr_441",
      "email": "jane.doe@example.com",
      "name": "Jane Doe",
      "isHost": true
    },
    {
      "userId": "usr_552",
      "email": "john.doe@example.com",
      "name": "John Doe",
      "isHost": false
    }
  ]
}

The data fields don’t have to have the same names. If custom work is required, we will provide the necessary help.