# Flex API

> Flex's tenant API for integrations and AI agents: customers, invoices, items, jobs, modules, schedule, schedule groups and users 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; errors are RFC 7807 application/problem+json
- Rate limit: 120 requests/min per key (configurable), 600/min per organization; 429 + Retry-After when exceeded
- Pagination: `?after=<nextCursor>&limit=<n>` on list endpoints; ETags on single resources; `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

### Customers
- GET /api/v1/customers — Lists customers, oldest first, one page at a time.
- POST /api/v1/customers — Creates 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.

### Invoices
- GET /api/v1/invoices — Lists invoice headers.
- POST /api/v1/invoices/from-job — Creates a draft invoice for a job.
- GET /api/v1/invoices/{id} — Returns one invoice with its lines and payments.
- POST /api/v1/invoices/{id}/mark-sent — Finalizes a draft invoice (marks it sent).

### Items
- GET /api/v1/items — Lists items (templates) with pricing and total on-hand.
- GET /api/v1/items/{id} — Returns one item with its properties, price tiers, barcodes and per-location stock.

### 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.
- 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}/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.

### Modules
- GET /api/v1/modules — Lists the calling organization's modules and the presented key's permissions.

### 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.

### Users
- GET /api/v1/users — Lists the organization's users with the schedule groups each belongs to.