Skip to content
Developers4 min readUpdated October 27, 2026

API overview

Quick answer

ScrambleSync provides a versioned REST API at https://scramblesync.com/api/v1. It lets your systems read and manage contacts, tournaments, teams, the live leaderboard, registrations, invitations, and webhooks, all over OAuth 2.0 Bearer tokens. The full interactive reference is at scramblesync.com/developers/reference.

On this page

Overview

Our REST API lets your own systems read and update your ScrambleSync data: contacts, events, teams, scores, registrations, invitations and more.

Who this is for

Developers building an integration, and admins deciding whether the API fits what they need.

Base URL and versioning

All API endpoints are under https://scramblesync.com/api/v1. The version segment is part of the URL so future breaking changes can be introduced under a new version without disrupting existing integrations.

What the API can do

ResourceWhat you can do
Contacts & tagsList, create, update, delete contacts; bulk import; export CSV; manage tags.
TournamentsList and read tournaments; change status; read teams and leaderboard.
ScoresRead per-team hole scores.
RegistrationsList and export registrations; issue refunds.
InvitationsCreate, schedule, and read invitations; pull delivery stats.
WebhooksCreate, update, delete, and replay webhook endpoints; read delivery history.
Side games / contestsRead brackets, raffles, auctions, announcements, RSVPs, series standings, scorecards, flights.
Live-day writesCheck in teams/players; move teams; send messages; record bracket results; draw raffle winners; correct scores (with appropriate scopes).

Authentication

The API uses OAuth 2.0 client credentials. You create an API client in Settings → API access, obtain a Bearer token, then pass it on every request.

  1. Open API access

    Click API access in the top bar of your dashboard. Only admins see it. It opens Settings → API access.

  2. Create a client

    Under Create API client, name it, tick its scopes and click Create client. Copy the secret right away. It's shown once.

  3. Get a token

    POST to https://scramblesync.com/api/v1/oauth/token with grant_type=client_credentials and your client ID and secret (HTTP Basic or JSON body). The access_token lasts 1 hour.

  4. Call the API

    Send Authorization: Bearer <access_token> on every request. When it expires, ask for a new one.

Create API client form with a sample name and scopes
1. Client name 2. Scopes (tick only what you need) 3. Create client.

Scopes

A token only carries the scopes its client was granted. Request a subset at token time with a space-delimited scope parameter; omit it to receive all of the client's scopes. A call that lacks a required scope returns 403 insufficient_scope.

ScopeWhat it grants
contacts:readRead contacts & tags
contacts:writeCreate, edit, import & delete contacts & tags
registrations:readRead & export registrations
registrations:writeRefund & cancel registrations (issues Stripe refunds)
invitations:readRead invitations & delivery stats
invitations:writeCreate & schedule invitations
tournaments:readRead tournaments, teams & leaderboard
tournaments:writeEdit event details, scoring & holes, and change event status (Setup / Open / Live / Final / Archived)
webhooks:readRead webhook endpoints & deliveries
webhooks:writeCreate, edit, delete & replay webhooks
teams:writeMove or remove teams (live day)
checkin:writeCheck teams & players in
messages:writeSend broadcast messages
scores:writeCorrect team & player hole scores
sidegames:writeAdd, edit & remove side games / contests
players:writeEdit player details (shirt size, cart, etc.)
brackets:readRead match-play brackets and match results
brackets:writeRecord match-play results & advance brackets
raffles:readRead raffles, prizes & ticket counts
raffles:writeDraw raffle winners
auctions:readRead auction items & current bids
announcements:readRead announcements & delivery status
announcements:writeCreate & send announcements
contests:readRead contest-hole leaders (closest-to-pin, longest drive)
flights:readRead per-flight standings
scorecards:readRead per-team hole-by-hole scorecards
rsvps:readRead RSVP responses
series:readRead series / season standings
audit:readRead the tournament audit log

Pagination

List endpoints are cursor-paginated. Each response has the shape { "data": [...], "page": { "next_cursor": "..."|null, "has_more": true|false } }. Pass ?cursor=<next_cursor>&limit=<1 to 200> to fetch the next page. The default limit is 50; the maximum is 200.

Error format

All non-2xx responses share one shape: { "error": "human message", "code": "snake_case_code", "request_id": "uuid" }. Every response also carries an X-Request-Id header, include it when contacting support. Common codes: invalid_token (401), insufficient_scope (403), not_found (404), validation_error (400), conflict (409), rate_limited (429).

Rate limiting

Approximately 600 requests per minute per API client. Exceeding the limit returns 429 with a Retry-After header in seconds. The limit is per client, not per IP.

Idempotency

POST requests accept an Idempotency-Key header (up to 128 characters). Replaying the same key returns the original response; reusing a key with a different body returns 409 conflict.

Full reference

The interactive OpenAPI reference, with live try-it-out for every endpoint, is at scramblesync.com/developers/reference. The raw spec is at scramblesync.com/openapi.yaml.

Developer landing page
The developer landing page at scramblesync.com/developers links to the full reference.

Tips

  • Start with read-only scopes while you build, then add write scopes when you need them.
  • Log the X-Request-Id header. It's the fastest way for us to find a request when you email [email protected].

Troubleshooting

If you see thisTry this
401 invalid_tokenThe token expired after an hour or the client was disabled. Request a new token.
403 insufficient_scopeThe client doesn't have the scope that endpoint needs. Create a new client with the scope you need, then switch your integration over.
429 rate_limitedWait the number of seconds in Retry-After, then try again.

Frequently asked questions

Do tokens expire?

Yes. Access tokens are valid for 1 hour (3600 seconds). Request a new token using your client credentials when the current one expires. Tokens can also be revoked by deleting the API client.

Can I use the API without creating a client?

No. Every API call requires a Bearer token obtained from an API client. Create one in Settings → API access.

Is the API tenant-isolated?

Yes. Every client belongs to one organization and tokens only ever see that organization's data, there is no way for a token to access another org's tournaments or contacts.

Where is the interactive docs?

At scramblesync.com/developers/reference, powered by Scalar, with live try-it-out for every endpoint. (scramblesync.com/developers is the developer landing page.)

Where do I create a client?

Click API access in the top bar of your dashboard. Only admins see it.