> 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/readme/configuration/api-and-integrations.md).

# API & integrations

Connect QuickBooks, use Shortcut from Claude, ChatGPT and other AI apps, and create API tokens for your own tools.

**API & integrations** is where you connect Shortcut to other software: your accounting, AI apps like Claude and ChatGPT, and any tool you or a developer build. Open **Settings → Workspace → API & integrations**. [Open API & integrations →](https://shortcutco.com/settings/api)

Only company admins see this page, and only on the web. In the mobile app it says **Use the web app**.

The page has these sections, top to bottom:

* **Waiting for approval** — changes your AI apps and tokens asked to make, when one is waiting.
* **Integrations** — QuickBooks Online and Office email.
* **Connect an AI app** — set up Claude, ChatGPT and other AI apps.
* **Connected apps** — the AI apps an admin has approved.
* **API tokens** and **Usage** — keys for your own tools and integrations.
* **Webhooks** — send events, like a paid invoice, to another system as they happen.

## Integrations

The **QuickBooks Online** row shows where your connection stands: **Connected** with when it last synced, **Finish setup** if you started connecting and didn't pick a start date, or **Needs reconnect** if QuickBooks signed Shortcut out. On an older plan without QuickBooks, the row shows a **Growth** lock. Click the row to open the QuickBooks page. See [QuickBooks integration](https://docs.shortcutco.com/readme/configuration/quickbooks-integration.md).

The **Office email** row brings customer email into the Inbox and each customer's timeline. Once it's set up, it shows the office address and **Connected**, or **Waiting for first email** until the first one arrives, or **Needs reconnect** if Microsoft signed Shortcut out. Click the row to open the Office email page. See [Office email](https://docs.shortcutco.com/readme/configuration/office-email.md).

## Connect an AI app

Connect an AI app and you can use Shortcut from inside it: ask about your customers, schedule, estimates and invoices in plain words, and, if you allow it, have the app make changes for you. A company admin connects each app once and approves what it can do.

<figure><img src="https://2299783971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOhi7KtJ4vY1pDKwWu5SV%2Fuploads%2Fgit-blob-3eaca2f92495d1bdd223267b34bc6388ffbf9833%2Fsettings-api-connect-ai-app.png?alt=media" alt="Settings → API &#x26; integrations: the Connect an AI app section with tiles for Claude, ChatGPT, Grok, Claude Code, Cursor, VS Code, Codex, Windsurf and Other app, each with a Sign in, API token or Sign in or API token badge, and the Connected apps section below reading No connected apps yet"><figcaption><p>Pick your app. Once you approve it, it shows under Connected apps.</p></figcaption></figure>

Each tile names the app and how it signs in:

| Tile            | What it is               | Signs in with            |
| --------------- | ------------------------ | ------------------------ |
| **Claude**      | Web, desktop, and mobile | **Sign in**              |
| **ChatGPT**     | ChatGPT on the web       | **Sign in**              |
| **Grok**        | Grok on the web          | **Sign in or API token** |
| **Claude Code** | Terminal and IDE         | **Sign in**              |
| **Cursor**      | Editor                   | **Sign in**              |
| **VS Code**     | GitHub Copilot           | **Sign in**              |
| **Codex**       | CLI and IDE extension    | **Sign in**              |
| **Windsurf**    | Cascade                  | **API token**            |
| **Other app**   | Any MCP client           | **Sign in or API token** |

**Sign in** means the app sends you to Shortcut to sign in with your own account and approve it. There's no key to copy. **API token** means you create a token on this page and paste it into the app.

### Set up an app

1. Click the app's tile. A setup sheet opens.
2. Click **Copy URL** to copy Shortcut's server address.
3. Follow the numbered steps on the sheet. They tell you where to paste the address in that app. Some apps have a command or settings snippet to paste instead, with a **Copy command** or **Copy config** button, and Cursor and VS Code have a one-click install link.
4. For a **Sign in** app, your browser opens Shortcut. Sign in if asked, check what the app will be able to do, then click **Approve**. Back in the app, Shortcut's tools appear within a few seconds.
5. For **Windsurf**, or for **Grok** or **Other app** when the app asks for a key instead of sending you to sign in, click **Create token** on the sheet. The token's name is filled in for you. Pick its access (the sheet says which), create it, and copy the token straight into the app's settings: Shortcut shows it only once.

Some apps have their own rules about who can add a connection. For example, ChatGPT needs a Business, Enterprise, Edu or Pro plan, on Claude's Team and Enterprise plans an Owner adds the connector first, and on Grok Business and Enterprise an admin adds the connector in xAI's console. The setup sheet says so, and links to a full setup guide.

### The approval screen

When an app asks to connect, Shortcut shows **Connect** *app* **to Shortcut**, with:

* **App** — the app's name, and whether Shortcut has verified it (for example **Verified by Shortcut**).
* **Sends you back to** — where you go after you answer.
* **Workspace** — your company, and which account you're signed in as.
* A warning if something deserves a second look, such as **This app runs on your computer** (normal for Claude Code and similar tools) or **Check where this app sends you**.
* The list of what the app **will be able to** do, with a note on anything that messages customers or changes money.
* **What should** *app* **be able to do?**, when the app asked only to read. Choose one:
  * **Only what it asked for** — the list above. Recommended until you trust what it does.
  * **Work for you as an AI agent** — it can also add and change customers, leads, estimates, jobs, visits, notes, tasks, services, products and tags, build draft project estimates, post to a customer's activity, text and email your customers, send estimates and invoices, see and change gate and lockbox codes, and start your automations. Anything that reaches your customers or reveals a gate code carries a warning. It can never complete visits, record payments, or void invoices. A new AI agent connection starts with [access levels](#access-levels) that ask you before it messages a customer or moves a visit.

Most AI apps ask only to read. Choose **Work for you as an AI agent** if you want the app to finish work for you, like sending the estimate it drafted. An AI agent can also build a project estimate for you from a spreadsheet or a bid document: it starts the draft project and adds the phases and priced lines, and you review and send it from **Projects**. It can't send, approve or bill a project. Developers: see [Build a project estimate](https://docs.shortcutco.com/developers/guides/build-a-project-estimate). If you approve an app again later and choose differently, the newest approval replaces the old one.

The app acts as you in your company. Only approve apps you trust and set up yourself just now. Click **Approve** to connect it, or **Deny** to refuse.

Only company admins can approve. If an employee tries, Shortcut shows **Ask a company admin**.

## Waiting for approval

When a connected app or token is set to **Do after approval** in an area, a change it asks for there doesn't happen right away. It waits at the top of this page, under **Waiting for approval**. Every company admin gets a push notification and an email naming the app and what it asked, for example *Grok is waiting for approval*. Each admin can switch these off under **App waiting for approval** in **Settings → General → Notifications** (see [Push notifications](https://docs.shortcutco.com/readme/mobile-app.md#push-notifications)). An app can also hand you a link that opens this page on its request.

Each row shows what the app or token wants to do, which one asked, the area, when it asked and when the request expires. Click **Details** to see what the change will look like, for example the note's text or the visit's new date. Then:

* Click **Approve** to make the change, exactly as the app asked. Approving a message to a customer (a text, an email, or sending an estimate or invoice) or a payment change asks once more first, because it can't be taken back. The row then says **Done**, or **Failed** with the reason.
* Click **Reject** and nothing changes. The row says **Rejected**.

A request nobody decides expires after 72 hours and shows **Expired**. The app sees the outcome and can tell you. If you disconnect an app or revoke a token, its waiting changes can no longer run; approving one fails and nothing changes.

If an approved change was cut off before it finished, its row shows **Stopped** with **Try again**. Click it to finish the change. Anything that already went through isn't done twice, and it doesn't ask you to confirm again.

## Access levels

Scopes say what a connected app or token may ever touch. **Access levels** say how far it goes on its own, area by area: **Customers and leads**, **Schedule and dispatch**, **Messages to customers**, **Estimates and invoices**, **Payments and refunds**, **Team and timesheets**, **Settings**, and **Reports and numbers**. Click **Access levels** on a connected app or token, pick a level for each area, and click **Save**. The row shows a summary, such as **2 areas need approval** or **No limits**.

| Level                 | What the app can do in that area                                                                                    |
| --------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Off**               | Nothing, not even look.                                                                                             |
| **Look**              | Look only.                                                                                                          |
| **Draft**             | Prepare things, like a draft estimate, but not send to customers or change money. A person finishes it in Shortcut. |
| **Do after approval** | Ask; the change waits under **Waiting for approval** until an admin approves it.                                    |
| **Do**                | Make the change right away.                                                                                         |

A connected app that can change things, and a new **AI agent** token, start at the AI agent defaults: customers, estimates and reports **Do**; schedule, messages, team and settings **Do after approval**; payments **Draft**. **Use AI agent defaults** in the drawer sets them again. Other tokens, and apps and tokens connected before access levels existed, have **No limits**. Click **Remove all limits** to go back to that. A level never gives an app more than its scopes allow.

<figure><img src="https://2299783971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOhi7KtJ4vY1pDKwWu5SV%2Fuploads%2Fgit-blob-0db486b6073f00aa144daa7d3df1bf73b8964830%2Fsettings-api-access-levels.png?alt=media" alt="The Access levels for Grok drawer: the five levels explained (Off, Look, Draft, Do after approval, Do), the Use AI agent defaults and Remove all limits buttons, and a grid of areas set to the AI agent defaults, with Customers and leads, Estimates and invoices and Reports and numbers on Do, Payments and refunds on Draft, and the rest on Do after approval"><figcaption><p>Pick how far the app goes on its own in each area.</p></figcaption></figure>

When an app or token changes something, the customer's **Activity** says which one: for example **Comment · Chance A. · via Grok**. A token shows its name.

## Connected apps

**Connected apps** lists every AI app an admin has approved. Each row shows the app, how much it can do (**Read everything**, **AI agent**, or a number of scopes you can point at to see), who connected it and when, and when it was last used. Once an app has changed something, the row shows its **Last change**; point at it to see its last five changes from the past 30 days.

To cut an app off, click **Disconnect** on its row and confirm. It loses access on its next request. To use it again, someone signs in from the app and approves it again.

Each app acts as the admin who connected it. If that person is deactivated, deactivates their own account, or is changed from admin to employee, the apps they connected are disconnected. API tokens they created keep working.

## API tokens

An API token is a key that lets another tool read or change your Shortcut data, for example Zapier, your website, a reporting tool, or an AI agent you run yourself. Give each tool its own token, with only what it needs. Revoke a token and anything using it stops at once.

### Create a token

1. Click **Create token** at the top of the page.
2. Give it a **Name** you'll recognize later, like the tool that will use it.
3. Choose when it **Expires**: **30 days**, **90 days**, **1 year** or **No expiry**.
4. Choose its **Scopes**, the things the token is allowed to do:
   * **Read everything** — can look at everything except gate and lockbox codes, and change nothing. The safe choice for reporting, and for a new AI app until you trust what it does.
   * **AI agent** — for an AI app you direct, such as Grok, Claude or ChatGPT: everything Standard integration can do (below), plus texting and emailing your customers, sending estimates and invoices, reading and setting gate codes, and starting your automations. It can't complete visits, record payments, void invoices or manage webhooks. An AI agent token starts with the AI agent [access levels](#access-levels).
   * **Standard integration** — can look at everything Read everything can, add or update customers, leads, estimates, jobs, visits, notes, tasks, services, products and tags, build draft project estimates, post to a customer's activity, and manage webhooks. It can't message your customers or touch money.
   * **Custom** — pick each one yourself in a grid of **Read**, **Write**, **Send**, **Complete** and **Manage** for each kind of record.
5. Click **Create token**.
6. Shortcut shows the token once. Click **Copy token** and paste it into your tool, or keep it somewhere safe like a password manager. **Copy this token now**: it will not be shown again.

Some scopes reach your customers, your money or your properties: **Send estimates**, **Send invoices**, **Send messages**, **Complete visits** (which creates the invoice and can charge autopay), **Write payments**, **Trigger automations**, and **Read** and **Write property access** (gate and lockbox codes). Each one shows a warning in the grid. Only the **AI agent** preset holds any of them: the ones that message customers, and gate codes. **Complete visits** and **Write payments** are in no preset; turn them on with **Custom** only when the tool needs them.

<figure><img src="https://2299783971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOhi7KtJ4vY1pDKwWu5SV%2Fuploads%2Fgit-blob-843a5beccf99b20ef0f6385ddb8bc9e86e3aca63%2Fsettings-api-create-token.png?alt=media" alt="The Create token dialog: Name Grok, Expires set to 90 days, the Read everything, AI agent, Standard integration and Custom presets with AI agent selected, and the scope grid underneath with Send estimates ticked"><figcaption><p>Give each tool its own token, with only the scopes it needs.</p></figcaption></figure>

### Your tokens

The **API tokens** list shows each token's name, the start of the key, its scopes, who created it, when it was last used (**Never used** if it hasn't been) and when it expires. Its status is **Active**, **Expired** or **Revoked**. A token that has changed something shows its **Last change**, the same way as a connected app.

To stop a token, click **Revoke** on its row, then **Revoke token**. Anything using it stops working on its next request. This can't be undone; create a new token to reconnect.

A developer will find the **OpenAPI document** link at the top of the **API tokens** section.

### Usage

**Usage** shows how many tokens are active, how many were used in the last 24 hours and the last 30 days, and when the last request came in. Under that, each token and connected app that made calls in the last 7 days gets a row: how many calls and errors, and the calls Shortcut refused, such as a tool that needed a scope the token doesn't have. If an app keeps saying it can't do something, look here first.

## Webhooks

A webhook tells another system about something the moment it happens in Shortcut: an invoice gets paid, a visit is completed, a lead comes in. You give Shortcut a web address that belongs to the other system and pick the events you want. From then on Shortcut sends each event there as it happens, so nobody has to check back. The other system can be Zapier or Make, your own server, or an AI agent. A workspace can have up to 20 webhooks.

You'll usually set one up with a developer, or with a tool that gives you the address to paste. What they need to know about what Shortcut sends, and how to check it came from Shortcut, is in the [developer docs](https://docs.shortcutco.com/developers/webhooks/overview).

### Create a webhook

1. Click **Create webhook** in the Webhooks section.
2. Paste the **Endpoint URL** your tool or developer gave you. It must start with `https://` and be reachable from the internet.
3. Add a **Description** if you like, such as "Zapier: new invoices", so you can tell webhooks apart later.
4. Under **Events**, tick what to send. Events are grouped by **Customers**, **Leads**, **Estimates**, **Jobs**, **Visits**, **Invoices** and **Payments**; tick a group to send everything in it, or tick single events listed under it. Each group names the API scope it uses, which only matters to a developer. The footer counts how many you've picked.
5. Click **Create webhook**.
6. Shortcut shows the **Signing secret** once. Click **Copy secret** and paste it into your tool where it asks for a secret, or hand it to your developer; their side uses it to check that each delivery really came from Shortcut. **Copy this signing secret now**: it will not be shown again. If you lose it, rotate it (below).
7. Click **Done**. The new webhook appears in the list.

To check the other system receives it, open the row's **⋯** menu and click **Send test event**. Shortcut says **Test event delivered** or **Test event failed** and why.

<figure><img src="https://2299783971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOhi7KtJ4vY1pDKwWu5SV%2Fuploads%2Fgit-blob-06bf4f9eeebdf9081be76a833bbf3738e2f734bd%2Fsettings-api-webhooks.png?alt=media" alt="Settings → API &#x26; integrations: the Webhooks section with the Create webhook button and one webhook row showing its endpoint, event chips, an Active status and when it was created in Settings"><figcaption><p>Each webhook shows where it sends, what it sends and whether it's healthy.</p></figcaption></figure>

### The webhooks list

Each row shows the **Endpoint** (the site first, with your description under it), the **Events** it sends, its **Status**, and when it was **Created** and how: **Created in Settings** or **Created with an API token**. The status is one of:

* **Active** — events are being sent.
* **Paused** — you paused it. New events are held for up to 30 days and sent when you resume it.
* **Turned off** — Shortcut turned it off after too many failures. See [When a webhook is turned off](#when-a-webhook-is-turned-off).

The **⋯** menu on a row has **View deliveries**, **Send test event**, **Pause** or **Resume**, **Edit…** (change the address, description or events), **Rotate secret…** and **Delete…**. Deleting stops sending at once and removes the delivery history; it can't be undone.

### Rotate the secret

If the signing secret may have leaked, or you lost it, click **⋯ → Rotate secret…** on the row, then **Rotate secret**. Shortcut shows a **New signing secret** once; copy it into your tool the same way as before. For the next 24 hours deliveries carry both the old and the new signature, so the other system keeps working while you update it. The row says **Old secret works until** and when.

### Deliveries

**⋯ → View deliveries** lists the webhook's latest 50 deliveries, newest first; Shortcut keeps them for 30 days. Each one shows the **Event**, its **Status**, how many **Attempts** Shortcut made, the **Last response** (**HTTP 200**, say, or **No response** and the reason), when it was **Created**, and the **Next attempt** if one is scheduled. A delivery is:

* **Succeeded** — the other system accepted it.
* **Pending** — it's being sent, or waiting for the next attempt.
* **Failed** — the last attempt didn't get through; Shortcut will try again.
* **Exhausted** — Shortcut gave up after six attempts over about 15 hours.
* **Held** — the webhook is paused; it will be sent when you resume.

Click **Retry** on a failed or exhausted delivery to send it again within about a minute. Retry is unavailable while the webhook is paused or turned off.

### When a webhook is turned off

If 50 attempts in a row fail, Shortcut turns the webhook off: its status becomes **Turned off**, the row shows how many attempts failed in a row, and every company admin gets a notification and an email naming the endpoint. Events that happen while it's off are not kept. Once the other system is fixed, click **⋯ → Turn back on…**, then **Turn back on**; the failure count starts over. Send a test event afterwards to make sure it answers.

{% hint style="info" %}
**Support sessions.** When Shortcut support is signed in to your account to help, they can see and revoke tokens and apps, but can't create tokens, change access levels, approve waiting changes, or approve an AI app.
{% endhint %}

<details>

<summary>Still stuck?</summary>

Email **<hello@shortcutco.com>** with a screenshot of the API & integrations page.

</details>
