Customers
The people and businesses the workspace serves.
A customer has contact details, tags, custom field values, one or more properties, and the ids you gave it in your other systems.
Fields: The customer object · The contact preferences object · The review request object.
Customers newest first, or by last change when updatedSince is set. Customers are the same people the app's Customers list shows. Attaching or removing a tag and changing a custom-field value count as changes to the customer.
Returns a list of customer objects.
A workspace API token. Each operation lists the scopes it needs; write implies read, and send/complete are never implied.
How many items to return, 1-200. Defaults to 50.
50The meta.nextCursor from the previous page. Omit it for the first page.
Case-insensitive search over name, company name, and email.
Only customers with this status.
Only customers with this tag attached.
With externalId: only the customer with this id in your system.
^[a-z0-9][a-z0-9_.-]{0,63}$With externalSource: only the customer with this id in your system.
^[^\p{Cc}\s/\\]+$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.
Success.
The request is invalid.
The token is missing, invalid, expired, or revoked.
The workspace's subscription needs attention.
The token is missing a required scope.
No such object in this workspace.
Rate limited; see Retry-After.
Internal error.
Temporarily unavailable; retry later.
curl https://api.shortcutco.com/v1/customers \
-H "Authorization: Bearer $SHORTCUT_TOKEN"{
"data": [
{
"id": "e61681e7-e260-4d2e-8eaa-f875daf533bc",
"object": "customer",
"firstName": "Robin",
"lastName": "Alvarez",
"companyName": null,
"email": "robin.alvarez@example.com",
"phone": "(406) 555-0142",
"status": "active",
"tags": [
{
"id": "3f07b03c-3b51-4b83-879c-26ca33e66211",
"name": "Corner lot"
}
],
"externalReferences": [
{
"source": "mywebsite",
"externalId": "contact-58213"
}
],
"createdAt": "2026-10-16T17:04:12.381Z",
"updatedAt": "2026-10-16T17:04:12.381Z"
}
],
"meta": {
"nextCursor": null,
"hasMore": false
}
}Creates a customer with their first property, like adding one in the app. Email is optional; it must not belong to another customer or a team member. With externalReference, your id is saved in the same request, and a duplicate fails the request with 409. If QuickBooks is connected, the customer is queued for sync. Your automations, including those that start when a customer is created, run only if the token has automations:trigger, and then as they do for customers added in the app. Send an Idempotency-Key to retry safely.
Returns the customer object.
Errors specific to this endpoint: already_exists, email_in_use. Every endpoint can also return the common errors.
A workspace API token. Each operation lists the scopes it needs; write implies read, and send/complete are never implied.
Any string up to 255 characters. Retrying with the same key returns the first response instead of repeating the write, for 24 hours.
A new customer with their first property.
First name.
Last name.
Company name, when the customer is a business. Null or empty clears it.
Email address. Optional: without one the customer gets no email from the app. It must not belong to another customer or a team member.
Phone number, such as (406) 555-0142. US numbers may omit the country code.
Success.
The request is invalid.
The token is missing, invalid, expired, or revoked.
The workspace's subscription needs attention.
The token is missing a required scope.
No such object in this workspace.
Conflict with the current state or an in-flight request with the same idempotency key.
The request cannot be applied, or its idempotency key was used for a different request.
Rate limited; see Retry-After.
Internal error.
Temporarily unavailable; retry later.
curl https://api.shortcutco.com/v1/customers \
-X POST \
-H "Authorization: Bearer $SHORTCUT_TOKEN" \
-H "Idempotency-Key: 73494906-6f93-444d-8bdd-bf946827fadb" \
-H "Content-Type: application/json" \
-d '{"firstName":"Robin","lastName":"Alvarez","property":{"address":"412 Elm St, Bozeman, MT 59715"}}'{
"data": {
"id": "ca679ae7-c6b1-462e-82fc-1175bf464cbc",
"object": "customer",
"firstName": "Robin",
"lastName": "Alvarez",
"companyName": null,
"email": null,
"phone": null,
"status": "active",
"tags": [],
"externalReferences": [],
"createdAt": "2026-10-16T17:04:12.381Z",
"updatedAt": "2026-10-16T17:04:12.381Z",
"properties": [
{
"id": "b7674040-b3b1-4b87-8ffb-b6ceac45f215",
"object": "property",
"label": "Home",
"address": "412 Elm St, Bozeman, MT 59715",
"latitude": 45.6793,
"longitude": -111.0373,
"squareFeet": 8200,
"status": "active",
"createdAt": "2026-10-16T17:04:12.381Z",
"updatedAt": "2026-10-16T17:04:12.381Z"
}
]
}
}One customer with their tags, properties, and external ids.
Returns the customer object.
A workspace API token. Each operation lists the scopes it needs; write implies read, and send/complete are never implied.
The object's id.
Success.
The request is invalid.
The token is missing, invalid, expired, or revoked.
The workspace's subscription needs attention.
The token is missing a required scope.
No such object in this workspace.
Rate limited; see Retry-After.
Internal error.
Temporarily unavailable; retry later.
curl https://api.shortcutco.com/v1/customers/ed731568-e9bd-40af-8607-8bf6e251c73d \
-H "Authorization: Bearer $SHORTCUT_TOKEN"{
"data": {
"id": "ed731568-e9bd-40af-8607-8bf6e251c73d",
"object": "customer",
"firstName": "Robin",
"lastName": "Alvarez",
"companyName": null,
"email": "robin.alvarez@example.com",
"phone": "(406) 555-0142",
"status": "active",
"tags": [
{
"id": "74a52178-70ef-4cbf-8d39-98066983d34d",
"name": "Corner lot"
}
],
"externalReferences": [
{
"source": "mywebsite",
"externalId": "contact-58213"
}
],
"createdAt": "2026-10-16T17:04:12.381Z",
"updatedAt": "2026-10-16T17:04:12.381Z",
"properties": [
{
"id": "5de083ec-5a2a-4f33-8674-fa7a52bf35c1",
"object": "property",
"label": "Home",
"address": "412 Elm St, Bozeman, MT 59715",
"latitude": 45.6793,
"longitude": -111.0373,
"squareFeet": 8200,
"status": "active",
"createdAt": "2026-10-16T17:04:12.381Z",
"updatedAt": "2026-10-16T17:04:12.381Z"
}
]
}
}Changes a customer's name, company, email, or phone, like editing their profile in the app. Fields you leave out are unchanged. A new email must not belong to another customer or a team member; changing it clears the workspace's delivery blocks for both addresses so the next email is tried again. If QuickBooks is connected, the change is queued for sync.
Returns the customer object.
Errors specific to this endpoint: email_in_use. Every endpoint can also return the common errors.
A workspace API token. Each operation lists the scopes it needs; write implies read, and send/complete are never implied.
The object's id.
The contact fields to change. Fields you leave out are unchanged.
First name.
Last name.
Company name, when the customer is a business. Null or empty clears it.
Email address. It must not belong to another customer or a team member in the workspace.
Phone number. Null or empty clears it.
Success.
The request is invalid.
The token is missing, invalid, expired, or revoked.
The workspace's subscription needs attention.
The token is missing a required scope.
No such object in this workspace.
Conflict with the current state or an in-flight request with the same idempotency key.
The request cannot be applied, or its idempotency key was used for a different request.
Rate limited; see Retry-After.
Internal error.
Temporarily unavailable; retry later.
curl https://api.shortcutco.com/v1/customers/ed731568-e9bd-40af-8607-8bf6e251c73d \
-X PATCH \
-H "Authorization: Bearer $SHORTCUT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"firstName":"Robin"}'{
"data": {
"id": "ed731568-e9bd-40af-8607-8bf6e251c73d",
"object": "customer",
"firstName": "Robin",
"lastName": "Alvarez",
"companyName": null,
"email": "robin.alvarez@example.com",
"phone": "(406) 555-0142",
"status": "active",
"tags": [
{
"id": "9052604e-8c9c-4b95-88e6-d6dc85311223",
"name": "Corner lot"
}
],
"externalReferences": [
{
"source": "mywebsite",
"externalId": "contact-58213"
}
],
"createdAt": "2026-10-16T17:04:12.381Z",
"updatedAt": "2026-10-16T17:04:12.381Z"
}
}Whether the customer replied STOP to texts, their choice for billing, service, and marketing email, and their access to the customer portal. Check it before messaging a customer.
Returns the contact preferences object.
A workspace API token. Each operation lists the scopes it needs; write implies read, and send/complete are never implied.
The object's id.
Success.
The request is invalid.
The token is missing, invalid, expired, or revoked.
The workspace's subscription needs attention.
The token is missing a required scope.
No such object in this workspace.
Rate limited; see Retry-After.
Internal error.
Temporarily unavailable; retry later.
curl https://api.shortcutco.com/v1/customers/3bd20064-381c-4bab-8466-76f230b0b239/contact-preferences \
-H "Authorization: Bearer $SHORTCUT_TOKEN"{
"data": {
"object": "contact_preferences",
"customerId": "3bd20064-381c-4bab-8466-76f230b0b239",
"textsOptedOut": true,
"email": "robin.alvarez@example.com",
"billingEmail": "enabled",
"serviceEmail": "enabled",
"marketingEmail": "enabled",
"portalAvailable": true,
"portalAccess": "none"
}
}Marks the customer inactive, records a churn reason, and pauses every pending, scheduled, or paused job they have, exactly as archiving in the app does. A note on the customer names the token. Every body field is optional; send {} when you have nothing to add. Deactivating an inactive customer changes nothing. If the token has automations:trigger, automations that start on a customer status change run as they do in the app. Undo with POST /v1/customers/{id}/reactivate.
A workspace API token. Each operation lists the scopes it needs; write implies read, and send/complete are never implied.
The object's id.
Any string up to 255 characters. Retrying with the same key returns the first response instead of repeating the write, for 24 hours.
Why, saved on the customer's note in the app.
The churn reason for retention reports. Defaults to unknown.
Success.
The request is invalid.
The token is missing, invalid, expired, or revoked.
The workspace's subscription needs attention.
The token is missing a required scope.
No such object in this workspace.
Conflict with the current state or an in-flight request with the same idempotency key.
The request cannot be applied, or its idempotency key was used for a different request.
Rate limited; see Retry-After.
Internal error.
Temporarily unavailable; retry later.
curl https://api.shortcutco.com/v1/customers/e2860f19-ded0-4a60-8b1a-85a7d764c0ee/deactivate \
-X POST \
-H "Authorization: Bearer $SHORTCUT_TOKEN" \
-H "Idempotency-Key: 991f4f4d-9569-4a94-81b3-c5db8dfe0122" \
-H "Content-Type: application/json" \
-d '{}'{
"data": {
"customer": {
"id": "e2860f19-ded0-4a60-8b1a-85a7d764c0ee",
"object": "customer",
"firstName": "Robin",
"lastName": "Alvarez",
"companyName": null,
"email": "robin.alvarez@example.com",
"phone": "(406) 555-0142",
"status": "inactive",
"tags": [
{
"id": "86f7719b-8341-4ce2-8f8b-e8297bd62370",
"name": "Corner lot"
}
],
"externalReferences": [
{
"source": "mywebsite",
"externalId": "contact-58213"
}
],
"createdAt": "2026-10-16T17:04:12.381Z",
"updatedAt": "2026-10-16T17:04:12.381Z"
},
"changed": true,
"pausedJobs": 1
}
}Records externalId as this customer's id in source, so the external lookup and upsert find it. Linking is always explicit; the API never matches a customer to your id by email or address. Repeating the same link changes nothing. If the id already belongs to another customer, or this customer already has a different id in source, the request fails with 409 and nothing changes.
Returns the customer object.
Errors specific to this endpoint: already_exists, external_reference_exists. Every endpoint can also return the common errors.
A workspace API token. Each operation lists the scopes it needs; write implies read, and send/complete are never implied.
The object's id.
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.
^[a-z0-9][a-z0-9_.-]{0,63}$Any string up to 255 characters. Retrying with the same key returns the first response instead of repeating the write, for 24 hours.
The object's id in that system.
The object's id in that system: 1-255 characters, no spaces, slashes, or control characters.
^[^\p{Cc}\s/\\]+$Success.
The request is invalid.
The token is missing, invalid, expired, or revoked.
The workspace's subscription needs attention.
The token is missing a required scope.
No such object in this workspace.
Conflict with the current state or an in-flight request with the same idempotency key.
The request cannot be applied, or its idempotency key was used for a different request.
Rate limited; see Retry-After.
Internal error.
Temporarily unavailable; retry later.
curl https://api.shortcutco.com/v1/customers/ca3cb5b9-c686-4100-82d1-2c47bf1b678e/external-references/mywebsite \
-X PUT \
-H "Authorization: Bearer $SHORTCUT_TOKEN" \
-H "Idempotency-Key: aeb9211c-ab03-4c63-874d-97aaa397d2f1" \
-H "Content-Type: application/json" \
-d '{"externalId":"contact-58213"}'{
"data": {
"id": "ca3cb5b9-c686-4100-82d1-2c47bf1b678e",
"object": "customer",
"firstName": "Robin",
"lastName": "Alvarez",
"companyName": null,
"email": "robin.alvarez@example.com",
"phone": "(406) 555-0142",
"status": "active",
"tags": [
{
"id": "fd1e5f02-f968-4a49-85b2-d590f1fd10d7",
"name": "Corner lot"
}
],
"externalReferences": [
{
"source": "mywebsite",
"externalId": "contact-58213"
}
],
"createdAt": "2026-10-16T17:04:12.381Z",
"updatedAt": "2026-10-16T17:04:12.381Z",
"properties": [
{
"id": "1eaf9aee-1af9-4635-8744-117c138e4cc3",
"object": "property",
"label": "Home",
"address": "412 Elm St, Bozeman, MT 59715",
"latitude": 45.6793,
"longitude": -111.0373,
"squareFeet": 8200,
"status": "active",
"createdAt": "2026-10-16T17:04:12.381Z",
"updatedAt": "2026-10-16T17:04:12.381Z"
}
]
}
}Removes this customer's id in source. The customer itself is unchanged. Unlinking when there is no link changes nothing.
Returns the customer object.
A workspace API token. Each operation lists the scopes it needs; write implies read, and send/complete are never implied.
The object's id.
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.
^[a-z0-9][a-z0-9_.-]{0,63}$Success.
The request is invalid.
The token is missing, invalid, expired, or revoked.
The workspace's subscription needs attention.
The token is missing a required scope.
No such object in this workspace.
Conflict with the current state or an in-flight request with the same idempotency key.
The request cannot be applied, or its idempotency key was used for a different request.
Rate limited; see Retry-After.
Internal error.
Temporarily unavailable; retry later.
curl https://api.shortcutco.com/v1/customers/ca3cb5b9-c686-4100-82d1-2c47bf1b678e/external-references/mywebsite \
-X DELETE \
-H "Authorization: Bearer $SHORTCUT_TOKEN"{
"data": {
"id": "ca3cb5b9-c686-4100-82d1-2c47bf1b678e",
"object": "customer",
"firstName": "Robin",
"lastName": "Alvarez",
"companyName": null,
"email": "robin.alvarez@example.com",
"phone": "(406) 555-0142",
"status": "active",
"tags": [
{
"id": "d7ab564e-d3f5-4195-803f-ccdccc8a0823",
"name": "Corner lot"
}
],
"externalReferences": [],
"createdAt": "2026-10-16T17:04:12.381Z",
"updatedAt": "2026-10-16T17:04:12.381Z",
"properties": [
{
"id": "7f95ee3a-7be0-4981-882a-64c87474a00f",
"object": "property",
"label": "Home",
"address": "412 Elm St, Bozeman, MT 59715",
"latitude": 45.6793,
"longitude": -111.0373,
"squareFeet": 8200,
"status": "active",
"createdAt": "2026-10-16T17:04:12.381Z",
"updatedAt": "2026-10-16T17:04:12.381Z"
}
]
}
}Marks an inactive customer active again and clears the churn reason, as reactivating in the app does. A customer who is not inactive is left alone: changed: false with resumeJobs: keep_paused, and 409 customer_not_inactive when asked to resume jobs. Their paused jobs stay paused unless resumeJobs is now or date, which resumes every paused job and needs the jobs:write scope. Every body field is optional; send {} to reactivate without resuming jobs. A note on the customer names the token. If the token has automations:trigger, automations that start on a customer status change run as they do in the app.
Errors specific to this endpoint: customer_not_inactive, jobs_not_resumable. Every endpoint can also return the common errors.
A workspace API token. Each operation lists the scopes it needs; write implies read, and send/complete are never implied.
The object's id.
Any string up to 255 characters. Retrying with the same key returns the first response instead of repeating the write, for 24 hours.
What happens to the customer's paused jobs: keep_paused (the default) leaves them paused, now resumes them from today, date from resumeDate. Resuming needs the jobs:write scope.
With resumeJobs: date, the workspace-local date (YYYY-MM-DD, today or later) jobs resume from.
^\d{4}-\d{2}-\d{2}$Why, saved on the customer's note in the app.
Success.
The request is invalid.
The token is missing, invalid, expired, or revoked.
The workspace's subscription needs attention.
The token is missing a required scope.
No such object in this workspace.
Conflict with the current state or an in-flight request with the same idempotency key.
The request cannot be applied, or its idempotency key was used for a different request.
Rate limited; see Retry-After.
Internal error.
Temporarily unavailable; retry later.
curl https://api.shortcutco.com/v1/customers/b1fd7b47-ae47-468e-8a91-f1d5a6dc2d1c/reactivate \
-X POST \
-H "Authorization: Bearer $SHORTCUT_TOKEN" \
-H "Idempotency-Key: 41c5235f-3e0f-4ea6-8a59-99ed36a3d534" \
-H "Content-Type: application/json" \
-d '{}'{
"data": {
"customer": {
"id": "b1fd7b47-ae47-468e-8a91-f1d5a6dc2d1c",
"object": "customer",
"firstName": "Robin",
"lastName": "Alvarez",
"companyName": null,
"email": "robin.alvarez@example.com",
"phone": "(406) 555-0142",
"status": "active",
"tags": [
{
"id": "d0c04b7d-cd0a-46c4-8954-c20bc59efd52",
"name": "Corner lot"
}
],
"externalReferences": [
{
"source": "mywebsite",
"externalId": "contact-58213"
}
],
"createdAt": "2026-10-16T17:04:12.381Z",
"updatedAt": "2026-10-16T17:04:12.381Z"
},
"changed": true,
"resumedJobs": 1
}
}The review requests sent to the customer after visits, newest first, with whether they opened the link and any private feedback they left.
Returns a list of review request objects.
A workspace API token. Each operation lists the scopes it needs; write implies read, and send/complete are never implied.
The object's id.
How many items to return, 1-200. Defaults to 50.
50The meta.nextCursor from the previous page. Omit it for the first page.
Success.
The request is invalid.
The token is missing, invalid, expired, or revoked.
The workspace's subscription needs attention.
The token is missing a required scope.
No such object in this workspace.
Rate limited; see Retry-After.
Internal error.
Temporarily unavailable; retry later.
curl https://api.shortcutco.com/v1/customers/3a58f63e-36a3-4185-82ed-6ccc2f37a813/review-requests \
-H "Authorization: Bearer $SHORTCUT_TOKEN"{
"data": [
{
"id": "1454b2dd-109e-4e24-8ce9-296b093364b2",
"object": "review_request",
"customerId": "3a58f63e-36a3-4185-82ed-6ccc2f37a813",
"visitId": "48f7a360-4541-4ea7-818c-19ee3dd65535",
"status": "queued",
"queuedFor": "2026-10-16T17:04:12.381Z",
"sentAt": "2026-10-16T17:04:12.381Z",
"clickedAt": null,
"feedback": [
{
"text": "Example text",
"submittedAt": "2026-10-16T17:04:12.381Z"
}
],
"createdAt": "2026-10-16T17:04:12.381Z"
}
],
"meta": {
"nextCursor": null,
"hasMore": false
}
}The tags attached to the customer, in the order they were attached.
A workspace API token. Each operation lists the scopes it needs; write implies read, and send/complete are never implied.
The object's id.
Success.
The request is invalid.
The token is missing, invalid, expired, or revoked.
The workspace's subscription needs attention.
The token is missing a required scope.
No such object in this workspace.
Rate limited; see Retry-After.
Internal error.
Temporarily unavailable; retry later.
curl https://api.shortcutco.com/v1/customers/1f118ed6-1b5b-4a1d-87a6-056413f040ab/tags \
-H "Authorization: Bearer $SHORTCUT_TOKEN"{
"data": [
{
"id": "73a17b31-6feb-4678-8c35-f1bf68802d06",
"name": "Corner lot"
}
]
}Replaces the customer's whole tag list with tagIds: missing tags are attached (in the order given) and every tag not listed is removed. Tags must exist (POST /v1/tags creates one). Any change counts as a change to the customer for updatedSince. If the token has automations:trigger, automations that start when a tag is added or removed run as they do for changes in the app.
A workspace API token. Each operation lists the scopes it needs; write implies read, and send/complete are never implied.
The object's id.
Any string up to 255 characters. Retrying with the same key returns the first response instead of repeating the write, for 24 hours.
Every tag the customer should have, by id. Tags not listed are removed; an empty list removes all.
Success.
The request is invalid.
The token is missing, invalid, expired, or revoked.
The workspace's subscription needs attention.
The token is missing a required scope.
No such object in this workspace.
Conflict with the current state or an in-flight request with the same idempotency key.
The request cannot be applied, or its idempotency key was used for a different request.
Rate limited; see Retry-After.
Internal error.
Temporarily unavailable; retry later.
curl https://api.shortcutco.com/v1/customers/1f118ed6-1b5b-4a1d-87a6-056413f040ab/tags \
-X PUT \
-H "Authorization: Bearer $SHORTCUT_TOKEN" \
-H "Idempotency-Key: a0006c95-9c4a-47dc-8894-e32394df1e6a" \
-H "Content-Type: application/json" \
-d '{"tagIds":["c0106ba0-bc5a-46e7-88a4-e22eb4ef1d75"]}'{
"data": [
{
"id": "57c49786-540e-42cd-8059-0e144ca3495b",
"name": "Corner lot"
}
]
}Everything that happened with the customer, newest first, as the profile's Activity tab shows it: visits, texts and emails, estimates, invoices and payments, automations, notes, tasks, posts, photos, and chemical applications, including what happened while they were a lead. Covers the 200 most recent events. Filter by group to get one kind of activity. Photos, videos, and files appear as attachment references; GET /v1/attachments/{id} returns a download link.
Returns a list of timeline event objects.
A workspace API token. Each operation lists the scopes it needs; write implies read, and send/complete are never implied.
The object's id.
How many items to return, 1-200. Defaults to 50.
50The meta.nextCursor from the previous page. Omit it for the first page.
Only events in this group, as the Activity tab's filters group them.
Success.
The request is invalid.
The token is missing, invalid, expired, or revoked.
The workspace's subscription needs attention.
The token is missing a required scope.
No such object in this workspace.
Rate limited; see Retry-After.
Internal error.
Temporarily unavailable; retry later.
curl https://api.shortcutco.com/v1/customers/b063dd68-acae-48af-88f8-53f6a5428f3d/timeline \
-H "Authorization: Bearer $SHORTCUT_TOKEN"{
"data": [
{
"id": "Example id",
"object": "timeline_event",
"kind": "Example kind",
"group": "comments",
"occurredAt": "2026-10-16T17:04:12.381Z",
"title": "Example title",
"detail": "Example detail",
"authorName": "Example authorName",
"attachments": [
{
"id": "5dc7b1e3-5a11-4d2a-865c-287152a663b8",
"source": "activity_post",
"type": "photo",
"filename": "Example filename"
}
],
"taskId": "8bbe8264-8808-4dab-8452-f8f2809d3439",
"activityPostId": "5364b902-4fae-4449-8bf9-2f9048436ad7",
"visitIds": [
"3b7b8049-37c5-4b90-840f-f6d7305a321e"
],
"viaApp": "Example viaApp"
}
],
"meta": {
"nextCursor": null,
"hasMore": false
}
}The customer your id maps to, as GET /v1/customers/{id} returns it, or 404.
Returns the customer object.
A workspace API token. Each operation lists the scopes it needs; write implies read, and send/complete are never implied.
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.
^[a-z0-9][a-z0-9_.-]{0,63}$The object's id in that system: 1-255 characters, no spaces, slashes, or control characters.
^[^\p{Cc}\s/\\]+$Success.
The request is invalid.
The token is missing, invalid, expired, or revoked.
The workspace's subscription needs attention.
The token is missing a required scope.
No such object in this workspace.
Rate limited; see Retry-After.
Internal error.
Temporarily unavailable; retry later.
curl https://api.shortcutco.com/v1/customers/external/mywebsite/contact-58213 \
-H "Authorization: Bearer $SHORTCUT_TOKEN"{
"data": {
"id": "7dcab79e-7a14-42e5-865f-2e2c72a96973",
"object": "customer",
"firstName": "Robin",
"lastName": "Alvarez",
"companyName": null,
"email": "robin.alvarez@example.com",
"phone": "(406) 555-0142",
"status": "active",
"tags": [
{
"id": "4592308f-41dc-4bd6-8e26-a71d3a70e264",
"name": "Corner lot"
}
],
"externalReferences": [
{
"source": "mywebsite",
"externalId": "contact-58213"
}
],
"createdAt": "2026-10-16T17:04:12.381Z",
"updatedAt": "2026-10-16T17:04:12.381Z",
"properties": [
{
"id": "18c16b6b-150b-46b2-8155-e1f90da01d40",
"object": "property",
"label": "Home",
"address": "412 Elm St, Bozeman, MT 59715",
"latitude": 45.6793,
"longitude": -111.0373,
"squareFeet": 8200,
"status": "active",
"createdAt": "2026-10-16T17:04:12.381Z",
"updatedAt": "2026-10-16T17:04:12.381Z"
}
]
}
}The sync endpoint. If your id is new, creates the customer as POST /v1/customers does and saves the id (created: true, status 201). If it exists, applies the contact fields that differ from the stored ones as PATCH does and ignores property (created: false, status 200); a request that changes nothing writes nothing. Concurrent requests for the same id run one after another, so they never create two customers.
Errors specific to this endpoint: email_in_use, external_reference_changed. Every endpoint can also return the common errors.
A workspace API token. Each operation lists the scopes it needs; write implies read, and send/complete are never implied.
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.
^[a-z0-9][a-z0-9_.-]{0,63}$The object's id in that system: 1-255 characters, no spaces, slashes, or control characters.
^[^\p{Cc}\s/\\]+$Any string up to 255 characters. Retrying with the same key returns the first response instead of repeating the write, for 24 hours.
The customer as in POST /v1/customers. When the reference is new the customer is created; when it exists, the contact fields update the mapped customer and property is ignored.
First name.
Last name.
Company name, when the customer is a business. Null or empty clears it.
Email address. Optional: without one the customer gets no email from the app. It must not belong to another customer or a team member.
Phone number, such as (406) 555-0142. US numbers may omit the country code.
Success.
Your id was new: the customer was created and your id saved (created: true).
The request is invalid.
The token is missing, invalid, expired, or revoked.
The workspace's subscription needs attention.
The token is missing a required scope.
No such object in this workspace.
Conflict with the current state or an in-flight request with the same idempotency key.
The request cannot be applied, or its idempotency key was used for a different request.
Rate limited; see Retry-After.
Internal error.
Temporarily unavailable; retry later.
curl https://api.shortcutco.com/v1/customers/external/mywebsite/contact-58213 \
-X PUT \
-H "Authorization: Bearer $SHORTCUT_TOKEN" \
-H "Idempotency-Key: 4599dbe2-41e4-4729-8e2e-52703a788db7" \
-H "Content-Type: application/json" \
-d '{"firstName":"Robin","lastName":"Alvarez","property":{"address":"412 Elm St, Bozeman, MT 59715"}}'{
"data": {
"created": false,
"customer": {
"id": "8a824e89-86cc-49d0-8316-c5177f61005e",
"object": "customer",
"firstName": "Robin",
"lastName": "Alvarez",
"companyName": null,
"email": null,
"phone": null,
"status": "active",
"tags": [],
"externalReferences": [
{
"source": "mywebsite",
"externalId": "contact-58213"
}
],
"createdAt": "2026-10-16T17:04:12.381Z",
"updatedAt": "2026-10-16T17:04:12.381Z",
"properties": [
{
"id": "55921f36-51dc-4a7d-8e26-95c44a70d10b",
"object": "property",
"label": "Home",
"address": "412 Elm St, Bozeman, MT 59715",
"latitude": 45.6793,
"longitude": -111.0373,
"squareFeet": 8200,
"status": "active",
"createdAt": "2026-10-16T17:04:12.381Z",
"updatedAt": "2026-10-16T17:04:12.381Z"
}
]
}
}
}Last updated