> ## Documentation Index > Fetch the complete documentation index at: https://docs.animo.co/llms.txt > Use this file to discover all available pages before exploring further. # For ai agents # Animo for AI agents **Read this first — before writing any code.** This guide is for AI coding agents (Claude and others) asked to build, set up, or operate events with Animo. Its purpose is to keep you from rebuilding things Animo already does. Animo is a complete events platform: ticketing, payments (Mollie), VAT, invoicing, attendee CRM, lifecycle emails, approval workflows, QR check-in, and hosted event & registration pages all exist and are battle-tested. **Your job is to orchestrate and present — not to reimplement the platform.** If you read nothing else, read the contract below. *** ## The contract > **You are integrating with Animo, an events platform that already handles ticketing, payments (Mollie), VAT, invoicing, attendee CRM, confirmation/lifecycle emails, approval workflows, QR check-in, and hosted event & form pages. Orchestrate and present — do not rebuild these.** > > ### Never build > > Payment or checkout flows · VAT/tax calculation · invoicing · ticket issuance, QR codes, or door scanning · attendee or lead storage · confirmation/lifecycle emails · custom forms that submit into Animo. > > ### Decide with one question — *what is this thing?* > > | The thing is… | Rule | Who builds it | > | --------------------------------------------------------------------------------------- | ------------------------------------------------------- | ---------------------- | > | **Money** — tickets, payment, refunds, VAT, invoices | Always Animo-hosted. Link or embed. | Animo | > | **Data of record** — registrations, leads, sponsorship / waitlist / contact submissions | Animo-hosted form or activation, **embedded or linked** | Animo hosts, you frame | > | **Presentation** — marketing pages, schedules, speaker bios, calendars | Build freely; pull content via `GET` | You | > > ### Two supported modes > > 1. **Fully Managed** — you call the API to set up and operate; Animo hosts everything the attendee sees. **This is the default. Start here.** > 2. **Custom Site + Animo Checkout** — you build the marketing site; every money and data-of-record path links or embeds to Animo. > > ### Not supported — do not attempt > > Your own payment UI or Mollie integration · completing payment outside Animo's hosted checkout ("headless paid") · custom-built forms that POST submissions or leads into Animo · polling for leads/submissions. There is no submission/lead ingest endpoint and no checkout URL for completing payment yourself. **If a requirement seems to need one of these, stop and surface the limitation — do not code around it.** ### Supported patterns at a glance | Pattern | OK? | | ------------------------------------------------------------------------------------- | --- | | API setup + link to hosted ticket/checkout pages | ✅ | | API `orders/create` (paid ticket) **+ redirect attendee to** `/o/{order-id}/checkout` | ✅ | | API form definitions (`POST /forms/create`) + attach `form_id` to ticket types | ✅ | | Custom site + `GET` for display + links to Animo | ✅ | | Webhook receiver that persists events | ✅ | | Your own payment form or direct Mollie integration | ❌ | | Custom form POSTing submissions/leads into Animo | ❌ | | Polling the API for leads/submissions (no `GET` — use webhooks) | ❌ | **On paid registration:** creating an order via the API and sending the attendee to Animo's hosted checkout is *supported orchestration*, not "building checkout." Don't avoid `orders/create` for paid tickets — use it, then redirect to `/o/{order-id}/checkout`. What's forbidden is collecting payment yourself. "Headless paid orders" means *completing payment outside Animo's hosted checkout* — that path has no checkout URL, not API-driven paid registration. **On forms:** *defining* a form via the Forms API (`POST /forms/create`) and attaching it to a ticket type is supported and encouraged. *Collecting answers* on your own frontend and posting them into Animo is not — answers are captured on the hosted ticket/activation flow. ### Why the money path is off-limits Animo's price is a function of `ticket count × customer type (business vs. consumer) × country × online-vs-in-person`. That is tax law encoded in software. Reimplementing it produces invoices that are confidently wrong in ways nobody catches until one is disputed. The same logic extends to data of record: there is no API to write a submission or lead into Animo, so any "custom form that posts to Animo" is a fragile bridge across a gap that does not exist. **Hosted-and-linked is not a limitation to work around — it is the correct architecture.** *** ## Before you call the API First-contact gotchas documented elsewhere that bite agents who only read this file: * **Pro plan required.** Without it, `GET /api/v1/companies` returns `200` with an **empty** `data` array — not a `403`. An empty list means "no Pro plan," not "bad token." See [API index — Plan requirement](index.md#plan-requirement). * **`{company}` in API paths is a sqid; public URLs use slugs.** Don't interchange them — get the sqid from `GET /api/v1/companies`, build public URLs from the `slug` fields. See [Conventions — Public URLs](conventions.md#public-urls). * **Paid ticket public pages 404 until Mollie is connected.** A paid ticket type with no connected payment provider has no working signup page. * **Event `slug` is ignored on create** — it's derived from `name`. Use the `id` from the create response; `PATCH` the slug afterward if you need a specific one. *** ## The two supported modes ### Mode 1 — Fully Managed (default) You call the API; Animo hosts the entire attendee experience. * **You build:** no separate site. You orchestrate API calls to set up and run the event. You still shape what attendees see *through the API* — event page copy, ticket types, pricing, email templates — you just don't build a frontend. * **Animo owns:** event page, ticket shop, checkout, payments, forms, emails, approvals, scanning — everything. * **Best for:** private or marketing events, individuals, fast turnaround, anyone without a hard branding requirement. * **Attendees go to:** the hosted event page — `https://app.animo.co/{company-slug}/event/{event-slug}`. Start here. Only climb to Mode 2 when there is a **hard branding or domain requirement** the hosted page cannot meet. ### Mode 2 — Custom Site + Animo Checkout You build the marketing site on your own design and domain; every money and data-of-record path links or embeds to Animo. * **You build:** marketing/landing pages, schedules, speaker bios, a calendar — all *presentation*, populated via `GET`. * **Animo owns:** the entire money path (ticket pages, checkout, payments, VAT, invoices) and the entire data-of-record path (hosted forms/activations for sponsorship, waitlist, contact). * **Best for:** professional or paid public events that need a bespoke brand. * **How you connect to Animo:** * **Tickets** → link to the hosted ticket signup page: `https://app.animo.co/{company-slug}/event/{event-slug}/{ticket-type-slug}` (append `?qty=1` to pre-select quantity). See [Conventions — Public URLs](conventions.md#public-urls). * **Forms** (sponsorship, waitlist, contact) → embed or link the **Animo-hosted activation**. Get the activation `slug` from `GET /api/v1/{company}/activations` and link to the company-scoped URL `https://app.animo.co/{company-slug}/{activation-slug}` (the default — always works for published activations). Link to that **base URL, not `/form`** — `/form` is where attendees land *after* sign-up, not a cold-traffic entry point. See [Conventions — Activation form page](conventions.md#activation-form-page) for the event-scoped variant. Do **not** build a custom form that posts into Animo — see [Known API gaps](index.md#known-api-gaps). The API does not return public URLs in responses; build them from slugs per [Conventions — Public URLs](conventions.md#public-urls). *** ## What the AI's job actually is Setup is only one of several jobs. These are orthogonal to the two modes above — any of them applies on top of either mode. Most real engagements are one or two of these, not all five. ### Operate — ongoing, no building (highest value, lowest cost) The AI as an **ops console**, not a builder. Approve or reject pending registrations, monitor sign-ups, pull attendee lists, shift event dates, swap copy on pages and emails. This is the cheapest and most common mode — reach for it before assuming a setup or build task. * Read events, ticket types, orders. * `PATCH` events (dates, details), ticket types, orders (approve/reject). * `PATCH` comms templates to update email copy; `PATCH`/`POST` event pages to update content. Customize Animo's templates — don't send parallel lifecycle emails from your own app; Animo already sends them. ### Provision — one-time setup Create events, ticket types, forms, and pages from a spec. Build the structure, attach forms to ticket types, set up comms templates, then hand off to Operate. ### Integrate — webhook-driven On `form-submitted`, `activation-submitted`, `lead-created`, `meeting-booked`, etc., route the event to Slack / Sheets / CRM / email. The AI builds a thin **receiver**, not a site. > **Important:** there is no `GET` backfill for leads, submissions, or meetings. Webhooks are the *only* way to obtain this data — you **must persist** every webhook event when it arrives. See [Webhooks](endpoints/webhooks.md). ### Sync / pull — Animo as source of truth → your site The inverse of Provision: read events, ticket types, and pages, then generate or refresh a static site, calendar, or directory from them. Great for multi-event calendars. ### Bulk / templated — one spec → many events Recurring series, multi-vertical programs, franchise/decentralized editions. One spec fans out to many events via repeated Provision calls. *** ## Prompt recipes Copy-paste starting prompts for each job. Adjust names, dates, and the company sqid. ### Operate — approve pending registrations ``` Using the Animo API for company {sqid}, list pending orders for the organizing event "{event}". Show me each registrant's name and ticket type, and approve the ones from a company domain. Don't reimplement any email — Animo sends the approval email. ``` ### Provision — set up a new event ``` Create an event "{name}" on {date} in Animo for company {sqid}. Add ticket types: {list}. For any paid ticket, the attendee pays through Animo's hosted checkout — do not build a payment flow. Give me the hosted event URL and the ticket signup URLs when done. ``` ### Custom site — link out to Animo ``` Build a marketing landing page for "{event}" with our branding. Pull the schedule and ticket types from the Animo API. For tickets, link to the hosted Animo ticket pages — do not build a cart or checkout. For the sponsorship enquiry, embed/link our Animo activation form. ``` ### Integrate — webhook receiver ``` Register an Animo webhook for {events} pointing at {url}. Then build a receiver that persists every event to {store} — there is no GET backfill, so nothing should depend on re-fetching this data from the API. ``` ### Sync — refresh a calendar ``` Read all events and ticket types for company {sqid} from the Animo API and regenerate our events calendar page. Animo is the source of truth; the page is read-only presentation. ``` *** ## Capability map & known gaps What the API supports today, and the edges not to wander into. Always treat the [endpoint docs](index.md#endpoints) and [Conventions](conventions.md) as the source of truth. | Capability | Status | | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | Read user, companies, events, activations, ticket types, orders, forms | ✅ `GET` | | Create/update events, ticket types, forms, event pages, comms templates | ✅ | | Create/update orders (free tickets) | ✅ | | Create paid orders, then redirect attendee to hosted checkout (`/o/{order-id}/checkout`) | ✅ | | Approve/reject orders, shift dates, edit copy (Operate) | ✅ `PATCH` | | Register webhooks for submissions, leads, meetings | ✅ | | **Payment collection / VAT / invoicing** | 🚫 Animo-hosted only — never build | | **Completing payment outside hosted checkout** ("headless paid") | 🚫 No checkout URL for this — always redirect to `/o/{order-id}/checkout` | | **Custom form that posts into Animo** | 🚫 No submission/lead ingest endpoint — embed/link the hosted activation instead | | **`GET` leads / submissions / meetings** | 🚫 Not exposed — use webhooks and persist | | `orders/create` `form` payload | ⚠️ Not yet persisted server-side; send order-level fields only | | Delete events / ticket types / orders / forms | ⚠️ Routes missing — cannot delete via API | For the full, current list see [API index — Known API gaps](index.md#known-api-gaps) and the [Changelog](changelog.md). *** ## Related * [API index](index.md) — API overview and endpoint index * [Authentication](authentication.md) — tokens and scopes * [Conventions](conventions.md) — IDs, dates, errors, public URLs * [Webhooks](endpoints/webhooks.md) — outbound events (the only path to lead/submission data) * [Changelog](changelog.md) — version history and known limitations