### Successful API Response Example

Source: https://developer.servicebay.io/docs/quickstart

This is an example of a successful JSON response when fetching customer data. It includes customer details and pagination information.

```json
{
  "success": true,
  "data": {
    "customers": [
      {
        "id": "abc123",
        "firstName": "John",
        "lastName": "Doe",
        "email": "john@example.com",
        "phone": "+1234567890",
        "createdAt": "2025-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "limit": 50,
      "hasMore": false,
      "nextCursor": null
    }
  }
}
```

--------------------------------

### Example: Fetching All Customers with Pagination

Source: https://developer.servicebay.io/docs/pagination

This asynchronous function demonstrates how to fetch all customers by repeatedly calling the API with pagination parameters until all data is retrieved. It handles cursor-based pagination using 'startAfter' and 'nextCursor'.

```javascript
async function getAllCustomers(orgId, apiKey) {
  let allCustomers = [];
  let cursor = null;

  do {
    const url = new URL(`https://developer.servicebay.io/api/v1/organisations/${orgId}/customers`);
    url.searchParams.set("limit", "100");
    if (cursor) {
      url.searchParams.set("startAfter", cursor);
    }

    const response = await fetch(url, {
      headers: { "X-API-Key": apiKey },
    });

    const data = await response.json();
    allCustomers = allCustomers.concat(data.data.customers);

    cursor = data.data.pagination.hasMore ? data.data.pagination.nextCursor : null;
  } while (cursor);

  return allCustomers;
}
```

--------------------------------

### View Rate Limit Response Headers

Source: https://developer.servicebay.io/docs/rate-limiting

Example of the HTTP headers returned by the API to indicate current rate limit status.

```http
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705325400
```

--------------------------------

### GET /api/v1/organisations/{orgId}/customers

Source: https://developer.servicebay.io/docs/pagination

Retrieves a paginated list of customers for a specific organization using cursor-based pagination.

```APIDOC
## GET /api/v1/organisations/{orgId}/customers

### Description
Retrieves a list of customers for the specified organization. Results are paginated to handle large datasets.

### Method
GET

### Endpoint
/api/v1/organisations/{orgId}/customers

### Parameters
#### Path Parameters
- **orgId** (string) - Required - The unique identifier of the organization.

#### Query Parameters
- **limit** (integer) - Optional - Maximum items per page (default: 50, max: 100).
- **startAfter** (string) - Optional - Cursor for the next page of results.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the customers list and pagination metadata.
- **pagination** (object) - Metadata including limit, hasMore, and nextCursor.

#### Response Example
{
  "success": true,
  "data": {
    "customers": [],
    "pagination": {
      "limit": 50,
      "hasMore": true,
      "nextCursor": "abc123xyz"
    }
  }
}
```

--------------------------------

### GET /organisations/{orgId}/customers/lookup

Source: https://developer.servicebay.io/docs/api

Performs a server-side exact-match lookup for customers using phone or email identifiers, useful for intake forms.

```APIDOC
## GET /organisations/{orgId}/customers/lookup

### Description
Performs a server-side exact-match lookup by phone or email (or both). Returns up to 10 matches per identifier or 404 if none match.

### Method
GET

### Endpoint
/organisations/{orgId}/customers/lookup

### Parameters
#### Path Parameters
- **orgId** (string) - Required - The unique identifier for the organisation.

#### Query Parameters
- **phone** (string) - Optional - Phone number for lookup.
- **email** (string) - Optional - Email address for lookup.
```

--------------------------------

### Fetch Organisation Customers (cURL)

Source: https://developer.servicebay.io/docs/quickstart

Use this cURL command to retrieve a list of customers for your organization. Replace YOUR_ORG_ID and sk_live_your_api_key with your actual credentials.

```curl
curl -X GET \
  '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'
```

--------------------------------

### Fetch Organisation Customers (Python)

Source: https://developer.servicebay.io/docs/quickstart

This Python snippet shows how to retrieve customer data using the 'requests' library. It configures the request with the correct API endpoint, headers, and content type.

```python
import requests

response = requests.get(
    'https://developer.servicebay.io/api/v1/organisations/YOUR_ORG_ID/customers',
    headers={
        'X-API-Key': 'sk_live_your_api_key',
        'Content-Type': 'application/json',
    }
)

