> For the complete documentation index, see [llms.txt](https://docs.shortcutco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shortcutco.com/developers/concepts/glossary.md). # Glossary The objects in the Shortcut API, what each one is in the app, and how ids work. After this page you will know what every object in the API is, where to find it in the Shortcut app, and how objects point at each other. The API uses the words the app uses, so what your users see on screen is what you see in JSON. ## Objects | API object | In the Shortcut app | Notes | | ------------------ | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Workspace | The business, under **Settings → Company & brand** | One per token. `GET /v1/me` returns its id, name, timezone, and today's date there. | | Customer | **Customers**: the people and businesses you serve | Contact details, tags, and one or more properties. `status` is `active`, `inactive` (deactivated in the app), or `invited`. Email is optional; a customer without one has `email: null`. | | Property | A customer's service address, on the customer's profile | Address, label (such as `Home`), coordinates, and measured lawn area in `squareFeet`. Gate codes and access notes are not part of the API. | | Lead | A request for service, listed in **Customers** with the **Lead** label | `status` is `pending` (open) or `dismissed` (set aside). `lifecycleStage` moves from `lead` to `prospect` when an estimate is written for it and to `customer` when a job is booked. `source` says how it arrived: `intake_form`, `manual` (added in the app), `csv`, or `api`. | | Estimate | **Estimates**: the price you offer a lead or customer | `status` is `draft`, `pending` (sent, waiting for the customer), `approved`, `declined`, `voided`, or `expired`. `GET /v1/estimates/{id}` adds its lines, price options, and products. | | Job | **Jobs**: the recurring or one-time work you sold | `status` is `pending` (not on the schedule yet), `scheduled`, `paused`, `canceled`, or `completed`. A job produces visits; visits carry its `jobId` and `jobName`. A price change in the app replaces a job with a new one, linked by `previousVersionJobId`. | | Visit | One stop on the schedule: a job's work for one customer on one date | `date` is the scheduled day in the workspace's timezone. See [Visits and crews](#visits-and-crews). | | Crew | **Settings → Teams**: the people who work together in the field | The API calls crews teams (`GET /v1/teams`), so crew ids appear as `teamId`, `assignedTeamId`, and `effectiveTeamId`. Each crew lists its active members; `isDefault` marks the crew new work goes to. | | Staff | **Settings → Users**: company admins and employees (`GET /v1/users`) | `role` is `admin` or `employee`; `status` is `active`, `invited`, or `inactive`. Customers are never staff. | | Service | **Settings → Services**, such as `Weekly mowing` | `serviceType` is `standard`, `snow`, or `chemical`. Chemical services are read-only through the API. Jobs are created from services. | | Product | **Settings → Products**, such as mulch by the yard | Sold by `unitLabel` at `defaultUnitPrice`. `status` is `active` or `archived`. | | Tag | **Settings → Tags**, attached to customers and leads | Names are unique in the workspace, ignoring case. A customer's tags are set as a whole list with `PUT /v1/customers/{id}/tags`. | | Custom field | **Settings → Custom fields**: extra fields on every customer's profile | `type` is `text`, `select`, `date`, `number`, or `boolean`. Definitions are read-only through the API; a customer's values are read and set at `/v1/customers/{id}/custom-fields`. A `select` value is an option id. | | External reference | Not shown in the app | Your own id for a customer or property, as `{ source, externalId }`. Records list theirs in `externalReferences`. See [Sync](/developers/concepts/sync.md#external-references). | | Invoice | **Invoices** | `status` is `draft`, `unpaid`, `overdue`, `paid`, or `void`. `kind` is `standard`, `prepay`, or `project`. `GET /v1/invoices/{id}` adds the lines the customer sees. | | Payment | A payment against an invoice, on the invoice and in the customer's billing | `method` is `online` (paid through Shortcut) or how an offline payment was recorded: `cash`, `check`, `ach`, `other`. `refundedAmount` is what has been refunded so far. | Every object in a response carries an `object` field (`customer`, `property`, `lead`, `estimate`, `job`, `visit`, `team`, `user`, `service`, `product`, `tag`, `custom_field`, `invoice`, `payment`, `token`), so a parser can tell a customer from a lead without guessing from field names. ## Visits and crews A visit has three crew fields, so you never compute a fallback yourself. Jobs carry `teamId`, the job's own crew, and `effectiveTeamId`, the crew doing the job's next visit. | Field | Meaning | | ----------------- | ------------------------------------------------------------------------------------------------------------------- | | `assignedTeamId` | The crew pinned to this one visit, or `null` when the visit follows its job's crew. | | `effectiveTeamId` | The crew doing the work: `assignedTeamId` when set, otherwise the job's crew. `null` means the visit is unassigned. | | `routePosition` | The visit's stop number on that crew's route for the day, starting at 1, or `null` when it is not routed. | Use `effectiveTeamId` for "who is doing this visit". The `teamId` filter on `GET /v1/visits` matches it too. Crew names and members come from `GET /v1/teams`: ```bash curl "https://api.shortcutco.com/v1/teams?archived=false" \ -H "Authorization: Bearer $SHORTCUT_TOKEN" ``` ```json { "data": [ { "id": "6c7d8e9f-0a1b-4c2d-8e3f-4a5b6c7d8e9f", "object": "team", "name": "North crew", "color": "#2E7D32", "isDefault": true, "sortOrder": 0, "members": [ { "userId": "f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4a5b", "firstName": "Sam", "lastName": "Ortiz" }, { "userId": "0a9b8c7d-6e5f-4a3b-9c2d-1e0f9a8b7c6d", "firstName": "Lee", "lastName": "Park" } ], "archivedAt": null, "createdAt": "2025-03-04T16:20:11.502Z", "updatedAt": "2026-02-10T18:01:45.930Z" } ], "meta": { "nextCursor": null, "hasMore": false } } ``` Visit `status` values: | `status` | Meaning | | ------------------ | ---------------------------------------------------------------------------------------------------------------------- | | `scheduled` | On the schedule. | | `rescheduled` | Moved to this date, and on the schedule. | | `pending` | Planned but not on the schedule yet. | | `needs_reschedule` | Waiting for a new date. | | `completed` | Done. `completedAt` says when. | | `skipped` | Closed without doing the work. | | `canceled` | Closed. `closeReason: "already_handled"` means the work was handled outside Shortcut; the app shows it as **Handled**. | ## Ids Ids are UUIDs, the same ones the app uses in its own page addresses, so the customer you open in Shortcut and `GET /v1/customers/{id}` with the id from that page's address are the same record. Store ids as strings. Objects point at each other by id, with the field named after the object: a visit has `customerId`, `jobId`, and `propertyId`; a job has `customerId`, `propertyId`, `serviceId`, and `estimateId`; a property has `customerId`; a lead has `customerId` and `propertyId`; an estimate has `customerId`, `leadId`, and `propertyId`; an invoice has `customerId` and `propertyId`; a payment has `invoiceId` and `customerId`. ## Dates, times, and money * `createdAt`, `updatedAt`, and every other timestamp are ISO 8601 in UTC, such as `2026-10-16T17:04:12.381Z`. * Dates without a time, such as a visit's `date`, are `YYYY-MM-DD` in the workspace's timezone. `GET /v1/me` returns the timezone and today's date there. * An invoice's `dueDate`, and the `dueBefore` filter, use the calendar date printed on the invoice. `dueAt` is the exact time the invoice turns `overdue`. * Money is a decimal number of US dollars, such as `129.5`. More in [Conventions](/developers/concepts/conventions.md).