Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

List customers

get

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.

Required scopes
This endpoint requires the following scopes:
Authorizations
AuthorizationstringRequired

A workspace API token. Each operation lists the scopes it needs; write implies read, and send/complete are never implied.

Query parameters
limitinteger · min: 1 · max: 200Optional

How many items to return, 1-200. Defaults to 50.

Default: 50
cursorstring · min: 1 · max: 4096Optional

The meta.nextCursor from the previous page. Omit it for the first page.

qstring · min: 1 · max: 200Optional

Case-insensitive search over name, company name, and email.

statusstring · enumOptional

Only customers with this status.

Possible values:
tagIdstring · uuidOptional

Only customers with this tag attached.

externalSourcestringOptional

With externalId: only the customer with this id in your system.

Pattern: ^[a-z0-9][a-z0-9_.-]{0,63}$
externalIdstring · min: 1 · max: 255Optional

With externalSource: only the customer with this id in your system.

Pattern: ^[^\p{Cc}\s/\\]+$
updatedSincestring · date-timeOptional

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.

Responses
200

Success.

application/json
get/v1/customers
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
  }
}

Create a customer

post

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.

Required scopes
This endpoint requires the following scopes:
Authorizations
AuthorizationstringRequired

A workspace API token. Each operation lists the scopes it needs; write implies read, and send/complete are never implied.

Header parameters
Idempotency-Keystring · max: 255Optional

Any string up to 255 characters. Retrying with the same key returns the first response instead of repeating the write, for 24 hours.

Body

A new customer with their first property.

firstNamestring · min: 1 · max: 100Required

First name.

lastNamestring · min: 1 · max: 100Required

Last name.

companyNamestring · max: 120 · nullableOptional

Company name, when the customer is a business. Null or empty clears it.

emailstring · email · max: 254Optional

Email address. Optional: without one the customer gets no email from the app. It must not belong to another customer or a team member.

phonestring · max: 30Optional

Phone number, such as (406) 555-0142. US numbers may omit the country code.

Responses
201

Success.

application/json
post/v1/customers
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"
      }
    ]
  }
}

Get a customer

get

One customer with their tags, properties, and external ids.

Returns the customer object.

Required scopes
This endpoint requires the following scopes:
Authorizations
AuthorizationstringRequired

A workspace API token. Each operation lists the scopes it needs; write implies read, and send/complete are never implied.

Path parameters
idstring · uuidRequired

The object's id.

Responses
200

Success.

application/json
get/v1/customers/{id}
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"
      }
    ]
  }
}

Update a customer

patch

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.

Required scopes
This endpoint requires the following scopes:
Authorizations
AuthorizationstringRequired

A workspace API token. Each operation lists the scopes it needs; write implies read, and send/complete are never implied.

Path parameters
idstring · uuidRequired

The object's id.

Body

The contact fields to change. Fields you leave out are unchanged.

firstNamestring · min: 1 · max: 100Optional

First name.

lastNamestring · min: 1 · max: 100Optional

Last name.

companyNamestring · max: 120 · nullableOptional

Company name, when the customer is a business. Null or empty clears it.

emailstring · email · max: 254Optional

Email address. It must not belong to another customer or a team member in the workspace.

phonestring · max: 30 · nullableOptional

Phone number. Null or empty clears it.

Responses
200

Success.

application/json
patch/v1/customers/{id}
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"
  }
}

Get how a customer can be reached

get

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.

Required scopes
This endpoint requires the following scopes:
Authorizations
AuthorizationstringRequired

A workspace API token. Each operation lists the scopes it needs; write implies read, and send/complete are never implied.

Path parameters
idstring · uuidRequired

The object's id.

Responses
200

Success.

application/json
get/v1/customers/{id}/contact-preferences
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"
  }
}

Deactivate a customer

post

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.

Required scopes
This endpoint requires the following scopes:
Authorizations
AuthorizationstringRequired

A workspace API token. Each operation lists the scopes it needs; write implies read, and send/complete are never implied.

Path parameters
idstring · uuidRequired

The object's id.

Header parameters
Idempotency-Keystring · max: 255Optional

Any string up to 255 characters. Retrying with the same key returns the first response instead of repeating the write, for 24 hours.

Body
reasonstring · max: 500Optional

Why, saved on the customer's note in the app.

churnReasonstring · enumOptional

The churn reason for retention reports. Defaults to unknown.

Possible values:
Responses
200

Success.

application/json
post/v1/customers/{id}/deactivate
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
  }
}

Link a customer to your id

put

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.

Required scopes
This endpoint requires the following scopes:
Authorizations
AuthorizationstringRequired

A workspace API token. Each operation lists the scopes it needs; write implies read, and send/complete are never implied.

Path parameters
idstring · uuidRequired

The object's id.

sourcestringRequired

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.

Pattern: ^[a-z0-9][a-z0-9_.-]{0,63}$
Header parameters
Idempotency-Keystring · max: 255Optional

Any string up to 255 characters. Retrying with the same key returns the first response instead of repeating the write, for 24 hours.

Body

The object's id in that system.

externalIdstring · min: 1 · max: 255Required

The object's id in that system: 1-255 characters, no spaces, slashes, or control characters.

Pattern: ^[^\p{Cc}\s/\\]+$
Responses
200

Success.

application/json
put/v1/customers/{id}/external-references/{source}
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"
      }
    ]
  }
}

Unlink a customer from your id

delete

Removes this customer's id in source. The customer itself is unchanged. Unlinking when there is no link changes nothing.

Returns the customer object.

Required scopes
This endpoint requires the following scopes:
Authorizations
AuthorizationstringRequired

A workspace API token. Each operation lists the scopes it needs; write implies read, and send/complete are never implied.