data = response.json()
print(data['data']['customers'])
```

--------------------------------

### Create Organisation Customer (cURL)

Source: https://developer.servicebay.io/docs/quickstart

Use this cURL command to create a new customer within your organization. Ensure you replace placeholders with your actual organization ID and API key.

```curl
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"
  }'
```

--------------------------------

### Fetch Organisation Customers (JavaScript)

Source: https://developer.servicebay.io/docs/quickstart

This JavaScript code snippet demonstrates how to fetch customer data using the fetch API in a Node.js environment. It includes setting the necessary headers for authentication and content type.

```javascript
const response = await fetch("https://developer.servicebay.io/api/v1/organisations/YOUR_ORG_ID/customers", {
  headers: {
    "X-API-Key": "sk_live_your_api_key",
    "Content-Type": "application/json",
  },
});

const data = await response.json();
console.log(data.data.customers);
```

--------------------------------

### Handle 404 Not Found Error

Source: https://developer.servicebay.io/docs/error-handling

Response received when the requested resource ID does not exist.

```json
{
  "success": false,
  "error": "Customer not found"
}
```

--------------------------------

### Create Job with Service Location

Source: https://developer.servicebay.io/docs/api

When creating a job, specify the `serviceLocation` using one of the provided values: `instore`, `offsite`, or `remote`. This, combined with `customerId`, `serviceTime`, and `endTime`, provides all necessary information for an external intake form to book a job after a customer lookup.

```text
instore
offsite
remote
```

--------------------------------

### Authenticate API Request with API Key

Source: https://developer.servicebay.io/docs/api

Include your API key in the `X-API-Key` header for all API requests. Replace `sk_live_your_api_key_here` with your actual key.

```curl
curl -X GET \
  'https://developer.servicebay.io/api/v1/organisations/{orgId}/customers' \
  -H 'X-API-Key: sk_live_your_api_key_here'
```

--------------------------------

### Create Invoice

Source: https://developer.servicebay.io/docs/api

When creating an invoice, the server automatically assigns the next available index.

```http
POST /organisations/{orgId}/invoices
```

--------------------------------

### Create Quote

Source: https://developer.servicebay.io/docs/api

When creating a quote, the server automatically assigns the next available index.

```http
POST /organisations/{orgId}/quotes
```

--------------------------------

### Authenticate with the Servicebay API using cURL

Source: https://developer.servicebay.io/docs/authentication

Include the API key in the X-API-Key header for all requests to the Servicebay API.

```bash
curl -X GET \
  'https://developer.servicebay.io/api/v1/organisations/{orgId}/customers' \
  -H 'X-API-Key: sk_live_your_api_key_here' \
  -H 'Content-Type: application/json'
```

--------------------------------

### Lookup Customer by Phone or Email

Source: https://developer.servicebay.io/docs/api

Perform a server-side exact-match lookup for customers using their phone number, email address, or both. This endpoint is designed for customer-facing intake forms to find existing records before booking a job. It returns up to 10 matches per identifier or a `404` if no matches are found.

```http
GET /organisations/{orgId}/customers/lookup?phone=…&email=…
```

--------------------------------

### Handle 403 Forbidden Error

Source: https://developer.servicebay.io/docs/error-handling

Response received when the provided API key lacks access to the requested organization.

```json
{
  "success": false,
  "error": "You do not have access to this organisation"
}
```

--------------------------------

### Handle 401 Unauthorized Error

Source: https://developer.servicebay.io/docs/error-handling

Response received when the API key is missing or invalid.

```json
{
  "success": false,
  "error": "Missing API key. Include X-API-Key header in your request."
}
```

--------------------------------

### Implement Retry Logic with Fetch

Source: https://developer.servicebay.io/docs/rate-limiting

An asynchronous function that handles 429 errors by waiting until the reset time before retrying the request.

```javascript
async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const resetTime = response.headers.get("X-RateLimit-Reset");
      const waitMs = parseInt(resetTime) * 1000 - Date.now();

      if (waitMs > 0 && attempt < maxRetries - 1) {
        console.log(`Rate limited. Waiting ${waitMs}ms...`);
        await new Promise((resolve) => setTimeout(resolve, waitMs));
        continue;
      }
    }

    return response;
  }

  throw new Error("Max retries exceeded");
}
```

--------------------------------

### API Success Response Format

Source: https://developer.servicebay.io/docs/api

This is the standard format for successful API responses. It includes a success flag and a data object.

```json
{
  "success": true,
  "data": {
    // Response data here
  }
}
```

--------------------------------

### POST /organisations/{orgId}/tickets

Source: https://developer.servicebay.io/docs/api

Creates a new job (ticket) within the specified organisation.

```APIDOC
## POST /organisations/{orgId}/tickets

