---
title: "Ticket Fairy Organizer API | Create Events, Read Sales, Copy Setups"
description: "Create events with safe retries, read sales by day and ticket type, and copy one event's setup to another. Operations, headers, errors and limits."
canonical: "https://www.ticketfairy.com/developers/organiser-api"
---

Ticket Fairy developer documentation

# Create and manage events with the organizer API

Create events, read sales by day and by ticket type, copy the setup of last year's edition into this year's, hand a draft event to an organizer, and sign up new organizers from your platform. A request with a token acts as the person who owns it, with their team role.

  [See the operations](#operations) [Open the OpenAPI description](https://www.theticketfairy.com/api/openapi.json)

You need a token first. The [authentication documentation](https://www.ticketfairy.com/developers/authentication) shows how to get one.

     Read an event's sales

```
$ curl 'https://www.theticketfairy.com/api/events/EVENT_ID/relationships/performance?section=sales|release_breakdown' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/vnd.api+json'
```

## Every request

- The base address is `https://www.theticketfairy.com/api/`.
- Send `Authorization: Bearer YOUR_TOKEN`.
- Send `Accept: application/vnd.api+json`. Without it, some addresses answer 400 with `NOT_LOGGED_IN`.
- An error answer has a plain-language `message` and, where it helps, a `code` to branch on.
- Too many requests get 429 with a `Retry-After` header.

## Operations

The [organizer API description](https://www.theticketfairy.com/api/openapi.json) holds every field of each request and answer, in OpenAPI 3.1.

| Operation | Request | What it does |
| --- | --- | --- |
| `createEvent` | `POST /api/events` | Create an event |
| `getEventSales` | `GET /api/events/{eventId}/relationships/performance` | Get an event's sales |
| `listSetupCopySources` | `GET /api/event/{eventId}/setup-copy/sources` | Find an event to copy from |
| `previewSetupCopy` | `GET /api/event/{eventId}/setup-copy/preview` | Preview a setup copy |
| `startSetupCopy` | `POST /api/event/{eventId}/setup-copy/runs` | Copy another event's setup |
| `getSetupCopyRun` | `GET /api/event/{eventId}/setup-copy/runs/{runId}` | Follow a setup copy |

## Create an event, with safe retries

A draft needs only a name and `flagDraft: true`. A complete event also needs its dates, sales end date, currency and venue. You need the admin or owner role on the brand.

    Create a draft event

```
$ curl -X POST 'https://www.theticketfairy.com/api/events' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Idempotency-Key: 6f1c2a9e-1d4b-4c55-9a39-0f6f2f4e8b10' \
  -d '{"data": {"type": "event", "attributes": {"displayName": "Summer Festival 2027", "flagDraft": true}, "relationships": {"owner": {"data": {"id": "BRAND_ID"}}}}}'
```

### The Idempotency-Key header

Send a new unique value, such as a UUID, in `Idempotency-Key` with each new event. If the network fails and you send the same request again with the same key within 24 hours, you get the first answer again, with `Idempotent-Replayed: true`, and no second event. A key can be at most 255 bytes.

| Status | What it means |
| --- | --- |
| 200 | The event was created. |
| 400 | The Idempotency-Key is longer than 255 bytes. |
| 401 | No valid token was sent. |
| 403 | You do not have the admin or owner role on this brand. |
| 410 | This Idempotency-Key was already used with a different body or endpoint. Use a new key. |
| 422 | The request is not valid, for example a missing field, a name with a blocked word, or an online event, which cannot be created here. The message names the first problem. |
| 429 | Too many events were created from this address, or a request with the same Idempotency-Key is still running. Wait for the number of seconds in Retry-After. After a rate limit, send the request again with a new Idempotency-Key. |

## Copy another event's setup in the background

A setup copy brings the stages, departments, rota and other parts of an earlier event, usually last year's edition, into a new one. It needs the Event Management feature on the brand.

1. Find the event to copy from with `listSetupCopySources`. The likely previous edition comes first.
2. Show the person the result of `previewSetupCopy`, and let them choose the parts to copy.
3. Start the copy with `startSetupCopy`. Send a `request_key` of 8 to 64 letters, digits, hyphens or underscores, so that a retry does not start a second copy.
4. The answer is 202 with the run's address in the `Location` header. GET that address every few seconds until the status is `done`, `partly_done` or `failed`.

   Start a setup copy

```
$ curl -i -X POST 'https://www.theticketfairy.com/api/event/EVENT_ID/setup-copy/runs' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/json' \
  -d '{"source_event_id": 12345, "request_key": "copy-summer-2027"}'
```

| Status | What it means |
| --- | --- |
| 202 | The copy is queued or running. Follow it at the Location address. |
| 200 | The copy is not running, in one of two cases. This request\_key was already used for the same copy and that copy has finished: the body is that run. Or the copy could not be queued: the status is failed with error\_code not\_started, nothing was copied, and allowed\_actions.copy\_again is true, so start it again later with a new request\_key. |
| 400 | The request\_key is missing or not 8 to 64 letters, digits, hyphens or underscores (request\_key\_required), a part name is not valid (parts\_invalid), or the event to copy from is this event (source\_invalid). |
| 401 | No valid token was sent. |
| 403 | The brand does not have the Event Management feature, or you do not have the owner, admin or producer role on this event or the event to copy from (not\_allowed). |
| 404 | No event has this ID (event\_not\_found), or the event to copy from is not an event of the same brand (source\_not\_found). |
| 409 | This request\_key was already used for a different copy (request\_key\_reused), or a copy into this event is still running (copy\_in\_progress). data is that earlier run. For copy\_in\_progress, follow it, then start again. |
| 429 | More than 20 start requests were sent in a minute, whether or not they started a copy. Wait for the number of seconds in Retry-After. |

## Hand a draft event to an organizer

Your agent prepares the event, and the organizer takes it over without typing anything again. No account and no personal details are needed.

1. Create a draft with `POST https://www.theticketfairy.com/api/guest-event-drafts`, with the event name, dates, venue, type, age limit and description. Keep the draft token from the answer.
2. Ask for a handoff with `POST .../guest-event-drafts/{draft_id}/handoff` and the draft token. The answer is a link for the organizer, valid for 72 hours. Asking again replaces the earlier link.
3. The organizer opens the link, checks the details, and signs up or signs in. The event becomes theirs, under their brand.

When the organizer opens the link, your draft token stops working, so the draft cannot change after they take it. The link carries only the details the organizer sees on the page.

## Sign up new organizers from your platform

A platform with an application credential starts the signup, and the person finishes it in their browser: they sign in, accept the terms, choose their brand and choose how to get paid. Your agent never sees their payout details. A signup has 30 minutes to reach the payout step.

The base address is `https://www.theticketfairy.com/api/agent/organizer/v1/onboardings`. Send these headers with every request:

| Header | Value |
| --- | --- |
| `Authorization` | Bearer agc\_..., an application credential with the agentic-organizer grant |
| `Ticket-Fairy-Organizer-Version` | 2026-09-10 |
| `Idempotency-Key` | 1 to 255 visible characters. Repeat the exact key and body to retry; a changed body under the same key is refused. |
| `Agent-Return-Origin` | An HTTPS origin registered for your platform |

| Request | What it does |
| --- | --- |
| `POST /` | Start a signup, with the brand details and an optional draft event to prefill. The answer has setup\_url for the person, and a resume capability to keep secret. |
| `POST /{id}/resume` | Read where the signup is and what it waits for, in next\_action. |
| `POST /{id}/cancel` | Cancel the signup before a brand exists. |
| `POST /{id}/consume` | Collect the result of the account link, once. |
| `POST /{id}/payout` | Record how the person wants to be paid: bank, stripe, xendit, or skip with skip\_confirmed. |

Pass the `revision` from each answer as `expected_revision` in your next change. When the signup completes, the answer has the brand, the payout status, and the address of the new event for the person to finish. The [authentication documentation](https://www.ticketfairy.com/developers/authentication#application-credentials) explains application credentials.

### Through Stripe Projects

A developer who uses Stripe Projects can add Ticket Fairy as a provider. Stripe confirms the person, and Ticket Fairy creates their account and first organizer workspace on the free plan.

## Limits

| Operation | Requests allowed |
| --- | --- |
| Create an event | 120 an hour from each address |
| Find an event to copy from | 120 a minute |
| Start a setup copy | 20 a minute |
| Ask for a draft handoff link | 30 an hour from each network, with a separate limit for each agent that signs its requests |
| Open a draft handoff link | 60 an hour from each network |

## More ways to work with your events

- The hosted organizer MCP server gives an AI assistant the same organizer tools that Fai uses. The person signs in and approves it in their browser, and the assistant can do only what their team role allows. See the [AI agents documentation](https://www.ticketfairy.com/developers/ai-agents#mcp).
- The [Ticket Fairy CLI](https://www.ticketfairy.com/cli) covers events, ticket types, orders, customers, promotions, invitations, check-in, webhooks and team from the command line, and its `ticketfairy api` command calls any organizer address with your sign-in attached.
- The Python and Go API clients on the [developer documentation](https://www.ticketfairy.com/developers#sdks) page wrap these operations.
- [Order webhooks](https://www.ticketfairy.com/developers/webhooks) send each order to your own address as it changes.

Ticket Fairy in full: [online ticketing system](https://www.ticketfairy.com/event-ticketing/), with the features, pricing and support behind this page.

## Further Reading

  [**Authentication** Personal Access Tokens, agent approval and OAuth.](https://www.ticketfairy.com/developers/authentication) [**Order webhooks** Receive every order at your own address as it changes.](https://www.ticketfairy.com/developers/webhooks) [**Ticket Fairy CLI** Manage events from the terminal or a script.](https://www.ticketfairy.com/cli)

## Questions about the organizer API?

Email [support@theticketfairy.com](mailto:support@theticketfairy.com) with the request you sent and the answer you got. Leave your token out.

  [Get a token](https://www.ticketfairy.com/developers/authentication) [Open the OpenAPI description](https://www.theticketfairy.com/api/openapi.json)

---

This page is on Ticket Fairy, a ticketing, marketing and operations platform for live events and the venues that host them: festivals, club nights, concerts, conferences and tours, and night clubs, beach clubs and concert venues. It grows revenue with fan rewards that turn an audience into a sales channel, and runs the money side with payments and payouts, Vault business banking, and working capital advanced against ticket sales. [How Ticket Fairy ticketing works](https://www.ticketfairy.com/event-ticketing) · [Ticket Fairy for AI assistants](https://www.ticketfairy.com/llms.txt)