API Reference

Service Plans

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

List service plans

GET/service-plans

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.

Query ParametersExpand Collapse

created_at_range_end: optional string

Return plans created on or before this date (ISO 8601)

formatdate-time

created_at_range_start: optional string

Return plans created on or after this date (ISO 8601)

formatdate-time

frequency: optional "One-Time" or "Annual" or "Semi-Annual" or 7 more

Filter by service frequency name.

One of the following:

"One-Time"

"Annual"

"Semi-Annual"

"Tri-Annual"

"Quarterly"

"Bi-Monthly"

"Monthly"

"Bi-Weekly"

"Weekly"

"Custom"

limit: optional number

Number of results per page (max 1000)

minimum1

maximum1000

page: optional number

Page number (1-based)

minimum1

service_type: optional string

Filter by service type (e.g. Window Cleaning, Pressure Washing)

sold_by_user_id: optional string

Filter by the ID of the user who sold the plan

formatuuid

status: optional "active" or "inactive"

Filter by active/inactive status

One of the following:

"active"

"inactive"

Header ParametersExpand Collapse

"rotor-api-version": "1.1.0"

ReturnsExpand Collapse

data: optional array of object { id, active, created_at, 10 more }

id: optional string

active: optional boolean

Whether the service plan is currently active

created_at: optional string

customer: optional object { id, company_name, first_name, last_name }

id: optional string

company_name: optional string

first_name: optional string

last_name: optional string

num_completed_jobs: optional number

Number of jobs in this plan that have been completed

num_pending_jobs: optional number

Number of jobs in this plan that are pending and haven't been created or scheduled yet

num_scheduled_jobs: optional number

Total number of jobs scheduled in this plan, including completed jobs

sale_value: optional number

Total calculated contract value across all jobs in the plan (dollars)

service_frequency: optional string

Human-readable recurrence frequency

service_type: optional string

Type of service (from plan configuration)

sold_by: optional object { email, name, user_id }

email: optional string

name: optional string

user_id: optional string

start_date: optional string

total_received: optional number

Net amount paid so far (invoices minus refunds, in dollars)

pagination: optional object { has_more, limit, page, total }

has_more: optional boolean

Whether more pages are available

limit: optional number

page: optional number

total: optional number

Total number of matching records

status: optional string

List service plans

HTTP

HTTP

curl https://api.getrotor.com/open-api/service-plans \
    -H "x-api-key: $ROTOR_API_KEY"

200 example

401 example

403 example

429 example

500 example

{
  "data": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "active": true,
      "created_at": "2019-12-27T18:11:19.117Z",
      "customer": {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "company_name": "company_name",
        "first_name": "first_name",
        "last_name": "last_name"
      },
      "num_completed_jobs": 1,
      "num_pending_jobs": 3,
      "num_scheduled_jobs": 1,
      "sale_value": 1200,
      "service_frequency": "Quarterly",
      "service_type": "Window Cleaning",
      "sold_by": {
        "email": "dev@stainless.com",
        "name": "Jane Smith",
        "user_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
      },
      "start_date": "2026-03-01",
      "total_received": 600
    }
  ],
  "pagination": {
    "has_more": true,
    "limit": 50,
    "page": 1,
    "total": 142
  },
  "status": "success"
}

{
  "status": "error",
  "message": "Authentication required. Provide x-api-key header.",
  "error_code": "AUTHENTICATION_REQUIRED"
}

{
  "status": "error",
  "message": "Forbidden: required scope 'leads:read' not granted for this API key",
  "error_code": "INSUFFICIENT_SCOPE"
}

{
  "status": "error",
  "message": "Daily API key request limit of 1000 exceeded",
  "error_code": "RATE_LIMIT_EXCEEDED"
}

{
  "status": "error",
  "message": "Internal server error"
}

Returns Examples

200 example

401 example

403 example

429 example

500 example

{
  "data": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "active": true,
      "created_at": "2019-12-27T18:11:19.117Z",
      "customer": {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "company_name": "company_name",
        "first_name": "first_name",
        "last_name": "last_name"
      },
      "num_completed_jobs": 1,
      "num_pending_jobs": 3,
      "num_scheduled_jobs": 1,
      "sale_value": 1200,
      "service_frequency": "Quarterly",
      "service_type": "Window Cleaning",
      "sold_by": {
        "email": "dev@stainless.com",
        "name": "Jane Smith",
        "user_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
      },
      "start_date": "2026-03-01",
      "total_received": 600
    }
  ],
  "pagination": {
    "has_more": true,
    "limit": 50,
    "page": 1,
    "total": 142
  },
  "status": "success"
}

{
  "status": "error",
  "message": "Authentication required. Provide x-api-key header.",
  "error_code": "AUTHENTICATION_REQUIRED"
}

{
  "status": "error",
  "message": "Forbidden: required scope 'leads:read' not granted for this API key",
  "error_code": "INSUFFICIENT_SCOPE"
}

{
  "status": "error",
  "message": "Daily API key request limit of 1000 exceeded",
  "error_code": "RATE_LIMIT_EXCEEDED"
}

{
  "status": "error",
  "message": "Internal server error"
}