Developer API & Webhooks

What a key is allowed to do

The Permissions grid in the Create a new secret key card has one row per record type and three columns.

Estimates and Invoices show a dash in the Create and Update columns because the API can only read them. If the words in the first column look different in your account — for example Jobs instead of Leads — that is because your organization renamed them in its own settings.

Reading your lead statuses is included with Leads›Read, so a reporting tool does not need a separate tick for it.

Records, filters, and page sizes

Every address starts with the base URL you copied, then the record type. A list request returns many records; adding an ID after the record type returns one.

GET    /leads              GET  /leads/{id}
POST   /leads              PATCH /leads/{id}

GET    /clients            POST /clients        PATCH /clients/{id}
GET    /appointments       POST /appointments   PATCH /appointments/{id}
GET    /tasks              POST /tasks          PATCH /tasks/{id}

GET    /estimates          (read only)      GET /estimates/{id}/items
GET    /invoices           (read only)      GET /invoices/{id}/items
GET    /payments           (read only)
GET    /lead_statuses      (read only, uses the Leads Read permission)
GET    /job_types          GET /service_areas   GET /agents   GET /estimate_templates
GET    /custom_fields?target=lead|client       (Reference data permission)
GET    /reference          everything above in one call
GET    /search?q=          find a customer by name, phone, email or lead number
GET    /leads/{id}/timeline   messages, calls, documents, tasks and payments on one lead
GET    /schedule?date=     jobs and appointments on a day (in your timezone)
GET    /schema             what this key is allowed to do
GET    /openapi.json       the OpenAPI 3.1 description of all of the above
POST   /mcp                the same operations as AI-assistant tools (see below)

Paging and filters

• limit — how many records to return. Default 50, maximum 1000.
• offset — how many to skip, for paging through a long list. Maximum 10000.
• cursor — every list reply carries next_cursor; send it back as cursor to get the next page. Unlike offset it has no ceiling, so use it to walk a whole account.
• created_since and updated_since — only records added or changed on or after a date and time.
• q — a simple name search (first name for leads, clients, and appointments; title for tasks).
• order_by — sort by one of the returned fields. Results always come back newest first.
• Exact matches per record type. For leads those are id, lead_number, status, phone, email, and client_id. Call /schema to see the list for every other record type.

What comes back

{
  "data": [
    {
      "id": "…",
      "lead_number": "…",
      "first_name": "Dana",
      "last_name": "Reyes",
      "phone": "+15551234567",
      "email": "dana@example.com",
      "status": "New",
      "primary_field_worker_id": "…",
      "primary_field_worker_name": "Alex Kim",
      "field_workers": [
        { "id": "…", "name": "Alex Kim", "is_primary": true, "assigned_at": "2026-02-26T14:05:00.000Z" }
      ],
      "created_at": "2026-02-25T18:30:12.123Z"
    }
  ],
  "limit": 50,
  "offset": 0,
  "request_id": "…"
}

Leads also carry their current Field Workers: primary_field_worker_id, primary_field_worker_name, and field_workers (everyone assigned right now, primary first). A removed Field Worker simply drops out of the list, so read these fields for the current team rather than rebuilding it from the timeline. Changing a lead's Field Workers does not change the lead's updated_at, so a sync that must catch assignment changes should re-read the leads it tracks.

A single record request returns data as one object instead of a list. Every reply also carries the same value in an X-Request-ID header, and that value appears in the Recent requests table — quote it if you need help tracing a specific call.

When you create or update a lead or client, only the fields Joby recognises are accepted. Sending anything else — or a protected field such as the record's own ID — is refused with a message listing the fields it rejected. Call /schema to see the exact field list.

Creating a lead with a phone number or email links it to the client Joby already has for that contact (matched by phone first, then email) and only creates a new client when nobody matches. Updating custom_fields changes just the keys you send — send a key as null to clear it. A key can add new custom fields on the fly, up to 150 per record type; past that, create the field in Settings first.

Connect an AI assistant

The same key works as a Model Context Protocol server at https://api.joby.io/v1/mcp, so Claude Code, Claude Desktop and any MCP-capable assistant can search your customers, read a job's timeline and check the schedule — limited to exactly the permissions you ticked. The assistant layer is read-only: it cannot create, change, send or delete anything, even on a key that has Create or Update ticked (those still apply to the API itself). Each tool call shows up in Recent requests like any other request.

claude mcp add --transport http joby https://api.joby.io/v1/mcp \
  --header "Authorization: Bearer YOUR_JOBY_API_KEY"

A key with Reference data and Activity & timeline ticked, plus Read on the records you care about, gives an assistant everything it needs to answer questions. Company owners and admins on Pro and Enterprise can also connect Claude with no key at all, through "Sign in with Joby": see Connect Claude to Joby CRM.

