# Rotor API Documentation > Documentation for Rotor API Append .md to any documentation page URL to get its markdown version. ## Guides - [Rotor API](https://docs.api.getrotor.com/docs/rotor-api.md) - [Rotor MCP](https://docs.api.getrotor.com/docs/rotor-mcp.md): Connect Rotor via MCP to analyze your data! ## API Reference - [Test authentication](https://docs.api.getrotor.com/reference/testauth.md): Simple endpoint to test if authentication credentials are valid. Returns authentication status, company/user info, and the scopes granted to the token. Useful for debugging during development. - [List leads](https://docs.api.getrotor.com/reference/listleads.md): Returns a paginated list of leads for the authenticated company. Results are ordered by creation date (newest first). - [Create or update a lead](https://docs.api.getrotor.com/reference/createorupdatelead.md): Creates a new lead or updates an existing one based on the provided information. **Upsert Logic:** 1. If `id` is provided, updates the lead with that ID 2. If no `id` but phone/email provided, searches for existing lead by phone first, then email 3. If no existing lead found, creates a new lead **Response Status:** - `201 Created` for new leads - `200 OK` for updated leads Tags are merged (not replaced) when updating. - [Get a lead by ID](https://docs.api.getrotor.com/reference/getlead.md) - [List customers](https://docs.api.getrotor.com/reference/listcustomers.md): Returns a paginated list of customers for the authenticated company. - [Create or update a customer](https://docs.api.getrotor.com/reference/createorupdatecustomer.md): Creates a new customer or updates an existing one based on the provided information. **Upsert Logic:** 1. If `id` is provided, updates the customer with that ID 2. If no `id` but phone/email provided, searches for existing customer by phone first, then email 3. If no existing customer found, creates a new customer Tags are merged (not replaced) when updating. - [Get a customer by ID](https://docs.api.getrotor.com/reference/getcustomer.md) - [List service plans](https://docs.api.getrotor.com/reference/listserviceplans.md): Returns a paginated list of service plan agreements for the authenticated company. Results are ordered by creation date (newest first). Service plans represent recurring service agreements (e.g. quarterly window cleaning, monthly pressure washing). The `sale_value` is the total calculated contract value across all jobs in the plan. The `total_received` is the net amount paid (invoices minus refunds) in dollars. - [List serviced jobs](https://docs.api.getrotor.com/reference/listservicedjobs.md): Returns a paginated list of completed jobs for the authenticated company. By default only completed jobs are returned (`only_completed` defaults to `true`). Results are ordered by `created_at` (newest first). The `service_date` is taken from the first visit's start time. `total_received` and `total_outstanding` are in dollars. **Note:** When `service_date_range_start` or `service_date_range_end` are provided, filtering is applied against the first visit's start time. Because this is evaluated after the database query, pagination totals reflect the filtered count. - [List recurring-billing cycles](https://docs.api.getrotor.com/reference/listcycles.md): Returns a paginated list of recurring-billing cycles for the authenticated company. Results are ordered by `created_at` (newest first). A cycle owns the cadence, amount and next billing date behind a service plan's recurring charge — the service plan's own fields do not. Follow `billing_cycle_ids` from a service plan or a serviced job to get here. Cancelled and `rollup` cycles are included. Filter them out with `status` and `pricing_mode` if you do not want them; they are returned by default so that a sync does not read an omitted row as a deletion. `next_amount` is in dollars, and is null for `rollup` cycles, which charge whatever work is outstanding when the period closes. Requires the `service_plans:read` scope. - [Get a cycle by ID](https://docs.api.getrotor.com/reference/getcycle.md): Requires the `service_plans:read` scope. Answers 404 for a cycle belonging to another company — to your key it does not exist. - [List pins](https://docs.api.getrotor.com/reference/listpins.md): Returns a paginated list of pins for the authenticated company. Results are ordered by creation date (newest first). - [List pin types](https://docs.api.getrotor.com/reference/listpintypes.md): Returns a list of available pin types (colors and labels) for the authenticated company. - [List timesheets](https://docs.api.getrotor.com/reference/listtimesheets.md): Returns a paginated list of timesheets for the authenticated company. Results are ordered by start time (newest first). - [Get a timesheet by ID](https://docs.api.getrotor.com/reference/gettimesheet.md) - [List visit timers](https://docs.api.getrotor.com/reference/listvisittimers.md): Returns a paginated list of visit timers for the authenticated company. Visit timers track the time technicians spend on a scheduled visit and are commonly used for payroll. Results are ordered by start time (newest first). - [Get a visit timer by ID](https://docs.api.getrotor.com/reference/getvisittimer.md) - [List tasks](https://docs.api.getrotor.com/reference/listtasks.md): Returns a paginated list of tasks for the authenticated company. Results are ordered by creation time (newest first). Requires the `tasks:read` scope. - [Create a task](https://docs.api.getrotor.com/reference/createtask.md): Creates a new task for the authenticated company. Requires the `tasks:create` scope. - [Get a task by ID](https://docs.api.getrotor.com/reference/gettask.md): Requires the `tasks:read` scope. - [Update a task](https://docs.api.getrotor.com/reference/updatetask.md): Updates an existing task. Only the fields provided in the request body are changed, and only the rules covering those fields are re-checked — so a task whose linked contact was later archived can still have its status or name updated. An empty body is a successful no-op that returns the task unchanged. Requires the `tasks:update` scope. - [Get company configuration](https://docs.api.getrotor.com/reference/getconfiguration.md): Returns the company's configured vocabularies — the values its records are allowed to carry, as set up in Settings. Each list is in the order the company arranged it, and any of them may be empty. These are the values the rest of this API expects: `service_type` filters take a name from `service_types`, `tags` filters take names from `tags`, and so on. - [List line item templates](https://docs.api.getrotor.com/reference/listconfigurationlineitemtemplates.md): Returns a paginated list of the company's active price book line item templates.