{"openapi":"3.1.0","info":{"title":"Flyra API","version":"2026-06-01","description":"REST API for the Flyra CRM. All endpoints are scoped to the organization owning the API key — there is no cross-org access.\n\n**Authentication.** Every request must include `Authorization: Bearer flr_live_<your_key>`. Generate a key at [Developer](https://app.flyra.io/developer) in the Flyra sidebar inside your org.\n\n**Scopes.** Each endpoint declares an `x-required-scope` extension. A key without that scope returns `403 {\"code\": \"scope_denied\"}`. Legacy keys minted before 2026-05 have full access; new keys can be tightened to specific resources × verbs.\n\n**Versioning.** The current version is `2026-06-01`. Date-versioned in the path so old keys keep working when we ship breaking changes. The unversioned `/api/public/*` paths are still served but emit advisory `Deprecation: true` headers — prefer `/v2026-06-01/*` for new integrations.\n\n**Rate limits.** Per-key bucket, currently 200 requests / 15 min for reads and 100 / 15 min for writes. Returned headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.\n\n**Error shape.** `{ \"error\": string, \"code\"?: string, \"hint\"?: string, \"errors\"?: [{ field, message }], \"required_scope\"?: string }`. `hint` says what to do next.\n\n**Everything the connector can do.** Every action the Flyra MCP connector has is also a REST call: `POST /v2026-06-01/actions/{name}` with the action's inputs as the JSON body, answered `{ \"data\": … }`. `GET /v2026-06-01/actions` lists them all with their scopes and input schemas, and each one is documented below under its area. Texting, email and calls also have named routes (`POST /messages`, `GET /conversations`, `POST /emails`, `GET /calls` …) that run the same actions.\n\n**Action rate limits.** Actions share the connector's per-key ceiling: a `429` with `code: \"rate_limited\"` and a `Retry-After` header when it is reached. Sending texts is also capped at 10 per minute per org; send lists with `flyra_send_sms_blast`. Texts to people the business is not already working with cost SMS blast credits after 25 free numbers every 30 days.","contact":{"name":"Flyra Support","email":"info@flyra.io"}},"servers":[{"url":"https://app.flyra.io","description":"Production"}],"tags":[{"name":"Jobs","description":"Create, schedule, dispatch, and cancel jobs."},{"name":"Leads","description":"Sales pipeline — capture, list, and advance leads."},{"name":"Customers","description":"Customer records — the people you do work for."},{"name":"Employees","description":"Your team (read-only)."},{"name":"Services","description":"Your price book / service catalog (read-only)."},{"name":"Subscriptions","description":"Recurring subscriptions: list, read, create."},{"name":"Estimates","description":"Estimates: create, list, and text them to the customer."},{"name":"Texting","description":"Send texts (SMS/MMS) from the org's own line, read the inbox and threads, reply."},{"name":"Email","description":"Send email and read email threads."},{"name":"Calls","description":"Call history and transcripts (read-only; the API does not place calls)."},{"name":"Invoices","description":"Invoices, payment links and payments."},{"name":"Map","description":"Door-knocking pins, pin types and rep territories."},{"name":"Reviews","description":"Review requests and results."},{"name":"Equipment","description":"Equipment records."},{"name":"Automations","description":"Automations: list, switch on and off, inspect runs."},{"name":"Tasks","description":"Team tasks."},{"name":"Agreements","description":"Agreements and their templates."},{"name":"Settings","description":"Organization, message and email settings, pipelines, roles."},{"name":"Forms","description":"Public lead forms."},{"name":"Expenses","description":"Business expenses."},{"name":"Payroll","description":"Pay rates, overrides and period pay."},{"name":"Bulk","description":"Bulk actions across many records. The scope follows the `entity` argument."},{"name":"Search","description":"Cross-record search and fetch, and the org this key belongs to."},{"name":"Actions","description":"Run any action by name. Every operation under the other tags with a path under `/actions/` is one of these."}],"security":[{"bearerAuth":[]}],"paths":{"/v2026-06-01/jobs":{"get":{"operationId":"listJobs","summary":"List jobs","description":"Returns the org's jobs, newest first. Filterable by status, customer, and creation date.","tags":["Jobs"],"x-required-scope":"jobs:read","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"description":"Max records to return. Capped at 200."},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0},"description":"Number of records to skip."},{"name":"status","in":"query","schema":{"type":"string"},"description":"Filter by status."},{"name":"customer_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Created_at >= since."}],"responses":{"200":{"description":"Page of jobs.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["scheduled","on_the_way","arrival","in_progress","completed","cancelled","overdue"]},"title":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"service":{"type":"string","nullable":true,"description":"Free-text service label — does not need to match `GET /services`."},"scheduled_start":{"type":"string","format":"date-time","nullable":true},"scheduled_end":{"type":"string","format":"date-time","nullable":true},"scheduled_for":{"type":"string","format":"date-time","nullable":true,"description":"Legacy \"anytime\" anchor — prefer scheduled_start."},"notes":{"type":"string","nullable":true},"amount_cents":{"type":"integer","nullable":true,"description":"Job total in minor units."},"customer_id":{"type":"string","format":"uuid"},"customer_name":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"lead_source":{"type":"string","nullable":true},"payment_status":{"type":"string","nullable":true},"charge_status":{"type":"string","nullable":true},"dispatched_employee_ids":{"type":"array","items":{"type":"string","format":"uuid"},"nullable":true},"salesperson_ids":{"type":"array","items":{"type":"string","format":"uuid"},"nullable":true},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time","nullable":true},"completed_at":{"type":"string","format":"date-time","nullable":true}}}},"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer","nullable":true,"description":"Total matching records (PostgREST `count: exact`); null if not computed."}}}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope denied — the key does not grant the required `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found, or out of org scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server / database error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createJob","summary":"Create a job (and customer if needed)","description":"Upserts the customer by email/phone, then creates a job. Honors `minimum_job_price_cents` and `minimum_job_length_minutes` from your org settings.","tags":["Jobs"],"x-required-scope":"jobs:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["customer"],"properties":{"customer":{"type":"object","description":"`first_name` or `last_name` required; `email` or `mobile_phone` required.","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string","format":"email"},"mobile_phone":{"type":"string","description":"Alias: `phone`."}}},"service":{"type":"string","description":"Free-text label — does not need to match a row in /services."},"scheduled_start":{"type":"string","format":"date-time"},"scheduled_end":{"type":"string","format":"date-time"},"notes":{"type":"string"},"price":{"type":"number","description":"Dollar amount; stored as cents."}}},"examples":{"window_cleaning":{"value":{"customer":{"first_name":"Jane","last_name":"Doe","email":"jane@example.com","mobile_phone":"+15555550100"},"service":"Window Cleaning","scheduled_start":"2026-06-15T09:00:00Z","scheduled_end":"2026-06-15T11:00:00Z","notes":"Second floor only","price":150}}}}}},"responses":{"201":{"description":"Job created.","content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"title":{"type":"string","nullable":true},"scheduled_start":{"type":"string","format":"date-time","nullable":true},"scheduled_end":{"type":"string","format":"date-time","nullable":true},"amount_cents":{"type":"integer","nullable":true},"customer_id":{"type":"string","format":"uuid"}}}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope denied — the key does not grant the required `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found, or out of org scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server / database error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/jobs/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getJob","summary":"Fetch one job","tags":["Jobs"],"x-required-scope":"jobs:read","responses":{"200":{"description":"Job detail.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["scheduled","on_the_way","arrival","in_progress","completed","cancelled","overdue"]},"title":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"service":{"type":"string","nullable":true,"description":"Free-text service label — does not need to match `GET /services`."},"scheduled_start":{"type":"string","format":"date-time","nullable":true},"scheduled_end":{"type":"string","format":"date-time","nullable":true},"scheduled_for":{"type":"string","format":"date-time","nullable":true,"description":"Legacy \"anytime\" anchor — prefer scheduled_start."},"notes":{"type":"string","nullable":true},"amount_cents":{"type":"integer","nullable":true,"description":"Job total in minor units."},"customer_id":{"type":"string","format":"uuid"},"customer_name":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"lead_source":{"type":"string","nullable":true},"payment_status":{"type":"string","nullable":true},"charge_status":{"type":"string","nullable":true},"dispatched_employee_ids":{"type":"array","items":{"type":"string","format":"uuid"},"nullable":true},"salesperson_ids":{"type":"array","items":{"type":"string","format":"uuid"},"nullable":true},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time","nullable":true},"completed_at":{"type":"string","format":"date-time","nullable":true}}}}}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope denied — the key does not grant the required `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found, or out of org scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server / database error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateJob","summary":"Update a job","description":"Partial update — any subset of fields. `scheduled_end` must be after `scheduled_start` (using existing values when one side is omitted).","tags":["Jobs"],"x-required-scope":"jobs:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["scheduled","on_the_way","arrival","in_progress","completed","cancelled","overdue"]},"title":{"type":"string"},"description":{"type":"string"},"notes":{"type":"string"},"scheduled_start":{"type":"string","format":"date-time"},"scheduled_end":{"type":"string","format":"date-time"},"price":{"type":"number"},"amount_cents":{"type":"integer"}}}}}},"responses":{"200":{"description":"Updated job.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["scheduled","on_the_way","arrival","in_progress","completed","cancelled","overdue"]},"title":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"service":{"type":"string","nullable":true,"description":"Free-text service label — does not need to match `GET /services`."},"scheduled_start":{"type":"string","format":"date-time","nullable":true},"scheduled_end":{"type":"string","format":"date-time","nullable":true},"scheduled_for":{"type":"string","format":"date-time","nullable":true,"description":"Legacy \"anytime\" anchor — prefer scheduled_start."},"notes":{"type":"string","nullable":true},"amount_cents":{"type":"integer","nullable":true,"description":"Job total in minor units."},"customer_id":{"type":"string","format":"uuid"},"customer_name":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"lead_source":{"type":"string","nullable":true},"payment_status":{"type":"string","nullable":true},"charge_status":{"type":"string","nullable":true},"dispatched_employee_ids":{"type":"array","items":{"type":"string","format":"uuid"},"nullable":true},"salesperson_ids":{"type":"array","items":{"type":"string","format":"uuid"},"nullable":true},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time","nullable":true},"completed_at":{"type":"string","format":"date-time","nullable":true}}}}}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope denied — the key does not grant the required `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found, or out of org scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server / database error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"cancelJob","summary":"Cancel a job","description":"Soft cancel — sets `status` to `cancelled`. Job and its line items / payments are preserved.","tags":["Jobs"],"x-required-scope":"jobs:write","responses":{"200":{"description":"Cancelled.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["cancelled"]}}}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope denied — the key does not grant the required `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found, or out of org scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server / database error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/customers":{"get":{"operationId":"listCustomers","summary":"List customers","tags":["Customers"],"x-required-scope":"customers:read","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"description":"Max records to return. Capped at 200."},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0},"description":"Number of records to skip."},{"name":"search","in":"query","schema":{"type":"string"},"description":"ILIKE match on name, email, phone."},{"name":"email","in":"query","schema":{"type":"string","format":"email"}},{"name":"phone","in":"query","schema":{"type":"string"},"description":"Alias: `mobile_phone`."},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Page of customers.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"email":{"type":"string","format":"email","nullable":true},"mobile_phone":{"type":"string","nullable":true,"description":"E.164 preferred (e.g. `+15551234567`)."},"address":{"type":"string","nullable":true},"unit":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"zip":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true,"description":"Legacy alias for `zip` — same value."},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"notes":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"},"nullable":true},"notifications_enabled":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer","nullable":true,"description":"Total matching records (PostgREST `count: exact`); null if not computed."}}}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope denied — the key does not grant the required `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found, or out of org scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server / database error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createCustomer","summary":"Create a customer","description":"Deduped on email + mobile_phone within your org. Returns 409 with `duplicate_customer_id` if a match exists.","tags":["Customers"],"x-required-scope":"customers:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"`first_name` or `last_name` required; `email` or `mobile_phone` required.","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"display_name":{"type":"string"},"email":{"type":"string","format":"email"},"mobile_phone":{"type":"string"},"address":{"type":"string"},"unit":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zip":{"type":"string"},"notes":{"type":"string"}}}}}},"responses":{"201":{"description":"Customer created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"email":{"type":"string","format":"email","nullable":true},"mobile_phone":{"type":"string","nullable":true,"description":"E.164 preferred (e.g. `+15551234567`)."},"address":{"type":"string","nullable":true},"unit":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"zip":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true,"description":"Legacy alias for `zip` — same value."},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"notes":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"},"nullable":true},"notifications_enabled":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope denied — the key does not grant the required `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found, or out of org scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Duplicate — a customer with this email or phone already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["duplicate_customer"]},"duplicate_customer_id":{"type":"string","format":"uuid"},"duplicate_customer_name":{"type":"string","nullable":true}}}}}},"500":{"description":"Internal server / database error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/customers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getCustomer","summary":"Fetch one customer","tags":["Customers"],"x-required-scope":"customers:read","responses":{"200":{"description":"Customer detail.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"email":{"type":"string","format":"email","nullable":true},"mobile_phone":{"type":"string","nullable":true,"description":"E.164 preferred (e.g. `+15551234567`)."},"address":{"type":"string","nullable":true},"unit":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"zip":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true,"description":"Legacy alias for `zip` — same value."},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"notes":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"},"nullable":true},"notifications_enabled":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope denied — the key does not grant the required `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found, or out of org scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server / database error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateCustomer","summary":"Update a customer","description":"Partial update — any subset of fields. Pass `null` to clear a field; omit the key to leave it unchanged.","tags":["Customers"],"x-required-scope":"customers:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"email":{"type":"string","format":"email","nullable":true},"mobile_phone":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"unit":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"zip":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true}}}}}},"responses":{"200":{"description":"Updated customer.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"email":{"type":"string","format":"email","nullable":true},"mobile_phone":{"type":"string","nullable":true,"description":"E.164 preferred (e.g. `+15551234567`)."},"address":{"type":"string","nullable":true},"unit":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"zip":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true,"description":"Legacy alias for `zip` — same value."},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"notes":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"},"nullable":true},"notifications_enabled":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope denied — the key does not grant the required `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found, or out of org scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server / database error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/employees":{"get":{"operationId":"listEmployees","summary":"List employees","tags":["Employees"],"x-required-scope":"employees:read","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"description":"Max records to return. Capped at 200."},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0},"description":"Number of records to skip."},{"name":"role","in":"query","schema":{"type":"string"}},{"name":"is_active","in":"query","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"Page of employees.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"email":{"type":"string","format":"email","nullable":true},"phone":{"type":"string","nullable":true},"role":{"type":"string","description":"Admin | Sales Rep | Technician | <custom-role-uuid>"},"is_active":{"type":"boolean"},"color_tag":{"type":"string","nullable":true},"profile_picture_url":{"type":"string","format":"uri","nullable":true},"invitation_status":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer","nullable":true,"description":"Total matching records (PostgREST `count: exact`); null if not computed."}}}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope denied — the key does not grant the required `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found, or out of org scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server / database error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/services":{"get":{"operationId":"listServices","summary":"List the price book","description":"Returns the org's service categories with their line items. The `service` field on `POST /jobs` is free text and does not need to match a row here, but listing is useful for syncing names + canonical prices.","tags":["Services"],"x-required-scope":"services:read","responses":{"200":{"description":"Categories with nested line items.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"sort_order":{"type":"integer"},"line_items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"price":{"type":"number","nullable":true,"description":"Dollar amount (not cents)."},"quantity":{"type":"number","nullable":true},"unit":{"type":"string","nullable":true}}}}}}}}}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope denied — the key does not grant the required `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found, or out of org scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server / database error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createService","summary":"Add a service to the price book","description":"Creates a line item (a service) under an existing category. Use GET /services to find a valid `category_id`.","tags":["Services"],"x-required-scope":"services:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["category_id","name"],"properties":{"category_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"title":{"type":"string","description":"Optional display title; falls back to `name`."},"description":{"type":"string"},"price":{"type":"number","description":"Dollar amount (not cents). Defaults to 0."},"quantity":{"type":"integer","description":"Default quantity. Defaults to 1."},"unit":{"type":"string","description":"Defaults to \"each\"."}}},"examples":{"window_service":{"value":{"category_id":"00000000-0000-0000-0000-000000000000","name":"Gutter Cleaning","description":"Single-story home","price":120,"unit":"each"}}}}}},"responses":{"201":{"description":"Service created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"price":{"type":"number","nullable":true,"description":"Dollar amount (not cents)."},"quantity":{"type":"number","nullable":true},"unit":{"type":"string","nullable":true}}}}}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope denied — the key does not grant the required `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found, or out of org scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server / database error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/estimates":{"get":{"operationId":"listEstimates","summary":"List estimates","description":"Returns the org's estimates (quotes), newest first. Filterable by status, customer, and creation date.","tags":["Estimates"],"x-required-scope":"estimates:read","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"description":"Max records to return. Capped at 200."},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0},"description":"Number of records to skip."},{"name":"status","in":"query","schema":{"type":"string"},"description":"Filter by status."},{"name":"customer_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Created_at >= since."}],"responses":{"200":{"description":"Page of estimates.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"customer_name":{"type":"string","nullable":true},"status":{"type":"string","description":"e.g. draft, sent, accepted, declined."},"subject":{"type":"string","nullable":true},"subtotal_cents":{"type":"integer"},"tax_cents":{"type":"integer"},"total_cents":{"type":"integer"},"tax_rate":{"type":"number","nullable":true,"description":"Fraction, e.g. 0.08 for 8%."},"valid_until":{"type":"string","format":"date","nullable":true},"created_at":{"type":"string","format":"date-time"}}}},"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer","nullable":true,"description":"Total matching records (PostgREST `count: exact`); null if not computed."}}}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope denied — the key does not grant the required `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found, or out of org scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server / database error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createEstimate","summary":"Create a draft estimate","description":"Creates a draft quote for an existing customer from a list of line items. Totals are computed server-side. Status always starts as \"draft\"; send it to the customer separately.","tags":["Estimates"],"x-required-scope":"estimates:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["customer_id","line_items"],"properties":{"customer_id":{"type":"string","format":"uuid"},"line_items":{"type":"array","minItems":1,"items":{"type":"object","required":["name","qty","unit_price_cents"],"properties":{"name":{"type":"string"},"qty":{"type":"number","description":"Positive quantity."},"unit_price_cents":{"type":"integer","description":"Per-unit price in cents."},"description":{"type":"string"},"taxable":{"type":"boolean","default":true}}}},"subject":{"type":"string"},"notes":{"type":"string"},"terms":{"type":"string"},"valid_until":{"type":"string","format":"date","description":"ISO date (YYYY-MM-DD)."},"tax_rate":{"type":"number","description":"Fraction applied to taxable items, e.g. 0.08 for 8%."}}},"examples":{"window_quote":{"value":{"customer_id":"00000000-0000-0000-0000-000000000000","line_items":[{"name":"Window Cleaning — exterior","qty":1,"unit_price_cents":15000},{"name":"Screen cleaning","qty":12,"unit_price_cents":500,"taxable":false}],"subject":"Spring window cleaning","tax_rate":0.08,"valid_until":"2026-07-31"}}}}}},"responses":{"201":{"description":"Estimate created. Includes a customer-facing `public_link`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"customer_name":{"type":"string","nullable":true},"status":{"type":"string","description":"e.g. draft, sent, accepted, declined."},"subject":{"type":"string","nullable":true},"subtotal_cents":{"type":"integer"},"tax_cents":{"type":"integer"},"total_cents":{"type":"integer"},"tax_rate":{"type":"number","nullable":true,"description":"Fraction, e.g. 0.08 for 8%."},"valid_until":{"type":"string","format":"date","nullable":true},"created_at":{"type":"string","format":"date-time"}}},{"type":"object","properties":{"public_link":{"type":"string","format":"uri"}}}]}}}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope denied — the key does not grant the required `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found, or out of org scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server / database error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/estimates/{id}/send":{"post":{"operationId":"sendEstimate","summary":"Text an estimate to its customer","description":"Texts the estimate's link to the customer's mobile phone from the business's Flyra number, using the business's own estimate message (Settings > Automations), then marks the estimate sent and starts its follow-ups. Typical website flow: create the customer, create the estimate with its line items, then call this. Refused (409) once the estimate is accepted or declined, and (422) when the customer has no mobile phone, has opted out, or the business has not finished texting setup. At most 20 sends per minute per business.","tags":["Estimates"],"x-required-scope":"estimates:write","x-additional-required-scopes":["sms:send"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Text queued and estimate marked sent.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"sent_at":{"type":"string","format":"date-time"},"public_link":{"type":"string","format":"uri"},"to":{"type":"string","description":"The number texted."},"message_id":{"type":"string"},"body":{"type":"string","description":"The text as sent."}}}}}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope denied — the key does not grant the required `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No estimate with that id in this business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The estimate is already accepted or declined.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Nobody to text: no mobile phone, opted out, or texting not set up.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server / database error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/subscriptions":{"get":{"operationId":"listSubscriptions","summary":"List subscriptions","tags":["Subscriptions"],"x-required-scope":"subscriptions:read","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"description":"Max records to return. Capped at 200."},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0},"description":"Number of records to skip."},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"customer_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"term","in":"query","schema":{"type":"string","enum":["fixed","until_cancelled"]},"description":"Only contracts with a set length, or only ones that run until cancelled."},{"name":"term_months","in":"query","schema":{"type":"integer","minimum":1},"description":"Only fixed contracts of this many months, e.g. 12 or 24."},{"name":"pricing","in":"query","schema":{"type":"string","enum":["custom_per_visit","flat"]},"description":"Only plans priced visit by visit, or only flat-priced plans."}],"responses":{"200":{"description":"Page of subscriptions, each with nested customer + template summary and a `contract` object: `term` (`fixed` | `until_cancelled`), `term_months` (e.g. 12, 24), `term_source` (`end_date` | `plan` | `none`), `plan_term_months` (the plan template default), `start_date`, `end_date` (the day billing stops), `pricing` (`custom_per_visit` | `flat`), `visits` (each visit's `date`, `amount_cents`, `has_own_line_items`, on custom per-visit pricing), `payment_plan` (`contract_total_cents`, `payment_term_months`, when the contract is paid in equal monthly payments) and `billing_mode`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}},"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer","nullable":true,"description":"Total matching records (PostgREST `count: exact`); null if not computed."}}}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope denied — the key does not grant the required `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found, or out of org scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server / database error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createSubscription","summary":"Create a subscription","tags":["Subscriptions"],"x-required-scope":"subscriptions:write","description":"Start a recurring subscription for a customer from one of your subscription templates. Name, description, visits per year and frequency default to the template. The template's length sets the end date unless `term` / `term_months` say otherwise. Created as `pending` (sent to the customer to accept) unless you pass `status: \"active\"`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["customer_id","template_id","amount_cents"],"properties":{"customer_id":{"type":"string","format":"uuid"},"template_id":{"type":"string","format":"uuid","description":"A subscription template that is not archived."},"amount_cents":{"type":"integer","minimum":1,"description":"Price per billing period, in cents."},"frequency":{"type":"string","enum":["weekly","monthly","bi_monthly","quarterly","tri_annual","six_months","yearly","biennial","triennial"],"description":"Defaults to the template's."},"status":{"type":"string","enum":["pending","active"],"default":"pending"},"is_taxable":{"type":"boolean","default":false},"tax_rate":{"type":"number","minimum":0,"maximum":100,"description":"Percent. Used only when `is_taxable` is true."},"term":{"type":"string","enum":["fixed","until_cancelled"],"description":"Defaults to the template's length."},"term_months":{"type":"integer","minimum":1,"description":"Length of a `fixed` contract. Not allowed with `until_cancelled`."},"name":{"type":"string","description":"Defaults to the template name."},"description":{"type":"string"},"visits_per_year":{"type":"integer"},"notes":{"type":"string"},"lead_source":{"type":"string"}}}}}},"responses":{"201":{"description":"The new subscription, in the same shape as GET /subscriptions/{id}.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"}}}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope denied — the key does not grant the required `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found, or out of org scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server / database error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/subscriptions/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getSubscription","summary":"Fetch one subscription","tags":["Subscriptions"],"x-required-scope":"subscriptions:read","responses":{"200":{"description":"One subscription in the same shape as a row of List subscriptions, including `contract`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"}}}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope denied — the key does not grant the required `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found, or out of org scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server / database error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/leads":{"get":{"operationId":"listLeads","summary":"List leads","tags":["Leads"],"x-required-scope":"leads:read","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"description":"Max records to return. Capped at 200."},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0},"description":"Number of records to skip."},{"name":"search","in":"query","schema":{"type":"string"},"description":"ILIKE match on name, email, phone."},{"name":"email","in":"query","schema":{"type":"string","format":"email"}},{"name":"phone","in":"query","schema":{"type":"string"}},{"name":"stage","in":"query","schema":{"type":"string"},"description":"Pipeline stage label or slug — normalized before matching."},{"name":"status","in":"query","schema":{"type":"string"},"description":"Top-level status: `open` | `won` | `lost`."},{"name":"pipeline_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Created_at >= since."}],"responses":{"200":{"description":"Page of leads.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"email":{"type":"string","format":"email","nullable":true},"phone":{"type":"string","nullable":true,"description":"E.164, normalized on create (e.g. `+15551234567`)."},"status":{"type":"string","nullable":true,"description":"Top-level lifecycle: `open` | `won` | `lost`."},"stage":{"type":"string","nullable":true,"description":"Pipeline column slug (e.g. `new`, `contacted`, `estimate_sent`)."},"pipeline_id":{"type":"string","format":"uuid","nullable":true},"lead_source_id":{"type":"string","format":"uuid","nullable":true,"description":"Org-defined Lead Source (Referral, Yard sign, …)."},"source":{"type":"string","nullable":true,"description":"Source/platform label — also routes the lead to a matching pipeline."},"service_type":{"type":"string","nullable":true},"value_cents":{"type":"integer","nullable":true,"description":"Estimated lead value in minor units."},"address_line1":{"type":"string","nullable":true},"address_line2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"owner_user_id":{"type":"string","format":"uuid","nullable":true,"description":"Assigned team member (auth user id)."},"converted_customer_id":{"type":"string","format":"uuid","nullable":true,"description":"Set once the lead becomes a customer."},"converted":{"type":"boolean","description":"Convenience flag — true when `converted_customer_id` is set."},"external_lead_id":{"type":"string","nullable":true,"description":"Your upstream id — pass on create for idempotency."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true},"last_inbound_at":{"type":"string","format":"date-time","nullable":true},"last_outbound_at":{"type":"string","format":"date-time","nullable":true}}}},"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer","nullable":true,"description":"Total matching records (PostgREST `count: exact`); null if not computed."}}}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope denied — the key does not grant the required `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found, or out of org scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server / database error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createLead","summary":"Create a lead","description":"Captures a lead into your sales pipeline and fires the same `lead.created` automation (auto-text / nurture workflow + new-lead push) as a lead created in-app. `email` or `phone` is required. Omit `pipeline_id` to use your default pipeline, and omit `stage` to land on that pipeline's first column. Pass `external_lead_id` to make retries idempotent (returns 409 if it already exists).","tags":["Leads"],"x-required-scope":"leads:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"`email` or `phone` is required.","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string","description":"Validated + normalized to E.164."},"source":{"type":"string","description":"Free-text label (e.g. \"Referral\", \"Yelp\"); also routes to a matching pipeline."},"service_type":{"type":"string"},"value_cents":{"type":"integer","minimum":0},"score":{"type":"integer","minimum":0,"maximum":100,"description":"Your own 0-100 score for this lead. Automations can branch on it."},"notes":{"type":"string"},"pipeline_id":{"type":"string","format":"uuid"},"stage":{"type":"string","description":"Pipeline stage label/slug. Non-`new` stages skip the \"new lead\" automation."},"lead_source_id":{"type":"string","format":"uuid"},"owner_user_id":{"type":"string","format":"uuid","description":"Assign to a team member (auth user id or employee id)."},"address_line1":{"type":"string"},"address_line2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postal_code":{"type":"string"},"external_lead_id":{"type":"string","description":"Your upstream id — enables idempotent create."}}}}}},"responses":{"201":{"description":"Lead created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"email":{"type":"string","format":"email","nullable":true},"phone":{"type":"string","nullable":true,"description":"E.164, normalized on create (e.g. `+15551234567`)."},"status":{"type":"string","nullable":true,"description":"Top-level lifecycle: `open` | `won` | `lost`."},"stage":{"type":"string","nullable":true,"description":"Pipeline column slug (e.g. `new`, `contacted`, `estimate_sent`)."},"pipeline_id":{"type":"string","format":"uuid","nullable":true},"lead_source_id":{"type":"string","format":"uuid","nullable":true,"description":"Org-defined Lead Source (Referral, Yard sign, …)."},"source":{"type":"string","nullable":true,"description":"Source/platform label — also routes the lead to a matching pipeline."},"service_type":{"type":"string","nullable":true},"value_cents":{"type":"integer","nullable":true,"description":"Estimated lead value in minor units."},"address_line1":{"type":"string","nullable":true},"address_line2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"owner_user_id":{"type":"string","format":"uuid","nullable":true,"description":"Assigned team member (auth user id)."},"converted_customer_id":{"type":"string","format":"uuid","nullable":true,"description":"Set once the lead becomes a customer."},"converted":{"type":"boolean","description":"Convenience flag — true when `converted_customer_id` is set."},"external_lead_id":{"type":"string","nullable":true,"description":"Your upstream id — pass on create for idempotency."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true},"last_inbound_at":{"type":"string","format":"date-time","nullable":true},"last_outbound_at":{"type":"string","format":"date-time","nullable":true}}}}}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope denied — the key does not grant the required `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found, or out of org scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Duplicate — a lead with this `external_lead_id` already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["duplicate_lead"]},"duplicate_lead_id":{"type":"string","format":"uuid"}}}}}},"500":{"description":"Internal server / database error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/leads/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getLead","summary":"Fetch one lead","tags":["Leads"],"x-required-scope":"leads:read","responses":{"200":{"description":"Lead detail.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"email":{"type":"string","format":"email","nullable":true},"phone":{"type":"string","nullable":true,"description":"E.164, normalized on create (e.g. `+15551234567`)."},"status":{"type":"string","nullable":true,"description":"Top-level lifecycle: `open` | `won` | `lost`."},"stage":{"type":"string","nullable":true,"description":"Pipeline column slug (e.g. `new`, `contacted`, `estimate_sent`)."},"pipeline_id":{"type":"string","format":"uuid","nullable":true},"lead_source_id":{"type":"string","format":"uuid","nullable":true,"description":"Org-defined Lead Source (Referral, Yard sign, …)."},"source":{"type":"string","nullable":true,"description":"Source/platform label — also routes the lead to a matching pipeline."},"service_type":{"type":"string","nullable":true},"value_cents":{"type":"integer","nullable":true,"description":"Estimated lead value in minor units."},"address_line1":{"type":"string","nullable":true},"address_line2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"owner_user_id":{"type":"string","format":"uuid","nullable":true,"description":"Assigned team member (auth user id)."},"converted_customer_id":{"type":"string","format":"uuid","nullable":true,"description":"Set once the lead becomes a customer."},"converted":{"type":"boolean","description":"Convenience flag — true when `converted_customer_id` is set."},"external_lead_id":{"type":"string","nullable":true,"description":"Your upstream id — pass on create for idempotency."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true},"last_inbound_at":{"type":"string","format":"date-time","nullable":true},"last_outbound_at":{"type":"string","format":"date-time","nullable":true}}}}}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope denied — the key does not grant the required `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found, or out of org scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server / database error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateLead","summary":"Update a lead","description":"Partial update — any subset of fields. Use `stage` to move the lead between pipeline columns and `status` for the top-level lifecycle. Pass `null` to clear a field; omit the key to leave it unchanged.","tags":["Leads"],"x-required-scope":"leads:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"email":{"type":"string","format":"email","nullable":true},"stage":{"type":"string","nullable":true,"description":"Pipeline stage label/slug — normalized to the stored slug."},"status":{"type":"string","nullable":true,"description":"`open` | `won` | `lost`."},"service_type":{"type":"string","nullable":true},"value_cents":{"type":"integer","minimum":0,"nullable":true},"score":{"type":"integer","minimum":0,"maximum":100,"nullable":true,"description":"Your own 0-100 score for this lead. Automations can branch on it."},"notes":{"type":"string","nullable":true},"address_line1":{"type":"string","nullable":true},"address_line2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true}}}}}},"responses":{"200":{"description":"Updated lead.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"email":{"type":"string","format":"email","nullable":true},"phone":{"type":"string","nullable":true,"description":"E.164, normalized on create (e.g. `+15551234567`)."},"status":{"type":"string","nullable":true,"description":"Top-level lifecycle: `open` | `won` | `lost`."},"stage":{"type":"string","nullable":true,"description":"Pipeline column slug (e.g. `new`, `contacted`, `estimate_sent`)."},"pipeline_id":{"type":"string","format":"uuid","nullable":true},"lead_source_id":{"type":"string","format":"uuid","nullable":true,"description":"Org-defined Lead Source (Referral, Yard sign, …)."},"source":{"type":"string","nullable":true,"description":"Source/platform label — also routes the lead to a matching pipeline."},"service_type":{"type":"string","nullable":true},"value_cents":{"type":"integer","nullable":true,"description":"Estimated lead value in minor units."},"address_line1":{"type":"string","nullable":true},"address_line2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"owner_user_id":{"type":"string","format":"uuid","nullable":true,"description":"Assigned team member (auth user id)."},"converted_customer_id":{"type":"string","format":"uuid","nullable":true,"description":"Set once the lead becomes a customer."},"converted":{"type":"boolean","description":"Convenience flag — true when `converted_customer_id` is set."},"external_lead_id":{"type":"string","nullable":true,"description":"Your upstream id — pass on create for idempotency."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true},"last_inbound_at":{"type":"string","format":"date-time","nullable":true},"last_outbound_at":{"type":"string","format":"date-time","nullable":true}}}}}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope denied — the key does not grant the required `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found, or out of org scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server / database error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/invoices/{id}/record-payment":{"post":{"operationId":"recordInvoicePayment","summary":"Record a payment on an invoice","tags":["Invoices"],"description":"Record a payment taken outside Flyra (e-transfer, check, cash) against an invoice, then recompute the invoice and job payment status. Built for reconciliation. Pass a stable `idempotency_key` so a retry returns the first payment (`deduped: true`) instead of crediting twice; without one, the same amount and method within 60 seconds is treated as a retry.\n\nScope: `invoices:write`.","x-required-scope":"invoices:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Invoice id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount_cents","payment_method"],"properties":{"amount_cents":{"type":"integer","minimum":1,"description":"Amount in cents."},"payment_method":{"type":"string","description":"How it was paid, e.g. `e-transfer`, `check`, `cash`."},"payment_date":{"type":"string","format":"date-time","description":"When it was paid. Defaults to now."},"idempotency_key":{"type":"string","pattern":"^[A-Za-z0-9_.\\-:]{1,128}$","description":"Your stable id for this payment."},"external_reference":{"type":"string","maxLength":200,"description":"Your reference (bank transaction id, check number)."}}}}}},"responses":{"200":{"description":"Already recorded (`deduped: true`): the earlier payment is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordedPayment"}}}},"201":{"description":"Payment recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordedPayment"}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/messages":{"post":{"operationId":"sendMessage","summary":"Send a text","tags":["Texting"],"description":"Send one SMS or MMS from the org's Flyra number. Pass customer_id (their mobile_phone is used) or a raw to_phone in E.164 (+15551234567).\n\nSame as `POST /v2026-06-01/actions/flyra_send_sms`. Scope: `sms:send`.","x-required-scope":"sms:send","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"description":"Customer UUID or semantic id from flyra_search_customers. Recipient's mobile_phone is used.","type":"string"},"to_phone":{"description":"Raw E.164 phone, e.g. +15551234567. Used when customer_id is omitted or the customer has no phone on file.","type":"string"},"body":{"description":"Message text. At most 10 carrier segments: 1530 characters of plain text, or about 670 once the text has any emoji or special character (the carrier then bills 67-character segments). Longer is refused here, before anything is queued. Required unless media_urls is given — a picture with no caption is a real message, an empty text is not. Bare flyra.io URLs are auto-rewritten to app.flyra.io to avoid T-Mobile spam filtering.","type":"string","maxLength":1600},"media_urls":{"description":"Public https URLs to attach, at most 5. Images and PDFs. The carrier fetches these itself, so they must be reachable without a login.","maxItems":5,"type":"array","items":{"type":"string"}},"send_at":{"description":"Send it later, as Schedule message in the Flyra Inbox does: an ISO 8601 time with its offset, at least a minute and at most a year from now (e.g. 2026-10-30T09:00:00-07:00). Leave out to send now. At most 10 connector texts per business can be scheduled for any one minute, and a cancelled one still counts. The reply then carries scheduled_for, flyra_get_thread shows the text with scheduled_for set until it goes out, and flyra_cancel_scheduled_message stops it before then. A cold text's credit is spent when it is scheduled, and cancelling does not give it back.","type":"string"},"idempotency_key":{"description":"Optional: a key for this one text (8 to 128 characters). A retry with the same key is not texted or charged again.","type":"string","minLength":8,"maxLength":128},"from_line":{"description":"Optional. The line to send from: a phone_<uuid> id from flyra_list_lines. Must be a line that can text. Left out, a reply goes out from the line the conversation is already on, and a new conversation from the business's main number.","type":"string"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/conversations":{"get":{"operationId":"listConversations","summary":"List text conversations","tags":["Texting"],"description":"List recent SMS conversations (contacts) ordered by last message. Each row carries the contact id, customer link, last message preview, and unread state. A person connected through OAuth sees the threads their Inbox shows them; `total` is null while more pages remain. Pass updated_since to list only threads with a message at or after that time: a new text in either direction from anyone counts, a later delivery status change does not, and a recorded call counts from the time it landed in Flyra, which can be minutes after the call ended. To keep a copy in sync, pass the newest last_message_at from your previous run less a few seconds, read each listed thread with flyra_get_thread passing after (your newest sent_at for it, less a few seconds), skip message ids you already have, and move your saved times forward only once has_more is false.\n\nSame as `POST /v2026-06-01/actions/flyra_list_conversations`. Scope: `sms:read`.","x-required-scope":"sms:read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":50}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"updated_since","in":"query","required":false,"schema":{"type":"string"},"description":"ISO 8601 time. Only threads whose last message is at or after it. With an Inbox filter below, a recorded call that landed late is not added, as in the Inbox."},{"name":"awaiting_reply","in":"query","required":false,"schema":{"type":"boolean"},"description":"Awaiting your reply: true keeps threads whose last message came in from the contact."},{"name":"salesperson_ids","in":"query","required":false,"schema":{"maxItems":50,"type":"array","items":{"type":"string"}},"description":"Salesperson: employee ids (emp_<uuid>) from flyra_list_employees. Keeps threads whose customer one of them sold a job to or sent an estimate to, or whose lead one of them sent an estimate to."},{"name":"tag_ids","in":"query","required":false,"schema":{"maxItems":50,"type":"array","items":{"type":"string"}},"description":"Tag: ids from flyra_list_tags. Keeps threads whose customer has any of them; a thread with no customer never matches."},{"name":"technician_ids","in":"query","required":false,"schema":{"maxItems":50,"type":"array","items":{"type":"string"}},"description":"Technician: employee ids (emp_<uuid>) from flyra_list_employees. Keeps threads whose customer has a job or subscription, not cancelled, dispatched to one of them; a thread with no customer never matches."}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"contact_<uuid>; pass to flyra_get_thread as contact_id."},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"E.164."},"customer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"cus_<uuid>, or null when the number is not linked to a customer."},"last_message_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO timestamp."},"last_message_direction":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"inbound or outbound."},"last_message_preview":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_message_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"muted":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"summary":{"type":"string"}},"required":["id","name","phone","customer_id","last_message_at","last_message_direction","last_message_preview","last_message_status","muted","summary"],"additionalProperties":{}}},"total":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"null while more pages remain on a person's list."},"offset":{"type":"number"},"limit":{"type":"number"},"truncated":{"type":"boolean"},"next_offset":{"anyOf":[{"type":"number"},{"type":"null"}]},"note":{"description":"Set when the first page is empty.","type":"string"}},"required":["items","total","offset","limit","truncated","next_offset"],"additionalProperties":{}}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/conversations/{id}/messages":{"get":{"operationId":"listConversationMessages","summary":"Read a conversation","tags":["Texting"],"description":"Return the most recent messages on a thread, oldest-first within the page so the agent reads it like a transcript. Pass either contact_id (preferred) or customer_id. count is the size of this page, not of the thread. To read further back, pass next_before as before and next_before_id as before_id while has_more is true. To read only what is new, pass after (and the id of that newest message as after_id): the page then holds the newest messages after it, so when has_more is true, keep after and page back with before. The ids keep two messages sent in the same instant from being skipped at a page edge. Each message names its numbers in from and to and its org line in line_id; an outbound text has no from until it has gone out, and none when it went over iMessage or before Flyra recorded lines. A text scheduled to send later has its send time in scheduled_for; its status reads queued until then. Photos, videos and files on a text are download links in media_urls.\n\nSame as `POST /v2026-06-01/actions/flyra_get_thread`. Scope: `sms:read`.","x-required-scope":"sms:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The conversation's contact id (`id` from GET /conversations)."},{"name":"customer_id","in":"query","required":false,"schema":{"type":"string"},"description":"Customer UUID or semantic id — used to look up the contact."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":50}},{"name":"before","in":"query","required":false,"schema":{"type":"string"},"description":"ISO 8601 time, exclusive. Only messages sent before it; pass next_before from the previous page."},{"name":"after","in":"query","required":false,"schema":{"type":"string"},"description":"ISO 8601 time, exclusive. Only messages sent after it, such as the newest sent_at you already have. A recorded call that landed in Flyra after this time is included too, even though its sent_at is the time the call ended."},{"name":"before_id","in":"query","required":false,"schema":{"type":"string"},"description":"next_before_id from the previous page, passed with before."},{"name":"after_id","in":"query","required":false,"schema":{"type":"string"},"description":"The id of the message whose sent_at you pass as after."}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"contact":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"customer_id":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","phone","customer_id"],"additionalProperties":{}},{"type":"null"}]},"count":{"type":"number"},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"msg_<uuid>."},"direction":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"inbound or outbound."},"channel":{"anyOf":[{"type":"string"},{"type":"null"}]},"body":{"anyOf":[{"type":"string"},{"type":"null"}]},"sent_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO timestamp."},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"from":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"E.164. Inbound: the contact's number on file. Outbound: the org line it went out on; null when the row names no line: not sent yet, sent over iMessage, or sent before Flyra recorded lines."},"to":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"E.164. Inbound: the org line it came in on, null on a recorded call. Outbound: the number it was sent to."},"line_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"phone_<uuid> of the org line it used, or null."},"scheduled_for":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO timestamp a scheduled text is set to send at; null once it has gone out, and on every other message. Cancel one with flyra_cancel_scheduled_message."},"media_urls":{"type":"array","items":{"type":"string"},"description":"Download links for the pictures, videos and files sent or received on this text, the same files the Flyra Inbox shows. Empty when it has none."}},"required":["id","direction","channel","body","sent_at","status","error","from","to","line_id","scheduled_for","media_urls"],"additionalProperties":{}},"description":"Oldest first within the page."},"has_more":{"type":"boolean","description":"True when older messages remain: pass next_before as before and next_before_id as before_id to read them."},"next_before":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The oldest sent_at on this page. Null when has_more is false."},"next_before_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"msg_<uuid> of the oldest message on this page, for before_id. Null when has_more is false."}},"required":["contact","count","messages","has_more","next_before","next_before_id"],"additionalProperties":{}}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"replyToConversation","summary":"Reply in a conversation","tags":["Texting"],"description":"Send a SMS or MMS to the phone number on an existing contact. Convenience wrapper around flyra_send_sms — accepts a contact_id and reuses its phone_e164. Same per-org 10/min cap, media_urls rules and cold-text credits as flyra_send_sms; a reply to someone who texted in the last 30 days is free. Returns message_id, thread_message_id (this text's id in flyra_get_thread) and from, the line it goes out from: the conversation's own line, or the one passed as from_line (an id from flyra_list_lines). On an org texting over iMessage it can go out another way; its flyra_get_thread row shows the line it used. status is queued when this replies; the carrier's sent, delivered or failed verdict lands on that row within a few minutes, so read flyra_get_thread before resending. Pass send_at to schedule it for later, as Schedule message in the Inbox does; flyra_cancel_scheduled_message stops it before it goes out.\n\nSame as `POST /v2026-06-01/actions/flyra_reply_to_thread`. Scope: `sms:send`.","x-required-scope":"sms:send","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The conversation's contact id (`id` from GET /conversations)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"description":"Message text. Same limit as flyra_send_sms: at most 10 carrier segments (1530 plain characters, about 670 with any emoji); longer is refused here. Required unless media_urls is given.","type":"string","maxLength":1600},"media_urls":{"description":"Public https URLs to attach, at most 5. The carrier fetches these itself, so they must be reachable without a login.","maxItems":5,"type":"array","items":{"type":"string"}},"send_at":{"description":"Send it later, as Schedule message in the Flyra Inbox does: an ISO 8601 time with its offset, at least a minute and at most a year from now (e.g. 2026-10-30T09:00:00-07:00). Leave out to send now. At most 10 connector texts per business can be scheduled for any one minute, and a cancelled one still counts. The reply then carries scheduled_for, flyra_get_thread shows the text with scheduled_for set until it goes out, and flyra_cancel_scheduled_message stops it before then. A cold text's credit is spent when it is scheduled, and cancelling does not give it back.","type":"string"},"idempotency_key":{"description":"Optional: a key for this one text (8 to 128 characters). A retry with the same key is not texted or charged again.","type":"string","minLength":8,"maxLength":128},"from_line":{"description":"Optional. The line to send from: a phone_<uuid> id from flyra_list_lines. Must be a line that can text. Left out, a reply goes out from the line the conversation is already on, and a new conversation from the business's main number.","type":"string"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/sms-credits":{"get":{"operationId":"getSmsCredits","summary":"Texting credit balance","tags":["Texting"],"description":"Returns the org's remaining SMS blast credits. flyra_send_sms_blast and cold texts sent with flyra_send_sms spend them, so check before a list: if balance is low or zero, warn the user instead of attempting a send that will be refused. Auto-recharge and the spending limit are in flyra_get_sms_blast_settings.\n\nSame as `POST /v2026-06-01/actions/flyra_get_sms_credits`. Scope: `sms:read`.","x-required-scope":"sms:read","parameters":[],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/emails":{"post":{"operationId":"sendEmail","summary":"Send an email","tags":["Email"],"description":"Send an outbound email via Resend. Accepts plain text OR HTML — pass `html` for richer formatting, or `body` for plain text (auto-wrapped in a simple HTML shell).\n\nSame as `POST /v2026-06-01/actions/flyra_send_email`. Scope: `email:send`.","x-required-scope":"email:send","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"description":"Recipient email. Omit when passing customer_id.","type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"customer_id":{"description":"Customer UUID or semantic id. If set and to is omitted, we look up customer.email.","type":"string"},"subject":{"type":"string","minLength":1,"maxLength":998},"body":{"description":"Plain text body. Becomes a simple HTML wrapper.","type":"string"},"html":{"description":"Raw HTML body. Overrides `body` if both are passed.","type":"string"},"reply_to":{"description":"Optional Reply-To header.","type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["subject"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/email-threads":{"get":{"operationId":"listEmailThreads","summary":"List email threads","tags":["Email"],"description":"List email conversations (threads) newest-first, mirroring the email inbox. Each row carries the thread id, the customer link when the sender is known, the last subject and preview, and the unread count.\n\nSame as `POST /v2026-06-01/actions/flyra_list_email_threads`. Scope: `email:read`.","x-required-scope":"email:read","parameters":[{"name":"direction","in":"query","required":false,"schema":{"type":"string","enum":["inbound","outbound"]},"description":"Filters on the latest email in the thread. Omit for both."},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Substring match against customer name, customer email, sender email/name, and the last subject."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":50}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"ISO timestamp from a previous call's next_cursor. Omit for the first page."}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"thread_id":{"type":"string","description":"Pass to flyra_get_email_thread."},"customer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"cus_<uuid>, or null for a sender not matched to a customer."},"lead_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"lead_<uuid> when the thread is with a lead that is not a customer yet, else null."},"is_unknown_sender":{"type":"boolean"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_email_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO timestamp."},"last_subject":{"type":"string"},"last_preview":{"type":"string"},"last_direction":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"inbound or outbound."},"unread_count":{"type":"number"},"summary":{"type":"string"}},"required":["thread_id","customer_id","lead_id","is_unknown_sender","name","email","last_email_at","last_subject","last_preview","last_direction","unread_count","summary"],"additionalProperties":{}}},"limit":{"type":"number"},"truncated":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pass back as cursor for the next page."},"note":{"description":"Set when the first page is empty.","type":"string"}},"required":["items","limit","truncated","next_cursor"],"additionalProperties":{}}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/email-threads/{id}":{"get":{"operationId":"getEmailThread","summary":"Read an email thread","tags":["Email"],"description":"Return the emails on one thread, oldest-first within the page so the agent reads it like a transcript.\n\nSame as `POST /v2026-06-01/actions/flyra_get_email_thread`. Scope: `email:read`.","x-required-scope":"email:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Thread id from GET /email-threads."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":50}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"thread_id":{"type":"string"},"customer_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"lead_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"lead_<uuid> when the thread is with a lead that is not a customer yet, else null."},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"email_<uuid>."},"direction":{"anyOf":[{"type":"string"},{"type":"null"}]},"from":{"anyOf":[{"type":"string"},{"type":"null"}]},"to":{"anyOf":[{"type":"string"},{"type":"null"}]},"subject":{"anyOf":[{"type":"string"},{"type":"null"}]},"body":{"type":"string"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"read":{"type":"boolean"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO timestamp."}},"required":["id","direction","from","to","subject","body","status","read","created_at"],"additionalProperties":{}},"description":"Oldest first within the page."},"limit":{"type":"number"},"truncated":{"type":"boolean"}},"required":["thread_id","customer_id","lead_id","items","limit","truncated"],"additionalProperties":{}}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/calls":{"get":{"operationId":"listCalls","summary":"List calls","tags":["Calls"],"description":"List the org's phone call history, newest first. Covers both inbound and outbound calls and mirrors the Phone page.\n\nSame as `POST /v2026-06-01/actions/flyra_list_calls`. Scope: `calls:read`.","x-required-scope":"calls:read","parameters":[{"name":"filter","in":"query","required":false,"schema":{"type":"string","enum":["all","missed","answered","live"]},"description":"Default \"all\". \"missed\" includes voicemail; \"answered\" means someone picked up; \"live\" means in progress now."},{"name":"direction","in":"query","required":false,"schema":{"type":"string","enum":["inbound","outbound"]},"description":"Omit for both directions."},{"name":"customer_id","in":"query","required":false,"schema":{"type":"string"},"description":"Customer UUID or semantic id — resolved to their contact."},{"name":"contact_id","in":"query","required":false,"schema":{"type":"string"},"description":"Contact UUID or semantic id. Takes precedence over customer_id."},{"name":"transcribed_only","in":"query","required":false,"schema":{"type":"boolean"},"description":"Only calls that were recorded and transcribed."},{"name":"since","in":"query","required":false,"schema":{"type":"string"},"description":"ISO 8601 — only calls that started on or after."},{"name":"include_transcripts","in":"query","required":false,"schema":{"type":"boolean"},"description":"Add each call's full transcript text (null when there is none). Default false; transcripts are long, so keep limit small."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":50}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/calls/{id}":{"get":{"operationId":"getCall","summary":"Get a call","tags":["Calls"],"description":"Fetch a single call by id, including notes, hangup cause, and the call outcome when one was recorded.\n\nSame as `POST /v2026-06-01/actions/flyra_get_call`. Scope: `calls:read`.","x-required-scope":"calls:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Call id from GET /calls."}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/payments":{"get":{"operationId":"listPayments","summary":"List payments","tags":["Invoices"],"description":"List the payments taken in a time window, newest first: the same payments as Reports > Payments (completed, refunded and partly refunded), by when the payment happened.\n\nSame as `POST /v2026-06-01/actions/flyra_list_payments`. Scope: `invoices:read`.","x-required-scope":"invoices:read","parameters":[{"name":"from","in":"query","required":true,"schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"description":"Start of the window, inclusive: when the payment happened. ISO 8601 with Z or an offset, e.g. 2026-10-23T04:00:00Z."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"description":"End of the window, inclusive. ISO 8601 with Z or an offset. Defaults to now."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":50},"description":"Rows per page, up to 50. Defaults to 50."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"payment_methods","in":"query","required":false,"schema":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1}},"description":"Only these methods, as Reports > Payments filters them: method_code as each row returns it (e.g. cash, check); a payment with no method_code is card, or manual when entered by hand."},{"name":"payment_type","in":"query","required":false,"schema":{"type":"string","enum":["subscription","oneTime"]},"description":"Only plan payments (the job behind it belongs to a plan, or a plan's card charge) or only one-time ones, as the report's type filter."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["completed","refunded"]},"description":"Only completed payments, or only refunded and partly refunded ones (refund rows included), as the report's status filter."},{"name":"lead_sources","in":"query","required":false,"schema":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1}},"description":"Only payments whose job came from one of these lead sources (any case). A payment with no job behind it is left out."},{"name":"team_members","in":"query","required":false,"schema":{"maxItems":50,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"description":"Employee ids from flyra_list_employees, as the report's team member filter: only payments on a job or invoice one of them created or is the salesperson on (else on a customer of those jobs and invoices). Only people with a Flyra login count, as on the report."}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions":{"get":{"operationId":"listActions","summary":"List every action","tags":["Actions"],"security":[],"description":"Every action a key can run, with its scope and input JSON Schema. No key needed: it describes the API and reads no data.","responses":{"200":{"description":"The catalog.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"scope":{"type":"string","nullable":true},"read_only":{"type":"boolean"},"destructive":{"type":"boolean"},"method":{"type":"string"},"path":{"type":"string"},"input_schema":{"type":"object"},"output_schema":{"type":"object","nullable":true}}}},"total":{"type":"integer"}}}}}}}}},"/v2026-06-01/actions/flyra_list_organizations":{"post":{"operationId":"flyra_list_organizations","summary":"List connected companies","tags":["Search"],"description":"List every Flyra company (organization) this connection can act on.\n\nUse this to discover the exact company names to pass as the \"organization\" argument on other tools when the account is linked to more than one company. Example: the user says \"what did Aloha Window Bros make this month\" — call this first to find the matching company name, then call flyra_metrics with organization set to it.\n\nReturns: { organizations: [{ id, name }], multi_company }. When multi_company is true, the other tools require an \"organization\" argument to disambiguate which company you mean.\n\nScope: any valid key.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_invite_employee":{"post":{"operationId":"flyra_invite_employee","summary":"Invite an employee","tags":["Employees"],"description":"Invite somebody to join this company, with a role. Sends them an invitation email with a setup link. They occupy a paid seat once they accept, and the invite is refused now if the company is already at its plan limit. Use flyra_list_employees to check who is already here and flyra_list_custom_roles for the available roles. Somebody already on the team (an invite they have not accepted) is refused with duplicate_email_in_org: send them a fresh link with flyra_resend_employee_invite instead.\n\nScope: `employees:write`.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string","minLength":1,"description":"Their first name."},"last_name":{"description":"Their last name.","type":"string"},"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$","description":"Where the invitation is sent. Must not already belong to somebody in this company."},"phone":{"description":"Mobile number, digits only or formatted.","type":"string"},"role":{"type":"string","description":"Either a built-in role name (Admin, Sales Rep, Technician) or the id of a custom role from flyra_list_custom_roles. Admin can see and change everything including billing, so grant it deliberately."}},"required":["first_name","email","role"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_resend_employee_invite":{"post":{"operationId":"flyra_resend_employee_invite","summary":"Resend an employee’s invite","tags":["Employees"],"description":"Email a fresh setup link to somebody who was invited but has not signed up yet, as Resend invite on their page in Settings > Team does. Use this, not flyra_invite_employee, for someone already on the team: inviting them again is refused with duplicate_email_in_org. The link goes to the email on their employee record (fix it first with flyra_set_employee_email if it is wrong) and expires in 24 hours. Someone who already has a Flyra login is refused with not_pending: they sign in as usual, and flyra_add_employees_to_onboarding puts them on their role’s onboarding. Needs confirm: true. Admins, Owners and people who can manage the team, connected through OAuth as themselves.\n\nScope: `employees:write`.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"string","maxLength":200,"description":"The employee, from flyra_list_employees."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed the invitation email should go out again."}},"required":["employee_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_add_employees_to_onboarding":{"post":{"operationId":"flyra_add_employees_to_onboarding","summary":"Put employees on onboarding","tags":["Employees"],"description":"Put existing team members on their role’s onboarding checklist, starting now, as Add people in Settings > Team > Onboarding does. People who join after a role’s onboarding is set up get it on their own. Anyone who was on the team before that, including someone whose invite was resent or who was re-invited on the same record, only gets it this way. Each person gets the list for their own role. Someone whose role has no onboarding is skipped, and someone already on it stays where they are. The checklist shows the next time they open the Flyra app. Admins, Owners and people with Manage onboarding, connected through OAuth as themselves.\n\nScope: `employees:write`.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_ids":{"minItems":1,"maxItems":200,"type":"array","items":{"type":"string","maxLength":200},"description":"The employees, from flyra_list_employees."}},"required":["employee_ids"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_employee_role":{"post":{"operationId":"flyra_set_employee_role","summary":"Change an employee’s role","tags":["Employees"],"description":"Move an existing employee onto a different role. Their permissions are replaced by the new role’s, so anything the old role allowed and the new one does not is withdrawn immediately. Refused if it would leave the company with no Admin who can sign in. Does not change whether they have access; use flyra_deactivate_employee for that.\n\nScope: `employees:write`.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"string","description":"The employee, from flyra_list_employees."},"role":{"type":"string","description":"Either a built-in role name (Admin, Sales Rep, Technician) or the id of a custom role from flyra_list_custom_roles. Admin can see and change everything including billing, so grant it deliberately."}},"required":["employee_id","role"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_employee_phone":{"post":{"operationId":"flyra_set_employee_phone","summary":"Set an employee’s phone number","tags":["Employees"],"description":"Set or clear the mobile number on an existing employee. Automation texts to the team, such as a Job Closed alert, go to this number, and an employee without one gets no text. It is also the number customer messages show for {employee_phone} and {salesperson_phone}. Changes nothing else about the employee.\n\nScope: `employees:write`.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"string","description":"The employee, from flyra_list_employees."},"phone":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"description":"Their mobile number, digits only or formatted, with the country code if it is not a local number. Empty or null clears it."}},"required":["employee_id","phone"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_employee_name_and_color":{"post":{"operationId":"flyra_set_employee_name_and_color","summary":"Set an employee’s name or colour","tags":["Employees"],"description":"Change the first name, last name or calendar colour of an existing employee, as the name fields and colour swatch on their page in Settings > Team do. Pass only what changes. The colour is a hex colour such as #2563EB and is what their jobs show in on the schedule. Changes nothing else about the employee: not their role, access, email or login. Admins and Owners only, connected through OAuth as themselves.\n\nScope: `employees:write`.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"string","maxLength":200,"description":"The employee, from flyra_list_employees."},"first_name":{"description":"Empty or null clears it.","anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"last_name":{"description":"Empty or null clears it.","anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"color_tag":{"description":"A hex colour such as #2563EB.","type":"string","maxLength":16}},"required":["employee_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_employee_email":{"post":{"operationId":"flyra_set_employee_email","summary":"Set an employee’s email","tags":["Employees"],"description":"Change the email of an existing employee, as the email field on their page in Settings > Team does. Only someone who has not signed up yet (an invite) can get a new email: once a person has a Flyra login, their email is the email they sign in with and this refuses with code login_email, as the app keeps it. Changes nothing else, and does not send the invite again. Needs confirm: true. Admins and Owners only, connected through OAuth as themselves.\n\nScope: `employees:write`.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"string","maxLength":200,"description":"The employee, from flyra_list_employees."},"email":{"type":"string","maxLength":320,"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$","description":"The new email address."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed the new email."}},"required":["employee_id","email","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_employee_bio":{"post":{"operationId":"flyra_set_employee_bio","summary":"Set an employee’s “About me”","tags":["Employees"],"description":"Set or clear the short bio (\"About me\") on an existing employee. Customers see it under the technician's photo on their visit page (the Meet your cleaner text the day before, then live tracking). Write a few lines in their voice: how long they have done this, what they take pride in, something human. At most 400 characters. Empty or null hides the section. Changes nothing else about the employee; flyra_list_employees shows the current bio.\n\nScope: `employees:write`.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"string","description":"The employee, from flyra_list_employees."},"bio":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"description":"The bio, at most 400 characters once trimmed. Empty or null clears it."}},"required":["employee_id","bio"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_deactivate_employee":{"post":{"operationId":"flyra_deactivate_employee","summary":"Switch off an employee’s access","tags":["Employees"],"description":"Take away an employee’s access to this company and sign them out everywhere immediately. Reversible with flyra_reactivate_employee, and it frees their paid seat. Their scheduled jobs and route stops are deliberately left assigned to them, so tomorrow’s schedule does not empty; reassign anything that matters with flyra_job_assign_employee. Refused if they are the last Admin who can sign in.\n\nScope: `employees:write`. Destructive: it deletes or cancels.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"string","description":"The employee, from flyra_list_employees."}},"required":["employee_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_reactivate_employee":{"post":{"operationId":"flyra_reactivate_employee","summary":"Give an employee their access back","tags":["Employees"],"description":"Turn a deactivated employee’s access back on. They take a paid seat again, so this is refused if the company is at its plan limit. Somebody who was fully removed rather than deactivated cannot be reactivated and has to be invited again with flyra_invite_employee.\n\nScope: `employees:write`.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"string","description":"The employee, from flyra_list_employees."}},"required":["employee_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_employee_live_location":{"post":{"operationId":"flyra_get_employee_live_location","summary":"Get an employee’s live location requirement","tags":["Employees"],"description":"The \"Require live location\" switch on an employee's page in Settings > Team, Admin or Owner only: require_live_location is the person's own switch, role_requires is true when their role already requires it (the switch shows on and locked, \"Required by the {role_name} role\"). Needs a signed-in Flyra user. Read only.\n\nScope: `employees:read`.","x-required-scope":"employees:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"string","description":"The employee, from flyra_list_employees."}},"required":["employee_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_employee_live_location":{"post":{"operationId":"flyra_set_employee_live_location","summary":"Require an employee to share live location","tags":["Employees"],"description":"Turns the \"Require live location\" switch on an employee's page in Settings > Team on or off, Admin or Owner only. When their role already requires it (role_requires from flyra_get_employee_live_location), turning the person's switch off does not lift the role's requirement. Sends nothing to anyone. Returns the switch as saved. Needs a signed-in Flyra user.\n\nScope: `employees:write`.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"string","description":"The employee, from flyra_list_employees."},"require_live_location":{"type":"boolean"}},"required":["employee_id","require_live_location"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_notification_preferences":{"post":{"operationId":"flyra_get_notification_preferences","summary":"Get my notification preferences","tags":["Employees"],"description":"The signed-in person's own list on Settings > Profile > Notifications: each notification they can receive here, grouped as on the page, with its push and email switches (true = on). A channel left out of a row is not offered to them. Only their own switches, never anyone else's; the mute-all switch above the list is not included. Needs a signed-in Flyra user: an organization API key is refused. Read only.\n\nScope: `employees:read`.","x-required-scope":"employees:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_notification_preference":{"post":{"operationId":"flyra_set_notification_preference","summary":"Switch one of my notifications on or off","tags":["Employees"],"description":"Flips one switch on Settings > Profile > Notifications for the signed-in person only: key is a row key from flyra_get_notification_preferences, channel is push or email, enabled true or false. Changes nothing for anyone else and sends nothing. Returns the whole list as it now stands. Needs a signed-in Flyra user: an organization API key is refused.\n\nScope: `employees:write`.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","minLength":1,"description":"A row key from flyra_get_notification_preferences, e.g. job_dispatched."},"channel":{"type":"string","enum":["push","email"]},"enabled":{"type":"boolean","description":"true = receive it, false = stop it."}},"required":["key","channel","enabled"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_add_employee_file":{"post":{"operationId":"flyra_add_employee_file","summary":"Add a file to an employee’s record","tags":["Employees"],"description":"Add a file to the Files section of an employee’s page in Flyra, as its Upload file button does. PDF, DOC, DOCX, JPG or PNG, up to 10 MB. It is not sent to anyone. Give the file as file_url (a public https link that does not redirect) or as file_base64 (the file’s bytes), and its file_name with the extension. Any active member of the company may add one, as on the page; an organization API key with no person behind it is refused. Returns the stored file’s link.\n\nScope: `employees:write`.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"string","description":"The employee, from flyra_list_employees."},"file_url":{"description":"Public https link to the file. Pass this or file_base64.","type":"string"},"file_base64":{"description":"The file’s bytes, base64 encoded. Pass this or file_url.","type":"string","maxLength":14000000},"file_name":{"type":"string","minLength":1,"maxLength":200,"description":"The file’s name with its extension, e.g. \"W-9.pdf\". It is listed under this name."},"content_type":{"description":"The file type, e.g. application/pdf. Only used with file_base64; a link’s own type is used otherwise.","type":"string","pattern":"^[\\w.+-]+\\/[\\w.+-]+$"},"expires_on":{"description":"Optional. The day the document runs out (a licence, insurance or certification), YYYY-MM-DD. An automation on employee.document_expiring can warn ahead of it.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["employee_id","file_name"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_employee_file_expiry":{"post":{"operationId":"flyra_set_employee_file_expiry","summary":"Set when an employee’s file expires","tags":["Employees"],"description":"Set or clear the expiry date on a file in the Files section of an employee’s page (a licence, insurance or certification), so an automation on employee.document_expiring can warn ahead of it. file_id comes from flyra_add_employee_file. Pass expires_on as YYYY-MM-DD, or null to clear it. Nothing is sent to anyone. Only an Admin or Owner may; an organization API key with no person behind it is refused.\n\nScope: `employees:write`.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"file_id":{"type":"string","description":"The file, from flyra_add_employee_file."},"expires_on":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"The day the document runs out, YYYY-MM-DD, or null to clear it."}},"required":["file_id","expires_on"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_employee_photo":{"post":{"operationId":"flyra_set_employee_photo","summary":"Set an employee’s profile picture","tags":["Employees"],"description":"Replace the profile picture on an employee’s page in Flyra, as uploading a photo there or on Settings > Profile does. The old picture is deleted. JPEG, PNG or WebP, up to 2 MB. If the employee has signed up, the same picture becomes their avatar in every company they belong to. Only a member with the Admin role, or the employee themselves, may; an organization API key with no person behind it is refused. Give the picture as image_url (a public https link that does not redirect) or image_base64 (its bytes), and its file_name with the extension.\n\nScope: `employees:write`.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"string","description":"The employee, from flyra_list_employees."},"image_url":{"description":"Public https link to the picture. Pass this or image_base64.","type":"string"},"image_base64":{"description":"The picture’s bytes, base64 encoded. Pass this or image_url.","type":"string","maxLength":3000000},"file_name":{"type":"string","minLength":1,"maxLength":200,"description":"The picture’s file name with its extension, e.g. \"jane.jpg\". The extension must be jpg, jpeg, png or webp."},"content_type":{"description":"The picture’s type. Only used with image_base64; a link’s own type is used otherwise.","type":"string","enum":["image/jpeg","image/png","image/webp"]}},"required":["employee_id","file_name"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_report_gap":{"post":{"operationId":"flyra_report_gap","summary":"Report something this connection could not do","tags":["Settings"],"description":"Call this when you could NOT complete what the user asked because this Flyra connection has no tool for it, or the tool that exists cannot express what they wanted. Before you call it for something that should happen on its own, every time (a text before each job, a follow-up after a payment, a message when a lead arrives), check whether an automation can do it: flyra_save_automation lists the triggers and steps. If one does it, or comes close, recommend it to the user and offer to set it up instead of reporting a gap; report one only if nothing close exists or the user still needs the exact thing. Send it once per distinct gap, after you have told the user you cannot do the thing through this connection. It reaches the Flyra team with the user’s request attached. Do not use it for errors in your own arguments, for a missing permission, for questions about how to use Flyra, or to report a problem with the customer’s data — retry or explain those instead.\n\nScope: `settings:read`.","x-required-scope":"settings:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"wanted":{"type":"string","minLength":10,"maxLength":1000,"description":"What the user actually asked for, as close to their own words as you can. This is the most useful field: write what they wanted, not what you tried."},"blocked_by":{"type":"string","minLength":5,"maxLength":1000,"description":"Why you could not do it. Name the tool you expected to find, or the argument the existing tool would not take."},"tools_tried":{"description":"Tool names you tried first, if any. Helps us tell a missing tool from one that is hard to find.","maxItems":10,"type":"array","items":{"type":"string"}}},"required":["wanted","blocked_by"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_bulk_update":{"post":{"operationId":"flyra_bulk_update","summary":"Change many records at once","tags":["Bulk"],"description":"Edit every record matching a filter, in one call, instead of looping a single-record update.\n\nTWO WAYS TO CHANGE THE RECORDS, and you may use both in one call:\n- set: write the same value to every matched record. `{\"city\": \"Phoenix\"}`. Pass null to clear a field.\n- find_replace: substitute text inside each record's existing value, so every record keeps its own. This is the one for cleaning up imports — stripping \" UNC (solar deal)\" off 2,000 different surnames is one call, not 2,000.\n\nSELECTING THE RECORDS:\n- Pass `ids` and the call runs immediately.\n- Pass a filter (query / status / city / tag / …) and the FIRST call is a dry run: it reports how many matched, shows a sample of the exact before → after text, and returns a `confirm_token`. Call again with that token to actually write. Nothing changes until you do.\n\nThe token is tied to the exact records and the exact change previewed. If either moved, it is refused and you preview again.\n\nUse flyra_bulk_delete to remove records and flyra_bulk_tag_customers for tags — this tool writes columns only.\n\nA lead's Lead Source (lead_source_id, the dropdown and the source report) is not bulk-editable; `source` on a lead is only a free-text label. Set it per lead with flyra_update_lead_stage, or on creation with flyra_create_lead.\n\nA lead's pipeline (pipeline_id) is not bulk-editable either: move each lead with flyra_update_lead_stage and pipeline_id, which also puts it on that pipeline's first stage or the status_stage you name.\n\nScope: depends on `entity` (for example `leads:write`).","x-required-scope":"varies","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"entity":{"type":"string","enum":["customers","leads","jobs","estimates","invoices","tasks"],"description":"Which records to edit."},"ids":{"description":"Explicit record ids (raw UUIDs or semantic ids). Naming ids runs the call immediately — no confirm_token needed.","maxItems":2000,"type":"array","items":{"type":"string"}},"query":{"description":"Free-text match on the entity's text columns. Matched literally: query=\"UNC (solar deal)\" finds that exact phrase, parentheses included.","type":"string"},"status":{"description":"Match any of these status values. Not available on customers.","type":"array","items":{"type":"string"}},"city":{"description":"customers and leads only.","type":"string"},"state":{"description":"customers and leads only.","type":"string"},"zip":{"description":"customers and leads only (leads match on postal_code).","type":"string"},"tag":{"description":"customers only — tag label or tag id.","type":"string"},"customer_id":{"description":"jobs, estimates and invoices only — records belonging to this customer.","type":"string"},"created_after":{"description":"ISO 8601 — records created on or after.","type":"string"},"created_before":{"description":"ISO 8601 — records created strictly before.","type":"string"},"last_booked_days_gt":{"description":"Not available here. Page the matches out of flyra_filter_customers and pass their `ids`.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"min_lifetime_value_cents":{"description":"Not available here — see last_booked_days_gt.","type":"integer","minimum":0,"maximum":9007199254740991},"has_subscription":{"description":"Not available here — see last_booked_days_gt.","type":"boolean"},"has_unpaid_invoice":{"description":"Not available here — see last_booked_days_gt.","type":"boolean"},"set":{"description":"Field → new value, applied to every matched record. null clears the field. Customers also take notifications_enabled: true or false. The customer page's Automations switch. false pauses this customer's automatic messages; true resumes them. Paused: job reminders; estimate, invoice, review and subscription-invitation follow-ups; review and referral requests; invoices sent automatically when a job is completed; recurring customer follow-ups. Workflows: a workflow message for this customer that starts after the switch is off is held, job status texts included in orgs that run them as workflows, except the estimate, invoice, receipt, subscription and subscription confirmation workflows. A workflow already waiting on a delay still sends, and so does one for a lead not yet linked to this customer. Not paused (the app's built-in senders): job status texts (booking confirmation, on the way, arrival, completed and the rest), payment receipts, failed-payment and add-a-card notices, subscription confirmations, tip requests, holiday emails, SMS blasts and their follow-ups, and anything a team member sends by hand. If the check itself fails, the message is sent. Only the customer replying STOP to a text blocks every text to their number. Tell the user this before they rely on it for compliance. Turning it back on (true) resumes these messages; confirm with the user first, because someone may have paused the customer on purpose.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"boolean"},{"type":"null"}]}},"find_replace":{"description":"Substitute text inside each record's current value.","type":"object","properties":{"fields":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Which text fields to substitute in."},"find":{"type":"string","minLength":1,"description":"The exact text to look for. Matched literally, not as a pattern."},"replace":{"type":"string","description":"What to put in its place. Use \"\" to delete the text."},"match_case":{"description":"Default true. false matches regardless of case.","type":"boolean"}},"required":["fields","find","replace"]},"confirm_token":{"description":"The token from this tool's dry run. Required to write when selecting by filter.","type":"string"}},"required":["entity"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_bulk_delete":{"post":{"operationId":"flyra_bulk_delete","summary":"Delete many records at once","tags":["Bulk"],"description":"Permanently delete every record matching a filter. There is no undo — confirm with the user before calling.\n\nSELECTING THE RECORDS:\n- Pass `ids` and the deletion runs immediately.\n- Pass a filter and the FIRST call is a dry run: it reports how many matched and shows a sample of the actual records, then returns a `confirm_token`. Nothing is deleted until a second call hands that token back. The token is tied to that exact set, so if the data moved in between it is refused and you preview again.\n\nEACH ENTITY KEEPS ITS OWN GUARDRAILS, and a refused record does not stop the rest — you get back which ones went and why each survivor stayed:\n- customers: linked jobs, estimates, invoices and attachments go too. A customer with a live subscription is refused unless you pass force=true, which cancels it in Stripe first. A job carrying a card, invoice or subscription payment refuses the whole customer.\n- jobs: a job with a Stripe, invoice or subscription payment on it is refused; linked invoice totals are recomputed for the ones that go.\n- invoices: refused once any money is attached. The invoice number is not reclaimed.\n- estimates: an accepted estimate is refused — it is the record of a won deal.\n- leads and tasks: deleted outright with their history.\n\nLarge sets are deleted in capped batches; `remaining` tells you how many are left and the same call continues.\n\nScope: depends on `entity` (for example `leads:write`). Destructive: it deletes or cancels.","x-required-scope":"varies","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"entity":{"type":"string","enum":["customers","leads","jobs","estimates","invoices","tasks"],"description":"Which records to delete."},"ids":{"description":"Explicit record ids (raw UUIDs or semantic ids). Naming ids runs the call immediately — no confirm_token needed.","maxItems":2000,"type":"array","items":{"type":"string"}},"query":{"description":"Free-text match on the entity's text columns. Matched literally: query=\"UNC (solar deal)\" finds that exact phrase, parentheses included.","type":"string"},"status":{"description":"Match any of these status values. Not available on customers.","type":"array","items":{"type":"string"}},"city":{"description":"customers and leads only.","type":"string"},"state":{"description":"customers and leads only.","type":"string"},"zip":{"description":"customers and leads only (leads match on postal_code).","type":"string"},"tag":{"description":"customers only — tag label or tag id.","type":"string"},"customer_id":{"description":"jobs, estimates and invoices only — records belonging to this customer.","type":"string"},"created_after":{"description":"ISO 8601 — records created on or after.","type":"string"},"created_before":{"description":"ISO 8601 — records created strictly before.","type":"string"},"last_booked_days_gt":{"description":"Not available here. Page the matches out of flyra_filter_customers and pass their `ids`.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"min_lifetime_value_cents":{"description":"Not available here — see last_booked_days_gt.","type":"integer","minimum":0,"maximum":9007199254740991},"has_subscription":{"description":"Not available here — see last_booked_days_gt.","type":"boolean"},"has_unpaid_invoice":{"description":"Not available here — see last_booked_days_gt.","type":"boolean"},"force":{"description":"customers only. Default false. true cancels the customer's live Stripe subscriptions rather than refusing the delete. Ask the user before setting it.","type":"boolean"},"confirm_token":{"description":"The token from this tool's dry run. Required to delete when selecting by filter.","type":"string"}},"required":["entity"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_bulk_tag_customers":{"post":{"operationId":"flyra_bulk_tag_customers","summary":"Tag or untag many customers at once","tags":["Customers"],"description":"Add or remove one tag across every customer matching a filter, in a single call.\n\nTags are a join table rather than a column, which is why they are not part of flyra_bulk_update. Pass `tag_id` (from flyra_list_tags) or `label` — a label that does not exist yet is created.\n\nIdempotent: adding a tag a customer already carries, or removing one they never had, is a no-op rather than an error.\n\nSelection works exactly as in flyra_bulk_update: `ids` runs immediately, a filter gives you a dry run with a `confirm_token` first.\n\nScope: `customers:write`.","x-required-scope":"customers:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"description":"Explicit record ids (raw UUIDs or semantic ids). Naming ids runs the call immediately — no confirm_token needed.","maxItems":2000,"type":"array","items":{"type":"string"}},"query":{"description":"Free-text match on the entity's text columns. Matched literally: query=\"UNC (solar deal)\" finds that exact phrase, parentheses included.","type":"string"},"status":{"description":"Match any of these status values. Not available on customers.","type":"array","items":{"type":"string"}},"city":{"description":"customers and leads only.","type":"string"},"state":{"description":"customers and leads only.","type":"string"},"zip":{"description":"customers and leads only (leads match on postal_code).","type":"string"},"tag":{"description":"customers only — tag label or tag id.","type":"string"},"customer_id":{"description":"jobs, estimates and invoices only — records belonging to this customer.","type":"string"},"created_after":{"description":"ISO 8601 — records created on or after.","type":"string"},"created_before":{"description":"ISO 8601 — records created strictly before.","type":"string"},"last_booked_days_gt":{"description":"Not available here. Page the matches out of flyra_filter_customers and pass their `ids`.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"min_lifetime_value_cents":{"description":"Not available here — see last_booked_days_gt.","type":"integer","minimum":0,"maximum":9007199254740991},"has_subscription":{"description":"Not available here — see last_booked_days_gt.","type":"boolean"},"has_unpaid_invoice":{"description":"Not available here — see last_booked_days_gt.","type":"boolean"},"action":{"type":"string","enum":["add","remove"],"description":"\"add\" links the tag, \"remove\" unlinks it."},"tag_id":{"description":"Tag id from flyra_list_tags. Preferred over label.","type":"string"},"label":{"description":"Tag label. On \"add\", a label with no matching tag creates one.","type":"string"},"color":{"description":"Hex color for a tag created from a label (default #94a3b8).","type":"string"},"confirm_token":{"description":"The token from this tool's dry run. Required when selecting by filter.","type":"string"}},"required":["action"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_search_customers":{"post":{"operationId":"flyra_search_customers","summary":"Search Flyra customers","tags":["Customers"],"description":"Search the org customer list. Use this BEFORE flyra_get_customer when you only have a name, email, or phone. Returns concise summaries by default (id + name + one-line contact); pass format=\"detailed\" for full records. Always paginated; cap is 50 per call. With updated_since or cursor it returns full customer records with tags (as flyra_get_customer, without recent jobs) changed since then, oldest change first. To keep a copy in sync, do not call the get tool for each record and do not re-read the whole list: call this tool with updated_since once, then keep passing next_cursor until has_more is false, save that last next_cursor, and on your next run (every 5 to 15 minutes is plenty) start from it. Changes from the last 30 seconds arrive on the next run.\n\nScope: `customers:read`.","x-required-scope":"customers:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"description":"Free-text match against first_name, last_name, display_name, email, mobile_phone.","type":"string"},"email":{"description":"Exact email match.","type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"phone":{"description":"Exact mobile_phone match (E.164 preferred — e.g. +15551234567).","type":"string"},"limit":{"description":"Max records to return (default 25, hard cap 50).","type":"integer","exclusiveMinimum":0,"maximum":50},"offset":{"description":"Pagination offset.","type":"integer","minimum":0,"maximum":9007199254740991},"format":{"description":"\"concise\" (default) returns id+name+summary; \"detailed\" returns full records.","type":"string","enum":["concise","detailed"]},"updated_since":{"description":"ISO 8601 time. Switches to \"changed since\" mode: only records created or edited at or after it, oldest change first, each row complete. Use it once to start a sync, then pass cursor instead.","type":"string"},"cursor":{"description":"next_cursor from your previous call. Pass it to read the next page, and save the last one to start your next run where this one stopped.","type":"string"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_customer":{"post":{"operationId":"flyra_get_customer","summary":"Fetch a Flyra customer by id","tags":["Customers"],"description":"Returns the full record for a single customer plus their 5 most recent jobs. Accepts either the raw UUID OR a semantic id like \"cus_<uuid>\" returned by flyra_search_customers.\n\nScope: `customers:read`.","x-required-scope":"customers:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string","description":"Customer UUID or semantic id from flyra_search_customers."}},"required":["customer_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_create_customer":{"post":{"operationId":"flyra_create_customer","summary":"Create a Flyra customer","tags":["Customers"],"description":"Creates a new customer in the org. Either first_name or last_name is required; email or mobile_phone is required. If a customer with the same email or phone already exists in the org, behaviour depends on `if_exists`: \"return\" (default) returns the existing record; \"error\" returns a duplicate error. This takes the customer and one service address, as the New Customer form does. For the rest, call these after the create with the returned id, as the app does: flyra_add_tag_to_customer for each tag, flyra_add_customer_contact for another person on the customer, flyra_add_customer_property for another service address. Flyra customers have no company name field: for a business, put the name it goes by in display_name.\n\nScope: `customers:write`.","x-required-scope":"customers:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"display_name":{"type":"string"},"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"mobile_phone":{"description":"E.164 preferred (e.g. +15551234567).","type":"string"},"address":{"type":"string"},"unit":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zip":{"type":"string"},"notes":{"type":"string"},"lead_source":{"description":"Where the customer came from, as Lead source on the customer page's edit form: a name from flyra_list_lead_sources (e.g. \"Google Ads\"). New jobs for the customer inherit it; existing jobs keep theirs.","type":"string","maxLength":500},"if_exists":{"description":"Default \"return\": returns existing customer on email/phone match. \"error\" rejects duplicates.","type":"string","enum":["return","error"]}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_customer":{"post":{"operationId":"flyra_update_customer","summary":"Update a Flyra customer","tags":["Customers"],"description":"Partial update — pass only the fields you want to change. Pass null to clear a field; omit the field entirely to leave it unchanged. notes replaces the customer's whole Notes box; to add a note below the notes already there, use flyra_add_customer_note instead.\n\nScope: `customers:write`.","x-required-scope":"customers:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string","description":"Customer UUID or semantic id."},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"null"}]},"mobile_phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"address":{"anyOf":[{"type":"string"},{"type":"null"}]},"unit":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"zip":{"anyOf":[{"type":"string"},{"type":"null"}]},"notes":{"anyOf":[{"type":"string"},{"type":"null"}]},"lead_source":{"description":"Where the customer came from, as Lead source on the customer page's edit form: a name from flyra_list_lead_sources (e.g. \"Google Ads\"). New jobs for the customer inherit it; existing jobs keep theirs. null clears it.","anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"notifications_enabled":{"description":"The customer page's Automations switch. false pauses this customer's automatic messages; true resumes them. Paused: job reminders; estimate, invoice, review and subscription-invitation follow-ups; review and referral requests; invoices sent automatically when a job is completed; recurring customer follow-ups. Workflows: a workflow message for this customer that starts after the switch is off is held, job status texts included in orgs that run them as workflows, except the estimate, invoice, receipt, subscription and subscription confirmation workflows. A workflow already waiting on a delay still sends, and so does one for a lead not yet linked to this customer. Not paused (the app's built-in senders): job status texts (booking confirmation, on the way, arrival, completed and the rest), payment receipts, failed-payment and add-a-card notices, subscription confirmations, tip requests, holiday emails, SMS blasts and their follow-ups, and anything a team member sends by hand. If the check itself fails, the message is sent. Only the customer replying STOP to a text blocks every text to their number. Tell the user this before they rely on it for compliance. Turning it back on (true) resumes these messages; confirm with the user first, because someone may have paused the customer on purpose.","type":"boolean"}},"required":["customer_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_add_customer_note":{"post":{"operationId":"flyra_add_customer_note","summary":"Add a note to a customer","tags":["Customers"],"description":"Adds a note below what the customer's Notes box already says, with a blank line between. Earlier notes stay; nothing is overwritten. It is the same append the automation Add note step makes on a customer: if someone saves the Notes box at the same moment, it reads again and retries once, then refuses rather than overwrite them. It sends nothing and starts no automation. Use flyra_update_customer with notes only to replace the whole box, and flyra_add_lead_note for a lead's timeline.\n\nScope: `customers:write`.","x-required-scope":"customers:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string","description":"Customer UUID or semantic id, from flyra_search_customers."},"note":{"type":"string","description":"The note text."}},"required":["customer_id","note"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_customer_balance":{"post":{"operationId":"flyra_get_customer_balance","summary":"Get the customer's outstanding balance","tags":["Customers"],"description":"Sum of unpaid invoice totals for a customer. Returns total_owed_cents, overdue_owed_cents, and the list of unpaid invoices so the agent can offer to send reminders.\n\nScope: `customers:read`.","x-required-scope":"customers:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string","description":"Customer UUID or semantic id."}},"required":["customer_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_customer_activity":{"post":{"operationId":"flyra_get_customer_activity","summary":"Get a unified activity timeline for a customer","tags":["Customers"],"description":"Returns a chronological feed mixing jobs, invoices, and recent messages for a customer. Useful for \"what's the last time we talked to X?\" or \"what did we sell them this year?\".\n\nScope: `customers:read`.","x-required-scope":"customers:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string"},"limit":{"description":"Default 20, hard cap 50.","type":"integer","exclusiveMinimum":0,"maximum":50},"since":{"description":"ISO 8601 — only events on or after.","type":"string"}},"required":["customer_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_export_customers":{"post":{"operationId":"flyra_export_customers","summary":"Export customers as CSV","tags":["Customers"],"description":"Export the organization's customer list as CSV text (name, email, phone, address, and the date added in the organization's timezone), 500 customers per call, oldest first. Available per organization; where it is not enabled the reply says so and an admin can export from Customers > Export in the Flyra web app instead. Page with offset until next_offset is null, then join the csv values (drop the header line on every page but the first) and save the result as a .csv file.\n\nScope: `customers:read`.","x-required-scope":"customers:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"offset":{"description":"Row to start from (default 0). Pass the next_offset from the previous call.","type":"integer","minimum":0,"maximum":9007199254740991},"limit":{"description":"Rows per call (default and cap 500).","type":"integer","exclusiveMinimum":0,"maximum":500}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_import_customers":{"post":{"operationId":"flyra_import_customers","summary":"Import many customers at once","tags":["Customers"],"description":"Add a list of customers in one go, like Import with AI on the Customers page. Use this for any spreadsheet or list instead of calling flyra_create_customer in a loop: each create fires the org's \"Customer Created\" automations, an import does not.\n\nMap the file's columns onto the row fields yourself. Rows are numbered from 1 in the order sent.\n\nThe FIRST call is a dry run that saves nothing: it returns how many rows will import, rows with nothing to keep, likely duplicates of existing customers (by phone or email) and of other rows, a sample, and a confirm_token. Show the user, then call again with the SAME rows and that token to import.\n\nAddresses are placed on the map when imported. Nothing is sent to customers. Undo within 24 hours with flyra_undo_customer_import.\n\nScope: `customers:write`.","x-required-scope":"customers:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"object","properties":{"first_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"display_name":{"description":"Full name. Used when there is no first_name, and split into first and last.","anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"mobile_phone":{"description":"Any common format; stored the way the app stores it.","anyOf":[{"type":"string"},{"type":"null"}]},"address":{"description":"Street line, or a whole address in one cell (it is split into street, city, state and zip).","anyOf":[{"type":"string"},{"type":"null"}]},"unit":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}]},"zip":{"anyOf":[{"type":"string"},{"type":"null"}]},"notes":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false},"description":"The customers, up to 500 per call. Split a longer list into several calls; each is its own import with its own undo."},"filename":{"description":"The file the rows came from, recorded with the import.","type":"string","maxLength":255},"skip_existing_matches":{"description":"true leaves out rows that match a customer already in the account. Default false imports them too, as the page does unless \"Skip these rows\" is ticked. Rows that repeat each other always import.","type":"boolean"},"confirm_token":{"description":"The token from this tool's dry run. Required to import.","type":"string"}},"required":["rows"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_undo_customer_import":{"post":{"operationId":"flyra_undo_customer_import","summary":"Undo a customer import","tags":["Customers"],"description":"Delete every customer one import added, like Undo after Import with AI on the Customers page. Only within 24 hours of the import, and only once.\n\nPass the import_job_id flyra_import_customers returned. Refused when any of those customers is already linked to jobs, invoices or subscriptions. Confirm with the user first: the customers are deleted, not archived.\n\nScope: `customers:write`. Destructive: it deletes or cancels.","x-required-scope":"customers:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"import_job_id":{"type":"string","minLength":1,"description":"From flyra_import_customers."}},"required":["import_job_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_import_jobs":{"post":{"operationId":"flyra_import_jobs","summary":"Import past job history","tags":["Jobs"],"description":"Import past jobs from another CRM, like Import with AI on Reports > Jobs. Admins and Owners only. Map the file's columns onto the row fields yourself.\n\nOnly finished history is imported: status completed or cancelled, and start_at (plus end_at, completed_at and paid_at when given) more than 90 days ago. Every other row is refused with a reason. Nothing is sent to customers, and follow-ups (reviews, tips, auto invoices, reminders) are marked as already handled on these jobs.\n\ndry_run defaults to true and saves nothing. To import, call again with dry_run false and confirm true. Up to 200 rows per call; each call is its own import. A job already imported before (or listed twice) is skipped and counted in skipped_already_imported. The app has no Undo for a connector import, so check the dry run first.\n\nScope: `jobs:write`.","x-required-scope":"jobs:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"minItems":1,"maxItems":200,"type":"array","items":{"type":"object","properties":{"customer_name":{"description":"Required. Matched to an existing customer by phone, email, then name; a new customer is created otherwise.","anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"address":{"description":"The service address as one line.","anyOf":[{"type":"string"},{"type":"null"}]},"title":{"description":"Service name. Also the one line item.","anyOf":[{"type":"string"},{"type":"null"}]},"amount":{"description":"Job total in dollars.","anyOf":[{"type":"number"},{"type":"null"}]},"status":{"description":"completed or cancelled. Anything else is refused.","anyOf":[{"type":"string"},{"type":"null"}]},"start_at":{"description":"Required ISO date-time of the visit, more than 90 days ago.","anyOf":[{"type":"string"},{"type":"null"}]},"end_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"completed_at":{"description":"Defaults to start_at for a completed job.","anyOf":[{"type":"string"},{"type":"null"}]},"paid":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"paid_at":{"description":"Required when paid is true.","anyOf":[{"type":"string"},{"type":"null"}]},"source_ref":{"description":"The other CRM's job number; becomes the job number when free.","anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false}},"filename":{"type":"string","maxLength":255},"dry_run":{"description":"Default true: report what would import and write nothing.","type":"boolean"},"confirm":{"description":"Required with dry_run false.","type":"boolean","const":true}},"required":["rows"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_search_jobs":{"post":{"operationId":"flyra_search_jobs","summary":"Search Flyra jobs","tags":["Jobs"],"description":"List jobs matching filters. Status / customer / created-date filters available. Returns concise summaries by default; pass format=\"detailed\" for full records, which include each job's custom_fields answers (as flyra_get_job). Always paginated; cap is 50 per call. With updated_since or cursor it returns full job records with line items (as flyra_get_job, without the tip link) changed since then, oldest change first. Each line item carries upsell (the Upsell switch) and upsell_salesperson_ids (the employees credited with the upsell, counted only when upsell is true). To keep a copy in sync, do not call the get tool for each record and do not re-read the whole list: call this tool with updated_since once, then keep passing next_cursor until has_more is false, save that last next_cursor, and on your next run (every 5 to 15 minutes is plenty) start from it. Changes from the last 30 seconds arrive on the next run.\n\nScope: `jobs:read`.","x-required-scope":"jobs:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"Filter by job status.","type":"string","enum":["scheduled","on_the_way","arrival","in_progress","completed","cancelled","overdue"]},"customer_id":{"description":"Customer UUID or semantic id.","type":"string"},"since":{"description":"ISO 8601 — only jobs created on or after this timestamp.","type":"string"},"limit":{"description":"Default 25, hard cap 50.","type":"integer","exclusiveMinimum":0,"maximum":50},"offset":{"description":"Pagination offset.","type":"integer","minimum":0,"maximum":9007199254740991},"format":{"type":"string","enum":["concise","detailed"]},"updated_since":{"description":"ISO 8601 time. Switches to \"changed since\" mode: only records created or edited at or after it, oldest change first, each row complete. Use it once to start a sync, then pass cursor instead.","type":"string"},"cursor":{"description":"next_cursor from your previous call. Pass it to read the next page, and save the last one to start your next run where this one stopped.","type":"string"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_job":{"post":{"operationId":"flyra_get_job","summary":"Fetch a Flyra job by id","tags":["Jobs"],"description":"Returns full job detail including line items. Accepts raw UUID or semantic id. Each line item's applied_tax_rates lists the tax rates it is charged ({ id, name, rate_percent }; add the rate_percent values for the item's combined rate). An item with taxable false is not taxed. An item with taxable true and no applied_tax_rates is charged the org's tax rates added together (flyra_get_org_settings lists them). Each line item's upsell is true when the job page's Upsell switch is on, and upsell_salesperson_ids lists the employees (emp_ ids, as flyra_list_employees) credited with it. The ids count only when upsell is true (switching it off keeps the old ids, and then the closer keeps the credit); an upsell with no ids leaves the credit with the job's closer. Change them with flyra_set_job_line_item_upsell. For a completed job that is paid in full, tip_link is the customer's \"leave a tip\" page; getting it sends nothing, so text it with flyra_send_sms if the owner asks. If the job was already tipped or tips are off, the page tells the customer so. Otherwise tip_link is null and tip_link_note says why. tip_request_sent_at is when the automatic tip text already asked this customer: if it is set, tell the owner before sending a second ask; if it is null, the automatic tip text may still ask later. custom_fields lists the job's custom field answers, the same answers the job page shows: one { key, label, type, value } per answered field (a dropdown also has value_label). Unanswered fields are left out; flyra_list_custom_fields lists every job field. Look here, not only in notes and description, for anything a business records in its own job fields. A role that hides pricing gets no currency answers.\n\nScope: `jobs:read`.","x-required-scope":"jobs:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"Job UUID or semantic id from flyra_search_jobs."}},"required":["job_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_create_job":{"post":{"operationId":"flyra_create_job","summary":"Create a Flyra job","tags":["Jobs"],"description":"Schedule a new job. Pass either an existing customer_id OR enough fields (first_name/last_name + email/phone) to upsert the customer. Optional scheduled_start + scheduled_end ISO timestamps (end must be after start); optional price in dollars. Honors the org's minimum_job_price_cents + minimum_job_length_minutes settings. Pass `recurrence` to book a recurring service (the app's \"Make this a recurring service\"): every visit is created up front as its own job, on the same weekday and time as scheduled_start, titled \"<service> (Weekly)\" etc. This is NOT a subscription — nothing is billed. As with a booking made in the app, the business's own booking confirmation (if it has one switched on) can go to the customer for the first visit; the other visits of a series are marked silent and never confirm. Pass send_confirmation: false to book it with no confirmation to the customer. The price line item is not taxed unless taxable is true. The answer's booking_confirmation is 'suppressed' when send_confirmation is false, otherwise 'first_visit' (the first, or only, visit can confirm). Leave scheduled_start and scheduled_end out to book it unscheduled, as the New Job form's Schedule later does. Pass anytime for a job with a day but no arrival time, or arrival_window_minutes for a timed job the customer is told to expect within a window. Pass line_items for several lines, as the New Job form's Line Items card books them, instead of service and price.\n\nScope: `jobs:write`.","x-required-scope":"jobs:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"description":"Existing customer UUID or semantic id. If omitted, pass customer details below.","type":"string"},"customer":{"description":"Customer details for upsert when customer_id is omitted. first_name/last_name AND email/mobile_phone required.","type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"mobile_phone":{"type":"string"}}},"service":{"description":"Free-text service label (e.g. \"Window Cleaning\"). Becomes the job title.","type":"string"},"scheduled_start":{"description":"ISO 8601.","type":"string"},"scheduled_end":{"description":"ISO 8601 — must be after scheduled_start.","type":"string"},"notes":{"type":"string"},"price":{"description":"Dollar amount; stored as cents. Per visit for a recurring series.","type":"number","minimum":0},"dispatched_employee_ids":{"description":"Employee UUIDs or semantic ids dispatched to the job (the crew). Applied to every visit of a recurring series.","type":"array","items":{"type":"string"}},"salesperson_ids":{"description":"Employee UUIDs or semantic ids credited with the sale.","type":"array","items":{"type":"string"}},"recurrence":{"description":"Make this a recurring service. Requires scheduled_start (the first visit).","type":"object","properties":{"frequency":{"description":"How often the visit repeats. every_2_weeks is bi-weekly. Give this or custom_interval.","type":"string","enum":["daily","every_other_day","weekdays","weekly","every_2_weeks","monthly","every_2_months","every_3_months","every_4_months","every_6_months","yearly"]},"custom_interval":{"type":"object","properties":{"every":{"type":"integer","minimum":1,"maximum":365,"description":"How many units between visits."},"unit":{"type":"string","enum":["days","weeks","months"],"description":"days up to 365, weeks up to 52, months up to 24."}},"required":["every","unit"],"description":"The app's Custom interval, for a cadence frequency does not list, e.g. every 3 weeks. Give this or frequency, not both."},"duration_years":{"description":"How far out to book, 1-10 years. Default 1, as in the app.","type":"integer","minimum":1,"maximum":10},"occurrences":{"description":"Exact number of visits instead of duration_years.","type":"integer","minimum":1,"maximum":400},"never_ends":{"description":"Ends: Never, as the job page's Make recurring box books it: 10 years of visits, at most 400 (the most one series holds, so a weekly series stops after 400 visits). Nothing books more visits after that. Not with duration_years or occurrences.","type":"boolean"}}},"taxable":{"description":"Tax the job's line item at the org's tax rates that apply automatically at the customer's address, as the app does when the tax switch is turned on. Refused, with no job booked, when no rate applies there. Default false.","type":"boolean"},"anytime":{"description":"The New Job form's Anytime box: the job has a day but no arrival time, and shows as Anytime. Needs scheduled_start, read only for its day in the org's timezone: a date (2026-10-27) or any ISO time on that day. scheduled_end, if sent, is the last day of a job over several days. Stored as the app stores it: 12 AM to 2 AM on its day (2 AM on its last day). Not with arrival_window_minutes.","type":"boolean"},"arrival_window_minutes":{"description":"The New Job form's \"Arrival window instead of an exact time\": the customer is told the crew arrives between scheduled_start and this many minutes after it (a 9:30 AM start with 150 reads 9:30 AM to 12 PM). The job's own start and end do not change. Whole minutes, 15 to 720; the app's picker offers 30, 60, 90, 120, 180 and 240. Needs scheduled_start; not with anytime. Left out, the job has an exact time. On a recurring series every visit gets it.","type":"integer","minimum":15,"maximum":720},"line_items":{"description":"Several line items, as the New Job form's Line Items card adds them, in this order. Not with service, price or taxable: the job's title becomes the first line's name plus \"+ N more\", as in the app, and its total is the sum of the lines (quantity times price), checked against the org's minimum job price. On a recurring series every visit gets every line.","minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"service_id":{"description":"A service id from flyra_list_services (the price book). The line takes that service's name, description, price and unit, as picking it on the New Job form does.","type":"string"},"title":{"description":"A line that is not in the price book: its name, e.g. \"Gutter Clean\". Send this or service_id, not both.","type":"string","minLength":1,"maxLength":200},"description":{"description":"Detail shown under the name. With service_id it replaces the service's description.","type":"string","maxLength":2000},"quantity":{"description":"Whole number, default 1.","type":"integer","minimum":1,"maximum":10000},"unit_price":{"description":"Price of one, in dollars. Needed with title. With service_id it replaces the price book price, as editing the line's price on the form does.","type":"number","minimum":0,"maximum":1000000},"taxable":{"description":"Tax this line at the org's tax rates that apply automatically at the customer's address. Refused, with no job booked, when no rate applies there. Default false.","type":"boolean"},"unit":{"description":"What quantity is counted in, as the Unit picker on a line saves it: \"sq ft\" or \"linear ft\" (\"sqm\" or \"linear m\" for a business that measures in metres), or the business's own word, up to 16 characters. Leave it out for a plain count (Qty); with service_id, left out takes the service's unit.","type":"string","minLength":1,"maxLength":16}}}},"checklist":{"description":"Checklist tasks, in this order, not done yet: one-off tasks as the New Job form's Checklist > Add Item adds them, and template tasks as ticking them there does. On a recurring series every visit gets them. A template task that attaches to every new job is added by Flyra on its own, so sending it adds nothing more, as on the form. An unknown template task, or one listed twice, books nothing. Attaching a picture to a one-off task is not done here.","minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"title":{"description":"A task of its own, e.g. \"Photograph the gutters\". Send this or template_item_id, not both.","type":"string","minLength":1,"maxLength":200},"description":{"description":"Optional detail shown under a task sent with title.","type":"string","maxLength":2000},"template_item_id":{"description":"A checklist template task (chktpl_... from flyra_list_checklist_groups), as ticking it in the New Job form's checklist templates does: the task takes the template's name, description, first picture and group.","type":"string"}}}},"send_confirmation":{"description":"The New Job form's \"Text <first name> a confirmation\" box. Left out or true, nothing changes: the job's customer can get the business's own booking confirmation for the first visit, if the business has one switched on (this tool sends nothing itself). false is the box unticked: every visit is marked silent as the form marks it, so Flyra sends the customer no booking confirmation when it is booked. Needs scheduled_start: the form turns the box off with Schedule later.","type":"boolean"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_job":{"post":{"operationId":"flyra_update_job","summary":"Update a Flyra job","tags":["Jobs"],"description":"Partial update — pass only the fields to change. Use flyra_cancel_job to set status=\"cancelled\" with audit context. A new scheduled_start / scheduled_end (or is_anytime) is saved the way the job page's reschedule saves it: the org's minimum job length is checked and reminders are re-planned. Moving a subscription plan visit can move its card charge, or refund a charge already taken; confirm with the user first. Moving an open job to a time still ahead can text and/or email the customer the business's reschedule message, on the channels the business has switched on, unless notify_customer is false. Flyra's built-in reschedule message is not sent for a time already past, or for a job that is completed or that this call completes. A job that had no time gets the built-in booking confirmation when it is first scheduled only if notify_customer is true; a business that runs its booking confirmation as an automation still sends it, whatever notify_customer says. scheduled_start: null unschedules the job. When the time moved, the answer's customer_messaged says whether a message was sent or handed to the business's automation. A job's first time is confirmed by the business's booking automation when it is on, so customer_messaged is left out unless this call sent the confirmation itself. A new time and a new total in one call are refused when the customer would be messaged: change the price first, then the time.\n\nScope: `jobs:write`.","x-required-scope":"jobs:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"Job UUID or semantic id."},"status":{"description":"Prefer flyra_transition_job_status for lifecycle changes — it fires billing/review/invoice side-effects. Set status here only for a plain field correction, e.g. back-filling past visits as completed WITHOUT sending an invoice or review request. \"cancelled\" is refused here: use flyra_cancel_job. Setting \"completed\" stamps the completion time (completed_at, or the job's scheduled end, or now).","type":"string","enum":["scheduled","on_the_way","arrival","in_progress","completed","cancelled","overdue"]},"completed_at":{"description":"ISO 8601 completion time, for a completed job. Used with status=\"completed\" to record when a past visit was actually done; reports and revenue read it.","anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"notes":{"anyOf":[{"type":"string"},{"type":"null"}]},"scheduled_start":{"description":"ISO 8601; pass null to unschedule the job (its end and date clear with it).","anyOf":[{"type":"string"},{"type":"null"}]},"scheduled_end":{"description":"ISO 8601, after scheduled_start. A scheduled job needs both.","anyOf":[{"type":"string"},{"type":"null"}]},"notify_customer":{"description":"With a new time: false saves it without telling the customer. Left out or true, the customer gets the business's reschedule message on the channels it has switched on, as the job page's reschedule opens with. A job scheduled for the first time gets the built-in booking confirmation only when this is true (a booking confirmation the business runs as an automation sends either way). The built-in message is never sent for a time already past or a completed job.","type":"boolean"},"is_anytime":{"description":"The job page's Anytime box: true makes it a job with a day but no arrival time (stored as 12 AM to 2 AM on scheduled_start's day in the org's timezone, or the job's current day; scheduled_end, if sent, is its last day) and clears any arrival window. false makes it a timed job again: send the new scheduled_start and scheduled_end with it. Saved as a reschedule, so notify_customer applies.","type":"boolean"},"scheduled_for":{"description":"Calendar date the job sits on (YYYY-MM-DD), independent of the start/end timestamps; null clears.","anyOf":[{"type":"string"},{"type":"null"}]},"arrival_window_minutes":{"description":"The job page's \"Arrival window instead of an exact time\": the customer is told the crew arrives between the job's start and this many minutes after it (a 9:30 AM start with 150 reads 9:30 AM to 12 PM). The job's start and end do not change. This alone sends the customer nothing; texts sent later that show the arrival window read the new one. Whole minutes, 15 to 720; the app's picker offers 30, 60, 90, 120, 180 and 240. null makes it an exact time again. Refused on an Anytime job and on a job with no start time.","anyOf":[{"type":"integer","minimum":15,"maximum":720},{"type":"null"}]},"price":{"description":"The job's price in dollars before the discount. On a job with no line items it is the total (null clears it). On a job with one line item of quantity 1 it sets that line item's price, and the total follows from it minus any discount; null is refused. On a job with several line items, or one with another quantity, it is refused: change each line's price with flyra_edit_job_line_items. Refused while the job has line items and an open invoice.","anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"discount":{"description":"Flat discount in dollars; replaces any discounts already on the job; null/0 clears. The job total becomes the line-item subtotal (or, with no line items, the price before the discount) minus this; sent with price, it comes off that price. Refused while the job has an open invoice: ask the user to change the discount on that invoice in Flyra.","anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"discount_percent":{"description":"A percent discount instead of discount (10 = 10% off the line-item subtotal, or with no line items the price before the discount); replaces any discounts already on the job. Send discount or discount_percent, not both. Refused while the job has an open invoice.","type":"number","exclusiveMinimum":0,"maximum":100},"lead_source":{"description":"Lead-source label, free text (e.g. \"D2D\", \"Ads\", \"Referral\", \"Online\"). Pass null to clear.","anyOf":[{"type":"string"},{"type":"null"}]},"payment_status":{"description":"Override the payment status. Does not move money — for record correction only.","type":"string","enum":["unpaid","partially_paid","paid"]},"salesperson_ids":{"description":"Employee UUIDs or semantic ids credited with the sale. Replaces the whole list; null/[] clears.","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"dispatched_employee_ids":{"description":"Employee UUIDs or semantic ids dispatched to the job. Replaces the whole list; null/[] clears.","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"add_line_items":{"description":"New line items to add to the job, as adding a line on the job page does. Send it on its own, with only job_id. Each line is added not taxed: to tax one, call flyra_set_job_line_item_taxable with its id from line_items in the answer. The job total becomes all its lines minus its discount, and that is what its next invoice or card charge bills; on a plan visit, the visit's card charge bills the added lines too. The job's title may change to its first line's name plus \"+ N more\", as it does in the app. Refused while the job has an invoice that is not void, once the job is paid or charged, and on a job whose price is not on a line item unless replace_job_price is true.","minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200,"description":"The line's name, e.g. \"House Wash\"."},"description":{"description":"Optional detail shown under the name.","type":"string"},"quantity":{"description":"Whole number, default 1.","type":"integer","minimum":1,"maximum":10000},"unit_price":{"type":"number","minimum":0,"maximum":1000000,"description":"Price of one, in dollars."},"unit":{"description":"What quantity is counted in, as the Unit picker on a line saves it: \"sq ft\" or \"linear ft\" (\"sqm\" or \"linear m\" for a business that measures in metres), or the business's own word, up to 16 characters. Leave it out for a plain count (Qty).","type":"string","minLength":1,"maxLength":16}},"required":["title","unit_price"]}},"replace_job_price":{"description":"With add_line_items, on a job whose price is not on its line items (an imported $120 job with no lines): the job total becomes the lines minus the discount, replacing that price, as adding the lines on the job page does. Confirm the new total with the user first. The answer gives the old price as replaced_price_cents.","type":"boolean","const":true},"address_id":{"description":"Which of the job's customer's properties this job is done at (a property id from flyra_list_customer_properties). Moves only this job: the customer's other jobs and plans stay where they are. Only for a business with multiple properties per customer turned on. Refused on a completed or cancelled job, which keeps the property it was done at. Sends the customer nothing.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["job_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_job_line_item_taxable":{"post":{"operationId":"flyra_set_job_line_item_taxable","summary":"Turn tax on or off for a Flyra job's line items","tags":["Jobs"],"description":"The job page's tax switch on a line item. taxable=true charges the org's tax rates that apply automatically at the job's address; an item that is already taxed keeps the rates it has. taxable=false removes tax from the item. This changes what the customer is charged, but not the job's amount_cents: tax is added on the invoice and the card charge, and tax_cents in the answer is what the line items now carry. Refused when no tax rate applies at the job's address (ask the user to pick the rate on the job in Flyra), and while the job has an open invoice (ask the user to change tax on that invoice).\n\nScope: `jobs:write`.","x-required-scope":"jobs:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"Job UUID or semantic id."},"line_item_id":{"type":"string","description":"A line item id from flyra_get_job, or \"all\" for every line item on the job."},"taxable":{"type":"boolean","description":"true to charge tax on the item, false to stop charging it."}},"required":["job_id","line_item_id","taxable"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_edit_job_line_items":{"post":{"operationId":"flyra_edit_job_line_items","summary":"Edit or remove a Flyra job's line items","tags":["Jobs"],"description":"The job page's Service card: change the name, description, quantity or price of lines already on a job, or remove lines from it, as saving the card in the app does. Line ids come from line_items in flyra_get_job. Add new lines with flyra_update_job add_line_items; turn tax on or off with flyra_set_job_line_item_taxable. A changed line keeps its tax setting and rates. The job total becomes all its remaining lines minus its discount, and that is what its next invoice or card charge bills. The job's title may change to its first line's name plus \"+ N more\", as it does in the app. Nobody is messaged. Refused while the job has an invoice that is not void, once the job is paid or charged, on a job whose total does not match its lines, and when the job's discount would come off the new total differently on its invoice. Only a job the caller can open in the app.\n\nScope: `jobs:write`. Destructive: it deletes or cancels.","x-required-scope":"jobs:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"Job UUID or semantic id."},"update_line_items":{"description":"Lines to change. Send only the fields that change.","minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"line_item_id":{"type":"string","description":"The line's id, from line_items in flyra_get_job."},"title":{"description":"New name for the line.","type":"string","minLength":1,"maxLength":200},"description":{"description":"New detail shown under the name; \"\" clears it.","type":"string","maxLength":2000},"quantity":{"description":"New quantity, a whole number.","type":"integer","minimum":1,"maximum":10000},"unit_price":{"description":"New price of one, in dollars.","type":"number","minimum":0,"maximum":1000000}},"required":["line_item_id"]}},"remove_line_item_ids":{"description":"Ids of lines to take off the job.","minItems":1,"maxItems":50,"type":"array","items":{"type":"string"}},"confirm":{"type":"boolean","const":true,"description":"Must be true: this changes or removes the job's lines and so what the customer is billed."}},"required":["job_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_cancel_job":{"post":{"operationId":"flyra_cancel_job","summary":"Cancel a Flyra job","tags":["Jobs"],"description":"Cancel a job the way the app does: it goes through the same transition as flyra_transition_job_status with status=\"cancelled\", which records when it was cancelled and by whom in the job history, and starts the business's automations on a cancelled job, as any cancel does. A pending cancellation request on the job closes with it. The business's built-in cancellation message (text and/or email) goes to the customer only with notify_customer: true, as the cancel window's Notify customer switch sends it; a cancellation message the business runs as an automation still goes out. pending_reschedule: true flags the job Pending reschedule, as the cancel window's tick does: the customer still wants the visit and it waits in the schedule's Pending reschedule list until it is rebooked or restored. Line items, payments, and history are preserved. To undo it, use flyra_restore_job (the Restore button on the job page). Confirm with the user first.\n\nScope: `jobs:write`. Destructive: it deletes or cancels.","x-required-scope":"jobs:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"Job UUID or semantic id."},"reason":{"description":"Optional note appended to the job notes for audit.","type":"string"},"notify_customer":{"description":"true also sends the business's built-in cancellation message, if it has one switched on. Left out or false, it is not sent; the business's own automations on a cancelled job still run.","type":"boolean"},"pending_reschedule":{"description":"true flags the cancelled job Pending reschedule (the cancel window's tick), so it shows in the schedule's Pending reschedule list. Sends nothing. Left out, the flag is not set.","type":"boolean"},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed cancelling this job."}},"required":["job_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_restore_job":{"post":{"operationId":"flyra_restore_job","summary":"Restore a cancelled job","tags":["Jobs"],"description":"Put a CANCELLED job back on the schedule, like the Restore button on the job page. It becomes Scheduled at the same date and time; the cancel reason, the pending-reschedule flag and the on the way / arrived / started / completed times are cleared, the job history records the restore, and a customer pin on the map that turned cancelled with it shows as a sale again. A pending subscription charge left on another date moves onto the job's date, as Restore does, and is collected at once if that date is today or earlier; the customer then gets the business's automatic payment receipt, if it sends one. Otherwise the restore itself sends nothing to the customer or the team, though the business's own automations on job.restored run. Only for a cancelled job: a deleted job is gone for good and cannot be restored. To move it to a new time after restoring, use flyra_update_job.\n\nScope: `jobs:write`.","x-required-scope":"jobs:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"Job UUID or semantic id (job_<uuid>)."}},"required":["job_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_transition_job_status":{"post":{"operationId":"flyra_transition_job_status","summary":"Transition a Flyra job to a new status","tags":["Jobs"],"description":"Move a job along its lifecycle (scheduled → on_the_way → arrival → in_progress → completed, or cancelled from any state) the SAME way the app does. Unlike flyra_update_job, this routes through the validated transition_job RPC AND fires the completion/cancellation side-effects: on-completion subscription billing, the auto-review request, the auto-invoice send, and the cancellation notification. Use this — not flyra_update_job — whenever you change a job's status.\n\nScope: `jobs:write`.","x-required-scope":"jobs:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"Job UUID or semantic id."},"status":{"type":"string","enum":["scheduled","on_the_way","arrival","in_progress","completed","cancelled"],"description":"Target status. The RPC enforces legal transitions and will reject illegal jumps."},"request_id":{"description":"Optional idempotency key (UUID). Re-sending the same request_id is a no-op at the DB layer.","type":"string"}},"required":["job_id","status"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_schedule_callback":{"post":{"operationId":"flyra_schedule_callback","summary":"Schedule a callback visit","tags":["Jobs"],"description":"Job > Schedule Callback: create a callback job linked to the original job (callback_for_job_id), through the same code POST /api/jobs/[id]/callback runs for the web and iPhone apps. It copies the customer, address and salespeople, keeps the original's techs unless dispatched_employee_ids is passed, copies the line items at $0 with their line photos, and puts the reason under \"Callback for previous job …\" in the description. Like the screen, it schedules the company's usual job reminders for the callback's customer; it does not send the \"callback scheduled\" message (the screen asks for that separately). A role that may not dispatch cannot pick techs. Needs a signed-in person who can open the original job; an organization API key is refused. confirm must be true.\n\nScope: `jobs:write`.","x-required-scope":"jobs:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"The original job: UUID or semantic id."},"start_time":{"type":"string","description":"Callback start, ISO 8601."},"end_time":{"type":"string","description":"Callback end, ISO 8601."},"scheduled_for":{"description":"The visit day, YYYY-MM-DD, as the screen sends it.","type":"string"},"dispatched_employee_ids":{"description":"Techs for the callback (employee UUIDs or semantic ids). Leave out to keep the original job's techs.","type":"array","items":{"type":"string"}},"reason":{"description":"Why the callback is needed; added to the description.","type":"string","maxLength":5000},"confirm":{"type":"boolean","const":true,"description":"Must be true: the customer may get the company's usual job reminders for this visit."}},"required":["job_id","start_time","end_time","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_make_job_recurring":{"post":{"operationId":"flyra_make_job_recurring","summary":"Make an existing job recurring","tags":["Jobs"],"description":"Job > Make this job recurring, as the job page does it: books the future visits up front as their own jobs through the same code POST /api/jobs/create-with-reminders runs (the same visit dates, title \"<title> (Monthly)\" etc., line items, notes, salespeople, org minimum price and length checks), then renames this job to the series title. never_ends books 10 years, cut at 400 visits, as the modal's Never ends does. Like the page, no visit sends the customer a booking confirmation and no \"Job booked\" push goes out; each visit gets the company's usual job reminders (texts or emails to the customer before the visit, per the company's reminder settings), and Flyra's welcome email can go to the customer once if they never got one and the company has it on. A role that may not dispatch books visits with nobody on them. Not for a cancelled job, a plan visit, a job with no scheduled time, a job already in a series, or one with later visits already booked (the page hides the button). Call with dry_run:true first: it saves nothing and answers visits_planned, the first and last visit, reminders_planned (the reminder entries the visits will queue: the company's reminder schedules plus its \"before a job\" automations, counted the way they are queued) and welcome_email. Then call again without dry_run, passing expected_visits equal to visits_planned; if it changed, nothing is booked. All visits are saved in one go, as New job saves a repeating job: if the save is refused nothing is booked. If renaming the job then fails, the visits are deleted again; if that delete also fails, the reply is partial_booking with the job ids still on the schedule. Needs a signed-in person who can open the job; an organization API key is refused. confirm must be true.\n\nScope: `jobs:write`. Destructive: it deletes or cancels.","x-required-scope":"jobs:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"The job to repeat: UUID or semantic id."},"frequency":{"description":"How often it repeats, as the modal's Frequency. every_2_weeks is bi-weekly. Give this or custom_interval.","type":"string","enum":["daily","every_other_day","weekdays","weekly","every_2_weeks","monthly","every_2_months","every_3_months","every_4_months","every_6_months","yearly"]},"custom_interval":{"type":"object","properties":{"every":{"type":"integer","minimum":1,"maximum":365,"description":"How many units between visits."},"unit":{"type":"string","enum":["days","weeks","months"],"description":"days up to 365, weeks up to 52, months up to 24."}},"required":["every","unit"],"description":"The app's Custom interval, for a cadence frequency does not list, e.g. every 3 weeks. Give this or frequency, not both."},"duration_years":{"description":"How far out to book, 1-10 years. Default 1, as in the modal. Not with never_ends.","type":"integer","minimum":1,"maximum":10},"never_ends":{"description":"The modal's Never ends: books 10 years of visits, cut at 400.","type":"boolean"},"date_mode":{"description":"Monthly and slower cadences only, as the modal offers it: day_of_month (default, the job's own day of the month unless day_of_month is given) or day_of_week (ordinal + weekday).","type":"string","enum":["day_of_month","day_of_week"]},"day_of_month":{"description":"With date_mode day_of_month: the day each visit lands on (cut to the month's last day).","type":"integer","minimum":1,"maximum":31},"ordinal":{"description":"With date_mode day_of_week: 1st to 4th.","type":"integer","minimum":1,"maximum":4},"weekday":{"description":"With date_mode day_of_week: 0 Sunday to 6 Saturday.","type":"integer","minimum":0,"maximum":6},"dry_run":{"description":"true answers with visits_planned, reminders_planned and welcome_email and books nothing.","type":"boolean"},"expected_visits":{"description":"Required without dry_run: the visits_planned the dry run answered.","type":"integer","minimum":0,"maximum":9007199254740991},"confirm":{"type":"boolean","const":true,"description":"Must be true: this books every visit up front and the customer gets the company's usual reminders before each one."}},"required":["job_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_job_assign_employee":{"post":{"operationId":"flyra_job_assign_employee","summary":"Assign an employee to a Flyra job","tags":["Jobs"],"description":"Add an employee to a job as either dispatcher (does the work) or salesperson (gets sale credit). Idempotent — assigning an already-assigned employee returns success without duplicating.\n\nScope: `jobs:write`.","x-required-scope":"jobs:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"Job UUID or semantic id."},"employee_id":{"type":"string","description":"Employee UUID or semantic id from flyra_list_employees."},"role":{"type":"string","enum":["dispatcher","salesperson"],"description":"\"dispatcher\" puts the employee on the work crew. \"salesperson\" credits them with the sale."}},"required":["job_id","employee_id","role"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_job_unassign_employee":{"post":{"operationId":"flyra_job_unassign_employee","summary":"Remove an employee from a Flyra job","tags":["Jobs"],"description":"Remove an employee from a job's dispatcher or salesperson list. Idempotent — unassigning someone not on the list returns success without error.\n\nScope: `jobs:write`.","x-required-scope":"jobs:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"Job UUID or semantic id."},"employee_id":{"type":"string","description":"Employee UUID or semantic id."},"role":{"type":"string","enum":["dispatcher","salesperson"],"description":"Which list to remove from."}},"required":["job_id","employee_id","role"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_log_job_complaint":{"post":{"operationId":"flyra_log_job_complaint","summary":"Log a customer complaint on a job","tags":["Jobs"],"description":"The Customer complaint form on a job (Notes & files): saves what the customer said, the day it came in and the technicians it names, as an open complaint on the job. Admins, Owners and roles that can view Reports may log one on any job; anyone else only on a job they are dispatched on, and only when the company lets technicians take part. Refused while the company has customer complaints switched off. The named technicians are the ones it counts against wherever Flyra tallies complaints (technician progression, the weekly breakdown). Nobody is messaged. Needs a signed-in Flyra user, not an organization API key.\n\nScope: `jobs:write`.","x-required-scope":"jobs:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"Job UUID or semantic id."},"body":{"type":"string","description":"What the customer said, up to 2000 characters."},"received_on":{"type":"string","description":"YYYY-MM-DD, the day the complaint came in (the form starts at today in the company's timezone)."},"employee_ids":{"type":"array","items":{"type":"string"},"description":"The technicians the complaint names: employee UUIDs or semantic ids from flyra_get_job or flyra_list_employees. The form starts with the job's crew. May be empty."}},"required":["job_id","body","received_on","employee_ids"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_job_line_item_upsell":{"post":{"operationId":"flyra_set_job_line_item_upsell","summary":"Mark a Flyra job line item as an upsell","tags":["Jobs"],"description":"The Upsell switch on a line item on the job page (Job > Service), with its salesperson picker. upsell=true marks the line as an upsell; salesperson_ids, when sent, replaces who is credited with it (active employees only, as the picker offers). upsell=false turns the switch off and leaves who was credited as it is, as the page does. Payroll pays its upsell rate, and the leaderboard counts the line, only for a line with the switch on and someone credited. No price changes. Anyone who can open the job may call it, as on the job page. Refused when the job's total or discount is not what its lines give, because saving a line makes Flyra recompute them (ask the user to change it on the job in Flyra). The job's title may change to its first line's name plus \"+ N more\", as it does in the app when a line is saved.\n\nScope: `jobs:write`.","x-required-scope":"jobs:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"Job UUID or semantic id."},"line_item_id":{"type":"string","description":"A line item id from line_items on flyra_get_job."},"upsell":{"type":"boolean","description":"true to turn the Upsell switch on, false to turn it off."},"salesperson_ids":{"description":"Employee UUIDs or semantic ids from flyra_list_employees credited with the upsell. Replaces the list; [] clears it. Only with upsell=true. Omit to keep who is credited.","maxItems":20,"type":"array","items":{"type":"string"}}},"required":["job_id","line_item_id","upsell"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_appointments":{"post":{"operationId":"flyra_list_appointments","summary":"List appointments (quote visits)","tags":["Jobs"],"description":"On-site quote visits. With `start` and `end`: the visits on the Schedule in that window (any visit that overlaps it), cancelled ones left out, at most 62 days; a signed-in employee who does not see every job on the Schedule gets only the visits assigned to them. With `customer_id` or `lead_id` instead: every visit on that customer record or lead card, newest first, cancelled included, for a customer or lead the caller can open. Each visit has its id, customer_id or lead_id, the assigned employee, start and end, status (booked, completed, cancelled, no_show) and who and where it is for. Needs a signed-in Flyra user, not an organization API key. Read only.\n\nScope: `jobs:read`.","x-required-scope":"jobs:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"description":"Window start, ISO timestamp. Use with end.","type":"string"},"end":{"description":"Window end, ISO timestamp. Use with start.","type":"string"},"customer_id":{"description":"Instead of a window: the visits on this customer.","type":"string"},"lead_id":{"description":"Instead of a window: the visits on this lead.","type":"string"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_book_appointment":{"post":{"operationId":"flyra_book_appointment","summary":"Book an appointment (quote visit)","tags":["Jobs"],"description":"Book appointment, as + Create > Appointment and a lead's Book Appointment do it: an on-site visit for exactly one customer or one lead, from start_time to end_time, shown on the Schedule. Only for a company that has appointments switched on. Who may book: Admins, Owners, and roles that can create estimates. With no employee_id the visit is assigned to the caller's own employee record. With no notes it starts from the company's default appointment notes. A lead visit copies the lead's name, phone, email and address onto it. Booking runs the company's automations for a booked appointment (the appointment confirmation among them) for that one customer or lead, and lays down the reminders before the visit, which run the company's appointment reminder automations for them. notify_customer: false skips only the built-in Appointment Confirmation for this booking; the company's other booked-appointment automations and the reminders still run. Needs a signed-in Flyra user.\n\nScope: `jobs:write`.","x-required-scope":"jobs:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"description":"The customer the visit is for. Pass this or lead_id, not both.","type":"string"},"lead_id":{"description":"The lead the visit is for. Pass this or customer_id, not both.","type":"string"},"address_id":{"description":"Customer visits only: which of the customer's properties (a property id, such as a job's address_id). Leave out for the customer's default property.","type":"string"},"employee_id":{"description":"Who goes (an employee id from flyra_list_employees). Leave out to assign it to yourself.","type":"string"},"notes":{"description":"Notes on the visit. Leave out for the company's default appointment notes; \"\" for none.","type":"string"},"start_time":{"type":"string","description":"ISO timestamp the visit starts."},"end_time":{"type":"string","description":"ISO timestamp the visit ends, after start_time."},"notify_customer":{"description":"Leave out or true to send the company's Appointment Confirmation as usual. false skips only that confirmation for this booking; other automations on a booked appointment and the reminders still run.","type":"boolean"},"confirm":{"type":"boolean","const":true,"description":"Must be true: booking can message the customer or lead (confirmation and reminders)."}},"required":["start_time","end_time","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_reschedule_appointment":{"post":{"operationId":"flyra_reschedule_appointment","summary":"Reschedule an appointment","tags":["Jobs"],"description":"Move a visit to a new start and end, as dragging it on the Schedule or editing its time does. A visit that is still booked has its reminders re-planned from the new time (they run the company's appointment reminder automations for its customer or lead). Who may: Admins, Owners, and roles that can create estimates. Only a visit the caller sees on their Schedule or on a customer or lead they can open. Get the id from flyra_list_appointments. Needs a signed-in Flyra user.\n\nScope: `jobs:write`.","x-required-scope":"jobs:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"appointment_id":{"type":"string","description":"The visit id, from flyra_list_appointments."},"start_time":{"type":"string","description":"New ISO start."},"end_time":{"type":"string","description":"New ISO end, after start_time."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the reminders to the customer or lead move with it."}},"required":["appointment_id","start_time","end_time","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_cancel_appointment":{"post":{"operationId":"flyra_cancel_appointment","summary":"Cancel an appointment","tags":["Jobs"],"description":"Set a visit's Outcome to Cancelled, as on the visit in the app: it leaves the Schedule, the record stays on the customer or lead, and its reminders are withdrawn. Nobody is messaged. Who may: Admins, Owners, and roles that can create estimates. Only a visit the caller sees on their Schedule or on a customer or lead they can open. Needs a signed-in Flyra user.\n\nScope: `jobs:write`. Destructive: it deletes or cancels.","x-required-scope":"jobs:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"appointment_id":{"type":"string","description":"The visit id, from flyra_list_appointments."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the visit is taken off the Schedule."}},"required":["appointment_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_voice_memos":{"post":{"operationId":"flyra_list_voice_memos","summary":"List voice memos","tags":["Bulk"],"description":"List the voice memos saved on a job, lead, customer or subscription (newest first), each with its length in seconds and a short-lived (1 hour) URL to play or download the audio. URLs expire after an hour; call again to refresh. These are audio notes a teammate recorded on the record, not voicemails callers left (missed calls in flyra_list_calls include those). Voice memos can only be listed and played here: recording a new one is not available through the connector.\n\nScope: depends on `entity` (for example `leads:write`).","x-required-scope":"varies","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"entity_type":{"type":"string","enum":["job","lead","customer","subscription"],"description":"The kind of record the memos are on."},"entity_id":{"type":"string","description":"The record's id, from the matching search or get tool."},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":50},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["entity_type","entity_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_job_photos":{"post":{"operationId":"flyra_list_job_photos","summary":"List a job’s photos","tags":["Jobs"],"description":"List the photos captured on a job, each with a short-lived (1 hour) download URL for the image bytes. Use these URLs to fetch the images — e.g. to post them to social media or attach them elsewhere. URLs expire after an hour; call again to refresh.\n\nScope: `jobs:read`.","x-required-scope":"jobs:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"The job whose photos to return."},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":50},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["job_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_attach_estimate_photo":{"post":{"operationId":"flyra_attach_estimate_photo","summary":"Attach a photo to an estimate","tags":["Estimates"],"description":"Attach a picture (a mockup, a photo of the property) to an estimate. It is listed with the estimate's attachments, so the customer sees it on their estimate page, like a file added in the app. Give the picture as image_url (a public https link that does not redirect) or as image_base64 (the file's bytes). JPG, PNG, WebP, GIF or HEIC, up to 10 MB. Returns a 1 hour download link to check it. With line_item_id, the picture goes on that one line of the estimate instead, as the camera on a line item row does, and the customer sees it beside that line. Either way, only while the estimate is a draft or sent, as on the estimate page.\n\nScope: `estimates:write`.","x-required-scope":"estimates:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"estimate_id":{"type":"string","description":"Estimate UUID or semantic id (est_<uuid>)."},"image_url":{"description":"Public https link to the picture. Pass this or image_base64.","type":"string"},"image_base64":{"description":"The picture's bytes, base64 encoded. Pass this or image_url.","type":"string","maxLength":14000000},"file_name":{"description":"Name the customer sees, e.g. \"Roofline mockup\". Defaults to \"Photo\". Not used with line_item_id (a line's picture is a photo, not an attachment).","type":"string","maxLength":120},"line_item_id":{"description":"Optional: the id of one line item on this estimate (from flyra_get_estimate). Leave it out to attach to the estimate itself.","type":"string","minLength":1,"maxLength":100}},"required":["estimate_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_create_estimate_mockup":{"post":{"operationId":"flyra_create_estimate_mockup","summary":"Make a lights mockup on an estimate","tags":["Estimates"],"description":"Make a lights mockup from a photo of the house and put it on an estimate, as the Lights mockup card on the estimate page does: the photo goes to the image model, and the picture it draws becomes the estimate's mockup (and is copied into its attachments when the mockup is included in the estimate). Only for a business with mockups switched on. Each call is one paid render and counts against the business's monthly mockup allowance; it takes about half a minute. Give the photo as image_url (a public https link that does not redirect) or as image_base64 (the file's bytes): JPG, PNG, WebP or HEIC, up to 10 MB. Needs a signed-in Flyra user (not an organization API key) who can open the estimate. Returns the mockup's link.\n\nScope: `estimates:write`.","x-required-scope":"estimates:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"estimate_id":{"type":"string","description":"Estimate UUID or semantic id (est_<uuid>)."},"image_url":{"description":"Public https link to the house photo. Pass this or image_base64.","type":"string"},"image_base64":{"description":"The house photo's bytes, base64 encoded. Pass this or image_url.","type":"string","maxLength":14000000},"look":{"description":"The look to draw (one of the looks switched on in the business's mockup settings). Defaults to the business's default look.","type":"string","maxLength":40},"confirm":{"type":"boolean","const":true,"description":"Pass true once the user has agreed: each mockup is a paid render from the monthly allowance."}},"required":["estimate_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_attach_customer_photo":{"post":{"operationId":"flyra_attach_customer_photo","summary":"Attach a photo to a customer","tags":["Customers"],"description":"Add a picture (a product photo, a photo of the property) to a customer. It shows on the customer's Attachments tab in Flyra, like a photo added there in the app. It is not sent to the customer. Give the picture as image_url (a public https link that does not redirect) or as image_base64 (the file's bytes). JPG, PNG, WebP, GIF or HEIC, up to 10 MB. Returns a 1 hour download link to check it.\n\nScope: `customers:write`.","x-required-scope":"customers:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string","description":"Customer UUID or semantic id (cus_<uuid>)."},"image_url":{"description":"Public https link to the picture. Pass this or image_base64.","type":"string"},"image_base64":{"description":"The picture's bytes, base64 encoded. Pass this or image_url.","type":"string","maxLength":14000000}},"required":["customer_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_attach_job_photo":{"post":{"operationId":"flyra_attach_job_photo","summary":"Add a photo to a job","tags":["Jobs"],"description":"Add a picture (a before or after shot, a photo of the property) to a job. It shows with the job's photos in Flyra, like a photo added with Add photos on the job page. It is not texted or emailed to anyone, and it does not count toward the job's quality check. Give the picture as image_url (a public https link that does not redirect) or as image_base64 (the file's bytes). JPG, PNG, WebP, GIF or HEIC, up to 10 MB. Returns a 1 hour download link to check it. With line_item_id, the picture goes on that one line of the job instead, as the camera on a line item row does.\n\nScope: `jobs:write`.","x-required-scope":"jobs:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"Job UUID or semantic id (job_<uuid>)."},"image_url":{"description":"Public https link to the picture. Pass this or image_base64.","type":"string"},"image_base64":{"description":"The picture's bytes, base64 encoded. Pass this or image_url.","type":"string","maxLength":14000000},"line_item_id":{"description":"Optional: the id of one line item on this job (from flyra_get_job). Leave it out to add the photo to the job itself.","type":"string","minLength":1,"maxLength":100}},"required":["job_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_attach_file":{"post":{"operationId":"flyra_attach_file","summary":"Attach a file to a record","tags":["Bulk"],"description":"Add a document (PDF, Word, Excel, any file) or a picture to a customer, lead, invoice, job or estimate, as Add attachments on that record's page does (the customer's Attachments tab, the lead page, the invoice form, the job page's Attachments card, the estimate page). It is not sent to anyone. On an estimate every file, pictures included, is listed as an attachment, which the customer sees on their estimate page; an estimate that is no longer a draft or sent is read only and is refused. Elsewhere a picture joins the record's photos and any other file is listed as a document. Only for a record the caller can open in Flyra; an organization API key with no person behind it cannot. Give the file as file_url (a public https link that does not redirect) or as file_base64 (the file's bytes), and its file_name with the extension. Pictures (JPG, PNG, WebP, GIF or HEIC) up to 10 MB, other files up to 4 MB. Returns a 1 hour download link to check it. A video (MP4 or QuickTime, up to 10 MB here and up to 2 minutes) is added the way Add attachments uploads one; it needs duration_seconds, its length, which is taken as given as the page takes the browser's reading, and it is stored without a poster picture. With line_item_id, a picture goes on that one line of a job, invoice or estimate instead, as the camera on a line item row does; only a picture, only a line on that record, and on an invoice only while it is a draft (the invoice form is read only otherwise). A subscription (plan) takes only this: a picture on one line of its Plan card, as the camera on that line on the subscription page does; line_item_id is required there, the plan's customer must be one the caller can open, and a cancelled plan is refused (its Plan card is read only). As on the page, the picture is then also copied onto that line on the plan's upcoming scheduled visits.\n\nScope: depends on `entity` (for example `leads:write`).","x-required-scope":"varies","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"entity_type":{"type":"string","enum":["customer","lead","invoice","job","estimate","subscription"],"description":"Which kind of record the file goes on. subscription (a plan) needs line_item_id."},"entity_id":{"type":"string","description":"The record's UUID or semantic id (e.g. cus_<uuid>, job_<uuid>)."},"file_url":{"description":"Public https link to the file. Pass this or file_base64.","type":"string"},"file_base64":{"description":"The file's bytes, base64 encoded. Pass this or file_url.","type":"string","maxLength":14000000},"file_name":{"type":"string","minLength":1,"maxLength":200,"description":"The file's name with its extension, e.g. \"Scope of work.pdf\". A document downloads under this name."},"content_type":{"description":"The file type, e.g. application/pdf. Only used with file_base64; a link's own type is used otherwise.","type":"string","pattern":"^[\\w.+-]+\\/[\\w.+-]+$"},"duration_seconds":{"description":"A video's length in seconds (up to 120). Needed for a video, ignored otherwise.","type":"number"},"line_item_id":{"description":"Optional: the id of one line item on that job, invoice or estimate (from flyra_get_job, flyra_get_invoice or flyra_get_estimate), or on that subscription (its items in flyra_list_subscriptions; required for a subscription). The picture goes on that line; on an estimate the customer sees it on their estimate page right away. Leave it out to attach to the record itself.","type":"string","minLength":1,"maxLength":100}},"required":["entity_type","entity_id","file_name"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_customer_contacts":{"post":{"operationId":"flyra_list_customer_contacts","summary":"List a customer's contacts","tags":["Customers"],"description":"The people on a customer (a household or a business has several), as the Contacts card on the customer page lists them: name, phone, email and which one is primary, primary first. The primary's phone and email are the customer's own. Removed people are not listed. Only for a customer the caller can open in Flyra; an organization API key with no person behind it cannot. Read only.\n\nScope: `customers:read`.","x-required-scope":"customers:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string","description":"Customer UUID or semantic id (cus_<uuid>)."}},"required":["customer_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_add_customer_contact":{"post":{"operationId":"flyra_add_customer_contact","summary":"Add a contact to a customer","tags":["Customers"],"description":"Add a person to a customer, as Add on the customer page's Contacts card does. Needs a phone or an email. is_primary true makes them the primary contact: their phone and email become the customer's, and the old primary stays on as a contact. Only someone who may edit this customer in Flyra (customer management permission, and for a rep, a customer of theirs). Nothing is sent to anyone.\n\nScope: `customers:write`.","x-required-scope":"customers:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string","description":"Customer UUID or semantic id (cus_<uuid>)."},"first_name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"last_name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"phone":{"description":"Stored in E.164 for the business's country; null clears it.","anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"email":{"description":"null clears it.","anyOf":[{"type":"string","maxLength":320},{"type":"null"}]},"is_primary":{"description":"true makes this person the primary contact.","type":"boolean"}},"required":["customer_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_customer_contact":{"post":{"operationId":"flyra_update_customer_contact","summary":"Edit a customer's contact","tags":["Customers"],"description":"Change a person on a customer, as editing them on the customer page's Contacts card does; send only what changes. is_primary true is Make primary: their phone and email become the customer's. A primary is replaced by making someone else primary. Everyone other than the primary needs a phone or an email. Only someone who may edit this customer in Flyra (customer management permission, and for a rep, a customer of theirs). Nothing is sent to anyone.\n\nScope: `customers:write`.","x-required-scope":"customers:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string","description":"Customer UUID or semantic id (cus_<uuid>)."},"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The contact id from flyra_list_customer_contacts."},"first_name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"last_name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"phone":{"description":"Stored in E.164 for the business's country; null clears it.","anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"email":{"description":"null clears it.","anyOf":[{"type":"string","maxLength":320},{"type":"null"}]},"is_primary":{"description":"true makes this person the primary contact.","type":"boolean","const":true}},"required":["customer_id","contact_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_remove_customer_contact":{"post":{"operationId":"flyra_remove_customer_contact","summary":"Remove a customer's contact","tags":["Customers"],"description":"Remove a person from a customer, as Remove on the customer page's Contacts card does. It is an archive, not a delete: the person drops off the card, and anything that points at them keeps working. Removing the primary makes the oldest remaining person primary; a customer's last contact cannot be removed. Only someone who may edit this customer in Flyra (customer management permission, and for a rep, a customer of theirs). Nothing is sent to anyone. Pass confirm: true.\n\nScope: `customers:write`. Destructive: it deletes or cancels.","x-required-scope":"customers:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string","description":"Customer UUID or semantic id (cus_<uuid>)."},"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The contact id from flyra_list_customer_contacts."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the person is taken off the customer."}},"required":["customer_id","contact_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_customer_properties":{"post":{"operationId":"flyra_list_customer_properties","summary":"List a customer's properties","tags":["Customers"],"description":"The service properties (locations) on a customer, as the Service Locations card on the customer page lists them: address, label, map point and which one is the default, default first. Only for a business with multiple properties per customer turned on. Only for a customer the caller can open in Flyra; an organization API key with no person behind it cannot. Read only.\n\nScope: `customers:read`.","x-required-scope":"customers:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string","description":"Customer UUID or semantic id (cus_<uuid>)."}},"required":["customer_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_add_customer_property":{"post":{"operationId":"flyra_add_customer_property","summary":"Add a property to a customer","tags":["Customers"],"description":"Add a service property to a customer, as Add on the customer page's Service Locations card does. Needs at least a street address or a city; Flyra looks up its map point after the save. is_default true makes it the default: the property a new job or subscription gets when none is picked. Only for a business with multiple properties per customer turned on, and only someone who may edit this customer in Flyra (customer management permission, and for a rep, a customer of theirs). Nothing is sent to anyone.\n\nScope: `customers:write`.","x-required-scope":"customers:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string","description":"Customer UUID or semantic id (cus_<uuid>)."},"address":{"description":"Street address.","anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"unit":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"city":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"state":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"zip":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}]},"label":{"description":"A name for the property, e.g. \"Lake house\".","anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"is_default":{"description":"true makes this the customer's default property.","type":"boolean","const":true}},"required":["customer_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_customer_property":{"post":{"operationId":"flyra_update_customer_property","summary":"Edit a customer's property","tags":["Customers"],"description":"Change a customer's service property, as Edit property on the customer page's Service Locations card does; send only what changes. A changed address gets a new map point. Send latitude and longitude together (for example from the county parcel record) to set the map point exactly: Flyra saves that point and does not look the address up (send the point in its own call when you also change the address to a new one). is_default true is Make default. Only for a business with multiple properties per customer turned on, and only someone who may edit this customer in Flyra (customer management permission, and for a rep, a customer of theirs). Nothing is sent to anyone.\n\nScope: `customers:write`.","x-required-scope":"customers:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string","description":"Customer UUID or semantic id (cus_<uuid>)."},"property_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The property id from flyra_list_customer_properties."},"address":{"description":"Street address.","anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"unit":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"city":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"state":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"zip":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}]},"label":{"description":"A name for the property, e.g. \"Lake house\".","anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"latitude":{"description":"The exact map point's latitude in decimal degrees. Send with longitude.","type":"number","minimum":-90,"maximum":90},"longitude":{"description":"The exact map point's longitude in decimal degrees. Send with latitude.","type":"number","minimum":-180,"maximum":180},"is_default":{"description":"true makes this the customer's default property.","type":"boolean","const":true}},"required":["customer_id","property_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_remove_customer_property":{"post":{"operationId":"flyra_remove_customer_property","summary":"Remove a customer's property","tags":["Customers"],"description":"Delete a service property from a customer, as Remove property on the customer page's Service Locations card does. Past jobs at it fall back to the customer's default address; invoices and agreements keep the address they were made with. Refused for the customer's last property, and for a property an active subscription is scheduled at (move or cancel that subscription first). Only for a business with multiple properties per customer turned on, and only someone who may edit this customer in Flyra (customer management permission, and for a rep, a customer of theirs). Nothing is sent to anyone. Pass confirm: true.\n\nScope: `customers:write`. Destructive: it deletes or cancels.","x-required-scope":"customers:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string","description":"Customer UUID or semantic id (cus_<uuid>)."},"property_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The property id from flyra_list_customer_properties."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the property is deleted."}},"required":["customer_id","property_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_create_subscription_plan":{"post":{"operationId":"flyra_create_subscription_plan","summary":"Create a subscription with billing, first visit, discount and visit dates","tags":["Subscriptions"],"description":"The New Subscription form in the Flyra app, Send to customer: create a recurring plan for one customer with the plan discount, the initial (first) visit price, discount and tax, the billing schedule (service dates, on completion, a specific day of the month, the 1st of the month), the visit dates and the property, then send it to that customer, as the form does. Use flyra_create_subscription for a plain plan that is not sent.\n\nVisit dates: the form turns its service months, repeat day (e.g. the 2nd Tuesday, or the 15th) and visit time into one date-time per visit; pass those as visit_dates, each with its time and UTC offset. Left out, the plan has no dates yet (Schedule later).\n\nWhat the customer gets: the plan goes to THE PLAN'S CUSTOMER only, at the email and mobile number on file, through the same send as the form (the org's Subscription Approval Link message with the plan link, the agreement PDF unless send_with_agreement is false; the Automations switches apply, and a workflow already carrying it is not doubled). A plan that needs nothing from the customer (requires_card_on_file false and require_signature false) starts now: its visits are booked, and when it has visit_dates the customer also gets the service-schedule email. confirm must be true.\n\nDeposit (CRM#6768): deposit asks the customer for a deposit before the plan starts, as the form's Deposit section does: a percent (1-100) or a fixed amount in cents. As on the form, only with billing_mode service_dates or on_completion (the template's, when left out); the create refuses any other. A plan with a deposit is created pending, even when it needs no card or signature.\n\nAny member may create a plan, as in the app; dispatched_employee_ids needs the \"dispatch employees\" permission. Needs a signed-in person; an organization API key is refused.\n\nScope: `subscriptions:write`.","x-required-scope":"subscriptions:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string","description":"Customer UUID or semantic id (cus_...)."},"template_id":{"type":"string","description":"Subscription template id (flyra_list_subscription_templates). Its defaults fill anything left out."},"amount_cents":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Price per visit (or per billing cycle) BEFORE the plan discount, in cents, as typed on the form."},"confirm":{"type":"boolean","const":true,"description":"Must be true: this emails and/or texts the customer."},"address_id":{"description":"Which of the customer's properties the plan services. Left out = their default property.","type":"string"},"frequency":{"description":"Billing Frequency, for the specific_date and first_of_month billing schedules. Defaults to the template's.","type":"string","enum":["weekly","biweekly","monthly","bi_monthly","quarterly","tri_annual","six_months","yearly","biennial","triennial"]},"visits_per_year":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"name":{"type":"string"},"description":{"type":"string"},"discount":{"description":"The plan discount, taken off amount_cents and every visit price.","type":"object","properties":{"type":{"type":"string","enum":["percent","flat"]},"value":{"type":"number","exclusiveMinimum":0,"description":"percent: 1-100. flat: cents off each cycle."}},"required":["type","value"]},"initial_visit_price_cents":{"description":"Initial visit price. Defaults to the template's.","type":"integer","minimum":0,"maximum":9007199254740991},"initial_visit_discount_cents":{"description":"Initial visit discount. Defaults to the template's.","type":"integer","minimum":0,"maximum":9007199254740991},"initial_visit_taxable":{"type":"boolean"},"bill_initial_visit_separately":{"description":"Bill the first visit on its own. Defaults to the template's setting.","type":"boolean"},"initial_visit_billing":{"description":"With bill_initial_visit_separately: charge the first visit on its date, or when it is completed.","type":"string","enum":["service_dates","on_completion"]},"billing_mode":{"description":"When the customer is billed. Defaults to the template's.","type":"string","enum":["service_dates","on_completion","specific_date","first_of_month"]},"billing_day":{"description":"Day of the month, for specific_date.","type":"integer","minimum":1,"maximum":28},"bill_only_on_service_months":{"description":"specific_date / first_of_month: bill only in months that have a visit.","type":"boolean"},"visit_dates":{"description":"Every visit, e.g. \"2026-11-10T09:00:00-07:00\".","maxItems":366,"type":"array","items":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"is_taxable":{"type":"boolean"},"tax_rate":{"type":"number","minimum":0,"maximum":100},"notes":{"type":"string"},"lead_source":{"type":"string"},"salesperson_ids":{"maxItems":20,"type":"array","items":{"type":"string"}},"dispatched_employee_ids":{"maxItems":20,"type":"array","items":{"type":"string"}},"term":{"type":"string","enum":["fixed","until_cancelled"]},"term_months":{"description":"With term \"fixed\".","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"start_date":{"description":"Day the plan was sold, YYYY-MM-DD. Defaults to today in the company's timezone.","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"requires_card_on_file":{"type":"boolean"},"require_signature":{"type":"boolean"},"send_with_agreement":{"description":"Attach the agreement PDF, as the form's \"Send with agreement\" switch (on by default).","type":"boolean"},"deposit":{"description":"The form's Deposit section. Left out = no deposit.","type":"object","properties":{"type":{"type":"string","enum":["percent","fixed"]},"value":{"type":"number","exclusiveMinimum":0,"description":"percent: 1-100. fixed: whole cents."}},"required":["type","value"]}},"required":["customer_id","template_id","amount_cents","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_delete_subscription":{"post":{"operationId":"flyra_delete_subscription","summary":"Delete a subscription","tags":["Subscriptions"],"description":"Permanently delete a pending or cancelled subscription (plan), as the Delete button on the plan's page does. There is no undo: confirm with the user and pass confirm: true. It deletes the plan record and its per-visit charge records; the plan's visits stay as jobs without a plan, and its invoices and payments are kept. Any Stripe billing left on it is cancelled first (stripe_billing says what happened) and its plan-offer follow-ups are stopped (followups_stopped). Nothing is sent to the customer. An active or paused plan is refused: cancel it first with flyra_cancel_subscription. Owners and Admins only.\n\nScope: `subscriptions:write`. Destructive: it deletes or cancels.","x-required-scope":"subscriptions:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_id":{"type":"string","description":"Subscription UUID or semantic id (sub_<uuid>)."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed the delete."}},"required":["subscription_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_disconnect_stripe":{"post":{"operationId":"flyra_disconnect_stripe","summary":"Disconnect Stripe","tags":["Settings"],"description":"Disconnect this business's Stripe account from Flyra, as Settings > Payments > Delete Stripe account does, so customers can no longer pay online. Estimates, invoices and payment records stay. There is no undo: where the platform can, the account is deleted at Stripe too, and connecting again makes a new one. Before calling, tell the user this does not cancel plans: a plan with a saved card stays tied to this account, and its charges can fail once the account is gone. flyra_get_org_settings shows `stripe_connection`. A branch charging on its parent's account has nothing to disconnect; if this business is that parent, those branches stop taking online payments too. Owners and Admins only.\n\nScope: `settings:write`. Destructive: it deletes or cancels.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed the disconnect."}},"required":["confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_services":{"post":{"operationId":"flyra_list_services","summary":"List Flyra service catalog (price book)","tags":["Services"],"description":"Returns the org's service categories with their line items. Useful for picking canonical service names + prices when creating jobs/estimates/invoices, though jobs.service is free text and does not need to match. Categories and their services come in the price book's display order; set it with flyra_reorder_categories and flyra_reorder_services. Add, change and remove services with flyra_create_service, flyra_update_service and flyra_delete_service.\n\nScope: `services:read`.","x-required-scope":"services:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_employees":{"post":{"operationId":"flyra_list_employees","summary":"List Flyra employees","tags":["Employees"],"description":"Returns the org employee roster. Filter by role or active status, and as the Settings > Team filters do: invitation_status (active, pending invite, deactivated), date added (created_from / created_to, against `created_at`) and last service (last_service_from / last_service_to: the newest completed or in-progress job they were dispatched to, returned as `last_service_date`; only for a caller who sees every job). Each employee carries `bio`, the \"About me\" customers see on their visit page (null = hidden; set it with flyra_set_employee_bio).\n\nScope: `employees:read`.","x-required-scope":"employees:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"description":"Filter by role (Admin / Sales Rep / Technician / custom-role-uuid).","type":"string"},"is_active":{"description":"Filter by active status.","type":"boolean"},"invitation_status":{"description":"active = signed in and switched on; pending = invited, not yet accepted; deactivated = access switched off.","type":"string","enum":["active","pending","deactivated"]},"created_from":{"description":"ISO 8601: added on or after.","type":"string"},"created_to":{"description":"ISO 8601: added on or before.","type":"string"},"last_service_from":{"description":"ISO 8601: last service on or after.","type":"string"},"last_service_to":{"description":"ISO 8601: last service on or before.","type":"string"},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":50},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_subscriptions":{"post":{"operationId":"flyra_list_subscriptions","summary":"List Flyra recurring service subscriptions","tags":["Subscriptions"],"description":"Returns recurring service subscriptions with their customer + template summary, `items` (the plan's items with their id, price and which visits each runs on: every, first or months; change them with flyra_update_subscription_items), and `contract`: the term (term=\"fixed\" with term_months like 12 or 24, or \"until_cancelled\"), whether visits are priced one by one (pricing=\"custom_per_visit\" with each visit's date and amount) or flat, and any monthly payment plan.\n\nsalesperson_id is the Team filter on the Subscriptions list: plans where that person is the salesperson or one of the salespeople. As there, someone who is not an Owner or Admin and has no Reports access gets only the plans they sold when they pass it. It cannot be combined with term, term_months or pricing.\n\nScope: `subscriptions:read`.","x-required-scope":"subscriptions:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"Filter by subscription status.","type":"string"},"customer_id":{"description":"Customer UUID or semantic id.","type":"string"},"since":{"description":"ISO 8601 — only subscriptions created on or after.","type":"string"},"term":{"description":"Only contracts with a set length, or only ones that run until cancelled.","type":"string","enum":["fixed","until_cancelled"]},"term_months":{"description":"Only fixed contracts of this many months, e.g. 12 or 24.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"pricing":{"description":"Only plans priced visit by visit, or only flat-priced plans.","type":"string","enum":["custom_per_visit","flat"]},"salesperson_id":{"description":"Only plans sold by this team member (employee id from flyra_list_employees).","type":"string"},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":50},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_subscription_link":{"post":{"operationId":"flyra_get_subscription_link","summary":"Get the customer link for a subscription","tags":["Subscriptions"],"description":"Return the customer link for a service plan WITHOUT sending it. On a \"pending\" plan the customer reviews the agreement there, signs it when the plan asks for a signature, and saves a card when it asks for one (see flyra_update_subscription_requirements); on a started plan it is their plan page.\n\nSend it with flyra_send_sms or flyra_send_email, for example when signing in person did not work. The link works for 90 days.\n\nAlso returns agreement_pdf_link: the plan's agreement as a PDF, the file the public plan page's download button serves (/api/public/subscription/<id>/pdf). Use it where the subscription page offers Download agreement. It carries the same 90-day token as public_link. It is null when the plan has no agreement (the subscription page then shows no Download agreement button).\n\nScope: `subscriptions:read`.","x-required-scope":"subscriptions:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_id":{"type":"string","description":"Subscription UUID or semantic id (sub_...)."}},"required":["subscription_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_send_subscription":{"post":{"operationId":"flyra_send_subscription","summary":"Send or resend a subscription to its customer","tags":["Subscriptions"],"description":"The Send Subscription / Resend Subscription button on the subscription page: text and/or email THE PLAN'S CUSTOMER their plan link, through the same send the app uses. This messages the customer.\n\nA pending plan gets the invitation to review and accept it; a plan the rep accepted in person (pending or active) gets the \"you're all set\" confirmation. Any other plan is refused: a paused or cancelled one, and an active one that was sent for acceptance (the send would put it back to pending). So is one service of a bundle (the customer signs the bundle on its main plan).\n\nDelivery: channels [\"email\"], [\"text\"] or both, to the customer's email and mobile number on file only. Omitted = every channel the customer has an address for, as the button's dialog ticks them. The body is the org's own subscription message (Automations) unless `message` is given; {subscription_link}, {customer_name}, {company_name} and {pricing_summary} are filled in. When the org's workflow is already carrying this send, the result says handled_by_workflow: true and nothing is sent twice. A text of the same invitation in the last 30 seconds answers deduplicated: true.\n\nAny member who can open the plan's customer may send it, as in the app. Needs a signed-in person; an organization API key is refused. confirm must be true.\n\nScope: `subscriptions:write`. Destructive: it deletes or cancels.","x-required-scope":"subscriptions:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_id":{"type":"string","description":"Subscription UUID or semantic id (sub_...)."},"channels":{"description":"email and/or text. Omit to use every channel the customer has an address for.","minItems":1,"type":"array","items":{"type":"string","enum":["email","text"]}},"message":{"description":"Custom body. Omit to send the org's own subscription message.","type":"string","maxLength":1000},"confirm":{"type":"boolean","const":true,"description":"Must be true: this texts and/or emails the customer."}},"required":["subscription_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_subscription_templates":{"post":{"operationId":"flyra_list_subscription_templates","summary":"List Flyra subscription templates (recurring service plans)","tags":["Subscriptions"],"description":"Returns the org's subscription templates — the reusable plan definitions a new subscription is created from. Use this to find a template_id (and its default frequency / visits_per_year / line items / per_visit_line_items) before calling flyra_create_subscription. Archived templates are excluded by default. Each template carries its own terms_and_conditions, billing_information and guarantees text (null = the organization default): read it here before changing it with flyra_update_subscription_template. shows_terms / shows_billing say whether the Terms and Billing information boxes appear on the agreement; flyra_update_subscription_template display_terms / display_billing switches them.\n\nScope: `subscriptions:read`.","x-required-scope":"subscriptions:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"include_archived":{"description":"Include archived templates. Defaults to false.","type":"boolean"},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":50},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_employee_stats":{"post":{"operationId":"flyra_get_employee_stats","summary":"Get an employee's performance stats","tags":["Employees"],"description":"Aggregate stats for one employee over an optional date range: jobs completed, revenue produced, jobs in progress, scheduled and cancelled. Use range to scope (\"this month\", \"last 30 days\"): completed jobs count by when they were completed, the rest by when they are scheduled. Counts every job in the company, so only a caller who sees every job can use it.\n\nScope: `employees:read`.","x-required-scope":"employees:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"string"},"range":{"type":"object","properties":{"start":{"type":"string","description":"ISO 8601 inclusive."},"end":{"type":"string","description":"ISO 8601 inclusive."}},"required":["start","end"]}},"required":["employee_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_create_subscription":{"post":{"operationId":"flyra_create_subscription","summary":"Create a Flyra recurring service subscription","tags":["Subscriptions"],"description":"Create a recurring service subscription for a customer. Pass a customer_id, a template_id (use flyra_list_subscription_templates to find one), an amount_cents, and a frequency. Name/description/visits_per_year/frequency and the contract length (12 months, 24 months, until cancelled) default from the template when omitted; pass term / term_months to choose a different length. Defaults to status \"pending\" (awaiting customer acceptance), which counts as sending the plan for acceptance, as in the Flyra app: when the company has the Subscription Approval Link automation or its follow-ups switched on (flyra_list_automations), the customer gets the plan link from them shortly after this call. Creating a pending plan always counts as sending it, so when the user wants to send the link themselves, tell them that before creating it. The plan keeps the template's first visit price, billing schedule (such as the 1st of the month) and first visit billing; read its billing_mode in flyra_list_subscription_templates first. On a 1st of the month or set day plan, amount_cents is charged once per billing cycle (frequency; a biweekly plan is charged monthly there, see frequency), not per visit, starting when the customer approves the plan with a card, so leave it pending. To set those for this plan only, use flyra_create_subscription_plan (it sends the plan). Send the link from flyra_get_subscription_link with flyra_send_sms only when that automation is off, or the customer gets it twice. Pass status:\"active\" only when the subscription should bill immediately. requires_card_on_file and require_signature default to the template settings, as in the app; requires_card_on_file:false lets the customer sign now and add a card later (flyra_send_payment_method_link). amount_cents may be 0 for a plan Flyra should not charge; start_date defaults to today.\n\nScope: `subscriptions:write`.","x-required-scope":"subscriptions:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string","description":"Existing customer UUID or semantic id (e.g. \"cus_...\")."},"template_id":{"type":"string","description":"Subscription template UUID or semantic id (e.g. \"subtpl_...\"). Get one from flyra_list_subscription_templates."},"amount_cents":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Recurring charge per billing cycle, in cents, before any discount. 0 for a plan Flyra should not charge."},"discount":{"description":"The plan discount, as on the New Subscription form. It comes off amount_cents every cycle; the reply's amount_cents is what each cycle bills.","type":"object","properties":{"type":{"type":"string","enum":["percent","flat"]},"value":{"type":"number","exclusiveMinimum":0,"description":"percent: 1-100. flat: cents off each cycle."}},"required":["type","value"]},"frequency":{"description":"Billing/service cadence. Defaults to the template's frequency, or \"monthly\". \"biweekly\" (every 2 weeks) is a plan-only choice, as on the New Subscription form: templates cannot hold it. A biweekly plan is billed the way the app bills one: per visit on the default service_dates billing, and where billing runs through a Stripe recurring subscription (first_of_month / specific_date) Stripe charges it monthly, because Flyra has no two-week Stripe interval (CRM#3953).","type":"string","enum":["weekly","biweekly","monthly","bi_monthly","quarterly","tri_annual","six_months","yearly","biennial","triennial"]},"name":{"description":"Display name. Defaults to the template name.","type":"string"},"description":{"description":"Defaults to the template description.","type":"string"},"visits_per_year":{"description":"Defaults to the template value.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"is_taxable":{"type":"boolean"},"tax_rate":{"description":"Percent (e.g. 8.25). Only applied when is_taxable.","type":"number","minimum":0,"maximum":100},"notes":{"type":"string"},"lead_source":{"type":"string"},"status":{"description":"Defaults to \"pending\" (awaiting customer acceptance), which fires the Subscription Approval Link automation when it is on. Use \"active\" to start billing now.","type":"string","enum":["pending","active"]},"requires_card_on_file":{"description":"Whether the customer must save a card before the plan starts. Defaults to the template's setting, else true.","type":"boolean"},"require_signature":{"description":"Whether the customer must sign the agreement before the plan starts. Left out, the customer is asked to sign when the template asks for it.","type":"boolean"},"term":{"description":"Contract length. Defaults to the template's length (see flyra_list_subscription_templates). \"until_cancelled\" renews until someone cancels.","type":"string","enum":["fixed","until_cancelled"]},"term_months":{"description":"Fixed contract length in months (e.g. 12 or 24). Overrides the template's length. Billing stops when it ends.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"start_date":{"description":"First day of the plan, YYYY-MM-DD (e.g. 2026-11-01). Defaults to today in the company's timezone. A fixed term_months ends counted from it.","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"salesperson_ids":{"description":"Employee ids (flyra_list_employees) credited as the plan's salespeople, as the Salesperson picker on the New Subscription page. The first is the primary.","maxItems":20,"type":"array","items":{"type":"string"}},"dispatched_employee_ids":{"description":"Employee ids (flyra_list_employees) dispatched on the plan's visits, as the crew picker on the New Subscription page. The first is the primary technician. Needs the \"dispatch employees\" permission, as in the app.","maxItems":20,"type":"array","items":{"type":"string"}},"address_id":{"description":"Which of the customer's properties the plan services (a property id, such as a job's address_id), as the property picker on the New Subscription page. Leave out for the customer's default property.","type":"string"}},"required":["customer_id","template_id","amount_cents"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_subscription_requirements":{"post":{"operationId":"flyra_update_subscription_requirements","summary":"Change what a pending subscription needs from the customer","tags":["Subscriptions"],"description":"On a \"pending\" plan, set whether the customer must save a card (requires_card_on_file) and sign the agreement (require_signature) before it starts, as the plan page in the app does. requires_card_on_file:false lets them sign now and add a card later with flyra_send_payment_method_link; it needs require_signature too (true: wait for their signature). If nothing is left for the customer to do (no card, no signature, no unpaid deposit), the plan starts now, as when it starts in the app: its visits are booked and the customer gets the plan confirmation by email and text. Otherwise nothing is sent. The reply says which in started.\n\nScope: `subscriptions:write`.","x-required-scope":"subscriptions:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_id":{"type":"string","description":"Subscription UUID or semantic id (sub_...)."},"requires_card_on_file":{"type":"boolean"},"require_signature":{"type":"boolean"}},"required":["subscription_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_subscription_agreement":{"post":{"operationId":"flyra_update_subscription_agreement","summary":"Change one subscription's own agreement text","tags":["Subscriptions"],"description":"Set the Guarantees, Terms and conditions and Billing information of ONE subscription's agreement, without changing its template or any other plan, as Edit subscription in the Flyra iPhone app saves them. Pass only the sections to change; an empty string clears that plan's own text so the template's text shows again. While the customer has not signed, the plan's agreement copy is redrawn from the new text (the plan's Terms and Billing switches still decide which sections show); once signed, the copy the customer signed is kept as it is and only the stored text changes: signed in the reply says which. display_first_visit, display_visits_per_year and display_service_month_schedule turn this plan's First visit, Visits per year and 12-month service schedule sections on or off on the agreement the customer opens to sign (its page and PDF), as the Edit subscription switches do; they change only this plan, and on a signed plan they change what that page and PDF show too, as the switches do. Nothing is sent to the customer. The text sections are refused for a role an admin has kept from editing agreement terms (Settings > Team > Roles); everything is refused for a plan bundled with others and for an API key not tied to a person. Change the items with flyra_update_subscription_items. Each text field is replaced in full: send the whole new text, not only the part that changes. The reply's replaced_text holds the text each field replaced, so a mistake can be put back.\n\nScope: `subscriptions:write`.","x-required-scope":"subscriptions:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_id":{"type":"string","description":"Subscription UUID or semantic id (sub_...)."},"guarantees":{"description":"This plan's Guarantees text. Empty string clears it back to the template's.","type":"string","maxLength":20000},"terms_and_conditions":{"description":"This plan's Terms and conditions. Empty string clears it back to the template's.","type":"string","maxLength":20000},"billing_information":{"description":"This plan's Billing information. Empty string clears it back to the template's.","type":"string","maxLength":20000},"display_first_visit":{"description":"Show (true) or hide (false) the First visit section on this plan's agreement.","type":"boolean"},"display_visits_per_year":{"description":"Show (true) or hide (false) the Visits per year section on this plan's agreement.","type":"boolean"},"display_service_month_schedule":{"description":"Show (true) or hide (false) the 12-month service schedule section on this plan's agreement.","type":"boolean"}},"required":["subscription_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_change_subscription_template":{"post":{"operationId":"flyra_change_subscription_template","summary":"Move one subscription to a different template","tags":["Subscriptions"],"description":"Move ONE existing plan onto another of the company's subscription templates, as choosing a template when saving a plan in the Flyra app does. Only the plan's template link changes: its price, items, visits, billing and agreement (signed or not) stay as they are. Payroll follows the new template from then on (the template commission rate and sale bonus of the plan's seller), and so do the plan's template name on reports and pay statements. Archived templates are refused. Nothing is sent to the customer. Refused for a plan bundled with others. Get template ids from flyra_list_subscription_templates.\n\nScope: `subscriptions:write`.","x-required-scope":"subscriptions:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_id":{"type":"string","description":"Subscription UUID or semantic id (sub_...)."},"template_id":{"type":"string","description":"The template to move the plan to: UUID or semantic id (subtpl_...)."}},"required":["subscription_id","template_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_subscription_amount":{"post":{"operationId":"flyra_update_subscription_amount","summary":"Update a subscription's billing amount","tags":["Subscriptions"],"description":"Change the recurring amount on a subscription. amount_cents is the price BEFORE the plan's own discount, as on the subscription page: the plan's discount comes off it and the reply's amount_cents is what each cycle bills. flyra_list_subscriptions returns the current figure as amount_before_discount_cents. Future invoices use the new amount; the next_billing_date is unaffected. Refused on a plan paid in monthly installments (code term_payment_plan): its monthly is worked out from the contract total.\n\nScope: `subscriptions:write`.","x-required-scope":"subscriptions:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_id":{"type":"string"},"amount_cents":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The price per cycle before the plan's discount, in cents."}},"required":["subscription_id","amount_cents"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_subscription_frequency":{"post":{"operationId":"flyra_update_subscription_frequency","summary":"Update a subscription's billing frequency","tags":["Subscriptions"],"description":"Change how often a subscription bills (its billing frequency), as the frequency picker on the subscription page does. Use it when a plan's frequency is wrong, for example a plan with 4 visits a year saved as monthly, which inflates MRR and ARR. The amount is per billing cycle and is NOT rescaled: the reply shows amount_cents with the new frequency, and if the per-cycle amount is now wrong set it with flyra_update_subscription_amount. Visit dates and visits_per_year are unaffected (see flyra_update_subscription_schedule). Refused on a plan paid in monthly installments (code term_payment_plan) and on a plan in a bundle. Nothing is sent to the customer.\n\nScope: `subscriptions:write`.","x-required-scope":"subscriptions:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_id":{"type":"string","description":"Subscription UUID or semantic id (sub_...)."},"frequency":{"type":"string","description":"The new billing frequency, one of: weekly, monthly, bi_monthly, quarterly, tri_annual, six_months, yearly, biennial, triennial."}},"required":["subscription_id","frequency"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_subscription_auto_charge":{"post":{"operationId":"flyra_set_subscription_auto_charge","summary":"Turn automatic card charging on or off for a subscription","tags":["Subscriptions"],"description":"The Charge card automatically switch on a subscription's page in the Flyra app. auto_charge:false: no automatic path charges the card on file; each visit stays owed and the business collects it from the invoice. auto_charge:true: visits from now on are charged to the card on file on their own; visits up to today that are still owed (except an open visit on a plan that bills when the visit is completed) are kept manual, so nothing already collected through an invoice is charged twice (visits_left_manual counts them). Refused on a cancelled plan and on a plan billed monthly by a Stripe subscription, as the app does not show the switch there. Nothing is sent to the customer. Pass confirm:true after the user agreed to the change.\n\nScope: `subscriptions:write`.","x-required-scope":"subscriptions:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_id":{"type":"string","description":"Subscription UUID or semantic id (sub_...)."},"auto_charge":{"type":"boolean","description":"true charges the card automatically from now on; false stops automatic charging."},"confirm":{"type":"boolean","const":true,"description":"Must be true: this changes how the customer is charged."}},"required":["subscription_id","auto_charge","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_subscription_salespeople":{"post":{"operationId":"flyra_set_subscription_salespeople","summary":"Set who is credited with selling a subscription","tags":["Subscriptions"],"description":"The Salesperson field on a subscription's Assignment tab in the Flyra app. Replaces the whole list with salesperson_ids (employee ids from flyra_list_employees, active team members of this business only); [] clears it. The first one is the main salesperson. The salespeople are credited with this sale on the leaderboard and in payroll's sales override check, so pass confirm:true after the user agreed. Nothing is sent to anyone and billing does not change. Visits already booked keep their salespeople, except at a business set up to carry every salesperson onto its visits.\n\nScope: `subscriptions:write`.","x-required-scope":"subscriptions:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_id":{"type":"string","description":"Subscription UUID or semantic id (sub_...)."},"salesperson_ids":{"maxItems":20,"type":"array","items":{"type":"string"},"description":"Employee UUIDs or semantic ids (emp_...), main salesperson first. [] clears it."},"confirm":{"type":"boolean","const":true,"description":"Must be true: this changes who is paid for the sale."}},"required":["subscription_id","salesperson_ids","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_subscription_crew":{"post":{"operationId":"flyra_set_subscription_crew","summary":"Set which technicians a subscription is dispatched to","tags":["Subscriptions"],"description":"The Technicians field on a subscription's Assignment tab in the Flyra app. Replaces the whole crew with dispatched_employee_ids (employee ids from flyra_list_employees, team members of this business); the first one is the main technician; [] clears it. As in the app, the plan's future scheduled visits that are unassigned or still have the plan's old crew take the new crew; a visit somebody dispatched by hand keeps its own. Messages, exactly as in the app: each of those visits whose crew changes to a non-empty one starts the \"Technician assigned\" automation trigger, which texts or emails the plan's customer only where the business has an automation on it, and each technician newly put on a visit is emailed about it unless the business turned dispatch emails off. Call with dry_run:true first: it saves nothing and answers customer_messages (the \"Technician assigned\" events the save starts, all for the plan's one customer; a business with more than one automation on that trigger can send more than one message per event, so read it as at least this many) and visits (the visits that take the new crew). Then call again without dry_run, passing expected_customer_messages equal to that number; if it changed in between, nothing is saved. Needs the Dispatch employees permission when the crew changes, and a role that sees every job; plans with services on different schedules are refused, as in the app. Unlike a save on the subscription page, this does not book any of the plan's dated visits that have no job yet. Pass confirm:true after the user agreed.\n\nScope: `subscriptions:write`. Destructive: it deletes or cancels.","x-required-scope":"subscriptions:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_id":{"type":"string","description":"Subscription UUID or semantic id (sub_...)."},"dispatched_employee_ids":{"maxItems":20,"type":"array","items":{"type":"string"},"description":"Employee UUIDs or semantic ids (emp_...), main technician first. [] clears the crew."},"dry_run":{"description":"true answers with customer_messages and visits and saves nothing.","type":"boolean"},"expected_customer_messages":{"description":"Required without dry_run: the customer_messages the dry run answered.","type":"integer","minimum":0,"maximum":9007199254740991},"confirm":{"type":"boolean","const":true,"description":"Must be true: this changes who is sent to the customer's visits and can message the customer."}},"required":["subscription_id","dispatched_employee_ids","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_subscription_schedule":{"post":{"operationId":"flyra_update_subscription_schedule","summary":"Change a subscription's visit schedule","tags":["Subscriptions"],"description":"Replace a recurring subscription's visit days. Pass visit_dates: EVERY future visit of the next twelve months, each as an ISO 8601 date-time with its time of day and UTC offset (e.g. \"2026-10-09T10:00:00-07:00\" for Friday 10 AM Pacific). The plan repeats exactly those days every year; list each visit, nothing is inferred from the spacing. visits_per_year becomes the number of dates given. Booked future visits move to the new days, dropped days are cancelled and new days get a job; a visit with an invoice, a payment or a charge in progress is never touched and comes back in jobs.blocked for a person to handle. The customer is not told about moved or new visits. The card on file is not changed. Without items the plan's items stay as they are, but the price can change with the visit count: amount_cents_before and amount_cents show it, and dry_run previews. A plan with no items (as flyra_create_subscription makes it) needs items: send visit_dates and items together here, as the subscription page saves them; items is the WHOLE new list in the same shape flyra_update_subscription_items takes, and the plan's price is worked out from it. Active plans only, and not plans paid in monthly installments.\n\nScope: `subscriptions:write`. Destructive: it deletes or cancels.","x-required-scope":"subscriptions:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_id":{"type":"string"},"visit_dates":{"minItems":1,"maxItems":53,"type":"array","items":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"description":"Every future visit of the next twelve months, at most one per day."},"items":{"description":"The plan's whole new list of items, saved with the dates. Leave out to keep the items the plan has.","minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"id":{"description":"The item's id from flyra_list_subscriptions items, to keep or change it. Leave out for a new item.","type":"string"},"title":{"description":"Required for a new item.","type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":2000},"quantity":{"type":"integer","exclusiveMinimum":0,"maximum":10000},"unit_price_cents":{"description":"Price of one, in cents (at most 10,000,000). Required for a new item.","type":"integer","minimum":0,"maximum":10000000},"taxable":{"type":"boolean"},"applied_tax_rates":{"description":"The org's active tax rates on this item, by id (flyra_get_org_settings lists them). Only the id is read: the name and rate saved are the org's own.","maxItems":20,"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"rate_percent":{"type":"number"}},"required":["id"]}},"runs_on":{"description":"every visit (default for a new item), the first visit only, or only in the months listed. Left out, a kept item keeps its choice.","type":"string","enum":["every","first","months"]},"months":{"description":"runs_on \"months\": month numbers 1 (January) to 12.","minItems":1,"maxItems":12,"type":"array","items":{"type":"integer","minimum":1,"maximum":12}},"also_first_visit":{"description":"runs_on \"months\": also put it on the first visit.","type":"boolean"},"unit":{"description":"What quantity is counted in, as the Unit picker on a line saves it: \"sq ft\" or \"linear ft\" (\"sqm\" or \"linear m\" for a business that measures in metres), or the business's own word, up to 16 characters. Leave it out for a plain count (Qty); null makes a kept item a plain count, and left out a kept item keeps its unit.","anyOf":[{"type":"string","minLength":1,"maxLength":16},{"type":"null"}]}}}},"dry_run":{"description":"true answers with what would change (days, jobs, price) and saves nothing. Use it first when the number of visits changes or items are sent, and tell the user any new price.","type":"boolean"},"confirm":{"description":"Needed with items, as flyra_update_subscription_items needs it: true after the user agreed to the new items and price.","type":"boolean","const":true}},"required":["subscription_id","visit_dates"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_subscription_items":{"post":{"operationId":"flyra_update_subscription_items","summary":"Change a subscription's items and per-visit pricing","tags":["Subscriptions"],"description":"The items on a subscription's Plan card in the Flyra app, with each item's Runs on choice: every visit, the first visit only, or only in chosen months (optionally also on the first visit), e.g. a larger first visit or extra items in some months. Pass items: the WHOLE new list. Keep an item by passing its id from flyra_list_subscriptions (items); fields you leave out keep their value, and an item left out of the list is removed. A new item has no id and needs title and unit_price_cents. The plan's visit dates do not change. Each visit's price and the plan's price are worked out from the items, as in the app, so the price the customer pays can change: amount_cents_before and amount_cents show it, visits lists each upcoming visit's price, and dry_run:true shows all of it without saving. Booked future visits take their new items and price, and a pending card charge on them follows; a visit with an invoice, a payment or a charge in progress, or one somebody changed by hand, keeps its items and comes back in jobs.blocked. Nothing is sent to the customer. Active and pending plans only. Refused on plans paid in monthly installments, plans whose visits carry their own hand-set prices, plans with no visit dates, a plan billed by a Stripe subscription when its price or tax would change, a change that would take a charged plan to 0, and when the change would also move or cancel booked visits: those are changed on the subscription page. A change that would book new visits (code would_book_visits) is refused too, dry run included: a first-visit item usually does, since it writes the plan out to its first anniversary; make that change on the subscription page. Pass confirm:true after the user agreed to the new items and price.\n\nScope: `subscriptions:write`. Destructive: it deletes or cancels.","x-required-scope":"subscriptions:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_id":{"type":"string","description":"Subscription UUID or semantic id (sub_...)."},"items":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"id":{"description":"The item's id from flyra_list_subscriptions items, to keep or change it. Leave out for a new item.","type":"string"},"title":{"description":"Required for a new item.","type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":2000},"quantity":{"type":"integer","exclusiveMinimum":0,"maximum":10000},"unit_price_cents":{"description":"Price of one, in cents (at most 10,000,000). Required for a new item.","type":"integer","minimum":0,"maximum":10000000},"taxable":{"type":"boolean"},"applied_tax_rates":{"description":"The org's active tax rates on this item, by id (flyra_get_org_settings lists them). Only the id is read: the name and rate saved are the org's own.","maxItems":20,"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"rate_percent":{"type":"number"}},"required":["id"]}},"runs_on":{"description":"every visit (default for a new item), the first visit only, or only in the months listed. Left out, a kept item keeps its choice.","type":"string","enum":["every","first","months"]},"months":{"description":"runs_on \"months\": month numbers 1 (January) to 12.","minItems":1,"maxItems":12,"type":"array","items":{"type":"integer","minimum":1,"maximum":12}},"also_first_visit":{"description":"runs_on \"months\": also put it on the first visit.","type":"boolean"},"unit":{"description":"What quantity is counted in, as the Unit picker on a line saves it: \"sq ft\" or \"linear ft\" (\"sqm\" or \"linear m\" for a business that measures in metres), or the business's own word, up to 16 characters. Leave it out for a plain count (Qty); null makes a kept item a plain count, and left out a kept item keeps its unit.","anyOf":[{"type":"string","minLength":1,"maxLength":16},{"type":"null"}]}}}},"dry_run":{"description":"true answers with the new items, prices and visits and saves nothing.","type":"boolean"},"confirm":{"type":"boolean","const":true,"description":"Must be true: this changes what the customer is charged."}},"required":["subscription_id","items","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_subscription_item_tax":{"post":{"operationId":"flyra_update_subscription_item_tax","summary":"Change only the tax on a subscription's items","tags":["Subscriptions"],"description":"Set which tax rates apply to items on a subscription's Plan card, and nothing else: prices, quantities, Runs on, visit dates, the plan's price and booked visits do not change, and no visit is booked, moved or re-priced. Use it to take a tax rate off a plan's items (e.g. an old rate the business no longer charges) so visits made from the plan from now on are taxed the new way. Pass items: only the items to change, each by its id from flyra_list_subscriptions (items), with taxable and, when taxable is true, applied_tax_rates: the WHOLE new list of the org's active tax rates for that item, by id (flyra_get_org_settings lists them). Items left out keep their tax. Visits with their own items carry the same item ids, and their copy of the item gets the same tax; visit_items_unmatched counts per-visit items whose id is not on the plan and so keep their tax. Visits already booked keep the tax they have: change those on the visit. Refused on plans paid in monthly installments, and a plan billed by a recurring card subscription when its tax would change: those are changed on the subscription page. Nothing is sent to the customer. dry_run:true shows the new items and writes nothing. Pass confirm:true after the user agreed to the new tax.\n\nScope: `subscriptions:write`. Destructive: it deletes or cancels.","x-required-scope":"subscriptions:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_id":{"type":"string","description":"Subscription UUID or semantic id (sub_...)."},"items":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The item's id from flyra_list_subscriptions items."},"taxable":{"type":"boolean"},"applied_tax_rates":{"description":"Needed when taxable is true: every tax rate the item keeps, by id. Only the id is read: the name and rate saved are the org's own.","minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"rate_percent":{"type":"number"}},"required":["id"]}}},"required":["id","taxable"]}},"dry_run":{"description":"true answers with the new items and writes nothing.","type":"boolean"},"confirm":{"type":"boolean","const":true,"description":"Must be true: this changes the tax on the plan's future visits."}},"required":["subscription_id","items","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_pause_subscription":{"post":{"operationId":"flyra_pause_subscription","summary":"Pause a subscription","tags":["Subscriptions"],"description":"Mark the subscription paused. Recurring billing is suspended until flyra_resume_subscription is called. A cancelled plan cannot be paused. reason (optional, up to 500 characters) is not stored on the plan; it rides on the subscription.paused automation event, where trigger_field_matches can filter on it.\n\nScope: `subscriptions:write`.","x-required-scope":"subscriptions:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_id":{"type":"string"},"reason":{"type":"string","maxLength":500}},"required":["subscription_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_resume_subscription":{"post":{"operationId":"flyra_resume_subscription","summary":"Resume a paused subscription","tags":["Subscriptions"],"description":"Re-activate a paused subscription. next_billing_date is not auto-bumped: to move the plan's visits (and with them its billing dates), call flyra_update_subscription_schedule.\n\nScope: `subscriptions:write`.","x-required-scope":"subscriptions:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_id":{"type":"string"}},"required":["subscription_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_cancel_subscription":{"post":{"operationId":"flyra_cancel_subscription","summary":"Cancel a subscription","tags":["Subscriptions"],"description":"Permanently cancel a subscription. This stops recurring billing: the linked Stripe subscription (if any) is cancelled, the subscription status is set to \"cancelled\", and future scheduled jobs tied to it are cancelled. Past invoices/payments are preserved. Use flyra_pause_subscription instead if billing should only be temporarily suspended. reason is one of the org's cancellation reasons for plans (flyra_list_cancellation_reasons), with an optional note, as the Cancel subscription screen saves them; it is checked against that list as in the app: when the org requires a reason on plans, a cancel without one is refused, and when it asks for none, none is kept. Someone the Save Center lets only request a cancellation is refused (cancellation_request_required), as in the app. An open Save Center request on the plan is closed as cancelled with it, as when the plan is cancelled in the app. Any cancellation automations the org has switched on (flyra_list_automations) start, as on any cancel. This does not charge the plan's cancellation fee, which a cancel in the app does.\n\nScope: `subscriptions:write`. Destructive: it deletes or cancels.","x-required-scope":"subscriptions:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_id":{"type":"string"},"reason":{"description":"A cancellation reason name from flyra_list_cancellation_reasons (applies_to both or subscriptions).","type":"string","maxLength":200},"note":{"description":"A note saved with the reason.","type":"string","maxLength":500},"notify_customer":{"description":"Default false. true emails the customer the org's standard cancellation notice. Leave it unset unless the user asked for the customer to be told - nobody reviews this send before it goes out. Orgs running their own cancellation automation are skipped either way, so their customer is never emailed twice.","type":"boolean"}},"required":["subscription_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_send_sms":{"post":{"operationId":"flyra_send_sms","summary":"Send an SMS from Flyra","tags":["Texting"],"description":"Send one SMS or MMS from the org's Flyra number. Pass customer_id (their mobile_phone is used) or a raw to_phone in E.164 (+15551234567).\n\nAttach pictures or a PDF with media_urls: public https URLs the carrier can fetch (a flyra_list_job_photos link works); big files are shrunk. On an org's own Quo or Twilio account media is dropped and the text still goes.\n\nIf the org cannot text yet (no number, or for US orgs no 10DLC campaign), returns a setup-incomplete error. Max 10 sends a minute per org.\n\nTexts to people the business is already working with are free. Anyone else is cold: 25 cold numbers per 30 days are free, then each cold text costs 1 SMS blast credit; without enough credits it is refused with a message to pass on. Send lists with flyra_send_sms_blast.\n\nfrom_line (id from flyra_list_lines) picks the sending number; default: the thread's line or the main number.\n\nReturns thread_message_id (its flyra_get_thread id), from (the sending line) and status: queued. Read flyra_get_thread before resending.\n\nScope: `sms:send`.","x-required-scope":"sms:send","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"description":"Customer UUID or semantic id from flyra_search_customers. Recipient's mobile_phone is used.","type":"string"},"to_phone":{"description":"Raw E.164 phone, e.g. +15551234567. Used when customer_id is omitted or the customer has no phone on file.","type":"string"},"body":{"description":"Message text. At most 10 carrier segments: 1530 characters of plain text, or about 670 once the text has any emoji or special character (the carrier then bills 67-character segments). Longer is refused here, before anything is queued. Required unless media_urls is given — a picture with no caption is a real message, an empty text is not. Bare flyra.io URLs are auto-rewritten to app.flyra.io to avoid T-Mobile spam filtering.","type":"string","maxLength":1600},"media_urls":{"description":"Public https URLs to attach, at most 5. Images and PDFs. The carrier fetches these itself, so they must be reachable without a login.","maxItems":5,"type":"array","items":{"type":"string"}},"send_at":{"description":"Send it later, as Schedule message in the Flyra Inbox does: an ISO 8601 time with its offset, at least a minute and at most a year from now (e.g. 2026-10-30T09:00:00-07:00). Leave out to send now. At most 10 connector texts per business can be scheduled for any one minute, and a cancelled one still counts. The reply then carries scheduled_for, flyra_get_thread shows the text with scheduled_for set until it goes out, and flyra_cancel_scheduled_message stops it before then. A cold text's credit is spent when it is scheduled, and cancelling does not give it back.","type":"string"},"idempotency_key":{"description":"Optional: a key for this one text (8 to 128 characters). A retry with the same key is not texted or charged again.","type":"string","minLength":8,"maxLength":128},"from_line":{"description":"Optional. The line to send from: a phone_<uuid> id from flyra_list_lines. Must be a line that can text. Left out, a reply goes out from the line the conversation is already on, and a new conversation from the business's main number.","type":"string"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_lines":{"post":{"operationId":"flyra_list_lines","summary":"List the business's phone lines","tags":["Texting"],"description":"Every phone number the business has in Flyra: id (phone_<uuid>, what from_line takes on flyra_send_sms and flyra_reply_to_thread), number, name, whether it is the main number, and whether it can send texts. A line that cannot text is a calls-only line, a number left behind by a port or number switch (old: true), or one still waiting on carrier approval; it still receives texts and calls.\n\nScope: `sms:read`.","x-required-scope":"sms:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_conversations":{"post":{"operationId":"flyra_list_conversations","summary":"List SMS conversations","tags":["Texting"],"description":"List recent SMS conversations (contacts) ordered by last message. Each row carries the contact id, customer link, last message preview, and unread state. A person connected through OAuth sees the threads their Inbox shows them; `total` is null while more pages remain. Pass updated_since to list only threads with a message at or after that time: a new text in either direction from anyone counts, a later delivery status change does not, and a recorded call counts from the time it landed in Flyra, which can be minutes after the call ended. To keep a copy in sync, pass the newest last_message_at from your previous run less a few seconds, read each listed thread with flyra_get_thread passing after (your newest sent_at for it, less a few seconds), skip message ids you already have, and move your saved times forward only once has_more is false.\n\nawaiting_reply, salesperson_ids, tag_ids and technician_ids are the Inbox Filter panel's filters, for a person connected through OAuth; every one given must match.\n\nScope: `sms:read`.","x-required-scope":"sms:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"integer","exclusiveMinimum":0,"maximum":50},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991},"updated_since":{"description":"ISO 8601 time. Only threads whose last message is at or after it. With an Inbox filter below, a recorded call that landed late is not added, as in the Inbox.","type":"string"},"awaiting_reply":{"description":"Awaiting your reply: true keeps threads whose last message came in from the contact.","type":"boolean"},"salesperson_ids":{"description":"Salesperson: employee ids (emp_<uuid>) from flyra_list_employees. Keeps threads whose customer one of them sold a job to or sent an estimate to, or whose lead one of them sent an estimate to.","maxItems":50,"type":"array","items":{"type":"string"}},"tag_ids":{"description":"Tag: ids from flyra_list_tags. Keeps threads whose customer has any of them; a thread with no customer never matches.","maxItems":50,"type":"array","items":{"type":"string"}},"technician_ids":{"description":"Technician: employee ids (emp_<uuid>) from flyra_list_employees. Keeps threads whose customer has a job or subscription, not cancelled, dispatched to one of them; a thread with no customer never matches.","maxItems":50,"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"contact_<uuid>; pass to flyra_get_thread as contact_id."},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"E.164."},"customer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"cus_<uuid>, or null when the number is not linked to a customer."},"last_message_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO timestamp."},"last_message_direction":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"inbound or outbound."},"last_message_preview":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_message_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"muted":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"summary":{"type":"string"}},"required":["id","name","phone","customer_id","last_message_at","last_message_direction","last_message_preview","last_message_status","muted","summary"],"additionalProperties":{}}},"total":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"null while more pages remain on a person's list."},"offset":{"type":"number"},"limit":{"type":"number"},"truncated":{"type":"boolean"},"next_offset":{"anyOf":[{"type":"number"},{"type":"null"}]},"note":{"description":"Set when the first page is empty.","type":"string"}},"required":["items","total","offset","limit","truncated","next_offset"],"additionalProperties":{}}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_thread":{"post":{"operationId":"flyra_get_thread","summary":"Get the message history for a contact","tags":["Texting"],"description":"Return the most recent messages on a thread, oldest-first within the page so the agent reads it like a transcript. Pass either contact_id (preferred) or customer_id. count is the size of this page, not of the thread. To read further back, pass next_before as before and next_before_id as before_id while has_more is true. To read only what is new, pass after (and the id of that newest message as after_id): the page then holds the newest messages after it, so when has_more is true, keep after and page back with before. The ids keep two messages sent in the same instant from being skipped at a page edge. Each message names its numbers in from and to and its org line in line_id; an outbound text has no from until it has gone out, and none when it went over iMessage or before Flyra recorded lines. A text scheduled to send later has its send time in scheduled_for; its status reads queued until then. Photos, videos and files on a text are download links in media_urls.\n\nScope: `sms:read`.","x-required-scope":"sms:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"contact_id":{"description":"Contact UUID or semantic id.","type":"string"},"customer_id":{"description":"Customer UUID or semantic id — used to look up the contact.","type":"string"},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":50},"before":{"description":"ISO 8601 time, exclusive. Only messages sent before it; pass next_before from the previous page.","type":"string"},"after":{"description":"ISO 8601 time, exclusive. Only messages sent after it, such as the newest sent_at you already have. A recorded call that landed in Flyra after this time is included too, even though its sent_at is the time the call ended.","type":"string"},"before_id":{"description":"next_before_id from the previous page, passed with before.","type":"string"},"after_id":{"description":"The id of the message whose sent_at you pass as after.","type":"string"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"contact":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"customer_id":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","phone","customer_id"],"additionalProperties":{}},{"type":"null"}]},"count":{"type":"number"},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"msg_<uuid>."},"direction":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"inbound or outbound."},"channel":{"anyOf":[{"type":"string"},{"type":"null"}]},"body":{"anyOf":[{"type":"string"},{"type":"null"}]},"sent_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO timestamp."},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"from":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"E.164. Inbound: the contact's number on file. Outbound: the org line it went out on; null when the row names no line: not sent yet, sent over iMessage, or sent before Flyra recorded lines."},"to":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"E.164. Inbound: the org line it came in on, null on a recorded call. Outbound: the number it was sent to."},"line_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"phone_<uuid> of the org line it used, or null."},"scheduled_for":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO timestamp a scheduled text is set to send at; null once it has gone out, and on every other message. Cancel one with flyra_cancel_scheduled_message."},"media_urls":{"type":"array","items":{"type":"string"},"description":"Download links for the pictures, videos and files sent or received on this text, the same files the Flyra Inbox shows. Empty when it has none."}},"required":["id","direction","channel","body","sent_at","status","error","from","to","line_id","scheduled_for","media_urls"],"additionalProperties":{}},"description":"Oldest first within the page."},"has_more":{"type":"boolean","description":"True when older messages remain: pass next_before as before and next_before_id as before_id to read them."},"next_before":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The oldest sent_at on this page. Null when has_more is false."},"next_before_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"msg_<uuid> of the oldest message on this page, for before_id. Null when has_more is false."}},"required":["contact","count","messages","has_more","next_before","next_before_id"],"additionalProperties":{}}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_search_messages":{"post":{"operationId":"flyra_search_messages","summary":"Search text messages by their words","tags":["Texting"],"description":"Search every text thread in the organization for messages whose body contains the words given (case does not matter), newest first. Inbound messages only by default; pass direction \"outbound\" or \"any\" for the others. Each hit names its thread (contact_id for flyra_get_thread, name, phone, customer_id, lead_id) and says in is_first_inbound whether it is the first text that person ever sent in. The first page carries total, the exact number of hits; to read further, pass next_before as before and next_before_id as before_id while has_more is true. A person whose role limits which threads they see gets only hits on threads they can open, and no total.\n\nScope: `sms:read`.","x-required-scope":"sms:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":2,"maxLength":200,"description":"Words to find in the message body, e.g. \"yes\" or \"postcard\". Matched as written, not as a pattern; * is not allowed."},"direction":{"description":"Which messages to search. Defaults to inbound (texts the contact sent in).","type":"string","enum":["inbound","outbound","any"]},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":50},"before":{"description":"ISO 8601 time, exclusive: next_before from the previous page.","type":"string"},"before_id":{"description":"next_before_id from the previous page, passed with before.","type":"string"}},"required":["query"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_export_conversation":{"post":{"operationId":"flyra_export_conversation","summary":"Export a text conversation","tags":["Texting"],"description":"Export one text thread as a file, as Export conversation in the Flyra Inbox thread menu does: txt (the format that menu item writes: a \"Conversation with\" header, the export time, then one [time] sender: message line per text), csv (Date, Time, Direction, Message, Status), json, or pdf (the txt file's lines laid out as a text-only PDF; the app itself has no PDF export). The file content comes back as text with its file name and type; for pdf it comes back base64-encoded (content_encoding base64) with its byte_size, and a pdf over 5 MB is refused with too_large. Times are written in the business's time zone. Holds the newest 999 messages, oldest first; truncated says when older ones were left out. Pass contact_id or customer_id. Needs the Messages section, and a person reaches only the threads flyra_get_thread lets them read.\n\nScope: `sms:read`.","x-required-scope":"sms:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"contact_id":{"description":"Contact UUID or semantic id.","type":"string"},"customer_id":{"description":"Customer UUID or semantic id — used to look up the contact.","type":"string"},"format":{"description":"txt (default, what the Inbox menu item writes), csv, json, or pdf (the txt lines as a PDF, returned base64).","type":"string","enum":["txt","csv","json","pdf"]}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"format":{"type":"string"},"filename":{"type":"string"},"mime_type":{"type":"string"},"content":{"type":"string"},"message_count":{"type":"number"},"truncated":{"type":"boolean","description":"True when the thread has more than 999 messages and the oldest were left out."},"time_zone":{"type":"string","description":"The zone the dates and times are written in."},"content_encoding":{"description":"Set for pdf: content is the PDF file base64-encoded.","type":"string","const":"base64"},"byte_size":{"description":"Set for pdf: the PDF file size in bytes.","type":"number"}},"required":["format","filename","mime_type","content","message_count","truncated","time_zone"],"additionalProperties":{}}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_cancel_scheduled_message":{"post":{"operationId":"flyra_cancel_scheduled_message","summary":"Cancel a scheduled text before it sends","tags":["Texting"],"description":"Stop a text that is scheduled to send later, as Delete on it in the Flyra inbox does: it never goes out, and its thread row reads [Message deleted]. Pass the id of a flyra_get_thread message whose scheduled_for is set. Refused with already_sent when it was scheduled and has already gone out, already_sending when it is going out right now, already_failed when it failed and will not go out, already_cancelled when it was cancelled earlier, not_cancellable when no pending send is found for it, and not_scheduled when it was never a scheduled text. A cancelled text cannot be restored; to send it at another time, write it again in the Flyra app.\n\nScope: `sms:send`. Destructive: it deletes or cancels.","x-required-scope":"sms:send","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"message_id":{"type":"string","description":"msg_<uuid> from flyra_get_thread (or the raw uuid)."}},"required":["message_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_mark_thread_read":{"post":{"operationId":"flyra_mark_thread_read","summary":"Mark a text conversation read or unread","tags":["Texting"],"description":"Mark a text thread read or unread for the signed-in person, as Mark as read and Mark as unread on a thread in the Flyra Inbox do. read: true stamps a read time on every incoming text on the thread that has none and clears the person's unread mark on it; messages_marked_read is how many texts were stamped. read: false sets the person's unread mark on the thread; the texts keep their read times. Pass contact_id from flyra_list_conversations. For a person connected through OAuth whose role has Messages; an organization API key is refused, since read state belongs to a person.\n\nScope: `sms:read`.","x-required-scope":"sms:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"contact_id":{"type":"string","description":"contact_<uuid> from flyra_list_conversations (or the raw uuid)."},"read":{"type":"boolean","description":"true marks the thread read, false marks it unread."}},"required":["contact_id","read"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_reply_to_thread":{"post":{"operationId":"flyra_reply_to_thread","summary":"Send a reply on an existing SMS thread","tags":["Texting"],"description":"Send a SMS or MMS to the phone number on an existing contact. Convenience wrapper around flyra_send_sms — accepts a contact_id and reuses its phone_e164. Same per-org 10/min cap, media_urls rules and cold-text credits as flyra_send_sms; a reply to someone who texted in the last 30 days is free. Returns message_id, thread_message_id (this text's id in flyra_get_thread) and from, the line it goes out from: the conversation's own line, or the one passed as from_line (an id from flyra_list_lines). On an org texting over iMessage it can go out another way; its flyra_get_thread row shows the line it used. status is queued when this replies; the carrier's sent, delivered or failed verdict lands on that row within a few minutes, so read flyra_get_thread before resending. Pass send_at to schedule it for later, as Schedule message in the Inbox does; flyra_cancel_scheduled_message stops it before it goes out.\n\nScope: `sms:send`.","x-required-scope":"sms:send","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"contact_id":{"type":"string"},"body":{"description":"Message text. Same limit as flyra_send_sms: at most 10 carrier segments (1530 plain characters, about 670 with any emoji); longer is refused here. Required unless media_urls is given.","type":"string","maxLength":1600},"media_urls":{"description":"Public https URLs to attach, at most 5. The carrier fetches these itself, so they must be reachable without a login.","maxItems":5,"type":"array","items":{"type":"string"}},"send_at":{"description":"Send it later, as Schedule message in the Flyra Inbox does: an ISO 8601 time with its offset, at least a minute and at most a year from now (e.g. 2026-10-30T09:00:00-07:00). Leave out to send now. At most 10 connector texts per business can be scheduled for any one minute, and a cancelled one still counts. The reply then carries scheduled_for, flyra_get_thread shows the text with scheduled_for set until it goes out, and flyra_cancel_scheduled_message stops it before then. A cold text's credit is spent when it is scheduled, and cancelling does not give it back.","type":"string"},"idempotency_key":{"description":"Optional: a key for this one text (8 to 128 characters). A retry with the same key is not texted or charged again.","type":"string","minLength":8,"maxLength":128},"from_line":{"description":"Optional. The line to send from: a phone_<uuid> id from flyra_list_lines. Must be a line that can text. Left out, a reply goes out from the line the conversation is already on, and a new conversation from the business's main number.","type":"string"}},"required":["contact_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_sms_credits":{"post":{"operationId":"flyra_get_sms_credits","summary":"Get the org's SMS blast credit balance","tags":["Texting"],"description":"Returns the org's remaining SMS blast credits. flyra_send_sms_blast and cold texts sent with flyra_send_sms spend them, so check before a list: if balance is low or zero, warn the user instead of attempting a send that will be refused. Auto-recharge and the spending limit are in flyra_get_sms_blast_settings.\n\nScope: `sms:read`.","x-required-scope":"sms:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_quick_replies":{"post":{"operationId":"flyra_list_quick_replies","summary":"List quick replies (saved text templates)","tags":["Texting"],"description":"Lists the quick replies the signed-in person sees under the Quick replies button in the Flyra Inbox text composer: the org's shared ones plus their own, most used first. Each has its name, body text, category, whether it is shared (is_global) and how often it was used. Picking one in the Inbox only puts its text in the message box; to text it, pass that text to flyra_send_sms. This tool sends nothing. For a person connected through OAuth whose role has Messages; an organization API key is refused, since a person's own quick replies belong to them.\n\nScope: `sms:read`.","x-required-scope":"sms:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_create_quick_reply":{"post":{"operationId":"flyra_create_quick_reply","summary":"Create a quick reply (saved text template)","tags":["Texting"],"description":"Saves a new quick reply for the signed-in person, as Create Quick Reply under the Quick replies button in the Flyra Inbox text composer does: a name, the message text and an optional category. It is the person's own (not shared with the team), the way the Inbox saves it. Message variables in Flyra texts use single braces, never double braces. This sends nothing. For a person connected through OAuth whose role has Messages; an organization API key is refused.\n\nScope: `sms:read`.","x-required-scope":"sms:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","pattern":"\\S","description":"Quick reply name shown in the Quick replies list."},"body":{"type":"string","pattern":"\\S","description":"The text that goes into the message box. Message variables use single braces."},"category":{"description":"Optional category label.","type":"string"}},"required":["name","body"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_quick_reply":{"post":{"operationId":"flyra_update_quick_reply","summary":"Edit a quick reply (saved text template)","tags":["Texting"],"description":"Changes a quick reply's name, message text or category, as editing one under the Quick replies button in the Flyra Inbox text composer does. A field left out keeps its value. The person who saved it can edit it; a shared one can also be edited by an admin. This sends nothing. For a person connected through OAuth whose role has Messages; an organization API key is refused.\n\nScope: `sms:read`.","x-required-scope":"sms:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"quick_reply_id":{"type":"string","description":"id from flyra_list_quick_replies."},"name":{"description":"New name.","type":"string","pattern":"\\S"},"body":{"description":"New message text. Message variables use single braces.","type":"string","pattern":"\\S"},"category":{"description":"New category, or null to clear it.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["quick_reply_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_delete_quick_reply":{"post":{"operationId":"flyra_delete_quick_reply","summary":"Delete a quick reply (saved text template)","tags":["Texting"],"description":"Deletes a quick reply for good, as the trash button on one under the Quick replies button in the Flyra Inbox text composer does. The person who saved it can delete it; a shared one can also be deleted by an admin. This sends nothing. Confirm with the user and pass confirm: true. For a person connected through OAuth whose role has Messages; an organization API key is refused.\n\nScope: `sms:read`. Destructive: it deletes or cancels.","x-required-scope":"sms:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"quick_reply_id":{"type":"string","description":"id from flyra_list_quick_replies."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the quick reply is deleted for good."}},"required":["quick_reply_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/search":{"post":{"operationId":"search","summary":"Search Flyra","tags":["Search"],"description":"Search across the org's customers, jobs, and recurring subscriptions in one call. Used by ChatGPT for retrieval; useful from Claude too when you have a fuzzy query and want to discover what kind of record matches.\n\nReturns up to 20 cards. Each card has: id (semantic, prefixed with cus_/job_/sub_), title (display name + one-line summary), url (deep link into app.flyra.io). Use fetch(id) to retrieve full detail for any returned id.\n\nRequires at-least-one read scope. Result rows are filtered to resource types the key can read — a customers:read-only key will get customer hits but no jobs.\n\nScope: any valid key.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"description":"Free-text query. Matched against names, emails, phones, addresses, titles."}},"required":["query"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/fetch":{"post":{"operationId":"fetch","summary":"Fetch Flyra record","tags":["Search"],"description":"Retrieve the full record for an id returned by search(). The id's semantic prefix (cus_, job_, sub_) determines which resource is fetched.\n\nReturns: { id, title, text, url, metadata }. text is a human-readable markdown summary; metadata carries the raw fields. Use the resource-specific tools (flyra_get_customer, flyra_get_job) when you need fine-grained control.\n\nScope: any valid key.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Semantic id from search() — e.g. cus_<uuid>, job_<uuid>, sub_<uuid>."}},"required":["id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_invoices":{"post":{"operationId":"flyra_list_invoices","summary":"List invoices","tags":["Invoices"],"description":"List invoices with optional filters. status=\"unpaid\" covers everything still owed (void invoices are not owed); \"paid\" and \"draft\" are the other two states that actually occur. Combine with customer_id to scope to one customer. Returns at most 50 rows per call, so NEVER sum the returned rows to answer \"how much is outstanding\" — read `outstanding.total_cents`, which is computed over every matching invoice, not just this page, and never counts draft or void invoices. salesperson_id is the Team filter on the Invoices list: the invoice's salesperson.\n\nScope: `invoices:read`.","x-required-scope":"invoices:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"unpaid = anything still owed (any status other than paid, draft or void). Filter by invoice state.","type":"string","enum":["unpaid","draft","sent","paid"]},"customer_id":{"description":"Customer UUID or semantic id.","type":"string"},"since":{"description":"ISO 8601 — only invoices created on or after.","type":"string"},"salesperson_id":{"description":"Only invoices whose salesperson is this team member (employee id from flyra_list_employees).","type":"string"},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":50},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_invoice":{"post":{"operationId":"flyra_get_invoice","summary":"Get invoice with line items","tags":["Invoices"],"description":"Full invoice detail including all line items.\n\nScope: `invoices:read`.","x-required-scope":"invoices:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"invoice_id":{"type":"string","description":"Invoice UUID or semantic id (inv_<uuid>)."}},"required":["invoice_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_discounts":{"post":{"operationId":"flyra_list_discounts","summary":"List saved discounts","tags":["Invoices"],"description":"List the business's saved discounts, the ones the Discount row on estimates and invoices offers, newest first. value is a percent (0 to 100) for a percent discount and DOLLARS for a flat one. Pass an id as saved_discount_id in discounts on flyra_create_estimate or flyra_create_invoice. Any member, signed in as a person.\n\nScope: `invoices:read`.","x-required-scope":"invoices:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"integer","exclusiveMinimum":0,"maximum":50},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_create_discount":{"post":{"operationId":"flyra_create_discount","summary":"Save a discount","tags":["Invoices"],"description":"Save a discount to the business's saved discounts, as \"Save to my discounts for next time\" on the Discount row does. It is not put on any document; apply it with saved_discount_id on flyra_create_estimate or flyra_create_invoice. value is a percent (10 means 10%, at most 100) for a percent discount and DOLLARS for a flat one. Any member, signed in as a person.\n\nScope: `invoices:write`.","x-required-scope":"invoices:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1},"type":{"type":"string","enum":["percent","flat"]},"value":{"type":"number","exclusiveMinimum":0,"description":"percent: 0 to 100. flat: dollars (25 means $25)."},"expiration_date":{"description":"YYYY-MM-DD; the discount cannot be applied after this day.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"minimum_purchase_cents":{"description":"The lines must come to at least this many cents for the discount to apply.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["title","type","value"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_create_invoice":{"post":{"operationId":"flyra_create_invoice","summary":"Create an invoice","tags":["Invoices"],"description":"Create a new invoice for a customer. Provide line items as { name, qty, unit_price_cents, description?, taxable? }. Subtotal/tax/total are computed server-side. Status starts as \"draft\". discounts adds discounts under the total, one off or saved (flyra_list_discounts), as the Discount row on New Invoice does; tax is then charged on the discounted total. With job_id the job must not be another customer's; the invoice takes the job's salesperson, and the job's discount when you pass no discounts, as the job page does.\n\nScope: `invoices:write`.","x-required-scope":"invoices:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string","description":"Customer UUID or semantic id."},"line_items":{"minItems":1,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1},"qty":{"type":"number","exclusiveMinimum":0},"unit_price_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"description":{"type":"string"},"taxable":{"type":"boolean"},"unit":{"description":"What qty is counted in, as the Unit picker on a line saves it: \"sq ft\" or \"linear ft\" (\"sqm\" or \"linear m\" for a business that measures in metres), or the business's own word, up to 16 characters. Leave it out for a plain count (Qty).","type":"string","minLength":1,"maxLength":16}},"required":["name","qty","unit_price_cents"]}},"due_date":{"description":"ISO date (YYYY-MM-DD).","type":"string"},"subject":{"type":"string"},"notes":{"type":"string"},"tax_rate":{"description":"Percent: 8.75 means 8.75%, not a decimal (0.0875 would be 0.0875%). Applied to the taxable lines.","type":"number","minimum":0,"maximum":100},"job_id":{"description":"Link this invoice to an existing job of this customer.","type":"string"},"discounts":{"description":"Discounts under the total, as the Discount row adds them: { type: \"percent\" or \"flat\", value, title? } for a one off discount (percent 0 to 100, flat in cents), or { saved_discount_id } for one from flyra_list_discounts. A saved discount that has expired, or whose minimum purchase the lines do not reach, is refused.","minItems":1,"maxItems":10,"type":"array","items":{"anyOf":[{"type":"object","properties":{"saved_discount_id":{"type":"string","description":"A saved discount id from flyra_list_discounts."}},"required":["saved_discount_id"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["percent","flat"]},"value":{"type":"number","exclusiveMinimum":0,"description":"percent: 10 means 10%. flat: cents."},"title":{"type":"string","minLength":1}},"required":["type","value"],"additionalProperties":false}]}}},"required":["customer_id","line_items"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_edit_invoice":{"post":{"operationId":"flyra_edit_invoice","summary":"Edit a draft invoice's line items, discounts and notes","tags":["Invoices"],"description":"Change the line items of a DRAFT invoice, or add a discount to it, as the line items card and the Add discount link on the invoice page do. Only a draft can be edited, as on the invoice page: a sent, paid or void invoice is refused.\n\nline_items replaces every line on the invoice (read them first with flyra_get_invoice and send the full list you want). Each line is { name, qty, unit_price_cents, description?, taxable? }; a negative price is a discount line. The new taxable lines are taxed at tax_rate (a percent), as flyra_create_invoice does. Leave tax_rate out to keep the tax the invoice's taxable lines already carry (one rate or a set of rates, e.g. state + city): that is refused, asking for tax_rate, when those lines carry different taxes or the invoice's own tax rate does not match them (often true of an invoice built from a job). The answer says which percent the new lines were taxed at (tax_rate_used).\n\nadd_discounts adds discounts under the total, as Add discount does: { name?, type: \"percent\" | \"flat\", value } where a percent is 0-100 and a flat amount is in cents. Discounts already on the invoice stay. This tool does not remove discounts.\n\nnotes replaces the invoice's internal note (the Notes card on the invoice page, which only the team sees and the invoice document does not print), saved with the same draft save. It cannot be set to empty here.\n\nThe subtotal, tax and total are re-computed when it saves; the answer has the new figures. Needs a signed-in Flyra user: an organization API key is refused. Any member who can see the invoice's customer may do this. Nothing is sent to the customer and nothing is charged.\n\nScope: `invoices:write`. Destructive: it deletes or cancels.","x-required-scope":"invoices:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"invoice_id":{"type":"string","description":"Invoice UUID or semantic id (inv_<uuid>)."},"line_items":{"description":"The full new list of lines. Replaces every line on the invoice.","minItems":1,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1},"qty":{"type":"number","exclusiveMinimum":0},"unit_price_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"description":{"type":"string"},"taxable":{"type":"boolean"}},"required":["name","qty","unit_price_cents"]}},"tax_rate":{"description":"Percent: 8.75 means 8.75%. Applied to the taxable lines in line_items. Only with line_items.","type":"number","minimum":0,"maximum":100},"add_discounts":{"minItems":1,"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["percent","flat"]},"value":{"type":"number","exclusiveMinimum":0,"description":"Percent 0-100, or a flat amount in cents."}},"required":["type","value"]}},"notes":{"description":"The new internal note. Replaces the current one.","type":"string","minLength":1},"confirm":{"type":"boolean","const":true,"description":"Must be true: this replaces the invoice's lines or changes what the customer owes."}},"required":["invoice_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_mark_invoice_paid":{"post":{"operationId":"flyra_mark_invoice_paid","summary":"Mark an invoice paid","tags":["Invoices"],"description":"Record an out-of-band payment on an invoice (cash, check, ACH transfer recorded manually). Does NOT charge a card — for Stripe charges use the invoice public link or the Flyra UI.\n\nWorks for partial payments and deposits: pass paid_amount_cents for an exact amount, or paid_percent (1 to 100) for a share of the remaining balance, e.g. paid_percent=50 for a 50% deposit. Not both. With neither, the whole remaining balance is recorded.\n\nStatus follows the Record Payment button in the app: a partial payment leaves the invoice open with a smaller balance (its job reads partially_paid), the payment that covers the total marks it paid, and every payment shows in Collected and on the job. Refused on a paid or void invoice, or for more than the remaining balance. The reply echoes amount_recorded_cents, the cents actually booked.\n\nSend a request_id (a UUID you generate) and reuse it when you retry a call that timed out: the payment is booked once and the retry answers with it (deduped=true), whatever the balance is by then. request_id_conflict means the key is already booked and names that payment; do not book again with a new key.\n\nTo record it with one of the business's own payment methods (Zelle, Venmo, E-Transfer...), the list the Record payment dialog offers, pass org_payment_method_code: the code of one of its active methods from flyra_list_payment_methods. It is checked against that list, and payment_method is then ignored.\n\nScope: `invoices:write`.","x-required-scope":"invoices:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"invoice_id":{"type":"string"},"payment_method":{"default":"cash","type":"string","enum":["cash","check","ach","other"]},"org_payment_method_code":{"description":"The code of one of the business's active payment methods (flyra_list_payment_methods, is_active true), e.g. \"zelle\". Used instead of payment_method.","type":"string"},"paid_amount_cents":{"description":"Exact amount in cents. Defaults to the remaining balance. Do not combine with paid_percent.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"paid_percent":{"description":"Percent of the remaining balance, 1 to 100 (50 = half). Rounded half up to whole cents. Do not combine with paid_amount_cents.","type":"number","minimum":1,"maximum":100},"paid_at":{"description":"ISO timestamp — defaults to now.","type":"string"},"request_id":{"description":"Optional idempotency key (UUID). Re-sending the same request_id returns the payment it booked instead of recording another.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["invoice_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_delete_invoice":{"post":{"operationId":"flyra_delete_invoice","summary":"Delete an invoice","tags":["Invoices"],"description":"Permanently delete an invoice and its line items. There is no undo — confirm with the user before calling.\n\nRefused once any money is attached: a paid or partially-paid invoice, or one with payment records linked to it, is accounting history. Those have to be unwound from Reports → Payments first. Also refused while a bank payment is still clearing on it (code bank_payment_clearing). Owners and Admins only, as in the app.\n\nNote: the invoice number is NOT reclaimed. Numbers come from a per-org counter that only moves forward, so deleting INV-1001 does not free it — the next invoice is still INV-1002.\n\nMirrors the Delete action in Reports → Invoices, guardrails included.\n\nScope: `invoices:write`. Destructive: it deletes or cancels.","x-required-scope":"invoices:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"invoice_id":{"type":"string","description":"Invoice UUID or semantic id (inv_<uuid>)."}},"required":["invoice_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_invoice_link":{"post":{"operationId":"flyra_get_invoice_link","summary":"Get the public invoice link","tags":["Invoices"],"description":"Return the public sharable URL for an invoice (customer-facing payment page). Use this to compose an SMS or email — e.g. flyra_send_sms with body \"Your invoice: <link>\".\n\nAlso returns pdf_link: the invoice as a PDF file, the same file the Download PDF button on the public invoice page serves (/api/public/invoices/<id>/pdf). Like public_link, anyone who has the link can open it.\n\nScope: `invoices:read`.","x-required-scope":"invoices:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"invoice_id":{"type":"string"}},"required":["invoice_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_send_invoice":{"post":{"operationId":"flyra_send_invoice","summary":"Mark an invoice as sent","tags":["Invoices"],"description":"Mark an invoice as \"sent\" (stamps sent_at=now, and a draft's status becomes \"sent\"; any other status, such as partly paid, is kept) and schedules the invoice follow-up automation if it is not paid.\n\nRefused for a void invoice and while a bank payment is clearing on it.\n\nThis does NOT send an SMS or email — use flyra_get_invoice_link + flyra_send_sms to actually deliver the payment link to the customer.\n\nUse this after you have confirmed the message was sent, or when you want to move the invoice out of \"draft\" status.\n\nScope: `invoices:write`.","x-required-scope":"invoices:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"invoice_id":{"type":"string","description":"Invoice UUID or semantic id (inv_<uuid>)."}},"required":["invoice_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_send_invoice_to_customer":{"post":{"operationId":"flyra_send_invoice_to_customer","summary":"Send an invoice to its customer","tags":["Invoices"],"description":"Send an invoice to its customer by email and/or text, as the Send Invoice button on the invoice page does: the customer receives the org's invoice message with the link to view and pay it, and the invoice is marked sent and starts its follow-up automation.\n\nIt goes only to the one customer on the invoice, at the email and mobile number on their customer record. channels defaults to every one of the two they have. message replaces the org's invoice message (the link is added if you leave it out); leave it out to send the org's own. attach_pdf attaches the invoice PDF to the email, off by default as on the page.\n\nRefused for a paid invoice (the page sends a receipt instead), a void or cancelled one, one with no customer, and while a bank payment is clearing on it (the page hides Send then). Each call sends again, so never call it twice for one send.\n\nNeeds a signed-in Flyra user (not an organization API key) who can open the invoice and its customer. Confirm with the user first and pass confirm: true.\n\nScope: `invoices:write`.","x-required-scope":"invoices:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"invoice_id":{"type":"string","description":"Invoice UUID or semantic id (inv_<uuid>)."},"confirm":{"type":"boolean","const":true,"description":"Pass true once the user has said to send it."},"channels":{"description":"\"email\", \"text\" or both. Default: each the customer has on file.","minItems":1,"type":"array","items":{"type":"string","enum":["email","text"]}},"message":{"description":"Your own message instead of the org's invoice message.","type":"string","minLength":1,"maxLength":1000},"attach_pdf":{"description":"Attach the invoice as a PDF to the email. Default false.","type":"boolean"}},"required":["invoice_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_invoice_split_payment":{"post":{"operationId":"flyra_set_invoice_split_payment","summary":"Split an invoice into two payments","tags":["Invoices"],"description":"The \"Split into two payments\" switch under the total on the invoice page (PATCH /api/v2/billing/invoices/<id>/partial-payment). split=true freezes the next payment the customer is asked for at half of what the invoice still owes; the rest comes on a second payment. split=false turns it off and clears that amount.\n\nCharges nothing and messages nobody: it changes the amount the invoice's pay page asks for. Asking for a split that is already on changes nothing and answers with it as it stands (unchanged: true). Refused on a paid or void invoice, while a bank payment is clearing (the page hides the switch then), and when each half would be under the minimum payment. Needs a signed-in Flyra user; any member who can open the invoice may use it, as on the page.\n\nScope: `invoices:write`.","x-required-scope":"invoices:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"invoice_id":{"type":"string","description":"Invoice UUID or semantic id (inv_<uuid>)."},"split":{"type":"boolean","description":"true to split into two payments, false to turn the split off."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed the change to what the customer is asked to pay."}},"required":["invoice_id","split","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_preview_payment_reminders":{"post":{"operationId":"flyra_preview_payment_reminders","summary":"Preview a bulk payment reminder send","tags":["Invoices"],"description":"Preview of Reports > Payments > Send payment reminders in the Flyra web app: what one press would do for the unpaid jobs, without sending anything. Returns the same counts the modal shows (customers texted, jobs texted, total due, how many get a reminder for an existing invoice, how many get a new invoice created and sent, and how many are skipped and why), the org's default reminder text, and each job's plan. Every reminder is a text message with a pay link. Pass expected_count and expected_fingerprint from here to flyra_send_payment_reminders. Needs a signed-in person with Reports access (Admins and Owners always).\n\nScope: `invoices:read`.","x-required-scope":"invoices:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"job_ids":{"description":"Job ids to remind (at most 5000). Leave out to use every row of Reports > Payments > Unpaid jobs, which is what the button sends.","minItems":1,"maxItems":5000,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"skip_recent":{"description":"The modal's \"skip recent\" checkbox (default true): skip a customer sent a payment link in the last 24 hours, and text a customer with several unpaid jobs once, for the oldest. false texts every job.","type":"boolean"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_send_payment_reminders":{"post":{"operationId":"flyra_send_payment_reminders","summary":"Text a payment reminder to every unpaid customer","tags":["Invoices"],"description":"Reports > Payments > Send payment reminders in the Flyra web app: TEXTS EVERY CUSTOMER in the list a pay link in one go. A job with a live invoice gets a reminder with that invoice's link; a job with no invoice gets one created from its line items, marked sent, and texted. Call flyra_preview_payment_reminders first, show the user the counts, and pass its expected_count and expected_fingerprint; if the live list of texted jobs no longer matches, nothing is sent. confirm must be true. message is the text customers receive (at most 1000 characters; [Invoice Link] marks the link, as in the preview's default_message). Runs in the background; returns the run, read progress with flyra_get_payment_reminder_run. One send at a time per business. Needs a signed-in person with Reports access (Admins and Owners always).\n\nScope: `invoices:write`.","x-required-scope":"invoices:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"job_ids":{"description":"Job ids to remind (at most 5000). Leave out to use every row of Reports > Payments > Unpaid jobs, which is what the button sends.","minItems":1,"maxItems":5000,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"skip_recent":{"description":"The modal's \"skip recent\" checkbox (default true): skip a customer sent a payment link in the last 24 hours, and text a customer with several unpaid jobs once, for the oldest. false texts every job.","type":"boolean"},"message":{"type":"string","minLength":1,"maxLength":1000,"description":"The text every listed customer receives."},"expected_count":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"expected_count from flyra_preview_payment_reminders (jobs that will be texted)."},"expected_fingerprint":{"type":"string","minLength":1,"maxLength":64,"description":"expected_fingerprint from flyra_preview_payment_reminders: which jobs will be texted."},"confirm":{"type":"boolean","const":true,"description":"Must be true: this texts every listed customer."}},"required":["message","expected_count","expected_fingerprint","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_payment_reminder_run":{"post":{"operationId":"flyra_get_payment_reminder_run","summary":"Read a bulk payment reminder send","tags":["Invoices"],"description":"Progress of a Send payment reminders run (Reports > Payments): status (queued, running, completed, failed) and counts reminded, invoiced, skipped and failed. Leave run_id out for the business's most recent run. include_outcomes adds each job's outcome. Needs a signed-in person with Reports access (Admins and Owners always).\n\nScope: `invoices:read`.","x-required-scope":"invoices:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"run_id":{"description":"The run id flyra_send_payment_reminders returned.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"include_outcomes":{"description":"Add the per-job outcome list (default false).","type":"boolean"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_estimates":{"post":{"operationId":"flyra_list_estimates","summary":"List estimates","tags":["Estimates"],"description":"List estimates with optional filters. Common statuses: draft, sent, viewed, accepted, declined, expired. Combine with customer_id to scope to one customer.\n\nlead_sources and team_member_ids are the Lead source and Team filters on the Estimates list. As there, someone who is not an Owner or Admin and has no Reports access gets only the estimates they wrote when they pass team_member_ids.\n\nScope: `estimates:read`.","x-required-scope":"estimates:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"Filter by estimate status.","type":"string"},"customer_id":{"type":"string"},"since":{"description":"ISO 8601 — only estimates created on or after.","type":"string"},"lead_sources":{"description":"Only estimates whose lead source is one of these names, matched exactly (names from flyra_list_lead_sources).","type":"array","items":{"type":"string"}},"team_member_ids":{"description":"Only estimates written by these team members (employee ids from flyra_list_employees).","type":"array","items":{"type":"string"}},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":50},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_estimate":{"post":{"operationId":"flyra_get_estimate","summary":"Get estimate with line items","tags":["Estimates"],"description":"Full estimate detail including all line items.\n\nScope: `estimates:read`.","x-required-scope":"estimates:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"estimate_id":{"type":"string","description":"Estimate UUID or semantic id (est_<uuid>)."}},"required":["estimate_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_create_estimate":{"post":{"operationId":"flyra_create_estimate","summary":"Create an estimate","tags":["Estimates"],"description":"Create an estimate (quote) for a customer or an unconverted lead. Line items same shape as flyra_create_invoice. Status starts as \"draft\". For choices the customer picks one of, pass options and name each line item's option; the total follows the pick. A plan's discount goes in options[].discounts.\n\nPut what the customer agrees to in terms (work date, when payment is due, any late fee). The customer sees terms as Terms and Conditions on the link and PDF unless the business hides terms. notes are internal and never shown to the customer. The business's default terms are not added here, so pass terms when the customer must agree to something.\n\nPass require_signature: true to make the customer sign before approving or paying a deposit. A deposit needs require_deposit: true unless the business's default deposit is on. A late fee in terms is words the customer agrees to; Flyra does not add or charge it. The reply's terms_shown is false when the business hides terms, so a signature agrees to nothing in writing.\n\nScope: `estimates:write`.","x-required-scope":"estimates:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"description":"The customer this estimate is for. Pass this or lead_id (or both).","type":"string"},"lead_id":{"description":"The lead this estimate is for (from flyra_list_leads). The estimate is linked to the lead the way the app does: it appears on the lead, and a lead on a standard stage moves to Estimate Sent. A lead already converted to a customer links to that customer too. Needs the Leads permission as well as Estimates.","type":"string"},"line_items":{"minItems":1,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1},"qty":{"type":"number","exclusiveMinimum":0},"unit_price_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"description":{"type":"string"},"taxable":{"type":"boolean"},"option":{"description":"With options: the name of the option this line belongs to.","type":"string"},"unit":{"description":"What qty is counted in, as the Unit picker on a line saves it: \"sq ft\" or \"linear ft\" (\"sqm\" or \"linear m\" for a business that measures in metres), or the business's own word, up to 16 characters. Leave it out for a plain count (Qty).","type":"string","minLength":1,"maxLength":16},"is_optional":{"description":"The line editor's Optional switch: the customer can add or drop this line themselves on their estimate. Left out, the line is not optional.","type":"boolean"},"default_selected":{"description":"With is_optional: Pre-checked for customer. true (the default) counts the line until the customer drops it; false leaves it out of the total until the customer adds it.","type":"boolean"}},"required":["name","qty","unit_price_cents"]}},"options":{"description":"Choices on one estimate, of which the customer picks one, for example one time, a twice a year plan and a quarterly plan. Each line item then names its option in \"option\"; an option costs only its own lines, never the others added in. Mark one recommended: true (else the first is); the estimate total shows that option until the customer picks. A plan option becomes a subscription when the customer accepts it, and its lines are what each billing charges (per visit, unless the template bills by the month or another calendar period).","minItems":1,"maxItems":6,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"recommended":{"type":"boolean"},"plan_template_id":{"description":"Makes this a plan option: a template id from flyra_list_subscription_templates. Needs a connection signed in as a person, not an API key.","type":"string"},"visits_per_year":{"description":"Plan options only. Default: the template's.","type":"integer","exclusiveMinimum":0,"maximum":365},"frequency":{"description":"Plan options only: how often the customer is billed. Default: the template's.","type":"string","enum":["weekly","biweekly","monthly","bi_monthly","quarterly","tri_annual","six_months","yearly"]},"deposit_percent":{"description":"Plan options only: the share of the first visit the customer pays when they sign (50 = half). 0 = none. Default: the business's default deposit. Only plans billed per visit take one.","type":"number","minimum":0,"maximum":100},"discounts":{"description":"Plan options only: the plan discount, which comes off every visit and shows under the plan's full price. Discounts under the total, as the Discount row adds them: { type: \"percent\" or \"flat\", value, title? } for a one off discount (percent 0 to 100, flat in cents), or { saved_discount_id } for one from flyra_list_discounts. A saved discount that has expired, or whose minimum purchase the lines do not reach, is refused. A negative line on a plan option is refused; use this instead.","minItems":1,"maxItems":10,"type":"array","items":{"anyOf":[{"type":"object","properties":{"saved_discount_id":{"type":"string","description":"A saved discount id from flyra_list_discounts."}},"required":["saved_discount_id"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["percent","flat"]},"value":{"type":"number","exclusiveMinimum":0,"description":"percent: 10 means 10%. flat: cents."},"title":{"type":"string","minLength":1}},"required":["type","value"],"additionalProperties":false}]}}},"required":["name"]}},"valid_until":{"description":"ISO date (YYYY-MM-DD).","type":"string"},"subject":{"type":"string"},"notes":{"type":"string"},"terms":{"type":"string"},"tax_rate":{"description":"Percent: 8.25 means 8.25%, not a decimal (0.0825 would be 0.0825%). Left off or 0, the business's own tax rates from Settings apply. To quote with no tax, set taxable: false on the lines.","type":"number","minimum":0,"maximum":100},"require_deposit":{"description":"Omit to inherit the org's configured deposit default; false opts out.","type":"boolean"},"deposit_type":{"type":"string","enum":["percent","fixed"]},"deposit_value":{"description":"Percent (e.g. 10) or cents for a fixed deposit.","type":"number","exclusiveMinimum":0},"require_signature":{"description":"When true the customer must draw a signature before approving the estimate or paying its deposit. Omit to leave the estimate unsigned.","type":"boolean"},"lead_source":{"description":"The Lead source field on New Estimate: where this work came from (a name from flyra_list_lead_sources).","type":"string","minLength":1},"salesperson_ids":{"description":"The Salesperson field on New Estimate: employee ids from flyra_list_employees. The first is the main salesperson.","minItems":1,"type":"array","items":{"type":"string"}},"discounts":{"description":"Discounts under the total, as the Discount row adds them: { type: \"percent\" or \"flat\", value, title? } for a one off discount (percent 0 to 100, flat in cents), or { saved_discount_id } for one from flyra_list_discounts. A saved discount that has expired, or whose minimum purchase the lines do not reach, is refused. Tax is charged on the discounted total. Not with options: a plan option's discount goes in options[].discounts, and a one time option's is added afterwards with flyra_update_estimate.","minItems":1,"maxItems":10,"type":"array","items":{"anyOf":[{"type":"object","properties":{"saved_discount_id":{"type":"string","description":"A saved discount id from flyra_list_discounts."}},"required":["saved_discount_id"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["percent","flat"]},"value":{"type":"number","exclusiveMinimum":0,"description":"percent: 10 means 10%. flat: cents."},"title":{"type":"string","minLength":1}},"required":["type","value"],"additionalProperties":false}]}}},"required":["line_items"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_convert_estimate_to_invoice":{"post":{"operationId":"flyra_convert_estimate_to_invoice","summary":"Convert an estimate to an invoice","tags":["Estimates"],"description":"Promote an accepted estimate to an invoice. Copies customer, line items, subject. The new invoice starts as \"draft\". Returns both ids so the agent can hand the invoice link to the customer.\n\nScope: `estimates:write`.","x-required-scope":"estimates:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"estimate_id":{"type":"string"}},"required":["estimate_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_approve_estimate":{"post":{"operationId":"flyra_approve_estimate","summary":"Approve an estimate and create its job or plan","tags":["Estimates"],"description":"Approve an estimate on the customer's behalf, after they said yes by phone or in person, as the Approve & Schedule Job button on the estimate page does. Admins only. Needs a signed-in Flyra user.\n\nSame as the button: the estimate is marked accepted. With options, the option the customer chose is kept and the other options' lines come off the estimate. The job is created from the estimate's lines, with no time yet (a quote with no customer yet makes the customer first, and its lead is marked converted). If a job was already made for this estimate it is used instead, and while that job is still scheduled its lines are brought in line with the estimate. A deposit already paid on the estimate is linked to that job; nothing is charged. The estimate's follow-up messages stop, the \"estimate accepted\" email is queued to the business's admins, and its lead moves to Estimate Accepted when the lead's pipeline has that stage.\n\nAn option that is a plan becomes a subscription instead of a job, as on the page: the plan is made from the option (its price, visits, billing and agreement) as the estimate's rep, and the customer's saved card is linked to it if they have one. Nothing is charged now. A plan that needs no card, no signature and no deposit is active at once; any other plan waits as pending until the customer finishes on the plan's page, and Flyra does not send them that page (flyra_get_subscription_link gives it).\n\nMessages to this customer only, by text or email: it starts the business's \"Estimate accepted\" automations (for an estimate on a lead that includes the estimate accepted thank-you message, if they have it on). For a plan, when it activates (at once, or later) the business's Subscription Confirmation automation sends its \"you're all set\" text or email, and a plan with visit dates that is active at once also emails the customer its visit schedule unless that automation sends instead. The business's admins are emailed. Tell the user who will be messaged before you approve.\n\nAlready approved: answers with its job or plan (making it if it is missing) and does not start the automations again. Refused: a declined estimate.\n\nTo put the job on the calendar afterwards, call flyra_update_job with scheduled_start and scheduled_end.\n\nScope: `estimates:write`. Destructive: it deletes or cancels.","x-required-scope":"estimates:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"estimate_id":{"type":"string","description":"Estimate UUID or semantic id (est_<uuid>)."},"option_id":{"description":"Estimates with options: the id of the option the customer chose (options[].id from flyra_get_estimate). Needed when there is more than one option.","type":"string"},"confirm":{"type":"boolean","const":true,"description":"Must be true: approving can text or email this customer (automations, and a plan's \"you're all set\")."}},"required":["estimate_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_decline_estimate":{"post":{"operationId":"flyra_decline_estimate","summary":"Mark an estimate declined","tags":["Estimates"],"description":"Mark an estimate declined on the customer's behalf, after they said no by phone or in person, as the Decline button on the estimate's customer page does. Admins only. Needs a signed-in Flyra user.\n\nOnly an open estimate (draft, sent or expired) can be declined; an accepted one is refused. After the decline, as on the customer page, the estimate's follow-up messages are stopped and, for an estimate on a lead, the lead's estimate is marked declined and a line is added to the lead's timeline; if one of those steps fails it is logged for the team and the decline still stands. Nothing is sent to the customer and no automation is started. A declined estimate can no longer be approved (flyra_approve_estimate refuses it).\n\nAlready declined: answers already_declined and changes nothing.\n\nScope: `estimates:write`. Destructive: it deletes or cancels.","x-required-scope":"estimates:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"estimate_id":{"type":"string","description":"Estimate UUID or semantic id (est_<uuid>)."},"confirm":{"type":"boolean","const":true,"description":"Must be true: a declined estimate can no longer be approved, and its follow-up messages stop."}},"required":["estimate_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_send_estimate":{"post":{"operationId":"flyra_send_estimate","summary":"Mark an estimate as sent","tags":["Estimates"],"description":"Mark an estimate as \"sent\" (stamps sent_at=now, status→\"sent\" if still draft) and starts the org's \"Estimate sent\" automations, such as the follow-up reminders. The org's own estimate text is not sent: you deliver the link.\n\nThis does NOT send an SMS or email — use flyra_get_estimate_link + flyra_send_sms to actually deliver the estimate link to the customer.\n\nA map pin is not updated by this: for a door-knock lead, call flyra_update_map_pin with status \"quote\" afterwards so the map shows the door was quoted.\n\nUse this after you have confirmed the message was sent, or when you want to move the estimate out of \"draft\" status.\n\nScope: `estimates:write`.","x-required-scope":"estimates:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"estimate_id":{"type":"string","description":"Estimate UUID or semantic id (est_<uuid>)."}},"required":["estimate_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_estimate":{"post":{"operationId":"flyra_update_estimate","summary":"Edit an estimate","tags":["Estimates"],"description":"Change an estimate after it is made, as the Edit Estimate form saves it: line items, options, discounts, terms, notes, valid-until date, deposit rule, lead source and salespeople. Only what you pass changes; Flyra works out the totals. Admins only, signed in as a person (not an API key). Only a draft or sent estimate can be edited, as on the web estimate page.\n\nline_items replaces the whole list: pass every line the estimate should keep. Keep a line by passing its id from flyra_get_estimate; a line without an id is new. discounts replaces every discount; [] removes them. This does not change the status, and nothing is sent to the customer.\n\noptions replaces the choices: pass every option to keep with its id from flyra_get_estimate, a new one without an id, and line_items with each line naming its option. An option left out is removed with its lines; [] makes it one quote. A plan option's discount goes in options[].discounts; [] removes it. Send options and line_items without other fields.\n\nScope: `estimates:write`. Destructive: it deletes or cancels.","x-required-scope":"estimates:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"estimate_id":{"type":"string","description":"Estimate UUID or semantic id (est_<uuid>)."},"confirm":{"type":"boolean","const":true,"description":"Pass true once the user has agreed to the change: it changes what the customer is quoted."},"line_items":{"minItems":1,"type":"array","items":{"type":"object","properties":{"id":{"description":"The line's id from flyra_get_estimate, to keep that line. Omit for a new line.","type":"string"},"name":{"type":"string","minLength":1},"qty":{"type":"number","minimum":1},"unit_price_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"A negative price is a discount line."},"description":{"type":"string"},"taxable":{"type":"boolean"},"option":{"description":"With options: the name of the option this line belongs to.","type":"string"},"is_optional":{"description":"The line editor's Optional switch: the customer can add or drop this line themselves on their estimate. Left out, the line is not optional; a kept line left without it keeps its own.","type":"boolean"},"default_selected":{"description":"With is_optional: Pre-checked for customer. true (the default) counts the line until the customer drops it; false leaves it out of the total until the customer adds it.","type":"boolean"}},"required":["name","qty","unit_price_cents"]}},"options":{"description":"Every choice the estimate should offer, of which the customer picks one. Pass with line_items, each line naming its option in \"option\". An option left out is removed with its lines; [] makes the estimate one quote. Mark one recommended: true (else the first is). A new option is one time; add a plan option with flyra_create_estimate or in the Flyra app.","maxItems":6,"type":"array","items":{"type":"object","properties":{"id":{"description":"The option's id from flyra_get_estimate, to keep that option (a plan option keeps its plan). Omit for a new one time option.","type":"string"},"name":{"type":"string","minLength":1,"maxLength":80},"recommended":{"type":"boolean"},"discounts":{"description":"A kept plan option only: its plan discount, which comes off every visit. Replaces the plan's discounts; [] removes them; left out, they stay. Discounts under the total, as the Discount row adds them: { type: \"percent\" or \"flat\", value, title? } for a one off discount (percent 0 to 100, flat in cents), or { saved_discount_id } for one from flyra_list_discounts. A saved discount that has expired, or whose minimum purchase the lines do not reach, is refused.","maxItems":10,"type":"array","items":{"anyOf":[{"type":"object","properties":{"saved_discount_id":{"type":"string","description":"A saved discount id from flyra_list_discounts."}},"required":["saved_discount_id"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["percent","flat"]},"value":{"type":"number","exclusiveMinimum":0,"description":"percent: 10 means 10%. flat: cents."},"title":{"type":"string","minLength":1}},"required":["type","value"],"additionalProperties":false}]}}},"required":["name"],"additionalProperties":false}},"discounts":{"description":"The Add discount rows. Replaces every discount on the estimate; [] removes them.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["percent","flat"]},"value":{"type":"number","exclusiveMinimum":0,"description":"percent: 10 means 10%. flat: cents."},"title":{"type":"string","minLength":1}},"required":["type","value"]}},"terms":{"anyOf":[{"type":"string"},{"type":"null"}]},"notes":{"description":"Internal; the customer never sees notes.","anyOf":[{"type":"string"},{"type":"null"}]},"expires_at":{"description":"Valid until: an ISO date, or null to clear it.","anyOf":[{"type":"string"},{"type":"null"}]},"require_deposit":{"description":"false turns the deposit off; true needs deposit_type and deposit_value.","type":"boolean"},"deposit_type":{"type":"string","enum":["percent","fixed"]},"deposit_value":{"description":"Percent (e.g. 10) or cents for a fixed deposit.","type":"number","exclusiveMinimum":0},"lead_source":{"description":"A name from flyra_list_lead_sources, or null to clear it.","anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"salesperson_ids":{"description":"Employee ids from flyra_list_employees; the first is the main salesperson. [] clears them.","type":"array","items":{"type":"string"}}},"required":["estimate_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_send_estimate_to_customer":{"post":{"operationId":"flyra_send_estimate_to_customer","summary":"Send an estimate to its customer","tags":["Estimates"],"description":"Send an estimate to its customer by email and/or text, as the Send Estimate button on the estimate page does: the customer receives the org's estimate message with the link to view and accept it, and the estimate is marked sent and starts its \"Estimate sent\" automations.\n\nIt goes only to the one customer on the estimate, at the email and mobile number on their customer record. An estimate that is only on a lead (no customer yet) goes only to that one lead, at the email and mobile number on the estimate, as the Send box shows them; the lead must be one you can open. channels defaults to every one of the two they have. message replaces the org's estimate message (the link is added if you leave it out); leave it out to send the org's own. require_signature is the Send box's \"Require signature\" option, on by default as there.\n\nOnly a draft or sent estimate can be sent here; an accepted or declined one is refused, as is one with neither a customer nor a lead. Each call sends again, so never call it twice for one send.\n\nNeeds a signed-in Flyra user (not an organization API key). Confirm with the user first and pass confirm: true.\n\nScope: `estimates:write`.","x-required-scope":"estimates:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"estimate_id":{"type":"string","description":"Estimate UUID or semantic id (est_<uuid>)."},"confirm":{"type":"boolean","const":true,"description":"Pass true once the user has said to send it."},"channels":{"description":"\"email\", \"text\" or both. Default: each the customer has on file.","minItems":1,"type":"array","items":{"type":"string","enum":["email","text"]}},"message":{"description":"Your own message instead of the org's estimate message.","type":"string","minLength":1,"maxLength":1000},"attach_pdf":{"description":"Attach the estimate as a PDF to the email. Default false.","type":"boolean"},"require_signature":{"description":"Ask the customer to sign when they accept. Default true.","type":"boolean"}},"required":["estimate_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_delete_estimate":{"post":{"operationId":"flyra_delete_estimate","summary":"Delete an estimate","tags":["Estimates"],"description":"Permanently delete an estimate and its line items. There is no undo — confirm with the user before calling.\n\nAccepted estimates are refused: they are the record of a won deal and the basis of win-rate reporting. Decline the estimate first if it genuinely needs to go.\n\nMirrors the Delete action in Reports → Estimates, guardrail included. Owners and Admins only, as in the app.\n\nScope: `estimates:write`. Destructive: it deletes or cancels.","x-required-scope":"estimates:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"estimate_id":{"type":"string","description":"Estimate UUID or semantic id (est_<uuid>)."}},"required":["estimate_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_estimate_link":{"post":{"operationId":"flyra_get_estimate_link","summary":"Get the public estimate link","tags":["Estimates"],"description":"Return the public sharable URL for an estimate. Useful for composing an SMS or email.\n\nAlso returns pdf_link: the estimate as a PDF file, the same file the Download PDF button on the public estimate page serves (/api/public/estimates/<id>/pdf). Like public_link, anyone who has the link can open it.\n\nScope: `estimates:read`.","x-required-scope":"estimates:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"estimate_id":{"type":"string"}},"required":["estimate_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_schedule":{"post":{"operationId":"flyra_get_schedule","summary":"Get the schedule for a day or a date range","tags":["Jobs"],"description":"List the jobs on the calendar for one date, by start time, or pass `start_date` and `end_date` instead of `date` for a week or a month, as the Schedule's day, week and month views list them: every job whose start-to-end time touches the day or range, so a job that started before it and runs into it is included. Days are the org's own calendar days, in its timezone (the answer's `timezone`). A range is at most 62 days (the widest window the Schedule's month view loads). Optionally filter by employee, or with the Schedule's Filter menu: payment, job_type, salesperson_ids, dispatched_employee_ids (each list matches any of its values), city and zip (text the job's city or ZIP code contains, any case). A signed-in employee sees only the jobs their Schedule shows them. Useful for answering \"what does Tuesday look like?\", \"what is on next week?\" or \"is Caleb busy on Friday?\".\n\nScope: `jobs:read`.","x-required-scope":"jobs:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"description":"ISO date YYYY-MM-DD: one day. Leave out when passing start_date and end_date.","type":"string"},"start_date":{"description":"Range start, ISO date YYYY-MM-DD (the org's day, inclusive). Use with end_date instead of date.","type":"string"},"end_date":{"description":"Range end, ISO date YYYY-MM-DD (the org's day, inclusive). The range covers at most 62 days.","type":"string"},"employee_id":{"description":"Optional — filter to jobs dispatched to this employee.","type":"string"},"payment":{"description":"The Payment filter: \"unpaid\" is completed but unpaid, \"paid\" is paid in full, or completed with nothing due (a $0 job, never collected). A partly paid job matches neither. Both or neither: no filter.","type":"array","items":{"type":"string","enum":["unpaid","paid"]}},"job_type":{"description":"The Subscription / One-time filter: a visit of a subscription, or not. Both or neither: no filter.","type":"array","items":{"type":"string","enum":["subscription","oneTime"]}},"salesperson_ids":{"description":"The Salesperson filter: jobs any of these employees sold; \"unassigned\" for jobs with no salesperson.","type":"array","items":{"type":"string"}},"dispatched_employee_ids":{"description":"The Dispatched employee filter: jobs any of these employees is on (a published route's stop names the technician, as on the Schedule); \"unassigned\" for jobs with nobody dispatched.","type":"array","items":{"type":"string"}},"city":{"description":"The City filter: jobs whose city contains this text, any case. The city is the job's property's, else the customer's, as on the Schedule cards.","type":"string","maxLength":200},"zip":{"description":"The ZIP code filter: jobs whose ZIP code contains this text, any case. Same address as city.","type":"string","maxLength":200}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_check_availability":{"post":{"operationId":"flyra_check_availability","summary":"Check whether an employee is free during a window","tags":["Jobs"],"description":"Returns whether an employee has any jobs scheduled that overlap a given time window. Useful before flyra_create_job to avoid double-booking. Does NOT enforce booking — the agent decides.\n\nScope: `jobs:read`.","x-required-scope":"jobs:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"string"},"start":{"type":"string","description":"ISO timestamp."},"duration_minutes":{"type":"integer","exclusiveMinimum":0,"maximum":1440,"description":"Window length in minutes."}},"required":["employee_id","start","duration_minutes"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_find_open_slot":{"post":{"operationId":"flyra_find_open_slot","summary":"Find the next open scheduling slot","tags":["Jobs"],"description":"Scan the calendar starting from `start_after` and return the first N windows of `duration_minutes` where the given employee has no overlapping job.\n\nHonors the org's business hours in the org timezone, day by day (Settings hours by day, else its opening and closing times, else 8a–5p): slots only land inside them, and days the org does not work are skipped (its business days, Monday to Friday when it never set them). skip_weekends=true also skips Saturdays and Sundays; skip_weekends=false opens every day for an org that never set its business days.\n\nUse this BEFORE flyra_create_job when the user says \"find me a slot\" rather than naming an exact time.\n\nScope: `jobs:read`.","x-required-scope":"jobs:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"string","description":"Employee whose calendar to scan."},"duration_minutes":{"type":"integer","exclusiveMinimum":0,"maximum":720,"description":"How long each slot must be."},"start_after":{"description":"ISO timestamp — defaults to now.","type":"string"},"slots":{"description":"How many open windows to return (default 5).","type":"integer","exclusiveMinimum":0,"maximum":20},"skip_weekends":{"description":"true also skips Saturdays and Sundays; false opens weekends for an org that never set its business days. Left out, the org's business days decide.","type":"boolean"}},"required":["employee_id","duration_minutes"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_employee_availability":{"post":{"operationId":"flyra_get_employee_availability","summary":"Get employee working-hours (availability)","tags":["Employees"],"description":"Returns the working hours employees have set for themselves (the \"My Availability\" / shift hours, NOT booked jobs). Pass `date` for a single day, or `from`+`to` for a range. Optionally filter to one `employee_id`. Hours are plain local wall-clock hours (e.g. 8 = 8 AM, 17 = 5 PM), not timezone-adjusted timestamps. A signed-in person who is not an Owner, Admin or Manager reads only their own hours, as on Employee Scheduling.\n\nScope: `employees:read`.","x-required-scope":"employees:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"description":"Single day, ISO date YYYY-MM-DD.","type":"string"},"from":{"description":"Range start, ISO date YYYY-MM-DD (use with `to`).","type":"string"},"to":{"description":"Range end, ISO date YYYY-MM-DD (use with `from`).","type":"string"},"employee_id":{"description":"Optional — filter to a single employee (semantic id or raw UUID).","type":"string"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_employee_availability":{"post":{"operationId":"flyra_set_employee_availability","summary":"Set employee working-hours (availability)","tags":["Employees"],"description":"Set the working hours for one employee on one or more dates. Each entry upserts that day's hours (replacing only that employee+date if it already exists). Hours are local wall-clock integers: start_hour 0–23, end_hour 1–24, start < end (e.g. 8 → 17 means 8 AM–5 PM). Only the dates you pass are affected — other days and other employees are left untouched. A signed-in person who is not an Owner, Admin or Manager can set only their own hours, as on Employee Scheduling. For hours to the minute, a break or a day off use flyra_save_employee_hours; for saved shifts, flyra_list_hour_presets.\n\nScope: `employees:write`.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"string","description":"Employee whose hours to set (semantic id or raw UUID)."},"entries":{"minItems":1,"maxItems":60,"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"ISO date YYYY-MM-DD."},"start_hour":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Start hour, 0–23 (8 = 8 AM)."},"end_hour":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"End hour, 1–24 (17 = 5 PM, 24 = midnight)."}},"required":["date","start_hour","end_hour"]},"description":"One entry per date. Up to 60 dates per call."}},"required":["employee_id","entries"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_save_employee_hours":{"post":{"operationId":"flyra_save_employee_hours","summary":"Save employee working hours and days off (Employee Scheduling)","tags":["Employees"],"description":"The Save button on Schedule > Employee Scheduling (and My Availability). Each edit sets one employee's day: `kind: \"hours\"` with exact minutes from midnight (`start_minute` 0-1439, `end_minute` 1-1440, start before end; 480 = 8:00 AM, 1020 = 5:00 PM) and an optional break strictly inside them (`break_start`, `break_end`); `kind: \"off\"` for a day off with an optional `note` (up to 200 characters); `kind: \"clear\"` to remove what that day held. Only the days you pass change, all in one transaction: every edit lands or none does. One edit per employee and date. Admins, owners and managers can set anyone in the business; everyone else only their own days. Needs a signed-in user, not an organization API key. Through the connector this needs a role with Manage Team (Owner, Admin, or a role given it); anyone else saves hours on the Employee Scheduling screen. It overwrites those days, so confirm the days and hours with the user first. Returns how many days were saved.\n\nScope: `employees:write`. Destructive: it deletes or cancels.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"edits":{"minItems":1,"type":"array","items":{"type":"object","properties":{"employee_id":{"type":"string","description":"Employee (semantic id or raw UUID)."},"date":{"type":"string","description":"The day, YYYY-MM-DD."},"kind":{"type":"string","enum":["hours","off","clear"],"description":"hours = working hours, off = day off, clear = remove the day."},"start_minute":{"description":"kind \"hours\": start, minutes from midnight (480 = 8:00 AM).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"end_minute":{"description":"kind \"hours\": end, minutes from midnight (1020 = 5:00 PM, 1440 = midnight).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"break_start":{"description":"kind \"hours\": optional break start, minutes from midnight.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"break_end":{"description":"kind \"hours\": optional break end, minutes from midnight.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"note":{"description":"kind \"off\": optional note, up to 200 characters.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["employee_id","date","kind"]},"description":"One edit per employee and date."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed these days and hours."}},"required":["edits","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_repeat_employee_week":{"post":{"operationId":"flyra_repeat_employee_week","summary":"Repeat or copy a week of employee working hours (Employee Scheduling)","tags":["Employees"],"description":"The Repeat button on Schedule > Employee Scheduling. Copies the working hours saved in the 7 days starting `week_start` onto each of the next `weeks` weeks (1 to 52) for the employees given, day by day, in one transaction. A day with no hours in that week clears the same day in the later weeks. Days off are not copied, and a day off already set in a later week is kept. As on the screen, an employee with no working hours in that week is left out (listed in `skipped_employee_ids`), so their later weeks are not cleared. To copy last week onto this week (the Copy last week button), pass last week's first day (the screen's weeks start on Monday) and `weeks: 1`. Admins, owners and managers can do this for anyone in the business; everyone else only for themselves. Needs a signed-in user, not an organization API key. Through the connector this needs a role with Manage Team (Owner, Admin, or a role given it); anyone else repeats weeks on the Employee Scheduling screen. It overwrites the hours in those later weeks, so confirm the week, the number of weeks and the people with the user first. Returns the days written and the days off kept.\n\nScope: `employees:write`. Destructive: it deletes or cancels.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"week_start":{"type":"string","description":"First day of the week to copy, YYYY-MM-DD."},"weeks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many following weeks get these hours, 1 to 52."},"employee_ids":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Employees whose week to repeat (semantic ids or raw UUIDs), up to 100."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed the week, the number of weeks and the people."}},"required":["week_start","weeks","employee_ids","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_hour_presets":{"post":{"operationId":"flyra_list_hour_presets","summary":"List my working hour presets (Employee Scheduling)","tags":["Employees"],"description":"The presets in the hours editor on Schedule > Employee Scheduling: the signed in person's own saved shifts (up to 8), each with start_minute and end_minute (minutes from midnight, 480 = 8:00 AM) and an optional break. Use one as the hours in flyra_save_employee_hours. Presets belong to the person, not the business. Needs a signed in user. Read only.\n\nScope: `employees:read`.","x-required-scope":"employees:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_create_hour_preset":{"post":{"operationId":"flyra_create_hour_preset","summary":"Save a working hour preset (Employee Scheduling)","tags":["Employees"],"description":"Create preset in the hours editor on Schedule > Employee Scheduling: saves a shift to the signed in person's own presets. start_minute and end_minute are minutes from midnight (480 = 8:00 AM, 1020 = 5:00 PM, end after start); a break, if any, starts and ends inside them. Up to 8 presets; the same shift twice is refused. Sets nobody's hours. Needs a signed in user.\n\nScope: `employees:write`.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"start_minute":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Start, minutes from midnight (480 = 8:00 AM)."},"end_minute":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"End, minutes from midnight (1020 = 5:00 PM, 1440 = midnight)."},"break_start":{"description":"Optional break start, minutes from midnight.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"break_end":{"description":"Optional break end, minutes from midnight.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["start_minute","end_minute"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_delete_hour_preset":{"post":{"operationId":"flyra_delete_hour_preset","summary":"Delete a working hour preset (Employee Scheduling)","tags":["Employees"],"description":"Deletes one of the signed in person's own hour presets (an id from flyra_list_hour_presets), as removing it in the hours editor does. Hours already saved with it stay. Cannot be undone. Needs a signed in user.\n\nScope: `employees:write`. Destructive: it deletes or cancels.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"preset_id":{"type":"string","description":"A preset id from flyra_list_hour_presets."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed deleting this preset."}},"required":["preset_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_metrics":{"post":{"operationId":"flyra_metrics","summary":"Aggregated business metrics","tags":["Jobs"],"description":"Business figures. metric:\n- revenue: completed-job $ in range; mrr: monthly recurring revenue from active plans\n- jobs_by_status, customer_count, employee_count, subscription_count\n- top_customers / top_services: top N by completed-job revenue in range\nReports pages (Owner, Admin or Reports access):\n- retention: Reports > Retention for plans sold in range: churn, ARR, visit-to-visit retention, by rep/tech/plan, top at-risk plans\n- customers_report: Reports > Customers: totals, new customers, CLV growth, top N by CLV\n- jobs_by_lead_source, line_item_breakdown: the Jobs report charts (by job start date)\n- estimates_report: Reports > Estimates for estimates created in range: win rate (accepted of answered), quoted and open value, won revenue from the jobs they became, the sent > opened > answered > won funnel, estimates by lead source\n- map_report: Reports > Map for pins dropped in range: the page's cards (pins, sales, conversion, average per day, quotes, quote rate, revisit and no-answer rates), pins by status, each team member's pins by status, objections\n- reviews_report: Reports > Reviews summary for reviews left in range: count, average stars, 5-star reviews, count per star, how many have a comment\n- expenses_report: Reports > Expenses profit summary for the range: revenue (the price of every job scheduled to start in range, cancelled jobs included, as the page counts it), total expenses, net profit (revenue minus expenses), and spend per category; here a bare YYYY-MM-DD is the company's whole day in its timezone\n`range: { start, end }` (ISO) is required for customers_report, jobs_by_lead_source, line_item_breakdown and the four reports above, otherwise all time. `limit` sizes the lists (default 10).\n\nScope: `jobs:read`.","x-required-scope":"jobs:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"metric":{"type":"string","enum":["revenue","mrr","jobs_by_status","customer_count","employee_count","subscription_count","top_customers","top_services","retention","customers_report","jobs_by_lead_source","line_item_breakdown","estimates_report","map_report","reviews_report","expenses_report"]},"range":{"type":"object","properties":{"start":{"type":"string","description":"ISO 8601 timestamp, inclusive, with the org's UTC offset (flyra_get_org_settings has its timezone), e.g. 2026-10-31T23:59:59-07:00. A date alone is midnight UTC, so an end of 2026-10-31 leaves out Oct 31."},"end":{"type":"string","description":"ISO 8601 timestamp, inclusive, with the org's UTC offset (flyra_get_org_settings has its timezone), e.g. 2026-10-31T23:59:59-07:00. A date alone is midnight UTC, so an end of 2026-10-31 leaves out Oct 31."}},"required":["start","end"]},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":50}},"required":["metric"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_export_jobs":{"post":{"operationId":"flyra_export_jobs","summary":"Export the jobs report as CSV","tags":["Jobs"],"description":"Export the jobs between two dates as CSV text, the same file Reports > Jobs > Export CSV downloads in the Flyra web app with no filters set: Job Date, Customer, Sales Rep, Technician, Status, Lead Source and Total, newest added first. Dates are the organization's calendar days; fetch_by picks the scheduled date (default) or the date added, as the tab's toggle does, and an unscheduled job counts by its date added. The Job Date is the organization's calendar day and Total is in the organization's currency. 500 rows per call. Owners and Admins only. Available per organization; where it is not enabled the reply says so and an admin can export from Reports > Jobs in the web app instead. Page with offset until next_offset is null, then join the csv values (drop the header line on every page but the first) and save the result as a .csv file.\n\nScope: `jobs:read`.","x-required-scope":"jobs:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"start_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First day to include, YYYY-MM-DD, in the organization's timezone."},"end_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Last day to include, YYYY-MM-DD, in the organization's timezone."},"fetch_by":{"description":"startDate (default): by scheduled date. dateAdded: by the date the job was created.","type":"string","enum":["startDate","dateAdded"]},"offset":{"description":"Row to start from (default 0). Pass the next_offset from the previous call.","type":"integer","minimum":0,"maximum":9007199254740991},"limit":{"description":"Rows per call (default and cap 500).","type":"integer","exclusiveMinimum":0,"maximum":500}},"required":["start_date","end_date"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_export_subscriptions":{"post":{"operationId":"flyra_export_subscriptions","summary":"Export the subscriptions report as CSV","tags":["Subscriptions"],"description":"Export the plans table on Reports > Subscriptions as CSV text, the same file its Export CSV downloads in the Flyra web app with no person, customer or status filter: Subscription, Customer, Status, Jobs Completed, Total Visits, Billing, Amount and ARR (in the organization's currency). tab picks the table's tab: active (default; plans live as of today, or as of end_date), pending, or all. start_date and end_date, given together, keep the plans that overlap those days, as the report's date picker does. 500 rows per call. Owners and Admins only. Available per organization; where it is not enabled the reply says so and an admin can export from Reports > Subscriptions in the web app instead. Page with offset until next_offset is null, then join the csv values (drop the header line on every page but the first) and save the result as a .csv file.\n\nScope: `subscriptions:read`.","x-required-scope":"subscriptions:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"tab":{"description":"The table's tab (default active).","type":"string","enum":["active","pending","all"]},"start_date":{"description":"With end_date: first day of the range, YYYY-MM-DD.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"end_date":{"description":"With start_date: last day of the range, YYYY-MM-DD.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"offset":{"description":"Row to start from (default 0). Pass the next_offset from the previous call.","type":"integer","minimum":0,"maximum":9007199254740991},"limit":{"description":"Rows per call (default and cap 500).","type":"integer","exclusiveMinimum":0,"maximum":500}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_export_estimates":{"post":{"operationId":"flyra_export_estimates","summary":"Export the estimates report as CSV","tags":["Estimates"],"description":"Export the estimates created between two dates as CSV text, the same file Reports > Estimates > Export CSV downloads in the Flyra web app with no filters set: Date Created, Customer, Created By, Status, Lead Source and Amount, newest first. Dates are the organization's calendar days; Date Created is the organization's calendar day and Amount is in the organization's currency. 500 rows per call. Owners and Admins only. Available per organization; where it is not enabled the reply says so and an admin can export from Reports > Estimates in the web app instead. Page with offset until next_offset is null, then join the csv values (drop the header line on every page but the first) and save the result as a .csv file.\n\nScope: `estimates:read`.","x-required-scope":"estimates:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"start_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First day to include (by date created), YYYY-MM-DD, in the organization's timezone."},"end_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Last day to include (by date created), YYYY-MM-DD, in the organization's timezone."},"offset":{"description":"Row to start from (default 0). Pass the next_offset from the previous call.","type":"integer","minimum":0,"maximum":9007199254740991},"limit":{"description":"Rows per call (default and cap 500).","type":"integer","exclusiveMinimum":0,"maximum":500}},"required":["start_date","end_date"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_export_reviews":{"post":{"operationId":"flyra_export_reviews","summary":"Export the reviews report as CSV","tags":["Reviews"],"description":"Export the reviews left between two dates as CSV text, the same file Reports > Reviews > Export CSV downloads in the Flyra web app with no filters set: Reviewer, Job, Rating, Comment and Date, newest first. Dates are the organization's calendar days; Date is the organization's calendar day. 500 rows per call. Owners and Admins only. Available per organization; where it is not enabled the reply says so and an admin can export from Reports > Reviews in the web app instead. Page with offset until next_offset is null, then join the csv values (drop the header line on every page but the first) and save the result as a .csv file.\n\nScope: `reviews:read`.","x-required-scope":"reviews:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"start_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First day to include, YYYY-MM-DD, in the organization's timezone."},"end_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Last day to include, YYYY-MM-DD, in the organization's timezone."},"offset":{"description":"Row to start from (default 0). Pass the next_offset from the previous call.","type":"integer","minimum":0,"maximum":9007199254740991},"limit":{"description":"Rows per call (default and cap 500).","type":"integer","exclusiveMinimum":0,"maximum":500}},"required":["start_date","end_date"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_export_map_pins":{"post":{"operationId":"flyra_export_map_pins","summary":"Export the map pins report as CSV","tags":["Map"],"description":"Export the door-knocking pins dropped between two dates as CSV text, the same file Reports > Map > Export CSV downloads in the Flyra web app with no filters set: Address, Client Name, Status, Created At and Created By, newest first. Status is the organization's own label for each pin type. Dates are the organization's calendar days, and Created At is shown in the organization's time zone. 500 rows per call. Owners and Admins only. Available per organization; where it is not enabled the reply says so and an admin can export from Reports > Map in the web app instead. Page with offset until next_offset is null, then join the csv values (drop the header line on every page but the first) and save the result as a .csv file. If total changes between calls, rows were added or removed while paging: start again from offset 0.\n\nScope: `pins:read`.","x-required-scope":"pins:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"start_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First day to include (by date dropped), YYYY-MM-DD, in the organization's timezone."},"end_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Last day to include (by date dropped), YYYY-MM-DD, in the organization's timezone."},"offset":{"description":"Row to start from (default 0). Pass the next_offset from the previous call.","type":"integer","minimum":0,"maximum":9007199254740991},"limit":{"description":"Rows per call (default and cap 500).","type":"integer","exclusiveMinimum":0,"maximum":500}},"required":["start_date","end_date"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_export_payments":{"post":{"operationId":"flyra_export_payments","summary":"Export the payments report as CSV","tags":["Invoices"],"description":"Export the payments taken between two dates as CSV text, the same file Reports > Payments > Export payments downloads in the Flyra web app with no filters set: Date, Customer, Method, Source, Service amount, Sales tax, Tip and Total paid, newest first. Completed, refunded and partially refunded payments are included, as on the tab. Money is written as bare numbers; Service amount, Sales tax and Tip are blank where Flyra has no tax or tip split for the payment. Dates are the organization's calendar days; Date is the organization's calendar day. 500 rows per call. Owners and Admins only. Available per organization; where it is not enabled the reply says so and an admin can export from Reports > Payments in the web app instead. Page with offset until next_offset is null, then join the csv values (drop the header line on every page but the first) and save the result as a .csv file. If total changes between calls, rows were added or removed while paging: start again from offset 0.\n\nScope: `invoices:read`.","x-required-scope":"invoices:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"start_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First day to include (by payment date), YYYY-MM-DD, in the organization's timezone."},"end_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Last day to include (by payment date), YYYY-MM-DD, in the organization's timezone."},"offset":{"description":"Row to start from (default 0). Pass the next_offset from the previous call.","type":"integer","minimum":0,"maximum":9007199254740991},"limit":{"description":"Rows per call (default and cap 500).","type":"integer","exclusiveMinimum":0,"maximum":500}},"required":["start_date","end_date"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_export_unpaid":{"post":{"operationId":"flyra_export_unpaid","summary":"Export the unpaid jobs list as CSV","tags":["Invoices"],"description":"Export the All Unpaid Jobs list on Reports > Payments as CSV text, the same file its Export unpaid downloads in the Flyra web app with no filters set: Scheduled, Customer, Job, Days unpaid and Amount due (in the organization's currency), most days unpaid first. The list is every completed job dated up to now that still has a balance and is not marked paid, whatever the report's dates, as on the tab. Scheduled is the organization's calendar day. 500 rows per call. Owners and Admins only. Available per organization; where it is not enabled the reply says so and an admin can export from Reports > Payments in the web app instead. Page with offset until next_offset is null, then join the csv values (drop the header line on every page but the first) and save the result as a .csv file. If total changes between calls, rows were added or removed while paging: start again from offset 0.\n\nScope: `invoices:read`.","x-required-scope":"invoices:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"offset":{"description":"Row to start from (default 0). Pass the next_offset from the previous call.","type":"integer","minimum":0,"maximum":9007199254740991},"limit":{"description":"Rows per call (default and cap 500).","type":"integer","exclusiveMinimum":0,"maximum":500}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_leads":{"post":{"operationId":"flyra_list_leads","summary":"List leads","tags":["Leads"],"description":"List leads with optional filters. Filter by stage (status_stage label), status_v2, pipeline_id, or owner. Returns concise rows; cap 50 per call. search, source, city, postal_code and has_phone/has_email/has_address work like the Leads screen's search box and filters: search matches first, last or full name, email or phone (spaces or brackets in a phone are fine). Below Admin and Owner, without the permission to see every lead, only the caller's own leads come back, as on the Leads screen. With updated_since or cursor it returns full lead records (the same fields as flyra_get_lead) changed since then, oldest change first; the filters above apply there too. To keep a copy in sync, do not call the get tool for each record and do not re-read the whole list: call this tool with updated_since once, then keep passing next_cursor until has_more is false, save that last next_cursor, and on your next run (every 5 to 15 minutes is plenty) start from it. Changes from the last 30 seconds arrive on the next run.\n\nScope: `leads:read`.","x-required-scope":"leads:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"status_stage":{"description":"Stage label, e.g. \"Qualifying\" or \"Booked\".","type":"string"},"status_v2":{"description":"Top-level status: new | contacted | qualified | proposal | won | lost","type":"string"},"pipeline_id":{"type":"string"},"owner_user_id":{"type":"string"},"since":{"description":"ISO 8601 — only leads created on or after.","type":"string"},"search":{"description":"Name, email or phone, as typed in the Leads search box.","type":"string"},"source":{"description":"Lead source, one of the Leads screen's source chips: \"meta\", \"webform\", \"manual\" or \"map\".","type":"string"},"city":{"description":"Leads whose city contains this text.","type":"string"},"postal_code":{"description":"Leads whose ZIP / postal code starts with this.","type":"string"},"has_phone":{"description":"yes = has a phone number, no = has none.","type":"string","enum":["yes","no"]},"has_email":{"description":"yes = has an email, no = has none.","type":"string","enum":["yes","no"]},"has_address":{"description":"yes = has a street address, no = has none.","type":"string","enum":["yes","no"]},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":50},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991},"updated_since":{"description":"ISO 8601 time. Switches to \"changed since\" mode: only records created or edited at or after it, oldest change first, each row complete. Use it once to start a sync, then pass cursor instead.","type":"string"},"cursor":{"description":"next_cursor from your previous call. Pass it to read the next page, and save the last one to start your next run where this one stopped.","type":"string"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_lead":{"post":{"operationId":"flyra_get_lead","summary":"Get a lead","tags":["Leads"],"description":"Full lead record including notes + source attribution.\n\nScope: `leads:read`.","x-required-scope":"leads:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"lead_id":{"type":"string"}},"required":["lead_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_create_lead":{"post":{"operationId":"flyra_create_lead","summary":"Create a lead","tags":["Leads"],"description":"Manually capture a new lead. At least one of email or phone is required so we can contact them. Send the service address in address_line1/city/state/postal_code rather than inside notes — those columns are what the map, the pipeline and the customer created on conversion all read. With no pipeline_id it goes to the pipeline the business routes its source to (see flyra_list_pipelines), else the default pipeline; a pipeline_id from another business is refused. A lead on its pipeline's first stage sends the new-lead phone alert to the team, as one added in the app does.\n\nScope: `leads:write`.","x-required-scope":"leads:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"phone":{"description":"E.164 preferred.","type":"string"},"service_type":{"type":"string"},"value_cents":{"type":"integer","minimum":0,"maximum":9007199254740991},"address_line1":{"description":"Street address, e.g. \"2500 Londonderry Road\".","type":"string"},"address_line2":{"description":"Apartment, suite or unit.","type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postal_code":{"type":"string"},"notes":{"type":"string"},"pipeline_id":{"type":"string"},"status_stage":{"type":"string"},"lead_source_id":{"type":"string"},"source":{"description":"Free-text source label (e.g. \"Referral\", \"Yelp\").","type":"string"},"pin_id":{"description":"The map pin this lead came from (from flyra_list_map_pins). Stored on the lead the way the app does when a rep creates a lead from a pin.","type":"string"},"pin_status":{"description":"Also set that pin's status, a key from flyra_list_pin_types (e.g. \"quote\" when an estimate goes out, \"revisit\"). Needs pin_id. There is no \"lead\" pin status.","type":"string"},"run_automations":{"description":"Also start this business's automations the way a lead added in the Flyra app does, into the pipeline you pass or the default pipeline. Only a lead on its pipeline's first stage counts as new; automations limited to a different pipeline do not run. A lead created on a later stage starts nothing: stage automations run on a move, so to start only those, create it on the first stage without run_automations and then move it with flyra_update_lead_stage and run_automations. The reply's automations_queued says whether anything was queued. Leave off when importing or back-filling old leads.","type":"boolean"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_lead_stage":{"post":{"operationId":"flyra_update_lead_stage","summary":"Update a lead's details, owner, pipeline, stage, source or deal value","tags":["Leads"],"description":"Move a lead to a different stage or pipeline, set its lead source and/or its deal value, and edit its name, phone, email, address and notes the way the Edit button on a lead's Contact Information card in the Flyra app does (PATCH /api/leads/[id]). Pass only the fields to change; a blank value clears that field, except first_name, which cannot be blank. notes replaces the lead's whole notes field; to add a note to the lead's activity timeline and keep earlier notes, use flyra_add_lead_note instead. An email must look like name@domain.tld. A phone is checked for the business's country and stored in international (E.164) form; an invalid one is refused and nothing is saved. owner_user_id assigns the lead to a sales rep (the lead owner), as the Assigned To field in the lead's Edit details dialog does; null unassigns it. Only Admins and Owners may set it, as in the app; an id that is not a team member of this business is refused. Pass status_stage (label) and/or status_v2. status_stage lost or won lands on the pipeline's marked Lost or Won stage (flyra_set_pipeline_stage_outcome) when no stage is keyed lost or won, and status_v2 follows a move into or out of a marked stage unless you pass it. If marking lost, set lost_reason. pipeline_id (from flyra_list_pipelines) moves the lead to that pipeline: it lands on the pipeline's first stage unless status_stage names one of that pipeline's stages. lead_source_id (from flyra_list_lead_sources) sets where the lead came from; pass null to clear it. value_cents is the amount the pipeline column totals add up, in whole cents (350000 = $3,500); pass null to clear it. A lead converted into a job or subscription gets its sold value filled in on its own.\n\nScope: `leads:write`.","x-required-scope":"leads:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"lead_id":{"type":"string"},"status_stage":{"type":"string"},"status_v2":{"type":"string"},"lost_reason":{"type":"string"},"value_cents":{"description":"Deal value in whole cents. null clears it.","anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"pipeline_id":{"description":"Pipeline id from flyra_list_pipelines.","type":"string"},"lead_source_id":{"description":"Lead source id from flyra_list_lead_sources. null clears it.","anyOf":[{"type":"string"},{"type":"null"}]},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"description":"Blank clears it.","type":"string"},"email":{"type":"string"},"address_line1":{"type":"string"},"address_line2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postal_code":{"type":"string"},"notes":{"type":"string"},"owner_user_id":{"description":"The sales rep to assign: their user id, or their employee id (emp_… from flyra_list_employees). null unassigns. Admins and Owners only.","anyOf":[{"type":"string"},{"type":"null"}]},"run_automations":{"description":"Also start this business's Lead stage changed automations, exactly as when the lead is moved in the Flyra app. Leave off for bulk clean-ups. The reply's automations_queued says whether anything was queued.","type":"boolean"}},"required":["lead_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_run_lead_automations":{"post":{"operationId":"flyra_run_lead_automations","summary":"Run a lead's new-lead automations","tags":["Leads"],"description":"Start this business's new-lead automations (their texts and emails) for an existing lead that was imported or recovered late without them, for example a Facebook lead Flyra received hours after it was submitted. This sends real messages to the lead. Refused when the lead already got its new-lead automations, when it is no longer on its pipeline's first stage (new-lead automations only run for a lead there), and when it is won, lost or converted. Admin only. Use only when the business owner asks for it, never to re-send or as a bulk action.\n\nScope: `leads:write`.","x-required-scope":"leads:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"lead_id":{"type":"string","description":"Lead id from flyra_list_leads or flyra_get_lead."}},"required":["lead_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_add_lead_note":{"post":{"operationId":"flyra_add_lead_note","summary":"Add a note to a lead","tags":["Leads"],"description":"Adds a note to a lead's activity timeline, as the note box on a lead's page in Leads does. Earlier notes stay; nothing is overwritten. The note is saved with you as its author. It starts no automation and sends nothing. Below Admin and Owner, without the permission to see every lead, only a lead you own can take a note. Needs a signed-in Flyra user.\n\nScope: `leads:write`.","x-required-scope":"leads:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"lead_id":{"type":"string","description":"The lead, from flyra_list_leads."},"note":{"type":"string","description":"The note text."}},"required":["lead_id","note"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_convert_customer_to_lead":{"post":{"operationId":"flyra_convert_customer_to_lead","summary":"Convert a customer back into a lead","tags":["Leads"],"description":"Puts one existing customer back in the leads pipeline, as the Convert to Lead button on a customer's page does: a new lead with their name, mobile phone, email and address, on the default pipeline's first stage, linked to the customer. Sends: like the button, it emits the new-lead event, so this business's new-lead automations start for that lead and can text or email that customer. Confirm with the user first and pass confirm: true. A customer who already has an open lead is not converted again. Admins and Owners only, and a signed-in Flyra user, as the button.\n\nScope: `leads:write`.","x-required-scope":"leads:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string","description":"The customer, from flyra_search_customers."},"confirm":{"type":"boolean","const":true,"description":"Pass true once the user has agreed: the new lead starts this business's new-lead automations."}},"required":["customer_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_pipelines":{"post":{"operationId":"flyra_list_pipelines","summary":"List pipelines and their stages","tags":["Leads"],"description":"Returns every pipeline configured for the org, each with its ordered stage list. Use the stage labels for flyra_update_lead_stage.\n\nScope: `leads:read`.","x-required-scope":"leads:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_lead_sources":{"post":{"operationId":"flyra_list_lead_sources","summary":"List lead sources","tags":["Leads"],"description":"Returns the org's defined lead sources. Use lead_source_id when creating or updating a lead.\n\nScope: `leads:read`.","x-required-scope":"leads:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_convert_lead":{"post":{"operationId":"flyra_convert_lead","summary":"Convert a lead into a customer","tags":["Leads"],"description":"Turn a lead into a customer, the same way the Convert button on the lead page does: it creates the customer (and a job when the lead carries the work), marks the lead converted, and moves it to the won stage when the pipeline has one. Safe to call twice — an already-converted lead returns the customer it became rather than a second one. Use it when the person has agreed to the work, not to tidy up a lead nobody has spoken to.\n\nScope: `leads:write`.","x-required-scope":"leads:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"lead_id":{"type":"string"}},"required":["lead_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_link_lead_to_customer":{"post":{"operationId":"flyra_link_lead_to_customer","summary":"Link a lead to an existing customer","tags":["Leads"],"description":"Record that a lead became a customer who already exists in Flyra, for when someone added the customer by hand instead of converting the lead. Marks the lead converted into that customer, moves the lead's texts, notes, estimates and booked visits onto the customer, moves the lead to the won stage when its pipeline has one, and stops lead follow-up automations. When the lead came from a referral, the referral reward is released to that customer. Creates no customer and no job. Refuses a lead already linked to a customer; a lead marked converted with no customer recorded is linked like an open one. Admin or Owner only, like Convert. Use flyra_convert_lead instead when there is no customer yet.\n\nScope: `leads:write`.","x-required-scope":"leads:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"lead_id":{"type":"string"},"customer_id":{"type":"string"},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user confirmed this lead became this customer."}},"required":["lead_id","customer_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_lead_for_customer":{"post":{"operationId":"flyra_lead_for_customer","summary":"Find the lead a customer came from","tags":["Leads"],"description":"Given a customer, return the lead that converted into them, or nothing when they were never a lead. Use it to get back to the pipeline from a job or a customer — for example to move that lead to a different stage once their job is booked. It follows the recorded conversion link only, so a customer added directly returns no lead even if somebody with the same phone number is on the board.\n\nScope: `leads:read`.","x-required-scope":"leads:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string"}},"required":["customer_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_tags":{"post":{"operationId":"flyra_list_tags","summary":"List customer tags","tags":["Customers"],"description":"Every tag the org has defined for customers. Returns id + label + color so the agent can present a menu.\n\nScope: `customers:read`.","x-required-scope":"customers:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_add_tag_to_customer":{"post":{"operationId":"flyra_add_tag_to_customer","summary":"Add a tag to a customer","tags":["Customers"],"description":"Link a customer to a tag. Pass either tag_id (preferred, from flyra_list_tags) or label. A label with no tag yet creates the tag, which only an Admin or Owner can do, as in the app. Idempotent — re-tagging the same customer with the same tag is a no-op.\n\nScope: `customers:write`.","x-required-scope":"customers:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string"},"tag_id":{"type":"string"},"label":{"description":"Tag label — used to find or create the tag.","type":"string"},"color":{"description":"Hex color for a new tag (defaults to #94a3b8 / slate-400 if omitted).","type":"string"}},"required":["customer_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_remove_tag_from_customer":{"post":{"operationId":"flyra_remove_tag_from_customer","summary":"Remove a tag from a customer","tags":["Customers"],"description":"Detach a tag from a customer. Returns ok=true even if the tag wasn't present (idempotent).\n\nScope: `customers:write`. Destructive: it deletes or cancels.","x-required-scope":"customers:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string"},"tag_id":{"type":"string"}},"required":["customer_id","tag_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_customer_tag":{"post":{"operationId":"flyra_update_customer_tag","summary":"Rename or recolour a customer tag","tags":["Customers"],"description":"Rename or recolour one of the org's customer tags, as Customers > Edit Customer Tags does, saving through the same code as that screen's Save. Pass tag_id (from flyra_list_tags) and a new label, a new color (hex like #ff0000), or both. A tag whose internal name was made from its label gets a new name from the new label, as on the screen; customers keep the tag either way. Admins and Owners only.\n\nScope: `customers:write`.","x-required-scope":"customers:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"tag_id":{"type":"string","description":"Tag id from flyra_list_tags."},"label":{"description":"New label.","type":"string"},"color":{"description":"New hex color, like #ff0000.","type":"string"}},"required":["tag_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_delete_customer_tag":{"post":{"operationId":"flyra_delete_customer_tag","summary":"Delete a customer tag","tags":["Customers"],"description":"Delete one of the org's customer tags, as removing it on Customers > Edit Customer Tags and pressing Save does, through the same code. The tag is deleted for good and comes off every customer that had it. Pass tag_id from flyra_list_tags and confirm: true. Admins and Owners only.\n\nScope: `customers:write`. Destructive: it deletes or cancels.","x-required-scope":"customers:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"tag_id":{"type":"string","description":"Tag id from flyra_list_tags."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the tag is deleted and taken off every customer that has it."}},"required":["tag_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_reviews":{"post":{"operationId":"flyra_list_reviews","summary":"List customer reviews","tags":["Reviews"],"description":"List reviews received. Filter by customer_id, job_id, or minimum star rating.\n\nScope: `reviews:read`.","x-required-scope":"reviews:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string"},"job_id":{"type":"string"},"min_stars":{"type":"integer","minimum":1,"maximum":5},"since":{"description":"ISO 8601 — only reviews on or after.","type":"string"},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":50},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_review":{"post":{"operationId":"flyra_get_review","summary":"Get a review","tags":["Reviews"],"description":"Return the full review record.\n\nScope: `reviews:read`.","x-required-scope":"reviews:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"review_id":{"type":"string"}},"required":["review_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_send_review_request":{"post":{"operationId":"flyra_send_review_request","summary":"Send a review request for a completed job","tags":["Reviews"],"description":"Trigger the SMS/email review-request prompt for a completed job. Uses the same lib/reviews/send-review-request helper as the rest of the app (dedupe + audit baked in). Defaults to sending SMS only (cheapest); pass send_email=true to also send email.\n\nScope: `reviews:write`.","x-required-scope":"reviews:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string"},"send_sms":{"description":"Default true.","type":"boolean"},"send_email":{"description":"Default false.","type":"boolean"}},"required":["job_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_add_review":{"post":{"operationId":"flyra_add_review","summary":"Log a review left outside Flyra","tags":["Reviews"],"description":"Log a review a customer left somewhere else (for example on Google or by phone), as the Add Review button on Reports > Reviews does: a 1-5 star rating, an optional comment, and optionally the job it was for. Saved with source \"manual\". Sends nothing to the customer. Review automations do not run for it: the database trigger that starts \"review positive\" and \"review negative\" automations skips manual reviews, the same as for a review added on the screen. A job can hold only one review. Anyone in the business who can open the customer (and the job, when given) may call it.\n\nScope: `reviews:write`.","x-required-scope":"reviews:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string","description":"The customer who left the review."},"job_id":{"description":"The job the review is for (optional).","type":"string"},"stars":{"type":"integer","minimum":1,"maximum":5,"description":"Star rating, 1 to 5."},"comment":{"description":"What the customer wrote (optional).","type":"string"}},"required":["customer_id","stars"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_equipment":{"post":{"operationId":"flyra_list_equipment","summary":"List inventory","tags":["Equipment"],"description":"The Inventory page: each item with total and available quantities, who it is assigned to, and its reorder point.\n\nScope: `equipment:read`.","x-required-scope":"equipment:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"integer","exclusiveMinimum":0,"maximum":50},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_create_equipment":{"post":{"operationId":"flyra_create_equipment","summary":"Add an inventory item","tags":["Equipment"],"description":"Add an item to inventory, like Add item on the Inventory page. It starts with every unit available. It sends nothing.\n\nScope: `equipment:write`.","x-required-scope":"equipment:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Item name, e.g. \"Extension ladder\"."},"total_quantity":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many the business has."},"description":{"description":"Notes about the item. null clears it.","anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"assigned_to":{"description":"Employee (emp_<uuid> or uuid) the item is assigned to. null clears it.","anyOf":[{"type":"string"},{"type":"null"}]},"reorder_at":{"description":"Reorder point: the item shows Low at or below this many available. null clears it.","anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"consumable":{"description":"The item's Type on the Inventory page: true for Supplies (used up, like soap), false for Equipment (comes back, like a ladder).","type":"boolean"},"attention_on":{"description":"Date it needs attention (expiry, service), YYYY-MM-DD. null clears it.","anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"unit_cost_cents":{"description":"What one costs to buy, in cents. null clears it.","anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]}},"required":["name","total_quantity"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_equipment":{"post":{"operationId":"flyra_update_equipment","summary":"Edit an inventory item","tags":["Equipment"],"description":"Change an inventory item, like editing it on the Inventory page. Only the fields given change. A new total_quantity keeps checked-out units checked out (available = new total less what is out) and cannot go below what is out. A supply's usage rate (the form's \"Used at a set rate\": Per job, or Per linear ft; the page sets it on consumables) is sent whole: usage_qty alone is per job; usage_qty with usage_per and usage_unit is per that much of the unit; usage_qty null clears the rate. Admins or Manage inventory. If the item has a reorder point and its available count drops to it, the business's Low stock automation (if they turned one on) can text the team.\n\nScope: `equipment:write`.","x-required-scope":"equipment:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"equipment_id":{"type":"string","description":"The item id, from flyra_list_equipment."},"name":{"type":"string","minLength":1,"maxLength":200},"total_quantity":{"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"description":"Notes about the item. null clears it.","anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"assigned_to":{"description":"Employee (emp_<uuid> or uuid) the item is assigned to. null clears it.","anyOf":[{"type":"string"},{"type":"null"}]},"reorder_at":{"description":"Reorder point: the item shows Low at or below this many available. null clears it.","anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"consumable":{"description":"The item's Type on the Inventory page: true for Supplies (used up, like soap), false for Equipment (comes back, like a ladder).","type":"boolean"},"attention_on":{"description":"Date it needs attention (expiry, service), YYYY-MM-DD. null clears it.","anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"unit_cost_cents":{"description":"What one costs to buy, in cents. null clears it.","anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"usage_qty":{"description":"How many of this supply one job uses, e.g. 1.5. null clears the whole rate.","anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]},"usage_per":{"description":"Per how much of usage_unit, e.g. 6 for \"1 track per 6 linear ft\". Omit with usage_unit for per job.","anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]},"usage_unit":{"description":"The unit the job's line items measure in, e.g. \"linear ft\" (or \"linear m\"). Omit with usage_per for per job.","anyOf":[{"type":"string","minLength":1,"maxLength":40},{"type":"null"}]}},"required":["equipment_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_mark_equipment_serviced":{"post":{"operationId":"flyra_mark_equipment_serviced","summary":"Mark an inventory item serviced","tags":["Equipment"],"description":"Record that an inventory item was serviced (sets its last_serviced_at, which flyra_list_equipment returns). An automation on inventory.maintenance_due counts days and uses from this time, so it can fire again for the next service. serviced_at defaults to now. It sends nothing. Admins or Manage inventory.\n\nScope: `equipment:write`.","x-required-scope":"equipment:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"equipment_id":{"type":"string","description":"The item id, from flyra_list_equipment."},"serviced_at":{"description":"When it was serviced, ISO 8601, e.g. 2026-11-03T15:00:00Z. Defaults to now.","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["equipment_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_equipment_photo":{"post":{"operationId":"flyra_set_equipment_photo","summary":"Set an inventory item's photo","tags":["Equipment"],"description":"Set the photo on an inventory item, as choosing a photo on the item's form on the Inventory page and saving does. It replaces the item's photo (flyra_list_equipment `image_url`), and the old picture file is removed. It is not sent to anyone.\n\nGive the picture as image_url (a public https link that does not redirect) or as image_base64 (the file's bytes). JPG, PNG or WebP (a HEIC photo is saved as JPG), up to 5 MB. Like a photo added in the app, it is kept behind a public link that anyone holding it can open.\n\nAdmins or Manage inventory.\n\nScope: `equipment:write`.","x-required-scope":"equipment:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"equipment_id":{"type":"string","description":"The item id, from flyra_list_equipment."},"image_url":{"description":"Public https link to the picture. Pass this or image_base64.","type":"string"},"image_base64":{"description":"The picture's bytes, base64 encoded. Pass this or image_url.","type":"string","maxLength":7000000}},"required":["equipment_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_delete_equipment":{"post":{"operationId":"flyra_delete_equipment","summary":"Delete an inventory item","tags":["Equipment"],"description":"Permanently delete an inventory item and its checkout history, like the Delete button on an item's edit form on the Inventory page. Refused while any of it is checked out (return it first with flyra_return_equipment), and refused for a supply a job has recorded as used: that supply is part of what past jobs cost, so set its total_quantity to 0 with flyra_update_equipment instead. Admins or Manage inventory. Pass the item id from flyra_list_equipment and confirm: true. It sends nothing.\n\nScope: `equipment:write`. Destructive: it deletes or cancels.","x-required-scope":"equipment:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"equipment_id":{"type":"string","description":"The item id, from flyra_list_equipment."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the item and its checkout history are deleted for good."}},"required":["equipment_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_equipment_checkouts":{"post":{"operationId":"flyra_list_equipment_checkouts","summary":"List equipment checkouts","tags":["Equipment"],"description":"Who has what checked out, newest first, with the item and the employee: the Inventory page's movement log. active_only true lists only what is still out. Filter by item or by employee. Use a checkout id with flyra_return_equipment.\n\nScope: `equipment:read`.","x-required-scope":"equipment:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"equipment_id":{"description":"Only this item.","type":"string"},"employee_id":{"description":"Only this employee (emp_<uuid> or uuid).","type":"string"},"active_only":{"description":"true: only checkouts not yet returned.","type":"boolean"},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":50},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_check_out_equipment":{"post":{"operationId":"flyra_check_out_equipment","summary":"Check out equipment","tags":["Equipment"],"description":"Check out some of an item to the signed-in person, like Check out on the Inventory page. It is always to yourself: the app has no way to check an item out to someone else. Available drops by the quantity (a consumable's total drops too). Through the connector it needs Manage inventory, like adding and editing. If the item has a reorder point and its available count drops to it, the business's Low stock automation (if they turned one on) can text the team.\n\nScope: `equipment:write`.","x-required-scope":"equipment:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"equipment_id":{"type":"string","description":"The item id, from flyra_list_equipment."},"quantity":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"How many to take."},"notes":{"type":"string","maxLength":500}},"required":["equipment_id","quantity"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_return_equipment":{"post":{"operationId":"flyra_return_equipment","summary":"Return equipment","tags":["Equipment"],"description":"Return a checkout, like Return on the Inventory page: the units go back to available (a consumable's total goes back up too). Leave quantity out to return all of it. With a quantity less than the checkout's, only that many come back: the checkout is closed for that many and the rest stays out under a new checkout id (remaining_checkout), as the app does. Your own checkouts, or anyone's with Manage inventory; through the connector it needs Manage inventory, like adding and editing. Get the checkout id from flyra_list_equipment_checkouts with active_only true. It sends nothing.\n\nScope: `equipment:write`.","x-required-scope":"equipment:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"checkout_id":{"type":"string","description":"The checkout id, from flyra_list_equipment_checkouts."},"quantity":{"description":"How many to return. Leave out to return the whole checkout.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["checkout_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_job_supplies":{"post":{"operationId":"flyra_get_job_supplies","summary":"Get the supplies used on a job","tags":["Equipment"],"description":"The Supplies card on a job (Checklist tab), as GET /api/v2/jobs/[id]/supplies answers it: whether supply tracking is on, the supplies recorded as used (quantity, unit cost, what is left on the shelf), the supplies the usage rates suggest that are not recorded yet, the consumables that can be added (catalog), and when someone confirmed the job's usage. A signed-in employee gets only a job their Schedule shows them. Read the list here before flyra_record_job_supplies, which replaces it.\n\nScope: `equipment:read`.","x-required-scope":"equipment:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"Job UUID or semantic id."}},"required":["job_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_record_job_supplies":{"post":{"operationId":"flyra_record_job_supplies","summary":"Record the supplies used on a job","tags":["Equipment"],"description":"The Save button on a job's Supplies card (PUT /api/v2/jobs/[id]/supplies): REPLACES the whole list of supplies the job used with the list sent, and stamps the job as confirmed. A recorded supply left out of the list is removed and its quantity goes back on the shelf; a new line takes its quantity off the shelf (available and total, rounded up to whole units) and a changed one moves the difference. An empty list records that the job used nothing. Read the current list with flyra_get_job_supplies first and send it back with your changes. Only consumables can be recorded (equipment is checked out instead). Refused while supply tracking is off. If the item has a reorder point and its available count drops to it, the business's Low stock automation (if they turned one on) can text the team. Anyone who can open the job may save it on the card; over the connector it also needs View and Manage inventory. Needs a signed-in Flyra user, not an organization API key.\n\nScope: `equipment:write`. Destructive: it deletes or cancels.","x-required-scope":"equipment:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"Job UUID or semantic id."},"supplies":{"type":"array","items":{"type":"object","properties":{"equipment_id":{"type":"string","description":"The supply's id: equipmentId from flyra_get_job_supplies (recorded, suggested or catalog)."},"quantity":{"type":"number","exclusiveMinimum":0,"description":"How much the job used."},"source":{"description":"\"estimated\" for a suggested line kept as suggested, else \"manual\" (the default).","type":"string","enum":["estimated","manual"]}},"required":["equipment_id","quantity"]},"description":"The whole list of what the job used. Anything recorded and not in this list is removed."},"confirm":{"type":"boolean","const":true,"description":"Must be true: this replaces the job's recorded supplies and moves stock."}},"required":["job_id","supplies","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_automations":{"post":{"operationId":"flyra_list_automations","summary":"List automations","tags":["Automations"],"description":"Returns the org's automations (workflows) with their trigger and on/off state. Covers both the built-in message automations (job confirmation, on-the-way, review request, receipt, and so on) and any custom workflow the org built. Use it to answer \"is the lead follow-up on?\" or to find the id to pass to flyra_get_automation / flyra_update_automation. Job reminders have a master switch that is not one of the items: the top-level `job_reminders` field is it (id `job_reminders`, its on/off state and its schedules), returned on every page whatever the filters. The \"Job Reminder — …\" items only fire while it is on and the schedule for their offset is on, so those items also carry `effective_enabled` (and `effective_note` when it is false). Answer \"are reminders on?\" from `job_reminders`, not from those items' is_enabled.\n\nScope: `automations:read`.","x-required-scope":"automations:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"is_enabled":{"description":"Filter by on/off state.","type":"boolean"},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":50},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_automation":{"post":{"operationId":"flyra_get_automation","summary":"Get a single automation","tags":["Automations"],"description":"Returns one automation with the message text it sends. `message_steps` carries each message the automation sends, with its step_id, channels, subject and body — pass a step_id to flyra_update_automation to change the wording. `other_steps` lists the rest of the graph (delays, branches, actions) for context; those are edited in the Flyra builder, not here. Use the id from flyra_list_automations. With automation_id `job_reminders` it returns the Job Reminders master switch and its schedules instead (no steps, no runs). A \"Job Reminder — …\" automation also carries `effective_enabled`, false while that switch or the schedule for its offset is off. An Inbound webhook automation (trigger webhook.received) also carries `webhook_url`, where the business's website or form tool posts its form fields; it is a secret, so give it only to whoever sets up the form. It is null when the automation has no URL yet: saving it with flyra_save_automation gives it one. An org API key without automations:write does not get it. Pass include_runs to also read its most recent runs (when each started, how it ended, the steps it reached and any error), the history Admins and Owners see on its History tab in the web app; an org API key with automations:read reads it too. Errors are cut at 300 characters with phone numbers and email addresses masked.\n\nScope: `automations:read`.","x-required-scope":"automations:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"automation_id":{"type":"string","description":"Automation id from flyra_list_automations."},"include_runs":{"description":"Also return this automation's most recent runs, newest first: when each started, how it ended, every step it reached and any error (cut at 300 characters, phone numbers and emails masked). Off by default.","type":"boolean"},"runs_limit":{"description":"How many runs to return with include_runs. 5 by default, at most 10.","type":"integer","exclusiveMinimum":0,"maximum":10},"runs_offset":{"description":"How many of the newest runs to skip, at most 10000. Pass runs.next_offset from the last answer to read further back.","type":"integer","minimum":0,"maximum":10000}},"required":["automation_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_enable_automation":{"post":{"operationId":"flyra_enable_automation","summary":"Turn an automation on","tags":["Automations"],"description":"Turns an automation on. It starts firing on new trigger events immediately, so it texts or emails customers: ask the user first and pass confirm: true. With automation_id `job_reminders` it turns on the Job Reminders master switch the way the Automations page switch does: only the first reminder schedule is switched on, the reply lists the schedules still off, and reminders are scheduled for upcoming jobs. Already on, it changes nothing. Add offset (for example \"2 weeks\", from schedules[].offset) to turn on just that schedule, as its switch in Job Reminders does; the others stay as they are.\n\nScope: `automations:write`.","x-required-scope":"automations:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"automation_id":{"type":"string","description":"Automation id from flyra_list_automations."},"offset":{"description":"Only with automation_id 'job_reminders': the one reminder schedule to switch, by its offset as flyra_get_automation lists it in schedules (for example \"2 weeks\").","type":"string","maxLength":40},"confirm":{"type":"boolean","const":true,"description":"Must be true to switch an automation on: Flyra then texts or emails customers automatically."}},"required":["automation_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_disable_automation":{"post":{"operationId":"flyra_disable_automation","summary":"Turn an automation off","tags":["Automations"],"description":"Turns an automation off. Runs already in flight are not cancelled. With automation_id `job_reminders` it turns the Job Reminders master switch off the way the Automations page switch does: every reminder schedule is switched off and the reminders already scheduled for upcoming jobs ARE cancelled. The reply gives cancelled_count; when cancel_failed is true some of them could not be cancelled and may still send, so say so. Calling it again while the switch is already off retries that cancel. Add offset (from schedules[].offset) to turn off just that schedule and cancel the reminders already scheduled for it (and any left from schedules that are off); the others stay on as they are. Again while it is off retries that cancel.\n\nScope: `automations:write`.","x-required-scope":"automations:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"automation_id":{"type":"string","description":"Automation id from flyra_list_automations."},"offset":{"description":"Only with automation_id 'job_reminders': the one reminder schedule to switch, by its offset as flyra_get_automation lists it in schedules (for example \"2 weeks\").","type":"string","maxLength":40}},"required":["automation_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_snooze_automation":{"post":{"operationId":"flyra_snooze_automation","summary":"Snooze one person's automation until a date","tags":["Automations"],"description":"Holds the automation one customer or lead is going through until a date on the org's clock, for that person only (\"not ready yet, follow up in two weeks\"). Its next step waits until then (an earlier date brings it forward); later steps keep their own delays. Nobody else is affected. It moves a run already in flight only: nothing running means nothing changes, and it says why. Pass the record the run is on: lead_id for an estimate sent to a lead, customer_id otherwise. Without automation_id it works when the person is in one automation; in several, it changes nothing and lists them. Sending the estimate again restarts its follow-ups and drops the snooze. With \"Stop on reply\" on, a text reply still ends the run.\n\nScope: `automations:write`.","x-required-scope":"automations:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"description":"Customer id. Pass this or lead_id.","type":"string"},"lead_id":{"description":"Lead id. Pass this or customer_id.","type":"string"},"automation_id":{"description":"Automation id from flyra_list_automations, to snooze only that one.","type":"string"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Day to resume, YYYY-MM-DD, on the org's clock. At most a year ahead."},"time":{"description":"Time to resume, HH:MM (24h) on the org's clock. Defaults to 09:00.","type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"}},"required":["date"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_automation":{"post":{"operationId":"flyra_update_automation","summary":"Rename an automation or change what it says","tags":["Automations"],"description":"Changes an automation's name, its on/off state, or the wording of one of its messages. Turning it on (is_enabled: true) makes it text or email customers, so it needs confirm: true once the user has agreed. To change wording, read the automation with flyra_get_automation first and pass the step_id of the message you want to edit (step_id is optional when the automation sends exactly one message). Message bodies use {single_braces} variables such as {customer_first_name} and {company_name}; a variable the trigger cannot fill is reported back as a warning and would be stripped from what the customer receives. This tool does not change the shape of an automation — adding, removing or rewiring steps, and editing delays and conditions, is done in the Flyra builder. With automation_id `job_reminders` (the Job Reminders settings): is_enabled behaves as flyra_enable_automation / flyra_disable_automation do for that id (add offset to switch one schedule); send_time and message change one schedule's send time and wording, the schedule named by offset (one of schedules[].offset in flyra_get_automation). A reminder message uses the job variables such as {customer_first_name}, {job_date} and {arrival_window}.\n\nScope: `automations:write`.","x-required-scope":"automations:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"automation_id":{"type":"string","description":"Automation id from flyra_list_automations."},"name":{"description":"New name for the automation.","type":"string","minLength":1,"maxLength":200},"is_enabled":{"description":"Turn the automation on or off.","type":"boolean"},"step_id":{"description":"Which message to edit, from flyra_get_automation message_steps. Optional when the automation has exactly one message step.","type":"string"},"message":{"description":"New message body. Supports {single_brace} variables. On an email step (type send_email) it replaces the email's paragraphs, the same words flyra_get_automation reports as its message; its headings, buttons, images and sign-off stay.","type":"string","maxLength":4000},"subject":{"description":"New email subject. Only used when the step sends email.","type":"string","maxLength":300},"sends_text":{"description":"Whether this step sends a text message.","type":"boolean"},"sends_email":{"description":"Whether this step sends an email.","type":"boolean"},"offset":{"description":"Only with automation_id 'job_reminders': which reminder schedule, by its offset as flyra_get_automation lists it in schedules (for example \"24 hours\").","type":"string","maxLength":40},"send_time":{"description":"Only with automation_id 'job_reminders': when that schedule's reminder goes out, 24-hour HH:MM in the company's time zone.","type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"confirm":{"description":"Must be true to switch an automation on: Flyra then texts or emails customers automatically. Only needed with is_enabled: true.","type":"boolean","const":true}},"required":["automation_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_automation_graph":{"post":{"operationId":"flyra_get_automation_graph","summary":"Read an automation as an editable graph","tags":["Automations"],"description":"Returns the whole automation as steps and connections, in exactly the shape flyra_save_automation takes back. Read it, change the part you want, and send the whole thing back. Prefer flyra_get_automation when you only need to see what an automation says; this one is for editing its shape. To copy steps into another automation of this business (or within one): read the source and the target with this tool, add the steps you want to the target's steps with their type, name and config, give each copied step a new key the target does not use, wire them with connections between target keys, and save the target with flyra_save_automation. Rename the keys inside a copied step's config too (the to of an if_else's paths or split). Every save check runs on the copies, a connection to a step you did not copy is refused, and a copied send_webhook step must leave secret out (set it with flyra_set_webhook_secret). A save never turns anything on: the target keeps whether it is on.\n\nScope: `automations:read`.","x-required-scope":"automations:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"automation_id":{"type":"string","description":"Automation id from flyra_list_automations."}},"required":["automation_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_save_automation":{"post":{"operationId":"flyra_save_automation","summary":"Create an automation, or replace one step for step","tags":["Automations"],"description":"Writes a whole automation. Leave automation_id out to create one; pass it to replace an existing automation's steps and connections entirely. A save REPLACES the graph, so to edit one, read it with flyra_get_automation_graph first and send the full set back with your change in it — anything you leave out is deleted. A new automation is always created switched OFF; switch it on with flyra_enable_automation once a person has confirmed it. A save never changes whether an existing automation is on. Every step needs a unique `key` you choose, and connections refer to steps by those keys. Exactly one step must be the `trigger`. For trigger_event lead.not_contacted the trigger step takes config.minutes, how long a lead may go with no outbound text before it fires (default 60, minimum 5, up to 14 days = 20160; a 24 hour alert is 1440). An outbound text counts as contact; a call does not. For estimate.not_viewed and estimate.viewed_no_answer the trigger step takes config.hours (defaults 48 and 24, from 1 to 720). estimate.expiring takes config.days_before (default 3; 0 fires only when it expires) and fires twice per estimate, payload kind \"before\" then \"expired\". invoice.overdue takes config.days_overdue (default 1, up to 365) and its payload carries balance_cents. These fire once per estimate or invoice for each automation, only for moments after that automation was last saved, and each automation keeps its own value. For trigger_event record.date_reached the trigger step needs a date rule: config.dateField (one of job.start_time, job.completed_at, subscription_visit.start_time, invoice.due_date, estimate.sent_at, customer.created_at, appointment.start_time), config.offsetAmount (a whole number), config.offsetUnit (\"days\", up to 730, or \"hours\", up to 720; invoice.due_date takes days only), config.direction (\"before\" or \"after\") and, for days, config.time (\"HH:MM\" in the business's timezone, default 09:00). It runs once per record per date for the record's customer, only for dates that come around after the automation is saved or switched on, never for ones already past. appointment.start_time is a booked sales appointment (not a cancelled one or a no show); an appointment booked for a lead with no customer does not fire. For trigger_event lead.duplicate_detected it runs when a new lead (the add-lead form, the app, flyra_create_lead with run_automations, a public form or a Meta lead; not imports) has the same phone, the same email, or the same street address and zip as an existing customer or another lead of the business, checked a moment after the lead is saved. The run is about the new lead. The trigger step takes config.matchOn, a list of \"phone\", \"email\" and \"address\" that count as a match (left out, any of them counts). The payload carries matched_on (which of the three matched), matched_customer_ids, matched_lead_ids (up to 5 each), duplicate_of_customer_id and duplicate_of_lead_id (the first of each, or null). It never merges or deletes anything. For trigger_event lead.reply_matched or customer.reply_matched the trigger step needs config.keywords, 1 to 20 words or phrases, and optional config.matchMode \"any\" (default) or \"all\": it runs only for an inbound text containing them as whole words, any case. Optional config.matchType \"contains\" (the default), \"exact\" or \"starts_with\" says where: anywhere in the text, the whole text (YES but not \"yes please\"), or at its start. No AI is involved. Optional config.channels picks where to look: any of \"sms\" (the default, an inbound text), \"email\" (the subject and the new part of an inbound email, not the quoted thread under it) and \"call\" (the finished call transcript, once per call: only the caller's words when the call could be split by speaker, so the business's own rep saying a keyword does not match; a call that could not be split, usually a short call or a voicemail, matches on everything said, rep included, and caller_only on the payload is false; up to 30,000 characters, about half an hour of the caller talking); the payload carries channel and text, plus resend_email_id, subject, from_email and thread_id on email, and session_id, message_id, direction, from_number, to_number and caller_only on a call. A lead is lead.reply_matched, a customer with no open lead is customer.reply_matched; an unknown caller or sender fires neither. Patterns are not supported; to sort replies by intent (quote, reschedule, cancel, complaint, pay) use an ai_paths step after customer.replied. For trigger_event automation.finished (another automation's run ended with every step done) or automation.chain_failed (it ended on a failed step) the trigger step needs config.triggerSourceWorkflowId, the id of that other automation from flyra_list_automations; the new run carries the same person, job or invoice. config.triggerSourceStepKey (a step key of the source, from flyra_get_automation_graph) limits it to runs where that step ran: name the first step of a Yes or No branch to follow that path. An automation cannot start itself, and a chain stops after 4 automations in a row (the first plus 3 it starts). The answer's chain_source says what was saved. For trigger_event customer.service_anniversary the trigger step takes config.months (whole months, 1 to 120, default 6) and config.basis (\"last\" completed job, the default, or \"first\"); it fires at 9 AM local on the day. For customer.birthday the trigger step needs config.customFieldKey, the key of a customer date custom field (without it nothing fires), and takes config.daysBefore (0 to 60, default 0). For trigger_event job.reminder_due (\"Before a scheduled job\") the trigger step takes config.triggerReminderOffset, how long before the job it fires: one of \"2 hours\", \"4 hours\", \"6 hours\", \"12 hours\", \"24 hours\", \"2 days\", \"3 days\", \"1 week\", \"2 weeks\", \"3 weeks\", \"1 month\", or an offset the org's own Job Reminders schedules already run (schedules[].offset in flyra_get_automation with automation_id job_reminders). None of the standard times is shorter than 2 hours; left out, it fires with every reminder the org already sends. For a text shortly before the technician arrives (\"about 30 minutes out\", \"on my way\"), use trigger_event job.on_the_way instead: it fires when a technician marks the job on the way. For trigger_event appointment.reminder_due (before a booked sales appointment) the trigger step takes config.reminderOffsets, a list of whole hours before the visit such as [\"48h\", \"24h\", \"2h\"] (1h to 8760h); a plain connection out of the trigger runs at each of them. \"24 hours\", \"2 days\" and \"1 week\" are saved as hours; minutes and months are refused. config.triggerReminderOffset is set to the first offset. Left out, it fires with every reminder the org sends. For trigger_event lead.stage_changed the trigger step needs config.triggerStage: the stage id (stage_…) or label from flyra_list_pipelines. config.triggerPipelineId (pipe_… from the same tool) limits it to one pipeline. Without a stage it would run every time a lead moves to any stage. The answer's trigger_stage says what was saved. For trigger_event lead.created config.triggerPipelineId (pipe_… from flyra_list_pipelines) limits it to new leads in that pipeline; left out, it runs for every pipeline. For trigger_event lead.score_changed the trigger step needs config.score (a whole number from 0 to 100, the value to cross) and takes config.direction: up when the score reaches it, down when it falls below it, either by default. It fires on a change by the Change lead score step or a webhook update of a known lead, not on a new lead that arrives with a score. An automation never starts on a change it made itself. For trigger_event lead.idle_in_stage the trigger step needs config.triggerStage (a stage id or label from flyra_list_pipelines) and takes config.triggerPipelineId and config.hours, how long the lead may sit in that stage before it fires (default 24, up to 2160). Checked hourly, once per stay in the stage per automation; a stay already past the limit when the automation is saved does not fire. The payload carries lead_id, stage, pipeline_id, stage_changed_at, hours, hours_in_stage and owner_user_id. For trigger_event sign.dropped it fires when a new sign placement is found, checked hourly, so it can run up to an hour late. Once per sign per automation. A sign dropped before the automation is saved, or already collected when checked, does not fire. The trigger step takes optional config.kind (yard_sign, door_hanger or flyer) and config.repId (the user who dropped it). There is no territory filter. The payload carries placement_id, map_pin_id, kind, placed_at, placed_by, placed_by_name and address. For trigger_event sign.overdue the trigger step takes config.days, how many days past the due back date before it fires (default 1, up to 365). Checked hourly, once per sign per automation, only for signs with a due back date that are not collected; a sign already that late when the automation is saved does not fire. The payload carries placement_id, map_pin_id, kind, placed_at, due_back_at, days_overdue, placed_by, placed_by_name and address. For trigger_event pin.dropped it runs when a rep drops one map pin, on the web map, the iPhone app or flyra_create_map_pin (with a person behind the key). A pin import, several pins written at once, the sale pin a booked job makes and a pin backdated more than two days do not fire it. The payload carries pin_id, status (the pin type key from flyra_list_pin_types), address, client_name, created_by (the user who dropped it) and created_by_name; pick a pin type or a rep with trigger_field_matches on status or created_by. There is no territory on a pin. For trigger_event pin.status_changed it runs when a pin's type really changes on the web map, the iPhone app or flyra_update_map_pin; saving the same type again, a change to many pins at once and the change a booked or cancelled job makes do not fire it. The payload carries the pin.dropped fields plus from_status and to_status; pick a change with trigger_field_matches on from_status or to_status. For trigger_event pin.objection_logged it runs once for each objection id newly added to a pin's objection_ids, from the web map, the iPhone app, flyra_create_map_pin or flyra_update_map_pin (a new pin fires it only where pin.dropped would); taking one off fires nothing. The payload carries the pin.dropped fields plus objection_id (from flyra_list_objections); pick an objection with trigger_field_matches on objection_id. For trigger_event route.published it runs when a draft route plan is published, from the route planner, a publish of several routes or flyra_publish_route_plans; publishing a plan that is already published, and the repeat dates a recurring publish creates, do not fire it. The payload carries route_plan_id, route_date, route_name, published_by (the user), technician_employee_ids (everyone with a stop on it) and stop_count. For trigger_event leaderboard.rank_changed it runs once a day (6:30 UTC, with the month-to-date leaderboard snapshot) for each person whose rank on the sales or technician board moved since the last snapshot this month. Someone new to the board, and the first snapshot of a month, fire nothing; an automation fires only for a comparison whose previous snapshot was taken after it was saved. The payload carries employee_id, leaderboard_type (sales or technician), old_rank, new_rank, total_revenue, jobs_count, snapshot_date and previous_snapshot_date; pick a board or a climb into the top spot with trigger_field_matches on leaderboard_type or new_rank. A schedule.tick trigger step can carry a daily KPI digest (CRM#7309): config.digestMetrics, a list of any of revenue (the price on jobs completed in the period, as flyra_metrics reports it), jobs_completed, new_leads, new_reviews and unpaid_total (what invoices still owe right now, whatever the period), and config.digestPeriod, yesterday (the default), today (local midnight to the fire) or last_7_days (the seven whole days before today), in the business's timezone. At each fire the numbers ride the run as {kpi.revenue}, {kpi.jobs_completed}, {kpi.new_leads}, {kpi.new_reviews} and {kpi.unpaid_total} (money already formatted in the business's currency), for a team step such as notify_team. If the numbers cannot be read that fire is skipped, never sent as zeroes. A {kpi.<name>} the step did not ask for prints empty. A schedule.tick trigger can also run once per customer (CRM#7127): config.audience = { kind: \"customers_not_serviced\", days: N, batchSize: B, timeZone: \"America/Chicago\" }. On each scheduled day (interval daily, weekly with days, or monthly with dayOfMonth, at config.time) it starts one run per customer whose last completed or in-progress job is more than N days ago, or who has never had one (the customers list's \"not serviced in N days\" rule), with that customer as the run's subject, so {first_name} and send steps work. days is 1 to 3650. batchSize (1 to 500, default 100) is how many runs start every five minutes; the rest follow until six hours after the set time, and anyone still left that day waits for the next scheduled day. timeZone is optional and defaults to the business's own. A customer gets at most one run every N days from one automation; one still not serviced after that is run again on the next scheduled day. A new customer with no jobs counts as never serviced. Customers with automations paused are left out, and send steps still skip anyone opted out. Leads are not supported. Saved off like every automation: nothing runs until the business switches it on. For trigger_event metric.threshold_reached the trigger step needs config.metric (leads_in_stage with config.stage and optional config.pipelineId, jobs_on_day with config.dayOffset, days ahead from 0 to 14, or revenue_this_week, the price on jobs completed since Sunday midnight in the business's timezone, in dollars, the revenue flyra_metrics reports), config.comparator (above, below, at_least or at_most) and config.value (a whole number; dollars for revenue_this_week), plus the schedule fields config.interval, config.time, config.days and config.dayOfMonth as for schedule.tick. It counts at the scheduled time and fires then if the rule holds, at most once per automation per metric subject per local day. A rule that still holds fires again on the next scheduled day, so it is not a one time crossing. For a goal pace, schedule one automation per check day with the value the pace calls for by then. The payload carries metric, value (the count, or the dollars for revenue_this_week), threshold and comparator. For trigger_event timesheet.overtime the trigger step takes config.hours, the limit for one person in the current pay period (default 40, up to 744). Checked hourly using the same hours as the timesheet, so a shift counts once it is clocked out. Fires once per person per pay period per automation; someone already over when the automation is saved does not fire for that period. It changes no pay. The payload carries employee_id, hours_worked, hours, period_start and period_end. For trigger_event job.restored it runs when a cancelled job is put back on the schedule, from the job page or flyra_restore_job, for that job's customer. The payload carries job_id and restored_by. For trigger_event job.photos_added it runs once for each photo or video added to a job (the job page, the iPhone app, flyra_attach_job_photo or flyra_attach_file; not imports or copies from an estimate or plan), for that job's customer. The payload carries job_id, photo_id, photo_type (photo or video), quality_check (true for a quality check shot), quality_check_shot_id, line_item_id and added_by_user_id, so a trigger_field_matches condition can narrow it. For trigger_event job.upsell_added it runs when a line marked as an upsell is added to a job (or a line is newly marked as one), once per job and line, for that job's customer; not on cancelled or imported jobs. The payload carries job_id, line_item_id, title, quantity, unit_price_cents, line_total_cents, job_amount_cents and upsell_salesperson_ids. For trigger_event job.note_added it runs when a signed-in team member adds to or changes a job's notes, for that job's customer; automation and import writes never fire it. The payload carries job_id, note (the whole note), added_text (the new part), author_user_id and author_employee_id. add_note with target \"job\" is refused on it, since that would edit the note it listens to: use a task or a team message instead. For trigger_event job.total_changed it runs when a job's total (amount_cents) changes after it first had one, for that job's customer; not on cancelled or imported jobs, nor plan visits more than a day out. The payload carries job_id, old_amount_cents, new_amount_cents, change_cents and direction (up or down), so a trigger_field_matches condition can pick a direction or a size. add_job_line_item is refused on it. For trigger_event job.crew_changed it runs once for each technician added to or removed from a job, for that job's customer; not on cancelled or imported jobs. The payload carries job_id, employee_id and action (added or removed). assign_technician is refused on it. For trigger_event job.scheduled_from_later it runs when a job saved with no date (schedule later) gets a start time, for that job's customer; not on cancelled or imported jobs. The payload carries job_id and start_time. For trigger_event job.field_changed it runs once for each watched field that changed on a job: price, amount_cents, status, start_time, dispatched_employee_id, salesperson_id, payment_status, and the job's custom fields (custom.<key>, from the job page, the iPhone app or flyra_set_custom_field_values); not on imported jobs. The payload carries job_id, field, old_value, new_value and changed_fields. The trigger step takes optional config.field (one field; a custom field with or without custom.), config.fromValue (the old value must equal it; null for empty), and config.toOperator (any, equals, not_equals, gt, gte, lt or lte; default any) with config.toValue, numbers for gt to lte (money in cents on amount_cents). customer.field_changed and lead.custom_field_changed take the same settings. add_job_line_item, change_job_status, assign_technician and reschedule_job are refused on it. There is no subscription.charge_upcoming; for a notice before a plan is charged use subscription.renewal_upcoming. It fires a set number of days before the plan's next charge date, for that plan's customer, only for active plans billed on a fixed date (the first of the month or a set day) that charge a card on file. The number of days is the business's billing_reminder_days_before (1 to 30, default 7): one setting for the whole business, changed with flyra_update_message_settings, and it also times the built-in billing reminder email. The payload carries subscription_id, subscription_name, billing_date and amount_cents. Common step config: send_sms takes { template, sendSms, sendEmail, subject }; send_email takes { subject, preheader, doc, trackClicks } (trackClicks: true routes the email's links through Flyra so a click can start lead.email_link_clicked; default off) where doc is { version: 1, blocks: [...] } and each block is { id, type: \"heading\", text, level: 1 or 2 }, { id, type: \"paragraph\", text }, { id, type: \"button\", text, href (an https address or one link variable like {review_link}), style: \"primary\" or \"secondary\" }, { id, type: \"image\", src (an https address), alt, width: \"full\" or \"half\" }, { id, type: \"divider\" }, { id, type: \"spacer\", size: \"sm\", \"md\" or \"lg\" }, { id, type: \"details\", rows: [{ label, value }] }, { id, type: \"signature\", style: \"company\" or \"person\" }, { id, type: \"footer\" } or { id, type: \"html\", html } (the business's own email markup, up to 100,000 characters: scripts, forms and event handlers are removed, {variables} inside it are filled, and the unsubscribe line is still added), ids unique; doc may also carry theme: { letterhead: false } to leave out the logo and business name above the body, usual with custom HTML; delay_for takes { delaySeconds }; wait_for_reply takes { timeoutSeconds } and needs one on_reply and one on_timeout connection; if_else needs a condition_true and a condition_false connection. For the businesses it is switched on for, an if_else may instead take { paths: [{ to, conditionType, ...the settings that condition takes }, ...] } (2 to 10 paths, no conditionType of its own) for more than two ways out: the rules are asked in order, the first one met sends the run to the to step of that path (a condition_true connection to it), and when none is met the run takes the condition_false connection (Everything else, required). One path per run; every condition_true connection must be named by one path. For an A/B split an if_else may instead take { split: [{ to, percent }, ...] } (2 to 10 shares, whole percents adding to 100, no conditionType): each run goes down one share, picked from the run so it never changes, through a condition_true connection to that to step; no condition_false connection. Set 100 and 0 to send everyone down the winner. change_stage takes { stage }, the name of the stage the lead moves to (a label from flyra_list_pipelines), and an optional { pipelineId }, the bare uuid after pipe_ in flyra_list_pipelines: with it the lead moves into that pipeline on that stage from whichever pipeline it is in; left out, it stays in its own pipeline. For the businesses it is switched on for, a change_stage step whose stage is Lost also takes { lostReason }, text with the same {variables} as a message (at most 500 characters), saved as the lead's lost reason, the one the reports count. add_note takes { note } (text with the same {variables} as a message) and, for the businesses it is switched on for, { target }: \"lead\" (the lead's timeline, the default), \"customer\" or \"job\" (that record's Notes box, the note added below what is there; the step fails rather than overwrite a note someone saved at the same moment). A run with no customer or job for that target skips the step. { target: \"estimate\" } (on a run that carries an estimate, such as an estimate.* trigger) adds the note, starting \"Estimate #<number>: \", to that estimate's customer's Notes box, or to the lead's timeline for an estimate on a lead; it never writes the estimate's own notes, which print on the estimate the customer sees. A run with no estimate skips the step. create_task takes { title, description } (text with the same {variables} as a message) and, for the businesses it is switched on for, { taskAssignee } and { dueInMinutes }. taskAssignee is { to: \"lead_owner\" }, { to: \"person\", employeeId } (the bare uuid after emp_ in flyra_list_employees), { to: \"technician\" } (the first technician on the job), { to: \"salesperson\" } (the job's salesperson), { to: \"role\", role } (of the active team with that role, whoever has the fewest open tasks) or { to: \"round_robin\" } (of the whole active team, whoever has the fewest open tasks). When nobody fits (no technician on the job, the person is no longer active), the task goes to the first admin and the run says why. dueInMinutes (0 to 525600) sets the task due that many minutes after the step runs. assign_lead takes { assignMode: \"specific\", employeeId }, { assignMode: \"round_robin\" } (whoever has the fewest leads) or { assignMode: \"top_performer\" } (this month's top seller). For the businesses it is switched on for it also takes { assignMode: \"fewest_open_leads\" } (counts only leads not Won, Lost or No response) and { assignMode: \"pin_dropper\" } (whoever dropped the newest map pin on the customer; no pin skips the step). A round_robin or fewest_open_leads step may add { skipOffToday: true } (leaves out people with a day off saved for today) and { weights: { <the bare uuid after emp_ in flyra_list_employees>: 1 to 10 } } (only those people are in the draw, and a 2 takes twice the leads of a 1). To assign by ZIP, city, lead source, pipeline or map territory, put an if_else on record_facts_match (customer.zip, customer.city, lead.source, lead.pipeline_id, customer.territories) before a specific assign_lead on each path; customer.territories takes contains and a territory name, and a lead with no customer, or a customer with no map spot, is a No. assign_technician takes { assignMode: \"specific\", employeeId } or { assignMode: \"round_robin\" } (the technician with the fewest jobs ahead) and replaces whoever is on the job. For the businesses it is switched on for it also takes { crewAction: \"add\" } (puts the person on and keeps the rest of the crew), { crewAction: \"remove\" } (takes that person off) and { crewRole: \"salesperson\" } (the job's salesperson instead of its technician); a remove or a salesperson needs a specific employeeId (the bare uuid after emp_ in flyra_list_employees). Adding someone already on the job, or removing someone who is not, skips the step. wait_until takes { mode: \"until\", untilTime: \"HH:MM\", untilDay } to pause until the clock next reads that time in the business's timezone (untilDay is 0 for Sunday to 6 for Saturday; left out, any day), or { mode: \"for\", delaySeconds }. For the businesses it is switched on for it also takes { mode: \"record_date\", dateField, offsetAmount, offsetUnit, direction, time } to wait until a moment set by a date on the record: dateField is one of job.start_time, job.completed_at, invoice.due_date, estimate.sent_at, customer.created_at, subscription.end_date, appointment.start_time, subscription.next_billing_date, subscription.next_visit, customer.first_service; offsetAmount a whole number of offsetUnit (\"days\" or \"hours\"; a calendar date like invoice.due_date, subscription.end_date or subscription.next_billing_date takes days only; subscription.next_visit, the plan's next visit, takes direction \"before\" only; customer.first_service is the customer's earliest job) \"before\" or \"after\" that date, and time (\"HH:MM\", default 09:00, business timezone) for a days offset. When it wakes it reads the date again: a job moved later waits longer. A moment already passed goes on at once; a run with no such record, or a record with no date, skips the step. notify_team takes { title, body } and says who is told: { roles } for everyone in those roles, with each role written as flyra_list_employees shows it (a new list nobody can be reached through is refused; one role of several that reaches nobody is a warning), or { audience: \"people\", employeeIds } for named people only, whatever their role, with employeeIds a list of ids from flyra_list_employees. Named people need audience \"people\": without it the ids are refused, since the step would otherwise tell the whole team. A new automation stops its timed follow-ups for a lead once that lead replies; steps on a wait_for_reply on_reply path still run. stop_on_reply: false keeps it running after a reply, until a stop_if step ends it or it reaches its last step. quiet_hours sets the hours it holds texts; an automation started by a new lead or a form is not held overnight without it. business_hours sets when the business is open: a text or email step due while closed (outside the day's hours, a closed day, or a holiday) waits and goes out at the next open minute, in the business's timezone.To send a different message while closed instead of holding it, branch with an if_else on record_facts_match now.within_business_hours (see the if_else sentence below). if_else takes { conditionType }, and so does stop_if: one of a fixed list of questions, not a field expression: lead_replied, lead_stage_equals, lead_score_over, lead_came_in_after, job_booked, estimate_accepted, invoice_paid, has_active_subscription, has_upcoming_job, is_existing_customer, already_ran_for_customer, has_tipped, job_is_paid, job_value_over, job_from_subscription, is_repeat_customer, last_job_over_days_ago, estimate_answered, invoice_settled, subscription_answered, review_left, cancellation_request_closed, cancellation_fee_applies, custom_field_equals, custom_field_is_set, always_true. if_else and stop_if also take trigger_field_matches and record_facts_match, described below. To branch on the time of day or business hours (a different text after hours), use an if_else on record_facts_match with now.within_business_hours equals true, or now.time_hhmm with lt for a fixed cutoff such as 1800, on lead and customer triggers (call.missed and lead.created included); place it before any delay, since now is read when the step runs. Which of them a run can answer depends on the trigger: one the trigger cannot answer is refused and the answer lists the ones it can. On a job trigger, job_from_subscription asks whether the job is a plan visit. lead_stage_equals also takes { stage }, the lead's stage name (status_stage), not a stage_ id; lead_score_over, job_value_over (cents) and last_job_over_days_ago take { amount }; lead_came_in_after takes { time: \"HH:MM\" }; custom_field_equals takes { customFieldKey, customFieldValue } and custom_field_is_set takes { customFieldKey }. already_ran_for_customer (as a first stop_if: once per person) also takes { reentryWindowDays } (1 to 365: only runs started in that many days count, a cooldown) and { reentryMaxRuns } (1 to 100: Yes needs that many, so { reentryWindowDays: 30, reentryMaxRuns: 3 } is at most 3 per 30 days); stopped runs never count. Frequency cap: max_messages_per_contact_per_day (1 to 50) caps the texts, emails, review asks, payment reminders, receipts and connect calls this automation sends one person in any 24 hours (an automation started by a job price, field, crew or upsell change gets 3 when none is set); over the cap the send is skipped and the run continues. Re-entry and cooldown are the already_ran_for_customer stop_if settings. has_active_subscription is Yes when the customer is on an active plan. For trigger_event cancellation.requested (someone pressed Request cancellation and the plan went to the Save Center; the plan stays active and nothing is cancelled): a stop_if with cancellation_request_closed ends the run once the request is marked saved or cancelled, checked again every time a wait ends, so place it right after the trigger; cancellation_fee_applies is Yes when cancelling would cost the customer the plan's cancellation fee (a fee on the plan, and a completed visit when the plan charges only after the first one). Neither charges anything. To skip events that arrive while closed instead of holding them, set config.outsideHours: \"skip\" on the trigger step (default \"run\"): an event that comes in outside the day's hours, on a closed day or on a holiday starts no run at all, and is not started later. With no business_hours set the business is always open, so nothing is skipped. if_else takes { conditionType }, and so does stop_if: one of a fixed list of questions, not a field expression: lead_replied, lead_stage_equals, lead_score_over, lead_came_in_after, job_booked, estimate_accepted, invoice_paid, has_active_subscription, has_upcoming_job, is_existing_customer, already_ran_for_customer, has_tipped, job_is_paid, job_value_over, job_from_subscription, is_repeat_customer, last_job_over_days_ago, estimate_answered, invoice_settled, subscription_answered, review_left, cancellation_request_closed, cancellation_fee_applies, custom_field_equals, custom_field_is_set, always_true. if_else and stop_if also take trigger_field_matches and record_facts_match, described below. To branch on the time of day or business hours (a different text after hours), use an if_else on record_facts_match with now.within_business_hours equals true, or now.time_hhmm with lt for a fixed cutoff such as 1800, on lead and customer triggers (call.missed and lead.created included); place it before any delay, since now is read when the step runs. Which of them a run can answer depends on the trigger: one the trigger cannot answer is refused and the answer lists the ones it can. On a job trigger, job_from_subscription asks whether the job is a plan visit. lead_stage_equals also takes { stage }, the lead's stage name (status_stage), not a stage_ id; lead_score_over, job_value_over (cents) and last_job_over_days_ago take { amount }; lead_came_in_after takes { time: \"HH:MM\" }; custom_field_equals takes { customFieldKey, customFieldValue } and custom_field_is_set takes { customFieldKey }. already_ran_for_customer (as a first stop_if: once per person) also takes { reentryWindowDays } (1 to 365: only runs started in that many days count, a cooldown) and { reentryMaxRuns } (1 to 100: Yes needs that many, so { reentryWindowDays: 30, reentryMaxRuns: 3 } is at most 3 per 30 days); stopped runs never count. Frequency cap: max_messages_per_contact_per_day (1 to 50) caps the texts, emails and review asks this automation sends one person in any 24 hours; over the cap the send is skipped and the run continues. Re-entry and cooldown are the already_ran_for_customer stop_if settings. has_active_subscription is Yes when the customer is on an active plan. For trigger_event cancellation.requested (someone pressed Request cancellation and the plan went to the Save Center; the plan stays active and nothing is cancelled): a stop_if with cancellation_request_closed ends the run once the request is marked saved or cancelled, checked again every time a wait ends, so place it right after the trigger; cancellation_fee_applies is Yes when cancelling would cost the customer the plan's cancellation fee (a fee on the plan, and a completed visit when the plan charges only after the first one). Neither charges anything. trigger_field_matches works on every trigger: it asks about the details the trigger itself sent (the payload, such as rep_id, amount_cents, service_id, outcome, reason) and takes { triggerFieldRules: [{ field, operator, value }], triggerFieldMatch: \"all\" | \"any\" }, 1 to 10 rules, operator one of equals, not_equals, in, gt, lt, contains, exists; gt/lt take a number (money in cents), in takes a list, exists takes no value. A detail the trigger did not send is a No. For trigger_event save_request.moved (switched on for some businesses only) the payload carries request_id, kind (subscription or job), subscription_id, job_id, column_id (new, one of the board's own column ids, saved, or cancelled), column_title and outcome (moved, saved when the request is closed as saved, or lost when it is closed as cancelled, whoever cancelled it), save_offer (what saved them, one of the business's save offers, set when outcome is saved, otherwise null) and reason (the cancellation reason, or null); pick a column with trigger_field_matches on column_id or column_title. To run only when a request is saved, add a trigger_field_matches condition with the rule { field: \"outcome\", operator: \"equals\", value: \"saved\" }, plus a save_offer equals rule to run only for one offer (there is no separate save_request.saved trigger). For trigger_event save_request.assigned (switched on for some businesses only; someone took an open Save Center request, or it was given to a team member; an unassign does not fire it) the payload carries request_id, kind (subscription or job), subscription_id, job_id, assigned_to (the employee id who has it now) and assigned_by (the employee id who pressed, the same id when they took it themselves); pick a person with trigger_field_matches on assigned_to. For trigger_event job.touch_up_booked (switched on for some businesses only) the payload carries job_id (the rated visit), touch_up_job_id, outcome (booked, or none_fit when none of the offered times worked and the customer was told the office will call), rating_stars, rating_score (on a 10-point scale, when the business uses one), start_at (the booked time, or null) and technician_id; pick a rating with trigger_field_matches on rating_stars or rating_score. For trigger_event employee.clocked_in it runs on each clock in and clock out, from the web or the iPhone app (not a shift added or fixed on the timesheet). The trigger step takes optional config.clockDirection, in or out (blank runs on both), and optional config.clockRoles, a list of roles as flyra_list_employees shows them (blank runs for everyone). The payload carries employee_id, role, direction, time_entry_id and at. For trigger_event employee.forgot_clock_out the trigger step takes config.hours, how long after the team member's day ended they may stay clocked in before it fires (default 1, up to 24, fractions allowed). The day ends at the later of their last job that day and the end of their working hours; with neither, it never fires. Checked hourly, once per shift per automation. The payload carries employee_id, time_entry_id, clocked_in_at, last_job_end, workday_end, overdue_at and hours. For trigger_event campaign.response_rate_low the trigger step takes config.rate_percent (default 5), config.after_hours, how long after the send to judge it (default 72, up to 336), and config.min_recipients, the smallest blast it judges (default 20). A follow up send counts as its own blast. It fires once per blast when the people who texted back inside that window, leaving out keyword texts such as STOP and phones with no thread, come in under the rate. It has no customer on it, and it does not pause anything by itself. The payload carries batch_id, sent_at, recipients, replies, rate_percent, threshold_percent and after_hours. For trigger_event sms_credits.low the trigger step needs config.balance, a whole number of SMS blast credits (1 to 1000000). It fires when a blast, a follow up or another send takes the balance from that number or more to under it, once per crossing: a top up back over it and a later drop fires again. It has no customer on it. The payload carries balance (after), balance_before, delta, reason and source. For trigger_event sms_blast.completed it runs once a text blast, or one of its follow ups, has gone out and been saved, from the app or flyra_send_sms_blast. It has no customer on it; tell the team with notify_team. The payload carries batch_id, sent_count, is_follow_up (true for a follow up send), has_follow_ups (true when follow ups are scheduled after it) and sent_by (app or connector), plus requested_count and failed_count on app sends. A follow up is saved as its own blast, so its batch_id is its own. For trigger_event sms_blast.no_reply it runs once for each person a text blast reached (with a customer or lead) who has not texted back config.days days after the blast went out (default 3, 1 to 30), on their lead or customer; the audience is the built-in follow-up's no-reply list, so a failed first text or a deleted record never counts. Optional config.blast_id (blast_… from flyra_list_sms_blasts) keeps one blast; left out, every blast counts. A blast sent before the automation was switched on never fires. The payload carries batch_id, sent_at, to_phone and waited_days. For trigger_event job.completed_nearby it runs at most once per neighbour every 30 days, for each neighbour within config.radius_miles (default 1, 0.1 to 25) of a job just completed, measured from that job's customer's map location: a past customer runs on their customer record (the job's own customer is left out), a map pin that matches no customer runs team-only with pin_id, pin_address, pin_client_name and pin_mobile. config.audience is customers, pins or both (default both). Leads carry no map location, so they are never reached. A job completed before the automation was switched on never fires. The payload carries completed_job_id, completed_job_title and radius_miles (never job_id: the run is about the neighbour, not the finished job). For trigger_event sms_blast.replied it runs when someone a text blast reached in the last 30 days texts back (never for STOP or START), once per reply, for the newest blast that reached them, on their customer or lead. The trigger step takes optional config.blast_id (blast_… from flyra_list_sms_blasts) to keep one blast, and optional config.keywords with config.matchMode and config.matchType exactly as for customer.reply_matched; left out, every blast reply counts. The payload carries batch_id, sent_at, text, from_phone, to_phone and message_id. For trigger_event message.unanswered the trigger step takes config.minutes, how long after an inbound text with no team reply it fires (default 30, up to 1440), and config.business_hours_only: true starts the clock at the next opening for a text that came in closed and only fires while open. It fires once per unanswered stretch of a thread, only a message a person sent counts as a reply, and keyword texts such as STOP do not count. A thread may have no customer or lead on it. The payload carries contact_id, message_id, received_at, overdue_at, minutes and business_hours_only. For trigger_event customer.ltv_milestone the trigger step takes config.amount_cents, the lifetime value that fires it; with no amount it fires nothing. Lifetime value here is the amount on the customer's finished jobs. It fires once per customer per amount, when a finished job carries the total to the amount, and never when the job that crosses it was imported. The payload carries job_id, lifetime_value_cents, crossed_at and amount_cents. For trigger_event customer.balance_overdue the trigger step takes config.amount_cents, the customer's total overdue balance across invoices that fires it (default any balance), and config.days, how many days past its due date an invoice must be to count (default 1, up to 365). It fires once per invoice that tips the total, so crossing again on a new invoice fires again. Imported invoices never count. The payload carries invoice_id, overdue_balance_cents, overdue_invoice_count, crossed_at, amount_cents and days. For trigger_event customer.lapsed the trigger step takes config.days, how long after the customer's last finished job it fires (default 90, up to 3650), and optional config.has_plan: true only customers with an active plan, false only customers without one, unset both. It fires once per last job, skips a customer with a job booked ahead, and never fires for a customer never served or whose last job was imported. The payload carries last_job_id, last_service_at, lapsed_at and days. For trigger_event schedule.open_slot the trigger step takes config.min_minutes, the shortest slot that counts (default 60, up to 720). A slot is part of tomorrow's working hours not covered by a job or a break, for technicians with hours set tomorrow and anyone with a job tomorrow; business hours stand in when a person with a job has no hours set. Not on a day off, and anytime jobs do not fill time. Checked hourly from 5 PM in the business's timezone, once per person per slot start time per automation, so a later cancellation can fire a new one. An automation saved after 5 PM starts the next day. The payload carries date, employee_id, slot_start, slot_end, minutes and min_minutes. For trigger_event schedule.overbooked the trigger step takes optional config.technician_id for one person; without it everyone counts. Fires when a job on today or the next six days ends after that person's working hours end, or the business hours when they have no hours set that day. Not on a day off, and anytime jobs or jobs with no end time do not count. A day already over with nothing changed since the automation was saved does not fire. Checked hourly, once per person per day per automation. The payload carries employee_id, date, workday_end, last_job_end, over_minutes and job_id. Instead of trigger_event you may pass trigger_object with trigger_action (and trigger_status for status_changed); it saves as the real trigger_event and the answer shows which. Pairs: lead created = lead.created, updated = lead.custom_field_changed, status_changed = lead.stage_changed; customer created = customer.created, updated = customer.updated, deleted = customer.deleted; job created = job.created, updated = job.field_changed, deleted = job.deleted, status_changed = job.field_changed; appointment booked = appointment.booked, rescheduled = appointment.rescheduled, cancelled = appointment.cancelled, completed = appointment.completed; estimate created = estimate.created, sent = estimate.sent, accepted = estimate.accepted, declined = estimate.declined; invoice created = invoice.created, sent = invoice.sent, paid = invoice.paid, viewed = invoice.viewed, overdue = invoice.overdue; payment received = payment.received; subscription activated = subscription.activated, cancelled = subscription.cancelled; task created = task.created, completed = task.completed; territory created = territory.created, assigned = territory.assigned; employee invited = employee.invited, joined = employee.joined, deactivated = employee.deactivated. A lead status_changed takes trigger_status, the stage (saved as config.triggerStage). A job status_changed with trigger_status started, in_progress, completed or cancelled saves as job.started, job.completed or job.cancelled; scheduled, on_the_way, arrival, paid or review_sent watches job.field_changed on status equal to it, any other word is refused with the list of job statuses, and none watches every status change. Any other pair is refused with this list. For trigger_event cash.low_collections the trigger step takes config.collected_under_cents (fires when completed payments since Monday on the business's clock are under it), config.unpaid_over_cents (fires when what open invoices still owe is over it), or both; at least one is required. Optional config.day (default \"fri\") and config.time (default \"16:00\"), when the week is checked. Fires at most once per automation and week, never for a check already past when the automation was saved. Imported payments and invoices do not count. It carries no customer: one run for the business, never a send to a customer list. The payload carries week_start, collected_cents, collected_under_cents, unpaid_cents, unpaid_over_cents, low_collections and high_unpaid. For trigger_event season.started the trigger step needs config.season: spring (Mar 20), summer (Jun 21), fall (Sep 22), winter (Dec 21), or custom with config.month (1 to 12), config.day and config.label (Feb 29 is refused). Optional config.time, default \"09:00\" on the business's clock. Fires once per automation, season and year, checked hourly, never for a day already past when the automation was saved. It carries no customer: one run for the business, never a send to a customer list. The payload carries season, label and year. For trigger_event sprint.started the trigger step takes config.when, start (default) or end. Fires when the sprint's start or end date passes, once per sprint and date, for sprints not archived or cancelled, and not for a date before the automation was saved or more than two days ago. Moving a sprint's date can fire it again. Checked hourly. The payload carries campaign_id, name, phase, start_date, end_date and leaderboard_type. For trigger_event revenue_goal.reached the trigger step takes config.when, reached (default) or behind, and optional config.goal_id for one dashboard goal; without it every goal running today counts, job count goals included. Reached fires once per goal, dates and target. A goal already at target on the jobs that existed when the automation was saved does not fire. Behind fires once per goal and dates when less of the goal is done than of its time has gone, from a quarter of the way through; a goal already behind pace on the jobs that existed when the automation was saved does not fire for those dates. Checked hourly. The payload carries outcome, goal_id, goal_type, current_value, target_value, progress_percentage, start_date and end_date. For trigger_event employee.missed_clock_in the trigger step takes config.grace_minutes, how long after the person's working hours start they may go without clocking in (default 15, up to 240). The shift is their working hours for today in the business's timezone, so a person with no hours set today does not fire. Only for active people the time clock applies to, with the time clock on, and never after the shift has ended. Checked every five minutes, once per person per day per automation. The payload carries employee_id, date, shift_start, shift_end and grace_minutes. For trigger_event subscription.paused it runs when a plan is paused, on the web or by flyra_pause_subscription, once per pause, after it is saved. The run is about the plan's customer. The payload carries subscription_id, reason (empty when none was given) and source (web or connector); filter with trigger_field_matches on reason or source. subscription.resumed runs when a paused plan is resumed the same ways, with subscription_id and source. Nothing is sent unless a step sends. For trigger_event subscription.signed it runs when the customer signs a plan that had no signature, from the plan link or in person on the web or the app, after the signature is saved and whether or not the plan is active yet. A replaced signature and a plan signed while it is being created do not fire. The payload carries subscription_id, signed_at and source (link or in_person); filter with trigger_field_matches on source. Nothing is sent unless a step sends. For trigger_event subscription.viewed it runs when the customer opens the plan link. A link preview (iMessage, Slack, an email scanner) and a second open within 30 minutes of the last one do not fire, but every open is counted. The payload carries subscription_id, view_count (opens so far, this one included), first_view (true on the first open) and status; filter with trigger_field_matches, for example first_view equals true to run on the first open only. Nothing is sent unless a step sends. For trigger_event subscription.visit_skipped it runs when a visit of a plan is cancelled (kind skipped; not when the plan itself is cancelled) or given a new date still ahead (kind moved), on the web, the current app or the connector, after it is saved (a change made another way, such as an older iPhone build, does not fire it). The run is about the visit's job and the plan's customer. The payload carries subscription_id, job_id, kind, job_title, start_time, previous_start_time (moved only) and is_initial_visit; filter with trigger_field_matches, for example kind equals skipped. reschedule_job cannot be a step of it (the move would start it again). Nothing is sent unless a step sends. For trigger_event subscription.visit_completed it runs when a visit of a plan is completed, on the web, the current app or the connector (a change made another way, such as an older iPhone build, does not fire it). The run is about the visit's job and the plan's customer. The payload carries subscription_id, job_id, job_title, visit_number (1 is the plan's earliest visit not cancelled, the same count as the plan visit number condition; null when the visit has no date), is_initial_visit, is_last_of_year (no later visit of the plan in the same calendar year, in the business's time zone), next_visit_at and completed_at. For only the Nth visit filter with trigger_field_matches, for example visit_number equals 2, visit_number gt 1 for every visit after the first, is_initial_visit equals true, or is_last_of_year equals true. Nothing is sent unless a step sends. For trigger_event estimate.optional_item_changed it runs when an estimate is accepted (the customer's page or signing in person) with an optional item set differently from how it started: once per item, change \"added\" for an item that started unticked and was ticked, \"removed\" for one that started ticked and was unticked. An item left as it started fires nothing. The run is about the estimate's lead, or its customer when there is no lead. The payload carries estimate_id, item_id, item_name, change and amount_cents; pick an item or a direction with trigger_field_matches on item_name, item_id or change. Nothing is sent unless a step sends. For trigger_event invoice.created it runs when a new invoice is saved with its lines: on the web or iPhone, from a job, by the automatic invoice on job completion, from an estimate, or by flyra_create_invoice. The run is about the invoice's customer. The payload carries invoice_id, invoice_number, total_cents, job_id and source (web, job, auto_on_completion, estimate or connector); filter by amount with trigger_field_matches on total_cents (gt or lt, in cents) or by source. Imports and a blank draft opened in the invoice editor do not fire it. Nothing is sent unless a step sends. For trigger_event subscription.not_accepted the trigger step takes config.days (default 3, 1 to 90): it fires that many days after a plan was sent when it is still pending, not declined and never started, once per send (a re-sent plan can fire again). subscription.term_ending takes config.days_before (default 30, 0 to 365): it fires that many days before the end_date of an active or paused plan that does not renew itself (auto-renewing plans never fire it), once per plan and end date. invoice.split_second_due takes config.days_before (default 3, 0 to 60): it fires that many days before the due date of an open invoice that allows split payment, has its first part paid and still owes a balance, once per invoice and due date. All three are checked every five minutes, arm on the moment crossed (a moment before the automation was saved never fires, and none fires more than a day late), and run about the record's customer. Payloads: subscription_id, subscription_name, amount_cents and sent_at or end_date; invoice_id, invoice_number, due_date, total_cents, paid_amount_cents, balance_cents. Nothing is sent unless a step sends. For trigger_event subscription.anniversary the trigger step takes config.years: blank fires on every yearly anniversary, a number (1 to 50) only on that one. The anniversary is the day the plan started on the business's calendar (activated, else its start date), for active and paused plans, from 9 AM local, once per plan and year; a Feb 29 start fires on Feb 28 in other years. Payload: subscription_id, subscription_name, years, anniversary_date, started_on. For trigger_event subscription.churn_risk the score is the Retention report's own. config.min_level is high (default, a score of 55 or more) or medium (30 or more); config.signals, when set, keeps only plans showing one of these signals (matched as part of the signal text, any case): No visit in, Visit cancelled, visits cancelled, Waiting on reschedule, Overdue visit, Payment failed, review, Nothing scheduled, No card, visit soon. config.cooldown_days (default 30, 1 to 365) is how long before the same plan can fire again. Checked once a day in the 9 AM hour. Payload: subscription_id, customer_name, plan_label, risk_score, risk_level, risk_signals. For trigger_event card.expiring the trigger step takes config.days_before (default 30, 1 to 90): it fires when the saved card an active auto-charged plan bills expires within that many days (the end of its expiry month, read from Stripe once a day in the 9 AM hour), once per card and expiry, so a new card arms it again, and only for a card that comes inside that window after the automation was last saved (a card already inside it at the save never fires). A plan charged on Whop is read from Whop. Pair it with send_link linkKind add_card to ask for a new card. Payload: subscription_id, subscription_name, card_brand, card_last4, exp_month, exp_year, days_left. All three run about the plan's customer; nothing is sent unless a step sends. For trigger_event job.series_ending the trigger step takes config.visits_left and config.days_before: it fires when that many visits or fewer remain (default 1, up to 52) and the last one is within that many days (default 14, up to 365). A series is what the job page calls one: jobs with the same customer and title, a recurring tag in the title, not plan visits. Checked hourly, once per last visit per automation, so booking more visits can fire it again later. The payload carries job_id (the last visit), title, last_visit_at, next_visit_at and visits_left; the customer is the person on the run. For trigger_event job.unassigned_soon the trigger step takes config.hours, how long before the start time to check (default 2, up to 72). Checked every five minutes, once per job and start time per automation, for open jobs with no technician on them or on a published route. Anytime jobs have no start time to count back from and do not fire. The payload carries job_id, title, start_time and hours; the customer on the job is the person on the run. For trigger_event call.voicemail_left it runs when any caller (a customer, a lead or a number the business does not know) leaves a voicemail on a Flyra line, once per voicemail, after the audio is saved. The run's person is the customer or lead behind the number, when there is one. The payload carries session_id, message_id, from_number, to_number (the business line that was called), duration_seconds and transcript (null when it could not be transcribed or no one spoke in it); pick a line with trigger_field_matches on to_number, or a length with gt or lt on duration_seconds. For trigger_event lead.voicemail_left it runs when a caller whose number belongs to a lead (and to no customer) leaves a voicemail, once per voicemail, for that lead. The payload is the same as call.voicemail_left's: session_id, message_id, from_number, to_number (the business line that was called), duration_seconds and transcript; pick a line with trigger_field_matches on to_number, or a length with gt or lt on duration_seconds. For trigger_event call.completed it runs when an answered phone call on a Flyra line ends, inbound or outbound, once per call. The run's person is the customer or lead behind the other number, when there is one. The payload carries session_id, direction (inbound or outbound), outcome (completed), duration_seconds (talk time from the answer), total_seconds (from the first ring), hangup_cause, from_number and to_number; pick a direction with trigger_field_matches on direction, or a length with gt or lt on duration_seconds. For trigger_event call.outbound_no_answer it runs when a call the business makes from a Flyra line ends without being answered (no answer, busy or declined), once per call. The run's person is the customer or lead behind the number that was called, when there is one. It has no attempt count: each unanswered call fires it. The payload carries session_id, direction (outbound), outcome (no_answer, busy or declined), duration_seconds (talk time, 0 when nobody answered), total_seconds (from the first ring), hangup_cause, from_number and to_number; pick an outcome with trigger_field_matches on outcome. Optional config.shortCallSeconds (1 to 60) also runs it for an answered outbound call with less talk time than that (outcome short_call, often voicemail picking up); without it a short call never runs this automation. A rep can also mark an ended call no_answer or voicemail with flyra_set_call_outcome, which runs it once for that call with marked_by_agent true. For trigger_event call.transcript_ready it runs when a recorded call's transcript is saved, once per call. A call nobody spoke on gets no transcript and does not fire; voicemails use call.voicemail_left. The run's person is the customer or lead behind the other number, when there is one. The payload carries session_id, message_id (the call in the inbox, when filed), direction, from_number, to_number, duration_seconds (talk time) and transcript; match a keyword with trigger_field_matches contains on transcript. For trigger_event call.menu_option_pressed it runs when a caller presses a key set up in the line's phone menu, once per call, as the call is routed. A key with no option, or no key at all, does not fire. The run's person is the customer or lead behind the caller's number, when there is one. The payload carries session_id, digit, option_label, route (ring_all, ring_users, forward or voicemail), from_number and to_number (the business line that was called); pick an option with trigger_field_matches on digit or option_label. For trigger_event employee.knocking_session_started (the session.started event) it runs when a rep starts a door knocking session by hand on the phone app, once per session; a resume after a pause and the phone's own automatic sessions do not count, and it arrives with the phone's next telemetry upload (about a minute). The run is about the rep ({first_name}, {employee_name}); no customer is on it, so use team steps such as notify_team (audience \"assignee\" reaches that rep alone). To run it for one rep only, add trigger_field_matches on employee_id (the bare uuid after emp_ in flyra_list_employees). The payload carries employee_id, employee_name, employee_email, employee_phone, assigned_user_id, session_key, started_at, lat and lng. For trigger_event employee.knocking_session_ended (the session.ended event) it runs when a rep finishes a door knocking session on the phone app, once per session. The run is about the rep ({first_name}, {employee_name}, {doors_knocked}, {session_sales}, {session_minutes}); no customer is on it, so use team steps such as notify_team. The payload carries employee_id, knocking_session_id, doors_knocked, sales, session_minutes, duration_seconds, distance_meters, status_counts, outcome, feeling, started_at and ended_at. For a threshold such as fewer than 20 doors, use trigger_field_matches with gt or lt on doors_knocked or sales. For trigger_event employee.document_expiring the trigger step takes config.daysBefore (default 30, up to 365): it runs when a file on an employee's record (a licence, insurance or certification) runs out within that many days, counted on the business's calendar. Set the date with flyra_add_employee_file expires_on or flyra_set_employee_file_expiry. Checked hourly, once per file and expiry date per automation, so a new date fires again; a file already past its date does not fire. The run is about the employee ({first_name}, {employee_name}); no customer is on it, so use team steps such as notify_team. The payload carries employee_id, file_id, filename, expires_on and days_until. For trigger_event inventory.maintenance_due the trigger step takes config.everyDays (1 to 3650) and/or config.everyUses (1 to 10000, one check out is one use), and optionally config.equipmentIds (ids from flyra_list_equipment; all items when left out). With neither count set it never fires. It runs when an item reaches either count since its last service (last_serviced_at, or when it was added if never serviced). Checked hourly, once per item and service cycle per automation; flyra_mark_equipment_serviced starts the next cycle. The payload carries item_id, item_name, last_serviced_at, days_since, uses_since and reason (days, uses or days_and_uses). For trigger_event pin.revisit_due the trigger step takes config.days (default 3, from 1 to 90). It runs when a map pin is still marked revisit that many days after it was last changed. Map pins keep no follow-up date, so the clock is the pin's last edit: any edit to the pin (a note, a new photo, a re-save) restarts the count, and the pin can fire again that many days after each edit while it stays on revisit. Checked every five minutes, once per pin and edit for each automation, and only for moments after the automation was saved. No customer is on the run, even when the pin is linked to one, so steps that text or email a customer are not offered: an edit by anyone re-arms the pin, and a customer must not be messaged again each time. The payload carries pin_id, pin_address, pin_client_name, pin_mobile, pin_notes, created_by_name and assigned_user_id (the rep who dropped the pin), so notify_team with audience \"assignee\" reaches that rep. For trigger_event employee.team_chat_mentioned it runs when a team chat message @mentions someone in that chat (the \"@First Last\" the chat box inserts when you pick a person), once per person mentioned; the sender mentioning themself does not count, and a message posted by an automation's post_team_chat step never fires it. The run is about the person mentioned ({first_name}, {employee_name}, {mentioned_by_name}, {team_message}); no customer is on it, so use team steps: notify_team with audience \"assignee\" reaches only the person mentioned. The payload carries employee_id, employee_name, employee_email, employee_phone, assigned_user_id (the person mentioned), conversation_id, team_message_id, mentioned_by_user_id, mentioned_by_name and message_body (the first 1000 characters). For trigger_event employee.territory_crossed it runs when a team member's live location on the phone app moves into (\"enter\") or out of (\"leave\") one of the business's map territories. The trigger step takes config.territoryIds (the terr_ ids from flyra_list_territories, or the bare uuid after terr_; left out, every territory) and config.direction (\"enter\", \"leave\" or \"both\", the default). It only sees people sharing their live location during the business's tracking hours; a reading less accurate than 100 metres, or one more than 15 minutes after the last, does not count, and the same person, territory and direction fires at most once per 15 minutes. The run is about the team member ({first_name}, {employee_name}); no customer is on it, so use team steps: notify_team with audience \"assignee\" reaches that person alone. The payload carries employee_id, employee_name, employee_email, employee_phone, assigned_user_id, territory_id, territory_name, direction, lat and lng. For trigger_event task.due the trigger step takes config.minutes_before (default 0, from 0 to 1440). It runs when an open task reaches its due time, or that many minutes before it, checked every five minutes, so the alert lands within five minutes of the moment. Give the task a due time (an ISO timestamp); a due date with no time counts from midnight UTC. Moving the due time makes it fire again for the new time. Completed tasks never fire. The run is about the task, not a customer, so steps that message a customer do not run; use notify_team (audience \"assignee\" for the task's owner) and notify_admin. Notify team and Notify admin texts can use {task_title}, {task_notes}, {task_due_clause}, {task_assignee_name}, {task_set_by_name}, {task_customer_name} and {task_customer_phone}. The payload carries task_id, task_title, task_notes, assigned_user_id, due_date, is_team, task_assignee_name, task_set_by_name, task_customer_id, task_customer_name and task_customer_phone. By contrast task.overdue counts in days past the due date (config.daysAfter, default 1) and is checked once an hour. Callback alarm recipe: create the callback with flyra_create_task (a due_date with a time, and the customer_id), then save one automation: trigger_event task.due, then notify_team with audience \"assignee\" and a push, then notify_admin with an office text such as \"Callback due: {task_title} for {task_customer_name} {task_customer_phone}\". Both are team alerts; nothing goes to the customer. For trigger_event tip_page.opened_no_tip the trigger step takes config.hours (1 to 720, default 24). It runs that many hours after a customer first opened a job's tip page (the job tip link, or a plan's tip link) when that job still has no tip by any path. Only the first open counts. Checked hourly, once per job per automation, and only for opens whose wait comes due after the automation was saved. The run carries the job and the customer, so {tip_link} works in a message step. The payload carries job_id, customer_id, opened_at and hours_since_open. For trigger_event weather.forecast_alert the trigger step takes config.hoursAhead (1 to 72, default 24), config.conditions (a list of rain, freeze, wind and heat; all four when left out), config.rainPercent (chance of rain, default 60), config.windMph (default 25) and config.heatF (default 95); freeze means 32F or colder. It reads the US National Weather Service hourly forecast for the start hour of each open, timed job starting within hoursAhead, at the job's property (or the customer's address). US addresses only; a job with no map location, or an anytime job, never fires. Checked hourly, once per job, start time and condition per automation, so a moved job can fire again. The run carries the job and the customer. The payload carries job_id, title, start_time, condition, value (the percent, mph or degrees F that met it) and forecast_time. For trigger_event google_review.posted the trigger step takes optional config.minStars and config.maxStars (1 to 5), such as maxStars 3 for a bad review. It reads the business's Google listing (the listing set in settings, or the review link) about every 6 hours, checked hourly, and runs once per review published after the automation was saved. Google shows only 5 reviews at a time, so on a busy day a review can be missed; when the review count went up and none of the 5 is new, it runs once with no rating (only when neither minStars nor maxStars is set). The customer is on the run only when exactly one customer matches the reviewer's first name and last initial; otherwise the run has no customer, so use team steps such as notify_team. The payload carries rating, author (first name and last initial), text, publish_time, and review_count on the count-only run. For trigger_event google_calendar.event_created the trigger step takes optional config.employeeId (an id from flyra_list_employees: only that team member's calendar) and config.keyword (the event title contains it, any case, up to 80 characters). It runs when someone adds an event to the Flyra calendar a team member connected in Google Calendar. Flyra can only see the Flyra calendar it made, never anyone's personal calendar, so an event on another calendar never fires. Flyra's own job and blocked-time events never fire. Checked every five minutes, once per event per automation, and only for events created after the automation was saved. The run is about the team member, never a customer, so use team steps such as notify_team. The payload carries employee_id, employee_first_name, employee_name, employee_email, employee_phone, event_id, title, start, end, html_link and created_at. record_facts_match works on lead and customer triggers for the businesses it is switched on for (a save elsewhere is refused with the conditions that business has): it reads the run's own customer, lead, job, estimate, invoice and plan when the step runs, and takes { factRules: [{ field, operator, value }], factMatch: \"all\" | \"any\" } with the same operators and limits; field is one of customer.texts_opted_out (Opted out of texts), customer.emails_opted_out (Opted out of email), customer.has_email (Has an email), customer.has_phone (Has a phone), customer.tags (Tag labels (as shown in the app) or tag names), customer.city (City), customer.zip (ZIP or postal code), customer.territories (Map territory names their geocoded address is inside), customer.booked_work_cents (Total spend: booked work on jobs not cancelled, in cents), customer.jobs_count (Number of jobs not cancelled), customer.open_balance_cents (Open balance, in cents), customer.days_since_last_contact (Days since the last text either way), customer.last_rating (Rating left on the last review (1 to 5)), customer.has_card_on_file (Has a card Flyra can charge on a plan that is not cancelled, checked with Stripe (a card saved outside a plan is not seen)), lead.source (Lead source), lead.stage (Stage), lead.owner_id (Assigned user id), lead.pipeline_id (Pipeline id (the bare uuid after pipe_ in flyra_list_pipelines)), lead.value_cents (Lead value, in cents), lead.days_in_stage (Days in the current stage), job.services (Service names on the job), job.technician_ids (Technician employee ids), job.from_plan (Is a plan visit), job.total_cents (Job total, in cents), job.photo_count (Photos on the job), job.day_of_week (Day it is scheduled (0 Sunday to 6 Saturday)), job.first_plan_visit (Is the first visit of its plan (a job on no plan is a No either way)), job.plan_visits_per_year (Visits a year on the job's plan (12 monthly, 4 quarterly)), job.checklist_complete (Every checklist item on the job is done (a job with no checklist is a No either way)), job.territories (Map territory names the job's address is inside), reply.hours_since_last_inbound (Hours since the person last texted in), reply.texts_sent (Texts sent to the person so far, by anyone (automations and the team); queued, scheduled and failed ones do not count), now.day_of_week (Today in the business timezone (0 Sunday to 6 Saturday)), now.hour (Hour now in the business timezone (0 to 23)), reply.last_inbound_text (Words of the last text the person sent in (use contains for a keyword)), now.time_hhmm (Time now in the business timezone as HHMM (830 is 8:30 am, 1730 is 5:30 pm)), now.within_business_hours (Now is inside the business hours set in Settings (closed days are a No)), estimate.status (Estimate status), estimate.viewed (Estimate was opened), estimate.total_cents (Estimate total, in cents), invoice.status (Invoice status), invoice.balance_cents (Invoice balance, in cents), invoice.days_overdue (Days past the due date), estimate.deposit_paid (Deposit was paid (an estimate that asks for no deposit is a No either way)), estimate.chosen_option (Name of the option the customer picked (Good, Better, Best…)), plan.status (Plan status (such as active, paused or past_due)), plan.days_until_next_visit (Calendar days in the business timezone until the plan's next visit that is not cancelled (tomorrow is 1)), now.is_public_holiday (Today, in the business timezone, is a major public holiday in the US or Canada (new year, Memorial Day, Independence Day, Labor Day, Thanksgiving, Christmas, Canada Day, Boxing Day); a business anywhere else reads No), customer.created_at (When the customer was added), customer.state (State or province), lead.from_map_pin (The lead was added from a map pin), lead.from_qr_sign (The lead came in from a QR code, yard sign, door hanger or flyer link), reply.texts_since_last_reply (Texts sent to the person since they last texted in (every text sent if they never have); queued, scheduled and failed ones do not count), lead.created_at (When the lead came in), lead.last_inbound_at (When the lead last messaged in), lead.last_outbound_at (When the lead was last messaged), lead.stage_changed_at (When the lead last changed stage), lead.city (Lead city), lead.state (Lead state or province), lead.postal_code (Lead ZIP or postal code), lead.service_type (Service the lead asked about), lead.email (Lead email), lead.phone (Lead phone), lead.score (Lead score), lead.opted_out (Lead opted out), job.service_categories (Price book categories of the services on the job, matched by service name; a line typed by hand has none), job.status (Job status), job.start_time (When the job is scheduled), job.completed_at (When the job was completed), estimate.sent_at (When the estimate was sent), estimate.expires_at (When the estimate expires), estimate.last_viewed_at (When the estimate was last opened), invoice.due_date (Invoice due date), invoice.sent_at (When the invoice was sent), invoice.paid_at (When the invoice was paid), or custom.<key> for one of the business's lead or customer custom fields from flyra_list_custom_fields (number and currency in dollars, checkbox true or false, select the option value, date YYYY-MM-DD; an unanswered field is a No). A list fact (tags, territories, services, technicians) takes contains, exists or is_empty only; for \"does not have\", use contains and act on the No branch. Two more operators work here only: is_empty (no value) on any fact but a true or false one or territories, and within_last_days with a whole number of days as value, on a date fact or custom.<key>; the future is a No. Several rules with factMatch is a build-your-own If/else; an item in factRules can also be a group { match: \"all\" | \"any\", rules: [...] } for A and (B or C), up to two groups deep and 30 rules in all. A fact the run has no record for is a No, on every operator. send_sms also takes jobPhotos: { which: \"before\", \"after\" or \"both\", max: 1 to 4 } for the businesses it is switched on for: the job's before and/or after photos (the quality check boxes marked before and after; plain job photos are not tagged and are never picked) ride the text as pictures and the email as attachments, befores first. A run with no job, or a job with no such photos, skips the whole message rather than sending it without them, so put the photos in their own send_sms step when the words must go regardless. Not on send_review_request. update_task takes { tasks, action } for the businesses it is switched on for. tasks is \"this_run\" (the task that started the run, on a task trigger, and the tasks this run's create_task steps made) \"linked\" (open tasks any automation made for this lead, plus the customer's open tasks), or \"job\" (open tasks any automation run for this job made; a run with no job skips). action is \"complete\", \"reassign\" with taskAssignee (same shape as create_task's), or \"due\" with dueInMinutes (the due time becomes that many minutes after the step runs). Optional titleContains (1 to 80 characters) keeps only tasks whose title has it, such as \"call back\". Only open tasks change, up to 25 a step; completing one fires task.completed like the app. Nobody fits a reassign: the step skips, it never falls back to an admin. For trigger_event lead.website_visit (or customer.website_visit) it runs when that person opens a page on the business's own website from a link in one of its automation texts or emails. It needs the business's website saved in Flyra and this script on every page of that site: <script src=\"https://app.flyra.io/flyra-visit.js\" async></script>. While the business has an automation on either trigger, links to its own website in automation texts and emails carry an fcid code naming the person (good for 30 days; it makes each such link about 60 characters longer); nothing changes for a business without one. It fires once per person, page and day. Optional trigger config.pageContains (any case) runs it only for pages whose path contains those words, like \"pricing\". The payload carries path. A visit from a link the person got anywhere else is not seen. For trigger_event lead.email_link_clicked (or customer.email_link_clicked, for a customer with no lead) it runs when that person clicks a link in an automation email whose send_email step has config.trackClicks: true (off by default; nothing else is tracked and there is no open pixel). It fires once per link per email, only for a person: link scanners and clicks within ten seconds of sending are ignored. Optional trigger config.linkContains (any case) runs it only for links whose address contains those words. The payload carries url, link_index and outbox_id. Unsubscribe, mailto, tel and sms links are never tracked. send_sms, send_email, send_review_request, send_link and ai_write_text also take sendWindow: { open_hours, holidays, public_holidays } for the businesses it is switched on for, the same shape as the automation's business_hours: open_hours keyed \"0\" (Sunday) to \"6\" (Saturday), each { open: \"HH:MM\", close: \"HH:MM\" } or null for closed, and holidays a list of up to 60 \"YYYY-MM-DD\" dates the business is closed. public_holidays: true also keeps the step off the big public holidays for the business's country (new year, Memorial Day, Independence Day, Labor Day, Thanksgiving, Christmas, Canada Day, Boxing Day); the list covers the US and Canada, so a business elsewhere names its dates instead. That one step waits for its next open minute and then sends; nothing is dropped. It adds to the automation's own business hours and quiet hours, never loosens them. send_sms (text only, sendEmail off), send_email and ai_write_text also take holdForApproval: true for the businesses it is switched on for: the filled message is not sent but held, and the business's Admins and Owners and the lead's owner are told in Flyra and by email (the customer is not). It is listed by flyra_list_automation_approvals and sends only after flyra_approve_automation_message, through the normal send, so opt-out, quiet hours and a sendWindow are checked again then; flyra_discard_automation_message drops it and the run carries on. A message nobody decides on in 72 hours, or whose run stopped, is never sent. start_automation takes { workflowId } for the businesses it is switched on for: it puts the run's lead (or customer) into that automation, which must be another automation of this business saved with trigger_event lead.manually_triggered (or customer.manually_triggered), the same kind flyra_run_automation runs. To start it later, put a delay_for or wait_until step before this one. A switched-off target is skipped. An automation can never start itself, directly or round a loop, and a line of starts stops at 3 deep. The started run does not set off automation.finished chains. Runs with no lead (or customer, for a customer target) skip. stop_other_automations takes {}, { workflowIds } or { folderId } for the businesses it is switched on for: it ends this contact's other running automations (the run's lead and its customer), every one of them, or only the listed automation ids (1 to 50), or only the automations filed in that folder when the step runs (built-in message presets in the folder have no runs to stop). Waiting steps end with them and nothing is sent. This run and other runs of this same automation are never stopped. Runs with no lead or customer skip. close_estimate takes { status: \"declined\" | \"expired\", reason?: text up to 500 characters } for the businesses it is switched on for: it closes the estimate the run started from (use it on an estimate trigger; runs with no estimate skip). Declined works like the Decline button on the customer page: follow-ups stop, the lead records the decline, and estimate.declined fires once. Expired moves only a draft or sent estimate. An accepted estimate is never changed. The reason is kept in the estimate metadata as close_reason, and the first reason stays. The step sends nothing itself; automations listening for estimate.declined still run. extend_estimate takes { extendByDays, resend } for the businesses it is switched on for: extendByDays is a whole number from 1 to 90, resend true or false (left out: false). It pushes the run's estimate's expiry out by that many days, from the current expiry, or from now once it has passed (use it on an estimate trigger, such as estimate.expiring; runs with no estimate skip). Only a draft or sent estimate moves, and one with no expiry date is skipped. resend: true then texts a sent estimate to its own customer again, the same text and link as sending it from the estimate page, held for the automation's quiet hours like any text; a draft's date still moves but it is not sent (the resend is skipped). The resend marks the estimate sent again, its link is opened again and its new expiry comes due again, so it is refused on an estimate.sent, estimate.viewed or estimate.expiring automation. Add message (up to 1000 characters, with resend: true) to send your own words (\"still holding your price\") instead: it goes out through Send text with the estimate link, to this run's person only, does not mark the estimate sent, and is allowed on estimate.expiring; each automation does this once per estimate, and a later run on the same estimate stops at this step. Never on email.received or an unsigned webhook. send_estimate takes { channel: \"sms\" } for the businesses it is switched on for: it texts the estimate the run started from to its own customer, with the business's estimate text and link, and marks it sent. Use it on an estimate trigger other than estimate.sent, estimate.viewed or estimate.expiring. Later steps stop if nothing went out (no estimate, closed estimate, no mobile phone, opted out). Held for quiet hours. merge takes { join: \"first_path\" } for the businesses it is switched on for: paths join here, the first path to arrive goes on and the step runs once per run; it does not wait for the other paths. approve_estimate takes { schedule: \"unscheduled\" | \"next_open_slot\" } (left out: unscheduled) for the businesses it is switched on for: it approves an estimate on the customer's behalf, the same as Approve on the estimate page (the job is created, follow-ups stop, estimate.accepted fires). The estimate is the run's own on an estimate trigger; otherwise (a reply trigger such as customer.reply_matched, for \"reply YES\") it is the contact's one sent estimate, and a contact with none or several is skipped. Only a sent estimate with no options is approved; one with options is skipped. next_open_slot books the new job into the first free start the customer's booking page would offer (business hours, notice and the calendar), with no booking text; a job that already has a time keeps it (the step is skipped after the approval); if the calendar cannot be read nothing is approved. update_field takes { record: \"lead\" or \"customer\", fieldKey, value } or { record, fieldKey, clear: true } for the businesses it is switched on for: it sets (or empties) one custom field on the run's lead or customer, by the key flyra_list_custom_fields gives. value is filled like a text ({webhook.contact} and the usual variables), then read as that field wants it (a dropdown takes the option or its label, a number takes a number); a value that does not fit, or fills to nothing, skips the step rather than emptying the field. The field-changed triggers fire as when someone edits it, so it is refused on a field-changed automation. A dropdown value that is not one of its options fails the step. Built in fields use { record, builtInField, value } or { record, builtInField, clear: true } instead of fieldKey: lead takes notes or service_type, customer takes notes, first_name or last_name, job takes notes, description or title, estimate takes notes or subject (skipped once accepted or signed), plan takes notes or scheduling_notes. Nothing else: no money, status, payment or lead source field. ai_extract_fields takes { source: \"reply\", \"note\", \"lead_notes\" or \"call_transcript\", record: \"lead\" or \"customer\", fieldKeys: [custom field keys], builtinFields?: [service_type, address_line1, address_line2, city, state, postal_code], overwrite: true or false (left out: false) } for the businesses it is switched on for: AI reads the reply (customer.replied, lead.reply_matched, customer.reply_matched), the note (lead.note_added), the lead's notes (any lead trigger) or the newest finished call transcript (any lead or customer trigger) and fills those custom fields on the run's lead or customer. Each answer must fit its field (a dropdown option, a number, true or false, a YYYY-MM-DD date, short text); a field the AI cannot find is left as it is, and a field that already has a value is kept unless overwrite is true. builtinFields are the lead's own columns, record \"lead\" only, up to 10 fields in all with fieldKeys; one is filled only while it is empty, whatever overwrite says, and a customer's address, status, value, phone and email are never written. It sends nothing. upsert_customer takes { firstName, lastName, email, phone, address, unit, city, state, zip } for the businesses it is switched on for (only firstName, lastName, email, phone, address, unit, city, state, zip; firstName and an email or phone are required), each filled like a text ({webhook.first_name}). It adds the customer, or, when one already has that email or phone (the oldest one, the same match as adding a customer by hand), carries on with that one and fills only its blank last name, email and phone; it never overwrites what is there, and leaves an existing customer's address alone. The steps after it act on that customer. Not on lead triggers; on an appointment trigger it fails when the visit is a lead's. Nothing is sent by this step, but a new customer starts any Customer created automation. find_record takes { record: \"customer\", \"lead\", \"job\" or \"estimate\", by, value } for the businesses it is switched on for: a customer or lead by \"id\", \"phone\", \"email\" or \"address\" (the customer's address, the lead's first address line; compared ignoring case and extra spaces, so \"12 main st\" finds \"12  Main St\", but \"Street\" does not find \"St\"); a job or estimate by \"id\", \"customer_phone\", \"customer_email\" or \"customer_address\", which finds the one open job (scheduled through in progress) or open estimate (sent or viewed) of the customer with that phone, email or address. value is filled like a text ({webhook.email}, {webhook.job_id}). Exactly one match in this business goes down its condition_true connection (Found) and the steps after act on it (a job or estimate brings its customer); none, or more than one, goes down condition_false (Not found). It needs at least one of the two. Not on lead triggers; on an appointment trigger it fails when the visit is a lead's. request_quality_check takes {} for the businesses it is switched on for: it opens a quality check on the run's job, waiting in Reports > Payroll > Quality checks for a manager to approve or send back, the same check a tech's photo upload opens. Quality checks must be on for the business, or the step fails. A job that already has a check (waiting, sent back or approved) is left alone, so a re-run never opens a second one; runs with no job skip. When the business has Quality checks set to hold payroll, the completed job's pay waits until the check is approved; the step cannot turn that on or off. Nothing is sent: no push, text or email. record_job_supplies takes {} for the businesses it is switched on for: on the run's completed job it records the supplies their usage rates predict (Inventory, per job or per unit of work), the same as keeping the suggestions on the job's Supplies card, so stock comes off the shelf and Low Stock fires as usual. Supply tracking must be on. A job whose supplies someone already confirmed is left alone, and so is one no rate applies to; a skip stops the run there. It cannot be used on a job.supplies_logged automation, which it fires itself. Nothing is sent. open_save_request takes { reason?, note?, assigneeId? } for the businesses it is switched on for: it puts the run's plan on the Save Center board, as Request cancellation does, with the plan's yearly value. The plan is the run's own on a plan trigger, otherwise the customer's one active plan; a customer with none or several is skipped. reason is one of the business's cancellation reasons for plans (must be set when the business requires one); note is text, variables allowed; assigneeId is the bare uuid after emp_ in flyra_list_employees, a team member who can work the Save Center, and left out it follows the Save Center's own assign rule. Skipped when the Save Center is off or the plan already has an open request; a skip or failure stops the run there. Nothing is sent and the plan and its billing are not changed. send_team_contract takes { contractId } for the businesses it is switched on for, on employee.joined only: contractId is the id from flyra_list_team_contracts of a contract that has been sent and is not voided. It asks the new team member to sign it, as Send on Team > Contracts does: their copy, then one email and text to them. Skipped when the contract is not for them (its audience), they already signed it, their copy was voided, or the contract was voided since; a skip or failure stops the run there. Customers are never messaged. add_checklist_group takes { groupId } for the businesses it is switched on for: the bare uuid after chkgroup_ from flyra_list_checklist_groups. It copies that Price Book checklist group onto the run's job, as adding it from the job screen does (each item with its title, description, first photo and the group tag, in the group's order). A group already on the job is not added twice; runs with no job skip. Nothing is sent. add_job_line_item takes { priceBookItemId, quantity } (quantity a whole number from 1 to 10000, left out: 1), { discountPercent } (above 0, at most 100) or { discountAmount } (dollars), exactly one, for the businesses it is switched on for. priceBookItemId is the bare uuid after svc_ from flyra_list_services. It adds that item to the run's job as a line at its price book price, or the discount, and the job total follows, as flyra_update_job does. A job that is paid, charged or has an invoice that is not void is refused and the step fails; a discount on a job that already has one is skipped, not replaced; runs with no job skip. Add target: \"next_visit\" to change the soonest scheduled visit ahead on the plan of the run's job or of the run instead (never the run's job); no plan, a plan that does not bill per visit, no such visit, or the item already on that visit skips, and that visit's total follows. Nothing is sent. create_invoice takes {} for the businesses it is switched on for: on the run's completed job it makes a DRAFT invoice from the job's line items, or reuses the live invoice already on the job, and hands its id to the steps after it. It never sends anything; pair it with send_invoice, create_payment_link or a send_sms with {invoice_payment_link} to deliver it. It is skipped (the run stops there) when the job is not completed, is a plan visit, has no customer or no priced line items, or is already paid. send_payment_reminder takes an optional message ({single_braces} variables like {invoice_link}, at most 640 characters; the business's invoice reminder wording when left out) for the businesses it is switched on for: it texts the run's invoice (the one a create_invoice put on the run, else the newest open invoice on the run's job) the same reminder as the Send reminder button, with the pay link, to its customer only. It is skipped (the run stops there) when there is no invoice, the invoice is still a draft, paid or void, or has no customer, or the customer cannot get texts; quiet hours hold the text. For an email reminder, follow it or replace it with a send_email that uses {invoice_payment_link}. send_receipt takes channel (sms or email) and, for sms only, an optional message ({single_braces} variables like {receipt_link}, at most 640 characters; the business's receipt wording when left out) for the businesses it is switched on for: it sends the receipt for the run's latest collected payment (on the invoice the run carries, else on the run's job) to that customer, the same receipt the record-payment form sends. Each run sends it once, so it can be sent again on purpose (for example with a referral ask). Email needs the payment on an invoice and is skipped when an email receipt for that invoice already went out. It is skipped (the run stops there) when there is no collected payment or no one to reach; quiet hours hold the text. discount_plan takes { kind: \"percent\" | \"dollar\", value, visits, reason? } for the businesses it is switched on for: value is 1 to 100 for percent, or dollars from 0.01 to 10000 for dollar; visits is a whole number from 1 to 12; reason is optional text (at most 200 characters). It is a save offer: it puts that discount on each of the next N scheduled visits on the plan of the run's job (or of the run), soonest first, the same discount as add_job_line_item, and adds the customer note \"Save offer: <value> off the next N visits (<reason>)\". A visit that already has a discount, is paid or has an invoice is left as it is. It is skipped (the run stops there) when there is no plan, the plan does not bill per visit, no visit is ahead on it, or no visit could take the discount. A discount on the whole plan is not done here; it stays on the plan page. Nothing is sent. create_payment_link takes {} for the businesses it is switched on for: on a completed job it makes the invoice (the same draft as create_invoice) or uses the open invoice already on the job, and marks a draft sent like the Send button, so it has a live pay link. Marking it sent starts the business's own \"Invoice sent\" automations and the invoice follow-up reminders; the step itself texts and emails nobody. The invoice goes on the run, so a later send_sms or send_email can carry {invoice_payment_link}. It is skipped (the run stops there) when the job is not completed or the invoice is already paid. charge_card_on_file takes { maxAmountCents } (a whole number of cents from 100 to 1000000) for the businesses it is switched on for: it charges the open balance of the run's invoice (the one create_invoice or create_payment_link put on the run, else the newest open invoice on the run's job) on the customer's card on file, the default card or the only card, never a guess between several, with the same checks as flyra_charge_invoice. maxAmountCents caps the invoice balance; a card fee the business passes on goes on top. Charged goes down its condition_true connection (Charged); not charged goes down condition_false (Not charged): a balance above the cap, nothing owed, a plan visit (its plan bills it), no card on file, Stripe not set up, a decline, or no invoice. It needs at least one of the two. A charge Stripe has not confirmed fails the step and the run stops there, and the step is never retried. A stop_if with a condition_true connection is a goal, for the businesses it is switched on for: the rule is checked where the step sits, every time the run wakes from a wait, and again on the regular background pass while the run is still on any wait, wherever the run is, and when it is met the run leaves whatever step it was on (its waits and queued steps are cancelled) and takes the condition_true path (\"Goal met\") once, instead of just ending. A stop_if with no condition_true connection still only ends the run, and only at a wake. To put a goal on the whole automation, leave the stop_if with nothing leading into it and connect only its condition_true path: runs never walk through it, and it is still checked while they wait. The Goal met path runs right away: it cannot hold delay_for, wait_until, wait_for_reply or another stop_if, and cannot lead back to its stop_if. Example: trigger, then stop_if { conditionType: \"estimate_accepted\" } with default to the follow-up ladder and condition_true to a thank-you step. Custom fields as variables, for the businesses Automations 2 is switched on for: a custom field's key from flyra_list_custom_fields can go in a text or email as {key} (a lead field on a lead trigger, a customer field on a customer trigger) and fills in with that record's answer, formatted as the field shows it. A record with no answer fills nothing, and the empty variable is removed from what is sent, the same as any other empty variable. set_map_pin takes { pinStatus } for the businesses it is switched on for, on a lead or customer trigger: pinStatus is an enabled pin type key from flyra_list_pin_types (sale, not_interested, do_not_contact, or one the business added). A lead run moves the pin the lead was made from; a lead with no pin is skipped. A customer run moves the customer's newest pin, or drops one at the customer's mapped address when they have none, so running it again moves the same pin instead of adding another. A customer with no map spot or no address is skipped. One pin per run; nothing is sent. Example: job.completed, then set_map_pin { pinStatus: \"sale\" }. ai_paths takes { source, customFieldKey?, paths: [{ to, label, description? }, ...] } for the businesses it is switched on for, on a lead or customer trigger (AI decides the path): 2 to 8 paths, each a label of up to 60 characters and an optional one-line description, plus a required Everything else path. source \"latest_reply\" reads the newest text the run's lead or customer sent; source \"call_transcript\" reads the newest finished call transcript with them; source \"custom_field\" with customFieldKey reads that field's answer (a form answer) from flyra_list_custom_fields. source \"lead_details\" (lead triggers only) reads the lead's name, service, source, address, notes and every answered lead form field. AI lead score recipe (fit and urgency): on lead.created, an ai_paths step with source \"lead_details\" and paths such as Hot, Warm and Cold, each describing who belongs there, each going to its own change_lead_score step with { scoreAction: \"set\", amount } (90, 60, 20); a separate automation on lead.score_changed with a score threshold then calls or alerts on hot leads first. Detect intent recipe (customer.intent_detected): there is no separate intent trigger; on lead.responded or customer.replied, an ai_paths step with source \"latest_reply\" and paths such as Ready to book, Price question and Not interested, each with a one-line description of what that reply sounds like, then each path to its own steps (notify_team, add_note, a tag or a stage move). Negative sentiment recipe (customer.sentiment_negative): there is no separate sentiment trigger; the channel is the trigger you pick. For a text use lead.responded or customer.replied, for an email email.received, each with an ai_paths step on source \"latest_reply\"; for a call use call.transcript_ready with source \"call_transcript\". Give paths such as Unhappy (\"upset, complaining or threatening a bad review\") and Happy or neutral; an answer the model is not sure of takes Everything else, which is how confidence is set. Send Unhappy to notify_team or add_note so a person steps in. When the step runs, the model reads that one text and names one label; the run goes down that path's condition_true connection only. No text, or an answer that is not one of the labels, takes the condition_false connection (Everything else), and the reason is kept on the step; a model that does not answer fails the step and nothing after it runs. The customer writes the text it reads and can steer which path it takes, so a path should lead to a message or a note, not to a step that approves, books, bills or pays. Every condition_true connection must be named by one path. The test run does not ask the model: it takes path 1, or Everything else when told the world says no. ai_summary_note takes { target?: \"lead\" | \"customer\" | \"job\" } (default \"lead\") for the businesses it is switched on for, on a lead or customer trigger (a job target needs a job trigger): it reads the newest texts (up to 30), emails (up to 10) and finished call transcripts (up to 3) with the run's lead or customer, asks the AI for a short summary and adds it as a note on that record, the way add_note does. No conversation yet skips the step; an AI failure fails it. Nothing is sent. Example: job.completed, then ai_summary_note { target: \"job\" }. wait_for_event takes { event, timeoutSeconds } for the businesses it is switched on for: it pauses the run until something happens to the run's own record, and needs one condition_true connection (Happened) and one on_timeout connection (Timed out). event is one of estimate.accepted, estimate.declined, estimate.signed, estimate.viewed, invoice.paid, job.completed, subscription.activated, subscription.signed, subscription.card_saved, on a trigger of the same kind (estimate.* for the estimate events, invoice.* for invoice.paid, job.* for job.completed, subscription.* for the plan events). subscription.activated means the plan is active (signed, card on file and any deposit paid); subscription.signed means the customer signed it, card or not; subscription.card_saved means a card is on file. estimate.viewed means the customer has opened the estimate link, at any time, so an estimate opened before this step counts as Happened. timeoutSeconds is 3600 (1 hour) to 2592000 (30 days). The record is read again about every 15 minutes, so Happened can come up to about 15 minutes late; a record already in that state when the step runs goes down Happened at once. Nothing is sent. Example: estimate.sent, then wait_for_event { event: \"estimate.signed\", timeoutSeconds: 259200 }, then a reminder on the on_timeout connection. assign_territory takes { territoryId, assignTo, employeeId?, mode } for the businesses it is switched on for: territoryId is the bare uuid after terr_ in flyra_list_territories; assignTo \"person\" with employeeId (the bare uuid after emp_ in flyra_list_employees, an active team member) on any trigger, or \"team_member\" for the person who joined, on employee.joined only; mode \"add\" keeps the people already on the territory, \"replace\" takes them off. Whoever is new to the territory gets the same assignment email and push as when the office assigns it on the Map; nobody else is told, and someone already on it is not told again. Admins and owners still see every territory. Example: employee.joined, then assign_territory { territoryId, assignTo: \"team_member\", mode: \"add\" }. optimize_routes takes { day: \"today\" | \"tomorrow\", textFirstStop, publish } (the business's clock; textFirstStop and publish true or false, left out: false) on a schedule.tick trigger: it routes that day's scheduled jobs that already have a technician, each technician's jobs in drive order and every job kept on its own technician, into a plan on the Routes page. Without publish the plan stays a draft and no job moves. With publish true the plan is published and each job's start and end move to the planned times; publish moves job times; customers are not texted about the new times, and no technician changes. A job that started, finished, sits on a locked stop or is a multi-day Anytime job is left alone; the step output counts published_jobs, skipped_jobs and failed_jobs. If no job time can be written the plan goes back to draft; if only some fail the step fails with failed_job_ids and route_plan_id in its output and nobody is texted. With textFirstStop true each technician alone is texted the first stop of their route, marked as a draft unless that stop's job time was published. Up to 100 jobs a day. Example: schedule.tick every day at 6 PM, then optimize_routes { day: \"tomorrow\" }. schedule_callback takes { inMinutes } or { atTime, inDays? }, plus an optional employeeId, for the businesses it is switched on for, on a job trigger (not job.callback_scheduled): it schedules a callback on the run's job, as Job > Schedule Callback does (same customer and address, line items copied at $0). inMinutes is 1 to 43200 from when the step runs; atTime is \"HH:MM\" on the business clock, inDays days from today (1 to 30) or, left out, the next time the clock reads atTime. employeeId is an active team member from flyra_list_employees; left out, the lead owner goes, else the job's techs. It lasts the business's default job length. One callback per run; the step sends nothing itself, but the new callback gets the business's usual job reminders and fires job.callback_scheduled. Example: job.completed, then schedule_callback { atTime: \"09:00\", inDays: 1 }. A From address can be faked, so a run an email set off, directly or down a chain, cannot run send_sms, send_email, send_review_request, send_link, send_meet_your_cleaner, send_tip_request, send_message_to, send_webhook, ai_write_text, create_appointment, send_payment_reminder or send_receipt; they are refused at save on email.received. send_message_to takes { to, address?, subject?, body, alsoText? } and texts or emails ONE person who is not the run's customer, for the businesses it is switched on for. to is phone or email (address is one typed number or address, or one of the team's own: {rep_phone}, {salesperson_phone}, {employee_phone}, {company_phone} or the matching _email; on webhook.received it must be typed; the step is refused on email.received), lead_owner (the lead's assigned owner; lead or customer trigger), job_technician or job_salesperson (the run's job; job or customer trigger), referrer_phone or referrer_email (whoever referred the run's customer or lead; skipped if nobody did), customer_contact_phone or customer_contact_email (the customer's one other contact that receives automations; skipped if there are none or several, because contacts have no tenant or manager role). Those four take no address and are refused on email.received and webhook.received. A message to a referrer can fill only {first_name}, {customer_first_name}, {company_name}, {company_phone} and {company_email}. A team member gets it like Notify team (in-app, push and email, plus a text from the business number when alsoText is true). A phone number gets the customer text path: opt-out and quiet hours apply. An email skips an address that unsubscribed. subject names the email and the team alert. Variables use {single_braces}. Example: job.completed, then send_message_to { to: \"job_salesperson\", body: \"{first_name}'s job is done\" }. send_link takes { linkKind, formId?, channel, subject?, body } and texts or emails the run's OWN lead or customer one Flyra link, for the businesses it is switched on for, on a lead or customer trigger. linkKind is lead_form (formId is the id from flyra_list_lead_forms of a published form, and the link is its /f/ page), booking (the page of the run's job), add_card (the card on file page of the run's customer), plan_signing (the signing page of the run's plan, skipped once signed) or tip (the tip page of the run's job, skipped until the job is completed). Those four are refused on webhook.received and skip when the run has no such record; send_link is refused on email.received. channel is sms or email; subject is for email only. Put {link} where the link goes, or it goes on its own last line. It sends through Send message, so opt-out, quiet hours and a sendWindow apply. Variables use {single_braces}. Referral and pay links are not offered. Example: lead.created, then send_link { linkKind: \"lead_form\", formId: \"form_<uuid>\", channel: \"sms\", body: \"Hi {first_name}, tell us about your home: {link}\" }. ai_write_text takes { instruction, bannedWords?, context?, tone?, maxChars?, mustIncludeLink? } and texts the run's OWN lead or customer one message the AI writes when the step runs, for the businesses it is switched on for, on a lead or customer trigger. instruction (1 to 1000 characters) is what the text should say and how it should sound; it may use {single_braces} variables this trigger has, and the AI can use only those, filled in when the text is sent. Unless context is set the AI sees only the instruction. context is a list of \"conversation\" (the run's recent texts, emails and call transcripts, sent to the AI as quoted data) and \"job\" (the run's job title and time, never the amount); a failed read, or job on a run with no job, fails the step. tone is up to 80 characters on how the business sounds. maxChars is from 40 to 320 (default 320). mustIncludeLink is one full http or https link; an answer without it fails the step. bannedWords is up to 20 words or phrases the text must not contain; the AI is told them and they are checked again. An AI that does not answer in 25 seconds, an empty answer, a link, email address, domain or phone number not written exactly in the instruction, a banned word, a blank like [Name] or a variable not in the instruction fails the step and nothing is sent; there is no stand in text. It sends through Send text, so opt-out, quiet hours and a sendWindow apply; a held step asks the AI only when it wakes, and a retry never sends twice. Run history shows the text the AI wrote. Text only, no email. The test run shows the instruction and does not ask the AI. Example: job.completed, then ai_write_text { instruction: \"Thank {first_name} for having {company_name} out today. Warm, two short sentences.\", bannedWords: [\"discount\"] }. add_payroll_bonus takes { to, employeeId?, payrollType, amountCents, reason } for the businesses it is switched on for, saved by an Admin on a key with payroll:write: to is technician (the run's job's first technician), salesperson (the job's salesperson), lead_owner (the lead's owner) or person (employeeId, a team member id from flyra_list_employees). payrollType is sales or technician. amountCents is whole cents, not 0, from -100000 to 100000; below 0 is a deduction. reason (1 to 120 characters) shows beside it. It adds one bonus dated today in the business's time zone, so it counts in the current pay period, as the Add bonus popup does; a retried step never adds it twice. Nobody to pay, or someone no longer active, skips. No payout is made and nothing is sent. reschedule_job takes { moveByDays }, { moveTo: \"next_open_slot\" } or { moveTo: \"payload_date\", dateField } for the businesses it is switched on for. payload_date moves the run's job to the YYYY-MM-DD date at dateField: the trigger payload's key first, then the customer's custom field of that key (for example one an ai_extract_fields step filled from a reply), same time of day in the business's time zone. No value there skips the step (no_date); a value that is not a YYYY-MM-DD date fails it (date_invalid); a date more than 60 days before or 365 days after the job's day skips it (date_out_of_range). moveTo moves the run's job to the first open slot the booking page offers (business hours, minimum notice, other jobs), keeping its length; no open slot within 60 days skips the step, and it can land earlier than the job's current time. moveByDays is a whole number of days from -60 to 365, not 0. It moves the run's job that many days later (or earlier, below 0), keeping its start and end at the same time of day in the business's time zone, through the same path as a drag on the calendar (reminders follow). It never messages the customer: add a send_sms or send_email step after it to tell them. A job with no time yet, a finished or cancelled job, and a plan visit (its move would also move the plan's charge) are skipped, not moved. Runs with no job skip. change_lead_score takes { scoreAction: \"add\" | \"subtract\" | \"set\", amount } for the businesses it is switched on for: add or take away 1 to 100 points, or set the score to 0 to 100. The score stays between 0 and 100; adding to a lead nobody scored starts it at 0. Lead runs only. post_team_chat takes { conversationId, body } for the businesses it is switched on for: it posts body (variables allowed, like a text) into that Team Chat conversation, an id from flyra_list_team_conversations, as the person who saves the automation, who must be in that conversation. Team only, never customers. send_webhook takes { url, secret }: it POSTs the lead, customer and job that apply to the run as JSON to an https URL (a Zapier catch hook, an n8n webhook, the business's own endpoint), retried on failure, signed with X-Flyra-Signature once it has a secret. Put it after any trigger (job.completed, lead.created, invoice.paid and the rest) to send that event out; flyra_create_webhook_subscription does that in one call. A stored secret reads back as \"[hidden]\": send it back as \"[hidden]\" to keep it, and set or rotate it with flyra_set_webhook_secret. On trigger_event webhook.received the trigger step gets its own URL (automation.webhook_url in the answer, below) and takes an optional config.webhookEvent, a name for what is sending, passed to the run as webhook_event. Sign it with flyra_set_webhook_secret; flyra_test_inbound_webhook shows what a sample would match and map. A create_lead step after it takes config.fieldMap: [{ to, from }] rows, `to` a lead field (first_name, last_name, phone, email, address and the rest) or custom:<key> for one of the org's own fields, `from` a dot path into the request body. report_conversion takes { event, includeValue? } for the businesses it is switched on for: it reports the run's lead to Meta through the Meta Conversions connection. event is Lead, Contact, Schedule or Purchase. includeValue true sends the lead's newest estimate total, when it has one. It reports each lead once per event, whatever automation asked first. It works only for a lead that came from a Meta form (otherwise it is skipped), and a business with Meta Conversions off fails here. For the businesses Google Ads is switched on for, it also takes { destination: \"google_ads\", conversionAction } (destination defaults to \"meta\"; conversionAction is the numeric id of the conversion action in Google Ads): it uploads one click conversion matched on the Google click id (gclid, gbraid or wbraid) the hosted form saved on the lead, with the same order id each time so Google never counts it twice. A lead with no Google click id, or a business whose Google Ads is not connected, skips the step. Use one step per destination to report to both. It cannot be used on email.received, or on webhook.received until its signing secret is set. connect_call takes { ringSeconds?, whisper? } for the businesses it is switched on for: it rings the lead's owner rep (the phone on their team member profile) from the business calling number, and when the rep picks up it calls the lead from that same number and connects them. The lead sees the business number, never the rep's phone. ringSeconds is 15 to 60 (default 30). whisper (up to 200 characters, variables allowed like a text) is spoken to the rep before the lead is called. Wire condition_true (Connected: the rep's phone is ringing) and condition_false (Not connected: no owner, the rep or lead has no phone, the lead opted out or is blocked, or the business has no Telnyx calling number), for example to a send_sms. If the rep does not pick up, a note is added to the lead. The automation's quiet hours hold it like a text. Calls are not recorded. It cannot be used on email.received, or on webhook.received until its signing secret is set. block_calendar_time takes { employeeId, title, durationMinutes, startFrom?, offsetMinutes? } for the businesses it is switched on for: it adds one event to the Flyra calendar in that team member's connected Google account. It does not stop Flyra from booking that person, and nothing is sent to the customer. title (up to 200 characters) is filled like a text. durationMinutes is 1 to 1440. startFrom is now (default), job_start or job_end; a job start with no job or no set time is skipped. offsetMinutes is -1440 to 10080. A person with no live Google Calendar connection fails here. It cannot be used on email.received, or on webhook.received until its signing secret is set. opt_out_texting takes { reason } (1 to 200 characters) for the businesses it is switched on for: it opts the run's contact out of texts from this business, the same as their STOP reply, using the lead's phone, else the customer's mobile phone, and notes \"Opted out of texting by automation <name>: <reason>\" on that lead or customer. Every text after that to the number is blocked. It sends nothing, and a run with no phone is skipped. Only the person can opt back in, by replying START; no step does it. Email opt-out is not available. go_back takes { toNodeKey, maxLoops } (maxLoops a whole number from 1 to 10) for the businesses it is switched on for: it ends this run and starts a new run of the same automation for the same lead at the earlier step toNodeKey, so each pass shows as its own run. Connect nothing back to toNodeKey: go_back is not a connection. toNodeKey must be an earlier step on a path into go_back, never the trigger, and the steps from toNodeKey to go_back must include a delay_for or wait_until. Once maxLoops passes have run, go_back is skipped and the run goes on down its one optional default connection (for example to a notify_admin). Example, retry a failed charge every 3 days up to 3 times: charge_card_on_file, its condition_false connection to delay_for 3 days, then go_back { toNodeKey: the charge step, maxLoops: 3 }. offer_plan takes { templateId, amountCents, discount? } for the businesses it is switched on for: templateId is a plan template id from flyra_list_subscription_templates, amountCents the plan price in whole cents, discount { type: \"percent\" or \"flat\", value } as flyra_create_subscription takes it. It makes a pending plan from that template for the run's customer (the job's customer on a job trigger), exactly as flyra_create_subscription does, and keeps its id on the run as subscription_id. The step sends nothing itself: the business's Subscription Approval Link automation sends a pending plan, or put a send_link { linkKind: \"plan_signing\" } after it. When that customer already has an active or pending plan from the same template, no second plan is made and that plan is kept on the run as subscription_id instead (the step output says reused: true). It is skipped when the run has no customer or when the template is gone. change_plan takes { action, frequency? } for the businesses it is switched on for, on the run's plan (the run's subscription_id, as offer_plan keeps it, else the plan of the run's job). action \"pause\" or \"resume\" makes the same writes flyra_pause_subscription and flyra_resume_subscription make; a pending plan is not paused and only a paused plan is resumed. action \"skip_next_visit\" cancels the plan's next booked visit (an active plan; the visit must still be scheduled and have no invoice, payment or charge), without the cancellation text; the plan's booking does not book it again. It is refused on subscription.visit_skipped, job.cancelled and job.field_changed. The cancel fires those triggers as a cancel in the app does, so the business's other automations on them run for that customer (and any send step in them sends). action \"change_frequency\" with frequency (one of weekly, monthly, bi_monthly, quarterly, tri_annual, six_months, yearly, biennial, triennial, e.g. quarterly to six_months for twice a year) changes how often the plan bills, as flyra_update_subscription_frequency does: the per-cycle amount and the visit dates stay, and a plan paid in monthly installments is skipped. A cancelled or bundled plan is skipped with the reason. The customer is not told; add a send step for that. http_request takes { method, url, headers?, query?, body?, saveAs? } for the businesses it is switched on for: it calls an outside API once. method is GET, POST, PUT, PATCH or DELETE. url is a fixed https address (no variables, no private or local hosts, redirects are not followed). headers and query are lists of { name, value } (up to 20 each); put API keys in headers, because header values read back as \"[hidden]\" (send \"[hidden]\" back to keep the stored value) and are never shown on the run. Query values and the text values inside body (a JSON object or list, not for GET, up to 10000 characters) are filled like a text ({first_name}, {webhook.email}). saveAs is up to 10 { name, path } rows: name is lowercase letters, numbers and _, path is a dot path into the JSON answer (data.id, items.0.sku), and later steps use the value as {http.name}. An answer that is not 2xx, a timeout (10 seconds), an answer over 64 KB or not JSON when saveAs is set stops the run at this step; it is sent once and never retried. It cannot be used on email.received, or on webhook.received until its signing secret is set. add_tag and remove_tag take { tagId } from flyra_list_tags. create_lead takes an optional { pipelineId }, the bare uuid after pipe_ in flyra_list_pipelines (left out, the org's usual pipeline): on the Inbound webhook trigger it makes a lead from what arrived; on any other customer trigger (a job, invoice or payment) it adds that customer to the pipeline's first lane, skips when they already have an open lead, and does not start the org's Lead created automations. That lead is linked to the customer, so automations do not move or assign it; people do. For trigger_event webhook.received Flyra sets the trigger's URL itself (a config.webhookToken you send is ignored on every trigger) and keeps it on every later save: the answer's automation.webhook_url is where the business's website or form tool posts its form fields, as JSON or a normal form post. Treat the URL as a secret: anyone holding it can start this automation, so give it only to whoever sets up the form. Requests are refused while the automation is off. Message bodies use {single_braces} variables such as {customer_first_name}. Anything the trigger cannot fill comes back as a warning, and would be stripped from what the customer receives.\n\nScope: `automations:write`.","x-required-scope":"automations:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"automation_id":{"description":"Leave out to create. Pass an id from flyra_list_automations to replace that automation.","type":"string"},"name":{"type":"string","minLength":1,"maxLength":120,"description":"What the automation is called."},"trigger_event":{"description":"The event that starts it. Must match the trigger step. Required unless trigger_object is given instead.","type":"string","enum":["lead.created","form.submitted","call.missed","lead.not_contacted","lead.responded","lead.stage_changed","lead.converted","lead.reply_matched","lead.duplicate_detected","lead.manually_triggered","appointment.booked","appointment.reminder_due","appointment.rescheduled","appointment.completed","appointment.cancelled","appointment.on_the_way","appointment.no_show","lead.assigned","lead.unassigned","lead.lost","lead.reopened","lead.pipeline_changed","lead.value_changed","lead.custom_field_changed","lead.note_added","lead.meta_form_received","lead.google_lsa_received","form.booking_requested","form.photos_uploaded","referral.submitted","qr.scanned","sign.collected","sign.overdue","sign.dropped","pin.dropped","pin.status_changed","pin.objection_logged","pin.revisit_due","lead.idle_in_stage","lead.score_changed","lead.voicemail_left","lead.email_link_clicked","lead.website_visit","estimate.sent","estimate.accepted","estimate.created","estimate.viewed","estimate.option_selected","estimate.optional_item_changed","estimate.signed","estimate.deposit_paid","estimate.declined","estimate.self_scheduled","estimate.converted","estimate.not_viewed","estimate.viewed_no_answer","estimate.expiring","job.created","job.technician_assigned","job.reminder_due","job.on_the_way","job.running_late","job.arrived","job.started","job.completed","job.completed_nearby","job.overdue","job.unpaid","job.rescheduled","job.callback_scheduled","job.cancelled","job.restored","job.complaint_logged","job.complaint_resolved","job.touch_up_booked","tip_page.opened_no_tip","job.quality_check_submitted","job.quality_check_approved","job.quality_check_sent_back","job.deleted","job.checklist_completed","job.supplies_logged","job.signature_captured","job.photos_added","job.finished_early","job.upsell_added","job.note_added","job.total_changed","job.crew_changed","job.scheduled_from_later","job.field_changed","job.unassigned_soon","job.series_ending","invoice.sent","invoice.paid","invoice.viewed","invoice.created","invoice.overdue","invoice.split_second_due","payment.received","payment_link.opened_unpaid","payment.refunded","payment.removed","card.saved","payment.disputed","payment.failed","deposit.received","tip.requested_after_payment","tip.received","subscription.sent","subscription.activated","payment_method.requested","subscription.renewal_upcoming","tip.requested","subscription.cancelled","cancellation.requested","save_request.moved","subscription.amount_changed","subscription.charge_failed","subscription.paused","subscription.resumed","subscription.signed","subscription.viewed","subscription.visit_skipped","subscription.visit_completed","subscription.not_accepted","subscription.term_ending","subscription.anniversary","subscription.churn_risk","card.expiring","save_request.assigned","customer.created","customer.replied","customer.first_service","holiday.upcoming","referral.converted","referral.reward_released","customer.opted_out","customer.opted_in","customer.tag_added","customer.tag_removed","customer.updated","customer.deleted","customer.property_added","customer.converted_to_lead","message.delivery_failed","message.unanswered","sms_blast.replied","sms_blast.no_reply","email.received","email.bounced","customer.field_changed","customer.reply_matched","customer.manually_triggered","customer.arrived_geofence","customer.service_anniversary","customer.birthday","customer.ltv_milestone","call.voicemail_left","call.completed","call.outbound_no_answer","call.transcript_ready","call.menu_option_pressed","customer.balance_overdue","customer.lapsed","customer.email_link_clicked","customer.website_visit","review.requested","review.positive","review.negative","review.submitted","review.not_left","inventory.not_returned","inventory.low_stock","inventory.expiring","inventory.checked_out","inventory.item_added","inventory.maintenance_due","task.created","task.overdue","task.due","task.completed","employee.invited","employee.joined","employee.welcome_email","employee.knocking_session_ended","employee.knocking_session_started","employee.document_expiring","employee.team_chat_mentioned","employee.territory_crossed","google_calendar.event_created","schedule.tick","webhook.received","automation.failed","expense.created","payout.sent","payout.failed","cash.low_collections","territory.created","territory.assigned","employee.clocked_in","employee.forgot_clock_out","campaign.response_rate_low","sms_blast.completed","sms_credits.low","timesheet.overtime","metric.threshold_reached","employee.deactivated","employee.location_sharing_off","contract.signed","employee.availability_changed","payroll.period_closed","texting_registration.changed","integration.disconnected","accounting.sync_failed","automation.finished","automation.chain_failed","record.date_reached","pricebook.price_changed","employee.first_job","schedule.tomorrow_light","weather.forecast_alert","google_review.posted","employee.missed_clock_in","revenue_goal.reached","sprint.started","season.started","schedule.overbooked","schedule.open_slot","route.published","leaderboard.rank_changed"]},"trigger_object":{"description":"Instead of trigger_event: the kind of record, with trigger_action. Saved as the matching trigger_event.","type":"string","enum":["lead","customer","job","appointment","estimate","invoice","payment","subscription","task","territory","employee"]},"trigger_action":{"description":"With trigger_object: what happened to the record, such as created, updated, deleted or status_changed.","type":"string","maxLength":40},"trigger_status":{"description":"With trigger_action status_changed: the status (a job status, or a lead stage id or label).","type":"string","maxLength":80},"steps":{"minItems":1,"maxItems":60,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":60,"description":"Your own id for this step. Connections refer to it."},"type":{"type":"string","enum":["trigger","send_sms","send_email","send_tip_request","delay_for","wait_for_reply","wait_for_event","if_else","stop_if","change_stage","notify_admin","create_task","create_lead","add_note","wait_until","change_job_status","create_job","create_appointment","assign_technician","send_review_request","send_meet_your_cleaner","send_invoice","notify_team","notify_low_stock","notify_expiring","notify_borrower","post_team_chat","change_lead_score","update_task","reschedule_job","set_map_pin","ai_paths","ai_summary_note","assign_territory","optimize_routes","schedule_callback","send_message_to","send_link","ai_write_text","add_payroll_bonus","stop_other_automations","start_automation","close_estimate","extend_estimate","approve_estimate","add_checklist_group","add_job_line_item","record_job_supplies","request_quality_check","open_save_request","send_team_contract","update_field","ai_extract_fields","upsert_customer","find_record","assign_lead","unassign_lead","add_tag","remove_tag","create_estimate","send_estimate","convert_to_customer_job","send_webhook","http_request","report_conversion","block_calendar_time","connect_call","merge","create_invoice","send_payment_reminder","send_receipt","discount_plan","create_payment_link","charge_card_on_file","opt_out_texting","go_back","offer_plan","change_plan"],"description":"What the step does."},"name":{"description":"Label shown on the canvas.","type":"string","maxLength":120},"config":{"description":"Step settings. See the tool description.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["key","type"]},"description":"Every step, including exactly one of type `trigger`."},"connections":{"description":"How the steps are wired, in order of execution.","maxItems":120,"type":"array","items":{"type":"object","properties":{"from":{"type":"string","minLength":1,"description":"Step key this leaves."},"to":{"type":"string","minLength":1,"description":"Step key this arrives at."},"when":{"description":"Which way out of the step. Defaults to `default`.","type":"string","enum":["default","condition_true","condition_false","on_reply","on_timeout"]},"condition":{"description":"Condition payload for an if_else branch.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["from","to"]}},"quiet_hours":{"description":"Hours when this automation holds its texts and sends them once the window ends, in the business's timezone. { start: \"19:00\", end: \"08:00\" } texts only between 8 AM and 7 PM. null switches quiet hours off. Left out, a new automation has none and an existing one keeps what it has.","anyOf":[{"type":"object","properties":{"start":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","description":"When texts start being held, \"HH:MM\" on a 24 hour clock."},"end":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","description":"When held texts go out, \"HH:MM\" on a 24 hour clock."}},"required":["start","end"]},{"type":"null"}]},"business_hours":{"description":"When the business is open. A text or email step due while closed waits and goes out at the next open minute; it is never skipped and never sent early. Quiet hours and the overnight hold on texts still apply on top. Sending this object replaces both halves; null clears business hours; left out, a new automation has none and an existing one keeps what it has.","anyOf":[{"type":"object","properties":{"open_hours":{"description":"Opening hours per day, keyed \"0\" (Sunday) to \"6\" (Saturday): { \"1\": { open: \"09:00\", close: \"17:00\" }, ... }. A day left out or null is closed. Left out or null: open all day, every day, except the holidays.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"object","properties":{"open":{"type":"string"},"close":{"type":"string"}},"required":["open","close"]},{"type":"null"}]}},{"type":"null"}]},"holidays":{"description":"Dates the business is closed all day, \"YYYY-MM-DD\" in its own calendar, at most 60.","anyOf":[{"maxItems":60,"type":"array","items":{"type":"string"}},{"type":"null"}]}}},{"type":"null"}]},"stop_on_reply":{"description":"true stops this automation for a customer once they reply to a message. false keeps it running on its schedule after a reply, until a stop_if step ends it or it reaches its last step (for example once the invoice is settled). Left out, a new automation stops on reply and an existing one keeps what it has.","type":"boolean"},"max_messages_per_contact_per_day":{"description":"Frequency cap: at most this many texts, emails, review asks, payment reminders, receipts and connect calls from this automation to one person in any 24 hours (1 to 50). Over the cap the send step is skipped and the run carries on. null removes the cap; left out, a new automation has none and an existing one keeps what it has.","anyOf":[{"type":"integer","minimum":1,"maximum":50},{"type":"null"}]}},"required":["name","steps"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_test_run_automation":{"post":{"operationId":"flyra_test_run_automation","summary":"Test-run an automation (sends nothing)","tags":["Automations"],"description":"Walks a saved automation step by step against a sample lead and returns what each step would do, as the Test run button in the automation builder does: the message each text would say and who it would go to, the delays, which way each branch goes, the stage it would move the lead to. Nothing is sent, queued or changed. Waits and branches the run cannot know are simulated: lead_replies picks whether a wait-for-reply step sees a reply (default true), conditions_answer_yes picks the side of booked/paid/plan-style conditions (default true). A custom field if_else reads test_lead.custom_fields, and a field left out is a No, as on a live run; a stop_if is never answered in a test run, so the run walks past it. The sample lead defaults to John Doe, +15551234567, john@example.com, stage new; pass test_lead to change any of it. trigger_event picks which trigger to start from on an automation with several (default: its main trigger). To test against a real person instead, pass lead_id or customer_id (one of them): each step then shows the message as that person would get it, with their name, phone, email, stage and score. It is still a dry run: nothing is sent to them or anyone. Admins and Owners only, connected through OAuth as themselves.\n\nScope: `automations:read`.","x-required-scope":"automations:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"automation_id":{"type":"string","maxLength":200,"description":"Automation id from flyra_list_automations."},"trigger_event":{"description":"Which trigger to start from, on an automation with several. Default: its main trigger.","type":"string","maxLength":100},"test_lead":{"description":"The sample lead the run uses. Any field left out keeps the default.","type":"object","properties":{"first_name":{"type":"string","maxLength":100},"last_name":{"type":"string","maxLength":100},"phone":{"description":"Empty means the sample lead has no phone, so text steps are skipped.","type":"string","maxLength":40},"email":{"type":"string","maxLength":320},"status_stage":{"description":"The lead's stage name, for lead_stage_equals branches.","type":"string","maxLength":100},"score":{"description":"A lead score, for lead_score_over branches. Left out, that branch is simulated.","type":"number"},"custom_fields":{"description":"Custom field answers as text by field key, for custom_field_equals and custom_field_is_set branches, such as {\"preferred_channel\": \"sms\"}. A field left out is a No, as on a live run. These answers are not checked against the org's custom fields: a live run answers No for a key no field defines, and also matches a step set to the way an answer is shown against how it is saved (an option's label, Yes for a ticked box, a formatted amount or date), so confirm the key with the org's custom fields and use the same spelling the step uses.","type":"object","propertyNames":{"type":"string","maxLength":100},"additionalProperties":{"type":"string","maxLength":500}}}},"lead_id":{"description":"A lead id from this account to run against instead of the sample lead. Nothing is sent to them.","type":"string","maxLength":200},"customer_id":{"description":"A customer id from this account to run against instead of the sample lead. Nothing is sent to them.","type":"string","maxLength":200},"lead_replies":{"description":"Whether the lead replies at a wait-for-reply step. Default true.","type":"boolean"},"conditions_answer_yes":{"description":"The answer for conditions a test cannot check (booked, paid, on a plan...). Default true.","type":"boolean"}},"required":["automation_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_automation_results":{"post":{"operationId":"flyra_get_automation_results","summary":"Read how an automation's steps and A/B paths did","tags":["Automations"],"description":"Results counted from one automation's run history, for runs started in the last 30 days unless you pass from and to. steps has, per step key: reached, finished, failed, skipped, waiting, running, queued, stopped and replied. dropOff has, per step key: endedHere (runs that stopped at this step) and repliedAfter (a wait for reply wrote that the person replied at or after this step). splits has, per A/B split step and per path (the step that path goes to): percent, runs, replied (the person replied after the split), failed (a later step failed), booked and revenue_cents. booked and revenue_cents are an estimate, since a job is not tied to a run: booked counts runs whose customer (the run's customer, or its lead once converted) got a job that is not cancelled, created within 30 days after the split; revenue_cents adds up those jobs once completed, paid or review sent. A run with no customer is never booked. Per step, booked jobs and revenue are not included. capped true means the busiest runs were cut and the oldest are left out. Admins and Owners only. Sends nothing and changes nothing.\n\nScope: `automations:read`.","x-required-scope":"automations:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"automation_id":{"type":"string","description":"Automation id from flyra_list_automations."},"from":{"description":"Count runs started on or after this date, like 2026-10-01.","type":"string"},"to":{"description":"Count runs started on or before this date. Needs from. Now by default. At most 366 days from from.","type":"string"}},"required":["automation_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_copy_automation_steps":{"post":{"operationId":"flyra_copy_automation_steps","summary":"Copy steps from one automation into another","tags":["Automations"],"description":"Copies one or more steps, with their settings and the connections between them, into another automation or the same one. Each copied step gets a new key, returned in copied. The target is then saved through flyra_save_automation, so every save check applies, and the answer lists any problems. The target keeps whether it is on: if it is on, a connected copied step starts running for new runs. Pass connect_after with a step key of the target to join the first copied step to it. A connection to a step not copied is not brought along and is listed in connections_left_out. A trigger cannot be copied. A webhook signing secret stays behind and is listed in secrets_left_out: set one with flyra_set_webhook_secret. Sends nothing.\n\nScope: `automations:write`.","x-required-scope":"automations:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"source_automation_id":{"type":"string","description":"Automation to copy from, from flyra_list_automations."},"target_automation_id":{"type":"string","description":"Automation to copy into. It can be the same one."},"step_keys":{"minItems":1,"maxItems":59,"type":"array","items":{"type":"string","minLength":1},"description":"Keys of the steps to copy, from flyra_get_automation_graph."},"connect_after":{"description":"A step key in the target. The first copied step is connected after it.","type":"string"},"connect_when":{"description":"Which way out of connect_after. Defaults to `default`.","type":"string","enum":["default","condition_true","condition_false","on_reply","on_timeout"]}},"required":["source_automation_id","target_automation_id","step_keys"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_automation_folders":{"post":{"operationId":"flyra_list_automation_folders","summary":"List automation folders","tags":["Automations"],"description":"Returns the folders on the Automations page and which automations are filed in each. Automations not in any folder are not listed here; flyra_list_automations lists every automation. Folders only organise the page: they never change whether an automation runs.\n\nScope: `automations:read`.","x-required-scope":"automations:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_create_automation_folder":{"post":{"operationId":"flyra_create_automation_folder","summary":"Create an automation folder","tags":["Automations"],"description":"Creates a folder on the Automations page, the same as the Create folder button. Names are up to 60 characters and unique per company (a company can have up to 100 folders). File automations into it with flyra_move_automations_to_folder.\n\nScope: `automations:write`.","x-required-scope":"automations:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60,"description":"Folder name, for example \"Leads & Sales\"."}},"required":["name"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_rename_automation_folder":{"post":{"operationId":"flyra_rename_automation_folder","summary":"Rename an automation folder","tags":["Automations"],"description":"Renames a folder on the Automations page, the same as Rename in the folder's menu. Names are up to 60 characters and unique per company. Only the name changes; what is filed in it stays.\n\nScope: `automations:write`.","x-required-scope":"automations:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"folder_id":{"type":"string","description":"The folder, from flyra_list_automation_folders."},"name":{"type":"string","minLength":1,"maxLength":60,"description":"The new name."}},"required":["folder_id","name"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_delete_automation_folder":{"post":{"operationId":"flyra_delete_automation_folder","summary":"Remove an automation folder","tags":["Automations"],"description":"Removes a folder from the Automations page, the same as Remove folder in the folder's menu. Only the folder goes: the automations filed in it go back to the main list, not deleted and not switched on or off. unfiled is how many were in it. Pass confirm: true.\n\nScope: `automations:write`. Destructive: it deletes or cancels.","x-required-scope":"automations:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"folder_id":{"type":"string","description":"The folder, from flyra_list_automation_folders."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the folder is removed for good."}},"required":["folder_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_move_automations_to_folder":{"post":{"operationId":"flyra_move_automations_to_folder","summary":"Move automations into a folder","tags":["Automations"],"description":"Files automations into a folder on the Automations page, or takes them out of their folder when folder_id is null. An automation is in at most one folder, so moving it replaces where it was. Pass ids from flyra_list_automations (`job_reminders` files the Job Reminders row) and a folder_id from flyra_list_automation_folders or flyra_create_automation_folder. This only organises the page: it never turns an automation on or off. A built-in the company never set up (it shows on the page but has no id in flyra_list_automations) can only be filed on the Automations page; say so rather than reporting it filed.\n\nScope: `automations:write`.","x-required-scope":"automations:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"automation_ids":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"string"},"description":"Automation ids from flyra_list_automations."},"folder_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"The folder to file them in, or null to take them out of any folder."}},"required":["automation_ids","folder_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_duplicate_automation":{"post":{"operationId":"flyra_duplicate_automation","summary":"Duplicate an automation","tags":["Automations"],"description":"Copies an automation, steps and settings included, the same as Duplicate in the row menu on the Automations page. The copy is named \"Copy of …\" and always starts switched off, so it sends nothing until someone turns it on (flyra_enable_automation). A copy of a built-in becomes an ordinary automation.\n\nScope: `automations:write`.","x-required-scope":"automations:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"automation_id":{"type":"string","description":"Automation id from flyra_list_automations."}},"required":["automation_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_delete_automation":{"post":{"operationId":"flyra_delete_automation","summary":"Delete an automation","tags":["Automations"],"description":"Deletes an automation for good, the same as Delete in the row menu on the Automations page: its steps and its run history go with it, and anything it was waiting to send is dropped. This cannot be undone. Only an automation that is switched off can be deleted here; turn it off with flyra_disable_automation first. Confirm with the user before calling, and pass confirm: true.\n\nScope: `automations:write`. Destructive: it deletes or cancels.","x-required-scope":"automations:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"automation_id":{"type":"string","description":"Automation id from flyra_list_automations."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed the delete."}},"required":["automation_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_share_automation_link":{"post":{"operationId":"flyra_share_automation_link","summary":"Share an automation by link","tags":["Automations"],"description":"Creates the share link for one automation, the same as selecting one automation on the Automations page, pressing Share and then Create link: anyone who opens the link can add a copy of it to their own Flyra. Calling it again on an automation that is already shared keeps the same link and refreshes it to the automation's current steps (Share again on the page). This sends nothing. An automation with no steps yet cannot be shared. Admins and Owners only, connected through OAuth as themselves; an organization API key is refused. Confirm with the user before calling, and pass confirm: true.\n\nScope: `automations:write`.","x-required-scope":"automations:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"automation_id":{"type":"string","description":"Automation id from flyra_list_automations."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed making a public link to this automation."}},"required":["automation_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_create_webhook_subscription":{"post":{"operationId":"flyra_create_webhook_subscription","summary":"Send an event to another app as a webhook","tags":["Automations"],"description":"Subscribes an https URL to one Flyra event (job.completed, lead.created, invoice.paid and the rest): every time it happens, Flyra POSTs the lead, customer and job as JSON to the URL, signed, retried up to 3 times. It is made as an automation (the event, then a Send webhook step), created switched OFF: switch it on with flyra_enable_automation once a person has confirmed it, and off or away with flyra_disable_automation or flyra_delete_automation. The answer carries the signing secret ONCE; it is never shown again (rotate it with flyra_set_webhook_secret). Admins and Owners only.\n\nScope: `automations:write`.","x-required-scope":"automations:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120,"description":"What the subscription is called on the Automations page."},"event":{"type":"string","enum":["lead.created","form.submitted","call.missed","lead.not_contacted","lead.responded","lead.stage_changed","lead.converted","lead.reply_matched","lead.duplicate_detected","lead.manually_triggered","appointment.booked","appointment.reminder_due","appointment.rescheduled","appointment.completed","appointment.cancelled","appointment.on_the_way","appointment.no_show","lead.assigned","lead.unassigned","lead.lost","lead.reopened","lead.pipeline_changed","lead.value_changed","lead.custom_field_changed","lead.note_added","lead.meta_form_received","lead.google_lsa_received","form.booking_requested","form.photos_uploaded","referral.submitted","qr.scanned","sign.collected","sign.overdue","sign.dropped","pin.dropped","pin.status_changed","pin.objection_logged","pin.revisit_due","lead.idle_in_stage","lead.score_changed","lead.voicemail_left","lead.email_link_clicked","lead.website_visit","estimate.sent","estimate.accepted","estimate.created","estimate.viewed","estimate.option_selected","estimate.optional_item_changed","estimate.signed","estimate.deposit_paid","estimate.declined","estimate.self_scheduled","estimate.converted","estimate.not_viewed","estimate.viewed_no_answer","estimate.expiring","job.created","job.technician_assigned","job.reminder_due","job.on_the_way","job.running_late","job.arrived","job.started","job.completed","job.completed_nearby","job.overdue","job.unpaid","job.rescheduled","job.callback_scheduled","job.cancelled","job.restored","job.complaint_logged","job.complaint_resolved","job.touch_up_booked","tip_page.opened_no_tip","job.quality_check_submitted","job.quality_check_approved","job.quality_check_sent_back","job.deleted","job.checklist_completed","job.supplies_logged","job.signature_captured","job.photos_added","job.finished_early","job.upsell_added","job.note_added","job.total_changed","job.crew_changed","job.scheduled_from_later","job.field_changed","job.unassigned_soon","job.series_ending","invoice.sent","invoice.paid","invoice.viewed","invoice.created","invoice.overdue","invoice.split_second_due","payment.received","payment_link.opened_unpaid","payment.refunded","payment.removed","card.saved","payment.disputed","payment.failed","deposit.received","tip.requested_after_payment","tip.received","subscription.sent","subscription.activated","payment_method.requested","subscription.renewal_upcoming","tip.requested","subscription.cancelled","cancellation.requested","save_request.moved","subscription.amount_changed","subscription.charge_failed","subscription.paused","subscription.resumed","subscription.signed","subscription.viewed","subscription.visit_skipped","subscription.visit_completed","subscription.not_accepted","subscription.term_ending","subscription.anniversary","subscription.churn_risk","card.expiring","save_request.assigned","customer.created","customer.replied","customer.first_service","holiday.upcoming","referral.converted","referral.reward_released","customer.opted_out","customer.opted_in","customer.tag_added","customer.tag_removed","customer.updated","customer.deleted","customer.property_added","customer.converted_to_lead","message.delivery_failed","message.unanswered","sms_blast.replied","sms_blast.no_reply","email.received","email.bounced","customer.field_changed","customer.reply_matched","customer.manually_triggered","customer.arrived_geofence","customer.service_anniversary","customer.birthday","customer.ltv_milestone","call.voicemail_left","call.completed","call.outbound_no_answer","call.transcript_ready","call.menu_option_pressed","customer.balance_overdue","customer.lapsed","customer.email_link_clicked","customer.website_visit","review.requested","review.positive","review.negative","review.submitted","review.not_left","inventory.not_returned","inventory.low_stock","inventory.expiring","inventory.checked_out","inventory.item_added","inventory.maintenance_due","task.created","task.overdue","task.due","task.completed","employee.invited","employee.joined","employee.welcome_email","employee.knocking_session_ended","employee.knocking_session_started","employee.document_expiring","employee.team_chat_mentioned","employee.territory_crossed","google_calendar.event_created","automation.failed","expense.created","payout.sent","payout.failed","cash.low_collections","territory.created","territory.assigned","employee.clocked_in","employee.forgot_clock_out","campaign.response_rate_low","sms_blast.completed","sms_credits.low","timesheet.overtime","metric.threshold_reached","employee.deactivated","employee.location_sharing_off","contract.signed","employee.availability_changed","payroll.period_closed","texting_registration.changed","integration.disconnected","accounting.sync_failed","automation.finished","automation.chain_failed","record.date_reached","pricebook.price_changed","employee.first_job","schedule.tomorrow_light","weather.forecast_alert","google_review.posted","employee.missed_clock_in","revenue_goal.reached","sprint.started","season.started","schedule.overbooked","schedule.open_slot","route.published","leaderboard.rank_changed"],"description":"The event to send."},"url":{"type":"string","minLength":1,"maxLength":2000,"description":"The https URL to POST to. Private and local addresses are refused."}},"required":["name","event","url"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_webhooks":{"post":{"operationId":"flyra_list_webhooks","summary":"List the business's inbound and outbound webhooks","tags":["Automations"],"description":"Every outbound webhook (a Send webhook step: which automation, which event, where it sends, whether it is signed) and every inbound webhook (a Webhook trigger: its URL, its name, whether it is signed). Secrets are never listed. Admins and Owners only.\n\nScope: `automations:read`.","x-required-scope":"automations:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_webhook_secret":{"post":{"operationId":"flyra_set_webhook_secret","summary":"Set, rotate or remove a webhook signing secret","tags":["Automations"],"description":"For a Send webhook step: Flyra signs what it sends with the secret. For an inbound Webhook trigger: Flyra only accepts requests signed with it and refuses the rest with 401. A new secret replaces the old one at once, so update the other side straight after. The answer carries the new secret ONCE. clear: true removes it (an inbound webhook then takes unsigned requests again). step_key comes from flyra_list_webhooks. Admins and Owners only.\n\nScope: `automations:write`.","x-required-scope":"automations:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"automation_id":{"type":"string","minLength":1,"description":"Automation id from flyra_list_webhooks."},"step_key":{"type":"string","minLength":1,"maxLength":60,"description":"The Send webhook step or Webhook trigger step key."},"clear":{"description":"true removes the secret instead of setting a new one.","type":"boolean"}},"required":["automation_id","step_key"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_test_inbound_webhook":{"post":{"operationId":"flyra_test_inbound_webhook","summary":"Test an inbound webhook against a sample","tags":["Automations"],"description":"Shows what an inbound webhook automation would do with a request body, without running it: which phone and email it would match a customer on, the keys it found, and what each Create lead step's field map would fill. Pass sample, a JSON object, or leave it out to use the last request that arrived. Nothing is sent, saved or run, and the signature is not checked. Admins and Owners only.\n\nScope: `automations:read`.","x-required-scope":"automations:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"automation_id":{"type":"string","minLength":1,"description":"Automation id from flyra_list_webhooks."},"sample":{"description":"A request body to try. Left out, the newest one received.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["automation_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_preview_automation_run":{"post":{"operationId":"flyra_preview_automation_run","summary":"Preview running an automation by hand","tags":["Automations"],"description":"Shows what running an automation by hand would do, and changes nothing: how many leads or customers it would start for, the first few by name, which of its steps can text, email or notify someone, and whether the run is allowed. The automation must be saved with trigger_event lead.manually_triggered (runs for leads) or customer.manually_triggered (runs for customers). Choose records with ids, or a filter (query / status / city / tag / created dates). At most 200 records per run. An automation that can message people runs for ONE record at a time; for many records only an automation whose steps message nobody (tags, notes, stage changes) is allowed. Returns a confirm_token for flyra_run_automation, good for 15 minutes. Admins and Owners only.\n\nScope: `automations:write`.","x-required-scope":"automations:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"automation_id":{"type":"string","maxLength":200,"description":"Automation id from flyra_list_automations. It must start on lead.manually_triggered or customer.manually_triggered."},"ids":{"description":"Explicit lead or customer ids (raw UUIDs or semantic ids). A run still needs the confirm_token from flyra_preview_automation_run, even with ids.","maxItems":2000,"type":"array","items":{"type":"string"}},"query":{"description":"Free-text match on the entity's text columns. Matched literally: query=\"UNC (solar deal)\" finds that exact phrase, parentheses included.","type":"string"},"status":{"description":"Match any of these status values. Not available on customers.","type":"array","items":{"type":"string"}},"city":{"description":"customers and leads only.","type":"string"},"state":{"description":"customers and leads only.","type":"string"},"zip":{"description":"customers and leads only (leads match on postal_code).","type":"string"},"tag":{"description":"customers only — tag label or tag id.","type":"string"},"customer_id":{"description":"jobs, estimates and invoices only — records belonging to this customer.","type":"string"},"created_after":{"description":"ISO 8601 — records created on or after.","type":"string"},"created_before":{"description":"ISO 8601 — records created strictly before.","type":"string"},"last_booked_days_gt":{"description":"Not available here. Page the matches out of flyra_filter_customers and pass their `ids`.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"min_lifetime_value_cents":{"description":"Not available here — see last_booked_days_gt.","type":"integer","minimum":0,"maximum":9007199254740991},"has_subscription":{"description":"Not available here — see last_booked_days_gt.","type":"boolean"},"has_unpaid_invoice":{"description":"Not available here — see last_booked_days_gt.","type":"boolean"}},"required":["automation_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_run_automation":{"post":{"operationId":"flyra_run_automation","summary":"Run an automation by hand","tags":["Automations"],"description":"Starts an automation for the leads or customers chosen in flyra_preview_automation_run. Call the preview first, show the user its count, records and whether it messages anyone, then call this with the SAME automation and selection, the confirm_token, confirm: true and a new idempotency_key. If the records changed since the preview nothing runs and you preview again. A repeat of the same idempotency_key queues nothing. An automation that can text, email or notify runs for one record at a time. At most 10 runs per business per hour. Admins and Owners only.\n\nScope: `automations:write`.","x-required-scope":"automations:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"automation_id":{"type":"string","maxLength":200,"description":"Automation id from flyra_list_automations. It must start on lead.manually_triggered or customer.manually_triggered."},"ids":{"description":"Explicit lead or customer ids (raw UUIDs or semantic ids). A run still needs the confirm_token from flyra_preview_automation_run, even with ids.","maxItems":2000,"type":"array","items":{"type":"string"}},"query":{"description":"Free-text match on the entity's text columns. Matched literally: query=\"UNC (solar deal)\" finds that exact phrase, parentheses included.","type":"string"},"status":{"description":"Match any of these status values. Not available on customers.","type":"array","items":{"type":"string"}},"city":{"description":"customers and leads only.","type":"string"},"state":{"description":"customers and leads only.","type":"string"},"zip":{"description":"customers and leads only (leads match on postal_code).","type":"string"},"tag":{"description":"customers only — tag label or tag id.","type":"string"},"customer_id":{"description":"jobs, estimates and invoices only — records belonging to this customer.","type":"string"},"created_after":{"description":"ISO 8601 — records created on or after.","type":"string"},"created_before":{"description":"ISO 8601 — records created strictly before.","type":"string"},"last_booked_days_gt":{"description":"Not available here. Page the matches out of flyra_filter_customers and pass their `ids`.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"min_lifetime_value_cents":{"description":"Not available here — see last_booked_days_gt.","type":"integer","minimum":0,"maximum":9007199254740991},"has_subscription":{"description":"Not available here — see last_booked_days_gt.","type":"boolean"},"has_unpaid_invoice":{"description":"Not available here — see last_booked_days_gt.","type":"boolean"},"confirm_token":{"type":"string","maxLength":200,"description":"From flyra_preview_automation_run."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user saw the preview and wants it run."},"idempotency_key":{"type":"string","minLength":8,"maxLength":100,"description":"A new random string per intended run; a retry with the same key queues nothing more."}},"required":["automation_id","confirm_token","confirm","idempotency_key"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_automation_approvals":{"post":{"operationId":"flyra_list_automation_approvals","summary":"List automation messages waiting for approval","tags":["Texting"],"description":"Lists the texts and emails automations are holding for approval (steps saved with holdForApproval: true): who it goes to, the channel, the subject and words, the automation and step, and when it stops being approvable. A held message nobody approves in 72 hours is never sent; run_stopped: true means its run ended and it will not send. Admins and Owners see every one; anyone else sees those they were asked to approve. Approve with flyra_approve_automation_message or drop with flyra_discard_automation_message.\n\nScope: `sms:read`.","x-required-scope":"sms:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"description":"How many to return, newest first (default 25).","type":"integer","minimum":1,"maximum":100}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_approve_automation_message":{"post":{"operationId":"flyra_approve_automation_message","summary":"Approve an automation message","tags":["Texting"],"description":"Approves one text or email an automation held, optionally with edited words (body) or, for an email, an edited subject; the edited email words replace its paragraphs. Needs confirm: true. The message is not sent from here: the automation sends it within a minute through its normal send, which checks opt-out, quiet hours and the step's send window again, so a STOP still stops it and quiet hours still hold it. Refused when the message expired, was already decided, or its run stopped. Admins, Owners and the lead's owner it was held for.\n\nScope: `sms:send`.","x-required-scope":"sms:send","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"approval_id":{"type":"string","maxLength":100,"description":"From flyra_list_automation_approvals."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user saw the message and wants it sent."},"body":{"description":"Edited words to send instead of the held ones. Variables are not filled in here.","type":"string","maxLength":5000},"subject":{"description":"Email only: an edited subject.","type":"string","maxLength":200}},"required":["approval_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_discard_automation_message":{"post":{"operationId":"flyra_discard_automation_message","summary":"Discard an automation message","tags":["Texting"],"description":"Drops one text or email an automation held for approval. Nothing is sent; the automation skips that step and carries on with the next ones. Admins, Owners and the lead's owner it was held for.\n\nScope: `sms:send`. Destructive: it deletes or cancels.","x-required-scope":"sms:send","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"approval_id":{"type":"string","maxLength":100,"description":"From flyra_list_automation_approvals."}},"required":["approval_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_custom_fields":{"post":{"operationId":"flyra_list_custom_fields","summary":"List custom fields","tags":["Bulk"],"description":"Returns the company's custom fields for leads, customers, jobs or estimates, the list in Settings → Custom fields. Each field has a key: it is the {key} variable a message uses, the customFieldKey that custom_field_equals and custom_field_is_set conditions take, and the key flyra_set_custom_field_values writes.\n\nScope: depends on `entity` (for example `leads:write`).","x-required-scope":"varies","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["lead","customer","job","estimate"],"description":"Which record the fields belong to."},"include_archived":{"description":"Also return archived fields. Default false.","type":"boolean"}},"required":["object"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_save_custom_field":{"post":{"operationId":"flyra_save_custom_field","summary":"Create or edit a custom field","tags":["Automations"],"description":"Without field_id, adds a custom field for leads, customers, jobs or estimates, the same as Settings → Custom fields in Flyra. With field_id, changes its label, dropdown choices, help text, default answer or whether the customer sees it. The key (the {key} message variable) is set once from the label, or from key if given, and never changes afterwards; nor does the type. To change either, the field has to be archived on the page and a new one added. Types: text, textarea, number, currency, select, checkbox, date. A select needs options. Currency is in dollars.\n\nScope: `automations:write`.","x-required-scope":"automations:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"field_id":{"description":"The field to edit, from flyra_list_custom_fields. Leave out to create one.","type":"string"},"object":{"description":"Create only: whether the field is on leads, customers, jobs or estimates. A job field with the same key as an estimate field picks up the estimate's answer when the estimate becomes a job.","type":"string","enum":["lead","customer","job","estimate"]},"label":{"description":"The name people see. Required to create.","type":"string","maxLength":80},"key":{"description":"Create only: the variable name, letters, numbers and underscores. Derived from the label when left out.","type":"string","maxLength":60},"type":{"description":"Create only: the kind of answer.","type":"string","enum":["text","textarea","number","currency","select","checkbox","date"]},"options":{"description":"The choices of a select field. On an edit, the full new list.","maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"help_text":{"description":"A hint shown under the field. null clears it.","anyOf":[{"type":"string","maxLength":240},{"type":"null"}]},"default_value":{"description":"Job and estimate fields only: the answer every new job or estimate starts with. A select takes one of its options; a date is YYYY-MM-DD; checkboxes have none. null clears it.","anyOf":[{"anyOf":[{"type":"string","maxLength":500},{"type":"number"}]},{"type":"null"}]},"show_to_customer":{"description":"Estimate fields only: true prints the answer on the estimate the customer opens and its PDF.","type":"boolean"},"customer_can_answer":{"description":"Estimate fields only, never money: true asks the customer this field on the estimate link before they approve, and prints the answer. Turning it on turns show_to_customer on.","type":"boolean"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_custom_field_values":{"post":{"operationId":"flyra_set_custom_field_values","summary":"Set custom field values on a lead, customer, job or estimate","tags":["Bulk"],"description":"Saves answers to custom fields on one lead, customer, job or estimate, the same as editing them on its page. Only the keys passed change; null or \"\" clears that answer. Keys come from flyra_list_custom_fields for the same object. A select takes one of its choices (the value or the label), a checkbox true or false, a date YYYY-MM-DD, currency an amount in dollars.\n\nScope: depends on `entity` (for example `leads:write`).","x-required-scope":"varies","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["lead","customer","job","estimate"],"description":"Whether record_id is a lead, a customer, a job or an estimate."},"record_id":{"type":"string","description":"The record id, as the lead, customer, job or estimate tools return it (lead_…, cus_…, a job id or an estimate id)."},"values":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"description":"Field key → answer, for example { \"window_count\": 24, \"gate_code\": \"1234\" }."}},"required":["object","record_id","values"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_archive_custom_field":{"post":{"operationId":"flyra_archive_custom_field","summary":"Archive a custom field","tags":["Automations"],"description":"Stops using a custom field, as Stop using (the bin) on a field in Settings → Custom fields does. The field leaves the lead and customer panels and the automation variable picker, flyra_list_custom_fields returns it only with include_archived, and flyra_set_custom_field_values no longer takes its key. The answers people already gave stay on their records. Nothing in the app or here brings an archived field back; to ask the question again, add a new field. Pass confirm: true.\n\nScope: `automations:write`. Destructive: it deletes or cancels.","x-required-scope":"automations:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"field_id":{"type":"string","description":"The field to archive, from flyra_list_custom_fields."},"confirm":{"type":"boolean","const":true,"description":"Must be true: an archived field cannot be brought back."}},"required":["field_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_send_email":{"post":{"operationId":"flyra_send_email","summary":"Send a transactional email","tags":["Email"],"description":"Send an outbound email via Resend. Accepts plain text OR HTML — pass `html` for richer formatting, or `body` for plain text (auto-wrapped in a simple HTML shell).\n\nOptional `customer_id` looks up the recipient's email if `to` is omitted.\n\nCapped at 10 sends per minute per org (same posture as SMS). Use the SMS Blast tool for bulk.\n\nComposition tip: call flyra_get_invoice_link / flyra_get_estimate_link first, then paste the link into the body.\n\nScope: `email:send`.","x-required-scope":"email:send","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"description":"Recipient email. Omit when passing customer_id.","type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"customer_id":{"description":"Customer UUID or semantic id. If set and to is omitted, we look up customer.email.","type":"string"},"subject":{"type":"string","minLength":1,"maxLength":998},"body":{"description":"Plain text body. Becomes a simple HTML wrapper.","type":"string"},"html":{"description":"Raw HTML body. Overrides `body` if both are passed.","type":"string"},"reply_to":{"description":"Optional Reply-To header.","type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["subject"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_reply_email_thread":{"post":{"operationId":"flyra_reply_email_thread","summary":"Reply inside an email thread","tags":["Email"],"description":"Reply on an existing email thread, the way the Reply button in Inbox > Email does: the email goes to the one address the composer fills in (the sender of the latest email when it came in, else the address the latest email went to), threads onto the latest email (In-Reply-To), is branded with the company logo and name, and shows on the same thread in the Inbox.\n\nThe subject defaults to \"Re: <latest subject>\". Text only: the Inbox composer has no attachments, cc or bcc, so neither does this.\n\nPass thread_id from flyra_list_email_threads and confirm: true. Needs a signed-in person with the Inbox (an organization API key is refused) who can open the thread's customer. Shares the 10 per minute per org cap of flyra_send_email.\n\nScope: `email:send`.","x-required-scope":"email:send","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"thread_id":{"type":"string","minLength":1,"description":"Thread id from flyra_list_email_threads."},"body":{"type":"string","minLength":1,"description":"Plain text reply. Line breaks are kept."},"subject":{"description":"Defaults to \"Re: \" plus the latest email's subject.","type":"string","minLength":1,"maxLength":998},"confirm":{"type":"boolean","const":true,"description":"Must be true: this emails the person on the thread."}},"required":["thread_id","body","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_email_threads":{"post":{"operationId":"flyra_list_email_threads","summary":"List email threads","tags":["Email"],"description":"List email conversations (threads) newest-first, mirroring the email inbox. Each row carries the thread id, the customer link when the sender is known, the last subject and preview, and the unread count.\n\nOne customer can own several threads (billing / support / sales) — thread_id is the stable key, not the customer.\n\nPagination is cursor-based, not offset-based: pass the returned next_cursor back as cursor for the following page.\n\ndirection filters on the direction of each thread's most recent email, so direction=\"inbound\" is \"threads waiting on us\".\n\nScope: `email:read`.","x-required-scope":"email:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"direction":{"description":"Filters on the latest email in the thread. Omit for both.","type":"string","enum":["inbound","outbound"]},"search":{"description":"Substring match against customer name, customer email, sender email/name, and the last subject.","type":"string"},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":50},"cursor":{"description":"ISO timestamp from a previous call's next_cursor. Omit for the first page.","type":"string"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"thread_id":{"type":"string","description":"Pass to flyra_get_email_thread."},"customer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"cus_<uuid>, or null for a sender not matched to a customer."},"lead_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"lead_<uuid> when the thread is with a lead that is not a customer yet, else null."},"is_unknown_sender":{"type":"boolean"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_email_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO timestamp."},"last_subject":{"type":"string"},"last_preview":{"type":"string"},"last_direction":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"inbound or outbound."},"unread_count":{"type":"number"},"summary":{"type":"string"}},"required":["thread_id","customer_id","lead_id","is_unknown_sender","name","email","last_email_at","last_subject","last_preview","last_direction","unread_count","summary"],"additionalProperties":{}}},"limit":{"type":"number"},"truncated":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pass back as cursor for the next page."},"note":{"description":"Set when the first page is empty.","type":"string"}},"required":["items","limit","truncated","next_cursor"],"additionalProperties":{}}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_email_thread":{"post":{"operationId":"flyra_get_email_thread","summary":"Get the emails on a thread","tags":["Email"],"description":"Return the emails on one thread, oldest-first within the page so the agent reads it like a transcript.\n\nPass thread_id from flyra_list_email_threads. Bodies come back as plain text where available, falling back to the HTML body.\n\nScope: `email:read`.","x-required-scope":"email:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"thread_id":{"type":"string","description":"Thread id from flyra_list_email_threads."},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":50}},"required":["thread_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"thread_id":{"type":"string"},"customer_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"lead_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"lead_<uuid> when the thread is with a lead that is not a customer yet, else null."},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"email_<uuid>."},"direction":{"anyOf":[{"type":"string"},{"type":"null"}]},"from":{"anyOf":[{"type":"string"},{"type":"null"}]},"to":{"anyOf":[{"type":"string"},{"type":"null"}]},"subject":{"anyOf":[{"type":"string"},{"type":"null"}]},"body":{"type":"string"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"read":{"type":"boolean"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO timestamp."}},"required":["id","direction","from","to","subject","body","status","read","created_at"],"additionalProperties":{}},"description":"Oldest first within the page."},"limit":{"type":"number"},"truncated":{"type":"boolean"}},"required":["thread_id","customer_id","lead_id","items","limit","truncated"],"additionalProperties":{}}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_email_domain":{"post":{"operationId":"flyra_get_email_domain","summary":"Get the email domain","tags":["Settings"],"description":"The org's own email domain: which address mail goes out from now, the connected domain if any, its status, and the DNS records with a per-record check (found / missing / wrong, with a fix).\n\nRecords carry `fqdn` for DNS APIs and `name` for DNS panels. `next_step` says what to do next.\n\nScope: `settings:read`.","x-required-scope":"settings:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"current_from":{"type":"string","description":"The address mail goes out from right now."},"current_reply_to":{"anyOf":[{"type":"string"},{"type":"null"}]},"can_edit":{"type":"boolean"},"next_step":{"type":"string","description":"What to do next, in one sentence."},"domain":{"anyOf":[{"type":"object","properties":{"domain":{"type":"string"},"from_address":{"type":"string"},"reply_address":{"type":"string"},"send_status":{"type":"string","description":"pending | verified | failed"},"reply_status":{"type":"string","description":"pending | verified | failed"},"live":{"type":"boolean"},"primary":{"type":"boolean","description":"The org chose this domain as its sender."},"can_be_primary":{"type":"boolean"},"dns_provider":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"}},"required":["name","url"],"additionalProperties":{}},{"type":"null"}]},"records":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string","description":"Host as typed in a DNS panel, relative to the zone."},"fqdn":{"type":"string","description":"Fully qualified name, for DNS APIs."},"value":{"type":"string"},"priority":{"anyOf":[{"type":"number"},{"type":"null"}]},"optional":{"type":"boolean"},"dns_status":{"type":"string","description":"found | missing | wrong | unchecked"},"hint":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["type","name","fqdn","value","priority","optional","dns_status","hint"],"additionalProperties":{}}},"last_checked_at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["domain","from_address","reply_address","send_status","reply_status","live","primary","can_be_primary","dns_provider","records","last_checked_at"],"additionalProperties":{}},{"type":"null"}]}},"required":["current_from","current_reply_to","can_edit","next_step","domain"],"additionalProperties":{}}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_connect_email_domain":{"post":{"operationId":"flyra_connect_email_domain","summary":"Connect an email domain","tags":["Settings"],"description":"Start sending from the org's own address, e.g. office@acmepools.com. Registers acmepools.com (sending) and reply.acmepools.com (receiving replies) and returns the DNS records to add.\n\nNothing changes for customers until the records verify AND the domain is made primary (flyra_set_email_domain_primary). The business's existing inbox and website are not touched. One domain per org; disconnect first to change it. Admin only.\n\nScope: `settings:write`.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"from_address":{"type":"string","description":"Address to send from, on a domain the business owns, e.g. office@acmepools.com. Not gmail.com etc."}},"required":["from_address"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"current_from":{"type":"string","description":"The address mail goes out from right now."},"current_reply_to":{"anyOf":[{"type":"string"},{"type":"null"}]},"can_edit":{"type":"boolean"},"next_step":{"type":"string","description":"What to do next, in one sentence."},"domain":{"anyOf":[{"type":"object","properties":{"domain":{"type":"string"},"from_address":{"type":"string"},"reply_address":{"type":"string"},"send_status":{"type":"string","description":"pending | verified | failed"},"reply_status":{"type":"string","description":"pending | verified | failed"},"live":{"type":"boolean"},"primary":{"type":"boolean","description":"The org chose this domain as its sender."},"can_be_primary":{"type":"boolean"},"dns_provider":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"}},"required":["name","url"],"additionalProperties":{}},{"type":"null"}]},"records":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string","description":"Host as typed in a DNS panel, relative to the zone."},"fqdn":{"type":"string","description":"Fully qualified name, for DNS APIs."},"value":{"type":"string"},"priority":{"anyOf":[{"type":"number"},{"type":"null"}]},"optional":{"type":"boolean"},"dns_status":{"type":"string","description":"found | missing | wrong | unchecked"},"hint":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["type","name","fqdn","value","priority","optional","dns_status","hint"],"additionalProperties":{}}},"last_checked_at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["domain","from_address","reply_address","send_status","reply_status","live","primary","can_be_primary","dns_provider","records","last_checked_at"],"additionalProperties":{}},{"type":"null"}]}},"required":["current_from","current_reply_to","can_edit","next_step","domain"],"additionalProperties":{}}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_check_email_domain":{"post":{"operationId":"flyra_check_email_domain","summary":"Check the email domain's DNS","tags":["Settings"],"description":"Re-checks the DNS records now (asks the email provider to verify and looks each record up). Call after adding records. DNS can take minutes to hours; Flyra also re-checks on its own. Admin only.\n\nScope: `settings:write`.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"current_from":{"type":"string","description":"The address mail goes out from right now."},"current_reply_to":{"anyOf":[{"type":"string"},{"type":"null"}]},"can_edit":{"type":"boolean"},"next_step":{"type":"string","description":"What to do next, in one sentence."},"domain":{"anyOf":[{"type":"object","properties":{"domain":{"type":"string"},"from_address":{"type":"string"},"reply_address":{"type":"string"},"send_status":{"type":"string","description":"pending | verified | failed"},"reply_status":{"type":"string","description":"pending | verified | failed"},"live":{"type":"boolean"},"primary":{"type":"boolean","description":"The org chose this domain as its sender."},"can_be_primary":{"type":"boolean"},"dns_provider":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"}},"required":["name","url"],"additionalProperties":{}},{"type":"null"}]},"records":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string","description":"Host as typed in a DNS panel, relative to the zone."},"fqdn":{"type":"string","description":"Fully qualified name, for DNS APIs."},"value":{"type":"string"},"priority":{"anyOf":[{"type":"number"},{"type":"null"}]},"optional":{"type":"boolean"},"dns_status":{"type":"string","description":"found | missing | wrong | unchecked"},"hint":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["type","name","fqdn","value","priority","optional","dns_status","hint"],"additionalProperties":{}}},"last_checked_at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["domain","from_address","reply_address","send_status","reply_status","live","primary","can_be_primary","dns_provider","records","last_checked_at"],"additionalProperties":{}},{"type":"null"}]}},"required":["current_from","current_reply_to","can_edit","next_step","domain"],"additionalProperties":{}}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_email_domain_primary":{"post":{"operationId":"flyra_set_email_domain_primary","summary":"Choose the sending address","tags":["Settings"],"description":"Choose what mail goes out from: \"domain\" (the connected domain, once verified) or \"flyra\" (the org's Flyra address, always available). If the domain later stops verifying, mail falls back to the Flyra address on its own. Admin only.\n\nScope: `settings:write`.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"primary":{"type":"string","enum":["domain","flyra"]}},"required":["primary"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"current_from":{"type":"string","description":"The address mail goes out from right now."},"current_reply_to":{"anyOf":[{"type":"string"},{"type":"null"}]},"can_edit":{"type":"boolean"},"next_step":{"type":"string","description":"What to do next, in one sentence."},"domain":{"anyOf":[{"type":"object","properties":{"domain":{"type":"string"},"from_address":{"type":"string"},"reply_address":{"type":"string"},"send_status":{"type":"string","description":"pending | verified | failed"},"reply_status":{"type":"string","description":"pending | verified | failed"},"live":{"type":"boolean"},"primary":{"type":"boolean","description":"The org chose this domain as its sender."},"can_be_primary":{"type":"boolean"},"dns_provider":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"}},"required":["name","url"],"additionalProperties":{}},{"type":"null"}]},"records":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string","description":"Host as typed in a DNS panel, relative to the zone."},"fqdn":{"type":"string","description":"Fully qualified name, for DNS APIs."},"value":{"type":"string"},"priority":{"anyOf":[{"type":"number"},{"type":"null"}]},"optional":{"type":"boolean"},"dns_status":{"type":"string","description":"found | missing | wrong | unchecked"},"hint":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["type","name","fqdn","value","priority","optional","dns_status","hint"],"additionalProperties":{}}},"last_checked_at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["domain","from_address","reply_address","send_status","reply_status","live","primary","can_be_primary","dns_provider","records","last_checked_at"],"additionalProperties":{}},{"type":"null"}]}},"required":["current_from","current_reply_to","can_edit","next_step","domain"],"additionalProperties":{}}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_send_email_domain_records":{"post":{"operationId":"flyra_send_email_domain_records","summary":"Email the DNS records to someone","tags":["Settings"],"description":"Emails the DNS records for the connected domain to whoever manages it (a web designer, IT person). Admin only.\n\nScope: `settings:write`.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["email"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_disconnect_email_domain":{"post":{"operationId":"flyra_disconnect_email_domain","summary":"Disconnect the email domain","tags":["Settings"],"description":"Stops using the org's own domain: mail goes out from the Flyra address again and replies to the reply. subdomain stop reaching Flyra. The DNS records can be removed afterwards. Admin only.\n\nScope: `settings:write`. Destructive: it deletes or cancels.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"current_from":{"type":"string","description":"The address mail goes out from right now."},"current_reply_to":{"anyOf":[{"type":"string"},{"type":"null"}]},"can_edit":{"type":"boolean"},"next_step":{"type":"string","description":"What to do next, in one sentence."},"domain":{"anyOf":[{"type":"object","properties":{"domain":{"type":"string"},"from_address":{"type":"string"},"reply_address":{"type":"string"},"send_status":{"type":"string","description":"pending | verified | failed"},"reply_status":{"type":"string","description":"pending | verified | failed"},"live":{"type":"boolean"},"primary":{"type":"boolean","description":"The org chose this domain as its sender."},"can_be_primary":{"type":"boolean"},"dns_provider":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"}},"required":["name","url"],"additionalProperties":{}},{"type":"null"}]},"records":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string","description":"Host as typed in a DNS panel, relative to the zone."},"fqdn":{"type":"string","description":"Fully qualified name, for DNS APIs."},"value":{"type":"string"},"priority":{"anyOf":[{"type":"number"},{"type":"null"}]},"optional":{"type":"boolean"},"dns_status":{"type":"string","description":"found | missing | wrong | unchecked"},"hint":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["type","name","fqdn","value","priority","optional","dns_status","hint"],"additionalProperties":{}}},"last_checked_at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["domain","from_address","reply_address","send_status","reply_status","live","primary","can_be_primary","dns_provider","records","last_checked_at"],"additionalProperties":{}},{"type":"null"}]}},"required":["current_from","current_reply_to","can_edit","next_step","domain"],"additionalProperties":{}}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_blocked_numbers":{"post":{"operationId":"flyra_list_blocked_numbers","summary":"List blocked phone numbers","tags":["Settings"],"description":"The blocked numbers in the Spam and blocked numbers section of Settings > Organization > Phone, newest first: each number (E.164), its reason, who added it and when. Calls from a blocked number hang up before anything rings, and texts from it are dropped. Through the connector it needs the settings:read scope, which only Admins and Owners get. Needs a signed-in person; an organization API key is refused. Read only.\n\nScope: `settings:read`.","x-required-scope":"settings:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_block_phone_number":{"post":{"operationId":"flyra_block_phone_number","summary":"Block a phone number","tags":["Settings"],"description":"The Number to block field in the Spam and blocked numbers section of Settings > Organization > Phone: adds a number to the blocked list so its calls hang up before anything rings and its texts are dropped. Calls out to it still work. Admins only, as on that screen. The number is read the way the screen reads it (a local number uses the business's country). Refused when the number is already blocked. Needs a signed-in person; an organization API key is refused. Nothing is sent to anyone.\n\nScope: `settings:write`.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"string","minLength":1,"description":"The phone number to block, e.g. \"(555) 123-4567\" or \"+15551234567\"."},"label":{"description":"Optional reason shown beside the number (the Reason field), e.g. \"Robocaller\". Cut to 200 characters.","type":"string"}},"required":["number"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_unblock_phone_number":{"post":{"operationId":"flyra_unblock_phone_number","summary":"Unblock a phone number","tags":["Settings"],"description":"The Unblock button on a row of the Spam and blocked numbers section of Settings > Organization > Phone: deletes that entry, so calls and texts from the number come through again. Admins only, as on that screen. Use the id from flyra_list_blocked_numbers. Needs a signed-in person; an organization API key is refused. Nothing is sent to anyone.\n\nScope: `settings:write`. Destructive: it deletes or cancels.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"blocked_number_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The id from flyra_list_blocked_numbers."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed removing this number from the blocked list."}},"required":["blocked_number_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_voicemail_greeting":{"post":{"operationId":"flyra_get_voicemail_greeting","summary":"Get the voicemail greeting","tags":["Settings"],"description":"The Greeting row of the Voicemail section on Settings > Organization > Phone, for the organization default: what callers hear before they leave a message when nobody can take the call. source is \"default\" (Standard greeting), \"text\" (Custom message, spoken for you) or \"audio\" (Uploaded audio); text is the custom message; has_audio says whether a recording is uploaded, and preview_url is a link to it that expires after an hour. A greeting set on one number alone is not covered here. Any active member of the business may read it, as the endpoint that section loads from allows. Needs a signed-in person; an organization API key is refused. Read only.\n\nScope: `settings:read`.","x-required-scope":"settings:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_voicemail_greeting":{"post":{"operationId":"flyra_set_voicemail_greeting","summary":"Set the voicemail greeting","tags":["Settings"],"description":"Save on the Voicemail section of Settings > Organization > Phone, for the organization default: choose the Standard greeting, a Custom message (spoken for you) with its words, or an Uploaded audio file that is already uploaded (uploading stays in the app). With source \"text\", text replaces the custom message; leave it out to keep the saved one. Refused when \"text\" has no message to speak or \"audio\" has no file. Admins only, as on that screen. A greeting for one number alone is not set here. Needs a signed-in person; an organization API key is refused. Nothing is sent to anyone.\n\nScope: `settings:write`.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string","enum":["default","text","audio"],"description":"\"default\" = Standard greeting, \"text\" = Custom message (spoken for you), \"audio\" = Uploaded audio."},"text":{"description":"The custom message callers hear, up to 2500 characters. Only used with source \"text\".","type":"string","maxLength":2500}},"required":["source"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_phone_call_settings":{"post":{"operationId":"flyra_get_phone_call_settings","summary":"Get spam, forwarding and recording settings","tags":["Settings"],"description":"The business-wide call handling on Settings > Messages > Phone. caller_id: name is the Caller ID name the business saved (null = its business name is used), shown_as is what outgoing calls display (letters, numbers and spaces, up to max_length), applies_to_number is false when the number is not one Flyra can set a caller name on. outbound_call_lines lists each active line of the business with its id, number and label, for flyra_set_outbound_call_line; is_calling_line marks the line calls go out from right now, and can_place_calls is false for a line flyra_set_outbound_call_line would refuse. Texts do not follow this choice. spam_screening is what happens to a call the carrier flags as likely spam: \"voicemail\" (send it to voicemail, the default), \"reject\" (hang up on it) or \"off\" (ring as normal). call_forwarding: forward_to_number is the outside phone calls go to (null = no forwarding), forward_immediately true sends every call there before anyone in the app rings. call_recording: whether inbound and outbound calls are recorded, the disclosure callers hear and how many days recordings are kept. Settings for one number alone are not covered here. Any active member of the business may read it, as the endpoint that page loads from allows. Needs a signed-in person; an organization API key is refused. Read only.\n\nScope: `settings:read`.","x-required-scope":"settings:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_outbound_call_line":{"post":{"operationId":"flyra_set_outbound_call_line","summary":"Set the line calls go out from","tags":["Settings"],"description":"The Calls go out from choice on Settings > Messages > Phone: the line every outgoing call shows as its number. Use a line id from outbound_call_lines in flyra_get_phone_call_settings, or null to go back to automatic, where Flyra picks the line. A line that is not active, not dedicated, not this business's, or that Flyra cannot place calls from is refused. This covers calls only: texts pick their own line and do not change. Admins only, as on that screen. This changes the number customers see when the business calls them, so confirm the line with the user first. Needs a signed-in person; an organization API key is refused. Nothing is sent to anyone.\n\nScope: `settings:write`.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"phone_number_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"A line id from flyra_get_phone_call_settings, or null to go back to automatic. A phone_<id> id from another tool also works."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed the line calls go out from."}},"required":["phone_number_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_spam_screening":{"post":{"operationId":"flyra_set_spam_screening","summary":"Set spam call screening","tags":["Settings"],"description":"The Spam calls choice on Settings > Messages > Phone: what happens to an incoming call the carrier flags as likely spam, on every number the business owns. \"voicemail\" sends it to voicemail, \"reject\" hangs up on it, \"off\" lets it ring as normal. The numbers are switched first; if any number refuses, nothing is saved and the numbers are put back. Admins only, as on that screen. This changes how the business's incoming calls are handled, so confirm the choice with the user first. Needs a signed-in person; an organization API key is refused. Nothing is sent to anyone.\n\nScope: `settings:write`.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"setting":{"type":"string","enum":["off","voicemail","reject"],"description":"\"voicemail\" = send likely spam to voicemail, \"reject\" = hang up on it, \"off\" = ring as normal."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed this spam call setting."}},"required":["setting","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_call_forwarding":{"post":{"operationId":"flyra_set_call_forwarding","summary":"Set call forwarding","tags":["Settings"],"description":"Save on the Call forwarding section of Settings > Messages > Phone, for the business default: forward_to_number is the outside phone (a cell, say) incoming calls go to; null or \"\" turns forwarding off. forward_immediately true sends every call there before anyone in the app rings; false rings the team first and forwards when nobody answers. Pass either or both; what you leave out stays as saved. A Flyra number is refused, so calls cannot loop. A number set on one line alone is not changed here. Admins only, as on that screen. This changes where the business's incoming calls go, so confirm the number and timing with the user first. Needs a signed-in person; an organization API key is refused. Nothing is sent to anyone.\n\nScope: `settings:write`.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"forward_to_number":{"description":"The phone to forward to, e.g. \"(555) 123-4567\" or \"+15551234567\". A local number uses the business's country. null or \"\" turns forwarding off.","anyOf":[{"type":"string"},{"type":"null"}]},"forward_immediately":{"description":"true = forward every call right away; false = ring the team first, forward when nobody answers.","type":"boolean"},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed the forwarding number and timing."}},"required":["confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_call_recording":{"post":{"operationId":"flyra_set_call_recording","summary":"Set call recording","tags":["Settings"],"description":"Save on the Call recording section of Settings > Messages > Phone: whether inbound and outbound calls are recorded, whether callers hear a disclosure first and what it says, and how many days recordings are kept (1 to 3650). Pass only what changes; what you leave out stays as saved. Recording laws differ by place; keep the disclosure on unless the user is sure. Admins only, as on that screen. This changes how the business's calls are handled, so confirm with the user first. Needs a signed-in person; an organization API key is refused. Nothing is sent to anyone.\n\nScope: `settings:write`.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"record_inbound":{"description":"Record incoming calls.","type":"boolean"},"record_outbound":{"description":"Record outgoing calls.","type":"boolean"},"disclosure_enabled":{"description":"Play the disclosure to callers before a recorded call.","type":"boolean"},"disclosure_text":{"description":"What the disclosure says. Cannot be empty; cut to 500 characters.","type":"string"},"retention_days":{"description":"Days a recording is kept, 1 to 3650.","type":"number"},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed these recording settings."}},"required":["confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_caller_id_name":{"post":{"operationId":"flyra_set_caller_id_name","summary":"Set the Caller ID name","tags":["Settings"],"description":"Save on the Caller ID section of Settings > Messages > Phone: the name people see when the business calls them. Only letters, numbers and spaces show, up to 15 characters; anything else is dropped when it is sent to the phone carrier. \"\" clears it, and the business name is used again. It is saved first, then pushed to the business's Flyra number; carriers can take a day or more to show it. telnyx_sync says whether the push went through (reason \"byod\" = a number Flyra cannot set it on, \"no_number\" = no number yet, it is applied when one is set up). Admins only, as on that screen. This changes what customers see on the business's calls, so confirm the name with the user first. Needs a signed-in person; an organization API key is refused. Nothing is sent to anyone.\n\nScope: `settings:write`.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The Caller ID name, e.g. \"Acme Pest\". \"\" clears it."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed this Caller ID name."}},"required":["name","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_call_receivers":{"post":{"operationId":"flyra_get_call_receivers","summary":"Get who rings for incoming calls","tags":["Settings"],"description":"The Who rings section of Settings > Messages > Phone: who the business's phones ring for an incoming call. mode \"default_admins\" is Ring all Admins (default_receivers lists who that rings right now); mode \"explicit\" rings only selected_employee_ids. eligible is every active team member who can be picked. Any active member of the business may read it, as the endpoint that section loads from allows. Needs a signed-in person; an organization API key is refused. Read only.\n\nScope: `settings:read`.","x-required-scope":"settings:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_call_receivers":{"post":{"operationId":"flyra_set_call_receivers","summary":"Set who rings for incoming calls","tags":["Settings"],"description":"Save on the Who rings section of Settings > Messages > Phone: whose phones ring for an incoming call. employee_ids replaces the whole saved list: an empty list is Ring all Admins, otherwise only those team members ring. Use employee_id values from eligible in flyra_get_call_receivers; anyone not an active, linked member of the business is refused and nothing changes. Admins only, as on that screen. Needs a signed-in person; an organization API key is refused. Confirm with the user first. Nothing is sent to anyone. Returns the section as it reads after the save.\n\nScope: `settings:write`. Destructive: it deletes or cancels.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_ids":{"type":"array","items":{"type":"string"},"description":"Employee ids (emp_<uuid> or uuid) whose phones should ring. [] = Ring all Admins."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed who should ring for incoming calls."}},"required":["employee_ids","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_calls":{"post":{"operationId":"flyra_list_calls","summary":"List phone calls","tags":["Calls"],"description":"List the org's phone call history, newest first. Covers both inbound and outbound calls and mirrors the Phone page.\n\nUse filter=\"missed\" for the missed-call list (this also includes calls that landed in voicemail) — that is the usual \"who do we need to call back\" query. filter=\"answered\" returns only calls a human picked up. filter=\"live\" returns only calls in progress right now (status initiated, ringing or answered, and not ended); end one of your own with flyra_hang_up_call.\n\nNarrow to one person with customer_id or contact_id. Each row carries direction, status, a missed boolean, timestamps, duration, the resolved caller name, the contact/customer link, and has_transcript.\n\nTo review what was said on calls (for example, why leads did or did not book), pass transcribed_only=true and since, and include_transcripts=true to get each call's full transcript text in the same page. flyra_get_call returns one call's transcript split by speaker plus a link to the recording.\n\nScope: `calls:read`.","x-required-scope":"calls:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"filter":{"description":"Default \"all\". \"missed\" includes voicemail; \"answered\" means someone picked up; \"live\" means in progress now.","type":"string","enum":["all","missed","answered","live"]},"direction":{"description":"Omit for both directions.","type":"string","enum":["inbound","outbound"]},"customer_id":{"description":"Customer UUID or semantic id — resolved to their contact.","type":"string"},"contact_id":{"description":"Contact UUID or semantic id. Takes precedence over customer_id.","type":"string"},"transcribed_only":{"description":"Only calls that were recorded and transcribed.","type":"boolean"},"since":{"description":"ISO 8601 — only calls that started on or after.","type":"string"},"include_transcripts":{"description":"Add each call's full transcript text (null when there is none). Default false; transcripts are long, so keep limit small.","type":"boolean"},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":50},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_call":{"post":{"operationId":"flyra_get_call","summary":"Get one phone call","tags":["Calls"],"description":"Fetch a single call by id, including notes, hangup cause, and the call outcome when one was recorded.\n\nWhen the call was recorded and transcribed it also returns transcript (the full text), transcript_turns (the same words split into customer and team turns, best effort, null when the split failed) and recording_url, a link to the audio file that expires after an hour. transcript_status says where a missing transcript stands: processing, none (no speech, e.g. a hang-up), failed, or null when the call was never recorded.\n\nScope: `calls:read`.","x-required-scope":"calls:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"call_id":{"type":"string","description":"Call UUID or semantic id from flyra_list_calls."}},"required":["call_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_call_notes":{"post":{"operationId":"flyra_update_call_notes","summary":"Write notes on a phone call","tags":["Calls"],"description":"Write the notes on one call, the notes field flyra_get_call returns, after the call: what happened, the outcome or disposition in your own words, next steps. This replaces the call's notes; read them first with flyra_get_call to add to them. An empty string clears them.\n\nFlyra has no separate disposition field, so put the disposition in the notes. call_outcome (answered, missed and the like) is set by the phone system and is not changed here.\n\nfollow_up adds one task, as on Dashboard > Tasks (the same rules as flyra_create_task), owned by you and linked to the caller's customer when the call has one you can open. Needs a signed-in person whose role can see Messages; an organization API key is refused. Nothing is sent to a customer; a follow-up runs the company's Task Created automations, as adding a task in the app does.\n\nScope: `calls:write`.","x-required-scope":"calls:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"call_id":{"type":"string","description":"Call UUID or semantic id from flyra_list_calls or flyra_get_call."},"notes":{"type":"string","description":"The call's notes, replacing what is there. Empty string clears them."},"follow_up":{"description":"Also add one follow-up task for this call.","type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":280},"notes":{"type":"string"},"due_date":{"description":"ISO timestamp or date.","type":"string"}},"required":["title"]}},"required":["call_id","notes"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_hang_up_call":{"post":{"operationId":"flyra_hang_up_call","summary":"Hang up a call","tags":["Calls"],"description":"The hang-up button on a call in progress in the Flyra app: ends one of your own calls now, a call you dialed out from Flyra. A call someone else placed, or a call ringing in to the business, is not found here. Use flyra_list_calls (direction \"outbound\") or flyra_get_call for the id and the call's status. A call that already ended answers already_ended true and nothing changes. A call that has not reached the phone network yet is refused. Needs a signed-in person; an organization API key is refused. Nothing is sent to anyone.\n\nScope: `calls:write`. Destructive: it deletes or cancels.","x-required-scope":"calls:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"call_id":{"type":"string","description":"Call UUID or semantic id from flyra_list_calls or flyra_get_call."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed ending this call now."}},"required":["call_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_transfer_call":{"post":{"operationId":"flyra_transfer_call","summary":"Transfer a call to a teammate","tags":["Calls"],"description":"Blind transfer: hands one of your own calls in progress (a call you dialed out from Flyra) to a teammate, ringing their Flyra app or phone for up to 30 seconds. Your side of the call ends once it is handed over. Only your own live calls; a call someone else placed is not found. The teammate must be active on the team and signed in to the Flyra app on some device, or the transfer is refused. No warm (consult) transfer. Needs a signed-in person; an organization API key is refused. Use flyra_list_calls filter \"live\" for the call id and flyra_list_employees for the teammate's employee id.\n\nScope: `calls:write`. Destructive: it deletes or cancels.","x-required-scope":"calls:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"call_id":{"type":"string","description":"Call UUID or semantic id from flyra_list_calls or flyra_get_call."},"to_employee_id":{"type":"string","description":"The teammate's employee UUID or semantic id."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed handing this call over now."}},"required":["call_id","to_employee_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_call_outcome":{"post":{"operationId":"flyra_set_call_outcome","summary":"Mark how a call went","tags":["Calls"],"description":"After one of your own outgoing calls ends, say how it really went: no_answer, voicemail or answered. Use it when the phone system counted the call as answered but nobody picked up (voicemail answered it, for example). no_answer or voicemail on a call the phone system counted as answered starts the automations on \"A call you make is not answered\" (call.outbound_no_answer) once for that call, with outcome set to what you chose and marked_by_agent true. A call the phone system already counted as unanswered already started them and does not start them again; on a call it reported as a short call, an automation that already ran for that short call does not run again. Only your own outgoing calls, after they end. Needs a signed-in person; an organization API key is refused. Nothing is sent to anyone by this tool itself.\n\nScope: `calls:write`.","x-required-scope":"calls:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"call_id":{"type":"string","description":"Call UUID or semantic id from flyra_list_calls or flyra_get_call."},"outcome":{"type":"string","enum":["no_answer","voicemail","answered"],"description":"How the call went: no_answer, voicemail or answered."}},"required":["call_id","outcome"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_phone_menu":{"post":{"operationId":"flyra_get_phone_menu","summary":"Get the phone menu","tags":["Settings"],"description":"Read the phone menu on Settings > Messages (the menu callers hear when they ring the business number): whether it is on, the prompt (text, or an uploaded audio file with a one-hour preview link), and each digit's action: ring_all (ring everyone), ring_users (ring only the teammates in user_ids), forward (to forward_to, a phone number outside Flyra) or voicemail.\n\nteammates lists who a ring_users digit can ring (user_id, name, role). A user_id on a digit that is not in teammates has left the team: that digit skips them, rings everyone if none is left, and the menu cannot be saved again until they are replaced.\n\nnoInputAction is where a caller who presses no key goes once the menu has played three times: ring_all (ring everyone, the default) or voicemail (filters robocalls that never press a key). A key that is not in the menu always rings everyone.\n\nforwardsImmediately true means the business forwards every call before the menu plays, so the menu is not heard. Needs a signed-in Flyra user, not an organization API key. Read only.\n\nScope: `settings:read`.","x-required-scope":"settings:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_phone_menu":{"post":{"operationId":"flyra_update_phone_menu","summary":"Update the phone menu","tags":["Settings"],"description":"The Save button on Settings > Messages > Phone menu, Admins only. Sets what callers to the business number hear and where each digit sends them. To send callers to an outside AI voice agent, give a digit action \"forward\" with forward_to set to that agent's phone number in E.164 (+15551234567). A Flyra number is refused. To send a digit to specific people, give it action \"ring_users\" with user_ids taken from the teammates list of flyra_get_phone_menu; if none of them answers, the call goes to the line's usual fallback (voicemail by default), not to everyone.\n\nOnly the fields you pass change. options replaces the whole list, so read flyra_get_phone_menu first and send every digit you want to keep. Turning the menu on needs at least one option and a prompt. An uploaded audio prompt is set in the app, not here.\n\nThis changes where the business's inbound callers go, so confirm the menu (every digit and forward number) with the user before calling. Returns the saved menu.\n\nScope: `settings:write`.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"description":"Turn the phone menu on or off.","type":"boolean"},"prompt_source":{"description":"\"audio\" only works once an audio prompt was uploaded in the app.","type":"string","enum":["text","audio"]},"prompt_text":{"description":"What the menu says, e.g. \"Press 1 for scheduling, press 2 for our assistant.\"","anyOf":[{"type":"string","maxLength":2500},{"type":"null"}]},"options":{"description":"The whole menu, one entry per digit. Replaces the saved list.","maxItems":10,"type":"array","items":{"type":"object","properties":{"digit":{"type":"string","enum":["0","1","2","3","4","5","6","7","8","9"]},"label":{"type":"string","minLength":1,"maxLength":60,"description":"Shown in settings and on the call; callers hear the prompt, not this."},"action":{"type":"string","enum":["ring_all","ring_users","forward","voicemail"]},"forward_to":{"description":"E.164 phone number outside Flyra; required when action is \"forward\".","anyOf":[{"type":"string"},{"type":"null"}]},"user_ids":{"description":"Teammates to ring, by user_id from flyra_get_phone_menu teammates; required when action is \"ring_users\".","maxItems":10,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["digit","label","action"]}},"no_input_action":{"description":"Where a caller who presses no key goes after the menu plays three times: \"ring_all\" (default) or \"voicemail\".","type":"string","enum":["ring_all","voicemail"]},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed this menu, every forward number and every teammate a digit rings."}},"required":["confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_processing_fee_setting":{"post":{"operationId":"flyra_get_processing_fee_setting","summary":"Is the card processing fee passed to customers","tags":["Invoices"],"description":"Reads the \"Charge the client the processing fee\" switch on Settings > Payments. available false means the business is outside bank payments, and the switch then reads as off, as on the pay page.\n\nScope: `invoices:read`.","x-required-scope":"invoices:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_processing_fee_setting":{"post":{"operationId":"flyra_update_processing_fee_setting","summary":"Turn passing the card processing fee to customers on or off","tags":["Invoices"],"description":"The \"Charge the client the processing fee\" switch on Settings > Payments. On: the processing fee of the method the customer pays with is added on top of invoices, deposits and Tap to Pay, so the business gets the full amount. Off: the business absorbs it.\n\nThis changes what customers are billed from now on, so pass confirm: true. Admins and Owners only. Returns the saved setting.\n\nScope: `invoices:write`.","x-required-scope":"invoices:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"pass_processing_fees":{"type":"boolean","description":"true turns the switch on, false turns it off."},"confirm":{"type":"boolean","const":true,"description":"Must be true: this changes what customers are charged."}},"required":["pass_processing_fees","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_plan_processing_fee":{"post":{"operationId":"flyra_set_plan_processing_fee","summary":"Add or remove the card processing fee on existing plans","tags":["Subscriptions"],"description":"Plans only add the card processing fee to their automatic charges when they were created while \"Charge the client the processing fee\" was on. This turns that on (on: true) or off for one plan (subscription_id) or for every active plan (all_active: true). Cancelled plans are never changed.\n\nThe fee shows on the plan's next automatic charge, so tell those customers first. Without confirm: true nothing is written and the answer says how many plans would change; pass confirm: true to save. Refused while the business's switch is off. Admins and Owners only. Nothing is sent to anyone.\n\nScope: `subscriptions:write`.","x-required-scope":"subscriptions:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_id":{"description":"One plan. Give this or all_active, not both.","type":"string"},"all_active":{"description":"Every active plan of the business.","type":"boolean","const":true},"on":{"type":"boolean","description":"true adds the fee to the plan's automatic charges, false removes it."},"confirm":{"description":"true saves. Leave it out first to see how many plans would change.","type":"boolean"}},"required":["on"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_customer_payment_methods":{"post":{"operationId":"flyra_list_customer_payment_methods","summary":"List a customer's saved cards","tags":["Customers"],"description":"Return the Stripe payment methods saved on the customer's Stripe customer record (last 4, brand, exp). Useful before flyra_charge_invoice to confirm there's a card on file. Returns empty if the customer has no Stripe customer id or no saved cards.\n\nScope: `customers:read`.","x-required-scope":"customers:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string"}},"required":["customer_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_remove_customer_payment_method":{"post":{"operationId":"flyra_remove_customer_payment_method","summary":"Remove a customer's saved card","tags":["Customers"],"description":"The \"Remove card\" item on a saved card (the customer page's Payments tab, or a subscription's Payments tab). Detaches the card from the customer on the business's Stripe account, so it can no longer be charged; it cannot be undone (the customer would save the card again through the add-a-card link, flyra_get_payment_method_link).\n\nA plan that bills this card can no longer charge it. Sends the customer nothing. The card must be one of this customer's (payment_method_id from flyra_list_customer_payment_methods). A card Stripe shows as already detached answers card_not_found (it may already have been removed). Needs a signed-in Flyra user who may change customers, on customers they can see; API keys are refused. Pass confirm: true.\n\nScope: `customers:write`. Destructive: it deletes or cancels.","x-required-scope":"customers:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string"},"payment_method_id":{"type":"string","pattern":"^pm_[A-Za-z0-9_]+$","description":"Stripe pm_<id> from flyra_list_customer_payment_methods."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the card is removed from the customer."}},"required":["customer_id","payment_method_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_default_customer_payment_method":{"post":{"operationId":"flyra_set_default_customer_payment_method","summary":"Make a saved card the customer's default","tags":["Customers"],"description":"The \"Set as default\" item on a saved card (the customer page's Payments tab, or a subscription's Payments tab). Makes this card the default payment method on the customer's Stripe record on the business's Stripe account, replacing the current default.\n\nSends the customer nothing. The card must be one of this customer's (payment_method_id from flyra_list_customer_payment_methods). Needs a signed-in Flyra user who may change customers, on customers they can see; API keys are refused. Pass confirm: true.\n\nScope: `customers:write`. Destructive: it deletes or cancels.","x-required-scope":"customers:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string"},"payment_method_id":{"type":"string","pattern":"^pm_[A-Za-z0-9_]+$","description":"Stripe pm_<id> from flyra_list_customer_payment_methods."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the customer's default card changes."}},"required":["customer_id","payment_method_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_attach_saved_card_to_subscription":{"post":{"operationId":"flyra_attach_saved_card_to_subscription","summary":"Put a customer's saved card on a subscription","tags":["Subscriptions"],"description":"Makes a plan charge one of the customer's saved cards, so the plan shows Card on file: Yes and its visits charge that card. Use it when a plan was made for a customer who already has a card (flyra_list_customer_payment_methods). Without payment_method_id the customer's default card is used (or their only card).\n\nThis tool charges nothing itself and sends nothing to the customer; visits the plan charges from then on use this card. A visit already owed when a plan first gets a card is set to collect from the invoice, not charged. A pending plan whose other steps (signature, deposit) are already done can start once it has a card: its visits are booked and each one charges the card. The result gives the plan's status after the attach. Only active, past due and pending plans take a card; a past due plan only when it already has one (this swaps it). Refused, with the reason, when the plan owes a visit that must be settled first, a charge is in flight, the plan is paused, cancelled or ended, it is one schedule of a bundle (the bundle plan takes the card), it is a bundle that would start billing on its first visit's day, or Stripe bills it monthly. A customer with no saved card needs the card link instead (flyra_send_payment_method_link with subscription_id). Calling it again with the same card changes nothing. Admins and Owners only; API keys are refused. Pass confirm: true.\n\nScope: `subscriptions:write`. Destructive: it deletes or cancels.","x-required-scope":"subscriptions:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_id":{"type":"string","description":"Subscription UUID or semantic id (sub_<uuid>)."},"payment_method_id":{"description":"Stripe pm_<id> from flyra_list_customer_payment_methods. Omit to use the customer's default card.","type":"string","pattern":"^pm_[A-Za-z0-9_]+$"},"confirm":{"type":"boolean","const":true,"description":"Must be true: the plan charges this card from now on."}},"required":["subscription_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_charge_invoice":{"post":{"operationId":"flyra_charge_invoice","summary":"Charge a saved card for an invoice","tags":["Invoices"],"description":"Charge the customer's saved card for everything an invoice still owes (off-session), through the same code as the invoice page's \"Charge card on file\" button. If no payment_method_id is supplied, the most recently saved card on the customer's Stripe customer record is used.\n\nReal money moves. What is charged is the balance still owed (the total less deposits and earlier payments); to charge part of it, use flyra_charge_invoice_amount. When the business passes the card processing fee to customers (Settings > Payments), the fee is added on top; the reply says what the card was charged in total. Refused while a bank payment is clearing on the invoice. On 3D Secure nothing is charged and the reply gives the invoice link to send the customer.\n\nWhen the charge pays the invoice, the customer is emailed the business's payment receipt if automatic receipts are on and they have an email address, as with the button. code charge_unconfirmed means Stripe has not confirmed the outcome and the card may already have been charged: check the invoice with flyra_get_invoice before retrying. code already_charged means no new money moved.\n\nNeeds a signed-in Flyra user who can open the invoice; API keys are refused. Use flyra_list_customer_payment_methods first if you need to pick a specific card. Pass confirm: true once the user has agreed the card and the amount.\n\nScope: `invoices:write`. Destructive: it deletes or cancels.","x-required-scope":"invoices:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"invoice_id":{"type":"string"},"payment_method_id":{"description":"Stripe pm_<id>. Omit to use the most recently-saved card.","type":"string"},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user agreed the card and the amount, and that the customer may be emailed a receipt."}},"required":["invoice_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_charge_invoice_amount":{"post":{"operationId":"flyra_charge_invoice_amount","summary":"Charge a saved card for all or part of an invoice's balance","tags":["Invoices"],"description":"The \"Charge card on file\" button on an invoice in Flyra: charges one of the customer's saved cards for the amount you give, the whole balance still owed or less. Real money moves, off-session, on the business's Stripe account.\n\nPick the card with flyra_list_customer_payment_methods; a card that is not this customer's is refused. When the business passes the card processing fee to customers (Settings > Payments), the fee is added on top of the amount, as on the screen; the reply says what the card was charged in total. A partial charge leaves the invoice open with the rest still owed.\n\nWho hears about it, exactly as with the button: when the charge pays the invoice in full, the customer is emailed the business's payment receipt if automatic receipts are on in Settings and they have an email address, the business gets its own invoice-paid notification email, and the invoice's follow-up reminders stop. Automations the business set on a payment received run on every charge; those on an invoice paid run when it is paid in full.\n\nIf the bank asks the customer to authenticate (3D Secure), nothing is charged and the reply gives the invoice link to send them. code charge_unconfirmed means Stripe has not confirmed the outcome and the card may already have been charged: check the invoice with flyra_get_invoice before retrying or trying another card. code already_charged means Stripe returned an earlier charge of the same amount on the same card for this invoice, and no new money moved. Needs a signed-in Flyra user who can open the invoice; API keys are refused. Pass confirm: true once the user has agreed the card, the amount and that the customer may get the receipt.\n\nScope: `invoices:write`. Destructive: it deletes or cancels.","x-required-scope":"invoices:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"invoice_id":{"type":"string","description":"Invoice UUID or semantic id (inv_<uuid>)."},"payment_method_id":{"type":"string","description":"The saved card to charge, pm_<id>, from flyra_list_customer_payment_methods."},"amount_cents":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"What to charge, in cents, before any processing fee: at most the balance still owed."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user agreed the card and the amount, and that the customer may be emailed a receipt."}},"required":["invoice_id","payment_method_id","amount_cents","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_charge_job":{"post":{"operationId":"flyra_charge_job","summary":"Charge a saved card for a job, no invoice needed first","tags":["Invoices"],"description":"The \"Charge card on file\" button on a job's Payments tab in Flyra. If the job has an open invoice, that invoice is charged; if not, a draft invoice is first made from the job's line items, discount and tax, as the job page does (it is not sent). Then one of the customer's saved cards is charged for the amount you give, at most what that invoice still owes. Real money moves, off-session, on the business's Stripe account.\n\nEverything after the invoice is flyra_charge_invoice_amount: pick the card with flyra_list_customer_payment_methods; the processing fee is added on top when the business passes it on; a partial charge leaves the rest owed; on 3D Secure nothing is charged and the reply gives the invoice link; charge_unconfirmed and already_charged mean the same as there (check with flyra_get_invoice before charging again). Plan visits are refused here (their plan bills them); charge a plan visit's invoice with flyra_charge_invoice_amount.\n\nWho hears about it, exactly as with the button: when the charge pays the invoice in full, the job is marked paid, the customer is emailed the business's payment receipt if automatic receipts are on in Settings and they have an email address, the business gets its own invoice-paid notification email, and the invoice's follow-up reminders stop. Automations the business set on a payment received run on every charge; those on an invoice paid run when it is paid in full.\n\nNeeds a signed-in Flyra user who can open the job and take payments on it (job editing, prices not hidden from their role); API keys are refused. Pass confirm: true once the user has agreed the card, the amount and that the customer may get the receipt.\n\nScope: `invoices:write`. Destructive: it deletes or cancels.","x-required-scope":"invoices:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"Job UUID or semantic id (job_<uuid>)."},"payment_method_id":{"type":"string","description":"The saved card to charge, pm_<id>, from flyra_list_customer_payment_methods."},"amount_cents":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"What to charge, in cents, before any processing fee: at most what the job's invoice still owes."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user agreed the card and the amount, and that the customer may be emailed a receipt."}},"required":["job_id","payment_method_id","amount_cents","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_refund_payment":{"post":{"operationId":"flyra_refund_payment","summary":"Refund a Stripe payment","tags":["Invoices"],"description":"Refund a Stripe payment — full or partial. Identify the payment by invoice_id (most common), job_id, or a raw payment_event_id. When given an invoice or job, the one completed payment on it is refunded; if there is more than one refundable payment, nothing is refunded and code ambiguous_payment lists them (payment_event_id, amount, status, date): ask the user which one and call again with its payment_event_id. A payment already partly refunded is only refunded again by its payment_event_id (code partly_refunded).\n\nReal money moves back to the customer. On success the ledger is synced immediately: the payment is marked refunded, the invoice balance and the job's payment_status are recomputed. Omit `amount` for a full refund of the remaining balance; pass `amount` (in dollars) for a partial refund.\n\nOnly Stripe-sourced payments can be refunded. Cash / external payments must be removed via the Flyra UI instead. Needs a signed-in Flyra user who can open the invoice or job the payment is on; API keys are refused. Pass confirm: true once the user has agreed the payment and the amount.\n\nScope: `invoices:write`. Destructive: it deletes or cancels.","x-required-scope":"invoices:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"invoice_id":{"description":"Invoice UUID or semantic id. Refunds the one refundable Stripe payment on it.","type":"string"},"job_id":{"description":"Job UUID or semantic id. Refunds the one refundable Stripe payment on it.","type":"string"},"payment_event_id":{"description":"Raw payment_events UUID, if you already have it (or from an ambiguous_payment reply).","type":"string"},"amount":{"description":"Partial refund amount in dollars. Omit for a full refund of the remaining balance.","type":"number","exclusiveMinimum":0},"reason":{"description":"Defaults to requested_by_customer.","type":"string","enum":["requested_by_customer","duplicate","fraudulent","other"]},"reason_text":{"description":"Free-text note stored on the refund audit log.","type":"string"},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user agreed which payment is refunded and how much."}},"required":["confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_payment_method_link":{"post":{"operationId":"flyra_get_payment_method_link","summary":"Get a customer's \"add a card on file\" link","tags":["Customers"],"description":"Return the secure URL where this customer saves a card on file, WITHOUT sending it. Use it to write your own message (then flyra_send_sms / flyra_send_email) or to hand the link over in person.\n\nFor the ready-made text/email the app's \"Add Payment Method\" button sends, use flyra_send_payment_method_link instead.\n\nPass subscription_id to get the plan-anchored link flyra_send_payment_method_link sends with subscription_id: the card the customer saves there goes on that plan. The plan must be this customer's and not cancelled.\n\nThe link works for 90 days. Without subscription_id, resolving it creates or reuses the customer's Stripe customer record, which is why this is not read-only.\n\nScope: `customers:write`.","x-required-scope":"customers:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string","description":"Customer UUID or semantic id (cust_<uuid>)."},"subscription_id":{"description":"Subscription UUID or semantic id (sub_<uuid>). Anchors the link to this plan; it must belong to the customer.","type":"string"}},"required":["customer_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_send_payment_method_link":{"post":{"operationId":"flyra_send_payment_method_link","summary":"Send a customer the \"add a card on file\" link","tags":["Customers"],"description":"Text and/or email a customer the secure link where they save a card on file. This is the same \"Add Payment Method\" button as the Flyra app, with the same message.\n\nPass subscription_id for a service-plan customer who has no card: the link is then anchored to that plan, so the card they save attaches to the plan and its visits charge it. Without subscription_id the link is customer-level: the card goes to the customer, and from there to their plans that have no card yet.\n\nDelivery: send_sms and/or send_email. When both are omitted the customer is texted if they have a mobile number, otherwise emailed. The body is the org's \"Add payment method\" template (Settings → Automations) unless `message` is given; the link is appended whenever the text has none.\n\nIf the org runs Add Payment Method as a workflow, that workflow delivers it and the result says handled_by_workflow: true — do not send again. Check flyra_list_customer_payment_methods first: a customer who already has a card does not need this.\n\nThe customer must be one the caller can see. It messages the customer, so confirm with the user first and pass confirm: true; every call sends again.\n\nScope: `customers:write`.","x-required-scope":"customers:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string","description":"Customer UUID or semantic id (cust_<uuid>)."},"subscription_id":{"description":"Subscription UUID or semantic id (sub_<uuid>). Anchors the link to this plan; it must belong to the customer.","type":"string"},"send_sms":{"description":"Text the link. Default: true when the customer has a mobile number.","type":"boolean"},"send_email":{"description":"Email the link. Default: true only when the customer has no mobile number.","type":"boolean"},"message":{"description":"Custom body. {customer_name}, {company_name}, {subscription_name} and {payment_method_link} are filled in. Omit to use the org template.","type":"string","maxLength":1600},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has said to send the customer this link now."}},"required":["customer_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_send_payment_receipt":{"post":{"operationId":"flyra_send_payment_receipt","summary":"Send a payment receipt to the customer","tags":["Invoices"],"description":"The Send receipt action on one payment in a job's Payments tab. EMAILS and/or TEXTS that payment's receipt to the job's customer, at the email and mobile number on their customer record, as the screen fills in. It messages the customer, so confirm first and call it once: every call sends again (a text resent in the same minute goes once), even when a receipt already went out and even when the business's automatic receipts are off, as the button does.\n\npayment_id is the payment_record_id that flyra_record_job_payment or flyra_mark_invoice_paid returns. send_email / send_sms default to on when the customer has that address. The email carries the receipt PDF; the text always carries the receipt link. message replaces the screen's starting text (the business's receipt message; same {variables}); omit it to send that text.\n\nRefused for a refunded payment, a payment not on a job, or a job with no customer. Needs a signed-in Flyra user; an organization API key is refused.\n\nScope: `invoices:write`.","x-required-scope":"invoices:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"payment_id":{"type":"string","description":"The payment's id (payment_record_id)."},"send_email":{"description":"Email the receipt. Default: on when the customer has an email address.","type":"boolean"},"send_sms":{"description":"Text the receipt. Default: on when the customer has a mobile number.","type":"boolean"},"message":{"description":"Replaces the text the screen starts with (the business's receipt message). Omit to send that text.","type":"string","maxLength":1600},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed the customer gets this receipt now."}},"required":["payment_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_record_job_payment":{"post":{"operationId":"flyra_record_job_payment","summary":"Record a payment on a job","tags":["Invoices"],"description":"The Record payment form on a job's Payments tab: books a payment taken outside Flyra (cash, check, any method on the business's list) on the job, no invoice needed. It never charges a card or sends a payment link. The payment goes onto the job's open invoice if it has one; the job's payment status follows. Refused while a bank payment on the job is clearing.\n\nIt can message the customer, so confirm first: (1) a receipt. send_receipt_email / send_receipt_sms are the form's boxes: true sends it, false stops that channel's automatic receipt, omitted leaves it to the business's Receipt Message automation (as the form's default boxes); true needs that address on file; (2) a review request, when the review automation asks on payment and this pays the job in full; (3) any automation it runs on a received payment.\n\nReuse a request_id on a retry: booked once (deduped: true). The reply's payment_record_id is what flyra_send_payment_receipt takes. Needs a signed-in Flyra user who can open the job; API keys are refused.\n\nScope: `invoices:write`.","x-required-scope":"invoices:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"Job UUID or semantic id (job_<uuid>)."},"amount_cents":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"What was paid, in cents."},"payment_method":{"type":"string","description":"One of the business's active payment method codes, as the form's Method list offers them (flyra_list_payment_methods, field code)."},"payment_date":{"description":"When it was paid, ISO 8601. Defaults to now.","type":"string"},"send_receipt_email":{"description":"The form's email receipt box. Omit to leave it to the business's receipt automation.","type":"boolean"},"send_receipt_sms":{"description":"The form's text receipt box. Omit to leave it to the business's receipt automation.","type":"boolean"},"request_id":{"description":"Optional idempotency key (a UUID you generate). Reused with a different amount, method, date or receipt choice it is refused. Without one, the same amount and method on this job within 60 seconds answers with the first payment.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed this payment, and that the customer may get a receipt or review request from it."}},"required":["job_id","amount_cents","payment_method","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_add_job_tip":{"post":{"operationId":"flyra_add_job_tip","summary":"Add a tip to a job","tags":["Invoices"],"description":"The Add tip form on a job's Payments tab: records a tip the customer gave outside Flyra (cash, check), for one employee, unassigned, or split equally across the job's dispatched crew. It moves no money and charges nothing; it records the tip, which counts toward that employee's pay. It sends no message.\n\npayment_id is Add tip on that payment's row (payment_record_id from flyra_record_job_payment or flyra_list_payments): the tip goes with that payment. Without it the tip goes with the job's payment made on tip_date, else the latest one before it, else the latest one, as Add tip in the Payments menu does; card payments are skipped, so a job paid only by card gets the tip with no payment. A tip that goes with a payment comes off what counts toward the bill, so the job's open invoice is recomputed afterwards (a paid invoice stays paid).\n\nEach call adds a tip, so do not repeat one that succeeded. Needs a signed-in Flyra user who can open the job and take payments on it (job editing, prices not hidden from their role); API keys are refused. Confirm the amount and who gets it with the user first.\n\nScope: `invoices:write`. Destructive: it deletes or cancels.","x-required-scope":"invoices:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"Job UUID or semantic id (job_<uuid>)."},"amount_cents":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The tip, in cents."},"tip_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The day of the tip, YYYY-MM-DD (the form's Date)."},"payment_id":{"description":"The payment the tip came with (payment_record_id), from this job.","type":"string"},"employee_id":{"description":"The employee the tip is for (flyra_list_employees). Omit for unassigned.","type":"string"},"split_equally":{"description":"true splits the tip equally across the job's dispatched employees (2 or more), as the form's Split equally box. Leave employee_id out when true.","type":"boolean"},"notes":{"description":"The form's Notes.","type":"string","maxLength":2000},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed the tip amount and who it is for."}},"required":["job_id","amount_cents","tip_date","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_payment":{"post":{"operationId":"flyra_update_payment","summary":"Edit a recorded payment","tags":["Invoices"],"description":"The Edit payment button on Reports > Payments (and Edit on a job's Payments tab): changes the amount, method or date of a payment someone typed in by hand (cash, check, Zelle, any method on the business's list). It moves no money. Only what you pass changes.\n\nOn a job's payment Flyra re-splits the tax on the new amount. A move from card to a non-card method takes any card-only fee off the invoice and the job. What the invoice and the job show as paid is recomputed; the reply reads them back. It sends no message itself, but if the change pays the invoice in full the invoice turns paid, and any automation the business set on an invoice being paid runs.\n\nRefused for a payment taken through Stripe (use flyra_refund_payment) or one from a subscription billing period. payment_id is the payment_record_id from flyra_list_payments, flyra_record_job_payment or flyra_mark_invoice_paid. Admins only, signed in as a person (an organization API key is refused). Confirm the change with the user first.\n\nScope: `invoices:write`. Destructive: it deletes or cancels.","x-required-scope":"invoices:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"payment_id":{"type":"string","description":"The payment's id (payment_record_id)."},"amount_cents":{"description":"The corrected amount, in cents.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"payment_method":{"description":"The corrected method: one of the business's payment method codes (flyra_list_payment_methods, field code).","type":"string"},"payment_date":{"description":"The corrected date it was paid, ISO 8601.","type":"string"},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed this change to the payment."}},"required":["payment_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_delete_payment":{"post":{"operationId":"flyra_delete_payment","summary":"Delete a recorded payment","tags":["Invoices"],"description":"The Delete payment button on Reports > Payments (and on a job's Payments tab): permanently removes a payment someone typed in by hand (cash, check, Zelle, any method on the business's list), with the photos attached to it. There is no undo. It moves no money and refunds nothing; it corrects the books.\n\nThe invoice and the job then show what is left as paid, so a paid invoice can go back to sent (unpaid); the reply gives what they hold after the delete. It sends no message itself.\n\nRefused for a payment taken through Stripe (use flyra_refund_payment) or one from a subscription billing period. payment_id is the payment_record_id from flyra_list_payments, flyra_record_job_payment or flyra_mark_invoice_paid. Admins only, signed in as a person (an organization API key is refused). Confirm with the user first.\n\nScope: `invoices:write`. Destructive: it deletes or cancels.","x-required-scope":"invoices:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"payment_id":{"type":"string","description":"The payment's id (payment_record_id)."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed this payment is deleted."}},"required":["payment_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_payouts":{"post":{"operationId":"flyra_get_payouts","summary":"Get the Stripe balance and payouts","tags":["Invoices"],"description":"Settings > Payments > Payouts, Admins and Owners only, read only: the business's Stripe balance and its last 20 payouts to the bank, read live from Stripe the way that screen reads them (GET /api/stripe/connect/payouts).\nbalance.available_cents is settled money waiting for the next payout; balance.pending_cents is recent payments still settling. on_the_way_cents is payouts that left Stripe and have not reached the bank yet (pending or in_transit); next_payout is the soonest of those. payout_schedule is the account's schedule (e.g. daily, delay_days 2); no date is predicted from it. Each payout has amount_cents, status (pending, in_transit, paid, failed, canceled), method (standard or instant), arrival_date and created (unix seconds; arrival is an estimate until paid), bank_name and last4. All amounts are in cents.\npayouts_enabled=false with zeros means Stripe setup is not finished or the account is no longer reachable. It never sends a payout; instant payouts are only in the app. Needs a signed-in user; an organization API key is refused.\n\nScope: `invoices:read`.","x-required-scope":"invoices:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_payments":{"post":{"operationId":"flyra_list_payments","summary":"List payments","tags":["Invoices"],"description":"List the payments taken in a time window, newest first: the same payments as Reports > Payments (completed, refunded and partly refunded), by when the payment happened.\n\nEach row has the method (the business's own method names), amount, tip and any refunded amount in dollars, the job, invoice and customer, when it was recorded, and who recorded it. `amount` is the total paid with the tip already in it; what was kept is amount minus refunded. `recorded_by_name` is the person signed in when the payment was recorded, and is empty when no person is on file: card payments, subscription charges and other automatic payments. `payment_record_id` is the record behind the payment, when there is one: a payment typed in by hand has one, and so can a card payment. flyra_update_payment and flyra_delete_payment take it, and refuse a card (Stripe) or subscription payment.\n\nFilters, as on Reports > Payments: payment_methods, payment_type (plan or one-time), status (completed or refunded), lead_sources and team_members.\n\nUse it to total cash per technician: filter rows by method_code (stays \"cash\" if the business renames Cash), then group by recorded_by_user_id (it stays the same if the person is removed or re-invited; recorded_by_employee_id can change). A payment marked paid from an invoice's \"Mark as paid\" comes through as method \"other\". Re-pull the whole window and recompute rather than only adding new rows: a payment can be dated in the past, and a deleted or voided one drops out. Page with offset until next_offset is null, sending back the \"to\" the first page returned so the window holds still; still de-duplicate on payment_event_id. One call covers at most 366 days.\n\nScope: `invoices:read`.","x-required-scope":"invoices:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"Start of the window, inclusive: when the payment happened. ISO 8601 with Z or an offset, e.g. 2026-10-23T04:00:00Z."},"to":{"description":"End of the window, inclusive. ISO 8601 with Z or an offset. Defaults to now.","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"limit":{"description":"Rows per page, up to 50. Defaults to 50.","type":"integer","exclusiveMinimum":0,"maximum":50},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991},"payment_methods":{"description":"Only these methods, as Reports > Payments filters them: method_code as each row returns it (e.g. cash, check); a payment with no method_code is card, or manual when entered by hand.","maxItems":50,"type":"array","items":{"type":"string","minLength":1}},"payment_type":{"description":"Only plan payments (the job behind it belongs to a plan, or a plan's card charge) or only one-time ones, as the report's type filter.","type":"string","enum":["subscription","oneTime"]},"status":{"description":"Only completed payments, or only refunded and partly refunded ones (refund rows included), as the report's status filter.","type":"string","enum":["completed","refunded"]},"lead_sources":{"description":"Only payments whose job came from one of these lead sources (any case). A payment with no job behind it is left out.","maxItems":50,"type":"array","items":{"type":"string","minLength":1}},"team_members":{"description":"Employee ids from flyra_list_employees, as the report's team member filter: only payments on a job or invoice one of them created or is the salesperson on (else on a customer of those jobs and invoices). Only people with a Flyra login count, as on the report.","maxItems":50,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["from"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_preview_sms_blast":{"post":{"operationId":"flyra_preview_sms_blast","summary":"Preview who an SMS blast would text","tags":["Texting"],"description":"Read-only: who flyra_send_sms_blast would text for this audience and body, and what it costs, without sending or charging anything. Pass the same audience (ONE of `customer_ids`, `to_phones`, or a map area `territory_id` / `polygon`) and the same body you will send; with_picture: true if the blast carries a picture; exclude_key to leave out everyone an earlier blast reached.\n\nReturns expected_count (people texted), credits_needed and credit_balance, sample_names, example_text (the first text as it will read), skipped (landlines, missing numbers, texts too long once a name is filled in) and expected_fingerprint. Show the user the count, credits and words, then pass expected_count and expected_fingerprint to flyra_send_sms_blast. A map area is for an Admin or Owner.\n\nScope: `sms:read`.","x-required-scope":"sms:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_ids":{"description":"Customer ids; each one’s mobile_phone is texted.","maxItems":1000,"type":"array","items":{"type":"string"}},"to_phones":{"maxItems":1000,"type":"array","items":{"type":"string"}},"territory_id":{"description":"A saved map territory (flyra_list_territories): the customers and map pins inside it, as the in-app SMS Blast picks them, minus opted-out numbers, landlines and anyone the signed-in person cannot see. A pin with no customer fills {customer_name} with the name on the pin, or \"Customer\". Not with customer_ids, to_phones or polygon.","type":"string"},"polygon":{"description":"A map area drawn as [longitude, latitude] points (latitude -90 to 90), picked like territory_id. Not with customer_ids, to_phones or territory_id.","minItems":3,"maxItems":1000,"type":"array","items":{"minItems":2,"maxItems":2,"type":"array","items":{"type":"number","minimum":-180,"maximum":180}}},"body":{"type":"string","minLength":1,"maxLength":1600},"exclude_key":{"description":"An earlier blast’s idempotency_key: everyone it already queued is left out. Pass the same value to the preview and the send.","type":"string","minLength":8,"maxLength":128},"with_picture":{"description":"True if the blast will carry a picture: 3 credits per person more.","type":"boolean"}},"required":["body"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_send_sms_blast":{"post":{"operationId":"flyra_send_sms_blast","summary":"Send the same SMS to a list of recipients","tags":["Texting"],"description":"Texts many real people, no undo: first tell the user how many get it and the exact words, and wait for a clear yes. Get them from flyra_preview_sms_blast (same audience, body); pass its expected_count and expected_fingerprint with confirm: true; a changed list sends nothing (count_changed). ONE audience: customer_ids, to_phones (E.164), territory_id or polygon. No emoji.\n\nFills per person: {first_name}, {customer_name}, {customer_full_name}, {street_name}, {company_name}, {company_phone}, {company_email}, {company_website}, {review_link} (customer ones empty for to_phones); others removed.\n\nPriced like flyra_send_sms: free for people the business is already working with, 25 cold numbers free per 30 days, then 1 SMS blast credit per cold number. A picture adds 3 credits per person, warm ones too. If short, none sent; approval_url returns. Unsent refunded. Max 1000 people per call and per 5 min.\n\nReturns statuses and batch_id. Same idempotency_key on a retry: nobody is texted twice.\n\nScope: `sms:send`.","x-required-scope":"sms:send","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_ids":{"description":"Customer ids; each one’s mobile_phone is texted.","maxItems":1000,"type":"array","items":{"type":"string"}},"to_phones":{"maxItems":1000,"type":"array","items":{"type":"string"}},"territory_id":{"description":"A saved map territory (flyra_list_territories): the customers and map pins inside it, as the in-app SMS Blast picks them, minus opted-out numbers, landlines and anyone the signed-in person cannot see. A pin with no customer fills {customer_name} with the name on the pin, or \"Customer\". Not with customer_ids, to_phones or polygon.","type":"string"},"polygon":{"description":"A map area drawn as [longitude, latitude] points (latitude -90 to 90), picked like territory_id. Not with customer_ids, to_phones or territory_id.","minItems":3,"maxItems":1000,"type":"array","items":{"minItems":2,"maxItems":2,"type":"array","items":{"type":"number","minimum":-180,"maximum":180}}},"body":{"type":"string","minLength":1,"maxLength":1600},"exclude_key":{"description":"An earlier blast’s idempotency_key: everyone it already queued is left out. Pass the same value to the preview and the send.","type":"string","minLength":8,"maxLength":128},"image_url":{"description":"One picture on every text, as Add picture on the SMS Blast page: a public https link to a JPG or PNG under 5 MB. Pass this or image_base64.","type":"string"},"image_base64":{"description":"The picture itself as base64 (JPG or PNG under 5 MB). Pass this or image_url.","type":"string"},"follow_ups":{"description":"Up to 4, delay_days 1 to 14: texted later, in business hours, to the people this blast reached who have not replied, like the in-app follow up. Each spends SMS blast credits only, at the in-app blast price (1 credit per text part per person, warm or cold), and never charges a card: if the balance is short when it is due, it is not sent and the admins get an email. See flyra_list_sms_blast_followups; call one off with flyra_cancel_sms_blast_followup.","maxItems":4,"type":"array","items":{"type":"object","properties":{"body":{"type":"string"},"delay_days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["body","delay_days"]}},"expected_count":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"expected_count from flyra_preview_sms_blast: how many people the user agreed to text."},"expected_fingerprint":{"type":"string","minLength":1,"maxLength":64,"description":"expected_fingerprint from flyra_preview_sms_blast: which numbers the user agreed to text."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user said yes to this count and these words."},"idempotency_key":{"type":"string","minLength":8,"maxLength":128,"description":"A new random key per blast (8 to 128 characters). Send the same key again on a retry of this blast: anyone it already reached is not texted or charged again."}},"required":["body","expected_count","expected_fingerprint","confirm","idempotency_key"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_sms_blast_settings":{"post":{"operationId":"flyra_get_sms_blast_settings","summary":"Get the SMS blast spending settings","tags":["Texting"],"description":"Returns the SMS blast spending settings: whether auto-recharge is on (Flyra buys more blast credits off session with the card on file when they run out), when the owner opted in, the monthly spending limit and the most it can be raised to without asking, the credit balance, what has been charged this month, and which card is charged. canEdit says whether this connection could change them. To switch auto-recharge off, use flyra_set_sms_blast_autorecharge; to turn it on, flyra_turn_on_sms_blast_autorecharge.\n\nScope: `sms:read`.","x-required-scope":"sms:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_sms_blast_autorecharge":{"post":{"operationId":"flyra_set_sms_blast_autorecharge","summary":"Turn SMS blast auto-recharge off","tags":["Texting"],"description":"Switch off SMS blast auto-recharge, so Flyra stops buying blast credits with the card on file when they run out. Pass enabled:false. To turn it back on, use flyra_turn_on_sms_blast_autorecharge, which needs the owner's yes to the card charges; the monthly spending limit is set in Flyra's SMS blast settings. Needs a signed-in Admin; an organization API key cannot change it. Returns the settings as saved.\n\nScope: `sms:send`.","x-required-scope":"sms:send","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"false to switch auto-recharge off. true is refused here: use flyra_turn_on_sms_blast_autorecharge."}},"required":["enabled"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_turn_on_sms_blast_autorecharge":{"post":{"operationId":"flyra_turn_on_sms_blast_autorecharge","summary":"Turn SMS blast auto-recharge on","tags":["Texting"],"description":"Turn SMS blast auto-recharge on, as \"Turn on and continue\" under \"Buy messages automatically when you run out?\" on Flyra's SMS blast send screen does. MONEY: from then on, when an SMS blast sent in Flyra, or a follow up scheduled there, needs more messages than the business has paid for, Flyra charges the Flyra billing card on file $0.02 for every 160 characters each person is sent, with a smallest charge of $5.00, at the moment it goes out. Anything left over stays on the account. Nothing is charged at any other time, the monthly spending limit still applies (flyra_get_sms_blast_settings shows it), and flyra_set_sms_blast_autorecharge turns it off again. Texts and blasts sent through this connection never buy credits this way. Turning it on is the owner's agreement to these card charges, and Flyra records when it was first given: read the terms above to the user and get their yes first. Refused when there is no card on file. Admins only; needs a signed-in person, not an organization API key. Returns the settings as saved.\n\nScope: `sms:send`. Destructive: it deletes or cancels.","x-required-scope":"sms:send","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has agreed to Flyra charging the card on file as described."}},"required":["confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_approve_sms_credit_purchase":{"post":{"operationId":"flyra_approve_sms_credit_purchase","summary":"Approve buying SMS credits","tags":["Texting"],"description":"Approve buying the SMS credits Flyra asked for when a text or blast from this connection was short of credits, as the Approve button on the approval link (approval_url, /sms-credits/approve/<id>) does. MONEY: charges the Flyra billing card on file the exact amount on the approval and adds the credits to the business ($0.02 a credit, 250 credits for $5.00 at least). The monthly blast spending limit and the daily charge limit apply. Approving twice does not charge twice. The approval expires 24 hours after it was made. Pass approval_id (the id at the end of approval_url) and charge_cents exactly as the refusal gave them (approval_charge_cents); any other amount is refused with the real one and nothing is charged. Tell the user the amount and get their yes first, then send the text again. Admins only; needs a signed-in person, not an organization API key. Returns the approval as saved (status approved).\n\nScope: `sms:send`. Destructive: it deletes or cancels.","x-required-scope":"sms:send","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"approval_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The approval id: the last part of approval_url."},"charge_cents":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The amount the approval is for, in cents (approval_charge_cents). Must match."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has agreed to this charge to the card on file."}},"required":["approval_id","charge_cents","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_sms_blasts":{"post":{"operationId":"flyra_list_sms_blasts","summary":"List recent SMS blasts","tags":["Texting"],"description":"The SMS blasts of the last 30 days that reached someone, newest first (up to 20), from the app and from flyra_send_sms_blast: each one’s message, how many it went to and when.\n\nScope: `sms:read`.","x-required-scope":"sms:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_sms_blast_followups":{"post":{"operationId":"flyra_list_sms_blast_followups","summary":"List SMS blast follow ups","tags":["Texting"],"description":"The SMS blast follow ups of the last 30 days, coming and gone (up to 50): status (scheduled, sending, sent, skipped, refused, cancelled, awaiting_payment), when it goes or went, its text, the blast it follows, and for one that did not go, why. Call one off with flyra_cancel_sms_blast_followup while it is scheduled.\n\nScope: `sms:read`.","x-required-scope":"sms:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_cancel_sms_blast_followup":{"post":{"operationId":"flyra_cancel_sms_blast_followup","summary":"Call off an SMS blast follow up","tags":["Texting"],"description":"Cancel an SMS blast follow up that has not gone out yet, so it is never sent. It cannot be turned back on. One that is already sending or sent cannot be called off, and the error says so. Ids come from flyra_list_sms_blast_followups or flyra_send_sms_blast.\n\nScope: `sms:send`. Destructive: it deletes or cancels.","x-required-scope":"sms:send","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"followup_id":{"type":"string","description":"Follow up id from flyra_list_sms_blast_followups."}},"required":["followup_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_team_conversations":{"post":{"operationId":"flyra_list_team_conversations","summary":"List my team chat conversations","tags":["Employees"],"description":"The Team Chat conversations the signed-in person is part of (the Team Chat page and the Team tab in Inbox), most recent first: each one’s name, who is in it, its last message and how many messages are unread. Team chat is between employees only, never customers. Read one with flyra_get_team_messages, reply with flyra_send_team_message. Pass next_cursor back as cursor for older conversations. Needs a signed-in person; an organization API key cannot read team chat.\n\nScope: `employees:read`.","x-required-scope":"employees:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"description":"Conversations per page, default 20.","type":"integer","minimum":1,"maximum":50},"cursor":{"description":"next_cursor from the previous call.","type":"string"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_team_messages":{"post":{"operationId":"flyra_get_team_messages","summary":"Read a team chat conversation","tags":["Employees"],"description":"Messages in one Team Chat conversation the signed-in person is part of, oldest to newest within the page, newest page first. Pass next_cursor back as cursor for older messages. Messages from anyone the person blocked are left out, as in the app. Only conversations the person is already in can be read; find them with flyra_list_team_conversations. Needs a signed-in person; an organization API key cannot read team chat.\n\nScope: `employees:read`.","x-required-scope":"employees:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"conversation_id":{"type":"string","description":"Conversation id from flyra_list_team_conversations."},"limit":{"description":"Messages per page, default 50.","type":"integer","minimum":1,"maximum":100},"cursor":{"description":"next_cursor from the previous call.","type":"string"}},"required":["conversation_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_send_team_message":{"post":{"operationId":"flyra_send_team_message","summary":"Send a team chat message","tags":["Employees"],"description":"Send a message as the signed-in person in a Team Chat conversation they are part of (the Team Chat page and the Team tab in Inbox). Team chat is between employees only, never customers. One picture can go with it: image_url (a public https link that does not redirect) or image_base64. JPG, PNG, WebP, GIF or HEIC (saved as JPG), up to 10 MB, stored like a Team Chat picture, behind a public link anyone holding it can open; body is then optional. Find a conversation with flyra_list_team_conversations, or start one with flyra_create_team_conversation. reply_to_message_id quotes a message from the same conversation. It pushes a notification to the phone of every other person in the conversation (except anyone who blocked the sender) and sends no SMS or email. Up to 10 per minute. Needs a signed-in person; an organization API key cannot send team messages. Through the connector, sending needs a role with Manage Team (Owner, Admin, or a role given it); anyone else sends from the Team Chat page.\n\nScope: `employees:write`.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"conversation_id":{"type":"string","description":"Conversation id from flyra_list_team_conversations."},"body":{"description":"The message text. Needed unless a picture is sent.","type":"string"},"image_url":{"description":"Public https link to a picture to send. Pass this or image_base64, not both.","type":"string"},"image_base64":{"description":"A picture's bytes, base64 encoded. Pass this or image_url, not both.","type":"string","maxLength":14000000},"reply_to_message_id":{"description":"A message id from flyra_get_team_messages in the same conversation.","type":"string"}},"required":["conversation_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_create_team_conversation":{"post":{"operationId":"flyra_create_team_conversation","summary":"Start a team chat conversation","tags":["Employees"],"description":"Start a new Team Chat conversation as the signed-in person, as Team Chat > New does: pick one or more teammates by employee id from flyra_list_employees. One teammate makes a 1:1 chat named for them; two or more make a group chat, which needs a name. You are always added. Only active employees of this company with a Flyra login can be added, never customers. It always starts a new chat, even if one with the same people exists; post in it with flyra_send_team_message. Creating the chat sends nothing: no push, SMS or email. Up to 10 new chats per minute. Needs a signed-in person; an organization API key cannot use team chat. Through the connector, this needs a role with Manage Team (Owner, Admin, or a role given it); anyone else starts chats from the Team Chat page.\n\nScope: `employees:write`.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"member_employee_ids":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Employee ids from flyra_list_employees: the teammates to add (not yourself). One makes a 1:1 chat, more make a group."},"name":{"description":"The group chat name. Required for a group; a 1:1 chat is named for the other person.","type":"string","minLength":1,"maxLength":120},"confirm":{"type":"boolean","const":true,"description":"Must be true: creates the chat."}},"required":["member_employee_ids","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_tasks":{"post":{"operationId":"flyra_list_tasks","summary":"List tasks","tags":["Tasks"],"description":"List tasks. Filter by status (pending/completed), is_team (true for org-wide tasks, false for personal), and a date range on due_date. Each task includes its notes, start_date, created_at and assignee_user_id (the user who owns it, null for none). flyra_get_task reads one task with the names of its assignee and of who assigned it. To add to the notes without erasing them, use flyra_update_task with append_notes.\n\nScope: `tasks:read`.","x-required-scope":"tasks:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["pending","completed"]},"is_team":{"type":"boolean"},"due_after":{"type":"string"},"due_before":{"type":"string"},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":50},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_task":{"post":{"operationId":"flyra_get_task","summary":"Get a task","tags":["Tasks"],"description":"Read one task by id (from flyra_list_tasks): title, status, notes, dates, team or personal, linked customer, who it is assigned to (assignee_user_id, assignee_employee_id, assignee_name) and who assigned it and when (assigned_by_user_id, assigned_by_name, assigned_at). Flyra does not record who created a task; assigned_by is the person who last gave it to its assignee, null when nobody did. assignee_name, assignee_employee_id and assigned_by_name are null when that login has no current employee record; assignee_user_id still shows it is assigned. You can read tasks you can see: an admin any task, anyone else their own and team tasks.\n\nScope: `tasks:read`.","x-required-scope":"tasks:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"task_id":{"type":"string","description":"The task id, from flyra_list_tasks."}},"required":["task_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_create_task":{"post":{"operationId":"flyra_create_task","summary":"Create a task","tags":["Tasks"],"description":"Add a task / reminder, as on Dashboard > Tasks. due_date is optional. The task is owned by the person connected to Flyra unless assignee_employee_id names someone else, which only Admins, people who can manage the team, and Owner or Manager employees may do (as in the app). pass is_team=true to make it visible to the whole team as well (default false, visible only to its owner). customer_id links it to a customer you can open. repeat makes a run of tasks, one per occurrence, like \"Make this a recurring task\" in the task form. Creating a task runs the company's Task Created automations, as in the app.\n\nScope: `tasks:write`.","x-required-scope":"tasks:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":280},"notes":{"type":"string"},"due_date":{"description":"ISO timestamp or date.","type":"string"},"start_date":{"type":"string"},"is_team":{"type":"boolean"},"assignee_employee_id":{"description":"Give it to this employee (emp_… or uuid, from flyra_list_employees). Omit for yourself.","type":"string"},"customer_id":{"description":"The customer it is for.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"repeat":{"description":"Repeat: one task per occurrence, each its own task.","type":"object","properties":{"every":{"type":"string","enum":["1","2","3","4","6","12","daily","weekly","biweekly"],"description":"How often, one of the task form's choices: daily (Every day), weekly (Every week), biweekly (Every 2 weeks), 1 (Every month), 2 (Every 2 months), 3 (Every 3 months), 4 (Every 4 months), 6 (Every 6 months), 12 (Every year)."},"duration_years":{"description":"For how many years (1-10). Defaults to 1.","type":"integer","minimum":1,"maximum":10},"never_ends":{"description":"true: no end date, the form's Never.","type":"boolean"}},"required":["every"]}},"required":["title"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_task_status":{"post":{"operationId":"flyra_update_task_status","summary":"Update a task's status","tags":["Tasks"],"description":"Move a task to a different status. Tasks are either pending or completed — there is no in-progress or cancelled state. Completing one runs the company's Task Completed automations, as in the app. You can change tasks you can see: an admin any task, anyone else their own and team tasks.\n\nScope: `tasks:write`.","x-required-scope":"tasks:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"task_id":{"type":"string"},"status":{"type":"string","enum":["pending","completed"]}},"required":["task_id","status"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_task":{"post":{"operationId":"flyra_update_task","summary":"Edit a task","tags":["Tasks"],"description":"Edit a task as on Dashboard > Tasks: title, notes, start and due dates, team or personal, assignee, linked customer, status. Only the fields given change; null clears notes, a date or the customer. append_notes adds text to the end of the current notes (a blank line between) instead of replacing them; send notes or append_notes, not both. Giving it to someone else is only for Admins, people who can manage the team, and Owner or Manager employees (as in the app). You can edit tasks you can see: an admin any task, anyone else their own and team tasks. Completing one runs the company's Task Completed automations, as in the app. A task in a repeat run is edited on its own.\n\nScope: `tasks:write`.","x-required-scope":"tasks:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"task_id":{"type":"string","description":"The task id, from flyra_list_tasks."},"title":{"type":"string","minLength":1,"maxLength":280},"notes":{"description":"Replaces the notes; null clears them.","anyOf":[{"type":"string"},{"type":"null"}]},"append_notes":{"description":"Text added to the end of the current notes, keeping what is there.","type":"string","minLength":1},"start_date":{"anyOf":[{"type":"string"},{"type":"null"}]},"due_date":{"anyOf":[{"type":"string"},{"type":"null"}]},"is_team":{"type":"boolean"},"assignee_employee_id":{"description":"Give it to this employee (emp_… or uuid, from flyra_list_employees).","type":"string"},"customer_id":{"description":"The customer it is for; null removes the link.","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"status":{"type":"string","enum":["pending","completed"]}},"required":["task_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_delete_task":{"post":{"operationId":"flyra_delete_task","summary":"Delete a task","tags":["Tasks"],"description":"Delete a task for good, as on Dashboard > Tasks. A task in a repeat run is deleted on its own; the rest of the run stays. You can delete tasks you can see: an admin any task, anyone else their own and team tasks. There is no undo: confirm with the user first.\n\nScope: `tasks:write`. Destructive: it deletes or cancels.","x-required-scope":"tasks:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"task_id":{"type":"string","description":"The task id, from flyra_list_tasks."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed this task should be deleted."}},"required":["task_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_agreement_templates":{"post":{"operationId":"flyra_list_agreement_templates","summary":"List agreement templates","tags":["Agreements"],"description":"List service-agreement templates the org has defined. Read only. A business's terms and conditions usually live elsewhere, so an empty list does not mean terms cannot be changed: company-wide terms on estimates (one-off jobs and installs) are flyra_update_org_settings estimate_default_terms; subscription agreement defaults are flyra_set_agreement_defaults; one plan's terms are flyra_update_subscription_template.\n\nScope: `agreements:read`.","x-required-scope":"agreements:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"integer","exclusiveMinimum":0,"maximum":50},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_agreement_template":{"post":{"operationId":"flyra_get_agreement_template","summary":"Get an agreement template","tags":["Agreements"],"description":"Return the full template including body_html so the agent can preview the contract before composing an email. Read only. A business's terms and conditions usually live elsewhere, so an empty list does not mean terms cannot be changed: company-wide terms on estimates (one-off jobs and installs) are flyra_update_org_settings estimate_default_terms; subscription agreement defaults are flyra_set_agreement_defaults; one plan's terms are flyra_update_subscription_template.\n\nScope: `agreements:read`.","x-required-scope":"agreements:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"template_id":{"type":"string"}},"required":["template_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_contract_library":{"post":{"operationId":"flyra_get_contract_library","summary":"Get the contract library layout","tags":["Agreements"],"description":"The contract library on Settings > Subscriptions: which agreement layout customers get (flyra = Classic, service = Service agreement, modern, letterhead) and color, the colour of every layout but letterhead (null = defaultColor). customAgreement true means this business has its own agreement, which customers get instead. canEdit says whether the caller may change it (Admins and Owners). Needs a signed-in Flyra user. Read only.\n\nScope: `agreements:read`.","x-required-scope":"agreements:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_contract_library":{"post":{"operationId":"flyra_set_contract_library","summary":"Set the contract library layout","tags":["Settings"],"description":"Saves the contract library on Settings > Subscriptions, Admins and Owners only: the layout customer agreements are drawn in, and its colour. Send both, as the screen does: color null (or the default colour) is the default, so pass the current color from flyra_get_contract_library to keep it. Sends nothing to anyone. Returns what was saved.\n\nScope: `settings:write`.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"layout":{"type":"string","enum":["flyra","service","modern","letterhead"],"description":"flyra (Classic), service (Service agreement), modern, or letterhead"},"color":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"#RRGGBB, or null for the default colour. Not used by letterhead."}},"required":["layout","color"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_agreement_defaults":{"post":{"operationId":"flyra_set_agreement_defaults","summary":"Set agreement defaults","tags":["Settings"],"description":"Saves Agreement defaults on Settings > Subscriptions, Admins only (the screen's rule): terms and conditions, billing information, guarantees and whether they show, whether the before and after gallery shows on agreements, the default cancellation fee (fixed cents, or a percent of one year of the price), the Add payment method button when signing, and whether new subscriptions need a signature. Only the fields you send change. Existing plan templates keep their own copy; this sets what new ones start with. Sends nothing to anyone. Returns the saved defaults. Each text field is replaced in full: send the whole new text, not only the part that changes. The reply's replaced_text holds the text each field replaced, so a mistake can be put back.\n\nScope: `settings:write`.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"terms_and_conditions":{"type":"string"},"billing_information":{"type":"string"},"guarantees":{"type":"string"},"display_guarantees":{"type":"boolean"},"display_before_after":{"type":"boolean"},"cancellation_fee_cents":{"type":"integer","minimum":0,"maximum":100000000},"cancellation_fee_type":{"type":"string","enum":["fixed","percent"]},"cancellation_fee_percent":{"type":"number","minimum":0,"maximum":100},"agreement_payment_method_enabled":{"type":"boolean"},"require_signature_on_create":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_job_checklist":{"post":{"operationId":"flyra_get_job_checklist","summary":"Get a job's checklist","tags":["Jobs"],"description":"Return the job checklist items in position order, including completion timestamps + completing employee.\n\nScope: `jobs:read`.","x-required-scope":"jobs:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string"}},"required":["job_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_mark_checklist_item":{"post":{"operationId":"flyra_mark_checklist_item","summary":"Toggle a checklist item","tags":["Jobs"],"description":"Mark a job-checklist item complete (status=\"completed\") or reopen it (status=\"pending\"), as ticking it in the job's checklist does (PATCH /api/jobs/[id]/checklist/[itemId]). Updates completed_at + completed_by when completing. Anyone who can open the job may call it.\n\nScope: `jobs:write`.","x-required-scope":"jobs:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"item_id":{"type":"string"},"complete":{"type":"boolean"}},"required":["item_id","complete"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_add_job_checklist_item":{"post":{"operationId":"flyra_add_job_checklist_item","summary":"Add a checklist item to a job","tags":["Jobs"],"description":"Add one item to the end of a job's checklist, as adding an item in the job's checklist does (POST /api/jobs/[id]/checklist). Pass checklist_group_id to file it under a checklist template group of this company. Anyone who can open the job may call it.\n\nScope: `jobs:write`.","x-required-scope":"jobs:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"checklist_group_id":{"description":"A checklist template group id (chkgroup_...) to file the item under.","type":"string"}},"required":["job_id","title"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_edit_job_checklist_item":{"post":{"operationId":"flyra_edit_job_checklist_item","summary":"Edit a checklist item on a job","tags":["Jobs"],"description":"Change the title or description of one item on a job's checklist, as editing an item in the job's checklist does (PATCH /api/jobs/[id]/checklist/[itemId]). Use flyra_mark_checklist_item to tick it. Anyone who can open the job may call it.\n\nScope: `jobs:write`.","x-required-scope":"jobs:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string"},"item_id":{"type":"string"},"title":{"type":"string"},"description":{"description":"An empty string clears it.","type":"string"}},"required":["job_id","item_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_remove_job_checklist_item":{"post":{"operationId":"flyra_remove_job_checklist_item","summary":"Remove a checklist item from a job","tags":["Jobs"],"description":"Delete one item from a job's checklist, as deleting an item in the job's checklist does (DELETE /api/jobs/[id]/checklist/[itemId]). It cannot be undone. Anyone who can open the job may call it.\n\nScope: `jobs:write`. Destructive: it deletes or cancels.","x-required-scope":"jobs:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string"},"item_id":{"type":"string"},"confirm":{"type":"boolean","const":true,"description":"Must be true: the item is deleted from the job."}},"required":["job_id","item_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_checklist_groups":{"post":{"operationId":"flyra_list_checklist_groups","summary":"List checklist template groups","tags":["Services"],"description":"Return the checklist template groups on Settings > Price Book in their order, each with its items in order, as that screen loads them (GET /api/checklist-categories). An item's auto_attach says whether it is added to new jobs; a group's Auto-add to jobs switch on that screen is on when any of its items is (flyra_set_checklist_group_auto_add flips it). A group's own auto_attach is an older group flag that new jobs do not read. Admins and Owners only.\n\nScope: `services:read`.","x-required-scope":"services:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_create_checklist_group":{"post":{"operationId":"flyra_create_checklist_group","summary":"Create a checklist template group","tags":["Services"],"description":"Add a checklist template group at the end of the list on Settings > Price Book, as adding a group there does (POST /api/checklist-categories). It starts with no items and is not added to new jobs. Admins and Owners only.\n\nScope: `services:write`.","x-required-scope":"services:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":2000}},"required":["name"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_rename_checklist_group":{"post":{"operationId":"flyra_rename_checklist_group","summary":"Rename a checklist template group","tags":["Services"],"description":"Change the name, and the description if given, of one checklist template group on Settings > Price Book, as editing a group there does (PUT /api/checklist-categories/[id]). Leaving description out keeps it; an empty string clears it. Its items and jobs are not changed. Admins and Owners only.\n\nScope: `services:write`.","x-required-scope":"services:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"group_id":{"type":"string","maxLength":200,"description":"Group id (chkgroup_...) from flyra_list_checklist_groups."},"name":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":2000}},"required":["group_id","name"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_checklist_group_auto_add":{"post":{"operationId":"flyra_set_checklist_group_auto_add","summary":"Switch a checklist template group's Auto-add to jobs on or off","tags":["Services"],"description":"The Auto-add to jobs switch on one checklist template group on Settings > Price Book, saving what that switch saves (PUT /api/checklist-categories/automation). auto_add=true adds every item in the group to each job created from now on; auto_add=false stops all of them. Jobs that already exist are not changed, and the other groups' items keep their own setting. The switch shows only on a group with at least one item, so an empty group is refused. Admins and Owners only.\n\nScope: `services:write`.","x-required-scope":"services:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"group_id":{"type":"string","maxLength":200,"description":"Group id (chkgroup_...) from flyra_list_checklist_groups."},"auto_add":{"type":"boolean","description":"true switches it on, false switches it off."}},"required":["group_id","auto_add"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_delete_checklist_group":{"post":{"operationId":"flyra_delete_checklist_group","summary":"Delete a checklist template group","tags":["Services"],"description":"Delete one checklist template group from Settings > Price Book, as deleting a group there does (DELETE /api/checklist-categories/[id]). Its template items are deleted with it. Checklists already on jobs keep their items. It cannot be undone. Admins and Owners only. Confirm with the user, then pass confirm: true.\n\nScope: `services:write`. Destructive: it deletes or cancels.","x-required-scope":"services:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"group_id":{"type":"string","maxLength":200,"description":"Group id (chkgroup_...) from flyra_list_checklist_groups."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the group and its template items are deleted."}},"required":["group_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_add_checklist_template_item":{"post":{"operationId":"flyra_add_checklist_template_item","summary":"Add an item to a checklist template group","tags":["Services"],"description":"Add one item to the end of a checklist template group on Settings > Price Book, as adding an item there does (POST /api/checklist-items). Jobs that already have the group are not changed. Admins and Owners only.\n\nScope: `services:write`.","x-required-scope":"services:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"group_id":{"type":"string","maxLength":200,"description":"Group id (chkgroup_...) from flyra_list_checklist_groups."},"title":{"type":"string","maxLength":500},"description":{"type":"string","maxLength":2000}},"required":["group_id","title"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_edit_checklist_template_item":{"post":{"operationId":"flyra_edit_checklist_template_item","summary":"Edit a checklist template item","tags":["Services"],"description":"Change the title or description of one item in a checklist template group on Settings > Price Book, as editing an item there does (PUT /api/checklist-items/[id]). Its picture and place in the group are kept. Jobs that already have the item are not changed. Admins and Owners only.\n\nScope: `services:write`.","x-required-scope":"services:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"item_id":{"type":"string","maxLength":200,"description":"Template item id (chktpl_...) from flyra_list_checklist_groups."},"title":{"type":"string","maxLength":500},"description":{"description":"An empty string clears it.","type":"string","maxLength":2000}},"required":["item_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_delete_checklist_template_item":{"post":{"operationId":"flyra_delete_checklist_template_item","summary":"Delete a checklist template item","tags":["Services"],"description":"Delete one item from a checklist template group on Settings > Price Book, as deleting an item there does (DELETE /api/checklist-items/[id]). Checklists already on jobs keep it. It cannot be undone. Admins and Owners only. Confirm with the user, then pass confirm: true.\n\nScope: `services:write`. Destructive: it deletes or cancels.","x-required-scope":"services:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"item_id":{"type":"string","maxLength":200,"description":"Template item id (chktpl_...) from flyra_list_checklist_groups."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the template item is deleted."}},"required":["item_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_customers_within_radius":{"post":{"operationId":"flyra_customers_within_radius","summary":"Find customers near a point","tags":["Customers"],"description":"Return customers within `miles` miles of (latitude, longitude). Uses the haversine formula against customers.latitude / longitude — those columns are populated by the geocoding pipeline. Customers without coords are skipped. One search reads at most 5000 customers around the point; truncated: true means the area held more, so a smaller radius gives exact results.\n\nScope: `customers:read`.","x-required-scope":"customers:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"miles":{"type":"number","exclusiveMinimum":0,"maximum":500,"description":"Radius in miles."},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":50}},"required":["latitude","longitude","miles"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_live_locations":{"post":{"operationId":"flyra_list_live_locations","summary":"See where teammates are now","tags":["Map"],"description":"The live location dots on the Map. teammates: everyone who reported a location in the last 8 hours, except the caller, with name, lat, lng, accuracy (meters), updatedAt, isLive (true = reporting now, false = last seen) and source (foreground or background). sharingEnabled: whether the caller shares their own location; tracking: the company's tracking hours. teammates is empty when live locations are not switched on for this company. Anyone who can open the Map (Admins, or a role with View Map on); an organization API key is refused. Read only.\n\nScope: `pins:read`.","x-required-scope":"pins:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_measure_area":{"post":{"operationId":"flyra_measure_area","summary":"Measure an area","tags":["Map"],"description":"Map > Measure an area: the area inside an outline traced as [longitude, latitude] points, through the same measureShape maths the line-item Measure modal prices with. Returns area_sq_ft, area_sq_meters, perimeter_ft (the closed outline) and self_intersects; when the outline crosses itself the area is 0, as in the modal. Saves nothing. Anyone who can open the Map (Admins, or a role with View Map on); an organization API key is refused. Read only.\n\nScope: `pins:read`.","x-required-scope":"pins:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"points":{"minItems":3,"maxItems":500,"type":"array","items":{"minItems":2,"maxItems":2,"type":"array","items":{"type":"number","minimum":-180,"maximum":180}},"description":"The outline, in order, each point [longitude, latitude] (latitude -90 to 90). At least 3 points; the shape is closed back to the first point."}},"required":["points"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_global_search":{"post":{"operationId":"flyra_global_search","summary":"Search everything (the app search box)","tags":["Customers"],"description":"The search box at the top of the Flyra app: finds customers, jobs, subscriptions, invoices, estimates and employees whose name, title or details contain the words, in one call. Each row has entity_type, entity_id, title, subtitle and route (the app page). Any member of the company can use it, as in the app; a signed-in person is needed. A person kept to their own customers sees only those customers and their jobs, invoices, estimates and plans, and each record type shows only if this connection was granted that area. After those records come the leads and text messages the same search box lists (the app's people search): up to 8 leads (entity_type \"lead\") the person may see, needing the leads area, and up to 5 text threads whose messages contain the words (entity_type \"message\", entity_id is the conversation, subtitle the matching text), needing the texts area and a role that can view messages. Near spellings (typos) the app may also find are not matched in the records.\n\nScope: `customers:read`.","x-required-scope":"customers:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":200,"description":"Words to find, as typed into the app search box."},"limit":{"description":"How many rows, 12 by default (the app shows 12), at most 50.","type":"integer","minimum":1,"maximum":50}},"required":["query"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_filter_customers":{"post":{"operationId":"flyra_filter_customers","summary":"Filter customers by structured criteria","tags":["Customers"],"description":"Smart filter: returns customers matching one or more conditions.\n\n- query: free-text match on name, email or phone. Punctuation is matched literally, so query=\"UNC (solar deal)\" finds exactly that phrase.\n- tag: customers carrying a tag, by label or tag id.\n- last_booked_days_gt: only customers whose last visit was more than N days ago. A visit is a completed or in-progress job, dated by when it was done. A customer who has never been served has no such date and is never returned by this condition.\n- has_subscription: true → only customers with at least one subscription; false → only customers without.\n- min_lifetime_value_cents: minimum lifetime value — the sum of every job amount except cancelled ones, the same number the customers screen shows.\n- has_unpaid_invoice: true → only customers with at least one unpaid invoice.\n- city / state / zip: exact text match.\n\nCombine freely — all conditions AND together.\n\nPAGINATION. A page holds at most 50. When more matched, `next_cursor` is non-null: pass it back verbatim to get the next page, and keep going until it comes back null. `matched_so_far` counts what this call found, NOT the size of the whole result set — only an exhausted scan (next_cursor null) tells you the total.\n\nTo act on every match rather than read them, hand the same filter to flyra_bulk_update or flyra_bulk_delete instead of paging the ids out yourself. Those tools understand query / tag / city / state / zip only; for last_booked_days_gt, min_lifetime_value_cents, has_subscription or has_unpaid_invoice, page the matches out here and pass their `ids`.\n\nCUSTOMERS PAGE FILTERS. These are the filters on the Customers page, answered by the same search the page runs, with the same access rules (the role's customers, the business's settings, hidden pricing): created_from / created_to, service_keys, sales_rep_ids, technician_ids, job_count, has_email, has_phone, has_address, and the page's Leave out menu: leave_out_subscribed, leave_out_serviced_within_days, leave_out_scheduled_from / leave_out_scheduled_to. They combine with each other, not with the conditions above, and need a signed-in person (an organization API key is refused). Their pages come back with `total` and a `next_cursor` of the form \"page:N\".\n\nScope: `customers:read`.","x-required-scope":"customers:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"description":"Free-text match against first_name, last_name, display_name, email, mobile_phone. Matched literally — parentheses, commas and apostrophes are part of the phrase.","type":"string"},"tag":{"description":"Tag label (case-insensitive) or tag id. See flyra_list_tags.","type":"string"},"last_booked_days_gt":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"has_subscription":{"type":"boolean"},"min_lifetime_value_cents":{"type":"integer","minimum":0,"maximum":9007199254740991},"has_unpaid_invoice":{"type":"boolean"},"city":{"type":"string"},"state":{"type":"string"},"zip":{"type":"string"},"created_from":{"description":"Customers page filter: added on or after this date (YYYY-MM-DD, from the start of that day UTC) or time (ISO 8601).","type":"string"},"created_to":{"description":"Customers page filter: added on or before this date (YYYY-MM-DD, to the end of that day UTC) or time (ISO 8601).","type":"string"},"service_keys":{"description":"Customers page filter: customers who bought one of these, each \"line_item:<catalog item id>\" or \"subscription:<plan template id>\".","maxItems":50,"type":"array","items":{"type":"string"}},"sales_rep_ids":{"description":"Customers page filter: employee ids (emp_<uuid>); customers with a job that is not cancelled sold by one of them.","maxItems":50,"type":"array","items":{"type":"string"}},"technician_ids":{"description":"Customers page filter: employee ids (emp_<uuid>); customers with a job that is not cancelled dispatched to one of them, or a subscription that is not cancelled whose crew includes one.","maxItems":50,"type":"array","items":{"type":"string"}},"job_count":{"description":"Customers page filter: how many jobs the customer has, as the page counts them.","type":"string","enum":["0","1","2-5","6+"]},"has_email":{"description":"Customers page filter: true only customers with an email, false only those without.","type":"boolean"},"has_phone":{"description":"Customers page filter: true only customers with a phone, false only those without.","type":"boolean"},"has_address":{"description":"Customers page filter: true only customers with an address, false only those without.","type":"boolean"},"leave_out_subscribed":{"description":"Customers page Leave out, \"Customers on a subscription\": true leaves out every customer with an active subscription.","type":"boolean","const":true},"leave_out_serviced_within_days":{"description":"Customers page Leave out, \"Serviced in the last\": 30, 60, 90 or 180 days. Leaves out customers whose last service date (the one the page shows) falls inside that window; a customer never serviced still shows.","type":"number","enum":[30,60,90,180]},"leave_out_scheduled_from":{"description":"Customers page Leave out, \"Scheduled\" (shown only to some businesses; refused for the rest): first day, YYYY-MM-DD. Leaves out customers with a job that is not cancelled starting between the two days, both inclusive, on the business's own calendar. Needs leave_out_scheduled_to.","type":"string"},"leave_out_scheduled_to":{"description":"Customers page Leave out, \"Scheduled\": last day, YYYY-MM-DD, on or after leave_out_scheduled_from.","type":"string"},"limit":{"description":"Matches per page (default 25, cap 50).","type":"integer","exclusiveMinimum":0,"maximum":50},"cursor":{"description":"The `next_cursor` from the previous call. Omit for the first page.","type":"string"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_map_pins":{"post":{"operationId":"flyra_list_map_pins","summary":"List map pins","tags":["Map"],"description":"List canvassing pins. Filter by status (a key from flyra_list_pin_types, e.g. not_home, quote, sale, do_not_contact), customer_id, since, created_by.\n\ncreated_by is the rep who dropped the pin, as Filter by person on the Map: pass their user id (each pin's created_by_user_id). It matches the pin's creator id only. Unlike the Map's filter, older pins saved with only a name or email prefix and no creator id are not matched, and it cannot be combined with `near`. Where this business shows reps only their own pins, a rep gets only their own pins whatever is passed.\n\nPass `near` to bound results to a radius around a point — far cheaper than scanning all pins for a big org.\n\nCap 50 per call. Pins without coordinates are skipped when `near` is used.\n\nScope: `pins:read`.","x-required-scope":"pins:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"Pin status key from flyra_list_pin_types (e.g. not_home, quote, sale, do_not_contact).","type":"string"},"customer_id":{"type":"string"},"since":{"description":"ISO 8601 — only pins created on or after.","type":"string"},"created_by":{"description":"User id of the rep who dropped the pin (a pin's created_by_user_id).","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"near":{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"miles":{"type":"number","exclusiveMinimum":0,"maximum":500}},"required":["latitude","longitude","miles"]},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":50},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_map_pin":{"post":{"operationId":"flyra_get_map_pin","summary":"Get a map pin","tags":["Map"],"description":"Full detail for a single pin including linked customer/job and objections.\n\nScope: `pins:read`.","x-required-scope":"pins:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"pin_id":{"type":"string"}},"required":["pin_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_create_map_pin":{"post":{"operationId":"flyra_create_map_pin","summary":"Drop a new map pin","tags":["Map"],"description":"Add a pin from a door-knock or canvassing outcome. Provide coordinates {latitude, longitude}, a status, a client_name and an address.\n\nStatus is a key from flyra_list_pin_types: the built-in ones are sale, not_home, not_interested, not_qualified, do_not_contact, revisit, referral, quote, yard_sign, door_hanger, flyer and cancelled_sale, plus any custom type the business added. There is no \"lead\" pin status: a pin whose door became a lead is linked through flyra_create_lead with pin_id.\n\nclient_name and address are both required — the map stores every pin against a name and a street address, and a pin without either cannot be saved. When the door was answered by someone who would not give a name, pass something descriptive (\"No name given\", \"Blue house on the corner\") rather than leaving it out.\n\nOptional `customer_id` / `job_id` link the pin to an existing record. `objection_ids` should come from flyra_list_objections.\n\nScope: `pins:write`.","x-required-scope":"pins:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"coordinates":{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"required":["latitude","longitude"]},"status":{"type":"string","minLength":1,"maxLength":40},"client_name":{"type":"string","minLength":1,"description":"Who lives here. Required. Use a placeholder like \"No name given\" when the name is genuinely unknown."},"address":{"type":"string","minLength":1,"description":"Street address for the pin. Required."},"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"mobile":{"type":"string"},"customer_id":{"type":"string"},"job_id":{"type":"string"},"objection_ids":{"type":"array","items":{"type":"string"}},"notes":{"type":"string"}},"required":["coordinates","status","client_name","address"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_map_pin":{"post":{"operationId":"flyra_update_map_pin","summary":"Update a map pin","tags":["Map"],"description":"Partial update — pass only fields you want to change. Pass null to clear a value. Nothing updates a pin on its own when its door becomes a lead or gets an estimate: set status to \"quote\" here after flyra_send_estimate, or pass pin_id and pin_status to flyra_create_lead when the lead is made.\n\nScope: `pins:write`.","x-required-scope":"pins:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"pin_id":{"type":"string"},"status":{"description":"A key from flyra_list_pin_types.","type":"string"},"client_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"address":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"null"}]},"mobile":{"anyOf":[{"type":"string"},{"type":"null"}]},"notes":{"anyOf":[{"type":"string"},{"type":"null"}]},"customer_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"job_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"objection_ids":{"type":"array","items":{"type":"string"}},"coordinates":{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"required":["latitude","longitude"]}},"required":["pin_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_add_map_pin_photo":{"post":{"operationId":"flyra_add_map_pin_photo","summary":"Add a photo to a map pin","tags":["Map"],"description":"Add one picture to a map pin, as Upload Photos on the pin sheet does. It is added to the pin's photos (flyra_get_map_pin `images`) and shows on the pin in the app. It is not sent to anyone.\n\nGive the picture as image_url (a public https link that does not redirect) or as image_base64 (the file's bytes). JPG, PNG, WebP, GIF or HEIC (saved as JPG), up to 10 MB. Like a photo added in the app, it is kept behind a public link that anyone holding it can open.\n\nWhere this business shows reps only their own pins, a rep can add photos only to pins they dropped.\n\nScope: `pins:write`.","x-required-scope":"pins:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"pin_id":{"type":"string","description":"Pin UUID or semantic id (pin_<uuid>)."},"image_url":{"description":"Public https link to the picture. Pass this or image_base64.","type":"string"},"image_base64":{"description":"The picture's bytes, base64 encoded. Pass this or image_url.","type":"string","maxLength":14000000}},"required":["pin_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_delete_map_pin":{"post":{"operationId":"flyra_delete_map_pin","summary":"Delete a map pin","tags":["Map"],"description":"Permanently remove a pin. There is no undo — confirm with the user before calling.\n\nScope: `pins:write`. Destructive: it deletes or cancels.","x-required-scope":"pins:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"pin_id":{"type":"string"}},"required":["pin_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_objections":{"post":{"operationId":"flyra_list_objections","summary":"List objection reasons","tags":["Map"],"description":"Lookup table — returns the org's objection labels with their ids so the agent can set pin.objection_ids correctly.\n\nScope: `pins:read`.","x-required-scope":"pins:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_create_objection":{"post":{"operationId":"flyra_create_objection","summary":"Create an objection","tags":["Map"],"description":"Add an objection to the org's list: what a homeowner says when they turn a rep down (e.g. \"Too expensive\"). Reps tag objections on map pins. Fails if an active objection already has the same name, ignoring case. If a removed objection had that name it is restored with its original spelling instead (`restored: true`).\n\nScope: `pins:write`.","x-required-scope":"pins:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Objection name, e.g. \"Too expensive\"."}},"required":["name"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_objection":{"post":{"operationId":"flyra_update_objection","summary":"Update an objection","tags":["Map"],"description":"Rename an objection. Pass the id from flyra_list_objections. The rename fails if another active objection has that name, or if a deleted objection still owns it.\n\nScope: `pins:write`.","x-required-scope":"pins:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"objection_id":{"type":"string","description":"ID of the objection, from flyra_list_objections."},"name":{"type":"string","minLength":1,"maxLength":100,"description":"New name."}},"required":["objection_id","name"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_delete_objection":{"post":{"operationId":"flyra_delete_objection","summary":"Delete an objection","tags":["Map"],"description":"Deletes an objection reason, as the delete button under Objections on Settings > Organization does. Like that button it archives the objection rather than removing it: it is no longer offered, while pins that carry it keep it and the map report keeps its name. Restore it by creating an objection with the same name (flyra_create_objection). Pass the id from flyra_list_objections. Admins and Owners only, as on that screen.\n\nScope: `pins:write`. Destructive: it deletes or cancels.","x-required-scope":"pins:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"objection_id":{"type":"string","description":"ID of the objection, from flyra_list_objections."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed the delete."}},"required":["objection_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_territories":{"post":{"operationId":"flyra_list_territories","summary":"List canvassing territories","tags":["Map"],"description":"Returns the territory polygons the caller can see on the map, with assigned employees + color: admins, owners and managers see every territory; anyone else sees the ones they created or are assigned to. Each territory carries a `map_url` that opens Flyra's map zoomed onto it — paste that into an SMS or email to send someone today's streets. It opens the app, so the recipient needs a Flyra login. Each territory carries `estimated_homes`, the \"~N homes\" figure shown in Map > Territories (an estimate from address points), with `estimated_homes_updated_at`; both are null until Flyra has counted that territory.\n\nScope: `pins:read`.","x-required-scope":"pins:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"assigned_employee_id":{"description":"Filter to territories assigned to this employee.","type":"string"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_territory":{"post":{"operationId":"flyra_get_territory","summary":"Get a territory","tags":["Map"],"description":"Full territory detail including polygon vertices, and a `map_url` that opens Flyra's map zoomed onto this territory (an app link — the recipient needs a Flyra login). Each territory carries `estimated_homes`, the \"~N homes\" figure shown in Map > Territories (an estimate from address points), with `estimated_homes_updated_at`; both are null until Flyra has counted that territory.\n\nScope: `pins:read`.","x-required-scope":"pins:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"territory_id":{"type":"string"}},"required":["territory_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_create_territory":{"post":{"operationId":"flyra_create_territory","summary":"Create a canvassing territory","tags":["Map"],"description":"Create a new territory polygon. Polygon is an array of [longitude, latitude] pairs (GeoJSON outer-ring order) — minimum 3 vertices.\n\nOptional: assign the territory to one or more employees by their UUIDs. The people assigned are not emailed or notified.\n\nAdmins, owners, managers, and roles with territory editing only. A polygon that crosses itself is refused.\n\nScope: `pins:write`.","x-required-scope":"pins:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Display name for the territory."},"polygon":{"minItems":3,"type":"array","items":{"minItems":2,"maxItems":2,"type":"array","items":{"type":"number"}},"description":"Array of [longitude, latitude] pairs forming the boundary."},"color":{"description":"Hex color for the territory (e.g. \"#FF5733\").","type":"string"},"assigned_employees":{"description":"Employee UUIDs to assign to this territory.","type":"array","items":{"type":"string"}},"prospect_name":{"description":"Optional prospect / neighborhood name.","type":"string"}},"required":["name","polygon"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_territory":{"post":{"operationId":"flyra_update_territory","summary":"Update a territory","tags":["Map"],"description":"Partial update — pass only the fields you want to change. Pass an empty array to clear assigned_employees; anyone newly assigned is not emailed or notified. Admins, owners, managers, and roles with territory editing only. A changed polygon that crosses itself is refused.\n\nScope: `pins:write`.","x-required-scope":"pins:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"territory_id":{"type":"string","description":"Territory UUID or semantic id."},"name":{"type":"string","minLength":1,"maxLength":100},"color":{"anyOf":[{"type":"string"},{"type":"null"}]},"polygon":{"minItems":3,"type":"array","items":{"minItems":2,"maxItems":2,"type":"array","items":{"type":"number"}}},"assigned_employees":{"description":"Full replacement list of employee UUIDs.","type":"array","items":{"type":"string"}},"prospect_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"expected_updated_at":{"description":"The updated_at the territory was read at (flyra_get_territory). When passed, a save by someone else since then is refused as a conflict instead of overwritten.","type":"string"}},"required":["territory_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_delete_territory":{"post":{"operationId":"flyra_delete_territory","summary":"Delete a territory","tags":["Map"],"description":"Permanently removes the territory polygon. Pins that were inside it are NOT deleted — they remain on the map.\n\nScope: `pins:write`. Destructive: it deletes or cancels.","x-required-scope":"pins:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"territory_id":{"type":"string","description":"Territory UUID or semantic id."}},"required":["territory_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_pin_types":{"post":{"operationId":"flyra_list_pin_types","summary":"List pin type configs","tags":["Map"],"description":"Return all pin types for the org, the same list as Settings > Map: the built-in system types merged with any org-level overrides from org_pin_type_configs, plus the org's custom types.\n\nEach entry has: id, key (e.g. \"sale\"), label, icon_name, color, is_enabled, sort_order, is_default, is_system. A built-in type the org has never changed has id null; reach it by key in flyra_update_pin_type.\n\nSystem pin types (sale, not_home, not_interested) are always enabled; is_enabled=false overrides are ignored for those.\n\nScope: `pins:read`.","x-required-scope":"pins:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_create_pin_type":{"post":{"operationId":"flyra_create_pin_type","summary":"Create a custom pin type","tags":["Map"],"description":"Create a new custom (non-system) pin type for the org. Custom types supplement the 9 built-in system types.\n\nRequired: pin_type_key (unique within org), label. Optional: color (hex), icon_name, sort_order, is_default.\n\nSet is_default: true to make this type pre-selected when a user drops a new pin — only one type may be default per org.\n\nScope: `pins:write`.","x-required-scope":"pins:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"pin_type_key":{"type":"string","minLength":1,"maxLength":40,"description":"Unique key for the pin type (e.g. \"follow_up\", \"left_flyer\"). Lowercase, underscores OK."},"label":{"type":"string","minLength":1,"maxLength":60,"description":"Display name shown in the pin picker."},"color":{"description":"Hex color (e.g. \"#FF5733\").","type":"string"},"icon_name":{"description":"Icon identifier used by the map UI.","type":"string"},"sort_order":{"description":"Position in the pin picker list. Lower = first.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"is_default":{"description":"Pre-select this type when creating a new pin.","type":"boolean"}},"required":["pin_type_key","label"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_pin_type":{"post":{"operationId":"flyra_update_pin_type","summary":"Update a pin type","tags":["Map"],"description":"Partial update on a pin type config row. Pass only the fields you want to change.\n\nYou can update both system and custom types (label, color, icon, sort_order, is_enabled, is_default). Pass id, or key for a built-in type whose id is null in flyra_list_pin_types; the first change to it saves its row.\n\nis_default stars the one default type for the whole company, as Settings > Map does: every other type loses the star, and a disabled type cannot have it.\n\nNote: is_enabled=false is ignored by the map UI for the three always-required types (sale, not_home, not_interested).\n\nScope: `pins:write`.","x-required-scope":"pins:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"description":"Row id from flyra_list_pin_types. Pass key instead when the id is null.","type":"string"},"key":{"description":"Pin type key from flyra_list_pin_types, e.g. \"not_home\". Used when id is not passed.","type":"string","minLength":1,"maxLength":40},"label":{"type":"string","minLength":1,"maxLength":60},"color":{"type":"string"},"icon_name":{"type":"string"},"sort_order":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"is_enabled":{"type":"boolean"},"is_default":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_delete_pin_type":{"post":{"operationId":"flyra_delete_pin_type","summary":"Delete a pin type config","tags":["Map"],"description":"Delete an org pin type config row.\n\nFor system types (is_system=true) this resets the type back to its built-in defaults (the API rejects deleting required types like sale/not_home/not_interested — you will get a validation_error).\n\nFor custom types (is_system=false) the row is permanently removed.\n\nScope: `pins:write`. Destructive: it deletes or cancels.","x-required-scope":"pins:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Row id from flyra_list_pin_types."}},"required":["id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_default_pins":{"post":{"operationId":"flyra_list_default_pins","summary":"List default pin types by person and role","tags":["Employees"],"description":"Show which pin type each person and each role starts new map pins as.\n\nA new pin starts as: the person's own default, else their role's default, else the org's starred type (is_default in flyra_list_pin_types), else Not Home.\n\nReturns employees (only the people with their own default) and roles (every built-in and custom role, pin_type_key null when it has none). Change them with flyra_set_default_pin_type.\n\nScope: `employees:read`.","x-required-scope":"employees:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_default_pin_type":{"post":{"operationId":"flyra_set_default_pin_type","summary":"Set a default pin type for people or roles","tags":["Employees"],"description":"Make a pin type the default for chosen people and/or roles, so the new pins they drop start as that type. Example: a flyer runner who should drop \"Christmas Flyer\" pins while the door knockers stay on Not Home.\n\nPass the pin type key (from flyra_list_pin_types; built-in types such as not_home work even if the org never edited them) and who to add or remove. Everyone else keeps their current default. A person or role has one default, so adding them here moves them off any other type.\n\nRemoving someone sends them back to their role's default, then the org's. Only applies to pins created after the change. The type must be enabled.\n\nOwner, Admin, or a role that can manage the team only.\n\nScope: `employees:write`.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"pin_type_key":{"type":"string","minLength":1,"description":"Pin type key from flyra_list_pin_types, e.g. \"christmas_flyer\" or \"not_home\"."},"add_employee_ids":{"description":"Employees (from flyra_list_employees) who should default to this type.","type":"array","items":{"type":"string"}},"remove_employee_ids":{"description":"Employees who should stop defaulting to this type.","type":"array","items":{"type":"string"}},"add_role_keys":{"description":"Roles that should default to this type: Admin, Sales Rep, Technician, or a custom role id from flyra_list_custom_roles.","type":"array","items":{"type":"string"}},"remove_role_keys":{"description":"Roles that should stop defaulting to this type.","type":"array","items":{"type":"string"}}},"required":["pin_type_key"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_pins_in_territory":{"post":{"operationId":"flyra_pins_in_territory","summary":"Find pins inside a territory","tags":["Map"],"description":"Return the map pins whose coordinates fall inside the given territory polygon. Containment and the count are computed in Postgres, so `total` is the true number inside the territory however many pins the org has.\n\n`total` is what to read for \"how many pins are in this territory\" — `items` is one page of at most 50, so page with `offset` when you need them all. Optional `status` and `since` narrow both.\n\nScope: `pins:read`.","x-required-scope":"pins:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"territory_id":{"type":"string"},"status":{"type":"string"},"since":{"description":"ISO 8601 — only pins created on or after.","type":"string"},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":50},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["territory_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_knocking_sessions":{"post":{"operationId":"flyra_list_knocking_sessions","summary":"List door-knocking sessions","tags":["Map"],"description":"List the team's door-knocking sessions, newest first, as the Sessions view on the Map shows them: who knocked, when, for how long, how far they walked, the pins they dropped by status, sales, and the mood and note they logged. from and to are ISO timestamps with a zone (from inclusive, to exclusive); leave both out for all time. Read only.\n\nScope: `pins:read`.","x-required-scope":"pins:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"from":{"description":"Start of the window, ISO 8601 with a zone, e.g. 2026-10-05T04:00:00Z.","type":"string"},"to":{"description":"End of the window (exclusive), ISO 8601 with a zone.","type":"string"},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":50}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_route_plans":{"post":{"operationId":"flyra_list_route_plans","summary":"List route plans","tags":["Jobs"],"description":"List the business's route plans, newest day first, as the Routes page lists them: the day, name, status (draft, published or archived), how many stops and technicians, and the planned drive time and distance. Filter by a date range, a status, or a search word. Use flyra_get_route_plan for a plan's stops. Read only.\n\nScope: `jobs:read`.","x-required-scope":"jobs:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"from_date":{"description":"First route day, YYYY-MM-DD.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"to_date":{"description":"Last route day, YYYY-MM-DD.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"status":{"type":"string","enum":["draft","published","archived"]},"query":{"description":"Matches the plan name, day, status or id.","type":"string","maxLength":120},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":50}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_route_plan":{"post":{"operationId":"flyra_get_route_plan","summary":"Get a route plan","tags":["Jobs"],"description":"Get one route plan and its stops in order, per technician: each stop's job, sequence, planned arrival and departure, and the drive from the previous stop. Pass plan_id (from flyra_list_route_plans), or route_date to get the most recently updated plan for that day. technician_id narrows the stops to one technician. Read only.\n\nScope: `jobs:read`.","x-required-scope":"jobs:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"plan_id":{"description":"The route plan id.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"route_date":{"description":"A route day, YYYY-MM-DD. Used when plan_id is not given.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"technician_id":{"description":"Employee id (emp_<uuid> or uuid) to show only their stops.","type":"string"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_optimize_route":{"post":{"operationId":"flyra_optimize_route","summary":"Optimize a day's route","tags":["Jobs"],"description":"Route optimization for a day's jobs, like Create New Route on the Routes page: orders the jobs into the shortest drive for each technician and returns the stops with planned arrival times. Get the day's job ids from flyra_get_schedule. By default this is a preview (dry_run true) that saves nothing. With dry_run false it saves a DRAFT route plan, and any other draft plans for that day are archived. Either way it calls Google Maps (a paid service). It does NOT move any job, change who is assigned, or text anyone: publishing a plan stays in the app. Jobs without a location are listed in excluded_jobs. With grouping, like Group nearby jobs on the Routes page, the jobs are split into groups of nearby jobs (within distance_miles of each other, at most max_jobs_per_group each) and each group is routed on its own; groups lists them. A grouped run is a preview only, as on the page: to save a group, call again without grouping, passing that group's job_ids.\n\nScope: `jobs:write`.","x-required-scope":"jobs:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"route_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The day to route, YYYY-MM-DD."},"job_ids":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"string"},"description":"The jobs to route (job_<uuid> or uuid), up to 100."},"technician_ids":{"description":"Technicians (emp_<uuid> or uuid) to split the jobs between. Leave out for one unassigned route.","maxItems":25,"type":"array","items":{"type":"string"}},"route_name":{"description":"Plan name. Defaults to the day's next \"Route N\".","type":"string","minLength":1,"maxLength":120},"route_start_time":{"description":"Day starts, HH:MM in the business's time zone. Default 09:00.","type":"string","pattern":"^([0-1]\\d|2[0-3]):[0-5]\\d$"},"route_end_time":{"description":"Day ends, HH:MM. Default 23:59.","type":"string","pattern":"^([0-1]\\d|2[0-3]):[0-5]\\d$"},"dry_run":{"description":"true (default): preview only, nothing saved. false: save a draft plan.","type":"boolean"},"start_location":{"description":"Where the day starts, like Set starting point on the Routes page: the first drive is from here. Leave out to start at the first stop.","type":"object","properties":{"lat":{"type":"number"},"lng":{"type":"number"},"address":{"type":"string"}},"required":["lat","lng"]},"grouping":{"description":"Group nearby jobs, as the Routes page does (one technician per group). Preview only: pass with dry_run true or left out.","type":"object","properties":{"enabled":{"type":"boolean"},"distance_miles":{"type":"number","exclusiveMinimum":0,"description":"Jobs within this many miles of each other go in the same group."},"max_jobs_per_group":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"Largest group; a bigger cluster is split."}},"required":["enabled","distance_miles","max_jobs_per_group"]}},"required":["route_date","job_ids"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_route_stop":{"post":{"operationId":"flyra_update_route_stop","summary":"Edit a route stop","tags":["Jobs"],"description":"Edit one stop on a route plan, as PATCH /api/routes/stops/[id] does: is_locked true or false locks or unlocks it, and resequence puts all of that technician's stops on the plan in a new order (list every one of their stop ids exactly once, with sequences 1, 2, 3 and so on). Stop ids come from flyra_get_route_plan. It changes the plan only: it does NOT move any job, change who is assigned, or text anyone. Admins, or a role that manages the team.\n\nScope: `jobs:write`.","x-required-scope":"jobs:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"stop_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$","description":"The route stop id, from flyra_get_route_plan."},"is_locked":{"description":"true locks the stop, false unlocks it.","type":"boolean"},"resequence":{"description":"Every stop of this stop's technician on the plan, each with its new sequence (1, 2, 3 ...).","minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"sequence":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["id","sequence"]}}},"required":["stop_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_rename_route_plan":{"post":{"operationId":"flyra_rename_route_plan","summary":"Rename a route plan","tags":["Jobs"],"description":"Rename a route plan, as the route name box on the Routes page does. Only the name changes. Plan ids come from flyra_list_route_plans. Admins, or a role that manages the team.\n\nScope: `jobs:write`.","x-required-scope":"jobs:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"plan_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$","description":"The route plan id."},"name":{"type":"string","minLength":1,"maxLength":120,"description":"The new plan name."}},"required":["plan_id","name"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_publish_route_plans":{"post":{"operationId":"flyra_publish_route_plans","summary":"Publish route plans","tags":["Jobs"],"description":"Publish saved route plans like Publish Route on the Routes page. Each stop gets its arrival from route_start_time (drive from the stop before, rounded up to the half hour, 30 minutes a stop), the plan is published, and each job moves to its stop's time and technician (a multi-day Anytime job keeps its days). This MESSAGES CUSTOMERS like the button, by the business's settings: a job moved to a new time ahead gets the rescheduled text or email, a job with no time starts the booking confirmation automations, a job whose technician changes starts the Technician Dispatched automations; new technicians get the dispatch notice. The page's optional confirmation is not sent. First call dry_run true (default): nothing is written; customer_messages lists who and why, and expected_customer_messages counts them (at least that many messages; a job can get several). Then dry_run false, confirm true and that count; another count publishes nothing. Admins, or roles that manage the team and may dispatch. Signed-in user only.\n\nScope: `jobs:write`. Destructive: it deletes or cancels.","x-required-scope":"jobs:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"plans":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"plan_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$","description":"The route plan id."},"route_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The day of the route, YYYY-MM-DD."},"route_start_time":{"type":"string","pattern":"^([0-1]\\d|2[0-3]):[0-5]\\d$","description":"When the route starts, HH:MM, 24 hour, in planner_time_zone (else the plan's zone, else the business's)."},"technician_id":{"description":"Employee id (emp_<uuid> or uuid) to put on every stop of this plan. Leave out to keep each stop's technician.","type":"string"}},"required":["plan_id","route_date","route_start_time"]},"description":"The plans to publish, up to 10."},"planner_time_zone":{"description":"IANA time zone route_start_time is in, as the Routes page sends its own (e.g. America/Denver). Leave out for the plan's, else the business's.","type":"string","minLength":1,"maxLength":100},"dry_run":{"description":"true (default): list who may be messaged and write nothing. false: publish.","type":"boolean"},"expected_customer_messages":{"description":"Required with dry_run false: the expected_customer_messages the dry run returned.","type":"integer","minimum":0,"maximum":9007199254740991},"confirm":{"type":"boolean","const":true,"description":"Must be true: publishing moves jobs and messages customers."}},"required":["plans","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_google_calendar_status":{"post":{"operationId":"flyra_get_google_calendar_status","summary":"Get Google Calendar status","tags":["Employees"],"description":"Whether the signed-in person's Google Calendar is connected to Flyra, so their jobs sync to it: connected, status (connected, reauth_required, disabled, or null when never connected), the Google account, and when it last synced. configured is false when Google Calendar is not available for this company. Each person connects their own calendar; this never shows another person's, and never returns a token. To connect or reconnect, the person opens connect_url (the Schedule page), clicks the Google Calendar button in the toolbar, then Connect (or Reconnect); an agent cannot connect it. flyra_disconnect_google_calendar disconnects it. Read only.\n\nScope: `employees:read`.","x-required-scope":"employees:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_disconnect_google_calendar":{"post":{"operationId":"flyra_disconnect_google_calendar","summary":"Disconnect Google Calendar","tags":["Employees"],"description":"Disconnect the signed-in person's own Google Calendar from Flyra, as the Disconnect button on the Schedule page's Google Calendar card does. This DELETES the \"Flyra\" calendar Flyra made in their Google account (with every job event on it), revokes Flyra's access to their Google account and stops syncing. It only ever touches the caller's own connection, never another person's. Needs confirm: true and a signed-in user. Returns disconnected: true, also when nothing was connected. Reconnecting is done in the app.\n\nScope: `employees:write`. Destructive: it deletes or cancels.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"confirm":{"type":"boolean","const":true,"description":"Must be true: the Flyra calendar is deleted from the person's Google account."}},"required":["confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_lead_forms":{"post":{"operationId":"flyra_list_lead_forms","summary":"List lead capture forms","tags":["Forms"],"description":"Returns the org's lead capture forms with their published state, embed URL, and field count. Use flyra_get_lead_form for the full schema.\n\nScope: `forms:read`.","x-required-scope":"forms:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"is_published":{"description":"Filter by published state.","type":"boolean"},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":50},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_lead_form":{"post":{"operationId":"flyra_get_lead_form","summary":"Get a lead capture form","tags":["Forms"],"description":"Full detail for a single form including schema_json (field definitions) and settings_json.\n\nScope: `forms:read`.","x-required-scope":"forms:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"form_id":{"type":"string","description":"Form UUID or semantic id (form_<uuid>)."}},"required":["form_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_create_lead_form":{"post":{"operationId":"flyra_create_lead_form","summary":"Create a lead capture form","tags":["Forms"],"description":"Create a new embeddable lead capture form. The form starts as a draft (is_published=false).\n\nschema_json is the whole form: { title?, description?, fields, steps?, faq?, contactFooter? }.\n\nEach entry in fields: { type, label, key?, required?, placeholder?, helperText?, options?, width?, step?, show_when? }.\n- type is one of \"text\", \"email\", \"phone\", \"textarea\", \"select\", \"multiselect\", \"checkbox\", \"date\", \"address\", \"preferred_time\", \"scheduling\", \"service_picker\", \"file_upload\".\n- key is derived from the label when omitted. Set it yourself on any field that a show_when rule points at.\n- options (select, multiselect) may be plain strings. Each becomes { label, value }, with value slugified from the label (\"Yes\" becomes \"yes\"). A select with no options is hidden.\n- width is \"full\" (default) or \"half\".\n\nMulti-step (split the form into pages):\n- Give every field a `step`: 0 for the first page, 1 for the second, and so on. The public form becomes pages as soon as its visible fields use more than one step. There is no page-break field type; `step` is how pages are made.\n- Also set steps: { enabled: true, labels: [...] } with one label per step, in order. steps.labels name the steps in the form builder; the public form shows progress dots, not the labels.\n- settings_json.nextButtonText (default \"Continue\"), settings_json.showStepIndicator and settings_json.showBackButton (both default true) style the pages.\n\nConditional display: show_when is a list of rules, all of which must hold for the field to show: [{ fieldKey, operator, value }].\n- fieldKey is another field's key. operator is \"equals\", \"not_equals\" or \"contains\". value is compared as text with that field's answer; for a select that is the option value, not its label.\n- A show_when field may be required: it is only required while its rules hold, so a hidden field never blocks the submit.\n\nExample, a two-page window quote with steps: { enabled: true, labels: [\"Contact info\", \"Home details\"] }:\n- step 0: name (text), phone (phone), email (email), address (address).\n- step 1: window range (select), French panes (select, options [\"Yes\", \"No\"], key \"has_french_panes\"), number of French panes (text, show_when [{ \"fieldKey\": \"has_french_panes\", \"operator\": \"equals\", \"value\": \"yes\" }]), stories (select), square footage (text), plan (select).\n\nReturns the embed URL immediately so the agent can share it once published.\n\nTo copy an existing form (for example a second form for yard-sign QR codes that must look like the door-flyer one), read it with flyra_get_lead_form and pass its schema_json, settings_json and style_json here under a new name.\n\nsettings_json.leadSourceLabel tags every lead the form creates with that Lead Source (\"Yard Sign\", \"Door Flyer\"), so the owner can see which marketing source each lead came from.\n\ndefault_pipeline_id is \"Send leads to\": the pipeline this form's leads land in. Admins and Owners only.\n\nsettings_json.successTitle (default \"Request Received\", up to 80 characters) and settings_json.successMessage (default \"Thanks! We will contact you soon.\") are the heading and the sentence on the card a visitor sees after sending the form. {{business_name}} in either becomes the business name.\n\nScope: `forms:write`.","x-required-scope":"forms:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string"},"schema_json":{"description":"The form. Omit to create an empty form and edit in the UI.","type":"object","properties":{"title":{"description":"Heading shown above the form.","type":"string"},"description":{"description":"Line shown under the heading.","type":"string"},"fields":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"description":"Every field on the form, in order. Field shape, `step` and `show_when` are in the tool description."},"steps":{"description":"Multi-step config: { enabled: true, labels: [\"Contact info\", \"Home details\"] }, one label per step.","type":"object","properties":{"enabled":{"type":"boolean"},"labels":{"type":"array","items":{"type":"string"}}},"additionalProperties":{}},"faq":{"description":"FAQ list under the form. Send back what flyra_get_lead_form returned unless you are changing it.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"contactFooter":{"description":"Contact block under the form. Send back what flyra_get_lead_form returned unless you are changing it.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["fields"],"additionalProperties":{}},"style_json":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"The look of the form: logo, brand colors, fonts, button shape. To make a form look like an existing one, read style_json with flyra_get_lead_form and pass it here unchanged. Omit to keep the default look."},"settings_json":{"type":"object","properties":{"submitButtonText":{"type":"string"},"nextButtonText":{"type":"string"},"showStepIndicator":{"type":"boolean"},"showBackButton":{"type":"boolean"},"showTrustMicrocopy":{"type":"boolean"},"trustMicrocopy":{"type":"string"},"requireSmsConsent":{"type":"boolean"},"smsConsentPrechecked":{"type":"boolean"},"smsConsentText":{"type":"string"},"successTitle":{"type":"string","maxLength":80},"successMessage":{"type":"string"},"leadSourceLabel":{"description":"Lead Source for every lead this form creates, e.g. \"Yard Sign\". Matched to the org's Lead Sources list (flyra_list_lead_sources) case-insensitively and created there if missing, so the leads show it in the list and in reports.","type":"string","maxLength":100}}},"default_pipeline_id":{"description":"\"Send leads to\" in the form builder: the pipeline (an id from flyra_list_pipelines) every lead from this form lands in. null clears it, so the leads land in the default pipeline. Admins and Owners only.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_lead_form":{"post":{"operationId":"flyra_update_lead_form","summary":"Update a lead capture form","tags":["Forms"],"description":"Partial update: pass only the arguments you want to change (name, description, schema_json, style_json, settings_json, default_pipeline_id).\ndefault_pipeline_id is \"Send leads to\": the pipeline this form's leads land in, or null for the default pipeline. Admins and Owners only.\nBut schema_json replaces the whole stored schema, style_json replaces the whole stored look and settings_json replaces the whole stored settings.\nRead the form with flyra_get_lead_form first and send back the complete object with your edits, or everything you leave out is deleted.\n\nsettings_json.leadSourceLabel tags every lead the form creates with that Lead Source (\"Yard Sign\", \"Door Flyer\"); it is matched to the org's Lead Sources list and created there if missing.\n\nsettings_json.metaTitle sets the public form page's browser-tab and link-preview title (default \"<business name> | Web Form\"); settings_json.metaDescription sets its preview description. Only this form changes: the business name stays unchanged. Remove the key to go back to the default.\n\nsettings_json.successTitle (default \"Request Received\", up to 80 characters) and settings_json.successMessage (default \"Thanks! We will contact you soon.\") are the heading and the sentence on the card a visitor sees after sending the form. {{business_name}} in either becomes the business name.\n\nschema_json is the whole form: { title?, description?, fields, steps?, faq?, contactFooter? }.\n\nEach entry in fields: { type, label, key?, required?, placeholder?, helperText?, options?, width?, step?, show_when? }.\n- type is one of \"text\", \"email\", \"phone\", \"textarea\", \"select\", \"multiselect\", \"checkbox\", \"date\", \"address\", \"preferred_time\", \"scheduling\", \"service_picker\", \"file_upload\".\n- key is derived from the label when omitted. Set it yourself on any field that a show_when rule points at.\n- options (select, multiselect) may be plain strings. Each becomes { label, value }, with value slugified from the label (\"Yes\" becomes \"yes\"). A select with no options is hidden.\n- width is \"full\" (default) or \"half\".\n\nMulti-step (split the form into pages):\n- Give every field a `step`: 0 for the first page, 1 for the second, and so on. The public form becomes pages as soon as its visible fields use more than one step. There is no page-break field type; `step` is how pages are made.\n- Also set steps: { enabled: true, labels: [...] } with one label per step, in order. steps.labels name the steps in the form builder; the public form shows progress dots, not the labels.\n- settings_json.nextButtonText (default \"Continue\"), settings_json.showStepIndicator and settings_json.showBackButton (both default true) style the pages.\n\nConditional display: show_when is a list of rules, all of which must hold for the field to show: [{ fieldKey, operator, value }].\n- fieldKey is another field's key. operator is \"equals\", \"not_equals\" or \"contains\". value is compared as text with that field's answer; for a select that is the option value, not its label.\n- A show_when field may be required: it is only required while its rules hold, so a hidden field never blocks the submit.\n\nExample, a two-page window quote with steps: { enabled: true, labels: [\"Contact info\", \"Home details\"] }:\n- step 0: name (text), phone (phone), email (email), address (address).\n- step 1: window range (select), French panes (select, options [\"Yes\", \"No\"], key \"has_french_panes\"), number of French panes (text, show_when [{ \"fieldKey\": \"has_french_panes\", \"operator\": \"equals\", \"value\": \"yes\" }]), stories (select), square footage (text), plan (select).\n\nScope: `forms:write`.","x-required-scope":"forms:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"form_id":{"type":"string","description":"Form UUID or semantic id."},"name":{"type":"string","minLength":1,"maxLength":200},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"schema_json":{"type":"object","properties":{"title":{"description":"Heading shown above the form.","type":"string"},"description":{"description":"Line shown under the heading.","type":"string"},"fields":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"description":"Every field on the form, in order. Field shape, `step` and `show_when` are in the tool description."},"steps":{"description":"Multi-step config: { enabled: true, labels: [\"Contact info\", \"Home details\"] }, one label per step.","type":"object","properties":{"enabled":{"type":"boolean"},"labels":{"type":"array","items":{"type":"string"}}},"additionalProperties":{}},"faq":{"description":"FAQ list under the form. Send back what flyra_get_lead_form returned unless you are changing it.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"contactFooter":{"description":"Contact block under the form. Send back what flyra_get_lead_form returned unless you are changing it.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["fields"],"additionalProperties":{}},"style_json":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"The look of the form: logo, brand colors, fonts, button shape. To make a form look like an existing one, read style_json with flyra_get_lead_form and pass it here unchanged. Omit to keep the default look."},"settings_json":{"type":"object","properties":{"successTitle":{"type":"string","maxLength":80}},"additionalProperties":{}},"default_pipeline_id":{"description":"\"Send leads to\" in the form builder: the pipeline (an id from flyra_list_pipelines) every lead from this form lands in. null clears it, so the leads land in the default pipeline. Admins and Owners only.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["form_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_delete_lead_form":{"post":{"operationId":"flyra_delete_lead_form","summary":"Delete a lead capture form","tags":["Forms"],"description":"Permanently delete a form. Submissions are also deleted. There is no undo. Confirm with the user before calling, and pass confirm: true.\n\nScope: `forms:write`. Destructive: it deletes or cancels.","x-required-scope":"forms:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"form_id":{"type":"string","description":"Form UUID or semantic id."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed the delete, submissions included."}},"required":["form_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_publish_lead_form":{"post":{"operationId":"flyra_publish_lead_form","summary":"Publish a lead capture form","tags":["Forms"],"description":"Sets is_published=true so the form becomes live at its embed URL. Returns the public embed URL.\n\nScope: `forms:write`.","x-required-scope":"forms:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"form_id":{"type":"string","description":"Form UUID or semantic id."}},"required":["form_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_unpublish_lead_form":{"post":{"operationId":"flyra_unpublish_lead_form","summary":"Unpublish a lead capture form","tags":["Forms"],"description":"Sets is_published=false — the embed URL returns 404 until re-published. Submissions are not deleted.\n\nScope: `forms:write`.","x-required-scope":"forms:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"form_id":{"type":"string","description":"Form UUID or semantic id."}},"required":["form_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_form_submissions":{"post":{"operationId":"flyra_list_form_submissions","summary":"List submissions for a lead capture form","tags":["Forms"],"description":"Returns recent submissions for a form. Each submission includes the raw field data submitted by the lead.\n\nScope: `forms:read`.","x-required-scope":"forms:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"form_id":{"type":"string","description":"Form UUID or semantic id."},"since":{"description":"ISO 8601 — only submissions on or after.","type":"string"},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":50},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["form_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_meta_form_routes":{"post":{"operationId":"flyra_list_meta_form_routes","summary":"List Meta instant forms and the pipeline each one feeds","tags":["Leads"],"description":"Lists every Facebook / Instagram (Meta) instant lead form on the organization's connected Facebook pages, with the pipeline each form's new leads land in. A form whose pipeline is null has no override and follows fallback_pipeline (the pipeline set to catch Meta leads), or the default pipeline when there is none. A form with do_not_route true is ignored: its leads never come into Flyra. forms_stale = true means Meta could not be reached, so only forms that already sent leads are listed, named \"Form <id>\". Change a form's pipeline with flyra_set_meta_form_route. Admin role required. The same setting is on Leads > Integrations > Form routing in the Flyra web app.\n\nScope: `leads:read`.","x-required-scope":"leads:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"page":{"description":"A connected Facebook page id or name. Omit to list every connected page.","type":"string"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_meta_form_route":{"post":{"operationId":"flyra_set_meta_form_route","summary":"Send one Meta instant form's leads into a pipeline","tags":["Leads"],"description":"Pins one Facebook / Instagram (Meta) instant lead form to a pipeline, so every NEW lead from that form lands in the first stage of that pipeline instead of the pipeline that catches all other Meta leads. Leads already in Flyra do not move. Every other form keeps its current route. form is the form id or its exact name from flyra_list_meta_form_routes. pipeline is a pipeline id or exact name from flyra_list_pipelines; pass null to remove the override so the form goes back to the default Meta routing, or \"do not route\" to ignore every new lead from that form. Automations that start on a new lead in a specific pipeline will fire for this form's leads from now on. Admin role required. The same setting is on Leads > Integrations > Form routing in the Flyra web app.\n\nScope: `leads:write`.","x-required-scope":"leads:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"form":{"type":"string","minLength":1,"description":"Meta form id, or its exact name (case does not matter)."},"pipeline":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"Pipeline id or exact name, or \"do not route\" to ignore the form. null removes this form's override."},"page":{"description":"Facebook page id or name. Needed only when the form name is on more than one connected page.","type":"string"}},"required":["form","pipeline"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_referrals":{"post":{"operationId":"flyra_list_referrals","summary":"List referrals","tags":["Leads"],"description":"Lists the people customers have referred, newest first: who referred them, the referred person's name and phone, the lead created for them and its pipeline stage, whether they became a customer, and the reward status. The same screen is Leads > Referrals in the Flyra web app.\n\nScope: `leads:read`.","x-required-scope":"leads:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"description":"Default and maximum 50.","type":"integer","exclusiveMinimum":0,"maximum":50},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_referral_stats":{"post":{"operationId":"flyra_get_referral_stats","summary":"Referral program numbers","tags":["Leads"],"description":"The numbers at the top of the Referrals tab: referral requests sent, referrals submitted and converted, conversion rate, revenue from referred customers and rewards released (cents), and the top three referrers. The same screen is Leads > Referrals in the Flyra web app.\n\nScope: `leads:read`.","x-required-scope":"leads:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_mark_referral_reward_paid":{"post":{"operationId":"flyra_mark_referral_reward_paid","summary":"Mark a referral reward paid","tags":["Leads"],"description":"Records that a released referrer reward was given (the credit applied or the gift card sent), as the Mark paid button on Leads > Referrals does: the reward's status becomes redeemed. It changes that status only: no money moves, nothing is charged, credited or sent. Only a reward whose status is released can be marked. Pass reward.referrerId from flyra_list_referrals. Needs a signed-in Flyra user who is an active member of the business, as the button does.\n\nScope: `leads:write`.","x-required-scope":"leads:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reward_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"reward.referrerId from flyra_list_referrals."}},"required":["reward_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_referral_link":{"post":{"operationId":"flyra_get_referral_link","summary":"Get a customer's referral link","tags":["Customers"],"description":"Returns the personal referral page link for one customer, to share with them yourself or put in a message. Anyone with the link can refer people on that customer's behalf; it works for 90 days. Creates nothing and sends nothing. The same screen is Leads > Referrals in the Flyra web app.\n\nScope: `customers:read`.","x-required-scope":"customers:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string","minLength":1,"description":"The customer, from flyra_search_customers."}},"required":["customer_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_referral_settings":{"post":{"operationId":"flyra_get_referral_settings","summary":"Read the referral program settings","tags":["Leads"],"description":"Whether referral requests are on, what triggers them (job completed, good review), the delays, rewards, channels and message. sends_automatically says whether customers are being messaged on their own. Change them with flyra_update_referral_settings. The same screen is Leads > Referrals in the Flyra web app.\n\nScope: `leads:read`.","x-required-scope":"leads:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_referral_settings":{"post":{"operationId":"flyra_update_referral_settings","summary":"Change the referral program settings","tags":["Settings"],"description":"Change the referral program, like the settings on Leads > Referrals. Owner or Admin only. Only the fields you pass change.\n\nSends: While referral requests are on with a trigger, Flyra texts and/or emails each customer the referral message automatically, the set delay after their job is completed or after they leave a good review. Turning enabled on does not pick a trigger here; pass trigger_on_completion or trigger_on_review too if the user wants requests to go out. Confirm with the user before switching sending on.\n\nThe message may use {customer_name}, {customer_full_name}, {company_name}, {company_phone}, {company_email} and {referral_link}.\n\nScope: `settings:write`.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"description":"Referral requests on or off.","type":"boolean"},"trigger_on_completion":{"description":"Send after a job is completed.","type":"boolean"},"trigger_on_review":{"description":"Send after the customer leaves a review at or above review_min_rating.","type":"boolean"},"completion_delay_minutes":{"description":"Minutes after the job is completed to send: 0 (Immediately), 30 (30 minutes after), 60 (1 hour after), 120 (2 hours after), 240 (4 hours after), 720 (12 hours after), 1440 (24 hours after), 2880 (48 hours after).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"review_delay_minutes":{"description":"Minutes after the review to send: 0 (Immediately), 30 (30 minutes after), 60 (1 hour after), 120 (2 hours after), 240 (4 hours after), 720 (12 hours after), 1440 (24 hours after), 2880 (48 hours after).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"review_min_rating":{"description":"Lowest star rating that triggers a request.","type":"integer","minimum":1,"maximum":5},"referee_reward_cents":{"description":"What the referred person gets, in cents.","type":"integer","minimum":0,"maximum":1000000},"referrer_reward_cents":{"description":"What the referring customer gets, in cents.","type":"integer","minimum":0,"maximum":1000000},"gift_card_cents":{"description":"Gift card the referrer can choose instead, in cents.","type":"integer","minimum":0,"maximum":1000000},"gift_card_enabled":{"type":"boolean"},"sms_enabled":{"description":"Send the request by text.","type":"boolean"},"email_enabled":{"description":"Send the request by email.","type":"boolean"},"message":{"description":"Text of the request. Include {referral_link}.","type":"string","minLength":1,"maxLength":2000},"subject":{"description":"Email subject.","type":"string","minLength":1,"maxLength":2000}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_qr_codes":{"post":{"operationId":"flyra_list_qr_codes","summary":"List lead form QR codes","tags":["Leads"],"description":"Admin or Owner only, as lead forms are in Flyra. Every lead form with the printable QR code link for each published one (yard signs, flyers), as on Leads > QR codes. An unpublished form has no code until it is published. Listing can create the short link behind a published form's code the first time; it sends nothing.\n\nScope: `leads:read`.","x-required-scope":"leads:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_yard_signs":{"post":{"operationId":"flyra_list_yard_signs","summary":"List yard signs","tags":["Leads"],"description":"The yard signs, door hangers and flyers the business is tracking: how many signs are out, in the truck, overdue or missing, scans and leads they brought in, which sign types are tracked, the return window, the scan form's state, and each placement (address, who placed it, when it is due back, scans). The revenue figure is null for someone who sees only their own jobs, since the page would add up only theirs. A sign is placed by dropping a map pin with status yard_sign, door_hanger or flyer (flyra_create_map_pin) while that type is tracked, and removed by deleting that pin. Listing can create the printed short code for a placement that has none; it sends nothing. Placements are the first 500 the page reads, soonest due back first; `capped` is true when there may be more. The same screen is Leads > QR codes in the Flyra web app.\n\nScope: `leads:read`.","x-required-scope":"leads:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"outstanding_only":{"description":"Only signs still out (not collected).","type":"boolean"},"kinds":{"description":"Only these sign types.","type":"array","items":{"type":"string","enum":["yard_sign","door_hanger","flyer"]}},"limit":{"description":"Placements per call, default 25, maximum 50.","type":"integer","exclusiveMinimum":0,"maximum":50},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_mark_yard_sign_collected":{"post":{"operationId":"flyra_mark_yard_sign_collected","summary":"Mark a yard sign collected","tags":["Leads"],"description":"Marks a placed sign, door hanger or flyer as picked up, as the Collected button on Leads > QR codes does (a yard sign then counts as back in the truck). Pass the placement id from flyra_list_yard_signs. A sign already collected is left as it was. Sends nothing.\n\nScope: `leads:write`.","x-required-scope":"leads:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"placement_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The placement id from flyra_list_yard_signs."}},"required":["placement_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_yard_sign_type":{"post":{"operationId":"flyra_set_yard_sign_type","summary":"Turn a sign type on or off","tags":["Leads"],"description":"Starts or stops tracking one sign type (yard_sign, door_hanger, flyer) for the whole business, as the type switches in the Leads > QR codes settings do. Turning one on also adds it as a map pin type and starts sign tracking for the business. Admin only. Sends nothing.\n\nScope: `leads:write`.","x-required-scope":"leads:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["yard_sign","door_hanger","flyer"]},"enabled":{"type":"boolean"}},"required":["kind","enabled"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_yard_sign_settings":{"post":{"operationId":"flyra_update_yard_sign_settings","summary":"Update yard sign settings","tags":["Leads"],"description":"Sets how many yard signs the business owns and how many days one may stay out before it counts as overdue, as the Leads > QR codes settings drawer does. Saving with at least one sign type on also starts sign tracking. Admin only. Sends nothing.\n\nScope: `leads:write`.","x-required-scope":"leads:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"sign_count":{"description":"Yard signs the business owns.","type":"integer","minimum":0,"maximum":10000},"return_days":{"description":"Days a sign may stay out before it is overdue.","type":"integer","minimum":1,"maximum":365}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_up_yard_sign_form":{"post":{"operationId":"flyra_set_up_yard_sign_form","summary":"Set up the yard sign scan form","tags":["Leads"],"description":"The lead form people land on when they scan a sign, as the setup card on Leads > QR codes. action \"create\" makes a starter form (name + phone) and links it, unpublished; \"publish\" puts that form live on the public internet under the business's name and makes the printed code; \"skip\" stops the setup card asking. Read the form with flyra_get_lead_form before publishing. Admin only. Sends nothing.\n\nScope: `leads:write`.","x-required-scope":"leads:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["create","publish","skip"]}},"required":["action"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_lead_integrations":{"post":{"operationId":"flyra_get_lead_integrations","summary":"Read the lead integrations","tags":["Leads"],"description":"What Leads > Integrations shows: the Facebook pages connected for Meta lead forms, Meta conversion reporting (on or off, the dataset, whether an access token is saved, and which pipeline stage sends which event), the lead forms that report conversions to Google Ads, and, for Owners and Admins, the Google Ads (Local Services) connection. Tokens are never returned. Change conversion reporting with flyra_set_meta_conversion_reporting; form routing is flyra_list_meta_form_routes. Connecting Meta or Google Ads is a sign-in with them in the browser, so it cannot be done here: `connect_url` is the page to do it on (the person needs a Flyra login). After Google sign-in, pick the account with flyra_select_google_ads_account.\n\nScope: `leads:read`.","x-required-scope":"leads:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_meta_conversion_reporting":{"post":{"operationId":"flyra_set_meta_conversion_reporting","summary":"Turn Meta conversion reporting on or off and map stages","tags":["Leads"],"description":"Change Meta conversion reporting on Leads > Integrations: switch it on or off, and choose which pipeline stage sends which Meta event. Only what you pass changes; stages you leave out keep their mapping.\n\nSends: While conversion reporting is on, each time a lead moves into a mapped stage Flyra sends Meta that lead's details (email, phone, name, city, state, zip, hashed) with the event, and the job value when include_value is on. Confirm with the user before turning it on.\n\nNeeds the dataset and access token already saved in the app; this tool never takes a token. Stage ids come from flyra_get_lead_integrations.\n\nScope: `leads:write`.","x-required-scope":"leads:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"description":"Conversion reporting on or off.","type":"boolean"},"stage_mappings":{"maxItems":200,"type":"array","items":{"type":"object","properties":{"stage_id":{"type":"string","minLength":1},"event_name":{"anyOf":[{"type":"string","enum":["Lead","Contact","Schedule","Purchase"]},{"type":"null"}],"description":"The Meta event this stage sends, or null to stop the stage sending anything."},"include_value":{"description":"Send the lead's value with the event (use it on Purchase). Left out, the stage keeps what it had.","type":"boolean"}},"required":["stage_id","event_name"]}}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_leads_report":{"post":{"operationId":"flyra_leads_report","summary":"Leads by source report","tags":["Leads"],"description":"The Leads report: leads per day, and per source the leads, converted, lost, conversion rate, pipeline value, average days to close and average lifetime value (money in cents), plus totals. Filter by date range (required, up to a year), source, form or owner. The rows are the export. Someone who sees only their own leads in the app gets only their own here.\n\nScope: `leads:read`.","x-required-scope":"leads:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 with a zone, e.g. 2026-10-01T00:00:00-07:00."},"end":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO 8601 with a zone."},"source_key":{"description":"One of the `sources` keys this report returns, or \"untagged\".","type":"string"},"form_id":{"description":"Only leads from this lead form.","type":"string"},"owner":{"description":"A lead owner's user id, or \"unassigned\".","type":"string"}},"required":["start","end"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_select_google_ads_account":{"post":{"operationId":"flyra_select_google_ads_account","summary":"Choose the Google Ads account","tags":["Leads"],"description":"Owner or Admin only. After someone signs in with Google on Leads > Integrations, chooses which Local Services Ads account Flyra reads leads from, as the account picker there does. Pass an ads_customer_id from the `accounts` list flyra_get_lead_integrations returns under google_ads (digits, dashes allowed). Sends nothing.\n\nScope: `leads:write`.","x-required-scope":"leads:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"ads_customer_id":{"type":"string","minLength":1,"maxLength":20,"description":"The Google Ads customer id, e.g. 123-456-7890."}},"required":["ads_customer_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_disconnect_google_ads":{"post":{"operationId":"flyra_disconnect_google_ads","summary":"Disconnect Google Ads","tags":["Leads"],"description":"Owner or Admin only. Disconnects Google Ads (Local Services) from Flyra, as Disconnect on Leads > Integrations does: Flyra asks Google to revoke its access and removes the connection; connecting again is a Google sign-in on that page. Leads already in Flyra stay. Confirm with the user first. Sends nothing.\n\nScope: `leads:write`. Destructive: it deletes or cancels.","x-required-scope":"leads:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed disconnecting Google Ads."}},"required":["confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_create_pipeline":{"post":{"operationId":"flyra_create_pipeline","summary":"Create Pipeline","tags":["Leads"],"description":"Create a new lead pipeline. The default stages (New → Contacted → Responded → Estimate Sent → Won → Lost → No Response) and a paused \"New Lead\" automation are added automatically, as in Settings. Returns the new pipeline id.\n\nScope: `leads:write`.","x-required-scope":"leads:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60,"description":"Pipeline name, e.g. \"Commercial Leads\""}},"required":["name"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_pipeline":{"post":{"operationId":"flyra_update_pipeline","summary":"Update Pipeline","tags":["Leads"],"description":"Rename or reorder a pipeline, flip it to default, or claim lead source routing for it.\n\nScope: `leads:write`.","x-required-scope":"leads:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Pipeline semantic id or raw UUID"},"name":{"description":"New name","type":"string","maxLength":60},"position":{"description":"New position integer","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"is_default":{"description":"true makes this the default pipeline (unsets the others). false changes nothing; make another pipeline the default instead.","type":"boolean"},"default_for_sources":{"description":"Lead source codes that auto-route to this pipeline. A source another pipeline holds moves to this one.","type":"array","items":{"type":"string"}}},"required":["id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_delete_pipeline":{"post":{"operationId":"flyra_delete_pipeline","summary":"Delete Pipeline","tags":["Leads"],"description":"Delete a pipeline. Supply move_to (another pipeline of this company) if the pipeline has leads: they move there, keeping their stage when the destination has a stage of that name and landing in its first stage otherwise. Deleting the default pipeline makes the destination the default.\n\nScope: `leads:write`. Destructive: it deletes or cancels.","x-required-scope":"leads:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Pipeline semantic id or raw UUID to delete"},"move_to":{"description":"Pipeline semantic id or raw UUID to move its leads into","type":"string"}},"required":["id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_pipeline_stages":{"post":{"operationId":"flyra_list_pipeline_stages","summary":"List Pipeline Stages","tags":["Leads"],"description":"List all stages for a pipeline in position order.\n\nScope: `leads:read`.","x-required-scope":"leads:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"pipeline_id":{"description":"Pipeline semantic id or raw UUID. Defaults to the org default pipeline.","type":"string"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_pipeline_stages":{"post":{"operationId":"flyra_update_pipeline_stages","summary":"Update Pipeline Stages","tags":["Leads"],"description":"Bulk replace all stages for a pipeline. Pass the full list; it is saved in position order. Keep an existing stage by passing its id; a renamed stage carries its leads and the automations that name it. Leads in removed stages move to the first stage.\n\nScope: `leads:write`.","x-required-scope":"leads:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"pipeline_id":{"type":"string","description":"Pipeline semantic id or raw UUID"},"stages":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"id":{"description":"Existing stage semantic id or UUID; omit for new stages","type":"string"},"name":{"type":"string","description":"Slug — lowercase letters, numbers, underscores only; unique in the pipeline"},"label":{"type":"string","description":"Display name shown in the UI"},"color":{"description":"Hex color e.g. #3b82f6","type":"string"},"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"0-based position"}},"required":["name","label","position"]}}},"required":["pipeline_id","stages"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_create_pipeline_stage":{"post":{"operationId":"flyra_create_pipeline_stage","summary":"Create Pipeline Stage","tags":["Leads"],"description":"Add a single new stage to a pipeline. Appended after the last existing stage.\n\nScope: `leads:write`.","x-required-scope":"leads:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"pipeline_id":{"type":"string","description":"Pipeline semantic id or raw UUID"},"name":{"type":"string","description":"Slug — lowercase letters, numbers, underscores only"},"label":{"type":"string","description":"Display label shown in the UI"},"color":{"description":"Hex color e.g. #3b82f6","type":"string"}},"required":["pipeline_id","name","label"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_pipeline_stage_outcome":{"post":{"operationId":"flyra_set_pipeline_stage_outcome","summary":"Mark a pipeline's Won or Lost stage","tags":["Leads"],"description":"Marks a stage as its pipeline's Won or Lost stage, or clears the mark. A lead moved into the marked Lost stage counts as lost (the lead.lost automation trigger fires and its status becomes lost), and the marked Won stage counts as won, whatever the stage is named. Each pipeline has at most one Won and one Lost stage: marking a stage clears that mark from the pipeline's other stage. Stages named won or lost were marked already. See flyra_list_pipeline_stages for each stage's outcome.\n\nScope: `leads:write`.","x-required-scope":"leads:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"stage_id":{"type":"string","description":"Stage semantic id or raw UUID from flyra_list_pipeline_stages"},"outcome":{"anyOf":[{"type":"string","enum":["won","lost"]},{"type":"null"}],"description":"won, lost, or null to clear the mark"}},"required":["stage_id","outcome"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_delete_pipeline_stage":{"post":{"operationId":"flyra_delete_pipeline_stage","summary":"Delete Pipeline Stage","tags":["Leads"],"description":"Remove a stage from a pipeline. Leads in that stage are migrated to the first remaining stage.\n\nScope: `leads:write`. Destructive: it deletes or cancels.","x-required-scope":"leads:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Stage semantic id or raw UUID"}},"required":["id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_custom_roles":{"post":{"operationId":"flyra_list_custom_roles","summary":"List Custom Roles","tags":["Employees"],"description":"List all custom employee roles defined for this org, including their permission sets.\n\nScope: `employees:read`.","x-required-scope":"employees:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_create_custom_role":{"post":{"operationId":"flyra_create_custom_role","summary":"Create Custom Role","tags":["Employees"],"description":"Create a new custom employee role with a specific permission set. Sales Rep and Technician permissions are built in and cannot be changed; as the Roles screen does, give their people more (the Map, say) with a custom role started from one: copy_of plus the permissions to change, then move each person to it with flyra_set_employee_role and set what it sees with flyra_set_role_access.\n\nScope: `employees:write`.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60,"description":"Role name, e.g. \"Field Supervisor\""},"copy_of":{"description":"Start from this built-in role's permissions; the keys sent in permissions replace its values.","type":"string","enum":["sales_rep","technician"]},"color":{"description":"Hex color for the role badge, e.g. \"#f59e0b\"","type":"string"},"permissions":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"boolean"},"description":"EmployeePermissions object: keys map to boolean. At least one must be true. Keys and what they open: can_view_schedule (the Schedule page; which jobs it shows is flyra_set_role_access schedule), can_view_all_jobs (every job, and the Leads section), can_add_jobs, can_edit_jobs, can_update_assigned_jobs, can_dispatch_employees, can_view_leads (the Leads section and its pipeline), can_view_customers (the Customers page), can_manage_customers, can_view_messages (the Inbox), can_create_estimates, can_view_map (the Map page), can_view_markers (pins on it), can_view_territory, can_edit_territory, can_view_reports, can_view_leaderboards, can_view_inventory, can_manage_inventory, can_manage_team, can_view_company_settings, can_issue_refunds, can_edit_agreement_terms. Keys outside this list (can_view_jobs, can_view_invoices, can_send_messages and the like) are saved but grant nothing."}},"required":["name","permissions"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_custom_role":{"post":{"operationId":"flyra_update_custom_role","summary":"Update Custom Role","tags":["Employees"],"description":"Update a custom role name, color, and/or permissions. Updated permissions cascade to all employees assigned this role.\n\nScope: `employees:write`.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Role semantic id or raw UUID"},"name":{"description":"New name","type":"string","minLength":1,"maxLength":60},"color":{"description":"New hex color","type":"string"},"permissions":{"description":"Full EmployeePermissions replacement object: send every key the role keeps, not only the changed ones. Keys and what they open: can_view_schedule (the Schedule page; which jobs it shows is flyra_set_role_access schedule), can_view_all_jobs (every job, and the Leads section), can_add_jobs, can_edit_jobs, can_update_assigned_jobs, can_dispatch_employees, can_view_leads (the Leads section and its pipeline), can_view_customers (the Customers page), can_manage_customers, can_view_messages (the Inbox), can_create_estimates, can_view_map (the Map page), can_view_markers (pins on it), can_view_territory, can_edit_territory, can_view_reports, can_view_leaderboards, can_view_inventory, can_manage_inventory, can_manage_team, can_view_company_settings, can_issue_refunds, can_edit_agreement_terms. Keys outside this list (can_view_jobs, can_view_invoices, can_send_messages and the like) are saved but grant nothing.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"boolean"}}},"required":["id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_delete_custom_role":{"post":{"operationId":"flyra_delete_custom_role","summary":"Delete Custom Role","tags":["Employees"],"description":"Delete a custom role. Blocked if any employee is currently assigned this role.\n\nScope: `employees:write`. Destructive: it deletes or cancels.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Role semantic id or raw UUID"}},"required":["id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_phone_provisioning":{"post":{"operationId":"flyra_get_phone_provisioning","summary":"Get Phone Provisioning Status","tags":["Employees"],"description":"Return the org phone number, provisioning status (active / purchased_pending_10dlc / no_phone), assigned SMS campaign id, and whether SMS is ready to send. Also returns connected_apps_url, the page where an Admin connects Quo or Blooio (iMessage) for texting.\n\nScope: `employees:read`.","x-required-scope":"employees:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_submit_business_verification":{"post":{"operationId":"flyra_submit_business_verification","summary":"Register the business for texting with the carriers","tags":["Settings"],"description":"Register this business with AT&T, T-Mobile and Verizon for texting (A2P 10DLC), as the Claim my number button under \"Claim your business number\" in Flyra does, for a registered business with an EIN. It saves the legal name, EIN, website, email, phone and address on the business, checks the website, then files the business with the carriers. MONEY: when this business is on the carrier setup fee (status.fee.enabled, and status.fee.simulated false), it charges a one-time $25 to the Flyra billing card on file before filing. It is not refundable, and a corrected resubmission after the carriers refuse the details is another $25. A branch with the same EIN as its parent is covered by the parent and is not charged. Tell the user about the $25 and get their yes before calling. Only while the registration is unsubmitted or rejected: when it is pending, awaiting a code or verified, it is refused with the current state and nothing is filed or charged. A refusal returns ok false, the reason, code (which refusal), field (the detail to fix, if any) and fee_charged. Most refusals come before any charge: a missing or wrong detail, the plan not active, the carriers already refused these exact details, a review already running, the website failing the check, or a card that cannot be charged. One can come after the $25 is taken (code compliance_missing, Flyra could not complete the filing): fee_charged is true then. If the call fails partway (code outcome_unknown), whether the details were filed or the $25 was charged is unknown: do not submit again until the state has been checked. Returns ok and the verification status (state: unsubmitted, awaiting_code, pending, verified or rejected). The review usually takes a few minutes. A sole proprietor (no EIN) registers in Flyra instead, because the carriers text the owner a code that is entered there. Sends no message to customers. Admins only; needs a signed-in person, not an organization API key.\n\nScope: `settings:write`. Destructive: it deletes or cancels.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"legal_business_name":{"type":"string","description":"The legal business name exactly as on the EIN letter (CP 575), with LLC, Inc or Corp."},"ein":{"type":"string","description":"The 9-digit EIN, e.g. 82-4613892."},"website":{"type":"string","description":"The full website address, starting with https://. The carriers open it to see who is texting."},"email":{"type":"string","description":"The business email."},"phone":{"type":"string","description":"The 10-digit business phone number."},"address":{"type":"string","description":"The business street address, as the IRS has it."},"city":{"type":"string","description":"The business city."},"state":{"type":"string","description":"The 2-letter state, e.g. AZ."},"zip":{"type":"string","description":"The ZIP code."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has agreed to the registration and to the $25 carrier setup fee if it applies."}},"required":["legal_business_name","ein","website","email","phone","address","city","state","zip","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_org_settings":{"post":{"operationId":"flyra_get_org_settings","summary":"Get org settings","tags":["Settings"],"description":"The org's core settings: name, address, phone, website, timezone, currency, country, locale, tax rates, review_link, business hours (business_hours_start/end, business_days, business_hours_by_day per weekday), job defaults (minimum price, duration, minimum booking notice: `minimum_notice_days` is in HOURS), default_arrival_window_minutes, dispatch and payroll toggles, `subscriptions_enabled`, map_provider, supply_tracking_enabled/required, and `estimate_display_terms` (null if unreadable). Also `estimateDefaults` (Settings > Documents > Estimate defaults: terms, deposit, require signature, self-scheduling; null if unsaved or unreadable; its terms are set by flyra_update_org_settings estimate_default_terms) and `preferences` (Settings > Preferences: complaints, location tracking hours, quality checks and photo boxes; null if unreadable). Read it before updating settings or using its timezone/currency. `browser_connections`: where an Admin connects accounting and iMessage apps; never take an API key in chat.\n\nScope: `settings:read`.","x-required-scope":"settings:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_billing_plan":{"post":{"operationId":"flyra_get_billing_plan","summary":"Get the Flyra plan","tags":["Settings"],"description":"Settings > Billing: this company's own Flyra plan as Stripe bills it (status, plan name and price per period, extra lines, discounts with end dates, the next charge with its date, amount, tax and credit, a scheduled plan change, end, pause and trial dates; summary is null when the company has no Stripe subscription), its locations' prices, and seats as that page counts them (active team members who accepted their invite, of the plan's included seats; included is null when the plan sets none). Admins only, and needs a signed-in Flyra user. Read only: it changes nothing in Flyra or Stripe.\n\nScope: `settings:read`.","x-required-scope":"settings:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_org_settings":{"post":{"operationId":"flyra_update_org_settings","summary":"Update org settings","tags":["Settings"],"description":"Change the org's core settings; send only what changes. Admin role required. Fields: name, address, phone, website, timezone, currency, locale, country, tax number, logo_url, review_link (the Google review link), business hours (business_hours_start/end, or business_hours_by_day per weekday), minimum job price (cents), minimum and default job duration (minutes), minimum booking notice (`minimum_notice_days`, in HOURS), dispatch/payroll/schedule toggles, estimate_display_terms. tax_rates: the full list, each existing rate with its `id`; rates left out are retired, not deleted. estimate_default_*: the estimate defaults; terms are replaced in full. Settings > Preferences: default_arrival_window_minutes, location_tracking, quality_checks, quality_check_shots, supply_tracking, map_provider, job_signatures_enabled, job_signature_terms, appointments_enabled, default_line_item_unit. mockups_enabled: the reps switch on Settings > Organization. Who can see customers is flyra_set_role_access.\n\nScope: `settings:write`.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"Organization name","type":"string","minLength":1,"maxLength":100},"phone":{"description":"Organization phone number. A blank does not clear a saved value.","type":"string"},"website":{"description":"Organization website URL. A blank does not clear a saved value.","type":"string"},"email":{"description":"Organization contact email. A blank does not clear a saved value.","type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"address":{"description":"Street address. A blank does not clear a saved value.","type":"string"},"unit":{"description":"Unit or suite number","type":"string"},"city":{"description":"City. A blank does not clear a saved value.","type":"string"},"state":{"description":"State or province. A blank does not clear a saved value.","type":"string"},"zip":{"description":"ZIP or postal code. A blank does not clear a saved value.","type":"string"},"country":{"description":"Country code: \"us\", \"ca\", or \"au\"","type":"string"},"timezone":{"description":"IANA timezone, e.g. \"America/New_York\". A zone Flyra cannot read is refused.","type":"string"},"currency":{"description":"ISO 4217 currency code: \"usd\", \"cad\", or \"aud\"","type":"string"},"locale":{"description":"Language: \"en\" or \"fr\". Anything else is stored as \"en\", as the app stores it.","type":"string"},"logo_url":{"description":"URL to the org logo image","type":"string","format":"uri"},"tax_number":{"description":"Tax / business number, checked and formatted for the country as Settings > Organization does (a U.S. EIN has 9 digits). A blank does not clear a saved value.","type":"string"},"tax_number_type":{"description":"Tax number type: us_ein, ca_bn, ca_gst_hst, ca_payroll, ca_corp, ca_import_export or au_abn. In Australia an 11-digit ABN is stored as au_abn; elsewhere outside Canada it is stored as us_ein.","type":"string"},"business_hours_start":{"description":"Business hours open time, e.g. \"08:00\"","type":"string"},"business_hours_end":{"description":"Business hours close time, e.g. \"18:00\"","type":"string"},"business_days":{"description":"Array of open days, e.g. [\"monday\",\"tuesday\",...]","type":"array","items":{"type":"string"}},"business_hours_by_day":{"description":"Hours for each weekday, keyed by lowercase day name (monday ... sunday). A day listed here uses its own start and end instead of business_hours_start/end. The whole map is replaced on every call: pass every day that should keep its own hours, because a day left out goes back to the shared hours. business_days still decides which days are open at all. Pass null to go back to one set of hours for every day. Example: { \"monday\": { \"start\": \"09:00\", \"end\": \"21:00\" }, \"saturday\": { \"start\": \"09:00\", \"end\": \"19:00\" } }","anyOf":[{"type":"object","propertyNames":{"type":"string","enum":["monday","tuesday","wednesday","thursday","friday","saturday","sunday"]},"additionalProperties":{"type":"object","properties":{"start":{"type":"string","pattern":"^(?:[01]\\d|2[0-3]):[0-5]\\d$","description":"Opening time, 24-hour HH:MM, e.g. \"09:00\""},"end":{"type":"string","pattern":"^(?:[01]\\d|2[0-3]):[0-5]\\d$","description":"Closing time, 24-hour HH:MM, e.g. \"21:00\". \"00:00\" is midnight at the end of the day"},"enabled":{"description":"false closes that day even when it has times. Omitted means open","type":"boolean"}},"required":["start","end"]}},{"type":"null"}]},"minimum_notice_days":{"description":"Minimum booking notice in HOURS (the column name says days — it stores hours). Must be one of: 0, 6, 12, 24, 72, 120. 0 means no minimum.","type":"integer","minimum":0,"maximum":9007199254740991},"minimum_job_price_cents":{"description":"Minimum job price in cents","type":"integer","minimum":0,"maximum":9007199254740991},"minimum_job_length_minutes":{"description":"Minimum job duration in minutes","type":"integer","minimum":0,"maximum":9007199254740991},"default_job_duration_minutes":{"description":"Default job duration in minutes, kept between 15 and 1440 as the app keeps it","type":"integer","minimum":0,"maximum":9007199254740991},"default_arrival_window_minutes":{"description":"The arrival window new jobs start with, in minutes (the customer is told the crew arrives within it). null = an exact time. Admin only","anyOf":[{"type":"integer","minimum":15,"maximum":720},{"type":"null"}]},"dispatch_only_technicians":{"description":"Restrict dispatch to Technician role employees only","type":"boolean"},"salesperson_only_sales_reps":{"description":"Restrict sales attribution to Sales Rep role only","type":"boolean"},"hide_cancelled_on_schedule":{"description":"Hide cancelled jobs from the schedule view","type":"boolean"},"hide_pricing_from_employees":{"description":"Hide job pricing from non-admin employees","type":"boolean"},"dispatch_notifications_enabled":{"description":"Email employees when they are dispatched to a job. false = the \"Don't email employees when they're dispatched to a job\" box in Settings > Preferences: the dispatch email is skipped","type":"boolean"},"scope_employees_to_assigned_jobs":{"description":"Legacy flag with no effect on an existing company. To change which jobs or customers a role sees, use flyra_set_role_access.","type":"boolean"},"review_link":{"description":"The Google review link review requests send customers to (Settings > Organization). Saved as the app saves it: a Google Maps or g.page link becomes Google's write-a-review link where it can, an empty string clears it, and the Google rating shown in Flyra is re-read. Admin only","type":"string"},"review_star_minimum":{"description":"Minimum star rating to show review link (review gate)","type":"integer","minimum":1,"maximum":5},"disable_review_gate":{"description":"Disable the review star gate (always show review link)","type":"boolean"},"subscriptions_enabled":{"description":"Whether the org sells subscriptions. false hides Subscription from the Create menu and the Create Subscription buttons on the web; plans already on the books keep billing and stay visible","type":"boolean"},"estimate_display_terms":{"description":"Show the terms and conditions on estimates: on the public estimate link the customer opens, and on the PDF. The \"Show terms\" switch in Settings > Documents. false hides them even on an estimate that has terms written.","type":"boolean"},"job_signatures_enabled":{"description":"The \"Enable job signatures\" box in Settings > Preferences: collect a customer signature on a job from the mobile app. Admin only","type":"boolean"},"job_signature_terms":{"description":"The terms and conditions shown with a job signature (Settings > Preferences > Job signatures). Replaced in full; trimmed, and an empty string or null clears it. Admin only","anyOf":[{"type":"string","maxLength":20000},{"type":"null"}]},"appointments_enabled":{"description":"Appointments (quote visits) on or off, as the Settings > Preferences switch. false hides the booking actions and nothing else. Admin only","type":"boolean"},"default_line_item_unit":{"description":"What a blank line item on a job, estimate or invoice starts as (Settings > Preferences > Line items): null = Qty (a plain count), \"sq ft\" or \"linear ft\" (\"sqm\" or \"linear m\" for metric orgs). \"each\" and an empty string are stored as null, as the app stores them. Admin only","anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"estimate_default_terms":{"description":"The default terms and conditions text printed on new estimates (Settings > Documents > Estimate defaults). Free text, replaced in full: send the whole new text, not just the changed part. An empty string is stored and the app then prints its shipped default terms","type":"string","maxLength":20000},"estimate_default_deposit_required":{"description":"Whether new estimates require a deposit by default (Settings > Documents > Estimate defaults)","type":"boolean"},"estimate_default_require_signature":{"description":"The \"Require customer signature on approval by default\" box in Settings > Preferences > Estimates: new estimates start asking the customer to sign when they approve. Admin only","type":"boolean"},"estimate_default_deposit_percent":{"description":"Default deposit percent for new estimates, a whole number from 0 to 100 (Settings > Documents > Estimate defaults)","type":"integer","minimum":0,"maximum":100},"tax_rates":{"description":"Full replacement list of tax rates for the org. Include each existing rate's `id` (from flyra_get_org_settings) so it is updated in place instead of replaced.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"name":{"type":"string"},"rate_percent":{"type":"number"},"is_default":{"type":"boolean"},"is_active":{"type":"boolean"}},"required":["name","rate_percent","is_default","is_active"]}},"review_on_receipt_enabled":{"description":"The \"Collect reviews after invoices\" switch on Settings > Organization. Turning it on sends customers a review request after their invoice or receipt, so it needs confirm: true, and it needs a review link saved (review_link) as the screen does. Admins and Owners only, as a signed-in user","type":"boolean"},"estimate_allow_customer_self_schedule":{"description":"Customer self scheduling on estimates: the opposite of the \"Disable customer self scheduling\" box in Settings > Preferences > Estimates. Turning it on lets a customer who accepts an estimate pick their own visit time on the estimate link; the job is booked from that pick and the job confirmation email and text go to that customer, so it needs confirm: true. Admins and Owners only, as a signed-in user","type":"boolean"},"confirm":{"description":"Must be true when turning review_on_receipt_enabled or estimate_allow_customer_self_schedule on: both make Flyra message customers.","type":"boolean","const":true},"customer_complaints":{"description":"Customer complaints on job notes. Not shown in Settings. Off unless Flyra turned it on for this company. Admin or Owner.","type":"object","properties":{"enabled":{"description":"Customer complaints on job pages","type":"boolean"},"technician_access":{"description":"Technicians may log complaints and see the ones that name them","type":"boolean"}}},"location_tracking":{"description":"The hours live location tracking records the team, in the org timezone. Admin only.","type":"object","properties":{"background_enabled":{"description":"Record team locations in the background, during the hours below","type":"boolean"},"days":{"minItems":1,"type":"array","items":{"type":"string","enum":["sunday","monday","tuesday","wednesday","thursday","friday","saturday"]}},"start":{"type":"string","description":"24-hour HH:MM"},"end":{"description":"24-hour HH:MM. Same as start means all day","type":"string"}}},"quality_checks":{"description":"Settings > Preferences > Quality checks (the before/after photos a tech submits). Admin or Owner.","type":"object","properties":{"enabled":{"type":"boolean"},"required":{"description":"A job cannot close without its check. Off when checks are off","type":"boolean"},"hold_payroll":{"description":"Hold the job from payroll until the check is in. Only with required","type":"boolean"},"require_video":{"description":"The check needs a video. Only with required","type":"boolean"},"instructions":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"quality_check_shots":{"description":"The quality check photo boxes, the whole list in order: a box left out is removed from new checks (past jobs keep it). Admin or Owner.","maxItems":12,"type":"array","items":{"type":"object","properties":{"id":{"description":"An existing box from flyra_get_org_settings; omit for a new one","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"label":{"type":"string","minLength":1,"maxLength":60},"instructions":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"kind":{"type":"string","enum":["photo","video","either"]},"required":{"type":"boolean"},"role":{"description":"At most one before and one after box","anyOf":[{"type":"string","enum":["before","after"]},{"type":"null"}]}},"required":["label"]}},"supply_tracking":{"description":"Settings > Preferences > Jobs: supply tracking. Admin or Owner.","type":"object","properties":{"enabled":{"description":"The \"Track supplies used on jobs\" box: a supplies card on every job; saving the card subtracts what it used from inventory","type":"boolean"},"required":{"description":"A job cannot be marked complete until someone confirms its supplies. Off when tracking is off","type":"boolean"}}},"map_provider":{"description":"Settings > Preferences > Map > Default map, for the team on web and iOS. apple is the iPhone app's map (the web draws Mapbox for it). A rep's own pick on their device still wins. Admin only.","type":"string","enum":["apple","mapbox","google"]},"mockups_enabled":{"description":"The \"Mockups on for your reps\" switch on Settings > Organization > Lights mockups: shows or hides the Mockup button for reps. Only where that page shows the switch (the add-on is included, or bought and not cancelled). It never buys or cancels the add-on, and off does not stop its billing. Admin only.","type":"boolean"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_email_settings":{"post":{"operationId":"flyra_get_email_settings","summary":"Get email settings","tags":["Settings"],"description":"Returns the org's outbound email configuration: custom inbox handle (e.g. \"acme\" → acme@mail.flyra.io), brand color used in email templates, whether to include the org logo in emails, reply-to mode (flyra address vs external address), and the external reply-to address if set. Use this when a user asks about their email branding or reply-to configuration.\n\nScope: `settings:read`.","x-required-scope":"settings:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_email_settings":{"post":{"operationId":"flyra_update_email_settings","summary":"Update email settings","tags":["Settings"],"description":"Updates the org's outbound email configuration. Pass only the fields to change. email_handle is the subdomain prefix for the org's Flyra inbox (e.g. \"acme\" → acme@mail.flyra.io) — must be lowercase alphanumeric with dots/hyphens/underscores, 2–63 chars, unique. email_reply_to_mode is \"flyra\" (default) or \"external\". Admin role required.\n\nScope: `settings:write`.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"email_handle":{"description":"Inbox handle, e.g. \"acme\". null to clear.","anyOf":[{"type":"string","minLength":2,"maxLength":63,"pattern":"^[a-z0-9._-]+$"},{"type":"null"}]},"email_brand_color":{"description":"Brand color hex code used in email templates, e.g. \"#57cdff\". null to clear.","anyOf":[{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},{"type":"null"}]},"email_include_logo":{"description":"Whether to show the org logo in outbound emails","type":"boolean"},"email_reply_to_mode":{"description":"\"flyra\" = replies go to the Flyra inbox, \"external\" = replies go to email_reply_to_external","type":"string","enum":["flyra","external"]},"email_reply_to_external":{"description":"External reply-to email address, used when email_reply_to_mode is \"external\". null to clear.","anyOf":[{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"null"}]}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_message_settings":{"post":{"operationId":"flyra_get_message_settings","summary":"Get automated message settings","tags":["Settings"],"description":"Returns all automated SMS/email notification settings for the org: job lifecycle messages (confirmation, on-the-way, arrival, start, finish, cancellation, reschedule), invoice reminders (up to 5 follow-ups), estimate follow-ups, subscription approval links, review requests, and the welcome email. Each setting has an _enabled toggle, optional _email_enabled toggle, a _message template (SMS), and a _subject (email). Use this when a user asks about automated messages, reminder sequences, or notification templates.\n\nScope: `settings:read`.","x-required-scope":"settings:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_message_settings":{"post":{"operationId":"flyra_update_message_settings","summary":"Update automated message settings","tags":["Settings"],"description":"Partially updates the org's automated SMS/email notification settings. Pass only the keys you want to change. Key naming pattern: {trigger}_{property}, e.g. \"job_creation_enabled\", \"job_creation_message\", \"job_creation_subject\", \"invoice_followup_1_enabled\", \"review_message_enabled\". Setting a followup _enabled to false will also cancel any pending queued messages for that step. Switching any _enabled or auto_send setting on makes Flyra message customers, so it needs confirm: true. Use flyra_get_message_settings first to see all available keys and current values.\n\nScope: `settings:write`.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"settings":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"boolean"},{"type":"string"},{"type":"number"}]},"description":"Object of message setting keys to update, e.g. { \"job_creation_enabled\": true, \"job_creation_message\": \"Hi {first_name}, your job is confirmed for {job_date}.\" }. All values are optional — only provided keys are changed."},"confirm":{"description":"Must be true when switching any _enabled or auto_send setting on: Flyra then texts or emails customers automatically.","type":"boolean","const":true}},"required":["settings"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_payment_methods":{"post":{"operationId":"flyra_list_payment_methods","summary":"List accepted payment methods","tags":["Settings"],"description":"Returns the org's configured list of accepted payment methods (e.g. Cash, Credit Card, Check, E-Transfer, etc.) with their id, name, code, sort_order, and is_active status. Use this when a user asks what payment methods they accept, or before creating/updating payment methods. \"Other\" is always pinned last.\n\nScope: `settings:read`.","x-required-scope":"settings:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_create_payment_method":{"post":{"operationId":"flyra_create_payment_method","summary":"Create a payment method","tags":["Settings"],"description":"Adds a new accepted payment method option to the org (e.g. \"Bank Transfer\", \"Zelle\", \"E-Transfer\"). The code is auto-derived from the name if not provided (slugified: lowercase, alphanumeric and hyphens, max 40 chars). Fails if an ACTIVE method already has that name or code. If a removed method had it, that row is restored instead of creating a duplicate.\n\nScope: `settings:write`.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Display name for the payment method, e.g. \"Bank Transfer\""},"code":{"description":"Slug/code identifier, e.g. \"bank-transfer\". Auto-derived from name if omitted.","type":"string","maxLength":40}},"required":["name"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_payment_method":{"post":{"operationId":"flyra_update_payment_method","summary":"Update a payment method","tags":["Settings"],"description":"Updates an existing payment method. Can rename it, change its sort_order, or toggle is_active. Pass only the fields to change. Use flyra_list_payment_methods to get the id first.\n\nScope: `settings:write`.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"The UUID of the payment method to update"},"name":{"description":"New display name","type":"string","minLength":1,"maxLength":100},"is_active":{"description":"Whether this payment method is active and shown to users","type":"boolean"},"sort_order":{"description":"Sort position (lower = shown first)","type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_delete_payment_method":{"post":{"operationId":"flyra_delete_payment_method","summary":"Delete a payment method","tags":["Settings"],"description":"Removes a payment method option from the org. Use flyra_list_payment_methods to get the id. The method is archived, not erased: it stops being offered when recording payments, and payments already recorded with it keep showing its name. flyra_list_payment_methods still returns it with is_active false, and flyra_update_payment_method can turn it back on with is_active true.\n\nScope: `settings:write`. Destructive: it deletes or cancels.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"The UUID of the payment method to delete"}},"required":["id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_role_access":{"post":{"operationId":"flyra_get_role_access","summary":"Get what each role can see","tags":["Settings"],"description":"Lists every role (Sales Rep, Technician, and each custom role) with what it sees: its schedule, its customers and messages, and text alerts. Use this before flyra_set_role_access, or when someone asks why an employee can or cannot see a job, a customer, or a text thread.\n\nEach role has two independent choices:\n- schedule: which jobs are on their schedule. \"own\" = jobs they are dispatched or routed to (or created), \"own_and_sold\" = those plus jobs they sold, \"all\" = every job in the company.\n- customers: which customers they can open, and therefore which customers' text threads they see in the inbox. \"own\" = customers they created, sold to, or work on; \"all\" = every customer.\nEvery role has text_alerts: whether its people are notified when one of the customers they can see texts in. For a custom role it is on by default when the role can read messages, and it can only be turned on for a role that can read messages.\nEvery role also has sale_alerts: whether its people are notified when anyone in the company sells a plan (off unless an admin turns it on).\nThis sets which jobs and customers, not which pages open: a custom role opens the Schedule page only with can_view_schedule, and the Leads section only with can_view_leads (or can_view_all_jobs), set with flyra_update_custom_role.\nAdmins and owners always see everything and are not listed.\nExample: reps who dispatch from the whole schedule but only read their own customers' texts = schedule \"all\", customers \"own\".\n\nschedule_is_explicit=false means the role never chose a schedule and the value shown is what the older settings resolve to today.\n\nScope: `settings:read`.","x-required-scope":"settings:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_role_access":{"post":{"operationId":"flyra_set_role_access","summary":"Change what a role can see","tags":["Settings"],"description":"Changes what one role sees. Send only the fields you want to change. Takes effect immediately on web and iOS for everyone in that role.\n\nEach role has two independent choices:\n- schedule: which jobs are on their schedule. \"own\" = jobs they are dispatched or routed to (or created), \"own_and_sold\" = those plus jobs they sold, \"all\" = every job in the company.\n- customers: which customers they can open, and therefore which customers' text threads they see in the inbox. \"own\" = customers they created, sold to, or work on; \"all\" = every customer.\nEvery role has text_alerts: whether its people are notified when one of the customers they can see texts in. For a custom role it is on by default when the role can read messages, and it can only be turned on for a role that can read messages.\nEvery role also has sale_alerts: whether its people are notified when anyone in the company sells a plan (off unless an admin turns it on).\nThis sets which jobs and customers, not which pages open: a custom role opens the Schedule page only with can_view_schedule, and the Leads section only with can_view_leads (or can_view_all_jobs), set with flyra_update_custom_role.\nAdmins and owners always see everything and are not listed.\nExample: reps who dispatch from the whole schedule but only read their own customers' texts = schedule \"all\", customers \"own\".\n\nrole is \"sales_rep\", \"technician\", or a custom role id from flyra_get_role_access. Confirm the change with the user before calling: widening a role lets its members see other people's customers or jobs.\n\nScope: `settings:write`.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","description":"\"sales_rep\", \"technician\", or a custom role id"},"schedule":{"type":"string","enum":["own","own_and_sold","all"]},"customers":{"type":"string","enum":["own","all"]},"text_alerts":{"description":"any role; a custom role must be able to read messages","type":"boolean"},"sale_alerts":{"description":"The \"Notify about plan sales\" switch: true notifies everyone on the role whenever anyone in the company sells a plan.","type":"boolean"},"edit_agreement_terms":{"description":"The \"Edit agreement terms\" switch: true lets the role change a plan's terms, billing text and guarantees; false keeps plans on the template's.","type":"boolean"},"dispatch_employees":{"description":"The \"Dispatch employees\" switch: true lets the role choose who is dispatched on jobs and subscriptions; false leaves that to admins.","type":"boolean"},"skip_live_location":{"description":"The \"Share live location on the way\" switch, INVERTED: skip_live_location true = that switch OFF (they can tap On my way without sharing their location); false = switch ON (On my way needs location set to Always, and the customer gets the live link).","type":"boolean"},"skip_on_my_way_text":{"description":"The \"Text the customer On my way\" switch, INVERTED: skip_on_my_way_text true = that switch OFF (they can untick the On my way text or skip On my way); false = switch ON (On my way always texts the customer, and a Scheduled job cannot go straight to Arrived, Started or Completed).","type":"boolean"},"map_all_customers":{"description":"The \"All customers on the map\" switch, for a role with Limited customer access: true shows every customer on the map, the ones they cannot open by name only; false shows only their own.","type":"boolean"},"leaderboard":{"description":"The \"Company leaderboard\" choice: which leaderboard the role sees on the Leaderboard page and the dashboard card. Admins always see both.","type":"string","enum":["off","sales","technician","both"]}},"required":["role"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_role_sidebars":{"post":{"operationId":"flyra_get_role_sidebars","summary":"Get each role's sidebar and + Create menu","tags":["Settings"],"description":"Settings > Team > Access, Admin only: every role that has a saved layout, with item_order (sidebar order), hidden_items (sidebar items it hides) and hidden_create_items (+ Create menu options it hides).\nA role with no saved layout is not listed: it shows the sidebar in its default order with default_hidden_items hidden.\nsidebar_items and create_menu_options are the ids these lists take, with their labels. This only arranges what a role sees; it never grants or takes away access. Read only.\n\nScope: `settings:read`.","x-required-scope":"settings:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_role_sidebar":{"post":{"operationId":"flyra_set_role_sidebar","summary":"Set a role's sidebar and + Create menu","tags":["Settings"],"description":"The Save button on Settings > Team > Access, Admin only: saves one role's sidebar order, the sidebar items it hides, and the + Create menu options it hides. It only arranges the menus; it never grants or takes away access.\nSend the whole lists, as the screen does: item_order replaces the saved order and hidden_items replaces the hidden set, so an id left out of hidden_items shows. Leave hidden_create_items out to keep the saved + Create choice.\nIds come from flyra_get_role_sidebars; an id that is not a sidebar item or + Create option is dropped, as the screen's save drops it. role is \"admin\", \"sales rep\", \"technician\" or a custom role id from flyra_list_custom_roles. Returns the saved layout. Time Tracking access is not set here.\n\nScope: `settings:write`.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","minLength":1,"description":"\"admin\", \"sales rep\", \"technician\", or a custom role id"},"item_order":{"maxItems":200,"type":"array","items":{"type":"string"},"description":"Sidebar item ids, top to bottom"},"hidden_items":{"maxItems":200,"type":"array","items":{"type":"string"},"description":"Sidebar item ids this role does not see in its sidebar"},"hidden_create_items":{"description":"+ Create menu option ids this role does not see; omit to keep the saved choice","maxItems":50,"type":"array","items":{"type":"string"}}},"required":["role","item_order","hidden_items"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_api_keys":{"post":{"operationId":"flyra_list_api_keys","summary":"List API keys","tags":["Settings"],"description":"Settings > Developer > API keys: the business's active (not revoked) API keys, newest first, with name, key_prefix (the first 16 characters, enough to tell keys apart), mode, scopes (null = full access), expires_at, created_at, created_by and when and from where each was last used. The secret key itself is never returned; Flyra only keeps a hash of it.\nAny active member can list, as on the screen. can_manage says whether the caller may revoke (Admins only). Needs a signed-in user; an organization API key is refused. Read only.\n\nScope: `settings:read`.","x-required-scope":"settings:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_revoke_api_key":{"post":{"operationId":"flyra_revoke_api_key","summary":"Revoke an API key","tags":["Settings"],"description":"The Revoke button on Settings > Developer > API keys, Admins only: stops one API key working, at once and for good (it cannot be turned back on; an Admin mints a new one in the app). Anything using that key (Zapier, a script, another connector) starts failing.\nkey_id is an id from flyra_list_api_keys. reason (optional, up to 200 characters) is kept on the key and in the API activity log. Confirm the key name with the user before calling. Needs a signed-in user; an organization API key is refused. Creating keys is only in the app.\n\nScope: `settings:write`. Destructive: it deletes or cancels.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"key_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The API key id from flyra_list_api_keys"},"reason":{"description":"Why it is revoked, for the audit trail","type":"string","maxLength":200},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed this key stops working for good."}},"required":["key_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_revenue_goal":{"post":{"operationId":"flyra_set_revenue_goal","summary":"Set a revenue goal","tags":["Settings"],"description":"Create a revenue or job-count goal for a date range, or change one by passing goal_id. The goal appears on the Revenue Goals card on the Flyra dashboard, which tracks progress toward it. To create, pass goal_type, target_value, start_date and end_date (for a monthly goal, the first and last day of the month). To change, pass goal_id and only the fields to change. target_value is whole dollars for monthly_revenue (20000 = $20,000) and a number of jobs for monthly_jobs. An organization can have at most 4 goals; an Admin deletes one from the dashboard card. Every reply lists all of the organization's goals with their ids. Admin role required. Available per organization; where it is not enabled the reply says so.\n\nScope: `settings:write`.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"goal_id":{"description":"The goal to change, from a previous reply. Omit to create a new goal.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"goal_type":{"description":"monthly_revenue (dollars from jobs in the range) or monthly_jobs (number of jobs in the range). Required to create.","type":"string","enum":["monthly_revenue","monthly_jobs"]},"target_value":{"description":"Whole dollars for monthly_revenue, a job count for monthly_jobs. Required to create.","type":"number","exclusiveMinimum":0},"start_date":{"description":"First day the goal counts, YYYY-MM-DD. Required to create.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"end_date":{"description":"Last day the goal counts, YYYY-MM-DD, on or after start_date. Required to create.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"color":{"description":"Bar color on the dashboard card, #RRGGBB (default #3b82f6).","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"visible_to_all":{"description":"true = every user in the organization sees it; false (default) = Admins only.","type":"boolean"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_delete_revenue_goal":{"post":{"operationId":"flyra_delete_revenue_goal","summary":"Delete a revenue goal","tags":["Settings"],"description":"Delete one revenue or job-count goal, as the delete button on a goal on the Revenue Goals card on the Flyra dashboard does. The goal leaves the card for everyone and cannot be brought back. Get goal_id from a flyra_set_revenue_goal reply. Pass confirm: true. The reply lists the goals left. Admin role required. Available per organization; where it is not enabled the reply says so.\n\nScope: `settings:write`. Destructive: it deletes or cancels.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"goal_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$","description":"The goal to delete, from a flyra_set_revenue_goal reply."},"confirm":{"type":"boolean","const":true,"description":"Must be true: deleting a goal cannot be undone."}},"required":["goal_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_leaderboard":{"post":{"operationId":"flyra_get_leaderboard","summary":"Read the leaderboard","tags":["Employees"],"description":"The Leaderboard page. view:\n- rankings (default): each rep ranked by revenue, with sold (sales board), ARR, subscriptions sold, with a card on file and signed, pins dropped/converted, linear ft, reviews.\n- team_totals: the title row (each job counted once), optionally against a compare window. Admins and Owners only.\n- sprint: standings and prizes of the active sprint, or sprint_id.\n- tab: a server tab (revenuePerHour, lostBeforeFirstVisit, complaintRate, reviewRate, revenuePerDay, avgRating, nps), sales board only.\ntype: sales (who sold) or technician (who did the work). Dates are ISO; date_basis created_at (sold that day, the default) or scheduled_for. role narrows every view but sprint to one role, as the page's role filter does.\nThe price-book item and plan template filters narrow every view but sprint to the jobs carrying them, as the page's type filter does.\nRead only. Needs the Leaderboard permission; technicians never see it.\n\nScope: `employees:read`.","x-required-scope":"employees:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"view":{"type":"string","enum":["rankings","team_totals","sprint","tab"]},"type":{"type":"string","enum":["sales","technician"]},"start_date":{"description":"ISO 8601 timestamp with the org's UTC offset (flyra_get_org_settings has its timezone), inclusive. A date alone is midnight UTC. Required except for view=sprint.","type":"string"},"end_date":{"description":"ISO 8601 timestamp with the org's UTC offset (flyra_get_org_settings has its timezone), inclusive. A date alone is midnight UTC. Required except for view=sprint.","type":"string"},"date_basis":{"type":"string","enum":["created_at","scheduled_for"]},"compare_start_date":{"description":"team_totals only: the window to compare against.","type":"string"},"compare_end_date":{"type":"string"},"employee_ids":{"description":"Only these reps.","maxItems":100,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"service_ids":{"description":"Only jobs carrying these price-book items (svc_ ids from flyra_list_services), as the page's Service Type filter. Every view but sprint.","maxItems":50,"type":"array","items":{"type":"string","maxLength":200}},"subscription_template_ids":{"description":"Only visits of plans built from these subscription templates (subtpl_ ids from flyra_list_subscription_templates), as the page's Service Type filter. Every view but sprint.","maxItems":50,"type":"array","items":{"type":"string","maxLength":200}},"role":{"description":"Only people in this role, as the page's role filter: \"Sales Rep\", \"Technician\", \"Admin\", or a custom role id.","type":"string"},"team_id":{"description":"rankings, sales board: only this sales team.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"sprint_id":{"description":"view=sprint: this sprint instead of the active one.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"tab_key":{"description":"view=tab: which tab.","type":"string","enum":["revenuePerHour","lostBeforeFirstVisit","complaintRate","reviewRate","revenuePerDay","avgRating","nps"]},"limit":{"description":"rankings: rows (default 50).","type":"integer","minimum":1,"maximum":100}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_sales_sprints":{"post":{"operationId":"flyra_list_sales_sprints","summary":"List sales sprints","tags":["Employees"],"description":"The sprints on the Leaderboard page (leaderboard competitions with a start and end date). By default only active ones; an Admin can pass include_all for drafts and finished ones, and archived=true lists the archived ones. Use the id with flyra_get_leaderboard view=sprint for standings, or flyra_save_sales_sprint to edit. Read only.\n\nScope: `employees:read`.","x-required-scope":"employees:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"description":"Which board (default sales).","type":"string","enum":["sales","technician"]},"include_all":{"description":"Admins: drafts and finished sprints too.","type":"boolean"},"archived":{"description":"List archived sprints instead.","type":"boolean"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_save_sales_sprint":{"post":{"operationId":"flyra_save_sales_sprint","summary":"Start or edit a sales sprint","tags":["Employees"],"description":"Leaderboard > Sprints, Admin only. Without sprint_id it starts a sprint: name, type (sales or technician), start_date and end_date are required; it is active if today is inside the dates, completed if they are over, otherwise a draft, and a draft stays a draft when its start date comes (an edit does not change it either), so create a sprint that should run with dates that include today. With sprint_id it edits the name, description, or both dates together. Standings come from the sprint dates by created date. Nobody is notified. Prizes are set in the app.\n\nScope: `employees:write`.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"sprint_id":{"description":"Edit this sprint; omit to start a new one.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string","minLength":1,"maxLength":200},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"type":{"description":"New sprints only: which board.","type":"string","enum":["sales","technician"]},"start_date":{"description":"ISO 8601.","type":"string"},"end_date":{"description":"ISO 8601, after start_date. On an edit, send both dates or neither.","type":"string"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_archive_sales_sprint":{"post":{"operationId":"flyra_archive_sales_sprint","summary":"Archive or restore a sales sprint","tags":["Employees"],"description":"Leaderboard > Sprints, Admin only: archive a sprint (archived=true) so it leaves the sprint picker, or bring it back (archived=false). Its prizes and standings are kept. Nobody is notified. Deleting a sprint is only in the app.\n\nScope: `employees:write`.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"sprint_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"archived":{"type":"boolean"}},"required":["sprint_id","archived"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_delete_sales_sprint":{"post":{"operationId":"flyra_delete_sales_sprint","summary":"Delete a sales sprint","tags":["Employees"],"description":"Leaderboard > Sprints, Admin only: deletes the sprint and its prizes, as the sprint's Delete button does. Cannot be undone; flyra_archive_sales_sprint hides a sprint and keeps it. Nobody is notified.\n\nScope: `employees:write`. Destructive: it deletes or cancels.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"sprint_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"From flyra_list_sales_sprints."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed deleting this sprint and its prizes, which cannot be undone."}},"required":["sprint_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_sprint_prizes":{"post":{"operationId":"flyra_set_sprint_prizes","summary":"Set a sprint's prizes","tags":["Employees"],"description":"Leaderboard > Edit Sprint > Prizes, Admin only. Saves the list as the dialog's Save does: a rank the sprint already has gets the new title, a new rank is added, and a rank left out of the list is removed. A blank title counts as left out. A prize is a title shown on the board for that place; nothing is paid out. Returns the sprint's prizes after the save. Nobody is notified.\n\nScope: `employees:write`. Destructive: it deletes or cancels.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"sprint_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"From flyra_list_sales_sprints."},"prizes":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"rank":{"type":"integer","minimum":1,"maximum":10,"description":"1 = first place."},"title":{"type":"string","maxLength":200}},"required":["rank","title"]},"description":"The whole prize list. Send [] to remove every prize."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed this list, and that any rank left out is removed."}},"required":["sprint_id","prizes","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_leaderboard_settings":{"post":{"operationId":"flyra_update_leaderboard_settings","summary":"Change leaderboard settings","tags":["Employees"],"description":"The Leaderboard settings gear, Admins only (the page's check): metric_tabs sets the tabs each board shows, in order (the first is the one it opens on; sending one board leaves the other as it is), and team_totals_visibility sets who sees the team totals row (admin, everyone or off). Send at least one. Returns the saved settings. Needs a signed-in person; an API key is refused. Nobody is notified.\n\nScope: `employees:write`.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"metric_tabs":{"description":"Tab keys per board, in order; the first is the tab it opens on. A key the board cannot show is refused.","type":"object","properties":{"sales":{"minItems":1,"type":"array","items":{"type":"string"}},"technician":{"minItems":1,"type":"array","items":{"type":"string"}}}},"team_totals_visibility":{"type":"string","enum":["admin","everyone","off"]}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_sales_teams":{"post":{"operationId":"flyra_list_sales_teams","summary":"List sales teams","tags":["Employees"],"description":"The sales teams on the Leaderboard (Teams): each team's id, name, description, colour, member ids and team lead (leaderEmployeeId, null when none), plus every active employee with the team they are on, and whether the caller may change teams (canManage: Admins only). Admins, or a role with View Leaderboards on, as the Leaderboard page; Technicians are refused. Needs a signed-in Flyra user. Read only.\n\nScope: `employees:read`.","x-required-scope":"employees:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_save_sales_team":{"post":{"operationId":"flyra_save_sales_team","summary":"Create or edit a sales team","tags":["Employees"],"description":"Leaderboard > Teams, Admin only. Without team_id it creates a team (name required); with team_id it edits only the fields sent. member_ids is the whole member list: each person can be on one team, so adding someone moves them off their old team. leader_employee_id names the team lead, who is added to the team if not on it; null clears it. Members must be active employees of this company. Nobody is notified. Returns the saved team.\n\nScope: `employees:write`.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"team_id":{"description":"Edit this team (from flyra_list_sales_teams); omit to create one.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"description":"Required for a new team; at most 60 characters.","type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"color":{"description":"A hex colour like #3B82F6.","anyOf":[{"type":"string"},{"type":"null"}]},"leader_employee_id":{"description":"The team lead's employee id; null clears it.","anyOf":[{"type":"string"},{"type":"null"}]},"member_ids":{"description":"Every member's employee id; omit to leave members as they are.","maxItems":500,"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_delete_sales_team":{"post":{"operationId":"flyra_delete_sales_team","summary":"Delete a sales team","tags":["Employees"],"description":"Leaderboard > Teams, Admin only: deletes the team. Its members stay employees and show on no team. Cannot be undone. Nobody is notified.\n\nScope: `employees:write`. Destructive: it deletes or cancels.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"team_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"From flyra_list_sales_teams."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed deleting this team, which cannot be undone."}},"required":["team_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_sales_stats":{"post":{"operationId":"flyra_get_sales_stats","summary":"Read a rep's sales stats","tags":["Employees"],"description":"One rep's Sales Stats page (open a rep from the Leaderboard), the same answer the page and the iPhone app get: sold total and count, sold per day, week or month, plan versus one time job split, average and biggest sale, revenue and ARR series, pins by status, the previous window to compare against, pace insights, leaderboard badges and rank among reps. partial: true means the badges, the rank or the comparison window failed to load and were left blank; ask again rather than report them as none. start_ymd and end_ymd are the org's calendar dates (the page defaults to month to date). Read only. Admins and Owners only, signed in as a person.\n\nScope: `employees:read`.","x-required-scope":"employees:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"string","description":"The rep: an employee id from flyra_list_employees or flyra_get_leaderboard."},"start_ymd":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First day, YYYY-MM-DD."},"end_ymd":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Last day, YYYY-MM-DD, inclusive."}},"required":["employee_id","start_ymd","end_ymd"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_save_center":{"post":{"operationId":"flyra_list_save_center","summary":"List the Save Center","tags":["Subscriptions"],"description":"The Save Center board: every open cancellation request (customer, plan or job, reason, value, who it is assigned to, contact attempts, next visit and charge, high priority), the requests saved or cancelled this month, this and last month's save rate, and the save offers. Use the request id with flyra_update_save_request. Only for people the Save Center lets in (Admins, or a role on its list). Read only.\n\nScope: `subscriptions:read`.","x-required-scope":"subscriptions:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_request_cancellation":{"post":{"operationId":"flyra_request_cancellation","summary":"Request cancellation","tags":["Subscriptions"],"description":"Request cancellation of a customer's plan or one-time job, as \"Request cancellation\" does in the app: a request goes to the Save Center for someone to try to keep the customer. Nothing is cancelled: the plan or job stays active until the request is closed (flyra_update_save_request, flyra_close_save_request_cancelled).\nThe business's \"Cancellation requested\" automations start for the customer, and those can text them.\nkind is subscription (target_id = the plan id) or job (a one-time job id; only when the Save Center takes one-time jobs, and never a visit on a plan, which is cancelled directly). reason is one of the org's cancellation reasons (flyra_list_cancellation_reasons) and is required when the org asks for one. Refused when the Save Center is off, the plan is not active, or a request is already open for it.\n\nScope: `subscriptions:write`.","x-required-scope":"subscriptions:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["subscription","job"]},"target_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The plan id (kind subscription) or the one-time job id (kind job)."},"reason":{"description":"A cancellation reason name.","type":"string","maxLength":200},"note":{"type":"string","maxLength":500}},"required":["kind","target_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_save_request":{"post":{"operationId":"flyra_update_save_request","summary":"Work a Save Center request","tags":["Subscriptions"],"description":"Work one open Save Center request, as on the Save Center board. action:\n- assign: assigned_to = an employee id, or null to unassign.\n- log_attempt: record that you called, texted or emailed the customer (attempt_kind), or a note. It only records it: nothing is sent.\n- close_saved: the customer stays; save_offer must be one of the board's save offers (flyra_list_save_center). Make the plan change itself separately.\nClosing as cancelled is not here: for a plan use flyra_close_save_request_cancelled; a job's request is closed as cancelled in the app.\n\nScope: `subscriptions:write`.","x-required-scope":"subscriptions:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"action":{"type":"string","enum":["assign","log_attempt","close_saved","close_cancelled"]},"assigned_to":{"description":"assign: the employee, or null.","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"attempt_kind":{"description":"log_attempt: what you did.","type":"string","enum":["call","text","email","note"]},"save_offer":{"description":"close_saved: what saved them.","type":"string"},"note":{"type":"string","maxLength":500}},"required":["request_id","action"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_close_save_request_cancelled":{"post":{"operationId":"flyra_close_save_request_cancelled","summary":"Close a Save Center request as cancelled","tags":["Subscriptions"],"description":"Close one open Save Center request for a plan as Cancelled, as the Cancelled outcome on the Save Center board does. This cancels the customer's plan for good, exactly as the app does:\n- the plan is cancelled with the reason (one of the org's cancellation reasons for plans, flyra_list_cancellation_reasons; left out, the request's own reason is used) and the note, and its future visits are cancelled;\n- in the background, after this answers, as in the app: the plan's Stripe billing is cancelled, a cancellation fee is charged if the plan has one and a card is on file (only after a completed visit when the plan says so), and the customer is emailed the cancellation notice unless the business sends its own through a cancellation automation. These are best effort and this tool does not confirm them;\n- the business's \"Subscription cancelled\" automations can message the customer. For an Admin or Owner they are switched off for this cancel unless run_cancel_automations is true, as the \"On cancel\" switches in the app; for anyone else they run, as in the app.\nOnly for people the Save Center lets work requests, who see every customer. A job's request is closed in the app. Refused for a business that takes payments through another business's Stripe account. Pass confirm:true after the user agreed to cancel the plan and charge any fee.\n\nScope: `subscriptions:write`. Destructive: it deletes or cancels.","x-required-scope":"subscriptions:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"reason":{"description":"A cancellation reason name for plans. Left out, the request's own reason.","type":"string","maxLength":200},"note":{"type":"string","maxLength":500},"run_cancel_automations":{"description":"Admins and Owners: true lets the business's \"Subscription cancelled\" automations run. Default false.","type":"boolean"},"confirm":{"type":"boolean","const":true,"description":"Must be true: this cancels the plan, can charge its cancellation fee and emails the customer."}},"required":["request_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_cancellation_reasons":{"post":{"operationId":"flyra_list_cancellation_reasons","summary":"List cancellation reasons","tags":["Settings"],"description":"The cancellation reasons in Settings (the list people pick from when they cancel a plan or a job), in order, each with where it shows (applies_to: both, subscriptions or jobs), and ask_for: whether cancelling a plan and cancelling a job asks for a reason (off, optional or required). Read only.\n\nScope: `settings:read`.","x-required-scope":"settings:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_manage_cancellation_reason":{"post":{"operationId":"flyra_manage_cancellation_reason","summary":"Manage cancellation reasons","tags":["Settings"],"description":"Edit the cancellation reasons in Settings, Admin or Owner only. action:\n- create: name, optional applies_to (both, subscriptions or jobs). An archived reason with that name comes back.\n- rename: reason_id, plus a new name and/or applies_to.\n- archive: reason_id. It leaves the list; cancels already saved keep the name.\n- reorder: ids, every current reason id in the new order.\n- set_ask_for: ask_for.subscriptions and/or ask_for.jobs, each off, optional or required.\nChanges what the cancel screens show. Nothing is sent to anyone.\n\nScope: `settings:write`.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["create","rename","archive","reorder","set_ask_for"]},"reason_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string","minLength":1,"maxLength":120},"applies_to":{"type":"string","enum":["both","subscriptions","jobs"]},"ids":{"description":"reorder: every current reason id, in order","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"ask_for":{"type":"object","properties":{"subscriptions":{"type":"string","enum":["off","optional","required"]},"jobs":{"type":"string","enum":["off","optional","required"]}}}},"required":["action"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_invoice_settings":{"post":{"operationId":"flyra_get_invoice_settings","summary":"Get invoice settings","tags":["Settings"],"description":"Tips on invoices (Settings > Preferences: tips on or off, the tip buttons the customer sees, the one preselected) and what the invoice document shows (Settings > Documents: each display_* switch, footer message, note, text color, custom background). Read only.\n\nScope: `settings:read`.","x-required-scope":"settings:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_invoice_settings":{"post":{"operationId":"flyra_update_invoice_settings","summary":"Update invoice settings","tags":["Settings"],"description":"Admin only. Change tips on invoices (Settings > Preferences) or what the invoice document shows (Settings > Documents); send only what changes. Tip buttons are up to three distinct whole percents; the preselected tip is 0 (none) or one of the buttons. Applies to invoices customers open from now on. Nothing is sent to anyone.\n\nScope: `settings:write`.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"tips_enabled":{"type":"boolean"},"tip_preset_percents":{"description":"The tip buttons, e.g. [10, 15, 20]","minItems":1,"maxItems":3,"type":"array","items":{"type":"integer","minimum":0,"maximum":100}},"default_tip_percent":{"description":"The preselected tip: 0 for none, or one of the buttons","type":"integer","minimum":0,"maximum":100},"display_logo":{"type":"boolean"},"display_invoice_number":{"type":"boolean"},"display_customer_name":{"type":"boolean"},"display_customer_address":{"type":"boolean"},"display_customer_email":{"type":"boolean"},"display_customer_phone":{"type":"boolean"},"display_business_name":{"type":"boolean"},"display_business_email":{"type":"boolean"},"display_business_phone":{"type":"boolean"},"display_business_address":{"type":"boolean"},"display_tax_number":{"type":"boolean"},"display_description":{"type":"boolean"},"display_quantity":{"type":"boolean"},"display_unit_price":{"type":"boolean"},"display_amount":{"type":"boolean"},"display_subtotal":{"type":"boolean"},"display_tax":{"type":"boolean"},"display_footer_business_name":{"type":"boolean"},"display_footer_website":{"type":"boolean"},"footer_message":{"type":"string"},"note":{"description":"The note printed on every invoice","type":"string"},"primary_text_color":{"description":"Text color as #rrggbb; empty string goes back to the default","type":"string","pattern":"^(#[0-9a-fA-F]{6}|#[0-9a-fA-F]{3}|)$"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_estimate_settings":{"post":{"operationId":"flyra_update_estimate_settings","summary":"Update the estimate document layout","tags":["Settings"],"description":"Admin only. Change what the estimate document shows (Settings > Documents > Estimates): each display_* switch, the text color, and Use custom background (only once a background is uploaded; upload one with flyra_set_estimate_background); send only what changes. Applies to estimates customers open from now on. Nothing is sent to anyone.\n\nScope: `settings:write`.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"display_logo":{"type":"boolean"},"display_estimate_number":{"type":"boolean"},"display_customer_name":{"type":"boolean"},"display_customer_address":{"type":"boolean"},"display_customer_email":{"type":"boolean"},"display_customer_phone":{"type":"boolean"},"display_business_name":{"type":"boolean"},"display_business_email":{"type":"boolean"},"display_business_phone":{"type":"boolean"},"display_business_address":{"type":"boolean"},"display_tax_number":{"type":"boolean"},"display_description":{"type":"boolean"},"display_quantity":{"type":"boolean"},"display_unit_price":{"type":"boolean"},"display_amount":{"type":"boolean"},"display_subtotal":{"type":"boolean"},"display_tax":{"type":"boolean"},"display_footer_business_name":{"type":"boolean"},"display_footer_website":{"type":"boolean"},"display_terms":{"type":"boolean"},"display_before_after":{"type":"boolean"},"primary_text_color":{"description":"Text color as #rrggbb; empty string goes back to the default","type":"string","pattern":"^(#[0-9a-fA-F]{6}|#[0-9a-fA-F]{3}|)$"},"use_custom_background":{"description":"The Use custom background switch. Only once a background is uploaded.","type":"boolean"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_estimate_background":{"post":{"operationId":"flyra_set_estimate_background","summary":"Set the estimate background picture","tags":["Settings"],"description":"Admin only. Puts a picture behind every estimate document and turns Use custom background on, as the Upload button on Settings > Documents > Estimates does. Replaces the current background picture, whose file is deleted. Pass the picture as a public https link (image_url) or as base64 (image_base64): a JPEG, PNG or WebP up to 10 MB; SVG and other files are refused. Applies to estimates customers open from now on. Nothing is sent to anyone.\n\nScope: `settings:write`. Destructive: it deletes or cancels.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"image_url":{"description":"A public https link to the picture. Pass this or image_base64.","type":"string"},"image_base64":{"description":"The picture itself as base64. Pass this or image_url.","type":"string"},"confirm":{"type":"boolean","const":true,"description":"true: replace the current estimate background, if there is one."}},"required":["confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_invoice_background":{"post":{"operationId":"flyra_set_invoice_background","summary":"Set the invoice background picture","tags":["Settings"],"description":"Admin only, as a signed-in user. Puts a picture behind every invoice document and turns Use custom background on, as the Upload button on Settings > Documents > Invoices does. Replaces the current invoice background picture, whose file is deleted. Pass the picture as a public https link (image_url) or as base64 (image_base64): a JPEG, PNG or WebP up to 10 MB; SVG and other files are refused. Applies to invoices customers open from now on. Nothing is sent to anyone.\n\nScope: `settings:write`. Destructive: it deletes or cancels.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"image_url":{"description":"A public https link to the picture. Pass this or image_base64.","type":"string"},"image_base64":{"description":"The picture itself as base64. Pass this or image_url.","type":"string"},"confirm":{"type":"boolean","const":true,"description":"true: replace the current invoice background, if there is one."}},"required":["confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_estimate_default_attachments":{"post":{"operationId":"flyra_list_estimate_default_attachments","summary":"List default estimate attachments","tags":["Settings"],"description":"The files every new estimate carries a copy of (a warranty, insurance certificate, scope of work), as Settings > Documents shows them for estimates: name, size, type and a download link that works for one hour. Up to 10. Invoices have no default attachments in Flyra. Read only.\n\nScope: `settings:read`.","x-required-scope":"settings:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_add_estimate_default_attachment":{"post":{"operationId":"flyra_add_estimate_default_attachment","summary":"Add a default estimate attachment","tags":["Settings"],"description":"Admin or Owner only. Adds a file every estimate created from now on carries a copy of, as the upload on Settings > Documents (Estimates) does. Pass the file as a public https link (file_url) or as base64 (file_base64), plus its file_name with the extension (e.g. \"Warranty.pdf\"). Documents and pictures up to 4 MB; video is refused; at most 10 files. Estimates already made are not changed. Nothing is sent to anyone.\n\nScope: `settings:write`.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"file_url":{"description":"A public https link to the file. Pass this or file_base64.","type":"string"},"file_base64":{"description":"The file itself as base64. Pass this or file_url.","type":"string"},"file_name":{"type":"string","minLength":1,"maxLength":200,"description":"The name customers see, with its extension, e.g. \"Warranty.pdf\"."},"content_type":{"description":"The file type, e.g. application/pdf. Only used with file_base64; a link's own type is used otherwise.","type":"string","pattern":"^[\\w.+-]+\\/[\\w.+-]+$"}},"required":["file_name"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_remove_estimate_default_attachment":{"post":{"operationId":"flyra_remove_estimate_default_attachment","summary":"Remove a default estimate attachment","tags":["Settings"],"description":"Admin or Owner only. Stops new estimates carrying this file, as removing it on Settings > Documents (Estimates) does, and deletes the stored file. Estimates that already carry a copy keep theirs. Pass the id from flyra_list_estimate_default_attachments. Nothing is sent to anyone.\n\nScope: `settings:write`. Destructive: it deletes or cancels.","x-required-scope":"settings:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"attachment_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The id from flyra_list_estimate_default_attachments."}},"required":["attachment_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_team_contracts":{"post":{"operationId":"flyra_list_team_contracts","summary":"List team contracts","tags":["Employees"],"description":"The contracts on Team > Contracts (documents the team signs in Flyra), newest first: name, who it goes to, whether it blocks the app until signed, sent and voided dates, and how many signed and how many are still outstanding. Admin only. Use the id with flyra_get_team_contract for who signed. Read only.\n\nScope: `employees:read`.","x-required-scope":"employees:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_team_contract":{"post":{"operationId":"flyra_get_team_contract","summary":"Get a team contract","tags":["Employees"],"description":"One contract on Team > Contracts: each person it was sent to with their status (signed, viewed, sent, or awaiting_account: no Flyra login yet), when it was sent, viewed and signed, plus a 5-minute download link to the file. Admin only. Like opening it in the app, it adds the copy for anyone who joined the team since it was sent, without messaging them.\n\nScope: `employees:read`.","x-required-scope":"employees:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"contract_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["contract_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_remind_team_contract":{"post":{"operationId":"flyra_remind_team_contract","summary":"Remind the team to sign a contract","tags":["Employees"],"description":"The Remind button on a sent contract (Team > Contracts), Admin only. It EMAILS AND TEXTS every team member who still has to sign and has a Flyra login, or only the copies in document_ids (from flyra_get_team_contract). Each call sends again, so confirm with the user who will get it before calling, and call it once. Returns how many were reminded. Refused for a voided or unsent contract.\n\nScope: `employees:write`.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"contract_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"document_ids":{"description":"Only these people's copies; omit for everyone outstanding","maxItems":500,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed who gets this email and text."}},"required":["contract_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_void_team_contract":{"post":{"operationId":"flyra_void_team_contract","summary":"Void a team contract","tags":["Employees"],"description":"Withdraw a contract on Team > Contracts, Admin only: nobody is asked to sign it any more and it no longer blocks anyone. Signed copies and their signatures stay as they are. Cannot be undone; nothing is sent to anyone.\n\nScope: `employees:write`. Destructive: it deletes or cancels.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"contract_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed withdrawing it, which cannot be undone."}},"required":["contract_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_create_team_contract":{"post":{"operationId":"flyra_create_team_contract","summary":"Create a team contract draft","tags":["Employees"],"description":"Admin only. Starts a new contract on Team > Contracts from a PDF, as the New contract form does, and saves it as a DRAFT: nobody is asked to sign and nothing is sent. Pass the PDF as a public https link (file_url) or base64 (file_base64), at most 10 MB, not password protected. `audience` is who it is for: \"*\" for everyone, built-in role names such as \"sales rep\" or \"technician\", custom role ids, or employee ids. Before it can be sent, someone places the signature boxes on the PDF and draws the company signature in the app (Team > Contracts); then send it there or with flyra_send_team_contract. Each call makes a new draft.\n\nScope: `employees:write`.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"The contract name the team sees."},"audience":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"string","minLength":1},"description":"\"*\", role names, custom role ids or employee ids."},"enforcement":{"description":"banner (default): a reminder banner; required: the app is blocked until signed.","type":"string","enum":["banner","required"]},"required_from":{"description":"ISO date from which a required contract blocks the app. Only used with enforcement: required.","type":"string"},"file_url":{"description":"A public https link to the PDF. Pass this or file_base64.","type":"string"},"file_base64":{"description":"The PDF itself as base64. Pass this or file_url.","type":"string"},"file_name":{"description":"The file name, ending in .pdf. Defaults to the contract name.","type":"string","minLength":1,"maxLength":200,"pattern":"\\.pdf$"}},"required":["name","audience"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_send_team_contract":{"post":{"operationId":"flyra_send_team_contract","summary":"Send a team contract","tags":["Employees"],"description":"Admin only. The Send button on a draft on Team > Contracts: it issues a copy to every team member the contract is for and, for each one with a Flyra login, emails them (when they have an email address) and texts them (when they have a phone and the business's texting number is set up), asking them to sign. Confirm with the user who will get it before calling. Refused until the signature boxes are placed and the company signature is drawn in the app, for an empty audience, for a voided contract, and for a contract already sent (to nudge people who have not signed, use flyra_remind_team_contract). After an error, check flyra_get_team_contract before calling again.\n\nScope: `employees:write`.","x-required-scope":"employees:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"contract_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed who gets this email and text."}},"required":["contract_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_create_lead_source":{"post":{"operationId":"flyra_create_lead_source","summary":"Create a lead source","tags":["Services"],"description":"Add a new lead source to the org's list (e.g. \"Google Ads\", \"Door Knock\"). Returns the row. Fails if an active source already has the same name, ignoring case. If a removed source had that name, it is restored with its original spelling instead of creating a duplicate.\n\nScope: `services:write`.","x-required-scope":"services:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Lead source name, e.g. \"Google Ads\"."}},"required":["name"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_lead_source":{"post":{"operationId":"flyra_update_lead_source","summary":"Rename a lead source","tags":["Services"],"description":"Update the name of an existing lead source. Pass the lead_source_id (from flyra_list_lead_sources or the ls_ semantic id) and the new name.\n\nScope: `services:write`.","x-required-scope":"services:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"lead_source_id":{"type":"string","description":"ID of the lead source to update (raw UUID or ls_ semantic id)."},"name":{"type":"string","minLength":1,"maxLength":100,"description":"New name for the lead source."}},"required":["lead_source_id","name"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_delete_lead_source":{"post":{"operationId":"flyra_delete_lead_source","summary":"Delete a lead source","tags":["Services"],"description":"Remove a lead source from the org. It leaves flyra_list_lead_sources and every picker, while the jobs, estimates, subscriptions, customers and leads that already carry it keep showing it. Creating a source with the same name later restores it.\n\nScope: `services:write`. Destructive: it deletes or cancels.","x-required-scope":"services:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"lead_source_id":{"type":"string","description":"ID of the lead source to delete (raw UUID or ls_ semantic id)."}},"required":["lead_source_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_create_service":{"post":{"operationId":"flyra_create_service","summary":"Create a service in the price book","tags":["Services"],"description":"Add a new line item (service) to the org's price book. Give category_id (from flyra_list_services) or category_name. A category_name that does not exist yet is created, so a whole price book, new categories included, can be built with this tool alone. Create the first service of a new category before adding the rest, not in parallel calls, or the category can be created twice. Returns the created service and category_created.\n\nScope: `services:write`.","x-required-scope":"services:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"category_id":{"description":"ID of the parent category (cat_ semantic id or raw UUID). Use flyra_list_services to list categories. Give this or category_name.","type":"string"},"category_name":{"description":"Name of the parent category, e.g. \"Add-Ons\". An existing category with this name (ignoring case) is used; otherwise the category is created. Give this or category_id.","type":"string","minLength":1,"maxLength":200},"name":{"type":"string","minLength":1,"maxLength":200,"description":"Service name (internal / lookup key)."},"title":{"description":"Display title shown to customers (defaults to name if omitted).","type":"string","maxLength":200},"description":{"description":"Description of the service.","type":"string","maxLength":2000},"price":{"description":"Default price in dollars (e.g. 149.99). Defaults to 0.","type":"number","minimum":0},"quantity":{"description":"Default quantity. Defaults to 1.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"unit":{"description":"Unit label (e.g. \"each\", \"sq ft\"). Defaults to \"each\".","type":"string","maxLength":50}},"required":["name"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_service":{"post":{"operationId":"flyra_update_service","summary":"Update a service in the price book","tags":["Services"],"description":"Patch one or more fields on an existing line item. Only the fields you provide are changed. Pass the service id from flyra_list_services (svc_ semantic id or raw UUID).\n\nScope: `services:write`.","x-required-scope":"services:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"service_id":{"type":"string","description":"ID of the service to update (svc_ semantic id or raw UUID)."},"name":{"description":"New internal name.","type":"string","minLength":1,"maxLength":200},"title":{"description":"New display title. Pass empty string to clear.","type":"string","maxLength":200},"description":{"description":"New description. Pass empty string to clear.","type":"string","maxLength":2000},"price":{"description":"New default price in dollars.","type":"number","minimum":0},"quantity":{"description":"New default quantity.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"unit":{"description":"New unit label.","type":"string","maxLength":50},"category_id":{"description":"Move to a different category (cat_ semantic id or raw UUID).","type":"string"},"default_duration_minutes":{"description":"How long a job with this service is booked for by default, 15 to 1440 minutes, as the Default duration switch in Settings > Price Book. null clears it. Admins and Owners only.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["service_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_delete_service":{"post":{"operationId":"flyra_delete_service","summary":"Delete a service from the price book","tags":["Services"],"description":"Permanently remove a line item from the org's price book. This does not affect historical job/invoice line items that already reference this service by name — they store a snapshot. Pass the service id (svc_ semantic id or raw UUID). Confirm with the user first and pass confirm: true.\n\nScope: `services:write`. Destructive: it deletes or cancels.","x-required-scope":"services:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"service_id":{"type":"string","description":"ID of the service to delete (svc_ semantic id or raw UUID)."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed this service should be deleted."}},"required":["service_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_service_photo":{"post":{"operationId":"flyra_set_service_photo","summary":"Set the photo on a price book service","tags":["Services"],"description":"Put a photo on one service in Settings > Price Book, as the photo box in that screen's item editor does. It replaces the photo the service had and shows next to the service in the price book. Not sent to anyone. Admins and Owners only. Give the picture as image_url (a public https link that does not redirect) or image_base64 (its bytes): JPG, PNG, WebP or HEIC, up to 10 MB. A picture wider than 800 pixels is shrunk to 800, as the price book stores it.\n\nScope: `services:write`.","x-required-scope":"services:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"service_id":{"type":"string","description":"ID of the service (svc_ semantic id from flyra_list_services, or raw UUID)."},"image_url":{"description":"Public https link to the picture. Pass this or image_base64.","type":"string"},"image_base64":{"description":"The picture's bytes, base64 encoded. Pass this or image_url.","type":"string","maxLength":14000000}},"required":["service_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_delete_category":{"post":{"operationId":"flyra_delete_category","summary":"Delete a price book category","tags":["Services"],"description":"Delete one category from Settings > Price Book, as the delete button on that screen does. Its services are deleted with it. Admins and Owners only. Pass the category id from flyra_list_services (cat_ semantic id or raw UUID) and confirm: true.\n\nScope: `services:write`. Destructive: it deletes or cancels.","x-required-scope":"services:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"category_id":{"type":"string","maxLength":1000,"description":"ID of the category to delete (cat_ semantic id or raw UUID)."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the category and its services are deleted."}},"required":["category_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_reorder_categories":{"post":{"operationId":"flyra_reorder_categories","summary":"Set the order of the price book categories","tags":["Services"],"description":"Set the display order of the org's service categories: pass every category id from flyra_list_services (cat_ semantic id or raw UUID) in the order they should show, first to last. flyra_list_services, the web price book, the public API and the iPhone price book follow it; the iPhone's line-item picker still sorts by name. Every category must be listed once; a partial list is refused rather than guessed at. Once the categories have been reordered, a category created later shows first until it is placed.\n\nScope: `services:write`.","x-required-scope":"services:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"category_ids":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"string","maxLength":1000},"description":"Every category of the org, in display order, first to last."}},"required":["category_ids"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_reorder_services":{"post":{"operationId":"flyra_reorder_services","summary":"Set the order of the services in a category","tags":["Services"],"description":"Set the display order of the services inside one price book category: pass the category id and every service id in it, from flyra_list_services (svc_ semantic ids or raw UUIDs), in the order they should show, first to last. flyra_list_services, the web price book, the public API and the iPhone price book follow it; the iPhone's line-item picker still sorts by name. Every service of the category must be listed once; a partial list is refused rather than guessed at. Once a category has been reordered, a service created in it, or moved into it with flyra_update_service, shows first until it is placed. To move a service to another category use flyra_update_service with category_id.\n\nScope: `services:write`.","x-required-scope":"services:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"category_id":{"type":"string","maxLength":1000,"description":"The category (cat_ semantic id or raw UUID)."},"service_ids":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"string","maxLength":1000},"description":"Every service of that category, in display order, first to last."}},"required":["category_id","service_ids"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_create_subscription_template":{"post":{"operationId":"flyra_create_subscription_template","summary":"Create a subscription (agreement) template","tags":["Subscriptions"],"description":"Create a reusable subscription template — a recurring service / maintenance plan, optionally a signable agreement. This is the entity behind \"subscription agreement templates\". Carries the main line item(s), plan/pricing options, visits-per-year, a billing schedule, a duration, an optional signature requirement, a footer, and customer-facing display toggles (logo, customer details, business details, 12-month service schedule, initial-visit pricing). Leave terms_and_conditions unset to use the organization's own default terms (none if it has not written any); leave billing_information unset for the standard card authorization. Use price 0 / amount_cents 0 for custom-priced plans so the operator can set the real price before sending. Returns the created template id. Fails if a non-archived template with the same name already exists (so re-runs do not create duplicates).\n\nScope: `subscriptions:write`.","x-required-scope":"subscriptions:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Template name, e.g. \"Residential Recurring Cleaning Agreement\"."},"description":{"description":"Internal description of the template.","type":"string","maxLength":2000},"service_title":{"description":"Display title for the main service shown to the customer.","type":"string","maxLength":200},"line_items":{"description":"Line items for the template. Typically one main line item with quantity 1.","type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200,"description":"Line item title shown to the customer."},"description":{"description":"Line item description.","type":"string","maxLength":2000},"quantity":{"description":"Quantity. Defaults to 1.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"price":{"description":"Unit price in DOLLARS (e.g. 149.99). Defaults to 0 for custom-priced plans.","type":"number","minimum":0},"taxable":{"description":"Whether this line item is taxable. Defaults to false.","type":"boolean"},"applied_tax_rates":{"description":"Tax rates to apply when taxable. Omit unless the org has specific tax rates to stamp.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"rate_percent":{"type":"number"}},"required":["id","name","rate_percent"]}},"unit":{"description":"What quantity is counted in, as the Unit picker on a line saves it: \"sq ft\" or \"linear ft\" (\"sqm\" or \"linear m\" for a business that measures in metres), or the business's own word, up to 16 characters. Leave it out for a plain count (Qty).","type":"string","minLength":1,"maxLength":16}},"required":["title"]}},"per_visit_line_items":{"type":"array","items":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200,"description":"Line item title shown to the customer."},"description":{"description":"Line item description.","type":"string","maxLength":2000},"quantity":{"description":"Quantity. Defaults to 1.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"price":{"description":"Unit price in DOLLARS (e.g. 149.99). Defaults to 0 for custom-priced plans.","type":"number","minimum":0},"taxable":{"description":"Whether this line item is taxable. Defaults to false.","type":"boolean"},"applied_tax_rates":{"description":"Tax rates to apply when taxable. Omit unless the org has specific tax rates to stamp.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"rate_percent":{"type":"number"}},"required":["id","name","rate_percent"]}},"unit":{"description":"What quantity is counted in, as the Unit picker on a line saves it: \"sq ft\" or \"linear ft\" (\"sqm\" or \"linear m\" for a business that measures in metres), or the business's own word, up to 16 characters. Leave it out for a plain count (Qty).","type":"string","minLength":1,"maxLength":16}},"required":["title"]}},{"type":"null"}]},"description":"Line items per visit, by visit ordinal (index 0 = the initial visit), for plans whose visits differ — e.g. a full clean first, then touch-ups. null at an index means that visit uses line_items. Subscriptions created from the template start from these; the operator can still adjust each visit. Pass an empty array to clear."},"pricing_options":{"description":"Plan/price options (one row per frequency). amount_cents 0 = custom-priced. Note: only these eight frequencies exist; \"bi-weekly\" is not a valid frequency.","type":"array","items":{"type":"object","properties":{"frequency":{"type":"string","enum":["weekly","monthly","bi_monthly","quarterly","tri_annual","six_months","yearly","biennial","triennial"],"description":"Billing cadence for this plan option."},"amount_cents":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Price for this option in CENTS (e.g. 15000 = $150.00). Use 0 for custom-priced plans."},"is_default":{"description":"Marks this as the default option. Exactly one option is the default; if you omit it the first option is used.","type":"boolean"}},"required":["frequency","amount_cents"]}},"visits_per_year":{"description":"Visits per year (e.g. 52 weekly, 26 bi-weekly, 12 monthly, 4 quarterly). Defaults to 1.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"duration_type":{"description":"\"continues\" = month-to-month / renews until cancelled (default). \"fixed_months\" = a set term.","type":"string","enum":["continues","fixed_months"]},"duration_months":{"description":"Number of months when duration_type is \"fixed_months\" (e.g. 12).","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"require_signature":{"description":"Require the customer to sign. Defaults to false.","type":"boolean"},"agreement_template_id":{"description":"Optional agreement_templates id to attach contract HTML (from flyra_list_agreement_templates).","type":"string"},"uses_subscription_terms":{"description":"Include the standard subscription terms block. Defaults to true.","type":"boolean"},"terms_and_conditions":{"description":"Override the terms text. Omit to use the organization default.","type":"string"},"billing_information":{"description":"Override the billing-information text. Omit to use the organization default.","type":"string"},"billing_mode":{"description":"\"service_dates\" (default) = bill on scheduled service dates; \"on_completion\" = bill when job completed; \"first_of_month\"; \"specific_date\" = bill on billing_day each cycle.","type":"string","enum":["service_dates","on_completion","first_of_month","specific_date"]},"billing_day":{"description":"Day of month (1-28) to bill when billing_mode is \"specific_date\".","type":"integer","minimum":1,"maximum":28},"frequency":{"description":"Template billing frequency. Defaults to the default pricing option's frequency, else \"monthly\".","type":"string","enum":["weekly","monthly","bi_monthly","quarterly","tri_annual","six_months","yearly","biennial","triennial"]},"bill_only_on_service_months":{"description":"Only bill in months that have a scheduled service (specific_date / first_of_month modes). Defaults to false.","type":"boolean"},"initial_fee_cents":{"description":"Initial / first-visit fee in cents. Defaults to 0.","type":"integer","minimum":0,"maximum":9007199254740991},"initial_fee_discount_cents":{"description":"Discount applied to the initial fee in cents. Defaults to 0.","type":"integer","minimum":0,"maximum":9007199254740991},"hybrid_initial_billing":{"description":"Bill the initial visit on a different schedule than recurring visits. Defaults to false.","type":"boolean"},"initial_visit_billing_mode":{"description":"Billing mode for the initial visit when hybrid_initial_billing is on.","type":"string","enum":["service_dates","on_completion"]},"initial_visit_taxable":{"description":"Whether the initial visit is taxable. Defaults to false.","type":"boolean"},"guarantees":{"description":"Optional guarantees / promises text.","type":"string","maxLength":4000},"display_guarantees":{"description":"Show the guarantees section. Defaults to false.","type":"boolean"},"display_terms":{"description":"Show the Terms and conditions box on the agreement (the builder's switch on that box). Defaults to true.","type":"boolean"},"display_billing":{"description":"Show the Billing information box on the agreement (the builder's switch on that box). Defaults to true.","type":"boolean"},"footer_message":{"description":"Custom footer message shown at the bottom of the document.","type":"string","maxLength":2000},"display_footer_business_name":{"description":"Show the business name in the footer. Defaults to true.","type":"boolean"},"display_footer_website":{"description":"Show the website in the footer. Defaults to true.","type":"boolean"},"display_first_visit":{"description":"Show initial-visit pricing. Defaults to true.","type":"boolean"},"display_visits_per_year":{"description":"Show visits-per-year. Defaults to true.","type":"boolean"},"display_service_month_schedule":{"description":"Show the visual 12-month service schedule block. Defaults to true.","type":"boolean"},"display_logo":{"description":"Show the company logo. Defaults to true.","type":"boolean"},"display_customer_name":{"description":"Show the customer name. Defaults to true.","type":"boolean"},"display_customer_address":{"description":"Show the customer address. Defaults to true.","type":"boolean"},"display_customer_email":{"description":"Show the customer email. Defaults to true.","type":"boolean"},"display_customer_phone":{"description":"Show the customer phone. Defaults to true.","type":"boolean"},"display_business_name":{"description":"Show the business name. Defaults to true.","type":"boolean"},"display_business_email":{"description":"Show the business email. Defaults to true.","type":"boolean"},"display_business_phone":{"description":"Show the business phone. Defaults to true.","type":"boolean"},"display_business_address":{"description":"Show the business address. Defaults to true.","type":"boolean"},"display_tax_number":{"description":"Show the tax number. Defaults to false.","type":"boolean"}},"required":["name"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_subscription_template":{"post":{"operationId":"flyra_update_subscription_template","summary":"Update a subscription (agreement) template","tags":["Subscriptions"],"description":"Edit an existing subscription template. Pass only the fields you want to change; anything you leave out keeps its current value. Get the id from flyra_list_subscription_templates. Passing pricing_options REPLACES the whole set of plan options, so include every option you want to keep. Passing line_items likewise replaces the whole list. Editing a template changes what future subscriptions built from it look like. Signed plans keep their agreement; plans sent but not yet signed show the template's current terms, term length and signature rule. terms_and_conditions, billing_information and guarantees: read the current text from flyra_list_subscription_templates and edit that. Each text field is replaced in full: send the whole new text, not only the part that changes. The reply's replaced_text holds the text each field replaced, so a mistake can be put back.\n\nScope: `subscriptions:write`.","x-required-scope":"subscriptions:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_template_id":{"type":"string","description":"Template id from flyra_list_subscription_templates."},"name":{"description":"New template name.","type":"string","minLength":1,"maxLength":200},"description":{"description":"Internal description.","type":"string","maxLength":2000},"service_title":{"description":"Display title for the main service.","type":"string","maxLength":200},"line_items":{"description":"REPLACES all line items on the template.","type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200,"description":"Line item title shown to the customer."},"description":{"description":"Line item description.","type":"string","maxLength":2000},"quantity":{"description":"Quantity. Defaults to 1.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"price":{"description":"Unit price in DOLLARS (e.g. 149.99). Defaults to 0 for custom-priced plans.","type":"number","minimum":0},"taxable":{"description":"Whether this line item is taxable. Defaults to false.","type":"boolean"},"applied_tax_rates":{"description":"Tax rates to apply when taxable. Omit unless the org has specific tax rates to stamp.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"rate_percent":{"type":"number"}},"required":["id","name","rate_percent"]}},"unit":{"description":"What quantity is counted in, as the Unit picker on a line saves it: \"sq ft\" or \"linear ft\" (\"sqm\" or \"linear m\" for a business that measures in metres), or the business's own word, up to 16 characters. Leave it out for a plain count (Qty).","type":"string","minLength":1,"maxLength":16}},"required":["title"]}},"per_visit_line_items":{"type":"array","items":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200,"description":"Line item title shown to the customer."},"description":{"description":"Line item description.","type":"string","maxLength":2000},"quantity":{"description":"Quantity. Defaults to 1.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"price":{"description":"Unit price in DOLLARS (e.g. 149.99). Defaults to 0 for custom-priced plans.","type":"number","minimum":0},"taxable":{"description":"Whether this line item is taxable. Defaults to false.","type":"boolean"},"applied_tax_rates":{"description":"Tax rates to apply when taxable. Omit unless the org has specific tax rates to stamp.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"rate_percent":{"type":"number"}},"required":["id","name","rate_percent"]}},"unit":{"description":"What quantity is counted in, as the Unit picker on a line saves it: \"sq ft\" or \"linear ft\" (\"sqm\" or \"linear m\" for a business that measures in metres), or the business's own word, up to 16 characters. Leave it out for a plain count (Qty).","type":"string","minLength":1,"maxLength":16}},"required":["title"]}},{"type":"null"}]},"description":"Line items per visit, by visit ordinal (index 0 = the initial visit), for plans whose visits differ — e.g. a full clean first, then touch-ups. null at an index means that visit uses line_items. Subscriptions created from the template start from these; the operator can still adjust each visit. Pass an empty array to clear."},"pricing_options":{"description":"REPLACES all plan/price options. amount_cents 0 = custom-priced. Note: only the eight listed frequencies exist; \"bi-weekly\" is not one.","type":"array","items":{"type":"object","properties":{"frequency":{"type":"string","enum":["weekly","monthly","bi_monthly","quarterly","tri_annual","six_months","yearly","biennial","triennial"],"description":"Billing cadence for this plan option."},"amount_cents":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Price for this option in CENTS (e.g. 15000 = $150.00). Use 0 for custom-priced plans."},"is_default":{"description":"Marks this as the default option. Exactly one option is the default; if you omit it the first option is used.","type":"boolean"}},"required":["frequency","amount_cents"]}},"visits_per_year":{"description":"Visits per year (52 weekly, 26 bi-weekly, 12 monthly, 4 quarterly).","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"duration_type":{"description":"\"continues\" = renews until cancelled. \"fixed_months\" = a set term.","type":"string","enum":["continues","fixed_months"]},"duration_months":{"description":"Months, when duration_type is \"fixed_months\".","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"require_signature":{"description":"Require the customer to sign.","type":"boolean"},"agreement_template_id":{"description":"agreement_templates id for contract HTML. Pass an empty string to detach.","type":"string"},"uses_subscription_terms":{"description":"Include the standard subscription terms block.","type":"boolean"},"terms_and_conditions":{"description":"The whole terms text; it replaces the current text in full. Empty string re-inherits the organization default.","type":"string"},"billing_information":{"description":"The whole billing-information text; it replaces the current text in full. Empty string re-inherits the organization default.","type":"string"},"billing_mode":{"description":"\"service_dates\" = bill on scheduled service dates; \"on_completion\" = bill when the job is completed; \"first_of_month\"; \"specific_date\" = bill on billing_day each cycle.","type":"string","enum":["service_dates","on_completion","first_of_month","specific_date"]},"billing_day":{"description":"Day of month (1-28) when billing_mode is \"specific_date\".","type":"integer","minimum":1,"maximum":28},"frequency":{"description":"Template billing frequency.","type":"string","enum":["weekly","monthly","bi_monthly","quarterly","tri_annual","six_months","yearly","biennial","triennial"]},"bill_only_on_service_months":{"description":"Only bill in months with a scheduled service (specific_date / first_of_month modes).","type":"boolean"},"initial_fee_cents":{"description":"Initial / first-visit fee in cents.","type":"integer","minimum":0,"maximum":9007199254740991},"initial_fee_discount_cents":{"description":"Discount on the initial fee in cents.","type":"integer","minimum":0,"maximum":9007199254740991},"hybrid_initial_billing":{"description":"Bill the initial visit on a different schedule than recurring visits.","type":"boolean"},"initial_visit_billing_mode":{"description":"Billing mode for the initial visit when hybrid_initial_billing is on.","type":"string","enum":["service_dates","on_completion"]},"initial_visit_taxable":{"description":"Whether the initial visit is taxable.","type":"boolean"},"guarantees":{"description":"The whole guarantees / promises text; it replaces the current text in full.","type":"string","maxLength":4000},"display_guarantees":{"description":"Show the guarantees section.","type":"boolean"},"display_terms":{"description":"Show the Terms and conditions box on the agreement. true turns a hidden box back on. Plans already created keep the switch they had.","type":"boolean"},"display_billing":{"description":"Show the Billing information box on the agreement. true turns a hidden box back on. Plans already created keep the switch they had.","type":"boolean"},"footer_message":{"description":"Custom footer message.","type":"string","maxLength":2000},"display_footer_business_name":{"description":"Show the business name in the footer.","type":"boolean"},"display_footer_website":{"description":"Show the website in the footer.","type":"boolean"},"display_first_visit":{"description":"Show initial-visit pricing.","type":"boolean"},"display_visits_per_year":{"description":"Show visits-per-year.","type":"boolean"},"display_service_month_schedule":{"description":"Show the 12-month service schedule block.","type":"boolean"},"display_logo":{"description":"Show the company logo.","type":"boolean"},"display_customer_name":{"description":"Show the customer name.","type":"boolean"},"display_customer_address":{"description":"Show the customer address.","type":"boolean"},"display_customer_email":{"description":"Show the customer email.","type":"boolean"},"display_customer_phone":{"description":"Show the customer phone.","type":"boolean"},"display_business_name":{"description":"Show the business name.","type":"boolean"},"display_business_email":{"description":"Show the business email.","type":"boolean"},"display_business_phone":{"description":"Show the business phone.","type":"boolean"},"display_business_address":{"description":"Show the business address.","type":"boolean"},"display_tax_number":{"description":"Show the tax number.","type":"boolean"}},"required":["subscription_template_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_archive_subscription_template":{"post":{"operationId":"flyra_archive_subscription_template","summary":"Archive or unarchive a subscription (agreement) template","tags":["Subscriptions"],"description":"Archive a subscription template so it leaves Settings → Subscriptions and can no longer start a new plan, or pass archived:false to bring it back. Plans already built from it are not changed. Nothing is deleted and nothing is sent. Admins and Owners only, as the Subscriptions tab in Settings. Find archived templates with flyra_list_subscription_templates include_archived:true.\n\nScope: `subscriptions:write`.","x-required-scope":"subscriptions:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_template_id":{"type":"string","description":"Template id from flyra_list_subscription_templates."},"archived":{"description":"true (default) archives it; false unarchives it.","type":"boolean"}},"required":["subscription_template_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_duplicate_subscription_template":{"post":{"operationId":"flyra_duplicate_subscription_template","summary":"Copy a subscription (agreement) template","tags":["Subscriptions"],"description":"Copy a subscription template into a new one, as Copy template in the plan template editor does: every setting, line item, agreement text and pricing option is copied, named \"<name> (Copy)\" unless you pass a name. The original and the plans built from it are not changed. Nothing is sent. Admins and Owners only, as the Subscriptions tab in Settings. Change the copy with flyra_update_subscription_template.\n\nScope: `subscriptions:write`.","x-required-scope":"subscriptions:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_template_id":{"type":"string","description":"Template to copy, from flyra_list_subscription_templates."},"name":{"description":"Name for the copy. Defaults to \"<name> (Copy)\".","type":"string","maxLength":200}},"required":["subscription_template_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_delete_subscription_template":{"post":{"operationId":"flyra_delete_subscription_template","summary":"Delete a subscription (agreement) template","tags":["Subscriptions"],"description":"Delete a subscription template for good, as the Delete button on Settings → Subscriptions does. Plans already built from it are not deleted, but lose their link to it. Call it first without confirm: it deletes nothing and answers live_subscription_count, the plans (pending, active or paused) built from this template. Then call again with confirm:true and expected_live_count set to that number; if the number has changed, nothing is deleted. To hide a template without deleting it, use flyra_archive_subscription_template. Nothing is sent. Admins only, as a signed-in user, as the Subscriptions tab in Settings.\n\nScope: `subscriptions:write`. Destructive: it deletes or cancels.","x-required-scope":"subscriptions:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_template_id":{"type":"string","description":"Template id from flyra_list_subscription_templates."},"confirm":{"description":"true deletes. Left out, nothing is deleted and the live plan count is returned.","type":"boolean","const":true},"expected_live_count":{"description":"With confirm: the live_subscription_count from the first call.","type":"integer","minimum":0,"maximum":9007199254740991}},"required":["subscription_template_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_expenses":{"post":{"operationId":"flyra_list_expenses","summary":"List expenses","tags":["Expenses"],"description":"List logged business expenses, newest first. Filter by date range on expense_date, by category, and by free-text search over description and category. Returns one page plus the exact total count — for what a period actually cost, call flyra_get_expense_summary instead of adding up pages.\n\nScope: `expenses:read`.","x-required-scope":"expenses:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"start_date":{"description":"Only expenses on or after this date. Calendar date as YYYY-MM-DD (e.g. 2026-07-23).","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"end_date":{"description":"Only expenses on or before this date. Calendar date as YYYY-MM-DD (e.g. 2026-07-23).","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"category":{"type":"string","enum":["Cost of Goods Sold","Vehicle and Travel","Office and Admin","Software and Subscriptions","Marketing and Advertising","Payroll and Contractors","Equipment and Tools","Insurance and Licenses","Banking and Finance","Meals and Entertainment","Education and Training","Other"]},"search":{"description":"Free-text match against description and category.","type":"string"},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":50},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_export_expenses":{"post":{"operationId":"flyra_export_expenses","summary":"Export expenses as CSV","tags":["Expenses"],"description":"Export the expenses between two dates as CSV text, the same file Reports > Expenses > Export downloads in the Flyra web app: Expense Date, Amount, Category, Description, Receipt URL and Created At, the dates read as the organization's calendar days, newest first, with the same optional search over description and category. 500 rows per call and 50,000 rows in all, as on the web. Owners and Admins only. Available per organization; where it is not enabled the reply says so and an admin can export from Reports > Expenses in the web app instead. Page with offset until next_offset is null, then join the csv values (drop the header line on every page but the first) and save the result as a .csv file.\n\nScope: `expenses:read`.","x-required-scope":"expenses:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"start_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First day to include. Calendar date as YYYY-MM-DD (e.g. 2026-07-23)."},"end_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Last day to include. Calendar date as YYYY-MM-DD (e.g. 2026-07-23)."},"search":{"description":"Only expenses whose description or category contains this text, as the Expenses report search.","type":"string","maxLength":200},"offset":{"description":"Row to start from (default 0). Pass the next_offset from the previous call.","type":"integer","minimum":0,"maximum":9007199254740991},"limit":{"description":"Rows per call (default and cap 500).","type":"integer","exclusiveMinimum":0,"maximum":500}},"required":["start_date","end_date"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_expense_summary":{"post":{"operationId":"flyra_get_expense_summary","summary":"Summarize expenses for a period","tags":["Expenses"],"description":"Total business spend for a date range, broken down by category. Aggregated in the database, so it covers every matching expense rather than one page of them. Use this for \"how much did we spend on X\" and for profit questions alongside revenue metrics.\n\nScope: `expenses:read`.","x-required-scope":"expenses:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"start_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Start of the period, inclusive. Calendar date as YYYY-MM-DD (e.g. 2026-07-23)."},"end_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"End of the period, inclusive. Calendar date as YYYY-MM-DD (e.g. 2026-07-23)."}},"required":["start_date","end_date"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_create_expense":{"post":{"operationId":"flyra_create_expense","summary":"Log an expense","tags":["Expenses"],"description":"Log one business expense against the org. Use this when the user reports a purchase, or hands you a receipt to file — read the receipt, then log the total they actually paid.\n\namount is the grand total charged, in the org's currency, tax included. Do not log the pre-tax subtotal, and do not split tax into its own expense.\nexpense_date is the date on the receipt, not today, whenever the receipt shows one.\ndescription is what it was for — put the merchant name in it (e.g. \"Costco fuel, 59.77 L\").\n\nMust be one of Flyra's 12 canonical categories — anything else is dropped from the by-category breakdown on the Expenses report:\n- Cost of Goods Sold: chemicals, soap, supplies that go INTO the service (e.g. window cleaning soap, fertilizer, salt for ice melt)\n- Vehicle and Travel: gas, fuel, oil, parking, tolls, Uber, Lyft, vehicle repair, registration, DMV\n- Office and Admin: office rent, utilities, paper, printer ink, postage\n- Software and Subscriptions: SaaS like Flyra, QuickBooks, Adobe, Google Workspace, Notion, Slack, hosting\n- Marketing and Advertising: Google Ads, Facebook ads, yard signs, flyers, business cards, SEO\n- Payroll and Contractors: wages, 1099 contractor pay, payroll service fees (Gusto, ADP)\n- Equipment and Tools: power washers, ladders, mowers, drills, vacuums, tarps — durable items\n- Insurance and Licenses: liability insurance, vehicle insurance, business license fees, bonding\n- Banking and Finance: bank fees, ATM fees, interest, Stripe/Square processing fees, overdraft fees\n- Meals and Entertainment: restaurant meals, coffee with clients, team lunches\n- Education and Training: courses, books, conferences, certifications\n- Other: everything that genuinely doesn't fit above (rare — try hard to pick a real category first)\n\nTo keep the receipt file with it, pass the image as receipt_image_url (a public https link) or receipt_image_base64, plus receipt_file_name, up to 10 MB; it is stored as the receipt on Reports > Expenses.\n\nScope: `expenses:write`.","x-required-scope":"expenses:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number","exclusiveMinimum":0,"description":"Grand total paid, tax included. Must be greater than zero."},"expense_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Date the money was spent. Calendar date as YYYY-MM-DD (e.g. 2026-07-23)."},"category":{"type":"string","enum":["Cost of Goods Sold","Vehicle and Travel","Office and Admin","Software and Subscriptions","Marketing and Advertising","Payroll and Contractors","Equipment and Tools","Insurance and Licenses","Banking and Finance","Meals and Entertainment","Education and Training","Other"],"description":"Must be one of Flyra's 12 canonical categories — anything else is dropped from the by-category breakdown on the Expenses report:\n- Cost of Goods Sold: chemicals, soap, supplies that go INTO the service (e.g. window cleaning soap, fertilizer, salt for ice melt)\n- Vehicle and Travel: gas, fuel, oil, parking, tolls, Uber, Lyft, vehicle repair, registration, DMV\n- Office and Admin: office rent, utilities, paper, printer ink, postage\n- Software and Subscriptions: SaaS like Flyra, QuickBooks, Adobe, Google Workspace, Notion, Slack, hosting\n- Marketing and Advertising: Google Ads, Facebook ads, yard signs, flyers, business cards, SEO\n- Payroll and Contractors: wages, 1099 contractor pay, payroll service fees (Gusto, ADP)\n- Equipment and Tools: power washers, ladders, mowers, drills, vacuums, tarps — durable items\n- Insurance and Licenses: liability insurance, vehicle insurance, business license fees, bonding\n- Banking and Finance: bank fees, ATM fees, interest, Stripe/Square processing fees, overdraft fees\n- Meals and Entertainment: restaurant meals, coffee with clients, team lunches\n- Education and Training: courses, books, conferences, certifications\n- Other: everything that genuinely doesn't fit above (rare — try hard to pick a real category first)"},"description":{"description":"What it was for, merchant included.","type":"string","maxLength":500},"receipt_image_url":{"description":"A public https link to the receipt image. Pass this or receipt_image_base64, with receipt_file_name.","type":"string"},"receipt_image_base64":{"description":"The receipt image itself as base64. Pass this or receipt_image_url, with receipt_file_name.","type":"string"},"receipt_file_name":{"description":"The receipt's file name, no folders; its extension (.jpg, .png, .gif, .webp, .heic or .pdf) sets the file type. Required with a receipt.","type":"string","maxLength":200,"pattern":"^(?!.*\\.\\.)[^/\\\\]+\\.(jpe?g|png|gif|webp|heic|heif|pdf)$"}},"required":["amount","expense_date","category"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_expense":{"post":{"operationId":"flyra_update_expense","summary":"Update an expense","tags":["Expenses"],"description":"Correct an already-logged expense. Only the fields you pass change; the rest are left alone. To attach or replace its receipt, pass receipt_image_url (a public https link) or receipt_image_base64, plus receipt_file_name, up to 10 MB; the old receipt file is removed once the new one is saved, as on Reports > Expenses.\n\nScope: `expenses:write`.","x-required-scope":"expenses:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"expense_id":{"type":"string","description":"Expense id from flyra_list_expenses (exp_… or a raw UUID)."},"amount":{"type":"number","exclusiveMinimum":0},"expense_date":{"description":"Calendar date as YYYY-MM-DD (e.g. 2026-07-23).","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"category":{"description":"Must be one of Flyra's 12 canonical categories — anything else is dropped from the by-category breakdown on the Expenses report:\n- Cost of Goods Sold: chemicals, soap, supplies that go INTO the service (e.g. window cleaning soap, fertilizer, salt for ice melt)\n- Vehicle and Travel: gas, fuel, oil, parking, tolls, Uber, Lyft, vehicle repair, registration, DMV\n- Office and Admin: office rent, utilities, paper, printer ink, postage\n- Software and Subscriptions: SaaS like Flyra, QuickBooks, Adobe, Google Workspace, Notion, Slack, hosting\n- Marketing and Advertising: Google Ads, Facebook ads, yard signs, flyers, business cards, SEO\n- Payroll and Contractors: wages, 1099 contractor pay, payroll service fees (Gusto, ADP)\n- Equipment and Tools: power washers, ladders, mowers, drills, vacuums, tarps — durable items\n- Insurance and Licenses: liability insurance, vehicle insurance, business license fees, bonding\n- Banking and Finance: bank fees, ATM fees, interest, Stripe/Square processing fees, overdraft fees\n- Meals and Entertainment: restaurant meals, coffee with clients, team lunches\n- Education and Training: courses, books, conferences, certifications\n- Other: everything that genuinely doesn't fit above (rare — try hard to pick a real category first)","type":"string","enum":["Cost of Goods Sold","Vehicle and Travel","Office and Admin","Software and Subscriptions","Marketing and Advertising","Payroll and Contractors","Equipment and Tools","Insurance and Licenses","Banking and Finance","Meals and Entertainment","Education and Training","Other"]},"description":{"type":"string","maxLength":500},"receipt_image_url":{"description":"A public https link to the receipt image. Pass this or receipt_image_base64, with receipt_file_name.","type":"string"},"receipt_image_base64":{"description":"The receipt image itself as base64. Pass this or receipt_image_url, with receipt_file_name.","type":"string"},"receipt_file_name":{"description":"The receipt's file name, no folders; its extension (.jpg, .png, .gif, .webp, .heic or .pdf) sets the file type. Required with a receipt.","type":"string","maxLength":200,"pattern":"^(?!.*\\.\\.)[^/\\\\]+\\.(jpe?g|png|gif|webp|heic|heif|pdf)$"}},"required":["expense_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_delete_expense":{"post":{"operationId":"flyra_delete_expense","summary":"Delete an expense","tags":["Expenses"],"description":"Permanently remove a logged expense, and its stored receipt file with it. There is no undo — confirm with the user before calling.\n\nScope: `expenses:write`. Destructive: it deletes or cancels.","x-required-scope":"expenses:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"expense_id":{"type":"string","description":"Expense id from flyra_list_expenses (exp_… or a raw UUID)."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed this expense should be deleted."}},"required":["expense_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_import_expenses":{"post":{"operationId":"flyra_import_expenses","summary":"Import expenses from a bank or card export","tags":["Expenses"],"description":"Import with AI on Reports > Expenses: hand over a bank statement, credit card export or expense spreadsheet as CSV text and Flyra reads it the way the dialog does. It finds the amount, date, payee and memo columns, leaves out money coming in (deposits, credits, refunds), and files each expense under one of the twelve expense categories. Use it instead of calling flyra_create_expense row by row.\n\nThe FIRST call is a dry run that saves nothing: it returns how many expenses will import, how many rows were left out as credits or unreadable, the total per category, a sample and a confirm_token. Show the user, then call again with the SAME csv and that token to import. Up to 5,000 rows and 5 MB per file. Receipt images are not part of an import.\n\nNothing is sent to anyone. Undo within 24 hours with flyra_undo_expense_import.\n\nScope: `expenses:write`.","x-required-scope":"expenses:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"csv":{"type":"string","minLength":1,"description":"The whole file as CSV text, header row included, exactly as exported. Convert a spreadsheet to CSV first."},"filename":{"description":"The file the rows came from, recorded with the import.","type":"string","maxLength":255},"confirm_token":{"description":"The token from this tool's dry run. Required to import.","type":"string"}},"required":["csv"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_undo_expense_import":{"post":{"operationId":"flyra_undo_expense_import","summary":"Undo an expense import","tags":["Expenses"],"description":"Undo after Import with AI on Reports > Expenses: deletes every expense one import added. Only within 24 hours of the import, and only once.\n\nPass the import_job_id flyra_import_expenses returned. The person who ran the import, or an Admin or Owner, can undo it. Confirm with the user first: the expenses are deleted, not archived.\n\nScope: `expenses:write`. Destructive: it deletes or cancels.","x-required-scope":"expenses:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"import_job_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"From flyra_import_expenses."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed these expenses are deleted."}},"required":["import_job_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_payroll":{"post":{"operationId":"flyra_get_payroll","summary":"Get payroll for a period","tags":["Payroll"],"description":"What every person earned over a pay period: revenue credited, commission, hourly pay, tips, bonuses, upline overrides, and the total payout. Runs the same code as the Reports → Payroll page, so the numbers match what the owner sees. Sales payroll credits the person who sold the job; technician payroll credits whoever was dispatched to it. Omit `period` to report on the org's own pay period, which is what a paycheck is actually cut on.\n\nScope: `payroll:read`.","x-required-scope":"payroll:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"payroll_type":{"description":"Which side to report. Omit for both, which is usually what someone means by \"payroll\".","type":"string","enum":["sales","technician"]},"period":{"type":"object","properties":{"start":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"end":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["start","end"],"description":"Explicit window as YYYY-MM-DD dates. Omit to use the org's own pay period, which is what a paycheck is actually cut on — prefer omitting it unless the user names dates."},"pay_period":{"type":"string","enum":["current","previous"],"description":"Which of the org's own pay periods to report on. Ignored when `period` is given. Defaults to current."},"employee_ids":{"description":"Limit to these employees. Omit for the whole roster.","type":"array","items":{"type":"string"}},"subscriptions_only":{"description":"Only count jobs that belong to a recurring plan.","type":"boolean"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_employee_payroll":{"post":{"operationId":"flyra_get_employee_payroll","summary":"Get one person's payroll","tags":["Payroll"],"description":"One person's pay for a period, with the rates that produced it and, on request, the job-by-job breakdown behind the number. Shows the rate actually applied — a one-period override replaces the standing rate and is reported as such. Use this to answer \"what did X earn\" or \"why is X's pay lower than expected\".\n\nScope: `payroll:read`.","x-required-scope":"payroll:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"string","description":"Employee id from flyra_list_employees."},"payroll_type":{"description":"Omit for both sides.","type":"string","enum":["sales","technician"]},"period":{"type":"object","properties":{"start":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"end":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["start","end"],"description":"Explicit window as YYYY-MM-DD dates. Omit to use the org's own pay period, which is what a paycheck is actually cut on — prefer omitting it unless the user names dates."},"pay_period":{"type":"string","enum":["current","previous"],"description":"Which of the org's own pay periods to report on. Ignored when `period` is given. Defaults to current."},"include_jobs":{"description":"Include the individual jobs that make up the pay. Off by default.","type":"boolean"}},"required":["employee_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_employee_hours":{"post":{"operationId":"flyra_get_employee_hours","summary":"Get an employee's worked hours","tags":["Payroll"],"description":"Hours behind a person's pay for a period. Reports clocked hours from the time clock when the org runs time tracking, and otherwise the job hours the org's own time method counts (scheduled window, on-site time, or start to finish). This is the same hours figure payroll pays on, so it can differ from raw job timestamps. `period` takes any start and end date here, one week included, whatever the org's pay period is. For an effective hourly rate, divide what flyra_get_employee_payroll reports the person earned over the same period by hours_paid.\n\nScope: `payroll:read`.","x-required-scope":"payroll:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"string"},"payroll_type":{"description":"Defaults to technician, the side hours usually matter on.","type":"string","enum":["sales","technician"]},"period":{"type":"object","properties":{"start":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"end":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["start","end"],"description":"Explicit window as YYYY-MM-DD dates. Omit to use the org's own pay period, which is what a paycheck is actually cut on — prefer omitting it unless the user names dates."},"pay_period":{"type":"string","enum":["current","previous"],"description":"Which of the org's own pay periods to report on. Ignored when `period` is given. Defaults to current."}},"required":["employee_id"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_pay_rates":{"post":{"operationId":"flyra_get_pay_rates","summary":"Get pay rates","tags":["Payroll"],"description":"The standing pay rates for one person or the whole roster: pay type, commission percents (standard, subscription, initial visit, upsell, shared-job), hourly rate, and tier ladder. Includes the effective-dated history, so you can see what a rate was on the day a job happened. Read this before changing a rate.\n\nScope: `payroll:read`.","x-required-scope":"payroll:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"description":"Omit for every person with a rate on file.","type":"string"},"payroll_type":{"description":"Omit for both sides.","type":"string","enum":["sales","technician"]},"include_history":{"description":"Include past rates and their effective dates.","type":"boolean"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_payroll_settings":{"post":{"operationId":"flyra_get_payroll_settings","summary":"Get payroll settings","tags":["Payroll"],"description":"The rules every payroll number is computed under: pay period shape, how hours are measured, whether commission is split across a crew, whether it is taken before or after discounts, whether unpaid jobs are held back, upline override model, org default rates, and the linear-foot plan when one is running. Read this when a number looks surprising. Apart from linear foot pay (flyra_update_linear_foot_pay), the pay period and default commission (flyra_update_pay_period_and_commission) and whether employees see their own tips (employee_tips_visible, flyra_set_employee_tips_visible), these settings are not editable through the API: one wrong call re-rates the whole company. When the user wants one changed, tell them where it is: Reports > Payroll, the gear icon, which opens Payroll Settings. Commission before or after discounts is the \"Commission on pre-discount price\" switch under Commission rules, next to the crew and sales split switches; pay period shape is under Pay period. Sales tiers counted by the pay period a job was sold in (payroll_sales_tier_by_sold_period) and the tier rate paid on the whole pay period (payroll_sales_tier_whole_period) are the two switches under Commission rules, after the pre-discount one. When a job counts (scheduled, paid, or paid and completed; payroll_exclude_until_paid + payroll_exclude_until_completed) and paying one period behind are under Job filters; sales rate cuts (payroll_sales_rate_cuts) have their own Rate cuts section; technician ranks (payroll_technician_ranks) have a Technician ranks section, and a technician is put in a rank on their own payroll page; the override gate (payroll_override_gate_enabled with its ARR and card-on-file targets, which make an upline earn the override on a rep only in pay periods where the rep hit both) is under Overrides. The technician's share of each tip (payroll_tip_technician_share_percent, 100 = the whole tip) has no screen yet; Flyra support sets it.\n\nScope: `payroll:read`.","x-required-scope":"payroll:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_linear_foot_pay":{"post":{"operationId":"flyra_update_linear_foot_pay","summary":"Set up linear foot pay","tags":["Payroll"],"description":"The Linear foot section of Payroll Settings (Reports > Payroll, the gear icon). Linear foot pay is on when the business's default line item unit (default_line_item_unit) is a foot unit such as \"linear ft\"; setting it here switches it on, and any other unit or null switches it off. Only lines measured in feet pay on it. Each side is paid by payroll_foot_sales_basis / payroll_foot_technician_basis: revenue (the usual commission, the default), redline (a share of what a sale cleared above payroll_redline_rate_cents per foot; the two share percents together are at most 100) or per_foot (a rate per foot; the business defaults are default_sales_rate_per_unit_cents and default_technician_rate_per_unit_cents). Send only what changes; null clears a number. This re-rates every job paid under it, so confirm the plan with the user first. Admins and Owners only, signed in as a person.\n\nScope: `payroll:write`. Destructive: it deletes or cancels.","x-required-scope":"payroll:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"default_line_item_unit":{"description":"The default unit for a blank line item. A foot unit (\"linear ft\") turns linear foot pay on.","anyOf":[{"type":"string"},{"type":"null"}]},"payroll_foot_sales_basis":{"type":"string","enum":["revenue","redline","per_foot"]},"payroll_foot_technician_basis":{"type":"string","enum":["revenue","redline","per_foot"]},"payroll_redline_rate_cents":{"description":"The redline, in cents per foot (3000 = $30/ft).","anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"payroll_redline_sales_share_percent":{"description":"The sales side's share of the amount above the redline.","anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}]},"payroll_redline_technician_share_percent":{"description":"The installer side's share of the amount above the redline.","anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}]},"default_sales_rate_per_unit_cents":{"description":"per_foot: the business default, cents per foot for salespeople.","anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"default_technician_rate_per_unit_cents":{"description":"per_foot: the business default, cents per foot for technicians (250 = $2.50/ft).","anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed this pay plan, which changes what people are paid."}},"required":["confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_service_foot_rate":{"post":{"operationId":"flyra_set_service_foot_rate","summary":"Set a per foot pay rate on a price book item","tags":["Payroll"],"description":"Linear foot pay, per foot plan: what a salesperson (sales_rate_per_unit_cents) or technician (technician_rate_per_unit_cents) earns per foot on job lines added from this price book item, e.g. 250 = $2.50/ft on \"Standard one story\", 400 = $4/ft on \"Two story\". A job line uses the item whose name or title matches its title. Pay order per foot: the item rate, then the person's own rate (flyra_set_pay_rate rate_per_unit_cents), then the business default. Applies only while that side's basis is per_foot (flyra_update_linear_foot_pay). null clears a rate. Get service_id from flyra_list_services. This re-rates every job paid under it, so confirm with the user first. Admins and Owners only, signed in as a person.\n\nScope: `payroll:write`. Destructive: it deletes or cancels.","x-required-scope":"payroll:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"service_id":{"type":"string","description":"The price book item (svc_ semantic id or raw UUID) from flyra_list_services."},"sales_rate_per_unit_cents":{"description":"Cents per foot for salespeople on this item. null clears it.","anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"technician_rate_per_unit_cents":{"description":"Cents per foot for technicians on this item (250 = $2.50/ft). null clears it.","anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed this rate, which changes what people are paid."}},"required":["service_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_update_pay_period_and_commission":{"post":{"operationId":"flyra_update_pay_period_and_commission","summary":"Change pay period and default commission","tags":["Payroll"],"description":"The Pay period section and the business default commission of Payroll Settings (Reports > Payroll, the gear icon). pay_period_config sets the period per side (sales, technician): type weekly, biweekly, semi_monthly or monthly; startWeekday 0-6 (Sunday = 0, weekly only); anchorDate YYYY-MM-DD (first day of one biweekly cycle); spanDays (days paid out of a weekly or biweekly cycle, null = all). null puts both sides back on pay_period_type and pay_period_anchor_date. default_*_commission_percent is the default rate; default_*_commission_tiers is a tier ladder (each rate applies only to revenue inside its bracket; first tier min_revenue 0, rates 0-100, no repeated thresholds), null removes it. Send only what changes. This re-rates every job paid under these defaults, so confirm with the user first. Admins and Owners only, signed in as a person.\n\nScope: `payroll:write`. Destructive: it deletes or cancels.","x-required-scope":"payroll:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"pay_period_type":{"description":"The older one-period-for-everyone setting.","type":"string","enum":["weekly","biweekly","semi_monthly","monthly"]},"pay_period_anchor_date":{"description":"YYYY-MM-DD, for pay_period_type.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"pay_period_config":{"anyOf":[{"type":"object","properties":{"sales":{"description":"{ type, startWeekday, anchorDate, spanDays }","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"technician":{"description":"{ type, startWeekday, anchorDate, spanDays }","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}}},{"type":"null"}]},"default_sales_commission_percent":{"anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}]},"default_technician_commission_percent":{"anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}]},"default_sales_commission_tiers":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"min_revenue":{"type":"number"},"percent":{"type":"number"}},"required":["min_revenue","percent"]}},{"type":"null"}]},"default_technician_commission_tiers":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"min_revenue":{"type":"number"},"percent":{"type":"number"}},"required":["min_revenue","percent"]}},{"type":"null"}]},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed this change, which changes what people are paid."}},"required":["confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_employee_tips_visible":{"post":{"operationId":"flyra_set_employee_tips_visible","summary":"Show or hide employees' own tips","tags":["Payroll"],"description":"The \"Show employees their own tips\" switch in the Tips section of Payroll Settings (Reports > Payroll, the gear icon). On, each person tipped in the last 90 days sees a tips card on the mobile dashboard with only their own tips. Off, that card is gone for everyone and tips are left off the pay statements of anyone who is not an admin. It is one switch for the whole business: there is no way to show tips to some roles and not others. Admins and Owners only, signed in as a person.\n\nScope: `payroll:write`.","x-required-scope":"payroll:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"visible":{"type":"boolean","description":"true shows employees their own tips; false hides them."}},"required":["visible"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_pay_statement":{"post":{"operationId":"flyra_get_pay_statement","summary":"Get a pay statement","tags":["Payroll"],"description":"The Pay page (for admins, Reports > Payroll > Pay statements): a person's saved pay statements, read from the copies frozen when their pay was marked paid, so nothing is recomputed. Returns their newest weeks (eight at most) and one statement: the week named by period_start (and period_end), else the newest. Over the connector only Owners and Admins can use this (payroll is closed to every other role). They may name any person, and also get everyone with a paid week. Tips and prices are hidden where the company hides them on that page. Needs a signed-in Flyra user. Read only.\n\nScope: `payroll:read`.","x-required-scope":"payroll:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"description":"Whose pay (emp_… or a raw UUID). Omit for your own. Admins only for anyone else.","type":"string"},"period_start":{"description":"First day of the paid week to show. Calendar date as YYYY-MM-DD (e.g. 2026-09-01).","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"period_end":{"description":"Last day of that week, when two paid ranges start the same day. Calendar date as YYYY-MM-DD (e.g. 2026-09-01).","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"payroll_type":{"description":"Which payroll to show. Omit for the kind of their newest paid week.","type":"string","enum":["sales","technician"]}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_get_timesheet":{"post":{"operationId":"flyra_get_timesheet","summary":"Get the timesheet","tags":["Payroll"],"description":"Reports > Payroll > Timesheets: each person's clocked shifts for a range of the company's own calendar days, hours per day (a shift over midnight is split across the days it touches) and in total, with each shift's id, clock-in and clock-out, whether it was edited (and its original times), its note, where each punch happened, and open or very long shifts flagged. Over the connector only Owners and Admins can use this (payroll is closed to every other role); they see everyone, or one person with employee_id. canEdit says whether the caller may change it with flyra_edit_timesheet. Needs a signed-in Flyra user. Read only.\n\nScope: `payroll:read`.","x-required-scope":"payroll:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First day. Calendar date as YYYY-MM-DD (e.g. 2026-09-01)."},"end":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Last day, inclusive. Calendar date as YYYY-MM-DD (e.g. 2026-09-01)."},"employee_id":{"description":"Only this person (emp_… or a raw UUID).","type":"string"}},"required":["start","end"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_export_timesheets":{"post":{"operationId":"flyra_export_timesheets","summary":"Export the timesheet as CSV","tags":["Payroll"],"description":"Export Reports > Payroll > Timesheets as CSV text, the same files the tab's Export and Export detail buttons download in the Flyra web app. Export (detail false, the default): Employee, Role, Pay type, hours for each day and Total hours, one line per person. Export detail: Employee, Date, Clock in, Clock in location, Clock out, Clock out location, Hours, Source, Edited, Edited by and Note, one line per shift per day, times in the company's own clock. Days are the company's calendar days. As on the screen, people with no hours and no open shift are left out unless show_empty is true, and needs_attention_only keeps only people with an open, very long or edited shift. 500 lines per call. Owners and Admins only; needs a signed-in Flyra user. Available per organization; where it is not enabled the reply says so and an admin can export from Reports > Payroll > Timesheets in the web app instead. Page with offset until next_offset is null, then join the csv values (drop the header line on every page but the first) and save the result as a .csv file.\n\nScope: `payroll:read`.","x-required-scope":"payroll:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First day. Calendar date as YYYY-MM-DD (e.g. 2026-09-01)."},"end":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Last day, inclusive. Calendar date as YYYY-MM-DD (e.g. 2026-09-01)."},"employee_id":{"description":"Only this person (emp_… or a raw UUID), as the tab's person filter.","type":"string"},"detail":{"description":"true: Export detail (one line per shift). false or omitted: Export (one line per person).","type":"boolean"},"show_empty":{"description":"Include people with no hours and no open shift (default false, as the screen).","type":"boolean"},"needs_attention_only":{"description":"Only people with an open, very long or edited shift (default false).","type":"boolean"},"offset":{"description":"Line to start from (default 0). Pass the next_offset from the previous call.","type":"integer","minimum":0,"maximum":9007199254740991},"limit":{"description":"Lines per call (default and cap 500).","type":"integer","exclusiveMinimum":0,"maximum":500}},"required":["start","end"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_export_payroll":{"post":{"operationId":"flyra_export_payroll","summary":"Export payroll as CSV","tags":["Payroll"],"description":"Export one payroll section on Reports > Payroll as CSV text, the same file its Export CSV downloads in the Flyra web app: Employee, Email, Role, Pay Type, Commission %, Revenue, (Feet, Margin, Foot Pay when the foot plan runs), Commission, Hours Worked, Hourly Payout, Tips, (Bonus when anyone has one) and Total Payout, money in the organization's currency. payroll_type picks Sales Payroll (default) or Technician Payroll; the window is resolved as flyra_get_payroll resolves it (the org's own pay period unless period is given). 500 rows per call. Owners and Admins only. Available per organization; where it is not enabled the reply says so and an admin can export from Reports > Payroll in the web app instead. Page with offset until next_offset is null, then join the csv values (drop the header line on every page but the first) and save the result as a .csv file.\n\nScope: `payroll:read`.","x-required-scope":"payroll:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"payroll_type":{"description":"sales (default) or technician.","type":"string","enum":["sales","technician"]},"period":{"type":"object","properties":{"start":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"end":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["start","end"],"description":"Explicit window as YYYY-MM-DD dates. Omit to use the org's own pay period, which is what a paycheck is actually cut on — prefer omitting it unless the user names dates."},"pay_period":{"type":"string","enum":["current","previous"],"description":"Which of the org's own pay periods to report on. Ignored when `period` is given. Defaults to current."},"employee_ids":{"description":"Limit to these employees. Omit for the whole roster.","type":"array","items":{"type":"string"}},"subscriptions_only":{"description":"Only count jobs that belong to a recurring plan.","type":"boolean"},"offset":{"description":"Row to start from (default 0). Pass the next_offset from the previous call.","type":"integer","minimum":0,"maximum":9007199254740991},"limit":{"description":"Rows per call (default and cap 500).","type":"integer","exclusiveMinimum":0,"maximum":500}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_edit_timesheet":{"post":{"operationId":"flyra_edit_timesheet","summary":"Edit the timesheet","tags":["Payroll"],"description":"Save changes on Reports > Payroll > Timesheets: correct clocked shifts in one batch. Edits are saved in order, so if one is refused (an overlap, a bad time) the ones before it stay saved: re-read with flyra_get_timesheet before sending the rest. update moves a shift's clock-in and/or clock-out (null clock-out reopens it) or changes its note; the first time it moves, its original times are kept and it shows as edited. create adds a finished shift by hand for an employee. A shift must end after it starts and cannot overlap another of that person's shifts. Owners and Admins only over the connector (payroll is closed to every other role), and only while time tracking is on. Hours follow the times, and payroll's clocked hours with them. Get shift ids from flyra_get_timesheet. Confirm the changes with the user first: they change what people are paid. Needs a signed-in Flyra user.\n\nScope: `payroll:write`. Destructive: it deletes or cancels.","x-required-scope":"payroll:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"edits":{"minItems":1,"maxItems":200,"type":"array","items":{"oneOf":[{"type":"object","properties":{"op":{"type":"string","const":"update"},"entry_id":{"type":"string","description":"The shift id, from flyra_get_timesheet."},"clocked_in_at":{"description":"New clock-in, ISO 8601 with offset.","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"clocked_out_at":{"description":"New clock-out, ISO 8601 with offset; null reopens the shift.","anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"note":{"description":"null clears the note.","anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]}},"required":["op","entry_id"]},{"type":"object","properties":{"op":{"type":"string","const":"create"},"employee_id":{"type":"string","description":"Whose shift (emp_… or a raw UUID)."},"clocked_in_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"Clock-in, ISO 8601 with offset."},"clocked_out_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"Clock-out, ISO 8601 with offset."},"note":{"type":"string","maxLength":1000}},"required":["op","employee_id","clocked_in_at","clocked_out_at"]}]}},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed these shift changes, which change hours and pay."}},"required":["edits","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_delete_time_entry":{"post":{"operationId":"flyra_delete_time_entry","summary":"Remove a shift from the timesheet","tags":["Payroll"],"description":"Remove one clocked shift on Reports > Payroll > Timesheets, as removing it in the grid and saving does: its hours leave the timesheet and payroll's clocked hours. Owners and Admins only over the connector (payroll is closed to every other role), while time tracking is on. Confirm with the user first. Get the id from flyra_get_timesheet. Needs a signed-in Flyra user.\n\nScope: `payroll:write`. Destructive: it deletes or cancels.","x-required-scope":"payroll:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"entry_id":{"type":"string","description":"The shift id, from flyra_get_timesheet."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed this shift should be removed."}},"required":["entry_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_pay_rate":{"post":{"operationId":"flyra_set_pay_rate","summary":"Set a person's pay rate","tags":["Payroll"],"description":"Set what one person is paid on one side of payroll, from a date forward. Writes the standing rate AND a dated history row (on a person's first change, their old rate is filed first). Weeks ticked Paid keep their pay, but Reports > Payroll prices every unpaid week from the standing rate, so earlier unpaid weeks move to the new rate too; only sales reps in orgs with rate at sale on keep the old rate on jobs sold before `effective_from`. history_saved: false means the dated row failed: call again with the same values. Pass only the fields you are changing; anything omitted keeps its current value. `commission_tiers` sets this one person's tier ladder, which is not dated (see that argument). Read flyra_get_pay_rates first, and confirm the new rate with the user before calling — this changes what a person is paid.\n\nScope: `payroll:write`. Destructive: it deletes or cancels.","x-required-scope":"payroll:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"string"},"payroll_type":{"type":"string","enum":["sales","technician"],"description":"Which side this rate applies to. A person can have both."},"commission_percent":{"type":"number","minimum":0,"maximum":100,"description":"Standard commission as a percentage, 0 to 100 (12.5 means 12.5%)."},"subscription_commission_percent":{"description":"Sales only. Null clears it, so plan visits pay the standard rate.","anyOf":[{"type":"number","minimum":0,"maximum":100,"description":"Commission on recurring plan visits as a percentage, 0 to 100 (12.5 means 12.5%)."},{"type":"null"}]},"upsell_commission_percent":{"anyOf":[{"type":"number","minimum":0,"maximum":100,"description":"Commission on upsells as a percentage, 0 to 100 (12.5 means 12.5%)."},{"type":"null"}]},"shared_job_commission_percent":{"description":"Used when two or more people are credited on one job and the org does not split the rate.","anyOf":[{"type":"number","minimum":0,"maximum":100,"description":"Commission when the job is shared with others as a percentage, 0 to 100 (12.5 means 12.5%)."},{"type":"null"}]},"pay_type":{"description":"How this person is paid. `both` pays commission and hourly.","type":"string","enum":["commission","hourly","both"]},"hourly_rate_cents":{"description":"Cents per hour (2500 = $25.00/hr). Required when pay_type includes hourly.","anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"rate_per_unit_cents":{"description":"This one person's pay per linear foot, in cents (45 = $0.45/ft): the \"Per foot\" box on their payroll page. Only used on a side whose foot pay basis is per_foot (flyra_update_linear_foot_pay sets the basis and the company default). Null clears it, so the person falls back to the company rate. Like the payroll page, it is not dated: Reports > Payroll uses it for every pay period, earlier ones included.","anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"commission_tiers":{"description":"A tier ladder: the \"Commission tiers\" option under Commission on the person's payroll page. Each percent applies only to the dollars inside its bracket, and a person's own ladder replaces their flat commission_percent. The first bracket starts at 0 and no two brackets start at the same amount. Null clears it, so the person falls back to the company's default ladder (when it has two or more brackets) or their flat rate. The ladder is not dated: like a save on that page, Reports > Payroll uses it for every pay period, earlier ones included, so effective_from does not apply to it. Needs a pay type that includes commission.","anyOf":[{"minItems":1,"type":"array","items":{"type":"object","properties":{"min_revenue":{"type":"number","minimum":0,"description":"Where this bracket starts, in dollars of the person's revenue. The first bracket starts at 0."},"percent":{"type":"number","minimum":0,"maximum":100,"description":"Commission on the dollars inside this bracket as a percentage, 0 to 100 (12.5 means 12.5%)."}},"required":["min_revenue","percent"]}},{"type":"null"}]},"effective_from":{"description":"Calendar date as YYYY-MM-DD (e.g. 2026-09-01). The date the new rate starts. Defaults to today. Earlier unpaid weeks may still change (see the tool description).","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed this rate, which changes what this person is paid."}},"required":["employee_id","payroll_type","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_job_pay_override":{"post":{"operationId":"flyra_set_job_pay_override","summary":"Override pay on one job","tags":["Payroll"],"description":"Change what one person earns on one specific job, without touching their standing rate. Use it to pay a different percent on a single job, to pay a fixed dollar amount on it (`pay_amount_cents`, e.g. a flat $18 a job whatever the job is charged), to exclude a job from someone's pay entirely, or to set the feet credited to them. A dollar amount is their whole pay on that job: it replaces the percent, any upsell add-on and any per-foot pay there, and does not apply to hourly pay. Setting a percent clears a dollar amount and the other way round. On a company that pays by the linear foot, the percent does not move a foot-paid job — set `units` or `pay_amount_cents` instead. Pass `clear: true` to drop the override and fall back to the normal rate. Confirm with the user before calling and pass confirm: true.\n\nScope: `payroll:write`. Destructive: it deletes or cancels.","x-required-scope":"payroll:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string"},"employee_id":{"type":"string"},"payroll_type":{"type":"string","enum":["sales","technician"]},"commission_percent":{"anyOf":[{"type":"number","minimum":0,"maximum":100,"description":"Commission for this job only as a percentage, 0 to 100 (12.5 means 12.5%)."},{"type":"null"}]},"pay_amount_cents":{"description":"A fixed amount this person earns on this job, in cents (1800 = $18.00), in place of their percent. Null clears it; leave it out to keep what is set.","anyOf":[{"type":"integer","minimum":0,"maximum":2147483647},{"type":"null"}]},"excluded":{"description":"True pays this person nothing on this job.","type":"boolean"},"units":{"description":"Linear feet credited to this person on this job. Only meaningful when the org pays by the foot.","anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"clear":{"description":"Remove any override on this job and use the standing rate.","type":"boolean"},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed this change to what this person earns on this job."}},"required":["job_id","employee_id","payroll_type","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_period_pay_override":{"post":{"operationId":"flyra_set_period_pay_override","summary":"Override a person's rate for one pay period","tags":["Payroll"],"description":"Pay someone a different rate for a single pay period, leaving their standing rate alone. Use it for a one-off month, a trial rate, or a correction. Omit `period` to target the org's current pay period; a `period` must be exactly one of the org's pay periods. Pass `clear: true` to drop the override. Confirm with the user before calling and pass confirm: true.\n\nScope: `payroll:write`. Destructive: it deletes or cancels.","x-required-scope":"payroll:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"string"},"payroll_type":{"type":"string","enum":["sales","technician"]},"period":{"type":"object","properties":{"start":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"end":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["start","end"],"description":"Explicit window as YYYY-MM-DD dates. Omit to use the org's own pay period, which is what a paycheck is actually cut on — prefer omitting it unless the user names dates."},"pay_period":{"type":"string","enum":["current","previous"],"description":"Which of the org's own pay periods to report on. Ignored when `period` is given. Defaults to current."},"commission_percent":{"anyOf":[{"type":"number","minimum":0,"maximum":100,"description":"Commission for this period only as a percentage, 0 to 100 (12.5 means 12.5%)."},{"type":"null"}]},"subscription_commission_percent":{"anyOf":[{"type":"number","minimum":0,"maximum":100,"description":"Recurring plan commission for this period only as a percentage, 0 to 100 (12.5 means 12.5%)."},{"type":"null"}]},"hourly_rate_cents":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"clear":{"description":"Remove the override for this period.","type":"boolean"},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed this period's rate, which changes what this person is paid."}},"required":["employee_id","payroll_type","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_add_payroll_bonus":{"post":{"operationId":"flyra_add_payroll_bonus","summary":"Add a one-off bonus to payroll","tags":["Payroll"],"description":"Add a one-off bonus for one person on one day, as the Add bonus popup on their payroll page does (Reports > Payroll, open the person). It counts in the pay period that holds that day, and the payroll reads show it in one_off_bonuses and total_payout. The amount is in cents and must be above zero: the popup takes no deductions. Owners and Admins only (payroll is closed to every other role over the connector, and the bonus route needs the Admin role). Confirm the person, the amount and the day with the user first: this changes what a person is paid. Needs a signed-in Flyra user.\n\nScope: `payroll:write`.","x-required-scope":"payroll:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"string","description":"Who gets the bonus (emp_… or a raw UUID)."},"payroll_type":{"type":"string","enum":["sales","technician"],"description":"Which payroll it lands on: sales or technician."},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The day the bonus belongs to; it is paid in the pay period holding this day. Calendar date as YYYY-MM-DD (e.g. 2026-09-01)."},"amount_cents":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The bonus in cents (2500 = $25.00). Above zero."},"reason":{"description":"What it is for, shown beside the bonus.","type":"string"},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed the person, amount and day."}},"required":["employee_id","payroll_type","date","amount_cents","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_preview_mark_paid":{"post":{"operationId":"flyra_preview_mark_paid","summary":"Preview marking everyone paid for a pay period","tags":["Payroll"],"description":"Preview of the \"Mark everyone paid\" button on Reports > Payroll: for one pay period of the sales or technician payroll, every person on the list with their total, whether they are already marked paid, and who one press would mark. Nothing is changed. The period is picked on the business's own calendar (its time zone). Pass expected_count and expected_total from here to flyra_mark_pay_period_paid. Owners and Admins only. Needs a signed-in Flyra user. Read only.\n\nScope: `payroll:read`.","x-required-scope":"payroll:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"payroll_type":{"type":"string","enum":["sales","technician"],"description":"Which section of Reports > Payroll: sales or technician. Each has its own button."},"period":{"description":"One whole pay period as its first and last day (YYYY-MM-DD). Omit to use pay_period.","type":"object","properties":{"start":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"end":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["start","end"]},"pay_period":{"type":"string","enum":["current","previous"],"description":"Which of the org's own pay periods to report on. Ignored when `period` is given. Defaults to current."}},"required":["payroll_type"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_mark_pay_period_paid":{"post":{"operationId":"flyra_mark_pay_period_paid","summary":"Mark everyone paid for a pay period","tags":["Payroll"],"description":"The \"Mark everyone paid\" button on Reports > Payroll: marks every person on the period's list who is not yet marked paid, one at a time, with the same save as ticking their Paid box (their pay statement is frozen at the total shown, and where employees see their pay they may get a \"You got paid\" notification). It records payment only; it moves no money. Call flyra_preview_mark_paid first, confirm the people and the total with the user, and pass its expected_count and expected_total; if the live list no longer matches, nobody is marked. It stops at the first person refused (for example a total that changed), and the people already marked stay marked. Owners and Admins only. Needs a signed-in Flyra user.\n\nScope: `payroll:write`.","x-required-scope":"payroll:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"payroll_type":{"type":"string","enum":["sales","technician"],"description":"Which section of Reports > Payroll: sales or technician. Each has its own button."},"period":{"description":"One whole pay period as its first and last day (YYYY-MM-DD). Omit to use pay_period.","type":"object","properties":{"start":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"end":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["start","end"]},"pay_period":{"type":"string","enum":["current","previous"],"description":"Which of the org's own pay periods to report on. Ignored when `period` is given. Defaults to current."},"expected_count":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"expected_count from flyra_preview_mark_paid: how many people would be marked."},"expected_total":{"type":"number","minimum":0,"description":"expected_total from flyra_preview_mark_paid: their combined total, in dollars."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed the people and the total."}},"required":["payroll_type","expected_count","expected_total","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_set_upline":{"post":{"operationId":"flyra_set_upline","summary":"Put a person under a manager (downline)","tags":["Payroll"],"description":"Put one person under a manager, or take them out from under anyone, as dragging a card in the Reports > Payroll tree view does. The manager is their upline: where upline overrides are on, the manager earns an override on this person. Pass upline_employee_id null to detach. Refused when the person would end up under themselves (a cycle). Owners and Admins only (payroll is closed to every other role over the connector). Confirm with the user first: this changes what the manager is paid. Read the tree with flyra_get_employee_payroll (its upline field). Needs a signed-in Flyra user.\n\nScope: `payroll:write`.","x-required-scope":"payroll:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"string","description":"The person being moved (emp_… or a raw UUID)."},"upline_employee_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Their new manager (emp_… or a raw UUID), or null to detach them."},"confirm":{"type":"boolean","const":true,"description":"Must be true: the user has confirmed this move."}},"required":["employee_id","upline_employee_id","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_list_quality_checks":{"post":{"operationId":"flyra_list_quality_checks","summary":"List quality checks","tags":["Payroll"],"description":"The Reports → Payroll → Quality checks list: completed jobs whose photos an admin has approved, is still waiting to review (pending), or sent back to the tech to redo (rejected). Defaults to APPROVED jobs in the org's current pay period, which is the gate for paying a job when quality checks hold payroll: approved_at is the date the job enters payroll. Each row names the job (pass job_id to the job tools for line items, notes and crew), when it was completed, who submitted and who approved it, the review note, the photo count and the job amount in cents. `waived` means an admin closed it without photos. `resubmitted` means the tech redid photos an admin sent back; `rejection_count` is how many times it was sent back, and `last_rejection_note` is what was asked for last time. Read only: approve or send back with flyra_review_quality_check.\n\nScope: `payroll:read`.","x-required-scope":"payroll:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"approved (default), pending (waiting for review), rejected (sent back, waiting on the tech), or all. The period only applies to approved.","type":"string","enum":["approved","pending","rejected","all"]},"period":{"type":"object","properties":{"start":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"end":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["start","end"],"description":"Explicit window as YYYY-MM-DD dates. Omit to use the org's own pay period, which is what a paycheck is actually cut on — prefer omitting it unless the user names dates."},"pay_period":{"type":"string","enum":["current","previous"],"description":"Which of the org's own pay periods to report on. Ignored when `period` is given. Defaults to current."}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2026-06-01/actions/flyra_review_quality_check":{"post":{"operationId":"flyra_review_quality_check","summary":"Approve or send back a quality check","tags":["Payroll"],"description":"The Approve and Send back buttons on a job's quality check (on the job, and in Reports → Payroll → Quality checks). approve passes the photos: the job enters payroll with today as its approved date, which puts it in the current pay period where quality checks hold payroll. Approval is final and cannot be undone here or in the app; a mistake is fixed with a payroll adjustment. reject sends it back to the tech to redo, with a note saying what needs fixing (required); the job stays out of payroll until new photos are approved. Either way the team member who submitted the photos gets a push notification on their phone with the verdict (the note, for a send back). No customer is messaged. Admins and Owners only, and only while quality checks are on. Needs a signed-in Flyra user. Answers with the check as it now stands.\n\nScope: `payroll:write`. Destructive: it deletes or cancels.","x-required-scope":"payroll:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"The job whose check to review: job_id from flyra_list_quality_checks or a job UUID."},"decision":{"type":"string","enum":["approve","reject"],"description":"approve (final, the job enters payroll) or reject (send back to redo)."},"note":{"description":"What needs fixing; required to reject. On approve, an optional review note.","type":"string","maxLength":500},"confirm":{"type":"boolean","const":true,"description":"Must be true: an approval puts the job in a pay period and cannot be undone, and either verdict notifies the tech."}},"required":["job_id","decision","confirm"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The action's result."}}}}}},"400":{"description":"Validation error. `errors` lists each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`scope_denied`: the key lacks the `x-required-scope`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not in this key's organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Understood but not done. `code` and `hint` say why (for example `opted_out`, `missing_phone`, `SMS_SETUP_INCOMPLETE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"flr_live_…","description":"API key with `flr_live_` prefix. Manage keys at [Developer](https://app.flyra.io/developer) in the Flyra sidebar."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable code (e.g. `scope_denied`, `validation_error`, `duplicate_customer`)."},"errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}},"description":"Per-field validation errors when `code: \"validation_error\"`."},"required_scope":{"type":"string","description":"When `code: \"scope_denied\"`, names the missing scope (e.g. `jobs:write`)."},"details":{"type":"string","description":"Free-form additional detail (DB errors, etc.)."}}},"Customer":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"email":{"type":"string","format":"email","nullable":true},"mobile_phone":{"type":"string","nullable":true,"description":"E.164 preferred (e.g. `+15551234567`)."},"address":{"type":"string","nullable":true},"unit":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"zip":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true,"description":"Legacy alias for `zip` — same value."},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"notes":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"},"nullable":true},"notifications_enabled":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Lead":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"email":{"type":"string","format":"email","nullable":true},"phone":{"type":"string","nullable":true,"description":"E.164, normalized on create (e.g. `+15551234567`)."},"status":{"type":"string","nullable":true,"description":"Top-level lifecycle: `open` | `won` | `lost`."},"stage":{"type":"string","nullable":true,"description":"Pipeline column slug (e.g. `new`, `contacted`, `estimate_sent`)."},"pipeline_id":{"type":"string","format":"uuid","nullable":true},"lead_source_id":{"type":"string","format":"uuid","nullable":true,"description":"Org-defined Lead Source (Referral, Yard sign, …)."},"source":{"type":"string","nullable":true,"description":"Source/platform label — also routes the lead to a matching pipeline."},"service_type":{"type":"string","nullable":true},"value_cents":{"type":"integer","nullable":true,"description":"Estimated lead value in minor units."},"address_line1":{"type":"string","nullable":true},"address_line2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"owner_user_id":{"type":"string","format":"uuid","nullable":true,"description":"Assigned team member (auth user id)."},"converted_customer_id":{"type":"string","format":"uuid","nullable":true,"description":"Set once the lead becomes a customer."},"converted":{"type":"boolean","description":"Convenience flag — true when `converted_customer_id` is set."},"external_lead_id":{"type":"string","nullable":true,"description":"Your upstream id — pass on create for idempotency."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true},"last_inbound_at":{"type":"string","format":"date-time","nullable":true},"last_outbound_at":{"type":"string","format":"date-time","nullable":true}}},"Job":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["scheduled","on_the_way","arrival","in_progress","completed","cancelled","overdue"]},"title":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"service":{"type":"string","nullable":true,"description":"Free-text service label — does not need to match `GET /services`."},"scheduled_start":{"type":"string","format":"date-time","nullable":true},"scheduled_end":{"type":"string","format":"date-time","nullable":true},"scheduled_for":{"type":"string","format":"date-time","nullable":true,"description":"Legacy \"anytime\" anchor — prefer scheduled_start."},"notes":{"type":"string","nullable":true},"amount_cents":{"type":"integer","nullable":true,"description":"Job total in minor units."},"customer_id":{"type":"string","format":"uuid"},"customer_name":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"lead_source":{"type":"string","nullable":true},"payment_status":{"type":"string","nullable":true},"charge_status":{"type":"string","nullable":true},"dispatched_employee_ids":{"type":"array","items":{"type":"string","format":"uuid"},"nullable":true},"salesperson_ids":{"type":"array","items":{"type":"string","format":"uuid"},"nullable":true},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time","nullable":true},"completed_at":{"type":"string","format":"date-time","nullable":true}}},"Employee":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"email":{"type":"string","format":"email","nullable":true},"phone":{"type":"string","nullable":true},"role":{"type":"string","description":"Admin | Sales Rep | Technician | <custom-role-uuid>"},"is_active":{"type":"boolean"},"color_tag":{"type":"string","nullable":true},"profile_picture_url":{"type":"string","format":"uri","nullable":true},"invitation_status":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ServiceCategory":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"sort_order":{"type":"integer"},"line_items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"price":{"type":"number","nullable":true,"description":"Dollar amount (not cents)."},"quantity":{"type":"number","nullable":true},"unit":{"type":"string","nullable":true}}}}}},"RecordedPayment":{"type":"object","properties":{"payment_id":{"type":"string","format":"uuid"},"invoice_id":{"type":"string","format":"uuid"},"job_id":{"type":"string","format":"uuid","nullable":true},"amount_cents":{"type":"integer"},"payment_method":{"type":"string"},"payment_date":{"type":"string","format":"date-time"},"status":{"type":"string"},"deduped":{"type":"boolean","description":"Present and true when this is an earlier payment returned for a retry."}}}}}}