SOURCE_ID: import_from_luma NAME: Import Luma Guests CATEGORY: First-party Import the guests of your Luma events into Floqer, either as a one-time historical pull or as an ongoing source that re-reads Luma on a schedule. Each row is one guest's registration for one event. Imported records become available to your Floqer workflows for follow-up automation, CRM enrichment, and the like. Luma is an event platform; this source reads the events of one Luma calendar and their guest lists. 1. ENDPOINTS Source identifier (used in every endpoint path): `import_from_luma`. POST /api/v1/sources/import_from_luma/preview Scope: sources:read Returns a sample of guest rows (up to 100) without creating anything. Use this to validate the event and status choices and inspect row shape before committing. POST /api/v1/sources/import_from_luma Scope: sources:write Creates the source and, for an active source, its schedule. Returns `source_instance_id` (the new source's UUID). The first import runs after the call returns, except for an active source with `pull_existing: false`, which imports nothing until its first scheduled run (§2). POST /api/v1/sources/import_from_luma/options/events Scope: sources:read Lists the calendar's events to pick from (see §6). GET /api/v1/sources//data Scope: sources:read Paginated rows imported into the created source. `` is the UUID returned by Create. Query: `page_no` (default 1), `page_size` (default 20, max 200). Source-agnostic; see concepts.txt §10. POST /api/v1/sources//sync Scope: sources:write Connects the created source to a workflow and (by default) backfills it with the source's current rows. `` here is the UUID returned by Create. Body: { workflow_id, field_mapping, push_existing? }. `field_mapping` keys are `input.` references on the target workflow, values are the source fields to pull. Also needs workflows:write, plus workflows:run when `push_existing` is true (the default). This step is source-agnostic; see concepts.txt §10 for the full shape. PATCH /api/v1/sources//status Scope: sources:write Pause or resume an active source by UUID. Body: {"status": "active" | "paused"}. Source-agnostic. Preview, options and create verify that the API-key user has an active Luma connection, after checking the body (a bad body returns 400 first). Missing connection returns 424. They read the default Luma key of the API key's organization. Create also reads Luma once before it makes anything, so a key that Luma refuses returns 424 and no source is created. A saved key that cannot be tied to a source returns 424 on create with "This saved Luma key cannot be tied to a list. Reconnect your Luma API key in Connections, then create the list again." If the schedule or the first import cannot start, create returns an error and archives the half-made source (List Sources shows it as "deleted"), so it is safe to call again. 2. IMPORT TYPE (ONE-TIME VS ONGOING) `import_type` is optional and defaults to "static". Values: "static" One-time import. The source imports every matching guest once, history included, and stops, with no recurring schedule. `pull_existing` has no effect on a static source. "active" Ongoing source. Imports matching guests initially AND re-reads Luma on the cadence in `frequency` (a cron string) until `expiration_date`. Every scheduled run re-reads every selected event, with no cutoff on how old the event is. With events ["all"], that means every event the calendar has at that moment, so events created later come in too. A guest that is not yet on the list is added. A guest already on the list has its row refreshed in place, never duplicated. `frequency` is required when `import_type: active` on create. Otherwise it is ignored. A scheduled run that starts while the previous one is still reading is skipped. When a guest reaches workflows: only the first time it enters the list. Later refreshes update the row but never send the guest to connected workflows again. A guest is sent once, no matter how often its row changes. `pull_existing` (create only, active sources only, default true): true The first read imports every matching guest that already exists. false Nothing is imported at creation. The list records its creation time, and scheduled runs bring in only guests who registered after it. The registration time used is `registered_at`, else `invited_at`; with `checked_in_only` true it is the guest's earliest check-in time. A guest with no such time is left out. 3. BODY SHAPE (PREVIEW + CREATE) Field names are snake_case. Unknown top-level keys are rejected with 400. The body is strict. Preview accepts: events required: ["all"] or a non-empty array of Luma event ids statuses optional: ["all"] (default) or a subset of the statuses checked_in_only boolean; optional (defaults to false) import_type "static" | "active"; optional (defaults to "static") frequency cron string; required on create when import_type === "active" expiration_date future ISO date, e.g. "2026-12-31"; optional (active source only) Create accepts all the preview fields plus: name required: display name for the new source pull_existing boolean; optional, defaults to true (active only) `name` and `pull_existing` are create-only: preview rejects them with 400 as unknown fields, so remove them before reusing a create body. 4. FIELD CATALOGUE events (string[]) required `["all"]` for every event on the calendar (an active source also picks up events created later; a static source reads once), or a non-empty list of Luma event ids from the events options call (§6). "all" cannot be mixed with event ids. A chosen event that Luma no longer has, or will not let this key read, is skipped. If none of the chosen events can be read, the import fails and asks the user to pick the events again. statuses (string[]) optional `["all"]` (the default when omitted) or any of: approved, pending_approval, waitlist, invited, declined. "all" cannot be mixed with statuses. `["all"]` turns the filter off, so it also keeps guests with any other Luma status; listing all five does not. See §5. checked_in_only (boolean) optional true keeps only guests who checked in at the event. Defaults to false. import_type (string) optional "static" (one-time) or "active" (ongoing). Defaults to "static". See §2. frequency (string) required on create when import_type === "active" Cron string for the re-read cadence (e.g. "0 12 * * *"). expiration_date (string) optional, active only Future ISO date on which an active source stops re-reading Luma. A value that is not an ISO date, or is in the past, returns 400. name (string) required on create only Human-readable display name for the source. pull_existing (boolean) optional on create, active only See §2. Defaults to true. 5. EVENTS AND GUEST STATUSES One row is one guest's registration for one event. The same person registered for two events is two rows. Guest statuses (`statuses`): approved Guest is approved for the event pending_approval Registration waits for the host to approve waitlist Guest is on the waitlist invited Guest was invited and has not answered declined Guest declined Only guests that match the choices come in: their status is one of the chosen statuses and, with `checked_in_only`, they checked in. With `statuses: ["all"]` no status filter applies, so a guest with a status Luma adds beyond these five (for example `session`) also comes in. A guest that starts matching later enters on a later run. A guest that stops matching after it entered stays on the list and its row keeps refreshing. Filters are applied after the guests are read from Luma. Every run still reads every guest of every selected event. Luma limits how many requests a calendar key can make. When Luma answers that the limit is reached, the import waits for the time Luma asks for (a minute when Luma gives none), keeps the progress it made, and continues. It gives up after five waits in a row and the import then shows as failed. A Luma server error or no answer is retried twice at once; if it lasts longer, the import waits 30 seconds and tries the same read again, doubling the wait up to 5 minutes, five times in a row (about 12 minutes in all), and then shows as failed with Luma's error. A single import stops with an error after 20,000 reads from Luma. Preview, options and create answer 429 "Luma rate limit reached." when Luma's limit is hit. Options also send a `Retry-After` header; otherwise wait about a minute before trying again. One preview can use about 40 of the key's reads. 6. DYNAMIC OPTIONS One dynamic-options field is available for this source: `events`. POST /api/v1/sources/import_from_luma/options/events Body: `{}` (no context) Returns: {value, label, extras}. The first entry is {value: "all", label: "All events"}; then one entry per event, with `value` the Luma event id, `label` the event name, and `extras.start_at` the event start. Newest events first, at most 500. Use the returned `value` directly in `events`. For events older than the newest 500, pass their Luma event ids directly. Connection check: the call verifies the API-key user has an active Luma connection first. Missing connection, or a key Luma refuses, returns 424. Options are read with the default Luma key of the API key's organization. 7. ROW COLUMNS Each row is one guest registration. Every column below is present on every row; it is empty when Luma has no value. `uid` is the guest id. Guest: guest_id Luma guest id (also the row's `uid`) name Guest name, or first and last name joined first_name First name last_name Last name email Email phone_number Phone number Registration: approval_status Luma's status for the guest: one of the statuses in §5, or another Luma status (for example `session`) when `statuses` is ["all"] registered_at When the guest registered (datetime) invited_at When the guest was invited (datetime) checked_in_at Earliest check-in across the guest's tickets (datetime) ticket_name Ticket names, each listed once, joined with commas ticket_price Total of the guest's ticket amounts as Luma reports them, in whole currency units (for example 25.00, not 2500); empty for crypto currencies currency Currency code, upper case From answers: company Company, from the registration question of type company job_title Job title, from the same answer linkedin LinkedIn, from the registration question of type linkedin registration_answers Every answer the guest gave, one "Label: value" per line Tracking: utm_source Urchin Tracking Module (UTM) source utm_medium UTM medium utm_campaign UTM campaign Event: event_id Luma event id event_name Event name event_start Event start (datetime) event_end Event end (datetime) event_url Event link (always a full link) event_location Full address, else address, else the meeting link Notes: - A guest who registered with several tickets still has one row. `ticket_name` lists each ticket name once and `ticket_price` adds the tickets up. - The row of a guest is found by the guest id, so reading a guest again never creates a second row. 8. HOW TO CONFIGURE END-TO-END Typical flow for an AI agent building a Luma import source: Step 1: Pick the events POST /api/v1/sources/import_from_luma/options/events Body: {} Use "all" or pick one or more event `value`s. Step 2: Preview before committing POST /api/v1/sources/import_from_luma/preview Body: { "events": ["all"], "statuses": ["approved", "waitlist"], "checked_in_only": false } Check the returned `data[]` row shape. Iterate the choices until you are happy, but mind Luma's limit (§5): each preview can use about 40 reads. Preview never creates anything and returns at most 100 sample rows. With `["all"]` it reads the newest events first; chosen events are read in the order given. When it stops before the last guest (at 100 rows, after about 15 seconds, or after about 40 reads from Luma), it sets `metadata.capped` to true: there may be more matching guests than it returned. An empty `data[]` with `capped` true does not mean an empty import (for example with `checked_in_only`, upcoming events with large guest lists can use up the reads before past events are reached). Preview answers 400 "None of the chosen Luma events were found in this calendar. Pick the events again." when none of the chosen events exist. Step 3: Create the source POST /api/v1/sources/import_from_luma Body: + the create-only fields: "name": "", "pull_existing": true // optional, active only and, if the preview body did not set them already: "import_type": "static" | "active", "frequency": "0 12 * * *", // required when import_type=active "expiration_date": "2027-01-01", // optional, active only Response: { "status": 201, "data": { "source_instance_id": "", "name", "created_at" }} Step 3b: (Optional) Poll imported rows while the import runs GET /api/v1/sources//data?page_no=1&page_size=20 ( = UUID from Step 3) `total_count` grows until the import finishes. An active source with `pull_existing: false` stays at 0 until its first scheduled run. Step 4: Sync the source into a workflow (so its records flow downstream) POST /api/v1/sources//sync ( = UUID from Step 3 ) First build `field_mapping`: a. GET /api/v1/workflows and pick the destination workflow_id. b. GET /api/v1/workflows//sheets//inputs Each input has a `reference` like `{{input.email}}`. c. Map each workflow input (reference WITHOUT braces) to a source field. The source fields are the keys on the preview `data[]` rows. Body: { "workflow_id": "", "field_mapping": { "input.email": "email" }, "push_existing": true } See concepts.txt §10 for the full sync semantics (source-agnostic). The initial import runs asynchronously. The create call returns as soon as the source is created and the import has started, not when records have finished arriving. An active source with `pull_existing: false` starts no import at creation; its first scheduled run brings in the first guests. 9. KEY NOTES - Luma connection is mandatory. The connection slug is `luma`. The user connects it on the Connections page by pasting a Luma calendar API key. Floqer checks the key with Luma when it is saved and stores it encrypted. One key covers one Luma calendar, and calendar API keys need a Luma Plus subscription. To import a second calendar, connect its key too and make it the default Luma key before previewing or creating the source: preview, options and create always use the default key, and the body has no key field. If the API-key user has no active Luma connection, preview, options, and create return 424 ("User is not connected to 'luma'."). - The list remembers the key that was the default when it was created and keeps using it, even if the default key changes later. If that key is deleted, the next import fails and the list shows "The Luma API key this list was created with was deleted or is no longer shared with you. Create a new list with a current key." If Luma refuses the key, the import stops at once and shows the refusal. - `events` is required. `statuses` defaults to all and `checked_in_only` to false. - `import_type` defaults to "static" (one-time). For an ongoing source set it to "active" and supply `frequency`. - Every run re-reads every selected event and every guest of it, so each active run costs one Luma request per page of guests, plus one per page of events with ["all"] or one per chosen event otherwise. - A guest reaches connected workflows once, the first time it enters the list. Its row keeps refreshing on later runs, but the refresh does not send it again. - With `pull_existing` false, the list holds only guests who registered (or checked in, with `checked_in_only`) after it was created. - Deleting a guest in Luma does not remove the row that was already imported. - Importing is free. This source uses no credits. 10. WHERE IT FITS UPSTREAM (in Luma) Events, their guests, ticket details, and registration answers live in the Luma calendar the API key belongs to. THIS SOURCE Creates a Luma import source. On creation it imports matching guests (except an active source with `pull_existing: false`); an active source re-reads the selected events on the `frequency` cron until `expiration_date`. DOWNSTREAM (in Floqer) Imported guests become available to your Floqer workflows. Wire the source into a workflow to enrich attendees, log them in a CRM, or send follow-ups. Each guest is sent once. 11. WHEN TO USE - One-time pull of everyone who registered for past events, for CRM enrichment or a follow-up campaign: `import_type: static`. - Keep new registrations flowing into a Floqer workflow on a schedule (for example, enrich every new guest of upcoming events): `import_type: active`, `frequency: "0 12 * * *"`, `events: ["all"]`. - Only follow up with people who showed up: `checked_in_only: true`. - Only guests who register from now on, not the existing guest lists: `import_type: active`, `pull_existing: false`. Last updated: 2026-11-15. Reference: https://floqer.com/docs/reference