Quickstart

Get your API key

Sign in to the Developer Portal with your Servicebay credentials and TOTP code. Pick an organisation from the dropdown, open API Keys, and click Create API Key.

New keys default to the read bundle, expire in 90 days, and are allowed for both REST (X-API-Key) and MCP (Authorization: Bearer). You can widen scopes, set an IP allowlist, or disable MCP at creation.

Make your first request

Fetch your customers list. Replace YOUR_ORG_ID and the API key with your own values. Customers are ordered by firstName.

curl -X GET \
  'https://developer.servicebay.io/api/v1/organisations/YOUR_ORG_ID/customers' \
  -H 'X-API-Key: sk_live_your_api_key'

const res = await fetch(
  "https://developer.servicebay.io/api/v1/organisations/YOUR_ORG_ID/customers",
  { headers: { "X-API-Key": "sk_live_your_api_key" } }
);
const { data } = await res.json();
console.log(data.customers);

import requests

res = requests.get(
    "https://developer.servicebay.io/api/v1/organisations/YOUR_ORG_ID/customers",
    headers={"X-API-Key": "sk_live_your_api_key"},
)
print(res.json()["data"]["customers"])

The same key works as a Bearer token at the MCP endpoint when allowedUses includes mcp:

curl -X POST https://oauth.servicebay.io/mcp \
  -H 'Authorization: Bearer sk_live_your_api_key' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream'

Read the response

Every Servicebay response uses the same envelope, so you only have to write the parsing code once. 5xx bodies also include a requestId to quote to support.

{
  "success": true,
  "data": {
    "customers": [
      {
        "id": "abc123",
        "firstName": "John",
        "lastName": "Doe",
        "email": "john@example.com",
        "phone": "+1234567890"
      }
    ],
    "pagination": {
      "limit": 50,
      "hasMore": false,
      "nextCursor": null
    }
  }
}

Create something

Creating a customer needs customers:write (widen the key, or use a second write-capable key). firstName is required; everything else is optional. Send Content-Type: application/json — anything else is 415. Bodies over 1 MB are 413.

curl -X POST \
  'https://developer.servicebay.io/api/v1/organisations/YOUR_ORG_ID/customers' \
  -H 'X-API-Key: sk_live_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@example.com",
    "phone": "+0987654321"
  }'

Try the API Playground (optional)

Open the API Playground with the same browser tab you used to create your key. Pick an endpoint, confirm orgId matches your organisation, and click Send Request — no terminal required.