> 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/properties.md).

# Properties

Service addresses that belong to customers.

A property is a customer's service address: where the work happens, with its label, coordinates, and measured lawn area.

Fields: [The property object](https://docs.shortcutco.com/developers/reference/objects/property) · [The property access object](https://docs.shortcutco.com/developers/reference/objects/property-access).

## List a customer's properties

> The customer's properties (service addresses), newest first, or by last change when \`updatedSince\` is set.\
> \
> Returns a list of \[property objects]\(<https://docs.shortcutco.com/developers/reference/objects/property>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Properties","description":"A property is a customer's service address: where the work happens, with its label, coordinates, and measured lawn area.\n\nFields: [The property object](https://docs.shortcutco.com/developers/reference/objects/property) · [The property access object](https://docs.shortcutco.com/developers/reference/objects/property-access)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["customers:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"Property":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The property's id."},"object":{"type":"string","const":"property","description":"Always `property`."},"customerId":{"type":"string","format":"uuid","description":"The customer the property belongs to."},"label":{"type":["string","null"],"description":"A short name for the property, such as `Home`."},"address":{"type":"string","description":"The full street address."},"latitude":{"type":["number","null"],"description":"Latitude, when the address was located."},"longitude":{"type":["number","null"],"description":"Longitude, when the address was located."},"squareFeet":{"type":["number","null"],"description":"Measured lawn area in square feet."},"status":{"type":"string","enum":["active","inactive"],"description":"Inactive properties are no longer serviced."},"externalReferences":{"type":"array","items":{"$ref":"#/components/schemas/ExternalReference"},"description":"Ids this property has in your other systems."},"createdAt":{"type":"string","format":"date-time","description":"When the property was created, ISO 8601 in UTC."},"updatedAt":{"type":"string","format":"date-time","description":"When the property last changed, ISO 8601 in UTC."}},"required":["id","object","customerId","label","address","latitude","longitude","squareFeet","status","externalReferences","createdAt","updatedAt"],"additionalProperties":false,"description":"A property (service address) belonging to a customer."},"ExternalReference":{"type":"object","properties":{"source":{"type":"string","description":"The system the id comes from."},"externalId":{"type":"string","description":"The object's id in that system."}},"required":["source","externalId"],"additionalProperties":false,"description":"An id this object has in another system."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/customers/{id}/properties":{"get":{"operationId":"properties.list","tags":["Properties"],"summary":"List a customer's properties","description":"The customer's properties (service addresses), newest first, or by last change when `updatedSince` is set.\n\nReturns a list of [property objects](https://docs.shortcutco.com/developers/reference/objects/property).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"description":"How many items to return, 1-200. Defaults to 50.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The `meta.nextCursor` from the previous page. Omit it for the first page.","schema":{"type":"string","minLength":1,"maxLength":4096}},{"name":"updatedSince","in":"query","required":false,"description":"ISO 8601 timestamp. Returns objects changed at or after it, oldest change first. Keep the largest `updatedAt` you have seen, subtract five minutes, and pass it on the next sync; deduplicate by `id`.","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Property"}},"meta":{"type":"object","properties":{"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"hasMore":{"type":"boolean","description":"Whether another page exists."}},"required":["nextCursor","hasMore"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Add a property

> Adds a property (service address) to a customer, as adding one on their profile does. Send \`latitude\` and \`longitude\` together when you have them; the map and routes use them. With \`externalReference\`, your id is saved in the same request, and a duplicate fails it with 409. The property gets its own customer-stage lead record, as in the app; if the token has \`automations:trigger\`, automations that start when a lead is created run as they do for properties added in the app. Send an \`Idempotency-Key\` to retry safely.\
> \
> Returns \[the property object]\(<https://docs.shortcutco.com/developers/reference/objects/property).\\>
> \
> \*\*Errors specific to this endpoint:\*\* \[\`already\_exists\`]\(<https://docs.shortcutco.com/developers/concepts/errors#already\\_exists>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Properties","description":"A property is a customer's service address: where the work happens, with its label, coordinates, and measured lawn area.\n\nFields: [The property object](https://docs.shortcutco.com/developers/reference/objects/property) · [The property access object](https://docs.shortcutco.com/developers/reference/objects/property-access)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["customers:write"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Any string up to 255 characters. Retrying with the same key returns the first response instead of repeating the write, for 24 hours.","schema":{"type":"string","maxLength":255}}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"Property":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The property's id."},"object":{"type":"string","const":"property","description":"Always `property`."},"customerId":{"type":"string","format":"uuid","description":"The customer the property belongs to."},"label":{"type":["string","null"],"description":"A short name for the property, such as `Home`."},"address":{"type":"string","description":"The full street address."},"latitude":{"type":["number","null"],"description":"Latitude, when the address was located."},"longitude":{"type":["number","null"],"description":"Longitude, when the address was located."},"squareFeet":{"type":["number","null"],"description":"Measured lawn area in square feet."},"status":{"type":"string","enum":["active","inactive"],"description":"Inactive properties are no longer serviced."},"externalReferences":{"type":"array","items":{"$ref":"#/components/schemas/ExternalReference"},"description":"Ids this property has in your other systems."},"createdAt":{"type":"string","format":"date-time","description":"When the property was created, ISO 8601 in UTC."},"updatedAt":{"type":"string","format":"date-time","description":"When the property last changed, ISO 8601 in UTC."}},"required":["id","object","customerId","label","address","latitude","longitude","squareFeet","status","externalReferences","createdAt","updatedAt"],"additionalProperties":false,"description":"A property (service address) belonging to a customer."},"ExternalReference":{"type":"object","properties":{"source":{"type":"string","description":"The system the id comes from."},"externalId":{"type":"string","description":"The object's id in that system."}},"required":["source","externalId"],"additionalProperties":false,"description":"An id this object has in another system."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflict with the current state or an in-flight request with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unprocessable":{"description":"The request cannot be applied, or its idempotency key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/customers/{id}/properties":{"post":{"operationId":"properties.create","tags":["Properties"],"summary":"Add a property","description":"Adds a property (service address) to a customer, as adding one on their profile does. Send `latitude` and `longitude` together when you have them; the map and routes use them. With `externalReference`, your id is saved in the same request, and a duplicate fails it with 409. The property gets its own customer-stage lead record, as in the app; if the token has `automations:trigger`, automations that start when a lead is created run as they do for properties added in the app. Send an `Idempotency-Key` to retry safely.\n\nReturns [the property object](https://docs.shortcutco.com/developers/reference/objects/property).\n\n**Errors specific to this endpoint:** [`already_exists`](https://docs.shortcutco.com/developers/concepts/errors#already_exists). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","minLength":1,"maxLength":300,"description":"The service address on one line, such as `412 Elm St, Bozeman, MT 59715`."},"label":{"type":"string","maxLength":120,"description":"A short name for the property, such as `Home`."},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the address. Send with `longitude`."},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the address. Send with `latitude`."},"squareFeet":{"type":"number","minimum":0,"maximum":100000000,"description":"Lawn area in square feet."},"externalReference":{"type":"object","properties":{"source":{"type":"string","pattern":"^[a-z0-9][a-z0-9_.-]{0,63}$","description":"Your name for the system the id comes from, such as `hubspot` or `mywebsite`: 1-64 lowercase letters, digits, `_`, `.`, or `-`, starting with a letter or digit."},"externalId":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[^\\p{Cc}\\s/\\\\]+$","description":"The object's id in that system: 1-255 characters, no spaces, slashes, or control characters."}},"required":["source","externalId"],"additionalProperties":false,"description":"Your id for this object. It is saved with the object in the same request; if another object already has it, nothing is created and the response is 409 `already_exists`."}},"required":["address"],"additionalProperties":false,"description":"A new property for the customer."}}}},"responses":{"201":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Property"},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Change a pest device

> Changes a monitored device as its drawer on the customer's Devices section does: where it is, its type, its area, a new code for a station put in its place (the old code stays on its history and the device keeps its readings), or its status (\`retired\` takes it out; \`active\` puts a retired or missing one back). Fields left out stay as they are. Refused with \`monitored\_devices\_off\` when the company has monitored devices off. Send an \`Idempotency-Key\` to retry safely.\
> \
> \*\*Errors specific to this endpoint:\*\* \[\`monitored\_devices\_admins\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#monitored\\_devices\\_admins\\_only>), \[\`monitored\_devices\_off\`]\(<https://docs.shortcutco.com/developers/concepts/errors#monitored\\_devices\\_off>), \[\`rule\_violation\`]\(<https://docs.shortcutco.com/developers/concepts/errors#rule\\_violation>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Properties","description":"A property is a customer's service address: where the work happens, with its label, coordinates, and measured lawn area.\n\nFields: [The property object](https://docs.shortcutco.com/developers/reference/objects/property) · [The property access object](https://docs.shortcutco.com/developers/reference/objects/property-access)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["customers:write"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflict with the current state or an in-flight request with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unprocessable":{"description":"The request cannot be applied, or its idempotency key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/monitored-devices/{id}":{"patch":{"operationId":"monitored_devices.update","tags":["Properties"],"summary":"Change a pest device","description":"Changes a monitored device as its drawer on the customer's Devices section does: where it is, its type, its area, a new code for a station put in its place (the old code stays on its history and the device keeps its readings), or its status (`retired` takes it out; `active` puts a retired or missing one back). Fields left out stay as they are. Refused with `monitored_devices_off` when the company has monitored devices off. Send an `Idempotency-Key` to retry safely.\n\n**Errors specific to this endpoint:** [`monitored_devices_admins_only`](https://docs.shortcutco.com/developers/concepts/errors#monitored_devices_admins_only), [`monitored_devices_off`](https://docs.shortcutco.com/developers/concepts/errors#monitored_devices_off), [`rule_violation`](https://docs.shortcutco.com/developers/concepts/errors#rule_violation), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"deviceLocation":{"type":"string","minLength":1,"maxLength":10000},"type":{"type":"string","enum":["rodent_bait_station","insect_bait_station","termite_monitor","snap_trap","glue_board","fly_light","other"]},"areaId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Move it to another area of the property; null for no area."},"replaceCode":{"type":"string","minLength":1,"maxLength":120,"description":"The code on a new station put in its place: the old code is kept on its history and the device keeps its readings."},"status":{"type":"string","enum":["active","retired"],"description":"`retired` takes it out (its history stays); `active` puts a retired or missing one back."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"number":{"type":"integer","description":"The station number crews and the customer see, unique per property."},"type":{"type":"string","enum":["rodent_bait_station","insect_bait_station","termite_monitor","snap_trap","glue_board","fly_light","other"]},"typeLabel":{"type":"string","description":"The type in words (\"Rodent bait station\")."},"deviceLocation":{"type":"string","description":"Where the device is, as the office or a crew typed it (\"Left of the loading dock door\")."},"areaId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"areaName":{"type":["string","null"],"description":"The part of the property it is in (\"Barrel cellar\"); null for no area."},"status":{"type":"string","enum":["active","missing","retired"],"description":"`missing` once a crew marked it missing and until it is found or replaced."},"deviceCode":{"type":["string","null"],"description":"The barcode or label on it now, as scanned or typed; null when none was assigned."}},"required":["id","number","type","typeLabel","deviceLocation","areaId","areaName","status","deviceCode"],"additionalProperties":false},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Read a pest device's history

> One monitored device and its readings, newest first, as its history drawer shows them: the property owner's visits only, at most 200, with the codes it carried before it was replaced. Refused with \`monitored\_devices\_off\` when the company has monitored devices off.\
> \
> \*\*Errors specific to this endpoint:\*\* \[\`monitored\_devices\_admins\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#monitored\\_devices\\_admins\\_only>), \[\`monitored\_devices\_off\`]\(<https://docs.shortcutco.com/developers/concepts/errors#monitored\\_devices\\_off>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Properties","description":"A property is a customer's service address: where the work happens, with its label, coordinates, and measured lawn area.\n\nFields: [The property object](https://docs.shortcutco.com/developers/reference/objects/property) · [The property access object](https://docs.shortcutco.com/developers/reference/objects/property-access)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["customers:read","chemicals:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/monitored-devices/{id}/history":{"get":{"operationId":"monitored_devices.history.get","tags":["Properties"],"summary":"Read a pest device's history","description":"One monitored device and its readings, newest first, as its history drawer shows them: the property owner's visits only, at most 200, with the codes it carried before it was replaced. Refused with `monitored_devices_off` when the company has monitored devices off.\n\n**Errors specific to this endpoint:** [`monitored_devices_admins_only`](https://docs.shortcutco.com/developers/concepts/errors#monitored_devices_admins_only), [`monitored_devices_off`](https://docs.shortcutco.com/developers/concepts/errors#monitored_devices_off), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"device":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"propertyId":{"type":"string","format":"uuid"},"number":{"type":"integer"},"type":{"type":"string","enum":["rodent_bait_station","insect_bait_station","termite_monitor","snap_trap","glue_board","fly_light","other"]},"typeLabel":{"type":"string"},"deviceLocation":{"type":"string","description":"Where the device is, as the office or a crew typed it (\"Left of the loading dock door\")."},"areaName":{"type":["string","null"]},"deviceCode":{"type":["string","null"],"description":"The barcode or label on it now, as scanned or typed."},"since":{"type":"string","format":"date-time","description":"When the device was added."},"replacedCodes":{"type":"array","items":{"type":"object","properties":{"deviceCode":{"type":"string"},"replacedAt":{"type":"string","format":"date-time"}},"required":["deviceCode","replacedAt"],"additionalProperties":false},"description":"Codes the device carried before it was replaced; it kept its history."}},"required":["id","propertyId","number","type","typeLabel","deviceLocation","areaName","deviceCode","since","replacedCodes"],"additionalProperties":false},"readings":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"visitId":{"type":"string","format":"uuid"},"visitDate":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"The visit's date, `YYYY-MM-DD`."},"outcome":{"type":"string","enum":["checked","skipped","missing"],"description":"`checked` with readings, `skipped` with a reason, or `missing` (the device was not there)."},"entry":{"type":"string","enum":["scan","typed","list","office"],"description":"How it was recorded: scanned, code typed, picked from the list, or by the office."},"recordedAt":{"type":"string","format":"date-time"},"recordedByName":{"type":["string","null"],"description":"Who recorded it (first name and last initial)."},"reading":{"type":"string","description":"The reading in the app's words (\"Most consumed · Added 3 · High activity\", \"Skipped · Locked\", \"Missing\")."},"consumed":{"anyOf":[{"type":"string","enum":["none","some","most","all"]},{"type":"null"}],"description":"Bait stations: how much bait was eaten."},"addedCount":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Bait placed this visit."},"productName":{"type":["string","null"],"description":"The bait product placed, when recorded."},"activity":{"anyOf":[{"type":"string","enum":["none","low","moderate","high"]},{"type":"null"}]},"condition":{"anyOf":[{"type":"string","enum":["ok","damaged","replaced"]},{"type":"null"}]},"catchCount":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Traps, glue boards and fly lights: what was caught."},"resetDone":{"type":["boolean","null"],"description":"Snap traps: reset."},"boardReplaced":{"type":["boolean","null"],"description":"Glue boards and fly lights: board or card replaced."},"skipReason":{"type":["string","null"],"description":"Why it was skipped, from the company's visit reasons."},"technicianNote":{"type":["string","null"],"description":"The technician's note on this reading, as typed; null when none."}},"required":["id","visitId","visitDate","outcome","entry","recordedAt","recordedByName","reading","consumed","addedCount","productName","activity","condition","catchCount","resetDone","boardReplaced","skipReason","technicianNote"],"additionalProperties":false},"description":"Newest first, the property owner's visits only; at most 200."}},"required":["device","readings"],"additionalProperties":false},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## List pest devices missed on visits

> Each monitored device skipped (with its reason) or found missing on a visit in the range, newest visit first, then by device number, with the technician's note and the device's status today. Filter by \`propertyId\` or \`customerId\`; \`latestVisitOnly=true\` keeps each property's latest visit in the range that has device readings. The default range is the 30 days up to today. Only the property owner's visits count. At most 500 rows. Refused with \`monitored\_devices\_off\` when the company has monitored devices off.\
> \
> \*\*Errors specific to this endpoint:\*\* \[\`monitored\_devices\_admins\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#monitored\\_devices\\_admins\\_only>), \[\`monitored\_devices\_off\`]\(<https://docs.shortcutco.com/developers/concepts/errors#monitored\\_devices\\_off>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Properties","description":"A property is a customer's service address: where the work happens, with its label, coordinates, and measured lawn area.\n\nFields: [The property object](https://docs.shortcutco.com/developers/reference/objects/property) · [The property access object](https://docs.shortcutco.com/developers/reference/objects/property-access)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["customers:read","jobs:read","visits:read","chemicals:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/monitored-devices/missed":{"get":{"operationId":"monitored_devices.missed.list","tags":["Properties"],"summary":"List pest devices missed on visits","description":"Each monitored device skipped (with its reason) or found missing on a visit in the range, newest visit first, then by device number, with the technician's note and the device's status today. Filter by `propertyId` or `customerId`; `latestVisitOnly=true` keeps each property's latest visit in the range that has device readings. The default range is the 30 days up to today. Only the property owner's visits count. At most 500 rows. Refused with `monitored_devices_off` when the company has monitored devices off.\n\n**Errors specific to this endpoint:** [`monitored_devices_admins_only`](https://docs.shortcutco.com/developers/concepts/errors#monitored_devices_admins_only), [`monitored_devices_off`](https://docs.shortcutco.com/developers/concepts/errors#monitored_devices_off), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"propertyId","in":"query","required":false,"description":"Only this property's visits.","schema":{"type":"string","format":"uuid"}},{"name":"customerId","in":"query","required":false,"description":"Only this customer's visits.","schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","required":false,"description":"Visits on or after this date; default 30 days before `to`.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to","in":"query","required":false,"description":"Visits on or before this date; default today in UTC.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"latestVisitOnly","in":"query","required":false,"description":"`true`: only each property's latest visit in the range that has device readings (\"missed last visit\").","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"visitsWithReadings":{"type":"integer","description":"Visits in the range with any device reading, after the filters."},"rows":{"type":"array","items":{"type":"object","properties":{"visitId":{"type":"string","format":"uuid"},"visitDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"propertyId":{"type":"string","format":"uuid"},"propertyLabel":{"type":"string"},"customerId":{"type":"string","format":"uuid"},"deviceId":{"type":"string","format":"uuid"},"number":{"type":"integer"},"typeLabel":{"type":"string"},"deviceLocation":{"type":"string","description":"Where the device is, as the office or a crew typed it (\"Left of the loading dock door\")."},"areaName":{"type":["string","null"]},"outcome":{"type":"string","enum":["skipped","missing"]},"skipReason":{"type":["string","null"]},"technicianNote":{"type":["string","null"],"description":"The technician's note on this reading, as typed; null when none."},"recordedByName":{"type":["string","null"]},"statusNow":{"type":"string","enum":["active","missing","retired"],"description":"The device's status today: a missing one may have been found or replaced since."}},"required":["visitId","visitDate","propertyId","propertyLabel","customerId","deviceId","number","typeLabel","deviceLocation","areaName","outcome","skipReason","technicianNote","recordedByName","statusNow"],"additionalProperties":false},"description":"Each device skipped or found missing on a visit, newest visit first, then by number."},"truncated":{"type":"boolean","description":"More than 500 rows matched; narrow the dates or the property."}},"required":["from","to","visitsWithReadings","rows","truncated"],"additionalProperties":false},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Get a property

> One property (service address). Gate codes and access notes are not included.\
> \
> Returns \[the property object]\(<https://docs.shortcutco.com/developers/reference/objects/property>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Properties","description":"A property is a customer's service address: where the work happens, with its label, coordinates, and measured lawn area.\n\nFields: [The property object](https://docs.shortcutco.com/developers/reference/objects/property) · [The property access object](https://docs.shortcutco.com/developers/reference/objects/property-access)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["customers:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"Property":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The property's id."},"object":{"type":"string","const":"property","description":"Always `property`."},"customerId":{"type":"string","format":"uuid","description":"The customer the property belongs to."},"label":{"type":["string","null"],"description":"A short name for the property, such as `Home`."},"address":{"type":"string","description":"The full street address."},"latitude":{"type":["number","null"],"description":"Latitude, when the address was located."},"longitude":{"type":["number","null"],"description":"Longitude, when the address was located."},"squareFeet":{"type":["number","null"],"description":"Measured lawn area in square feet."},"status":{"type":"string","enum":["active","inactive"],"description":"Inactive properties are no longer serviced."},"externalReferences":{"type":"array","items":{"$ref":"#/components/schemas/ExternalReference"},"description":"Ids this property has in your other systems."},"createdAt":{"type":"string","format":"date-time","description":"When the property was created, ISO 8601 in UTC."},"updatedAt":{"type":"string","format":"date-time","description":"When the property last changed, ISO 8601 in UTC."}},"required":["id","object","customerId","label","address","latitude","longitude","squareFeet","status","externalReferences","createdAt","updatedAt"],"additionalProperties":false,"description":"A property (service address) belonging to a customer."},"ExternalReference":{"type":"object","properties":{"source":{"type":"string","description":"The system the id comes from."},"externalId":{"type":"string","description":"The object's id in that system."}},"required":["source","externalId"],"additionalProperties":false,"description":"An id this object has in another system."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/properties/{id}":{"get":{"operationId":"properties.get","tags":["Properties"],"summary":"Get a property","description":"One property (service address). Gate codes and access notes are not included.\n\nReturns [the property object](https://docs.shortcutco.com/developers/reference/objects/property).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Property"},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Update a property

> Changes a property's address, label, or square footage, as editing it in the app does. A new address needs its \`latitude\` and \`longitude\`. Moving the address to another spot clears the property's map, its measured areas, and a square footage taken from that map: the request is refused with \`409 property\_map\_would\_clear\` unless it sends \`confirmClearPropertyMap: true\`, and \`meta.effects\` lists what was cleared. Fields you leave out are unchanged.\
> \
> Returns \[the property object]\(<https://docs.shortcutco.com/developers/reference/objects/property).\\>
> \
> \*\*Errors specific to this endpoint:\*\* \[\`property\_map\_would\_clear\`]\(<https://docs.shortcutco.com/developers/concepts/errors#property\\_map\\_would\\_clear>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Properties","description":"A property is a customer's service address: where the work happens, with its label, coordinates, and measured lawn area.\n\nFields: [The property object](https://docs.shortcutco.com/developers/reference/objects/property) · [The property access object](https://docs.shortcutco.com/developers/reference/objects/property-access)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["customers:write"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"Property":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The property's id."},"object":{"type":"string","const":"property","description":"Always `property`."},"customerId":{"type":"string","format":"uuid","description":"The customer the property belongs to."},"label":{"type":["string","null"],"description":"A short name for the property, such as `Home`."},"address":{"type":"string","description":"The full street address."},"latitude":{"type":["number","null"],"description":"Latitude, when the address was located."},"longitude":{"type":["number","null"],"description":"Longitude, when the address was located."},"squareFeet":{"type":["number","null"],"description":"Measured lawn area in square feet."},"status":{"type":"string","enum":["active","inactive"],"description":"Inactive properties are no longer serviced."},"externalReferences":{"type":"array","items":{"$ref":"#/components/schemas/ExternalReference"},"description":"Ids this property has in your other systems."},"createdAt":{"type":"string","format":"date-time","description":"When the property was created, ISO 8601 in UTC."},"updatedAt":{"type":"string","format":"date-time","description":"When the property last changed, ISO 8601 in UTC."}},"required":["id","object","customerId","label","address","latitude","longitude","squareFeet","status","externalReferences","createdAt","updatedAt"],"additionalProperties":false,"description":"A property (service address) belonging to a customer."},"ExternalReference":{"type":"object","properties":{"source":{"type":"string","description":"The system the id comes from."},"externalId":{"type":"string","description":"The object's id in that system."}},"required":["source","externalId"],"additionalProperties":false,"description":"An id this object has in another system."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflict with the current state or an in-flight request with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unprocessable":{"description":"The request cannot be applied, or its idempotency key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/properties/{id}":{"patch":{"operationId":"properties.update","tags":["Properties"],"summary":"Update a property","description":"Changes a property's address, label, or square footage, as editing it in the app does. A new address needs its `latitude` and `longitude`. Moving the address to another spot clears the property's map, its measured areas, and a square footage taken from that map: the request is refused with `409 property_map_would_clear` unless it sends `confirmClearPropertyMap: true`, and `meta.effects` lists what was cleared. Fields you leave out are unchanged.\n\nReturns [the property object](https://docs.shortcutco.com/developers/reference/objects/property).\n\n**Errors specific to this endpoint:** [`property_map_would_clear`](https://docs.shortcutco.com/developers/concepts/errors#property_map_would_clear). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","minLength":1,"maxLength":300,"description":"A new address. Send `latitude` and `longitude` with it so the map and routes stay right. Moving it to another spot clears the property's map; see `confirmClearPropertyMap`."},"label":{"anyOf":[{"type":"string","maxLength":120,"description":"A short name for the property, such as `Home`."},{"type":"null"}],"description":"A short name for the property. Null or empty clears it."},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the address. Send with `longitude`."},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the address. Send with `latitude`."},"squareFeet":{"anyOf":[{"type":"number","minimum":0,"maximum":100000000,"description":"Lawn area in square feet."},{"type":"null"}],"description":"Lawn area in square feet. Null clears it."},"confirmClearPropertyMap":{"type":"boolean","description":"Set `true` to allow an address change that clears the property's map, measurements, or measured square footage. Without it such a change is refused with `property_map_would_clear` and nothing changes."}},"additionalProperties":false,"description":"The fields to change. Fields you leave out are unchanged."}}}},"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Property"},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Get a property's access details

> The gate or lockbox code and the access instructions crews use at the property. Needs \`access:read\`, an opt-in scope: no preset but \*\*AI agent\*\* holds it, and the property object never carries these.\
> \
> Returns \[the property access object]\(<https://docs.shortcutco.com/developers/reference/objects/property-access>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Properties","description":"A property is a customer's service address: where the work happens, with its label, coordinates, and measured lawn area.\n\nFields: [The property object](https://docs.shortcutco.com/developers/reference/objects/property) · [The property access object](https://docs.shortcutco.com/developers/reference/objects/property-access)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["access:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"PropertyAccess":{"type":"object","properties":{"propertyId":{"type":"string","format":"uuid","description":"The property's id."},"object":{"type":"string","const":"property_access","description":"Always `property_access`."},"code":{"type":["string","null"],"description":"The gate, door, or lockbox code crews use."},"instructions":{"type":["string","null"],"description":"How crews get in: where the gate is, dogs, parking."}},"required":["propertyId","object","code","instructions"],"additionalProperties":false,"description":"How crews get into a property. Read with `access:read`, which no preset but AI agent holds."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/properties/{id}/access":{"get":{"operationId":"properties.access.get","tags":["Properties"],"summary":"Get a property's access details","description":"The gate or lockbox code and the access instructions crews use at the property. Needs `access:read`, an opt-in scope: no preset but **AI agent** holds it, and the property object never carries these.\n\nReturns [the property access object](https://docs.shortcutco.com/developers/reference/objects/property-access).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PropertyAccess"},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Set a property's access details

> Sets the gate or lockbox code or the access instructions crews see on the property's visits. Fields left out stay as they are; null clears one. Needs \`access:write\`, an opt-in scope.\
> \
> Returns \[the property access object]\(<https://docs.shortcutco.com/developers/reference/objects/property-access>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Properties","description":"A property is a customer's service address: where the work happens, with its label, coordinates, and measured lawn area.\n\nFields: [The property object](https://docs.shortcutco.com/developers/reference/objects/property) · [The property access object](https://docs.shortcutco.com/developers/reference/objects/property-access)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["access:write"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Any string up to 255 characters. Retrying with the same key returns the first response instead of repeating the write, for 24 hours.","schema":{"type":"string","maxLength":255}}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"PropertyAccess":{"type":"object","properties":{"propertyId":{"type":"string","format":"uuid","description":"The property's id."},"object":{"type":"string","const":"property_access","description":"Always `property_access`."},"code":{"type":["string","null"],"description":"The gate, door, or lockbox code crews use."},"instructions":{"type":["string","null"],"description":"How crews get in: where the gate is, dogs, parking."}},"required":["propertyId","object","code","instructions"],"additionalProperties":false,"description":"How crews get into a property. Read with `access:read`, which no preset but AI agent holds."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflict with the current state or an in-flight request with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unprocessable":{"description":"The request cannot be applied, or its idempotency key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/properties/{id}/access":{"put":{"operationId":"properties.access.set","tags":["Properties"],"summary":"Set a property's access details","description":"Sets the gate or lockbox code or the access instructions crews see on the property's visits. Fields left out stay as they are; null clears one. Needs `access:write`, an opt-in scope.\n\nReturns [the property access object](https://docs.shortcutco.com/developers/reference/objects/property-access).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"description":"The gate or lockbox code, up to 120 characters; null clears it."},"instructions":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"description":"Access instructions for crews; null clears them."}},"additionalProperties":false,"description":"The fields to change; send at least one."}}}},"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PropertyAccess"},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Read a property's pest device logbook

> A property's device logbook: each visit with device readings (the property owner's visits only), newest first, with the technician's end-of-visit summary, counts, and every device's reading that visit (checked, skipped with its reason, or missing). \`from\` and \`to\` are visit dates, inclusive; the default is the last 365 days. At most 60 visits; \`truncated\` says when more matched. Refused with \`monitored\_devices\_off\` when the company has monitored devices off.\
> \
> \*\*Errors specific to this endpoint:\*\* \[\`monitored\_devices\_admins\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#monitored\\_devices\\_admins\\_only>), \[\`monitored\_devices\_off\`]\(<https://docs.shortcutco.com/developers/concepts/errors#monitored\\_devices\\_off>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Properties","description":"A property is a customer's service address: where the work happens, with its label, coordinates, and measured lawn area.\n\nFields: [The property object](https://docs.shortcutco.com/developers/reference/objects/property) · [The property access object](https://docs.shortcutco.com/developers/reference/objects/property-access)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["customers:read","chemicals:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/properties/{id}/device-report":{"get":{"operationId":"properties.device_logbook.get","tags":["Properties"],"summary":"Read a property's pest device logbook","description":"A property's device logbook: each visit with device readings (the property owner's visits only), newest first, with the technician's end-of-visit summary, counts, and every device's reading that visit (checked, skipped with its reason, or missing). `from` and `to` are visit dates, inclusive; the default is the last 365 days. At most 60 visits; `truncated` says when more matched. Refused with `monitored_devices_off` when the company has monitored devices off.\n\n**Errors specific to this endpoint:** [`monitored_devices_admins_only`](https://docs.shortcutco.com/developers/concepts/errors#monitored_devices_admins_only), [`monitored_devices_off`](https://docs.shortcutco.com/developers/concepts/errors#monitored_devices_off), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","required":false,"description":"Visits on or after this date; default 365 days before `to`.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to","in":"query","required":false,"description":"Visits on or before this date; default today in UTC.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"propertyId":{"type":"string","format":"uuid"},"propertyLabel":{"type":"string"},"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"visits":{"type":"array","items":{"type":"object","properties":{"visitId":{"type":"string","format":"uuid"},"visitDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"visitSummary":{"type":["string","null"],"description":"The technician's end-of-visit summary, as typed."},"counts":{"type":"object","properties":{"checked":{"type":"integer"},"skipped":{"type":"integer"},"missing":{"type":"integer"}},"required":["checked","skipped","missing"],"additionalProperties":false},"readings":{"type":"array","items":{"type":"object","properties":{"deviceId":{"type":"string","format":"uuid"},"number":{"type":"integer"},"typeLabel":{"type":"string"},"areaName":{"type":["string","null"]},"outcome":{"type":"string","enum":["checked","skipped","missing"]},"reading":{"type":"string"},"productName":{"type":["string","null"]},"technicianNote":{"type":["string","null"],"description":"The technician's note on this reading, as typed; null when none."},"recordedByName":{"type":["string","null"]}},"required":["deviceId","number","typeLabel","areaName","outcome","reading","productName","technicianNote","recordedByName"],"additionalProperties":false}}},"required":["visitId","visitDate","visitSummary","counts","readings"],"additionalProperties":false},"description":"Each visit with device readings, newest first, the owner's visits only; at most 60 visits."},"truncated":{"type":"boolean","description":"More visits matched than were returned; narrow the dates."}},"required":["propertyId","propertyLabel","from","to","visits","truncated"],"additionalProperties":false},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## List a property's pest devices

> The monitored devices (bait stations, traps, glue boards, fly lights, termite monitors) at a property, as its customer's Devices section shows them: the areas in walking order; each device's number, type, where it is, code, status and latest reading on the property owner's visits; retired devices apart; and the last device report issued. Refused with \`monitored\_devices\_off\` when the company has monitored devices off.\
> \
> \*\*Errors specific to this endpoint:\*\* \[\`monitored\_devices\_admins\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#monitored\\_devices\\_admins\\_only>), \[\`monitored\_devices\_off\`]\(<https://docs.shortcutco.com/developers/concepts/errors#monitored\\_devices\\_off>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Properties","description":"A property is a customer's service address: where the work happens, with its label, coordinates, and measured lawn area.\n\nFields: [The property object](https://docs.shortcutco.com/developers/reference/objects/property) · [The property access object](https://docs.shortcutco.com/developers/reference/objects/property-access)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["customers:read","chemicals:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/properties/{id}/devices":{"get":{"operationId":"properties.devices.get","tags":["Properties"],"summary":"List a property's pest devices","description":"The monitored devices (bait stations, traps, glue boards, fly lights, termite monitors) at a property, as its customer's Devices section shows them: the areas in walking order; each device's number, type, where it is, code, status and latest reading on the property owner's visits; retired devices apart; and the last device report issued. Refused with `monitored_devices_off` when the company has monitored devices off.\n\n**Errors specific to this endpoint:** [`monitored_devices_admins_only`](https://docs.shortcutco.com/developers/concepts/errors#monitored_devices_admins_only), [`monitored_devices_off`](https://docs.shortcutco.com/developers/concepts/errors#monitored_devices_off), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"propertyId":{"type":"string","format":"uuid"},"propertyLabel":{"type":"string"},"counts":{"type":"object","properties":{"active":{"type":"integer"},"missing":{"type":"integer"},"retired":{"type":"integer"}},"required":["active","missing","retired"],"additionalProperties":false},"areas":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"activeDeviceCount":{"type":"integer"}},"required":["id","name","activeDeviceCount"],"additionalProperties":false},"description":"The property's areas in walking order."},"devices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"number":{"type":"integer","description":"The station number crews and the customer see, unique per property."},"type":{"type":"string","enum":["rodent_bait_station","insect_bait_station","termite_monitor","snap_trap","glue_board","fly_light","other"]},"typeLabel":{"type":"string","description":"The type in words (\"Rodent bait station\")."},"deviceLocation":{"type":"string","description":"Where the device is, as the office or a crew typed it (\"Left of the loading dock door\")."},"areaId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"areaName":{"type":["string","null"],"description":"The part of the property it is in (\"Barrel cellar\"); null for no area."},"status":{"type":"string","enum":["active","missing","retired"],"description":"`missing` once a crew marked it missing and until it is found or replaced."},"deviceCode":{"type":["string","null"],"description":"The barcode or label on it now, as scanned or typed; null when none was assigned."},"lastReading":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"visitId":{"type":"string","format":"uuid"},"visitDate":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"The visit's date, `YYYY-MM-DD`."},"outcome":{"type":"string","enum":["checked","skipped","missing"],"description":"`checked` with readings, `skipped` with a reason, or `missing` (the device was not there)."},"entry":{"type":"string","enum":["scan","typed","list","office"],"description":"How it was recorded: scanned, code typed, picked from the list, or by the office."},"recordedAt":{"type":"string","format":"date-time"},"recordedByName":{"type":["string","null"],"description":"Who recorded it (first name and last initial)."},"reading":{"type":"string","description":"The reading in the app's words (\"Most consumed · Added 3 · High activity\", \"Skipped · Locked\", \"Missing\")."},"consumed":{"anyOf":[{"type":"string","enum":["none","some","most","all"]},{"type":"null"}],"description":"Bait stations: how much bait was eaten."},"addedCount":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Bait placed this visit."},"productName":{"type":["string","null"],"description":"The bait product placed, when recorded."},"activity":{"anyOf":[{"type":"string","enum":["none","low","moderate","high"]},{"type":"null"}]},"condition":{"anyOf":[{"type":"string","enum":["ok","damaged","replaced"]},{"type":"null"}]},"catchCount":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Traps, glue boards and fly lights: what was caught."},"resetDone":{"type":["boolean","null"],"description":"Snap traps: reset."},"boardReplaced":{"type":["boolean","null"],"description":"Glue boards and fly lights: board or card replaced."},"skipReason":{"type":["string","null"],"description":"Why it was skipped, from the company's visit reasons."},"technicianNote":{"type":["string","null"],"description":"The technician's note on this reading, as typed; null when none."}},"required":["id","visitId","visitDate","outcome","entry","recordedAt","recordedByName","reading","consumed","addedCount","productName","activity","condition","catchCount","resetDone","boardReplaced","skipReason","technicianNote"],"additionalProperties":false},{"type":"null"}],"description":"The latest reading on the owner's visits."}},"required":["id","number","type","typeLabel","deviceLocation","areaId","areaName","status","deviceCode","lastReading"],"additionalProperties":false},"description":"Active and missing devices, by area in walking order, then number."},"retiredDevices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"number":{"type":"integer","description":"The station number crews and the customer see, unique per property."},"type":{"type":"string","enum":["rodent_bait_station","insect_bait_station","termite_monitor","snap_trap","glue_board","fly_light","other"]},"typeLabel":{"type":"string","description":"The type in words (\"Rodent bait station\")."},"deviceLocation":{"type":"string","description":"Where the device is, as the office or a crew typed it (\"Left of the loading dock door\")."},"areaId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"areaName":{"type":["string","null"],"description":"The part of the property it is in (\"Barrel cellar\"); null for no area."},"status":{"type":"string","enum":["active","missing","retired"],"description":"`missing` once a crew marked it missing and until it is found or replaced."},"deviceCode":{"type":["string","null"],"description":"The barcode or label on it now, as scanned or typed; null when none was assigned."},"lastReading":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"visitId":{"type":"string","format":"uuid"},"visitDate":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"The visit's date, `YYYY-MM-DD`."},"outcome":{"type":"string","enum":["checked","skipped","missing"],"description":"`checked` with readings, `skipped` with a reason, or `missing` (the device was not there)."},"entry":{"type":"string","enum":["scan","typed","list","office"],"description":"How it was recorded: scanned, code typed, picked from the list, or by the office."},"recordedAt":{"type":"string","format":"date-time"},"recordedByName":{"type":["string","null"],"description":"Who recorded it (first name and last initial)."},"reading":{"type":"string","description":"The reading in the app's words (\"Most consumed · Added 3 · High activity\", \"Skipped · Locked\", \"Missing\")."},"consumed":{"anyOf":[{"type":"string","enum":["none","some","most","all"]},{"type":"null"}],"description":"Bait stations: how much bait was eaten."},"addedCount":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Bait placed this visit."},"productName":{"type":["string","null"],"description":"The bait product placed, when recorded."},"activity":{"anyOf":[{"type":"string","enum":["none","low","moderate","high"]},{"type":"null"}]},"condition":{"anyOf":[{"type":"string","enum":["ok","damaged","replaced"]},{"type":"null"}]},"catchCount":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Traps, glue boards and fly lights: what was caught."},"resetDone":{"type":["boolean","null"],"description":"Snap traps: reset."},"boardReplaced":{"type":["boolean","null"],"description":"Glue boards and fly lights: board or card replaced."},"skipReason":{"type":["string","null"],"description":"Why it was skipped, from the company's visit reasons."},"technicianNote":{"type":["string","null"],"description":"The technician's note on this reading, as typed; null when none."}},"required":["id","visitId","visitDate","outcome","entry","recordedAt","recordedByName","reading","consumed","addedCount","productName","activity","condition","catchCount","resetDone","boardReplaced","skipReason","technicianNote"],"additionalProperties":false},{"type":"null"}],"description":"The latest reading on the owner's visits."}},"required":["id","number","type","typeLabel","deviceLocation","areaId","areaName","status","deviceCode","lastReading"],"additionalProperties":false},"description":"Devices taken out; their history stays."},"lastReport":{"anyOf":[{"type":"object","properties":{"publicationId":{"type":"string","format":"uuid","description":"The issued report; `resend_device_report` takes the visit, not this."},"visitId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"issuedAt":{"type":"string","format":"date-time"},"emailStatus":{"anyOf":[{"type":"string","enum":["sent","pending","suppressed","failed"]},{"type":"null"}],"description":"Its email to the customer: sent, still pending, suppressed (their email preferences or the company's), or failed; null when none was queued."}},"required":["publicationId","visitId","issuedAt","emailStatus"],"additionalProperties":false},{"type":"null"}],"description":"The latest device report issued to the property's owner."}},"required":["propertyId","propertyLabel","counts","areas","devices","retiredDevices","lastReport"],"additionalProperties":false},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Add a pest device to a property

> Adds a monitored device at a property, as Add device on the customer's Devices section does: it takes the property's next station number, and the area and code given. Crews scan or skip it on every device-checking visit from then on. Refused with \`monitored\_devices\_off\` when the company has monitored devices off. Send an \`Idempotency-Key\` to retry safely.\
> \
> \*\*Errors specific to this endpoint:\*\* \[\`monitored\_devices\_admins\_only\`]\(<https://docs.shortcutco.com/developers/concepts/errors#monitored\\_devices\\_admins\\_only>), \[\`monitored\_devices\_off\`]\(<https://docs.shortcutco.com/developers/concepts/errors#monitored\\_devices\\_off>), \[\`rule\_violation\`]\(<https://docs.shortcutco.com/developers/concepts/errors#rule\\_violation>), \[\`state\_conflict\`]\(<https://docs.shortcutco.com/developers/concepts/errors#state\\_conflict>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Properties","description":"A property is a customer's service address: where the work happens, with its label, coordinates, and measured lawn area.\n\nFields: [The property object](https://docs.shortcutco.com/developers/reference/objects/property) · [The property access object](https://docs.shortcutco.com/developers/reference/objects/property-access)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["customers:write"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Any string up to 255 characters. Retrying with the same key returns the first response instead of repeating the write, for 24 hours.","schema":{"type":"string","maxLength":255}}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflict with the current state or an in-flight request with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unprocessable":{"description":"The request cannot be applied, or its idempotency key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/properties/{id}/devices":{"post":{"operationId":"properties.devices.create","tags":["Properties"],"summary":"Add a pest device to a property","description":"Adds a monitored device at a property, as Add device on the customer's Devices section does: it takes the property's next station number, and the area and code given. Crews scan or skip it on every device-checking visit from then on. Refused with `monitored_devices_off` when the company has monitored devices off. Send an `Idempotency-Key` to retry safely.\n\n**Errors specific to this endpoint:** [`monitored_devices_admins_only`](https://docs.shortcutco.com/developers/concepts/errors#monitored_devices_admins_only), [`monitored_devices_off`](https://docs.shortcutco.com/developers/concepts/errors#monitored_devices_off), [`rule_violation`](https://docs.shortcutco.com/developers/concepts/errors#rule_violation), [`state_conflict`](https://docs.shortcutco.com/developers/concepts/errors#state_conflict). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["rodent_bait_station","insect_bait_station","termite_monitor","snap_trap","glue_board","fly_light","other"]},"deviceLocation":{"type":"string","minLength":1,"maxLength":10000,"description":"Where it is (\"Left of the loading dock door\")."},"areaId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The property's area it is in; from `areas` on the property's devices."},"deviceCode":{"type":"string","maxLength":120,"description":"The barcode or label on it, when it has one."}},"required":["type","deviceLocation"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"number":{"type":"integer","description":"The station number crews and the customer see, unique per property."},"type":{"type":"string","enum":["rodent_bait_station","insect_bait_station","termite_monitor","snap_trap","glue_board","fly_light","other"]},"typeLabel":{"type":"string","description":"The type in words (\"Rodent bait station\")."},"deviceLocation":{"type":"string","description":"Where the device is, as the office or a crew typed it (\"Left of the loading dock door\")."},"areaId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"areaName":{"type":["string","null"],"description":"The part of the property it is in (\"Barrel cellar\"); null for no area."},"status":{"type":"string","enum":["active","missing","retired"],"description":"`missing` once a crew marked it missing and until it is found or replaced."},"deviceCode":{"type":["string","null"],"description":"The barcode or label on it now, as scanned or typed; null when none was assigned."}},"required":["id","number","type","typeLabel","deviceLocation","areaId","areaName","status","deviceCode"],"additionalProperties":false},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Link a property to your id

> Records \`externalId\` as this property's id in \`source\`, so the external lookup and upsert find it. Linking is always explicit; the API never matches a property to your id by address. Repeating the same link changes nothing. If the id already belongs to another property, or this property already has a different id in \`source\`, the request fails with 409 and nothing changes.\
> \
> Returns \[the property object]\(<https://docs.shortcutco.com/developers/reference/objects/property).\\>
> \
> \*\*Errors specific to this endpoint:\*\* \[\`already\_exists\`]\(<https://docs.shortcutco.com/developers/concepts/errors#already\\_exists>), \[\`external\_reference\_exists\`]\(<https://docs.shortcutco.com/developers/concepts/errors#external\\_reference\\_exists>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Properties","description":"A property is a customer's service address: where the work happens, with its label, coordinates, and measured lawn area.\n\nFields: [The property object](https://docs.shortcutco.com/developers/reference/objects/property) · [The property access object](https://docs.shortcutco.com/developers/reference/objects/property-access)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["customers:write"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Any string up to 255 characters. Retrying with the same key returns the first response instead of repeating the write, for 24 hours.","schema":{"type":"string","maxLength":255}}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"Property":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The property's id."},"object":{"type":"string","const":"property","description":"Always `property`."},"customerId":{"type":"string","format":"uuid","description":"The customer the property belongs to."},"label":{"type":["string","null"],"description":"A short name for the property, such as `Home`."},"address":{"type":"string","description":"The full street address."},"latitude":{"type":["number","null"],"description":"Latitude, when the address was located."},"longitude":{"type":["number","null"],"description":"Longitude, when the address was located."},"squareFeet":{"type":["number","null"],"description":"Measured lawn area in square feet."},"status":{"type":"string","enum":["active","inactive"],"description":"Inactive properties are no longer serviced."},"externalReferences":{"type":"array","items":{"$ref":"#/components/schemas/ExternalReference"},"description":"Ids this property has in your other systems."},"createdAt":{"type":"string","format":"date-time","description":"When the property was created, ISO 8601 in UTC."},"updatedAt":{"type":"string","format":"date-time","description":"When the property last changed, ISO 8601 in UTC."}},"required":["id","object","customerId","label","address","latitude","longitude","squareFeet","status","externalReferences","createdAt","updatedAt"],"additionalProperties":false,"description":"A property (service address) belonging to a customer."},"ExternalReference":{"type":"object","properties":{"source":{"type":"string","description":"The system the id comes from."},"externalId":{"type":"string","description":"The object's id in that system."}},"required":["source","externalId"],"additionalProperties":false,"description":"An id this object has in another system."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflict with the current state or an in-flight request with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unprocessable":{"description":"The request cannot be applied, or its idempotency key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/properties/{id}/external-references/{source}":{"put":{"operationId":"properties.externalReferences.link","tags":["Properties"],"summary":"Link a property to your id","description":"Records `externalId` as this property's id in `source`, so the external lookup and upsert find it. Linking is always explicit; the API never matches a property to your id by address. Repeating the same link changes nothing. If the id already belongs to another property, or this property already has a different id in `source`, the request fails with 409 and nothing changes.\n\nReturns [the property object](https://docs.shortcutco.com/developers/reference/objects/property).\n\n**Errors specific to this endpoint:** [`already_exists`](https://docs.shortcutco.com/developers/concepts/errors#already_exists), [`external_reference_exists`](https://docs.shortcutco.com/developers/concepts/errors#external_reference_exists). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}},{"name":"source","in":"path","required":true,"description":"Your name for the system the id comes from, such as `hubspot` or `mywebsite`: 1-64 lowercase letters, digits, `_`, `.`, or `-`, starting with a letter or digit.","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_.-]{0,63}$"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"externalId":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[^\\p{Cc}\\s/\\\\]+$","description":"The object's id in that system: 1-255 characters, no spaces, slashes, or control characters."}},"required":["externalId"],"additionalProperties":false,"description":"The object's id in that system."}}}},"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Property"},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Unlink a property from your id

> Removes this property's id in \`source\`. The property itself is unchanged. Unlinking when there is no link changes nothing.\
> \
> Returns \[the property object]\(<https://docs.shortcutco.com/developers/reference/objects/property>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Properties","description":"A property is a customer's service address: where the work happens, with its label, coordinates, and measured lawn area.\n\nFields: [The property object](https://docs.shortcutco.com/developers/reference/objects/property) · [The property access object](https://docs.shortcutco.com/developers/reference/objects/property-access)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["customers:write"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"Property":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The property's id."},"object":{"type":"string","const":"property","description":"Always `property`."},"customerId":{"type":"string","format":"uuid","description":"The customer the property belongs to."},"label":{"type":["string","null"],"description":"A short name for the property, such as `Home`."},"address":{"type":"string","description":"The full street address."},"latitude":{"type":["number","null"],"description":"Latitude, when the address was located."},"longitude":{"type":["number","null"],"description":"Longitude, when the address was located."},"squareFeet":{"type":["number","null"],"description":"Measured lawn area in square feet."},"status":{"type":"string","enum":["active","inactive"],"description":"Inactive properties are no longer serviced."},"externalReferences":{"type":"array","items":{"$ref":"#/components/schemas/ExternalReference"},"description":"Ids this property has in your other systems."},"createdAt":{"type":"string","format":"date-time","description":"When the property was created, ISO 8601 in UTC."},"updatedAt":{"type":"string","format":"date-time","description":"When the property last changed, ISO 8601 in UTC."}},"required":["id","object","customerId","label","address","latitude","longitude","squareFeet","status","externalReferences","createdAt","updatedAt"],"additionalProperties":false,"description":"A property (service address) belonging to a customer."},"ExternalReference":{"type":"object","properties":{"source":{"type":"string","description":"The system the id comes from."},"externalId":{"type":"string","description":"The object's id in that system."}},"required":["source","externalId"],"additionalProperties":false,"description":"An id this object has in another system."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflict with the current state or an in-flight request with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unprocessable":{"description":"The request cannot be applied, or its idempotency key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/properties/{id}/external-references/{source}":{"delete":{"operationId":"properties.externalReferences.unlink","tags":["Properties"],"summary":"Unlink a property from your id","description":"Removes this property's id in `source`. The property itself is unchanged. Unlinking when there is no link changes nothing.\n\nReturns [the property object](https://docs.shortcutco.com/developers/reference/objects/property).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}},{"name":"source","in":"path","required":true,"description":"Your name for the system the id comes from, such as `hubspot` or `mywebsite`: 1-64 lowercase letters, digits, `_`, `.`, or `-`, starting with a letter or digit.","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_.-]{0,63}$"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Property"},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Get a property's measurements

> The property's stored map: each measured area (lawn, beds, driveway, sidewalk, structures, areas left out) with its square feet and whether auto-measure drew it, a person edited it or a person added it; whether the map was reviewed; the last auto-measure, its outcome and imagery date; the lot and building size; and the lawn size prices use. With \`jobs:read\`, each active job priced on an area, beside the measured lawn. Measurements hang off the property's newest lead: \`map\` is null when it has none. No margin of error is stored. Needs property measurement on the company's plan.\
> \
> \*\*Errors specific to this endpoint:\*\* \[\`feature\_not\_available\`]\(<https://docs.shortcutco.com/developers/concepts/errors#feature\\_not\\_available>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Properties","description":"A property is a customer's service address: where the work happens, with its label, coordinates, and measured lawn area.\n\nFields: [The property object](https://docs.shortcutco.com/developers/reference/objects/property) · [The property access object](https://docs.shortcutco.com/developers/reference/objects/property-access)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["customers:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/properties/{id}/measurements":{"get":{"operationId":"properties.measurements.get","tags":["Properties"],"summary":"Get a property's measurements","description":"The property's stored map: each measured area (lawn, beds, driveway, sidewalk, structures, areas left out) with its square feet and whether auto-measure drew it, a person edited it or a person added it; whether the map was reviewed; the last auto-measure, its outcome and imagery date; the lot and building size; and the lawn size prices use. With `jobs:read`, each active job priced on an area, beside the measured lawn. Measurements hang off the property's newest lead: `map` is null when it has none. No margin of error is stored. Needs property measurement on the company's plan.\n\n**Errors specific to this endpoint:** [`feature_not_available`](https://docs.shortcutco.com/developers/concepts/errors#feature_not_available). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"propertyId":{"type":"string","format":"uuid"},"customerId":{"type":"string","format":"uuid"},"customerName":{"type":"string"},"address":{"type":"string"},"lawnSqFootage":{"type":["number","null"],"description":"The property's lawn size, the one prices and Dispatch use."},"lawnSqFootageSource":{"type":"string","enum":["measured","manual","unknown"],"description":"measured: it equals the map's lawn; manual: typed in and differs from the map; unknown: none set."},"map":{"anyOf":[{"type":"object","properties":{"leadId":{"type":"string","format":"uuid","description":"The lead the map hangs off (the property's newest)."},"review":{"type":"string","enum":["reviewed","auto_measured_not_reviewed","drawn_not_reviewed","lot_only"],"description":"reviewed: a person accepted or saved the map; auto_measured_not_reviewed: auto-measure drew it and nobody has looked; drawn_not_reviewed: drawn or edited by hand, not marked reviewed; lot_only: lot lines only, no lawn measured. There is no margin of error: say which of these it is, never a margin."},"reviewedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"drawnBy":{"type":["string","null"],"description":"How the lawn outline was made: auto_measured, manual_drawn, operator_edited, provider_seeded or refreshed_provider."},"lawnNeedsReview":{"type":"boolean","description":"The app's rule of thumb: an unreviewed auto-measured lawn covering almost the whole lot (imagery may predate the house)."},"lawnShareOfLot":{"type":["number","null"],"description":"Auto-measured lawn as a share of the lot (0–1); null without a lot or auto areas."},"imageryCapturedOn":{"type":["string","null"],"description":"When the satellite imagery of the last auto-measure was taken; null when unknown."},"lastAutoMeasure":{"anyOf":[{"type":"object","properties":{"at":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["running","succeeded","failed"]},"outcome":{"type":"string","enum":["measured","lot_only","failed","running"]},"reason":{"type":["string","null"],"description":"Why only the lot was kept, or the run failed; Shortcut's own words."}},"required":["at","status","outcome","reason"],"additionalProperties":false},{"type":"null"}]},"measuredLawnSqft":{"type":["number","null"],"description":"The lawn areas added up (the map's lawn when it has no areas)."},"lotSqft":{"type":["number","null"]},"buildingSqft":{"type":["number","null"]},"boundaryDrawn":{"type":"boolean","description":"The office drew its own property outline; auto-measure measures inside it."},"totalsByKind":{"type":"object","additionalProperties":{"type":"number"},"propertyNames":{"enum":["lawn","driveway","sidewalk","bed","excluded","structure"]},"description":"Square feet by kind of area."},"areas":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"kind":{"type":"string","enum":["lawn","driveway","sidewalk","bed","excluded","structure"]},"sqft":{"type":"number"},"origin":{"type":"string","enum":["auto","edited","added"],"description":"auto: auto-measure's, untouched; edited: auto-measured, then changed by a person; added: drawn or typed by a person."},"sizeFrom":{"type":"string","enum":["calculated","manual"],"description":"calculated from the outline, or typed in."}},"required":["id","name","kind","sqft","origin","sizeFrom"],"additionalProperties":false}}},"required":["leadId","review","reviewedAt","drawnBy","lawnNeedsReview","lawnShareOfLot","imageryCapturedOn","lastAutoMeasure","measuredLawnSqft","lotSqft","buildingSqft","boundaryDrawn","totalsByKind","areas"],"additionalProperties":false},{"type":"null"}],"description":"Null when the property has no lead to hang a map off, or the lead has no map."},"pricedJobs":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"jobId":{"type":"string","format":"uuid"},"jobName":{"type":"string"},"priceStructure":{"type":"string"},"pricedSqft":{"type":"number","description":"The area the job was priced on."},"pricedFrom":{"type":"string","enum":["job_area","estimate_line_area"],"description":"job_area: the square feet a per-sq-ft job bills on; estimate_line_area: the area its estimate line was priced on (a program priced by area)."},"differenceSqft":{"type":["number","null"],"description":"Measured lawn minus priced area; positive when the job is priced on less than the lawn measures. Null with no measured lawn."},"differencePct":{"type":["number","null"],"description":"The difference as a percent of the priced area."}},"required":["jobId","jobName","priceStructure","pricedSqft","pricedFrom","differenceSqft","differencePct"],"additionalProperties":false}},{"type":"null"}],"description":"Active jobs here priced on an area, with the gap to the measured lawn. Null without `jobs:read`."}},"required":["propertyId","customerId","customerName","address","lawnSqFootage","lawnSqFootageSource","map","pricedJobs"],"additionalProperties":false},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## List a property's visit photos

> The photos and videos crews and the office added on this property's visits for its owner, newest upload first, each with its visit and the visit's date. \`from\` and \`to\` are visit dates in the workspace's timezone, inclusive. Facts only: no image, link, filename or location (none is stored). Photos a customer sent are not here.

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Properties","description":"A property is a customer's service address: where the work happens, with its label, coordinates, and measured lawn area.\n\nFields: [The property object](https://docs.shortcutco.com/developers/reference/objects/property) · [The property access object](https://docs.shortcutco.com/developers/reference/objects/property-access)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["customers:read","visits:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/properties/{id}/photos":{"get":{"operationId":"properties.photos.list","tags":["Properties"],"summary":"List a property's visit photos","description":"The photos and videos crews and the office added on this property's visits for its owner, newest upload first, each with its visit and the visit's date. `from` and `to` are visit dates in the workspace's timezone, inclusive. Facts only: no image, link, filename or location (none is stored). Photos a customer sent are not here.","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"description":"How many items to return, 1-200. Defaults to 50.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The `meta.nextCursor` from the previous page. Omit it for the first page.","schema":{"type":"string","minLength":1,"maxLength":4096}},{"name":"from","in":"query","required":false,"description":"Only photos from visits on or after this date, `YYYY-MM-DD` in the workspace's timezone.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to","in":"query","required":false,"description":"Only photos from visits on or before this date, `YYYY-MM-DD` in the workspace's timezone.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The photo's id. `view_attachment` takes it to look at the photo."},"label":{"anyOf":[{"type":"string","enum":["before","after"]},{"type":"null"}],"description":"Before or after, when the crew or the office marked it; null otherwise."},"areaName":{"type":["string","null"],"description":"The checklist area the photo answers (\"Front yard\"); null for a photo taken outside the checklist."},"takenAt":{"type":"string","format":"date-time","description":"When it was taken, ISO 8601 in UTC: the phone's clock, or the upload time when `takenAtIsUploadTime`."},"takenAtIsUploadTime":{"type":"boolean","description":"True when no taken time is stored (photos from before 10 Nov 2026 and office uploads): `takenAt` is when it uploaded."},"uploadedByName":{"type":"string","description":"Who uploaded it."},"sharedWithCustomer":{"type":"boolean","description":"Whether the customer can see it on the invoice and in the portal."},"mediaKind":{"type":"string","enum":["photo","video"],"description":"A photo or a video."},"visitId":{"type":"string","format":"uuid","description":"The visit the photo belongs to."},"visitDate":{"type":"string","description":"The visit's date, `YYYY-MM-DD` in the workspace's timezone."}},"required":["id","label","areaName","takenAt","takenAtIsUploadTime","uploadedByName","sharedWithCustomer","mediaKind","visitId","visitDate"],"additionalProperties":false}},"meta":{"type":"object","properties":{"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"hasMore":{"type":"boolean","description":"Whether another page exists."}},"required":["nextCursor","hasMore"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Get a site's snow push times by depth

> Minutes on site for a property's completed snow visits between \`from\` and \`to\` (default the last 730 days, two winters; at most 1,100), from arrival to completion as the crew stamped them: overall, by the depth each visit was dispatched at (any accumulation last), and by crew (median, average, shortest, longest). Visits without both stamps, under a minute or over 12 hours are counted in \`untimed\`.\
> \
> \*\*Errors specific to this endpoint:\*\* \[\`margins\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#margins\\_not\\_allowed>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Properties","description":"A property is a customer's service address: where the work happens, with its label, coordinates, and measured lawn area.\n\nFields: [The property object](https://docs.shortcutco.com/developers/reference/objects/property) · [The property access object](https://docs.shortcutco.com/developers/reference/objects/property-access)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["customers:read","jobs:read","visits:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/properties/{id}/snow-push-times":{"get":{"operationId":"properties.snow_push_times.get","tags":["Properties"],"summary":"Get a site's snow push times by depth","description":"Minutes on site for a property's completed snow visits between `from` and `to` (default the last 730 days, two winters; at most 1,100), from arrival to completion as the crew stamped them: overall, by the depth each visit was dispatched at (any accumulation last), and by crew (median, average, shortest, longest). Visits without both stamps, under a minute or over 12 hours are counted in `untimed`.\n\n**Errors specific to this endpoint:** [`margins_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#margins_not_allowed). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","required":false,"description":"The window's first visit day (default 730 days before `to`), `YYYY-MM-DD` in the workspace's timezone.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to","in":"query","required":false,"description":"The window's last visit day (default today), `YYYY-MM-DD` in the workspace's timezone.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"propertyId":{"type":"string","format":"uuid"},"customerName":{"type":"string"},"address":{"type":"string"},"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"overall":{"type":"object","properties":{"pushesTimed":{"type":"integer"},"medianMinutes":{"type":["number","null"]},"averageMinutes":{"type":["number","null"]},"shortestMinutes":{"type":["number","null"]},"longestMinutes":{"type":["number","null"]}},"required":["pushesTimed","medianMinutes","averageMinutes","shortestMinutes","longestMinutes"],"additionalProperties":false},"byDepth":{"type":"array","items":{"type":"object","properties":{"pushesTimed":{"type":"integer"},"medianMinutes":{"type":["number","null"]},"averageMinutes":{"type":["number","null"]},"shortestMinutes":{"type":["number","null"]},"longestMinutes":{"type":["number","null"]},"depthInches":{"type":["number","null"],"description":"The dispatched accumulation; null for `any accumulation`."}},"required":["pushesTimed","medianMinutes","averageMinutes","shortestMinutes","longestMinutes","depthInches"],"additionalProperties":false},"description":"Timed pushes grouped by the depth they were dispatched at, shallowest first, `any` last."},"byCrew":{"type":"array","items":{"type":"object","properties":{"pushesTimed":{"type":"integer"},"medianMinutes":{"type":["number","null"]},"averageMinutes":{"type":["number","null"]},"shortestMinutes":{"type":["number","null"]},"longestMinutes":{"type":["number","null"]},"crewId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"crewName":{"type":["string","null"]}},"required":["pushesTimed","medianMinutes","averageMinutes","shortestMinutes","longestMinutes","crewId","crewName"],"additionalProperties":false}},"untimed":{"type":"integer","description":"Completed pushes without both stamps, or on site under a minute or over 12 hours: listed in the passes, not counted."}},"required":["propertyId","customerName","address","from","to","overall","byDepth","byCrew","untimed"],"additionalProperties":false},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Get a property's real time on site

> How long a property really takes: each visit's minutes on site (arrival to completion, as the crew stamped them) between \`from\` and \`to\` (default the last 365 days), summed up by service and by crew (median, average, shortest, longest), the newest 60 visits, and visits the crew arrived at but never marked done. Visits under a minute or over 12 hours, or without both stamps, are listed but not counted. A split visit's crews each count their own visit. Bid minutes are not included.\
> \
> \*\*Errors specific to this endpoint:\*\* \[\`margins\_not\_allowed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#margins\\_not\\_allowed>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Properties","description":"A property is a customer's service address: where the work happens, with its label, coordinates, and measured lawn area.\n\nFields: [The property object](https://docs.shortcutco.com/developers/reference/objects/property) · [The property access object](https://docs.shortcutco.com/developers/reference/objects/property-access)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["customers:read","jobs:read","visits:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/properties/{id}/times":{"get":{"operationId":"properties.times.get","tags":["Properties"],"summary":"Get a property's real time on site","description":"How long a property really takes: each visit's minutes on site (arrival to completion, as the crew stamped them) between `from` and `to` (default the last 365 days), summed up by service and by crew (median, average, shortest, longest), the newest 60 visits, and visits the crew arrived at but never marked done. Visits under a minute or over 12 hours, or without both stamps, are listed but not counted. A split visit's crews each count their own visit. Bid minutes are not included.\n\n**Errors specific to this endpoint:** [`margins_not_allowed`](https://docs.shortcutco.com/developers/concepts/errors#margins_not_allowed). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","required":false,"description":"The window's first visit day (default 365 days before `to`), `YYYY-MM-DD` in the workspace's timezone.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to","in":"query","required":false,"description":"The window's last visit day (default today), `YYYY-MM-DD` in the workspace's timezone.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"serviceId","in":"query","required":false,"description":"Only visits of jobs on this catalog service.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"propertyId":{"type":"string","format":"uuid"},"customerId":{"type":"string","format":"uuid"},"customerName":{"type":"string"},"address":{"type":"string"},"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"overall":{"type":"object","properties":{"visitsTimed":{"type":"integer","description":"Visits with both stamps, on site between 1 minute and 12 hours."},"medianMinutes":{"type":["number","null"]},"averageMinutes":{"type":["number","null"]},"shortestMinutes":{"type":["number","null"]},"longestMinutes":{"type":["number","null"]},"lastTimedDate":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"The latest visit day counted."}},"required":["visitsTimed","medianMinutes","averageMinutes","shortestMinutes","longestMinutes","lastTimedDate"],"additionalProperties":false},"byService":{"type":"array","items":{"type":"object","properties":{"visitsTimed":{"type":"integer","description":"Visits with both stamps, on site between 1 minute and 12 hours."},"medianMinutes":{"type":["number","null"]},"averageMinutes":{"type":["number","null"]},"shortestMinutes":{"type":["number","null"]},"longestMinutes":{"type":["number","null"]},"lastTimedDate":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"The latest visit day counted."},"serviceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Null for jobs with no catalog service."},"serviceName":{"type":["string","null"]}},"required":["visitsTimed","medianMinutes","averageMinutes","shortestMinutes","longestMinutes","lastTimedDate","serviceId","serviceName"],"additionalProperties":false}},"byCrew":{"type":"array","items":{"type":"object","properties":{"visitsTimed":{"type":"integer","description":"Visits with both stamps, on site between 1 minute and 12 hours."},"medianMinutes":{"type":["number","null"]},"averageMinutes":{"type":["number","null"]},"shortestMinutes":{"type":["number","null"]},"longestMinutes":{"type":["number","null"]},"lastTimedDate":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"The latest visit day counted."},"crewId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The crew that did the visit (its own pin, else the job's crew); null when none."},"crewName":{"type":["string","null"]}},"required":["visitsTimed","medianMinutes","averageMinutes","shortestMinutes","longestMinutes","lastTimedDate","crewId","crewName"],"additionalProperties":false}},"visits":{"type":"array","items":{"type":"object","properties":{"visitId":{"type":"string","format":"uuid"},"jobId":{"type":"string","format":"uuid"},"jobName":{"type":"string"},"serviceId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"status":{"type":"string"},"crewId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"arrivedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"minutesOnSite":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"completedAt − arrivedAt; null without both stamps."},"counted":{"type":"boolean","description":"False when it has no stamps or an implausible time (under a minute, over 12 hours)."},"splitVisit":{"type":"boolean","description":"Worked by more than one crew; each crew's visit has its own stamps."}},"required":["visitId","jobId","jobName","serviceId","date","status","crewId","arrivedAt","completedAt","minutesOnSite","counted","splitVisit"],"additionalProperties":false},"description":"The newest visits in the window, up to 60, newest first."},"arrivedNotDone":{"type":"array","items":{"type":"object","properties":{"visitId":{"type":"string","format":"uuid"},"jobId":{"type":"string","format":"uuid"},"jobName":{"type":"string"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"status":{"type":"string"},"crewId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"arrivedAt":{"type":"string","format":"date-time"},"photos":{"type":"integer","description":"Photos and videos on the visit."}},"required":["visitId","jobId","jobName","date","status","crewId","arrivedAt","photos"],"additionalProperties":false},"description":"Visits the crew arrived at that were never marked done, newest first."},"untimedCompleted":{"type":"integer","description":"Completed visits in the window without both stamps (marked done in the office, or before stamps were kept)."},"truncated":{"type":"boolean","description":"True when the window holds more than 2,000 visits; only the newest were read."}},"required":["propertyId","customerId","customerName","address","from","to","overall","byService","byCrew","visits","arrivedNotDone","untimedCompleted","truncated"],"additionalProperties":false},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Read an address's history

> Every account, active or closed (\`inactive\`), with a property at an address: the property asked about by \`propertyId\`, or an \`address\` typed (a new lead's). Addresses match on the street line with street words shortened (\`12 Oak Street\` = \`12 Oak St\`), or the same house number pinned within 30 metres. For each: the account's status, when the property was added, and each job done there with its completed visits and first and last dates. Up to 25 accounts. No notes or messages from earlier accounts, and no access codes.

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Properties","description":"A property is a customer's service address: where the work happens, with its label, coordinates, and measured lawn area.\n\nFields: [The property object](https://docs.shortcutco.com/developers/reference/objects/property) · [The property access object](https://docs.shortcutco.com/developers/reference/objects/property-access)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["customers:read","jobs:read","visits:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/properties/address-history":{"get":{"operationId":"properties.address_history.get","tags":["Properties"],"summary":"Read an address's history","description":"Every account, active or closed (`inactive`), with a property at an address: the property asked about by `propertyId`, or an `address` typed (a new lead's). Addresses match on the street line with street words shortened (`12 Oak Street` = `12 Oak St`), or the same house number pinned within 30 metres. For each: the account's status, when the property was added, and each job done there with its completed visits and first and last dates. Up to 25 accounts. No notes or messages from earlier accounts, and no access codes.","parameters":[{"name":"propertyId","in":"query","required":false,"description":"A property's id: its address is the one looked up.","schema":{"type":"string","format":"uuid"}},{"name":"address","in":"query","required":false,"description":"A street address typed, such as a new lead's.","schema":{"type":"string","minLength":3,"maxLength":300}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"address":{"type":"string","description":"The address asked about."},"accounts":{"type":"array","items":{"type":"object","properties":{"propertyId":{"type":"string","format":"uuid"},"customerId":{"type":"string","format":"uuid"},"customerName":{"type":"string"},"customerStatus":{"type":"string","enum":["active","inactive","invited"],"description":"The account now: `inactive` accounts were deactivated (closed)."},"propertyStatus":{"type":"string","enum":["active","inactive"],"description":"The property on that account: `inactive` when it was removed from it."},"address":{"type":"string","description":"The address as that account holds it."},"isAskedProperty":{"type":"boolean","description":"The property asked about by id."},"addedOn":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"When the property was added to that account."},"lastServiceDate":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"The last completed visit at this property on that account, or null for none."},"services":{"type":"array","items":{"type":"object","properties":{"jobId":{"type":"string","format":"uuid","description":"The job's current version."},"jobName":{"type":"string"},"status":{"type":"string","description":"The job now: `scheduled`, `paused`, `canceled`, `completed`, `pending`."},"cadence":{"type":"string"},"completedVisits":{"type":"integer"},"firstDone":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"lastDone":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]}},"required":["jobId","jobName","status","cadence","completedVisits","firstDone","lastDone"],"additionalProperties":false}}},"required":["propertyId","customerId","customerName","customerStatus","propertyStatus","address","isAskedProperty","addedOn","lastServiceDate","services"],"additionalProperties":false},"description":"Every account, active or closed, with a property at this address, the most recently served first."},"truncated":{"type":"boolean","description":"True when more than 25 accounts matched."}},"required":["address","accounts","truncated"],"additionalProperties":false},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Get a property by your id

> The property your id maps to, as \`GET /v1/properties/{id}\` returns it, or 404.\
> \
> Returns \[the property object]\(<https://docs.shortcutco.com/developers/reference/objects/property>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Properties","description":"A property is a customer's service address: where the work happens, with its label, coordinates, and measured lawn area.\n\nFields: [The property object](https://docs.shortcutco.com/developers/reference/objects/property) · [The property access object](https://docs.shortcutco.com/developers/reference/objects/property-access)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["customers:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"Property":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The property's id."},"object":{"type":"string","const":"property","description":"Always `property`."},"customerId":{"type":"string","format":"uuid","description":"The customer the property belongs to."},"label":{"type":["string","null"],"description":"A short name for the property, such as `Home`."},"address":{"type":"string","description":"The full street address."},"latitude":{"type":["number","null"],"description":"Latitude, when the address was located."},"longitude":{"type":["number","null"],"description":"Longitude, when the address was located."},"squareFeet":{"type":["number","null"],"description":"Measured lawn area in square feet."},"status":{"type":"string","enum":["active","inactive"],"description":"Inactive properties are no longer serviced."},"externalReferences":{"type":"array","items":{"$ref":"#/components/schemas/ExternalReference"},"description":"Ids this property has in your other systems."},"createdAt":{"type":"string","format":"date-time","description":"When the property was created, ISO 8601 in UTC."},"updatedAt":{"type":"string","format":"date-time","description":"When the property last changed, ISO 8601 in UTC."}},"required":["id","object","customerId","label","address","latitude","longitude","squareFeet","status","externalReferences","createdAt","updatedAt"],"additionalProperties":false,"description":"A property (service address) belonging to a customer."},"ExternalReference":{"type":"object","properties":{"source":{"type":"string","description":"The system the id comes from."},"externalId":{"type":"string","description":"The object's id in that system."}},"required":["source","externalId"],"additionalProperties":false,"description":"An id this object has in another system."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/properties/external/{source}/{externalId}":{"get":{"operationId":"properties.external.get","tags":["Properties"],"summary":"Get a property by your id","description":"The property your id maps to, as `GET /v1/properties/{id}` returns it, or 404.\n\nReturns [the property object](https://docs.shortcutco.com/developers/reference/objects/property).","parameters":[{"name":"source","in":"path","required":true,"description":"Your name for the system the id comes from, such as `hubspot` or `mywebsite`: 1-64 lowercase letters, digits, `_`, `.`, or `-`, starting with a letter or digit.","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_.-]{0,63}$"}},{"name":"externalId","in":"path","required":true,"description":"The object's id in that system: 1-255 characters, no spaces, slashes, or control characters.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[^\\p{Cc}\\s/\\\\]+$"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Property"},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Create or update a property by your id

> The sync endpoint for properties. If your id is new, adds the property to \`customerId\` as \`POST /v1/customers/{id}/properties\` does and saves the id (\`created: true\`, status 201). If it exists, applies the fields that differ to that property as \`PATCH\` does (\`created: false\`, status 200); an unchanged address string is unchanged whatever coordinates come with it, and a request that changes nothing writes nothing. The property must belong to \`customerId\`, or the request fails with 409. A move to another spot needs \`confirmClearPropertyMap: true\`, as in \`PATCH\`. Concurrent requests for the same id run one after another.\
> \
> \*\*Errors specific to this endpoint:\*\* \[\`external\_reference\_changed\`]\(<https://docs.shortcutco.com/developers/concepts/errors#external\\_reference\\_changed>), \[\`external\_reference\_customer\_mismatch\`]\(<https://docs.shortcutco.com/developers/concepts/errors#external\\_reference\\_customer\\_mismatch>), \[\`property\_map\_would\_clear\`]\(<https://docs.shortcutco.com/developers/concepts/errors#property\\_map\\_would\\_clear>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Properties","description":"A property is a customer's service address: where the work happens, with its label, coordinates, and measured lawn area.\n\nFields: [The property object](https://docs.shortcutco.com/developers/reference/objects/property) · [The property access object](https://docs.shortcutco.com/developers/reference/objects/property-access)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["customers:write"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Any string up to 255 characters. Retrying with the same key returns the first response instead of repeating the write, for 24 hours.","schema":{"type":"string","maxLength":255}}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"Property":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The property's id."},"object":{"type":"string","const":"property","description":"Always `property`."},"customerId":{"type":"string","format":"uuid","description":"The customer the property belongs to."},"label":{"type":["string","null"],"description":"A short name for the property, such as `Home`."},"address":{"type":"string","description":"The full street address."},"latitude":{"type":["number","null"],"description":"Latitude, when the address was located."},"longitude":{"type":["number","null"],"description":"Longitude, when the address was located."},"squareFeet":{"type":["number","null"],"description":"Measured lawn area in square feet."},"status":{"type":"string","enum":["active","inactive"],"description":"Inactive properties are no longer serviced."},"externalReferences":{"type":"array","items":{"$ref":"#/components/schemas/ExternalReference"},"description":"Ids this property has in your other systems."},"createdAt":{"type":"string","format":"date-time","description":"When the property was created, ISO 8601 in UTC."},"updatedAt":{"type":"string","format":"date-time","description":"When the property last changed, ISO 8601 in UTC."}},"required":["id","object","customerId","label","address","latitude","longitude","squareFeet","status","externalReferences","createdAt","updatedAt"],"additionalProperties":false,"description":"A property (service address) belonging to a customer."},"ExternalReference":{"type":"object","properties":{"source":{"type":"string","description":"The system the id comes from."},"externalId":{"type":"string","description":"The object's id in that system."}},"required":["source","externalId"],"additionalProperties":false,"description":"An id this object has in another system."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflict with the current state or an in-flight request with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unprocessable":{"description":"The request cannot be applied, or its idempotency key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/properties/external/{source}/{externalId}":{"put":{"operationId":"properties.external.upsert","tags":["Properties"],"summary":"Create or update a property by your id","description":"The sync endpoint for properties. If your id is new, adds the property to `customerId` as `POST /v1/customers/{id}/properties` does and saves the id (`created: true`, status 201). If it exists, applies the fields that differ to that property as `PATCH` does (`created: false`, status 200); an unchanged address string is unchanged whatever coordinates come with it, and a request that changes nothing writes nothing. The property must belong to `customerId`, or the request fails with 409. A move to another spot needs `confirmClearPropertyMap: true`, as in `PATCH`. Concurrent requests for the same id run one after another.\n\n**Errors specific to this endpoint:** [`external_reference_changed`](https://docs.shortcutco.com/developers/concepts/errors#external_reference_changed), [`external_reference_customer_mismatch`](https://docs.shortcutco.com/developers/concepts/errors#external_reference_customer_mismatch), [`property_map_would_clear`](https://docs.shortcutco.com/developers/concepts/errors#property_map_would_clear). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"source","in":"path","required":true,"description":"Your name for the system the id comes from, such as `hubspot` or `mywebsite`: 1-64 lowercase letters, digits, `_`, `.`, or `-`, starting with a letter or digit.","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_.-]{0,63}$"}},{"name":"externalId","in":"path","required":true,"description":"The object's id in that system: 1-255 characters, no spaces, slashes, or control characters.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[^\\p{Cc}\\s/\\\\]+$"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string","format":"uuid","description":"The customer the property belongs to. When the reference exists it must be this customer."},"address":{"type":"string","minLength":1,"maxLength":300,"description":"The service address on one line, such as `412 Elm St, Bozeman, MT 59715`."},"label":{"type":"string","maxLength":120,"description":"A short name for the property, such as `Home`."},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the address. Send with `longitude`."},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the address. Send with `latitude`."},"squareFeet":{"type":"number","minimum":0,"maximum":100000000,"description":"Lawn area in square feet."},"confirmClearPropertyMap":{"type":"boolean","description":"Set `true` to allow an address change that clears the property's map, measurements, or measured square footage. Without it such a change is refused with `property_map_would_clear` and nothing changes."}},"required":["customerId","address"],"additionalProperties":false,"description":"The property as in `POST /v1/customers/{id}/properties`, plus its customer. When the reference is new the property is created; when it exists, these fields update the mapped property."}}}},"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"created":{"type":"boolean","description":"True when this request created the property."},"property":{"$ref":"#/components/schemas/Property"}},"required":["created","property"],"additionalProperties":false},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"201":{"description":"Your id was new: the property was created and your id saved (`created: true`).","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"created":{"type":"boolean","description":"True when this request created the property."},"property":{"$ref":"#/components/schemas/Property"}},"required":["created","property"],"additionalProperties":false},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## List the stops on a street

> Active properties whose address holds every word of \`street\`, with each recurring job there: its next visit, that visit's weekday (the stop's route day as it stands) and its crew. Up to 100 properties, by address. Neighbours who are not customers are not stored.

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Properties","description":"A property is a customer's service address: where the work happens, with its label, coordinates, and measured lawn area.\n\nFields: [The property object](https://docs.shortcutco.com/developers/reference/objects/property) · [The property access object](https://docs.shortcutco.com/developers/reference/objects/property-access)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["customers:read","jobs:read","visits:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/properties/on-street":{"get":{"operationId":"properties.on_street.list","tags":["Properties"],"summary":"List the stops on a street","description":"Active properties whose address holds every word of `street`, with each recurring job there: its next visit, that visit's weekday (the stop's route day as it stands) and its crew. Up to 100 properties, by address. Neighbours who are not customers are not stored.","parameters":[{"name":"street","in":"query","required":true,"description":"The street's words as they appear in addresses, such as `Maple Ave` or `County Road 12`.","schema":{"type":"string","minLength":3,"maxLength":80}},{"name":"weekday","in":"query","required":false,"description":"Only stops whose next visit falls on this weekday.","schema":{"type":"string","enum":["sunday","monday","tuesday","wednesday","thursday","friday","saturday"]}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"street":{"type":"string"},"properties":{"type":"array","items":{"type":"object","properties":{"propertyId":{"type":"string","format":"uuid"},"customerId":{"type":"string","format":"uuid"},"customerName":{"type":"string"},"address":{"type":"string"},"jobs":{"type":"array","items":{"type":"object","properties":{"jobId":{"type":"string","format":"uuid"},"jobName":{"type":"string"},"every":{"type":"string"},"nextVisitId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"nextVisitOn":{"type":["string","null"],"description":"The job's next visit on or after today; null when none is on the calendar."},"weekday":{"anyOf":[{"type":"string","enum":["sunday","monday","tuesday","wednesday","thursday","friday","saturday"]},{"type":"null"}],"description":"The next visit's weekday: the stop's route day as it stands."},"crewId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The next visit's crew, else the job's."}},"required":["jobId","jobName","every","nextVisitId","nextVisitOn","weekday","crewId"],"additionalProperties":false}}},"required":["propertyId","customerId","customerName","address","jobs"],"additionalProperties":false}},"truncated":{"type":"boolean","description":"True when more than 100 properties matched; the first by address are returned."}},"required":["street","properties","truncated"],"additionalProperties":false},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## List jobs priced on less than the lawn measures

> Active jobs priced on an area (per-sq-ft jobs, and programs priced on an estimate line's area) where that area is smaller than the property's measured lawn, the biggest gap (percent) first, each with whether the measurement was reviewed. \`minGapPct\` keeps only gaps at least that large. No margin of error is stored: a gap on an unreviewed auto-measurement is a lead to check, not a finding. Needs property measurement on the company's plan.\
> \
> \*\*Errors specific to this endpoint:\*\* \[\`feature\_not\_available\`]\(<https://docs.shortcutco.com/developers/concepts/errors#feature\\_not\\_available>). Every endpoint can also return the \[common errors]\(<https://docs.shortcutco.com/developers/concepts/errors>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Properties","description":"A property is a customer's service address: where the work happens, with its label, coordinates, and measured lawn area.\n\nFields: [The property object](https://docs.shortcutco.com/developers/reference/objects/property) · [The property access object](https://docs.shortcutco.com/developers/reference/objects/property-access)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["customers:read","jobs:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/properties/priced-below-measured":{"get":{"operationId":"properties.priced_below_measured.list","tags":["Properties"],"summary":"List jobs priced on less than the lawn measures","description":"Active jobs priced on an area (per-sq-ft jobs, and programs priced on an estimate line's area) where that area is smaller than the property's measured lawn, the biggest gap (percent) first, each with whether the measurement was reviewed. `minGapPct` keeps only gaps at least that large. No margin of error is stored: a gap on an unreviewed auto-measurement is a lead to check, not a finding. Needs property measurement on the company's plan.\n\n**Errors specific to this endpoint:** [`feature_not_available`](https://docs.shortcutco.com/developers/concepts/errors#feature_not_available). Every endpoint can also return the [common errors](https://docs.shortcutco.com/developers/concepts/errors).","parameters":[{"name":"minGapPct","in":"query","required":false,"description":"Only gaps of at least this many percent of the priced area. Defaults to 0 (any gap).","schema":{"type":"number","minimum":0,"maximum":1000,"default":0}},{"name":"customerId","in":"query","required":false,"description":"Only this customer's jobs.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"description":"How many jobs, up to 200. Defaults to 50.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"minGapPct":{"type":"number"},"checked":{"type":"object","properties":{"jobsPricedOnArea":{"type":"integer","description":"Active jobs priced on an area."},"withMeasuredLawn":{"type":"integer","description":"Of those, jobs whose property has a measured lawn to compare with."}},"required":["jobsPricedOnArea","withMeasuredLawn"],"additionalProperties":false},"jobs":{"type":"array","items":{"type":"object","properties":{"customerId":{"type":"string","format":"uuid"},"customerName":{"type":"string"},"propertyId":{"type":"string","format":"uuid"},"address":{"type":"string"},"jobId":{"type":"string","format":"uuid"},"jobName":{"type":"string"},"pricedSqft":{"type":"number"},"pricedFrom":{"type":"string","enum":["job_area","estimate_line_area"],"description":"job_area: the square feet a per-sq-ft job bills on; estimate_line_area: the area its estimate line was priced on (a program priced by area)."},"measuredLawnSqft":{"type":"number"},"differenceSqft":{"type":"number","description":"Measured lawn minus priced area."},"differencePct":{"type":["number","null"],"description":"The difference as a percent of the priced area."},"review":{"type":"string","enum":["reviewed","auto_measured_not_reviewed","drawn_not_reviewed","lot_only"],"description":"reviewed: a person accepted or saved the map; auto_measured_not_reviewed: auto-measure drew it and nobody has looked; drawn_not_reviewed: drawn or edited by hand, not marked reviewed; lot_only: lot lines only, no lawn measured. There is no margin of error: say which of these it is, never a margin."}},"required":["customerId","customerName","propertyId","address","jobId","jobName","pricedSqft","pricedFrom","measuredLawnSqft","differenceSqft","differencePct","review"],"additionalProperties":false}},"truncated":{"type":"boolean","description":"True when more jobs matched than `limit`."}},"required":["minGapPct","checked","jobs","truncated"],"additionalProperties":false},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```
