API Reference

Jobs

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

Jobs are the work you do for a customer — repairs, installations, on-site visits. A job links a customer to a scheduled time window, an optional technician, and a service location.

Naming note

Jobs are exposed under the /tickets collection. The Servicebay mobile and web apps use the term ticket internally; both terms refer to the same resource. The endpoint paths below all begin with /tickets.

Endpoints

  • GET/organisations/{orgId}/tickets — List jobs (paginated)
  • POST/organisations/{orgId}/tickets — Create job
  • GET/organisations/{orgId}/tickets/{ticketId} — Get job
  • PUT/organisations/{orgId}/tickets/{ticketId} — Update job
  • DELETE/organisations/{orgId}/tickets/{ticketId} — Delete job

List supports filtering by status, customerId, and assignedTechnician.

Service location

When creating or updating a job, set serviceLocation to one of:

ValueMeaning
instoreJob performed at the business premises
offsiteJob performed at the customer's address
remoteJob performed remotely (no physical location)

Combined with customerId, serviceTime, and endTime, this is everything an external intake form needs to book a job after a customer-lookup match.

Status

status is a free-form string. The Servicebay app commonly uses Open, In Progress, and Closed, but any value is accepted — integrators can define their own workflow states.

GET
/organisations/{orgId}/tickets

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

status?string

Filter by ticket status

Value in"Open" | "In Progress" | "Closed"
customerId?string

Filter by customer ID

assignedTechnician?string

Filter by assigned technician ID

Response Body

application/json

application/json

application/json

curl -X GET "https://developer.servicebay.io/api/v1/organisations/string/tickets"
{
  "success": true,
  "data": {
    "tickets": [
      {
        "id": "string",
        "ticketId": 0,
        "status": "Open",
        "timestamp": "2019-08-24T14:15:22Z",
        "ticketClosedTimestamp": "2019-08-24T14:15:22Z",
        "customerId": "string",
        "customerName": "string",
        "customerEmail": "user@example.com",
        "customerPhone": "string",
        "customerDeviceName": "string",
        "customerDeviceType": "string",
        "deviceId": "string",
        "assignedTechnician": "string",
        "serviceRequired": "string",
        "serviceNotes": "string",
        "serviceTime": "2019-08-24T14:15:22Z",
        "endTime": "2019-08-24T14:15:22Z",
        "serviceAddress": "string",
        "serviceLocation": "instore",
        "warrantyRepair": true,
        "alternativeCustomerAddress": true,
        "additionalItems": [
          {}
        ],
        "messageRooms": {}
      }
    ],
    "pagination": {
      "limit": 0,
      "hasMore": true,
      "nextCursor": "string"
    }
  }
}
{
  "success": false,
  "error": "An error occurred"
}
{
  "success": false,
  "error": "An error occurred"
}
POST
/organisations/{orgId}/tickets

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/tickets" \  -H "Content-Type: application/json" \  -d '{    "customerId": "customer123",    "customerName": "John Doe",    "customerEmail": "john@example.com",    "serviceRequired": "Device Repair",    "status": "Open"  }'
{
  "success": true,
  "data": {
    "id": "string",
    "ticketId": 0,
    "status": "Open",
    "timestamp": "2019-08-24T14:15:22Z",
    "ticketClosedTimestamp": "2019-08-24T14:15:22Z",
    "customerId": "string",
    "customerName": "string",
    "customerEmail": "user@example.com",
    "customerPhone": "string",
    "customerDeviceName": "string",
    "customerDeviceType": "string",
    "deviceId": "string",
    "assignedTechnician": "string",
    "serviceRequired": "string",
    "serviceNotes": "string",
    "serviceTime": "2019-08-24T14:15:22Z",
    "endTime": "2019-08-24T14:15:22Z",
    "serviceAddress": "string",
    "serviceLocation": "instore",
    "warrantyRepair": true,
    "alternativeCustomerAddress": true,
    "additionalItems": [
      {}
    ],
    "messageRooms": {}
  }
}
{
  "success": false,
  "error": "An error occurred"
}
{
  "success": false,
  "error": "An error occurred"
}
{
  "success": false,
  "error": "An error occurred"
}
GET
/organisations/{orgId}/tickets/{ticketId}

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

ticketId*string

Ticket ID

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://developer.servicebay.io/api/v1/organisations/string/tickets/string"
{
  "success": true,
  "data": {
    "id": "string",
    "ticketId": 0,
    "status": "Open",
    "timestamp": "2019-08-24T14:15:22Z",
    "ticketClosedTimestamp": "2019-08-24T14:15:22Z",
    "customerId": "string",
    "customerName": "string",
    "customerEmail": "user@example.com",
    "customerPhone": "string",
    "customerDeviceName": "string",
    "customerDeviceType": "string",
    "deviceId": "string",
    "assignedTechnician": "string",
    "serviceRequired": "string",
    "serviceNotes": "string",
    "serviceTime": "2019-08-24T14:15:22Z",
    "endTime": "2019-08-24T14:15:22Z",
    "serviceAddress": "string",
    "serviceLocation": "instore",
    "warrantyRepair": true,
    "alternativeCustomerAddress": true,
    "additionalItems": [
      {}
    ],
    "messageRooms": {}
  }
}
{
  "success": false,
  "error": "An error occurred"
}
{
  "success": false,
  "error": "An error occurred"
}
{
  "success": false,
  "error": "An error occurred"
}
PUT
/organisations/{orgId}/tickets/{ticketId}

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

ticketId*string

Ticket 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/tickets/string" \  -H "Content-Type: application/json" \  -d '{}'
{
  "success": true,
  "data": {
    "id": "string",
    "ticketId": 0,
    "status": "Open",
    "timestamp": "2019-08-24T14:15:22Z",
    "ticketClosedTimestamp": "2019-08-24T14:15:22Z",
    "customerId": "string",
    "customerName": "string",
    "customerEmail": "user@example.com",
    "customerPhone": "string",
    "customerDeviceName": "string",
    "customerDeviceType": "string",
    "deviceId": "string",
    "assignedTechnician": "string",
    "serviceRequired": "string",
    "serviceNotes": "string",
    "serviceTime": "2019-08-24T14:15:22Z",
    "endTime": "2019-08-24T14:15:22Z",
    "serviceAddress": "string",
    "serviceLocation": "instore",
    "warrantyRepair": true,
    "alternativeCustomerAddress": true,
    "additionalItems": [
      {}
    ],
    "messageRooms": {}
  }
}
{
  "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}/tickets/{ticketId}

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

ticketId*string

Ticket ID

Response Body

application/json

application/json

application/json

application/json

curl -X DELETE "https://developer.servicebay.io/api/v1/organisations/string/tickets/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.

Customers

Manage customer records and look them up by phone or email

Services

Manage reusable service templates with pricing and warranty defaults

On this page

EndpointsService locationStatus