Path parameters
idstring · uuidRequired

The object's id.

sourcestringRequired

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.

Pattern: ^[a-z0-9][a-z0-9_.-]{0,63}$
Responses
200

Success.

application/json
delete/v1/customers/{id}/external-references/{source}
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"
      }
    ]
  }
}

Reactivate a customer

post

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.

Required scopes
This endpoint requires the following scopes:
Authorizations
AuthorizationstringRequired

A workspace API token. Each operation lists the scopes it needs; write implies read, and send/complete are never implied.

Path parameters
idstring · uuidRequired

The object's id.

Header parameters
Idempotency-Keystring · max: 255Optional

Any string up to 255 characters. Retrying with the same key returns the first response instead of repeating the write, for 24 hours.

Body
resumeJobsstring · enumOptional

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.

Possible values:
resumeDatestringOptional

With resumeJobs: date, the workspace-local date (YYYY-MM-DD, today or later) jobs resume from.

Pattern: ^\d{4}-\d{2}-\d{2}$
reasonstring · max: 500Optional

Why, saved on the customer's note in the app.

Responses
200

Success.

application/json
post/v1/customers/{id}/reactivate
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
  }
}

List a customer's review requests

get

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.

Required scopes
This endpoint requires the following scopes:
Authorizations
AuthorizationstringRequired

A workspace API token. Each operation lists the scopes it needs; write implies read, and send/complete are never implied.

Path parameters
idstring · uuidRequired

The object's id.

Query parameters
limitinteger · min: 1 · max: 200Optional

How many items to return, 1-200. Defaults to 50.

Default: 50
cursorstring · min: 1 · max: 4096Optional

The meta.nextCursor from the previous page. Omit it for the first page.

Responses
200

Success.

application/json
get/v1/customers/{id}/review-requests
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
  }
}

List a customer's tags

get

The tags attached to the customer, in the order they were attached.

Required scopes
This endpoint requires the following scopes:
Authorizations
AuthorizationstringRequired

A workspace API token. Each operation lists the scopes it needs; write implies read, and send/complete are never implied.

Path parameters
idstring · uuidRequired

The object's id.

Responses
200

Success.

application/json
get/v1/customers/{id}/tags
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"
    }
  ]
}

Set a customer's tags

put

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.

Required scopes
This endpoint requires the following scopes:
Authorizations
AuthorizationstringRequired

A workspace API token. Each operation lists the scopes it needs; write implies read, and send/complete are never implied.

Path parameters
idstring · uuidRequired

The object's id.

Header parameters
Idempotency-Keystring · max: 255Optional

Any string up to 255 characters. Retrying with the same key returns the first response instead of repeating the write, for 24 hours.

Body
tagIdsstring · uuid[] · max: 100Required

Every tag the customer should have, by id. Tags not listed are removed; an empty list removes all.

Responses
200

Success.

application/json
put/v1/customers/{id}/tags
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"
    }
  ]
}

List a customer's timeline

get

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.

Required scopes
This endpoint requires the following scopes:
Authorizations
AuthorizationstringRequired

A workspace API token. Each operation lists the scopes it needs; write implies read, and send/complete are never implied.

Path parameters
idstring · uuidRequired

The object's id.

Query parameters
limitinteger · min: 1 · max: 200Optional

How many items to return, 1-200. Defaults to 50.

Default: 50
cursorstring · min: 1 · max: 4096Optional

The meta.nextCursor from the previous page. Omit it for the first page.

groupstring · enumOptional

Only events in this group, as the Activity tab's filters group them.

Possible values:
Responses
200

Success.

application/json
get/v1/customers/{id}/timeline
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
  }
}

Get a customer by your id

get

The customer your id maps to, as GET /v1/customers/{id} returns it, or 404.

Returns the customer object.

Required scopes
This endpoint requires the following scopes:
Authorizations
AuthorizationstringRequired

A workspace API token. Each operation lists the scopes it needs; write implies read, and send/complete are never implied.

Path parameters
sourcestringRequired

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.

Pattern: ^[a-z0-9][a-z0-9_.-]{0,63}$
externalIdstring · min: 1 · max: 255Required

The object's id in that system: 1-255 characters, no spaces, slashes, or control characters.

Pattern: ^[^\p{Cc}\s/\\]+$
Responses
200

Success.

application/json
get/v1/customers/external/{source}/{externalId}
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"
      }
    ]
  }
}

Create or update a customer by your id

put

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.

Required scopes
This endpoint requires the following scopes:
Authorizations
AuthorizationstringRequired

A workspace API token. Each operation lists the scopes it needs; write implies read, and send/complete are never implied.

Path parameters
sourcestringRequired

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.

Pattern: ^[a-z0-9][a-z0-9_.-]{0,63}$
externalIdstring · min: 1 · max: 255Required

The object's id in that system: 1-255 characters, no spaces, slashes, or control characters.

Pattern: ^[^\p{Cc}\s/\\]+$
Header parameters
Idempotency-Keystring · max: 255Optional

Any string up to 255 characters. Retrying with the same key returns the first response instead of repeating the write, for 24 hours.

Body

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.

firstNamestring · min: 1 · max: 100Required

First name.

lastNamestring · min: 1 · max: 100Required

Last name.

companyNamestring · max: 120 · nullableOptional

Company name, when the customer is a business. Null or empty clears it.

emailstring · email · max: 254Optional

Email address. Optional: without one the customer gets no email from the app. It must not belong to another customer or a team member.

phonestring · max: 30Optional

Phone number, such as (406) 555-0142. US numbers may omit the country code.

Responses
200

Success.

application/json
put/v1/customers/external/{source}/{externalId}
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