API Reference

Customers

Manage customer records and look them up by phone or email

Customers are the people (or businesses) you do work for. Each customer record holds contact details, an optional business name, billing address, and a list of devices you've serviced for them. Customers are scoped per organisation.

Endpoints

  • GET/organisations/{orgId}/customers — List customers (paginated)
  • POST/organisations/{orgId}/customers — Create customer
  • GET/organisations/{orgId}/customers/lookup — Find by phone or email (exact match)
  • GET/organisations/{orgId}/customers/{customerId} — Get customer
  • PUT/organisations/{orgId}/customers/{customerId} — Update customer
  • DELETE/organisations/{orgId}/customers/{customerId} — Delete customer

Customer-form workflow

The dedicated lookup endpoint runs an exact-match query server-side and is designed for customer-facing intake forms. Use it to find an existing record before booking a job, then create a job with the returned id. No composite Firestore index is required — phone and email are queried in parallel and deduplicated by document id.

firstName, lastName and email are required on create. Everything else is optional. On update every field is optional — send only what you want to change. The list endpoint supports limit, startAfter (cursor), and search (matches name, email or business).

GET
/organisations/{orgId}/customers

Authorization

apiKey
X-API-Key<token>

API key for authentication. Get your key from the Developer Dashboard.

In: header

Path Parameters

orgId*string

Organisation ID

Query Parameters

limit?integer

Maximum number of items to return (max 100)

Default50
Range1 <= value <= 100
startAfter?string

Cursor for pagination - ID of the last item from previous page

search?string

Search customers by name, email, or business name

Response Body

application/json

application/json

application/json

curl -X GET "https://developer.servicebay.io/api/v1/organisations/string/customers"
{
  "success": true,
  "data": {
    "customers": [
      {
        "id": "string",
        "firstName": "string",
        "lastName": "string",
        "email": "user@example.com",
        "phone": "string",
        "businessName": "string",
        "businessTaxId": "string",
        "addressLine1": "string",
        "addressLine2": "string",
        "city": "string",
        "state": "string",
        "zip": "string",
        "country": "string",
        "createdAt": "2019-08-24T14:15:22Z",
        "devices": [
          {}
        ]
      }
    ],
    "pagination": {
      "limit": 0,
      "hasMore": true,
      "nextCursor": "string"
    }
  }
}
{
  "success": false,
  "error": "An error occurred"
}
{
  "success": false,
  "error": "An error occurred"
}
POST
/organisations/{orgId}/customers

Authorization

apiKey
X-API-Key<token>

API key for authentication. Get your key from the Developer Dashboard.

In: header

Path Parameters

orgId*string

Organisation ID

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://developer.servicebay.io/api/v1/organisations/string/customers" \  -H "Content-Type: application/json" \  -d '{    "firstName": "John",    "lastName": "Doe",    "email": "john.doe@example.com",    "phone": "+1234567890",    "businessName": "Acme Corp"  }'
{
  "success": true,
  "data": {
    "id": "string",
    "firstName": "string",
    "lastName": "string",
    "email": "user@example.com",
    "phone": "string",
    "businessName": "string",
    "businessTaxId": "string",
    "addressLine1": "string",
    "addressLine2": "string",
    "city": "string",
    "state": "string",
    "zip": "string",
    "country": "string",
    "createdAt": "2019-08-24T14:15:22Z",
    "devices": [
      {}
    ]
  }
}
{
  "success": false,
  "error": "An error occurred"
}
{
  "success": false,
  "error": "An error occurred"
}
{
  "success": false,
  "error": "An error occurred"
}
GET
/organisations/{orgId}/customers/lookup

Authorization

apiKey
X-API-Key<token>

API key for authentication. Get your key from the Developer Dashboard.

In: header

Path Parameters

orgId*string

Organisation ID

Query Parameters

phone?string

Exact phone number to match

email?string

Exact email address to match

Formatemail

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://developer.servicebay.io/api/v1/organisations/string/customers/lookup"
{
  "success": true,
  "data": {
    "matches": [
      {
        "id": "string",
        "firstName": "string",
        "lastName": "string",
        "email": "user@example.com",
        "phone": "string",
        "businessName": "string",
        "businessTaxId": "string",
        "addressLine1": "string",
        "addressLine2": "string",
        "city": "string",
        "state": "string",
        "zip": "string",
        "country": "string",
        "createdAt": "2019-08-24T14:15:22Z",
        "devices": [
          {}
        ]
      }
    ],
    "count": 0
  }
}
{
  "success": false,
  "error": "An error occurred"
}
{
  "success": false,
  "error": "An error occurred"
}
{
  "success": false,
  "error": "An error occurred"
}
{
  "success": false,
  "error": "An error occurred"
}
GET
/organisations/{orgId}/customers/{customerId}

Authorization

apiKey
X-API-Key<token>

API key for authentication. Get your key from the Developer Dashboard.

In: header

Path Parameters

orgId*string

Organisation ID

customerId*string

Customer ID

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://developer.servicebay.io/api/v1/organisations/string/customers/string"
{
  "success": true,
  "data": {
    "id": "string",
    "firstName": "string",
    "lastName": "string",
    "email": "user@example.com",
    "phone": "string",
    "businessName": "string",
    "businessTaxId": "string",
    "addressLine1": "string",
    "addressLine2": "string",
    "city": "string",
    "state": "string",
    "zip": "string",
    "country": "string",
    "createdAt": "2019-08-24T14:15:22Z",
    "devices": [
      {}
    ]
  }
}
{
  "success": false,
  "error": "An error occurred"
}
{
  "success": false,
  "error": "An error occurred"
}
{
  "success": false,
  "error": "An error occurred"
}
PUT
/organisations/{orgId}/customers/{customerId}

Authorization

apiKey
X-API-Key<token>

API key for authentication. Get your key from the Developer Dashboard.

In: header

Path Parameters

orgId*string

Organisation ID

customerId*string

Customer ID

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://developer.servicebay.io/api/v1/organisations/string/customers/string" \  -H "Content-Type: application/json" \  -d '{}'
{
  "success": true,
  "data": {
    "id": "string",
    "firstName": "string",
    "lastName": "string",
    "email": "user@example.com",
    "phone": "string",
    "businessName": "string",
    "businessTaxId": "string",
    "addressLine1": "string",
    "addressLine2": "string",
    "city": "string",
    "state": "string",
    "zip": "string",
    "country": "string",
    "createdAt": "2019-08-24T14:15:22Z",
    "devices": [
      {}
    ]
  }
}
{
  "success": false,
  "error": "An error occurred"
}
{
  "success": false,
  "error": "An error occurred"
}
{
  "success": false,
  "error": "An error occurred"
}
{
  "success": false,
  "error": "An error occurred"
}
DELETE
/organisations/{orgId}/customers/{customerId}

Authorization

apiKey
X-API-Key<token>

API key for authentication. Get your key from the Developer Dashboard.

In: header

Path Parameters

orgId*string

Organisation ID

customerId*string

Customer ID

Response Body

application/json

application/json

application/json

application/json

curl -X DELETE "https://developer.servicebay.io/api/v1/organisations/string/customers/string"
{
  "success": true,
  "data": {
    "message": "Operation completed successfully"
  }
}
{
  "success": false,
  "error": "An error occurred"
}
{
  "success": false,
  "error": "An error occurred"
}
{
  "success": false,
  "error": "An error occurred"
}

Machine-readable version: OpenAPI 3.1 spec.

Organisations

Read and update the organisation your API key belongs to

Jobs

Create and manage service jobs (instore, offsite, or remote)

On this page

Endpoints