# API reference

> Every v1 endpoint, grouped by resource, with the conventions they all share. Generated from the OpenAPI specification.

- Canonical URL: https://couplrfsm.com/developers/api-reference
- Markdown: https://couplrfsm.com/developers/api-reference.md
- API version: v1 (base URL https://couplrfsm.com/api/v1)
- OpenAPI specification: https://couplrfsm.com/developers/openapi.yaml
- All documentation pages: https://couplrfsm.com/llms.txt

> **Flip:** This is the full list of what the API can do. Pick a resource below for its endpoints, fields and examples. I build these pages straight from the OpenAPI specification, and that specification is tested against the live API, so what you read here is what you get.

Base URL: `https://couplrfsm.com/api/v1`. API version: v1.

These pages are generated from the [OpenAPI specification](https://couplrfsm.com/developers/openapi.yaml), which is tested against the running API. Authentication is described in [Authentication and API keys](https://couplrfsm.com/developers/authentication). Error format, pagination, rate limits and idempotency are described in [Errors, limits and retries](https://couplrfsm.com/developers/errors-and-limits).

## Resources

- [Customers](https://couplrfsm.com/developers/api-reference/customers): List, find, create and update customers, and add service addresses to them.
- [Jobs](https://couplrfsm.com/developers/api-reference/jobs): List, create and update jobs.
- [Lookup lists](https://couplrfsm.com/developers/api-reference/lookup-lists): Short lists of the job types, technicians, tags, lead sources and market segments a job refers to by id.
- [Invoices](https://couplrfsm.com/developers/api-reference/invoices): List and read invoices with their line items, and create draft invoices.
- [Payments](https://couplrfsm.com/developers/api-reference/payments): Read the payments collected on invoices and what has been refunded.
- [Price book](https://couplrfsm.com/developers/api-reference/price-book): List, read, create and update the items a company puts on invoices and estimates.
- [Estimates](https://couplrfsm.com/developers/api-reference/estimates): List and read estimates, create one with the simple layout, and email it to the customer.
- [Schedules and time](https://couplrfsm.com/developers/api-reference/schedules-and-time): Read time entries (who worked when) and the schedule blocks that are not jobs.
- [Notes](https://couplrfsm.com/developers/api-reference/notes): Read the notes on a customer or a job, and add a note.
- [Photos and documents](https://couplrfsm.com/developers/api-reference/photos-and-documents): Time-limited links to the photos on a job or a customer, and to a customer's documents.
- [Equipment](https://couplrfsm.com/developers/api-reference/equipment): Read the equipment installed at a customer's addresses.
- [Booking](https://couplrfsm.com/developers/api-reference/booking): Find open time slots and book a visit into one.
- [Maintenance plans](https://couplrfsm.com/developers/api-reference/maintenance-plans): Read the maintenance plans a company sells and which customers are enrolled in them, and enroll a customer.
- [Leads](https://couplrfsm.com/developers/api-reference/leads): List and read the leads Couplr's assistant is talking to, and add a lead.
- [Webhook subscriptions](https://couplrfsm.com/developers/api-reference/webhook-subscriptions): Add, change and remove the destinations Couplr sends events to.
- [Deleted records](https://couplrfsm.com/developers/api-reference/deleted-records): Learn which customers, jobs, invoices and estimates were removed, to keep a copy in step.
- [Account](https://couplrfsm.com/developers/api-reference/account): Identify the API key in use.

## Conventions

Used by every endpoint:

- Send and receive JSON. Records come back inside `data`.
- In examples, replace `YOUR_API_KEY` with your key and `YOUR_UNIQUE_KEY` with a unique string per operation. Ids such as `1842` are examples.
- Request fields that are not listed are ignored. A field you omit keeps its value on update, or takes its default on create.
- Timestamps are ISO 8601 in UTC unless a field says otherwise. Dates are `YYYY-MM-DD`.
- Customer, job, estimate and lead ids are integers. Invoice ids are UUID strings.
- Money is in US dollars. Invoice `amount` and line `rate` are decimal strings such as `"389.00"`. Estimate `total` is a number.

## All endpoints

| Endpoint | What it does | Ability |
| --- | --- | --- |
| `GET /api/v1/customers` | [List customers](https://couplrfsm.com/developers/api-reference/customers#list-customers) | `customers:read` |
| `POST /api/v1/customers` | [Create a customer](https://couplrfsm.com/developers/api-reference/customers#create-a-customer) | `customers:write` |
| `GET /api/v1/customers/{id}` | [Get a customer](https://couplrfsm.com/developers/api-reference/customers#get-a-customer) | `customers:read` |
| `PATCH /api/v1/customers/{id}` | [Update a customer](https://couplrfsm.com/developers/api-reference/customers#update-a-customer) | `customers:write` |
| `POST /api/v1/customers/{id}/addresses` | [Add an address to a customer](https://couplrfsm.com/developers/api-reference/customers#add-an-address-to-a-customer) | `customers:write` |
| `GET /api/v1/jobs` | [List jobs](https://couplrfsm.com/developers/api-reference/jobs#list-jobs) | `jobs:read` |
| `POST /api/v1/jobs` | [Create a job](https://couplrfsm.com/developers/api-reference/jobs#create-a-job) | `jobs:write` |
| `GET /api/v1/jobs/{id}` | [Get a job](https://couplrfsm.com/developers/api-reference/jobs#get-a-job) | `jobs:read` |
| `PATCH /api/v1/jobs/{id}` | [Update a job](https://couplrfsm.com/developers/api-reference/jobs#update-a-job) | `jobs:write` |
| `POST /api/v1/jobs/{id}/complete` | [Complete a job](https://couplrfsm.com/developers/api-reference/jobs#complete-a-job) | `jobs:complete` |
| `GET /api/v1/job-types` | [List job types](https://couplrfsm.com/developers/api-reference/lookup-lists#list-job-types) | `jobs:read` |
| `GET /api/v1/technicians` | [List technicians](https://couplrfsm.com/developers/api-reference/lookup-lists#list-technicians) | `jobs:read` |
| `GET /api/v1/tags` | [List tags](https://couplrfsm.com/developers/api-reference/lookup-lists#list-tags) | `jobs:read` |
| `GET /api/v1/lead-sources` | [List lead sources](https://couplrfsm.com/developers/api-reference/lookup-lists#list-lead-sources) | `jobs:read` |
| `GET /api/v1/market-segments` | [List market segments](https://couplrfsm.com/developers/api-reference/lookup-lists#list-market-segments) | `jobs:read` |
| `GET /api/v1/invoices` | [List invoices](https://couplrfsm.com/developers/api-reference/invoices#list-invoices) | `invoices:read` |
| `POST /api/v1/invoices` | [Create a draft invoice](https://couplrfsm.com/developers/api-reference/invoices#create-a-draft-invoice) | `invoices:write` |
| `GET /api/v1/invoices/{id}` | [Get an invoice](https://couplrfsm.com/developers/api-reference/invoices#get-an-invoice) | `invoices:read` |
| `POST /api/v1/invoices/{id}/send` | [Send a draft invoice](https://couplrfsm.com/developers/api-reference/invoices#send-a-draft-invoice) | `invoices:send` |
| `GET /api/v1/invoices/{id}/payments` | [List an invoice's payments](https://couplrfsm.com/developers/api-reference/payments#list-an-invoices-payments) | `payments:read` |
| `GET /api/v1/payments` | [List payments](https://couplrfsm.com/developers/api-reference/payments#list-payments) | `payments:read` |
| `GET /api/v1/price-book-items` | [List price book items](https://couplrfsm.com/developers/api-reference/price-book#list-price-book-items) | `price-book:read` |
| `POST /api/v1/price-book-items` | [Create a price book item](https://couplrfsm.com/developers/api-reference/price-book#create-a-price-book-item) | `price-book:write` |
| `GET /api/v1/price-book-items/{id}` | [Get a price book item](https://couplrfsm.com/developers/api-reference/price-book#get-a-price-book-item) | `price-book:read` |
| `PATCH /api/v1/price-book-items/{id}` | [Update a price book item](https://couplrfsm.com/developers/api-reference/price-book#update-a-price-book-item) | `price-book:write` |
| `GET /api/v1/estimates` | [List estimates](https://couplrfsm.com/developers/api-reference/estimates#list-estimates) | `estimates:read` |
| `POST /api/v1/estimates` | [Create an estimate](https://couplrfsm.com/developers/api-reference/estimates#create-an-estimate) | `estimates:write` |
| `GET /api/v1/estimates/{id}` | [Get an estimate](https://couplrfsm.com/developers/api-reference/estimates#get-an-estimate) | `estimates:read` |
| `POST /api/v1/estimates/{id}/send` | [Send an estimate](https://couplrfsm.com/developers/api-reference/estimates#send-an-estimate) | `estimates:write` |
| `GET /api/v1/time-entries` | [List time entries](https://couplrfsm.com/developers/api-reference/schedules-and-time#list-time-entries) | `timesheets:read` |
| `GET /api/v1/schedule-events` | [List schedule events](https://couplrfsm.com/developers/api-reference/schedules-and-time#list-schedule-events) | `timesheets:read` |
| `GET /api/v1/customers/{id}/notes` | [List a customer's notes](https://couplrfsm.com/developers/api-reference/notes#list-a-customers-notes) | `notes:read` |
| `POST /api/v1/customers/{id}/notes` | [Add a note to a customer](https://couplrfsm.com/developers/api-reference/notes#add-a-note-to-a-customer) | `notes:write` |
| `GET /api/v1/jobs/{id}/notes` | [List a job's notes](https://couplrfsm.com/developers/api-reference/notes#list-a-jobs-notes) | `notes:read` |
| `POST /api/v1/jobs/{id}/notes` | [Add a note to a job](https://couplrfsm.com/developers/api-reference/notes#add-a-note-to-a-job) | `notes:write` |
| `GET /api/v1/jobs/{id}/photos` | [List a job's photos](https://couplrfsm.com/developers/api-reference/photos-and-documents#list-a-jobs-photos) | `photos:read` |
| `GET /api/v1/customers/{id}/photos` | [List a customer's photos](https://couplrfsm.com/developers/api-reference/photos-and-documents#list-a-customers-photos) | `photos:read` |
| `GET /api/v1/customers/{id}/documents` | [List a customer's documents](https://couplrfsm.com/developers/api-reference/photos-and-documents#list-a-customers-documents) | `photos:read` |
| `GET /api/v1/equipment` | [List equipment](https://couplrfsm.com/developers/api-reference/equipment#list-equipment) | `equipment:read` |
| `GET /api/v1/equipment/{id}` | [Get a piece of equipment](https://couplrfsm.com/developers/api-reference/equipment#get-a-piece-of-equipment) | `equipment:read` |
| `GET /api/v1/availability` | [List open time slots](https://couplrfsm.com/developers/api-reference/booking#list-open-time-slots) | `availability:read` |
| `POST /api/v1/bookings` | [Book a visit](https://couplrfsm.com/developers/api-reference/booking#book-a-visit) | `bookings:write` |
| `GET /api/v1/maintenance-plans` | [List maintenance plans](https://couplrfsm.com/developers/api-reference/maintenance-plans#list-maintenance-plans) | `plans:read` |
| `GET /api/v1/maintenance-plans/{id}` | [Get a maintenance plan](https://couplrfsm.com/developers/api-reference/maintenance-plans#get-a-maintenance-plan) | `plans:read` |
| `GET /api/v1/maintenance-plan-enrollments` | [List plan enrollments](https://couplrfsm.com/developers/api-reference/maintenance-plans#list-plan-enrollments) | `plans:read` |
| `POST /api/v1/maintenance-plan-enrollments` | [Enroll a customer in a plan](https://couplrfsm.com/developers/api-reference/maintenance-plans#enroll-a-customer-in-a-plan) | `plans:write` |
| `GET /api/v1/maintenance-plan-enrollments/{id}` | [Get a plan enrollment](https://couplrfsm.com/developers/api-reference/maintenance-plans#get-a-plan-enrollment) | `plans:read` |
| `GET /api/v1/leads` | [List leads](https://couplrfsm.com/developers/api-reference/leads#list-leads) | `leads:read` |
| `POST /api/v1/leads` | [Create a lead](https://couplrfsm.com/developers/api-reference/leads#create-a-lead) | `leads:write` |
| `GET /api/v1/leads/{id}` | [Get a lead](https://couplrfsm.com/developers/api-reference/leads#get-a-lead) | `leads:read` |
| `GET /api/v1/webhook-subscriptions` | [List webhook subscriptions](https://couplrfsm.com/developers/api-reference/webhook-subscriptions#list-webhook-subscriptions) | `webhooks:manage` |
| `POST /api/v1/webhook-subscriptions` | [Create a webhook subscription](https://couplrfsm.com/developers/api-reference/webhook-subscriptions#create-a-webhook-subscription) | `webhooks:manage` |
| `PATCH /api/v1/webhook-subscriptions/{id}` | [Update a webhook subscription](https://couplrfsm.com/developers/api-reference/webhook-subscriptions#update-a-webhook-subscription) | `webhooks:manage` |
| `DELETE /api/v1/webhook-subscriptions/{id}` | [Delete a webhook subscription](https://couplrfsm.com/developers/api-reference/webhook-subscriptions#delete-a-webhook-subscription) | `webhooks:manage` |
| `GET /api/v1/deleted` | [List deleted records](https://couplrfsm.com/developers/api-reference/deleted-records#list-deleted-records) | Any valid key |
| `GET /api/v1/me` | [Identify the API key](https://couplrfsm.com/developers/api-reference/account#identify-the-api-key) | Any valid key |

## Shared objects

Returned by every resource. Each resource's own object is described on its page.

### Page metadata object

| Field | Type | Description |
| --- | --- | --- |
| `page` | integer |  |
| `per_page` | integer |  |
| `total` | integer |  |
| `last_page` | integer |  |

### Error object

RFC 9457 problem details, plus `code`, `request_id`, and the older `message` / `errors` members.

| Field | Type | Description |
| --- | --- | --- |
| `type` | string | Always `about:blank`; branch on `code`. |
| `title` | string |  |
| `status` | integer |  |
| `detail` | string |  |
| `code` | string | Stable, machine-readable. New codes may be added. |
| `request_id` | string (uuid) |  |
| `message` | string | Same text as `detail`. |
| `errors` | object | On `422` only. Field name to list of messages. |