What the error numbers mean

• 401 — the key is missing, wrong, revoked, or past its expiry date.
• 403 — the key is real but not allowed. The reply says which permission was needed, or that developer access is switched off for the organization, or that the workspace is locked over billing.
• 400 — the request body had unknown or protected fields, an invalid value, or pointed at a record that is not in your organization.
• 404 — no such record, or a record type the API does not support.
• 405 — you tried to create or change something the API only lets you read, such as an estimate or invoice.
• 429 — this key went over its per-minute cap. The reply repeats the cap so your code can wait and try again.
• 500 — something went wrong on Joby's side. Safe to retry after a short pause.

{ "error": "Missing scope", "required_scope": "leads:create" }

{ "error": "Rate limit exceeded", "limit_per_minute": 60 }

Managing and revoking keys

The Secret keys card lists every key ever created for the organization. Each row shows:

• The Name you gave it, plus an active or revoked label.
• The first few characters of the key, so you can tell two keys apart.
• Small labels for each permission you ticked.
• Rate limit — the per-minute cap for that key.
• Last used — how long ago it made a request, or Never.

1. Find the key in the Secret keys list.
2. Press Revoke on the right of the row.
3. Confirm in the pop-up. It warns that any integration using that key will stop working.

Watching what the API is doing

The top of the API Keys tab has three counters and the bottom has a request table. This is where you look first when an integration "stopped working".

If an integration stops working

1. Open Settings›Admin›Developer Reference›API Keys.
2. Check the key is still marked active and has not passed its expiry date.
3. Look at Last used. If it says Never or a very old time, the outside tool is not reaching Joby at all — check the address and the key stored in that tool.
4. Scroll to Recent requests and read the status codes. Red codes tell you which failure it is; match them against the error list.
5. If every request is refused with a permission error, create a replacement key with the right boxes ticked.
6. If nothing appears at all and billing is behind, clear the billing issue first — a locked workspace blocks the API too.

Connect Zapier without writing code

Zapier is the no-code route. Joby creates and stores the key for you, with a sensible set of read permissions plus the ability to file new leads and clients.

1. Go to Settings›Integrations.
2. Open the Zapier card.
3. Press Connect Zapier.
4. Copy the connection key shown. Like any key, it is displayed once only.
5. Open Zapier, start a Zap, and search for Joby.
6. When Zapier asks to connect, paste the key.
7. Pick a trigger such as New Lead, then pick an action.

Once connected, the same page shows the first characters of the key and gives you two buttons: Generate new key (the old key stops working straight away, so paste the new one into Zapier) and Disconnect (revokes the key and stops every Zap that used it).

Webhooks inside Automations

Joby's webhooks live in Automations, not on the Developer Reference page. There is one for data coming in and one for data going out.

Letting another system send data into Joby

1. Go to Automations and press New Automation.
2. For the trigger, choose Webhook Received — described in the palette as "Another system posts data to Joby".
3. Save the automation. Until you save, the address is not created yet.
4. In the properties panel on the right, find Webhook Configuration and click the Webhook URL box to copy it.
5. Paste that address into the outside system — your website form builder, Zapier, or whatever is sending the data.
6. Optionally fill in Secret Key. If you set one, the sending system must include the same value in an x-webhook-secret header or Joby will ignore the request.
7. Send one real message from the outside system.
8. Press Refresh in the Last Received Webhook box. The message you just sent should appear, with the time it arrived.
9. Now add your actions — for example Create Lead — and use the received fields to fill them in.

Sending data from Joby to another system

1. In the automation builder, add the action Call a Webhook — "Send the data to an external URL".
2. Paste the destination address into URL.
3. Choose the Method the receiving system expects: GET, POST, or PUT.
4. Fill in Body (JSON) with the information to send. Use the variable picker underneath, or type tokens directly, for example {{Lead.phone}} or {{Estimate.customer_name}}.
5. Save and turn the automation on, then trigger it once and confirm the data arrived on the other side.

A full list of the tokens you can use — and a copy button for each — is on the Reference tab of Settings›Admin›Developer Reference.

Keeping keys safe

• Store keys in a password manager or your software's own secure settings — never in a spreadsheet, email, or chat message.
• Never paste a key into a public web page; anything a browser can see, a visitor can copy.
• Give each tool its own key so you can revoke one without breaking the others.
• Set an Expires date for anything temporary, such as a one-off migration or a contractor's project.
• Review the Secret keys list every few months and revoke anything whose Last used says Never or a very old date.
• Revoke straight away when a team member with access leaves or a key may have been seen by someone else.
• Keep Requests/min as low as the tool can live with; it limits the damage a runaway or stolen key can do.