API keys, webhooks, OAuth apps and MCP

Overview#

TradesWork is open to the other software you use. API keys with only the permissions you choose let a system read or act in TradesWork, including AI assistants like Claude and ChatGPT and the TradesForce marketing platform over MCP (Model Context Protocol). Connected to TradesForce, your leads arrive with where they came from, your ad spend shows next to the revenue it brought in (cost and return on ad spend), and TradesForce can ease off ads when your board is full. Webhooks push a signed event to your URL within about a minute of each change. OAuth apps let developers build integrations any TradesWork company can connect.

Before you start#

• You need the Owner or Admin role.

• Know what is connecting (for example TradesForce or Claude Desktop) and the least it needs. Read-only is safest.

• Keys and secrets are shown once. Have the other app open and ready to paste.

• Only an Owner can turn on Audience export.

Steps#

Connect TradesForce#

1. Open Settings, then REST API, webhooks, OAuth in the Integrations card (the page is titled Developers).

2. In TradesForce & marketing apps, press Connect TradesForce. TradesWork makes a key named TradesForce with the TradesForce marketing permissions.

3. Copy the key now with Copy: it won't be shown again. The line under it shows the MCP URL. Press Done.

4. In TradesForce, open Integrations › Field service software › TradesWork. Enter your TradesWork address and paste the key. If TradesForce offers Connect with OAuth, you can use that instead: sign in to TradesWork, check the permissions on the Connect TradesForce? screen and press Connect.

5. Back in TradesWork, the app shows in the TradesForce & marketing apps table with its permissions and Last call. Press Revoke to disconnect it immediately.

Also on the Integrations card on the Settings home page: Create TradesForce key makes the same key there.

Turn audience export on or off#

1. In Settings › Developers › TradesForce & marketing apps, find Audience export.

2. Read the explanation. TradesForce only gets scrambled codes (SHA-256 hashes) of emails and phone numbers, never names or addresses, and only for customers who agreed to marketing. Anyone who unsubscribed, bounced, texted STOP or is marked Do Not Mail or Do Not Service is always left out.

3. An owner presses Turn on audience export. To stop it, press Turn off and confirm.

4. Every download is logged with how many contacts it had.

Create an API key#

1. Open Settings (gear icon in the top bar) and scroll to the Integrations card at the bottom of the Settings home page.

2. Under New API key, enter a Name (name it after what will use it, for example TradesForce).

3. Under Permissions, tick only what it needs, for example Look up customers, Read jobs and their status, Book new jobs (creates customers and locations), Read open arrival windows and capacity, Read invoices and payments or Subscribe to webhooks.

4. Press Create key. Copy it with Copy key now: it won't be shown again. Keys start with tos_. Press Done.

5. The API keys table shows each key's name, first characters, permissions and Last used. Press Revoke to stop a key immediately.

Connect an MCP client (Claude, ChatGPT, TradesForce)#

1. In the same Integrations card, copy the MCP endpoint.

2. For Claude Desktop and similar clients, copy the configuration snippet shown under it and replace tos_YOUR_KEY with your key. In Claude Desktop: Settings › Developer › Edit config, paste, save, restart.

3. For ChatGPT: Settings › Connectors › Add, then paste the MCP URL and key.

4. For TradesForce: in TradesForce, open its TradesWork integration and paste the key.

5. The Connections hub step Paste it into the other app ticks itself the first time the key is used.

Add a webhook#

1. Open Settings › Integrations › API Application Access (the page is titled Developers).

2. In Webhooks, under Add an endpoint, enter the URL and choose All events or tick specific ones.

3. Press Add endpoint. Copy the signing secret shown so your system can verify each delivery.

4. Press Send test to check it. Delivery log shows every attempt with its result; press Resend on a failed one.

5. Use Pause / Turn on to stop and start deliveries, Rotate secret to replace the signing secret (the old one keeps working for 24 hours), and Delete to remove the endpoint.

Register or connect an OAuth app#

1. Building an integration other contractors can install? In Your OAuth apps, press Register an app, enter App name, Description (optional), Redirect URLs (one per line or comma-separated) and tick Permissions it may ask for, then Register app. You get a client id (authorization code with PKCE).

2. Connected apps lists apps someone in your company connected, with who approved them. Each acts with the permissions shown, never more than the person who approved it. Press Disconnect to remove one.

Settings that change this#

• Settings home › Integrations: API keys, the Create TradesForce key preset and the MCP endpoint.

• Settings › Developers › TradesForce & marketing apps: Connect TradesForce, connected marketing apps, Audience export.

• Settings › Integrations › API Application Access: REST API details (Base URL, OpenAPI, Read the docs), webhooks and OAuth apps.

• Settings › Integrations › Booking Providers & Lead Sources: inbound lead webhooks have their own secrets.

Tips#

• TradesForce works best with the full preset. A key with fewer permissions still works; TradesForce simply can't do the parts it isn't allowed to (for example, without audience export it only sees counts).

• Ad spend TradesForce sends shows as cost and ROAS next to revenue for each campaign. Days with no spend recorded show "—", not $0.

• One key per system, named after it. Then Last used tells you who's calling, and revoking one doesn't break the others.

• Keys can't be widened later. Need another permission? Create a new key and revoke the old one.

• Zapier, n8n and Make can subscribe to webhooks through the API themselves (endpoints show Added by an API key).

• Failed webhook deliveries retry for about 36 hours; an endpoint failing for 3 days is turned off automatically.

Troubleshooting#

• The other app gets 401 → the key was revoked or mistyped. → Create a new key and paste it again.

• It gets 403 "insufficient scope" → the key lacks a permission. → Create a key with the needed permission.

• TradesForce says audiences can't be exported → audience export is off, or the key lacks that permission. → An owner turns on Audience export; if it's still missing, press Connect TradesForce again and paste the new key.

• TradesForce exports fewer contacts than the audience count → only customers who agreed to marketing and aren't unsubscribed or blocked are exported. → This is expected; the count shows the whole segment.

• TradesForce's OAuth connection fails with "wasn't issued for the TradesWork MCP server" → it was connected for the REST API. → Disconnect it and connect again from TradesForce.

• Webhooks can't be added → the page says signing secrets can't be stored yet. → Contact support.

• My endpoint was turned off → it failed for 3 days. → Fix your endpoint, then press Turn on and Send test.

FAQ#

Can an API key see pay rates or payroll? No. API permissions never include pay, and each key only gets the permissions you tick.

Is my key safe in an AI assistant? The assistant can do only what the key allows. Prefer read-only keys for assistants, and revoke them when you stop using them.

Where's the API documentation? On Settings › Integrations › API Application Access, under REST API: OpenAPI and Read the docs.

Does TradesForce see my customers' names and phone numbers? No. It sends leads in and reads counts, revenue and job status. For ad audiences it gets only hashed codes, and only if an owner turns on audience export.

What if TradesForce sends the same lead twice? TradesWork keeps one lead. Leads and ad spend are matched on TradesForce's own ids, so a resend never duplicates anything.

Coming from ServiceTitan#

ServiceTitan's API Application Access connects marketplace apps with a client id, secret and tenant id. TradesWork uses scoped API keys, OAuth apps and webhooks instead, and an MCP endpoint for AI assistants. ServiceTitan apps don't carry over; reconnect each tool to TradesWork. TradesWork never uses ServiceTitan's API to move your data.