> 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).

## 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)."}],"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)."}],"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"}}}}}}
```

## 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)."}],"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)."}],"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"}}}}}}
```

## 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)."}],"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)."}],"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 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)."}],"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)."}],"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"}}}}}}
```