### Description
Creates a new job (ticket) for the organisation. Jobs are referred to as tickets internally.

### Method
POST

### Endpoint
/organisations/{orgId}/tickets

### Parameters
#### Path Parameters
- **orgId** (string) - Required - The unique identifier for the organisation.

#### Request Body
- **serviceLocation** (string) - Required - Must be one of: 'instore', 'offsite', 'remote'.
- **customerId** (string) - Required - The ID of the customer associated with the job.
- **serviceTime** (string) - Required - The start time of the job.
- **endTime** (string) - Required - The end time of the job.
```

--------------------------------

### Implement API Request Error Handling

Source: https://developer.servicebay.io/docs/error-handling

A wrapper function for fetch that parses JSON responses and throws specific errors based on HTTP status codes.

```javascript
async function makeApiRequest(url, options) {
  const response = await fetch(url, {
    ...options,
    headers: {
      "X-API-Key": API_KEY,
      "Content-Type": "application/json",
      ...options.headers,
    },
  });

  const data = await response.json();

  if (!data.success) {
    switch (response.status) {
      case 401:
        throw new Error("Invalid API key");
      case 403:
        throw new Error("Access denied to this resource");
      case 404:
        throw new Error("Resource not found");
      case 429:
        const resetTime = response.headers.get("X-RateLimit-Reset");
        throw new Error(`Rate limited. Retry after ${resetTime}`);
      default:
        throw new Error(data.error || "Unknown error");
    }
  }

  return data;
}
```

--------------------------------

### Response Format

Source: https://developer.servicebay.io/docs/api

All API responses adhere to a consistent structure, differentiating between successful operations and errors.

```APIDOC
## Response Format

All responses follow a consistent format:

### Success Response
```json
{
  "success": true,
  "data": {
    // Response data here
  }
}
```

### Error Response
```json
{
  "success": false,
  "error": "Description of what went wrong"
}
```
```

--------------------------------

### Rate Limiting

Source: https://developer.servicebay.io/docs/api

API requests are subject to rate limits to ensure fair usage and stability. Rate limit details are provided in the response headers.

```APIDOC
## Rate Limiting

API requests are rate limited to **100 requests per minute** per API key. Rate limit information is included in response headers:

| Header              | Description                                  |
|---------------------|----------------------------------------------|
| `X-RateLimit-Limit` | Maximum requests per minute                  |
| `X-RateLimit-Remaining` | Remaining requests in the current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets    |

For the interactive OpenAPI documentation, visit the OpenAPI Spec endpoint.
```

--------------------------------

### List Calendar Events for a Specific Job

Source: https://developer.servicebay.io/docs/api

To fetch all calendar events associated with a particular job, use the `ticketId` query parameter.

```http
GET /organisations/{orgId}/calendar-events?ticketId={ticketId}
```

--------------------------------

### Servicebay API Base URL

Source: https://developer.servicebay.io/docs/api

The base URL for all Servicebay API requests.

```text
https://developer.servicebay.io/api/v1
```

--------------------------------

### Handle 429 Rate Limited Error

Source: https://developer.servicebay.io/docs/error-handling

Response received when the request rate limit has been exceeded.

```json
{
  "success": false,
  "error": "Rate limit exceeded. Please wait before making more requests."
}
```

--------------------------------

### Define API Error Response Format

Source: https://developer.servicebay.io/docs/error-handling

The standard JSON structure returned by the API when a request fails.

```json
{
  "success": false,
  "error": "Description of what went wrong"
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.