Agency API v1

Connect your booking system to Find the Act. Keep your acts, availability and enquiry stages in sync automatically.

Basics

Base URL: https://findtheact.co.uk/api/v1
Auth: Authorization: Bearer fta_live_…. Create keys in the agency dashboard under API. Keys are shown once and stored only as a hash. Scopes: acts:read, acts:write, availability:write, enquiries:read, enquiries:write, webhooks:manage.
Rate limit: 120 requests per minute per key (headers x-ratelimit-remaining and retry-after).
Idempotency: send Idempotency-Key on writes. A repeat within 24 hours returns the original response.
Errors: {"ok":false,"error":{"code","message","details"}} with 400/401/403/404/409/413/422/429.
Audit: every call is logged (method, path, status, time) and visible in your dashboard.

Endpoints

Method	Path	What it does
`GET`	`/me`	Who am I (agency, key scopes)
`GET`	`/categories`	List act category slugs
`GET`	`/acts`	List your acts Requires scope `acts:read`.
`GET`	`/acts/{ref}`	Get one act Requires scope `acts:read`.
`PUT`	`/acts/{ref}`	Create or update an act (upsert by external_ref) Creates the act if the external_ref is new (category required); otherwise updates the supplied fields. `media`, if supplied, replaces the act's media list. Requires scope `acts:write`.
`GET`	`/acts/{ref}/availability`	List upcoming dates Requires scope `acts:read`.
`PUT`	`/acts/{ref}/availability`	Bulk upsert dates (optionally replace all API-sourced dates) Requires scope `availability:write`.
`POST`	`/acts/{ref}/availability`	Bulk upsert dates Requires scope `availability:write`.
`GET`	`/enquiries`	List enquiries Requires scope `enquiries:read`.
`GET`	`/enquiries/{id}`	Get one enquiry Requires scope `enquiries:read`.
`PATCH`	`/enquiries/{id}`	Update stage and/or notes Requires scope `enquiries:write`.
`GET`	`/webhooks`	List webhooks Requires scope `webhooks:manage`.
`POST`	`/webhooks`	Create a webhook (returns signing secret once) Requires scope `webhooks:manage`.
`DELETE`	`/webhooks/{id}`	Delete a webhook Requires scope `webhooks:manage`.
`POST`	`/webhooks/{id}/test`	Queue a ping delivery Requires scope `webhooks:manage`.

Examples

Check your key

curl https://findtheact.co.uk/api/v1/me \
  -H "Authorization: Bearer $FTA_KEY"

Create or update an act

curl -X PUT https://findtheact.co.uk/api/v1/acts/my-act-001 \
  -H "Authorization: Bearer $FTA_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: act-001-2026-10-14" \
  -d '{"name":"The Velvet Tones","category":"bands","tagline":"Soul & Motown party band","bio":"…","town":"Leeds","travels_nationwide":true,"price_from":1200,"price_to":1800,
       "media":[{"kind":"video","url":"https://www.youtube.com/watch?v=XXXXXXXXXXX"},{"kind":"image","url":"https://example.com/band.jpg"}],
       "substitution_policy":"Like-for-like replacement or full refund, your choice","cancellation_policy":"…","deposit_terms":"25% to confirm"}'

Push availability (bulk)

curl -X PUT https://findtheact.co.uk/api/v1/acts/my-act-001/availability \
  -H "Authorization: Bearer $FTA_KEY" -H "Content-Type: application/json" \
  -d '{"replace":true,"dates":[{"date":"2026-12-12","status":"booked"},{"date":"2026-12-19","status":"free"}]}'

New enquiries since yesterday

curl "https://findtheact.co.uk/api/v1/enquiries?status=new&since=2026-10-13T00:00:00Z" \
  -H "Authorization: Bearer $FTA_KEY"

Move an enquiry to quoted

curl -X PATCH https://findtheact.co.uk/api/v1/enquiries/123 \
  -H "Authorization: Bearer $FTA_KEY" -H "Content-Type: application/json" \
  -d '{"status":"quoted","notes":"Sent 2 options"}'

Register a webhook

curl -X POST https://findtheact.co.uk/api/v1/webhooks \
  -H "Authorization: Bearer $FTA_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://youragency.example/hooks/fta"}'

Webhooks

Event enquiry.created is POSTed to your HTTPS URL as JSON {id, event, created_at, data:{enquiry}}, with headers X-FTA-Event, X-FTA-Delivery and X-FTA-Signature: t=…,v1=… (HMAC-SHA256 of t + "." + rawBody using your whsec_ secret). Reply 2xx within 8 seconds. Failed deliveries retry after 1, 5, 30, 120, 720 and 1,440 minutes.

// Node.js: verify X-FTA-Signature
import crypto from 'node:crypto';
function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map(p => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // 5-minute replay window
  const mac = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(v1));
}

No-code alternative: iCal

If your diary is in Google, Apple or Outlook calendar, or your booking system exports an iCal feed, add the feed URL to each act (dashboard → My acts → iCal feed URL, or ical_url via the API). We import booked dates every 6 hours.

Already on a booking platform?

Find the Act also supports pull integrations. Flair Entertainments' diary syncs from Find the Act Booking automatically. Talk to us about connecting yours.