> 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/api-reference/reference/objects/visit.md).

# The visit object

The visit object in the Shortcut API - every field, an example, and the endpoints that return it.

A visit: one scheduled service for a customer on one date.

## Fields

| Field                      | Type                                                                                          | Description                                                                                                                                                                                                                                                                                                    |
| -------------------------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                       | id                                                                                            | The visit's id.                                                                                                                                                                                                                                                                                                |
| `object`                   | `"visit"`                                                                                     | Always `visit`.                                                                                                                                                                                                                                                                                                |
| `date`                     | date                                                                                          | The scheduled date, `YYYY-MM-DD` in the workspace's timezone.                                                                                                                                                                                                                                                  |
| `status`                   | `pending`, `scheduled`, `completed`, `canceled`, `rescheduled`, `needs_reschedule`, `skipped` | `scheduled` visits are on the schedule, and `rescheduled` visits were moved to this date and are on the schedule too. `pending` visits are planned but not on the schedule yet. `completed` visits are done. `needs_reschedule` visits are waiting for a new date. `skipped` and `canceled` visits are closed. |
| `closeReason`              | `already_handled` or null                                                                     | `already_handled` when a canceled visit was closed because the work was handled outside Shortcut (the app shows it as Handled); otherwise null.                                                                                                                                                                |
| `jobId`                    | id                                                                                            | The job this visit belongs to.                                                                                                                                                                                                                                                                                 |
| `jobName`                  | string                                                                                        | The job's name, such as `Weekly mowing`.                                                                                                                                                                                                                                                                       |
| `customerId`               | id                                                                                            | The customer the visit is for.                                                                                                                                                                                                                                                                                 |
| `propertyId`               | id or null                                                                                    | The property (service address), when the job has one.                                                                                                                                                                                                                                                          |
| `address`                  | string or null                                                                                | The property's street address, when the job has a property.                                                                                                                                                                                                                                                    |
| `assignedTeamId`           | id or null                                                                                    | The crew pinned to this visit. Null means the visit inherits its job's crew; read `effectiveTeamId` for the crew doing the work.                                                                                                                                                                               |
| `effectiveTeamId`          | id or null                                                                                    | The crew doing the visit: `assignedTeamId` when set, otherwise the job's crew. Null when neither has a crew (unassigned).                                                                                                                                                                                      |
| `routePosition`            | integer or null                                                                               | The visit's stop number on its crew's route for the day, starting at 1. Null when the visit is not routed or has no crew.                                                                                                                                                                                      |
| `plannedStartAt`           | timestamp or null                                                                             | Planned start, ISO 8601 in UTC, or null.                                                                                                                                                                                                                                                                       |
| `plannedEndAt`             | timestamp or null                                                                             | Planned end, ISO 8601 in UTC, or null.                                                                                                                                                                                                                                                                         |
| `estimatedDurationMinutes` | integer or null                                                                               | Estimated time on site in minutes, when known.                                                                                                                                                                                                                                                                 |
| `arrivedAt`                | timestamp or null                                                                             | When the crew arrived on site (read-only), ISO 8601 in UTC, or null.                                                                                                                                                                                                                                           |
| `completedAt`              | timestamp or null                                                                             | When the visit was completed, ISO 8601 in UTC, or null.                                                                                                                                                                                                                                                        |
| `invoiceId`                | id or null                                                                                    | The invoice that bills this visit, once a completed visit has been billed; otherwise null.                                                                                                                                                                                                                     |
| `createdAt`                | timestamp                                                                                     | When the visit was created, ISO 8601 in UTC.                                                                                                                                                                                                                                                                   |
| `updatedAt`                | timestamp                                                                                     | When the visit last changed, ISO 8601 in UTC.                                                                                                                                                                                                                                                                  |

## Example

```json
{
  "id": "950f54be-9159-4005-8da3-cb4c89ee0693",
  "object": "visit",
  "date": "2026-10-20",
  "status": "scheduled",
  "closeReason": null,
  "jobId": "e895444d-e4df-4f94-8129-badbdd73f622",
  "jobName": "Weekly mowing",
  "customerId": "c635a71a-c27f-4261-8eca-1da8bb1458ef",
  "propertyId": "ebbd3235-e807-4d7c-8451-a8c3e09be40a",
  "address": "412 Elm St, Bozeman, MT 59715",
  "assignedTeamId": "2467890d-20b1-4454-8cfb-ff9b19463ae2",
  "effectiveTeamId": "2467890d-20b1-4454-8cfb-ff9b19463ae2",
  "routePosition": 1,
  "plannedStartAt": null,
  "plannedEndAt": null,
  "estimatedDurationMinutes": 30,
  "arrivedAt": null,
  "completedAt": null,
  "invoiceId": null,
  "createdAt": "2026-10-16T17:04:12.381Z",
  "updatedAt": "2026-10-16T17:04:12.381Z"
}
```

## Endpoints

| Endpoint                          | What it does             |
| --------------------------------- | ------------------------ |
| `GET /v1/jobs/{id}/visits`        | List a job's visits      |
| `GET /v1/visits`                  | List visits              |
| `GET /v1/visits/{id}`             | Get a visit              |
| `POST /v1/visits/{id}/assign`     | Assign a visit to a crew |
| `POST /v1/visits/{id}/cancel`     | Cancel a visit           |
| `POST /v1/visits/{id}/reschedule` | Reschedule a visit       |
| `POST /v1/visits/{id}/skip`       | Skip a visit             |