# Flex API > Flex's tenant API for integrations and AI agents: activity, categories, customers, invoices, item properties, item units, items, jobs, labor rates, locations, me, modules, purchase orders, reorder, reorder points, roles, sales orders, schedule, schedule groups, transfers, user removal requests, users, vendors and webhooks of one organization, addressed with an API key. - Base URL: https://app.flexonthejob.com/api/v1 - Authentication: `Authorization: Bearer flx_live_…` (an API key an organization administrator creates in Flex; one organization per key; permissions are granted per key) - Responses: JSON; list endpoints also answer in CSV (`Accept: text/csv` or `?format=csv`; next-page cursor in the `X-Next-Cursor` header); errors are RFC 7807 application/problem+json - Rate limit: 120 requests/min per key (configurable), 600/min per organization; every response carries X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset (seconds); 429 + Retry-After when exceeded - Changelog: https://flexonthejob.com/changelog · Status: https://status.flexonthejob.com/ - Pagination: `?after=&limit=` on list endpoints; ETags on single resources and lists; `Idempotency-Key` header on writes ## Documentation - [Interactive reference](https://app.flexonthejob.com/docs): browse and try every endpoint - [OpenAPI document](https://app.flexonthejob.com/openapi/v1.json): machine-readable contract - [Full endpoint reference for LLMs](https://app.flexonthejob.com/llms-full.txt): every operation, parameter and schema field in plain text - [Discover capabilities](https://app.flexonthejob.com/api/v1/modules): GET with your key to see which modules are active and which permissions the key holds ## Resources ### Activity - GET /api/v1/activity — Lists logged API and MCP requests, oldest first, one page at a time. ### Categories - GET /api/v1/categories — Lists the organization's item categories, one page at a time. - POST /api/v1/categories — Creates an item category. - DELETE /api/v1/categories/{id} — Deletes an item category. - GET /api/v1/categories/{id} — Returns one item category. - PATCH /api/v1/categories/{id} — Renames, re-describes or moves an item category; only the fields sent change. - GET /api/v1/categories/{id}/properties — Lists a category's properties — its own and those inherited from parent categories. - POST /api/v1/categories/{id}/properties — Adds a property to a category. - DELETE /api/v1/categories/{id}/properties/{propertyId} — Deletes a category property. - PATCH /api/v1/categories/{id}/properties/{propertyId} — Changes a category property; only the fields sent change. - GET /api/v1/items/{id}/categories — Lists the categories an item is in, and which of them are assigned to it by hand. - DELETE /api/v1/items/{id}/categories/{categoryId} — Removes a hand-assigned category from an item. - POST /api/v1/items/{id}/categories/{categoryId} — Assigns a category to an item. ### Customers - GET /api/v1/customers — Lists customers, oldest first, one page at a time. - POST /api/v1/customers — Creates a customer. - DELETE /api/v1/customers/{id} — Deletes a customer. - GET /api/v1/customers/{id} — Returns one customer. - PUT /api/v1/customers/{id} — Replaces the editable fields of one customer. - GET /api/v1/customers/{id}/locations — Lists the additional locations (job sites / addresses) of one customer. - POST /api/v1/customers/{id}/locations — Adds a location (job site / address) to a customer. - DELETE /api/v1/customers/{id}/locations/{locationId} — Retires (deletes) a customer location. - GET /api/v1/customers/{id}/locations/{locationId} — Returns one location of a customer. - PATCH /api/v1/customers/{id}/locations/{locationId} — Edits a customer location; only the fields sent change. ### Invoices - GET /api/v1/invoices — Lists invoice headers. - POST /api/v1/invoices — Creates a standalone invoice (not tied to a job) from explicit lines. - POST /api/v1/invoices/from-job — Creates a draft invoice for a job. - DELETE /api/v1/invoices/{id} — Deletes a draft invoice. - GET /api/v1/invoices/{id} — Returns one invoice with its lines and payments. - PATCH /api/v1/invoices/{id} — Edits a draft invoice's header (number, dates, terms, notes, payment instructions, tax rate). - POST /api/v1/invoices/{id}/mark-sent — Finalizes a draft invoice (marks it sent). - POST /api/v1/invoices/{id}/payments — Records a payment and/or applies store credit to an invoice. - POST /api/v1/invoices/{id}/refresh-from-job — Recomputes a draft invoice's total from its job's current unbilled amount. - POST /api/v1/invoices/{id}/void — Voids an invoice. ### ItemProperties - GET /api/v1/items/{id}/properties — Lists an item's custom fields (properties) with definitions and current values. - PATCH /api/v1/items/{id}/properties — Sets several custom-field values of an item at once, by property name. - POST /api/v1/items/{id}/properties — Adds an item-level custom field to an item. - DELETE /api/v1/items/{id}/properties/{propertyId} — Deletes a property from an item. - PATCH /api/v1/items/{id}/properties/{propertyId} — Changes a property's name, data type or options. - POST /api/v1/items/{id}/properties/{propertyId}/revert — Reverts a customized property to its Item Template default. - PUT /api/v1/items/{id}/properties/{propertyId}/value — Replaces one custom-field value. ### ItemUnits - GET /api/v1/items/{id}/units — Lists an item's inventory units with their per-unit property values, one page at a time. - GET /api/v1/items/{id}/units/{unitId} — Returns one inventory unit of an item with its property values. - PUT /api/v1/items/{id}/units/{unitId}/properties/{name} — Sets one custom-field value on one inventory unit. ### Items - GET /api/v1/items — Lists items (templates) with pricing and total on-hand. - POST /api/v1/items — Creates a catalog item. - POST /api/v1/items/stock/batch — Applies several stock adjustments and moves in one call, all or nothing. - DELETE /api/v1/items/{id} — Deactivates (soft-deletes) an item. - GET /api/v1/items/{id} — Returns one item with its properties, price tiers, barcodes and per-location stock. - PATCH /api/v1/items/{id} — Changes some of an item's name, description, category, price, cost, preferred vendor or vendor part number. - POST /api/v1/items/{id}/stock/adjust — Adds or removes stock for an item at one location. - POST /api/v1/items/{id}/stock/move — Moves stock for an item from one location to another. ### Jobs - GET /api/v1/jobs — Lists the organization's jobs, oldest first, one page at a time. - POST /api/v1/jobs — Creates a job (estimate or draft) for a customer, optionally with material, labor and custom-charge lines. - GET /api/v1/jobs/{id} — Returns one job with its site address, pricing, assignees, material and labor lines and note timeline. - PATCH /api/v1/jobs/{id} — Edits a draft/estimate job's core fields (type, description, notes, schedule, customer, address). Status changes go through `POST /api/v1/jobs/{id}/status`. - POST /api/v1/jobs/{id}/assignees — Assigns people to a job — additively by default, or as the complete new crew with `replace: true`. - POST /api/v1/jobs/{id}/cancel — Cancels a job, returning its materials to stock. - POST /api/v1/jobs/{id}/charges — Adds a custom charge to a job (fees, disposal, permits …). - DELETE /api/v1/jobs/{id}/charges/{chargeId} — Removes a custom charge from a job (soft delete). - PATCH /api/v1/jobs/{id}/charges/{chargeId} — Edits a custom charge's name, price and/or description. - POST /api/v1/jobs/{id}/finalize — Publishes a draft estimate. - POST /api/v1/jobs/{id}/items — Adds a material line to a job (the app's "Add material" button). - DELETE /api/v1/jobs/{id}/items/{itemId} — Removes a material line from a job (soft delete). - PATCH /api/v1/jobs/{id}/items/{itemId} — Edits a material line's quantity, price and/or note. - POST /api/v1/jobs/{id}/labor — Adds a labor line to a job. - DELETE /api/v1/jobs/{id}/labor/{laborId} — Removes a labor line from a job (soft delete). - PATCH /api/v1/jobs/{id}/labor/{laborId} — Edits a labor line's rate, hours and/or note. - GET /api/v1/jobs/{id}/photos — Lists a job's photos, newest first. - POST /api/v1/jobs/{id}/photos — Attaches a photo to a job; it appears on the job's timeline as a `Photo` entry. - DELETE /api/v1/jobs/{id}/photos/{photoId} — Deletes a photo from a job. - GET /api/v1/jobs/{id}/photos/{photoId}/content — Downloads a job photo's image. - POST /api/v1/jobs/{id}/reschedule — Moves a scheduled job to a new start time (and optionally a new end). - POST /api/v1/jobs/{id}/status — Moves a job to another status. ### LaborRates - GET /api/v1/labor-rates — Lists the organization's labor rates, one page at a time. - GET /api/v1/labor-rates/{id} — Returns one labor rate. ### Locations - GET /api/v1/locations — Lists stock locations (warehouses, shelves, vehicles; job sites on request). - GET /api/v1/locations/{id} — Returns one stock location. ### Me - GET /api/v1/me — Returns the key's organization and the permissions it currently holds. ### Modules - GET /api/v1/modules — Lists the calling organization's modules and the presented key's permissions. ### PurchaseOrders - GET /api/v1/purchase-orders — Lists the organization's purchase orders, oldest first, one page at a time. - POST /api/v1/purchase-orders — Creates a purchase order in `Draft`, optionally with its lines. - GET /api/v1/purchase-orders/{id} — Returns one purchase order with its lines and their ordered, shipped and received quantities. - POST /api/v1/purchase-orders/{id}/cancel — Cancels a purchase order and its shipments. - POST /api/v1/purchase-orders/{id}/lines — Adds a line to a purchase order. - POST /api/v1/purchase-orders/{id}/mark-delivered — Marks a shipped purchase order as delivered to the receiving location (`Delivered`). - POST /api/v1/purchase-orders/{id}/mark-ordered — Marks a `Draft` purchase order as placed with the vendor (`Ordered`). - POST /api/v1/purchase-orders/{id}/mark-shipped — Marks an `Ordered` purchase order as shipped by the vendor (`Shipped`). - POST /api/v1/purchase-orders/{id}/receive — Receives purchase-order lines into stock (the app's receiving panel). ### Reorder - GET /api/v1/items/low-stock — Lists items below one of their reorder points, with on-hand, reorder quantity and vendor. - GET /api/v1/items/{id}/reorder-points — Lists an item's reorder points. - PUT /api/v1/items/{id}/reorder-points — Creates or updates an item's reorder point for one location. ### ReorderPoints - GET /api/v1/reorder-points — Lists the organization's reorder points, oldest first, one page at a time. - DELETE /api/v1/reorder-points/{id} — Deletes one reorder point. ### Roles - GET /api/v1/roles — Lists the roles accounts can hold: built-in first (highest rank first), then custom roles by name. - POST /api/v1/roles — Creates a custom role, like Roles → Create Role in the app. - DELETE /api/v1/roles/{id} — Deletes a custom role, like Roles → Delete in the app. - GET /api/v1/roles/{id} — Returns one custom role. - PATCH /api/v1/roles/{id} — Edits a custom role; only the fields sent change. ### SalesOrders - GET /api/v1/sales-orders — Lists the organization's sales orders, oldest first, one page at a time. - POST /api/v1/sales-orders — Creates a sales order, optionally with its lines (the app's New Sales Order page plus its item modal). - GET /api/v1/sales-orders/{id} — Returns one sales order with its lines. - PATCH /api/v1/sales-orders/{id} — Edits a sales order's header — the app's inline edits on the Details page (order number, PO, terms, dates, notes, tax rate, shipping cost). - POST /api/v1/sales-orders/{id}/cancel — Cancels a sales order (the app's Cancel page): delivered goods come back, transfers are cancelled. - POST /api/v1/sales-orders/{id}/complete — Marks a delivered sales order complete (the app's "Mark Complete"). - POST /api/v1/sales-orders/{id}/complete-pick — Finishes picking a transfer (the scan dialog's "Complete"): the transfer leaves the warehouse (In Transit). - POST /api/v1/sales-orders/{id}/deliver — Marks a shipped transfer delivered (the app's "Mark as Delivered"): its stock moves to the customer. - POST /api/v1/sales-orders/{id}/fulfill — Starts fulfilment of a sales order (the app's Begin Fulfillment button): creates the pick transfer. - POST /api/v1/sales-orders/{id}/lines — Adds lines to an existing sales order (the app's item picker on the Details page). - POST /api/v1/sales-orders/{id}/lines/pick-all — Marks every line of a sales order picked in full (the Fulfill page's "Pick All"). - DELETE /api/v1/sales-orders/{id}/lines/{lineId} — Removes a line from a sales order (the app's line remove button). - PATCH /api/v1/sales-orders/{id}/lines/{lineId} — Changes a line's unit price and/or unit cost (the app's inline price edit). - POST /api/v1/sales-orders/{id}/lines/{lineId}/pick — Picks one more unit of a line (the Fulfill page's per-line "Pick"). - PUT /api/v1/sales-orders/{id}/lines/{lineId}/picked-quantity — Sets a line's picked quantity (the Details page's picked-quantity editor); lowering it unpicks and releases stock. - POST /api/v1/sales-orders/{id}/pick — Picks a sales order's pick transfer — all of it (the app's "Pick All") or given units per line (the scan dialog). - GET /api/v1/sales-orders/{id}/returnable-items — Lists what can still be returned from a sales order (the app's return modal). - POST /api/v1/sales-orders/{id}/returns — Returns delivered goods of a sales order (the app's return modal): selected units, one transfer, or everything. - POST /api/v1/sales-orders/{id}/scan — Picks one unit by barcode (the Fulfill page's scanner). - POST /api/v1/sales-orders/{id}/ship — Records the shipment of an in-transit transfer (the app's Ship dialog): carrier and tracking, or "ship without tracking". - POST /api/v1/sales-orders/{id}/transfers — Creates another pick transfer for whatever lines are not yet covered (the app's "Create transfer"). ### Schedule - GET /api/v1/schedule — Lists the jobs scheduled to start within a date range as calendar events. ### ScheduleGroups - GET /api/v1/schedule-groups — Lists schedule groups with their active members, one page at a time. - POST /api/v1/schedule-groups — Creates a schedule group (a division, crew or team). - POST /api/v1/schedule-groups/reorder — Reorders the groups under one parent (sibling display order). - DELETE /api/v1/schedule-groups/{id} — Deletes a schedule group. - GET /api/v1/schedule-groups/{id} — Returns one schedule group with its active members. - PATCH /api/v1/schedule-groups/{id} — Edits a schedule group; only the fields sent change. - PUT /api/v1/schedule-groups/{id}/members — Replaces a schedule group's complete membership. - DELETE /api/v1/schedule-groups/{id}/members/{userId} — Removes a user from a schedule group. - PUT /api/v1/schedule-groups/{id}/members/{userId} — Adds a user to a schedule group, or sets their lead flag when already a member. ### Transfers - POST /api/v1/jobs/{id}/transfer — Creates the job-site transfer for a job (the Job Details "Create Transfer" button). - GET /api/v1/transfers — Lists the organization's inventory transfers, oldest first, one page at a time. - POST /api/v1/transfers — Creates a standalone transfer of stock from one location to another (Transfers → Create). - GET /api/v1/transfers/{id} — Returns one transfer with its item lines and approval state. - POST /api/v1/transfers/{id}/approve — Approves a transfer that is awaiting approval (Pending Approvals → Approve). - POST /api/v1/transfers/{id}/cancel — Cancels a job-site or standalone transfer and releases its stock. - POST /api/v1/transfers/{id}/complete — Completes (receives) an in-transit standalone transfer ("Complete Transfer"), optionally with lines that did not arrive. - POST /api/v1/transfers/{id}/fail — Marks an in-transit standalone transfer failed (the Details page's "Mark as Failed"). - PATCH /api/v1/transfers/{id}/lines/{lineId} — Reduces the number of units one line moves. - POST /api/v1/transfers/{id}/lines/{lineId}/pick — Picks units of one line (the scan dialog's per-line pick). - POST /api/v1/transfers/{id}/lines/{lineId}/redirect — Redirects one line to another waypoint, the final destination or another location. - POST /api/v1/transfers/{id}/lines/{lineId}/unpick — Removes picked units from one line (the scan dialog's unpick / reset). - POST /api/v1/transfers/{id}/pick — Marks every line of a standalone transfer fully picked (the scan dialog's "Pick All"). - POST /api/v1/transfers/{id}/reject — Rejects a transfer that is awaiting approval (Pending Approvals → Reject). - POST /api/v1/transfers/{id}/scan — Scans a barcode into a transfer (the scan dialog): one more unit picked on the matching line. - POST /api/v1/transfers/{id}/start — Starts a picked standalone transfer ("Mark as In Transit"). - POST /api/v1/transfers/{id}/submit — Submits a Draft standalone transfer (the Details page's "Submit Transfer"): it becomes Pending. - POST /api/v1/transfers/{id}/waypoints/{waypointId}/arrive — Arrives at a waypoint: the lines assigned to it are dropped off there. - POST /api/v1/transfers/{id}/waypoints/{waypointId}/deliver — Records delivery of every line at an arrived waypoint (Waypoint Delivery → Deliver All Items). - POST /api/v1/transfers/{id}/waypoints/{waypointId}/depart — Departs from an arrived waypoint towards the next stop. - POST /api/v1/transfers/{id}/waypoints/{waypointId}/skip — Skips a waypoint, redirecting the lines still assigned to it (Skip Waypoint). ### UserRemovalRequests - GET /api/v1/users/removal-requests — Lists the organization's Organization Admin removal requests, pending first. - POST /api/v1/users/{id}/removal-requests — Asks to demote or deactivate an Organization Admin (or steps the key's creator down). - POST /api/v1/users/{id}/removal-requests/{requestId}/approve — The admin being removed agrees: the change is made now. - POST /api/v1/users/{id}/removal-requests/{requestId}/cancel — The requester withdraws a pending removal request. - POST /api/v1/users/{id}/removal-requests/{requestId}/contest — The admin being removed objects: the request closes and nothing changes. ### Users - GET /api/v1/users — Lists the organization's users with the schedule groups each belongs to. - POST /api/v1/users — Creates an account in the organization, like Users → Add User in the app. - GET /api/v1/users/{id} — Returns one account with its roles and effective permissions. - PATCH /api/v1/users/{id} — Edits an account; only the fields sent change. - POST /api/v1/users/{id}/deactivate — Deactivates an account: it can no longer sign in and stops counting as a seat. - POST /api/v1/users/{id}/reactivate — Reactivates a deactivated account. ### Vendors - GET /api/v1/vendors — Lists the organization's vendors, one page at a time. - POST /api/v1/vendors — Creates a vendor. - GET /api/v1/vendors/{id} — Returns one vendor. - PATCH /api/v1/vendors/{id} — Edits a vendor; only the fields sent change. ### Webhooks - GET /api/v1/webhooks — Lists the organization's webhook subscriptions. - POST /api/v1/webhooks — Registers a webhook subscription (an instant-trigger endpoint). - GET /api/v1/webhooks/events — Lists the event names a subscription can subscribe to. - DELETE /api/v1/webhooks/{id} — Deletes a webhook subscription (stops delivery). ## Webhook events (outbound) Flex POSTs a JSON envelope `{ "event", "occurredAt", "organizationId", "data" }` to a subscribed https URL when one of these fires. Signed with `X-Flex-Signature-V2: t=,v1=` (HMAC-SHA256 of `.`, keyed with the subscription secret; reject `t` older/newer than 300 s and dedupe on `X-Flex-Delivery`) plus the legacy `X-Flex-Signature: sha256=` (HMAC-SHA256 of the raw body only); any 2xx acknowledges, otherwise retried up to 5 times; https endpoints only. Payload fields per event are in llms-full.txt; the machine-readable form is `x-webhooks` in the OpenAPI document. - `job.created` — A job or estimate is created — from the API, the web app or a synced device. - `job.status_changed` — A job moves to another status; `data.previousStatus` is the status it left. - `job.scheduled` — A job gets a start time or is rescheduled. - `job.assigned` — The crew assigned to a job changes; `data.assigneeUserIds` is the new crew. - `job.completed` — A job reaches a completed status (sent in addition to `job.status_changed`). - `invoice.created` — An invoice is created. - `invoice.sent` — An invoice leaves Draft (finalized or marked sent), or is created already finalized. - `invoice.paid` — An invoice is paid in full. - `invoice.deleted` — A draft invoice is deleted — from the web app, `DELETE /api/v1/invoices/{id}`, MCP `delete_draft_invoice`, or a synced device regenerating its draft. `data` is the invoice as it was (status `Draft`); its id no longer resolves. Finalized invoices are never deleted (they are voided). - `customer.created` — A customer is created. - `transfer.completed` — An inventory transfer is delivered — to a location, a job site, or as a direct/counter sale; `data.lines` lists item ids and quantities. - `transfer.created` — An inventory transfer is created — a job-site transfer (API, MCP, app or synced device), a standalone transfer, or a direct/counter sale (which also sends `transfer.completed`). Sent once its lines are saved; `data.lines` lists the reserved item ids and quantities. - `transfer.cancelled` — An inventory transfer is cancelled — from a job, the Transfers pages or the API, or because its approval was rejected. - `inventory.low_stock` — Stock for an item drops below its configured minimum and a new low-stock alert is raised (once per alert, not per unit). - `item.updated` — An existing item's name, description, category, preferred vendor or vendor part number, unit price, cost or custom fields change (on the item or on its inventory units), or it is deleted/restored; `data.changedFields` says which, `data.changedProperties` / `data.changedUnitProperties` name the custom fields. One event per item per save. - `purchase_order.created` — A purchase order is created (any status, including one entered already received). - `purchase_order.status_changed` — A purchase order moves to another status (Draft → Ordered → Shipped → Received, or Cancelled); `data.previousStatus` is the status it left. - `sales_order.created` — A sales order is created. - `sales_order.status_changed` — A sales order moves to another status (Pending → Picking → Packed → Shipped → Delivered, Complete or Cancelled); `data.previousStatus` is the status it left. - `vendor.created` — A vendor is created. - `vendor.updated` — A vendor's details change — name, contact, website, default shipping company, or active/inactive.