Clubtab API

Getting a token

Sign in to Clubtab and open your account. Under Connect an app, give the app or device a name and choose what it can do:

• Read only: See teams, statements, the inbox and cash. It can’t change anything. Choose this for a spreadsheet that reports on your money.
• Read and write: Also record cash, confirm matches and add receipts.

You see each token once, so copy it straight away. Treat it like a password: anyone with it can do what you chose. Your account lists your tokens, with what each can do and when it was last used. If one is lost or shared, remove it under Connect an app, and make a new one. It stops working at once.

A token can only reach the teams you can reach in the app, and do what your role allows there. A club treasurer can read a team’s squad but not record its cash, just as in the app.

Making a call

Every address starts with https://app.clubtab.co.uk/api/v1. Send the token as a bearer token, and ask for JSON:

GET https://app.clubtab.co.uk/api/v1/teams
Authorization: Bearer YOUR_TOKEN
Accept: application/json

Start with GET /me to check the token works, then GET /teams to find the ids of your teams.

Money, dates and ids

• Money is whole pence, as a number: 1000 is £10.00. Money out is negative. When you send an amount, send pounds as text, like "10.00", just as you’d type it in the app.
• Ids are ULIDs, like 01j9z3k8m6q2t4v7x0b5c8d1e2: 26 lower-case letters and digits. Send them as you got them.
• Dates are YYYY-MM-DD.
• Field names in answers are camelCase, like amountPence. Fields you send are snake_case, like client_uuid, as in the app’s forms.

Each answer is the same data the app shows on that page, so a field means the same thing in both.

Changing things safely

Anything that changes money (recording cash, confirming a match, adding a receipt) is a write, sent as a POST. Every write needs two things:

• an Idempotency-Key header: a new UUID for each change you mean to make
• a client_uuid in the body: also a new UUID for each change. Most apps use the same UUID for both.

If a write times out, send it again with the same key, the same client_uuid and the same body. If the first one went through, you get its answer back, marked Idempotent-Replayed: true, and nothing is done twice. If it’s still being worked on, you get 409; wait a moment and send it again.

Use new UUIDs for each new change, even about the same thing, like each step of adding a receipt. Sending a key or client_uuid again with a different body, or to a different address, is refused with 422, so a mistake can’t replay another change’s answer.

Clubtab keeps the first answer for a day. After that, the client_uuid still stops money being recorded twice, but you may get an error rather than the first answer.

A read-only token gets 403 for any write.

When something goes wrong

Every answer that isn’t a success has a message to show or log.

Receipt photos

Photos never go through the API itself. To add one:

1. POST /teams/{team}/receipts/uploads with the photo’s extension, type and size. You get back a url, the headers to send with it and a path.
2. PUT the photo to that url, with those headers, within 15 minutes.
3. POST /teams/{team}/receipts with the path, and the transaction_id of the payment out it’s for if you know it. You get back the receipt’s id.
4. Clubtab reads the photo in the background. GET /teams/{team}/receipts/{id} shows what it read, and the payments out it could be for.
5. POST /teams/{team}/receipts/{id}/confirm with the supplier, total, date and payment out, once they’re right.

Receipts are on the Team and Club plans.

Limits

Each person can make 120 calls a minute, across all their tokens. Past that you get 429 until the minute is up. A spreadsheet that refreshes a few times an hour won’t come close.

What you can do

Addresses are under https://app.clubtab.co.uk/api/v1. {team}, {player} and the rest are ids.

You and your teams

The inbox

Cash

When a write makes a single cash entry (cash for a child, other cash, cash out or a reversal), its answer names it in transactionId, so you can reverse it or add its receipt later. Cash at training makes one entry per child, and banking and counting don’t make a cash entry, so for those it’s empty.

Squad, charges and requests

Receipts

The full reference

The OpenAPI description lists every call with what it takes and what it answers, field by field. It’s built from the API itself, so its routes and fields always match. Some fields are needed only with others, like a sponsor’s name; if one is missing, the 422 says which. Most API tools can read it to make a client for you.

Something missing, or not working as this says? Email [email protected].