### Create a client

Source: https://context7.com/hightreequency/jobberschema/llms.txt

Example of how to create a new client, including handling potential business logic validation errors returned in `userErrors`.

```APIDOC
```javascript
async function createClient(accessToken, clientInput) {
  const endpoint = "https://api.getjobber.com/api/graphql";

  const mutation = `
    mutation CreateClient($client: ClientCreateInput!) {
      clientCreate(client: $client) {
        client {
          id
          name
          jobberWebUri
        }
        userErrors {
          message
          path
        }
      }
    }
  `;

  const response = await fetch(endpoint, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "X-JOBBER-GRAPHQL-VERSION": "2025-01-20",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: mutation,
      variables: { client: clientInput },
    }),
  });

  const { data, errors } = await response.json();

  // Top-level GraphQL transport/syntax errors
  if (errors && errors.length > 0) {
    throw new Error(`GraphQL transport error: ${errors[0].message}`);
  }

  const { client, userErrors } = data.clientCreate;

  // Business logic validation errors
  if (userErrors && userErrors.length > 0) {
    const messages = userErrors.map(e => `[${e.path.join(".")} ${e.message}`);
    throw new Error(`Client creation failed: ${messages.join("; ")}`);
  }

  // Success
  console.log(`Created client: ${client.name} (${client.id})`);
  console.log(`View in Jobber: ${client.jobberWebUri}`);
  return client;
}

// Usage
createClient(token, {
  firstName: "Jordan",
  lastName: "Lee",
  emails: [{ address: "jordan@example.com", primary: true, description: "MAIN" }],
}).catch(console.error);
```
```

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

### Sample webhook payload

Source: https://context7.com/hightreequency/jobberschema/llms.txt

An example of the JSON payload that a webhook endpoint will receive when an event occurs.

```APIDOC
```bash
# Sample webhook payload your endpoint receives (POST):
# {
#   "accountId": "Z2lkOi8vSm9iYmVyL0FjY291bnQvMTIz",
#   "appId": "your_app_id",
#   "itemId": "Z2lkOi8vSm9iYmVyL1Zpc2l0Lzk4Nw==",
#   "occuredAt": "2025-06-15T11:03:22Z",
#   "topic": "VISIT_COMPLETE"
# }
```
```

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

### Sample Webhook Payload

Source: https://context7.com/hightreequency/jobberschema/llms.txt

This is an example of the JSON payload your endpoint will receive when a webhook event occurs. It includes details about the event and associated Jobber entities.

```json
# Sample webhook payload your endpoint receives (POST):
# {
#   "accountId": "Z2lkOi8vSm9iYmVyL0FjY291bnQvMTIz",
#   "appId": "your_app_id",
#   "itemId": "Z2lkOi8vSm9iYmVyL1Zpc2l0Lzk4Nw==",
#   "occuredAt": "2025-06-15T11:03:22Z",
#   "topic": "VISIT_COMPLETE"
# }
```

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

### List Today's and Active Visits

Source: https://context7.com/hightreequency/jobberschema/llms.txt

Fetches visits scheduled for today or currently active, with filtering by date range and sorting by start time. Useful for dispatchers and field staff.

```graphql
query ListTodaysVisits {
  visits(
    filter: {
      visitStatus: [TODAY, ACTIVE]
      startDate: { from: "2025-06-01T00:00:00Z", to: "2025-06-01T23:59:59Z" }
    }
    sort: [{ key: START_AT, direction: ASCENDING }]
    first: 50
  ) {
    nodes {
      id
      title
      instructions
      startAt
      endAt
      allDay
      isComplete
      visitStatus(timezone: "America/Toronto")
      job {
        id
        jobNumber
        title
        billingFrequency
      }
      client {
        id
        name
        phones { number primary }
      }
      property {
        id
        address { street1 city province postalCode }
      }
      assignedUsers(first: 10) {
        nodes {
          id
          name { full }
          assignedVehicle { id name }
        }
      }
      actionsUponComplete
      completedAt
    }
    pageInfo { hasNextPage endCursor }
    totalCount
  }
}
```

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

### Get Unified Schedule Items

Source: https://context7.com/hightreequency/jobberschema/llms.txt

Retrieves a combined list of visits, tasks, events, and assessments within a specified date range. Supports filtering by scheduling aspect (assigned, unassigned, all).

```graphql
query GetSchedule($from: ISO8601DateTime!, $to: ISO8601DateTime!) {
  scheduledItems(
    filter: {
      startsBetween: { from: $from, to: $to }
      scheduledItemType: [VISIT, EVENT, TASK, ASSESSMENT]
      schedulingAspect: ALL
    }
    sort: [{ key: COMPLETED, direction: ASCENDING }]
    first: 100
  ) {
    nodes {
      id
      title
      startAt
      endAt
      allDay
      isComplete
      duration
      assignedUsers(first: 5) {
        nodes { id name { full } }
      }
      ... on Visit {
        visitStatus
        job { id jobNumber title }
        client { id name }
        property { address { street1 city } }
      }
      ... on Task {
        instructions
        isRecurring
        client { id name }
      }
      ... on Event {
        description
        createdBy { id name { full } }
      }
      ... on Assessment {
        request { id title requestStatus }
      }
    }
    pageInfo { hasNextPage endCursor }
    totalCount
  }
}
```

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

### Paginate through all clients

Source: https://context7.com/hightreequency/jobberschema/llms.txt

Demonstrates how to paginate through a large list of clients using cursor-based pagination with `first` and `after` arguments.

```APIDOC
```javascript
// JavaScript example: paginate through all clients
async function getAllClients(accessToken) {
  const endpoint = "https://api.getjobber.com/api/graphql";
  const headers = {
    "Authorization": `Bearer ${accessToken}`,
    "X-JOBBER-GRAPHQL-VERSION": "2025-01-20",
    "Content-Type": "application/json",
  };

  const query = `
    query ListClients($after: String) {
      clients(first: 50, after: $after) {
        nodes {
          id
          name
          balance
          createdAt
        }
        pageInfo {
          hasNextPage
          endCursor
        }
        totalCount
      }
    }
  `;

  let allClients = [];
  let after = null;
  let hasNextPage = true;

  while (hasNextPage) {
    const response = await fetch(endpoint, {
      method: "POST",
      headers,
      body: JSON.stringify({ query, variables: { after } }),
    });

    const { data, errors } = await response.json();

    if (errors) {
      throw new Error(`GraphQL errors: ${JSON.stringify(errors)}`);
    }

    const { nodes, pageInfo, totalCount } = data.clients;
    allClients = allClients.concat(nodes);
    hasNextPage = pageInfo.hasNextPage;
    after = pageInfo.endCursor;

    console.log(`Fetched ${allClients.length} / ${totalCount} clients`);
  }

  return allClients;
}
```
```

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

### Create and Complete a Job Visit

Source: https://context7.com/hightreequency/jobberschema/llms.txt

Use `visitCreate` to schedule a new visit for a job, specifying start/end times, title, instructions, and assigned users. Use `visitComplete` to mark a visit as finished.

```graphql
# Create a visit on a job
mutation CreateVisit {
  visitCreate(
    jobId: "Z2lkOi8vSm9iYmVyL0pvYi8xMjM="
    visit: {
      visits: [
        {
          schedule: {
            startAt: { isoTimestamp: "2025-06-15T09:00:00-04:00" }
            endAt: { isoTimestamp: "2025-06-15T11:00:00-04:00" }
          }
          title: "Initial Spring Cleanup"
          instructions: "Focus on backyard. Gate code is 4521."
          assignedUserIds: ["Z2lkOi8vSm9iYmVyL1VzZXIvNDU2"]
        }
      ]
    }
  ) {
    visit {
      id
      title
      startAt
      endAt
      visitStatus
      assignedUsers(first: 5) { nodes { id name { full } } }
    }
    userErrors { message path }
  }
}

# Complete a visit
mutation CompleteVisit {
  visitComplete(id: "Z2lkOi8vSm9iYmVyL1Zpc2l0Lzk4Nw==") {
    visit {
      id
      isComplete
      completedAt
      actionsUponComplete
    }
    userErrors { message path }
  }
}
```

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

### Create a New Client

Source: https://context7.com/hightreequency/jobberschema/llms.txt

Use this mutation to create a new client record. Provide contact details, address, and specify if it's a company. The mutation returns the created client or any user errors encountered.

```graphql
mutation CreateClient {
  clientCreate(
    client: {
      firstName: "Maria"
      lastName: "Santos"
      companyName: "Santos Property Management"
      isCompany: false
      isLead: false
      emails: [
        { address: "maria@santosproperty.com", primary: true, description: MAIN }
      ]
      phones: [
        { number: "555-234-5678", primary: true, description: MAIN }
      ]
      billingAddress: {
        street1: "45 Maple Avenue"
        street2: "Suite 200"
        city: "Toronto"
        province: "ON"
        postalCode: "M5V 2T6"
        country: "Canada"
      }
      note: "Prefers early morning appointments"
    }
  ) {
    client {
      id
      name
      jobberWebUri
      createdAt
    }
    userErrors {
      message
      path
    }
  }
}
```

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

### Create Client

Source: https://context7.com/hightreequency/jobberschema/llms.txt

Creates a new client record (person or company) with contact details and address. Returns the created client or a list of user errors on failure.

```APIDOC
## Mutation: `clientCreate`

**Create a new client (person or company).**

Creates a client record with contact details, address, and optional tags. Set `isCompany: true` and provide `companyName` for business clients. The mutation returns the created `Client` or a list of `userErrors` on failure.

```graphql
mutation CreateClient {
  clientCreate(
    client: {
      firstName: "Maria"
      lastName: "Santos"
      companyName: "Santos Property Management"
      isCompany: false
      isLead: false
      emails: [
        { address: "maria@santosproperty.com", primary: true, description: MAIN }
      ]
      phones: [
        { number: "555-234-5678", primary: true, description: MAIN }
      ]
      billingAddress: {
        street1: "45 Maple Avenue"
        street2: "Suite 200"
        city: "Toronto"
        province: "ON"
        postalCode: "M5V 2T6"
        country: "Canada"
      }
      note: "Prefers early morning appointments"
    }
  ) {
    client {
      id
      name
      jobberWebUri
      createdAt
    }
    userErrors {
      message
      path
    }
  }
}
```
```

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

### Create a New Incoming Work Request

Source: https://context7.com/hightreequency/jobberschema/llms.txt

Initiate a new work request, which represents a service inquiry. This mutation can link to an existing client or automatically create a new lead client. The `source` field is used to track the origin of the request.

```graphql
mutation CreateRequest {
  requestCreate(
    request: {
      clientId: "Z2lkOi8vSm9iYmVyL0NsaWVudC80NTY="
      title: "Lawn mowing and hedge trimming"
      source: "Phone Call"
      property: {
        addressAttributes: {
          street1: "45 Maple Avenue"
          city: "Toronto"
          province: "ON"
          postalCode: "M5V 2T6"
          country: "Canada"
        }
      }
    }
  ) {
    request {
      id
      title
      requestStatus
      client { id name }
      property { id address { street1 city } }
      createdAt
      jobberWebUri
    }
    userErrors {
      message
      path
    }
  }
}
```

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

### Create Client with Error Handling (JavaScript)

Source: https://context7.com/hightreequency/jobberschema/llms.txt

This JavaScript function shows how to create a client and handle potential business logic errors returned in the `userErrors` array. It also includes basic handling for top-level GraphQL transport errors.

```javascript
async function createClient(accessToken, clientInput) {
  const endpoint = "https://api.getjobber.com/api/graphql";

  const mutation = `
    mutation CreateClient($client: ClientCreateInput!) {
      clientCreate(client: $client) {
        client {
          id
          name
          jobberWebUri
        }
        userErrors {
          message
          path
        }
      }
    }
  `;

  const response = await fetch(endpoint, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "X-JOBBER-GRAPHQL-VERSION": "2025-01-20",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: mutation,
      variables: { client: clientInput },
    }),
  });

  const { data, errors } = await response.json();

  // Top-level GraphQL transport/syntax errors
  if (errors && errors.length > 0) {
    throw new Error(`GraphQL transport error: ${errors[0].message}`);
  }

  const { client, userErrors } = data.clientCreate;

  // Business logic validation errors
  if (userErrors && userErrors.length > 0) {
    const messages = userErrors.map(e => `[${e.path.join(".")}]. ${e.message}`);
    throw new Error(`Client creation failed: ${messages.join("; ")}`);
  }

  // Success
  console.log(`Created client: ${client.name} (${client.id})`);
  console.log(`View in Jobber: ${client.jobberWebUri}`);
  return client;
}

// Usage
createClient(token, {
  firstName: "Jordan",
  lastName: "Lee",
  emails: [{ address: "jordan@example.com", primary: true, description: "MAIN" }],
}).catch(console.error);
```

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

### List or fetch work requests

Source: https://context7.com/hightreequency/jobberschema/llms.txt

The `requests` query allows you to list or fetch work requests, which are the entry points for new work in Jobber. You can filter by request status and sort by creation date.

```APIDOC
## Query: `requests` / `request`

### Description
List or fetch work requests (incoming service requests from clients).

Requests are the entry point for new work in Jobber. They track the client's contact info, request status (`new`, `assessment_completed`, `converted`, `completed`, `archived`, etc.), and link to any assessment, jobs, and quotes created from them.

### Query
```graphql
query ListNewRequests {
  requests(
    filter: { requestStatus: [new, overdue] }
    sort: [{ key: REQUESTED_AT, direction: DESCENDING }]
    first: 25
  ) {
    nodes {
      id
      title
      requestStatus
      source
      contactName
      companyName
      email
      phone
      isScheduled
      client {
        id
        name
        isLead
      }
      property {
        id
        address { street1 city province }
      }
      assessment {
        id
        startAt
        endAt
        isComplete
        assignedUsers(first: 5) {
          nodes { id name { full } }
        }
      }
      jobs(first: 3) {
        nodes { id jobNumber jobStatus }
        totalCount
      }
      createdAt
      updatedAt
      jobberWebUri
    }
    pageInfo { hasNextPage endCursor }
    totalCount
  }
}
```
```

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

### visitCreate / visitEdit / visitComplete

Source: https://context7.com/hightreequency/jobberschema/llms.txt

Create, update, and complete job visits (scheduled service appointments). Visits belong to a job and represent individual on-site visits.

```APIDOC
## Mutation: `visitCreate` / `visitEdit` / `visitComplete`

### Description
Create, update, and complete job visits (scheduled service appointments).

Visits belong to a job and represent individual on-site visits. `visitCreate` schedules new visits; `visitEdit` changes time, instructions, or assigned users; `visitComplete` marks a visit as done and triggers configured `actionsUponComplete`.

### Method
`mutation`

### Endpoint
`/graphql` (Assumed for GraphQL mutations)

### Request Body Example (visitCreate)
```graphql
# Create a visit on a job
mutation CreateVisit {
  visitCreate(
    jobId: "Z2lkOi8vSm9iYmVyL0pvYi8xMjM="
    visit: {
      visits: [
        {
          schedule: {
            startAt: { isoTimestamp: "2025-06-15T09:00:00-04:00" }
            endAt: { isoTimestamp: "2025-06-15T11:00:00-04:00" }
          }
          title: "Initial Spring Cleanup"
          instructions: "Focus on backyard. Gate code is 4521."
          assignedUserIds: ["Z2lkOi8vSm9iYmVyL1VzZXIvNDU2"]
        }
      ]
    }
  ) {
    visit {
      id
      title
      startAt
      endAt
      visitStatus
      assignedUsers(first: 5) { nodes { id name { full } } }
    }
    userErrors { message path }
  }
}
```

### Request Body Example (visitComplete)
```graphql
# Complete a visit
mutation CompleteVisit {
  visitComplete(id: "Z2lkOi8vSm9iYmVyL1Zpc2l0Lzk4Nw==") {
    visit {
      id
      isComplete
      completedAt
      actionsUponComplete
    }
    userErrors { message path }
  }
}
```

### Response Example (visitCreate)
(Response structure is implied by the query, but a concrete example is not provided in the source.)

### Response Example (visitComplete)
(Response structure is implied by the query, but a concrete example is not provided in the source.)
```

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

### Paginate Through All Clients (JavaScript)

Source: https://context7.com/hightreequency/jobberschema/llms.txt

This JavaScript function demonstrates how to paginate through a large list of clients using Relay cursor-based pagination. It fetches clients in batches of 50 until all are retrieved.

```javascript
// JavaScript example: paginate through all clients
async function getAllClients(accessToken) {
  const endpoint = "https://api.getjobber.com/api/graphql";
  const headers = {
    "Authorization": `Bearer ${accessToken}`,
    "X-JOBBER-GRAPHQL-VERSION": "2025-01-20",
    "Content-Type": "application/json",
  };

  const query = `
    query ListClients($after: String) {
      clients(first: 50, after: $after) {
        nodes {
          id
          name
          balance
          createdAt
        }
        pageInfo {
          hasNextPage
          endCursor
        }
        totalCount
      }
    }
  `;

  let allClients = [];
  let after = null;
  let hasNextPage = true;

  while (hasNextPage) {
    const response = await fetch(endpoint, {
      method: "POST",
      headers,
      body: JSON.stringify({ query, variables: { after } }),
    });

    const { data, errors } = await response.json();

    if (errors) {
      throw new Error(`GraphQL errors: ${JSON.stringify(errors)}`);
    }

    const { nodes, pageInfo, totalCount } = data.clients;
    allClients = allClients.concat(nodes);
    hasNextPage = pageInfo.hasNextPage;
    after = pageInfo.endCursor;

    console.log(`Fetched ${allClients.length} / ${totalCount} clients`);
  }

  return allClients;
}
```

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

### Query: `clients` / `client`

Source: https://context7.com/hightreequency/jobberschema/llms.txt

List or fetch individual clients with filtering, sorting, and cursor-based pagination. `clients` returns a `ClientConnection` supporting full Relay pagination. Clients can be filtered by status (lead, archived) and sorted by name or creation date. `client(id:)` fetches a single client by its opaque `EncodedId`.

```APIDOC
## Query: `clients` / `client`

**List or fetch individual clients with filtering, sorting, and cursor-based pagination.**

`clients` returns a `ClientConnection` supporting full Relay pagination. Clients can be filtered by status (lead, archived) and sorted by name or creation date. `client(id:)` fetches a single client by its opaque `EncodedId`.

```graphql
# List active (non-lead, non-archived) clients, 25 per page
query ListClients($after: String) {
  clients(
    filter: { isLead: false, isArchived: false }
    sort: [{ key: CLIENT_NAME, direction: ASCENDING }]
    first: 25
    after: $after
  ) {
    nodes {
      id
      name
      companyName
      isCompany
      isLead
      balance
      billingAddress {
        street1
        street2
        city
        province
        postalCode
        country
      }
      emails {
        address
        primary
        description
      }
      phones {
        number
        primary
        description
      }
      jobberWebUri
      createdAt
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

# Fetch a single client by ID
query GetClient {
  client(id: "Z2lkOi8vSm9iYmVyL0NsaWVudC80NTY=") {
    id
    name
    isLead
    jobs(first: 5) {
      nodes {
        id
        jobNumber
        jobStatus
        totalPrice
      }
    }
    invoices(first: 5) {
      nodes {
        id
        invoiceNumber
        invoiceStatus
        amounts {
          total
          outstanding
        }
      }
    }
    tags {
      nodes {
        id
        label
      }
    }
  }
}
```
```

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

### List clients with filtering and pagination

Source: https://context7.com/hightreequency/jobberschema/llms.txt

List active (non-lead, non-archived) clients, 25 per page, sorted by name. Supports full Relay pagination with `PageInfo`, `nodes`, and `totalCount`.

```graphql
# List active (non-lead, non-archived) clients, 25 per page
query ListClients($after: String) {
  clients(
    filter: { isLead: false, isArchived: false }
    sort: [{ key: CLIENT_NAME, direction: ASCENDING }]
    first: 25
    after: $after
  ) {
    nodes {
      id
      name
      companyName
      isCompany
      isLead
      balance
      billingAddress {
        street1
        street2
        city
        province
        postalCode
        country
      }
      emails {
        address
        primary
        description
      }
      phones {
        number
        primary
        description
      }
      jobberWebUri
      createdAt
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}
```

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

### List Products and Services

Source: https://context7.com/hightreequency/jobberschema/llms.txt

Retrieves the account's product and service catalog, supporting filtering by name and sorting. Each item includes pricing, taxability, category, and custom fields.

```APIDOC
## Query: `productsAndServices`

**List the product and service catalog.**

Returns `ProductOrService` items from the account's catalog. Supports filtering by name and sorting. Each item includes pricing, taxability, category, and custom fields.

```graphql
query ListProductsAndServices {
  productsAndServices(
    sort: [{ key: NAME, direction: ASCENDING }]
    first: 100
  ) {
    nodes {
      id
      name
      description
      unitPrice
      defaultUnitCost
      taxable
      category {
        id
        name
      }
      internalNotes
      customFields {
        ... on CustomFieldText {
          label
          valueText
        }
        ... on CustomFieldLink {
          label
          valueLink
        }
      }
    }
    pageInfo { hasNextPage endCursor }
    totalCount
  }
}
```
```

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

### Create a Quote with Line Items

Source: https://context7.com/hightreequency/jobberschema/llms.txt

Use `quoteCreate` to create a new quote and `quoteCreateLineItems` to add services or products to it. Ensure `clientId` and `quoteId` are correctly provided.

```graphql
# Create a quote
mutation CreateQuote {
  quoteCreate(
    quote: {
      clientId: "Z2lkOi8vSm9iYmVyL0NsaWVudC80NTY="
      title: "Spring Cleanup Package"
      message: "Thank you for choosing Sunrise Landscaping!"
      depositAmount: 150.00
    }
  ) {
    quote {
      id
      quoteNumber
      quoteStatus
      amounts { subtotal total depositAmount }
      createdAt
    }
    userErrors { message path }
  }
}

# Add line items to the quote
mutation AddQuoteLineItems {
  quoteCreateLineItems(
    quoteId: "Z2lkOi8vSm9iYmVyL1F1b3RlLzEyMw=="
    lineItems: {
      lineItems: [
        {
          name: "Lawn Mowing (per visit)"
          description: "Standard residential lawn mowing service"
          unitPrice: 85.00
          quantity: 4
          taxable: true
        }
        {
          name: "Hedge Trimming"
          description: "Full property hedge and shrub trim"
          unitPrice: 200.00
          quantity: 1
          taxable: true
        }
      ]
    }
  ) {
    lineItems {
      id
      name
      quantity
      unitPrice
      totalPrice
    }
    userErrors { message path }
  }
}
```

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

### Create Request

Source: https://context7.com/hightreequency/jobberschema/llms.txt

Creates a new incoming work request, optionally linking it to an existing client or creating a new lead. The `source` field indicates the origin of the request.

```APIDOC
## Mutation: `requestCreate`

**Create a new incoming work request.**

Requests represent new service inquiries. They can be linked to an existing client or create a new lead client automatically. The `source` field tracks request origin (e.g. `"Online Booking"`, `"Phone Call"`).

```graphql
mutation CreateRequest {
  requestCreate(
    request: {
      clientId: "Z2lkOi8vSm9iYmVyL0NsaWVudC80NTY="
      title: "Lawn mowing and hedge trimming"
      source: "Phone Call"
      property: {
        addressAttributes: {
          street1: "45 Maple Avenue"
          city: "Toronto"
          province: "ON"
          postalCode: "M5V 2T6"
          country: "Canada"
        }
      }
    }
  ) {
    request {
      id
      title
      requestStatus
      client { id name }
      property { id address { street1 city } }
      createdAt
      jobberWebUri
    }
    userErrors {
      message
      path
    }
  }
}
```
```

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

### List Configured Webhook Endpoints

Source: https://context7.com/hightreequency/jobberschema/llms.txt

Fetches all webhook subscriptions configured for the account. The response includes the URL and the event topic each endpoint subscribes to.

```graphql
query ListWebhooks {
  webhookEndpoints(first: 50) {
    nodes {
      id
      url
      topic
      account { id name }
      createdAt
      updatedAt
    }
    totalCount
  }
}
```

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

### Handle API Rate Limiting with Backoff

Source: https://context7.com/hightreequency/jobberschema/llms.txt

This function demonstrates how to make a GraphQL request to the Jobber API and includes logic to monitor and handle rate limiting. It checks the `extensions.cost.throttleStatus.currentlyAvailable` field and implements a backoff delay if capacity drops below 20% of the maximum.

```javascript
async function graphqlWithRateLimitHandling(accessToken, query, variables = {}) {
  const endpoint = "https://api.getjobber.com/api/graphql";

  const response = await fetch(endpoint, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "X-JOBBER-GRAPHQL-VERSION": "2025-01-20",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ query, variables }),
  });

  const result = await response.json();

  // Log throttle status
  const cost = result?.extensions?.cost;
  if (cost) {
    const { actualQueryCost, throttleStatus } = cost;
    const { maximumAvailable, currentlyAvailable, restoreRate } = throttleStatus;
    console.log(
      `Query cost: ${actualQueryCost} | Available: ${currentlyAvailable}/${maximumAvailable} | Restore rate: ${restoreRate}/s`
    );

    // If we're below 20% capacity, wait before next request
    if (currentlyAvailable < maximumAvailable * 0.2) {
      const pointsNeeded = maximumAvailable * 0.5 - currentlyAvailable;
      const waitMs = Math.ceil((pointsNeeded / restoreRate) * 1000);
      console.warn(`Throttle warning — waiting ${waitMs}ms to restore capacity`);
      await new Promise(resolve => setTimeout(resolve, waitMs));
    }
  }

  return result;
}

// Expected extensions block in every response:
// {
//   "extensions": {
//     "cost": {
//       "requestedQueryCost": 10,
//       "actualQueryCost": 42,
//       "throttleStatus": {
//         "maximumAvailable": 10000,
//         "currentlyAvailable": 9958,
//         "restoreRate": 500
//       }
//     },
//     "versioning": { "version": "2025-01-20" }
//   }
// }
```

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

### List Product and Service Catalog

Source: https://context7.com/hightreequency/jobberschema/llms.txt

Retrieve the account's product and service catalog. This query supports filtering by name and sorting. Each item includes details like pricing, taxability, and custom fields.

```graphql
query ListProductsAndServices {
  productsAndServices(
    sort: [{ key: NAME, direction: ASCENDING }]
    first: 100
  ) {
    nodes {
      id
      name
      description
      unitPrice
      defaultUnitCost
      taxable
      category {
        id
        name
      }
      internalNotes
      customFields {
        ... on CustomFieldText {
          label
          valueText
        }
        ... on CustomFieldLink {
          label
          valueLink
        }
      }
    }
    pageInfo { hasNextPage endCursor }
    totalCount
  }
}
```

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

### Make a POST request to the Jobber GraphQL endpoint

Source: https://context7.com/hightreequency/jobberschema/llms.txt

All requests are sent as HTTP POST to the Jobber GraphQL endpoint. The OAuth 2.0 Bearer token must be included in the Authorization header and the API version must be specified in X-JOBBER-GRAPHQL-VERSION.

```bash
curl -X POST https://api.getjobber.com/api/graphql \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-JOBBER-GRAPHQL-VERSION: 2025-01-20" \
  -H "Content-Type: application/json" \
  -d '{ 
    "query": "{ account { id name phone industry } }" 
  }'
```

```json
{
  "data": {
    "account": {
      "id": "Z2lkOi8vSm9iYmVyL0FjY291bnQvMTIz",
      "name": "Sunrise Landscaping LLC",
      "phone": "555-867-5309",
      "industry": "LAWN_AND_GARDEN"
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 1,
      "actualQueryCost": 1,
      "throttleStatus": {
        "maximumAvailable": 10000,
        "currentlyAvailable": 9999,
        "restoreRate": 500
      }
    },
    "versioning": { "version": "2025-01-20" }
  }
}
```

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

### Query: `account`

Source: https://context7.com/hightreequency/jobberschema/llms.txt

Retrieve the authenticated account's profile and enabled features. Returns the top-level `Account` object for the authenticated user's Jobber account, including account name, phone, industry, creation date, and the list of enabled feature flags.

```APIDOC
## Query: `account`

**Retrieve the authenticated account's profile and enabled features.**

Returns the top-level `Account` object for the authenticated user's Jobber account, including account name, phone, industry, creation date, and the list of enabled feature flags.

```graphql
query GetAccount {
  account {
    id
    name
    phone
    industry
    createdAt
    features {
      name
      enabled
      available
      discoverable
    }
  }
}
```

```bash
curl -X POST https://api.getjobber.com/api/graphql \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-JOBBER-GRAPHQL-VERSION: 2025-01-20" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ account { id name phone industry createdAt features { name enabled available } } }"}'
```
```

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

### Register a Webhook

Source: https://context7.com/hightreequency/jobberschema/llms.txt

Use this mutation to register a new webhook endpoint for specific topics. Ensure the URL is publicly accessible.

```graphql
mutation CreateWebhook {
  webhookEndpointCreate(
    input: {
      url: "https://your-app.example.com/webhooks/jobber"
      topic: VISIT_COMPLETE
    }
  ) {
    webhookEndpoint {
      id
      url
      topic
      createdAt
    }
    userErrors { message path }
  }
}
```

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

### Query: `jobs` / `job`

Source: https://context7.com/hightreequency/jobberschema/llms.txt

List or fetch jobs with filtering by status, client, or date range. Supports filtering by JobStatusEnum values and date ranges. Each job links to its client, property, visits, invoices, line items, and custom fields.

```APIDOC
## Query: `jobs` / `job`

### Description
List or fetch jobs with filtering by status, client, or date range.

### Query
```graphql
query ListActiveJobs($after: String) {
  jobs(
    filter: {
      jobStatus: [active, upcoming]
      startDate: { from: "2025-01-01T00:00:00Z", to: "2025-12-31T23:59:59Z" }
    }
    sort: [{ key: CREATED_AT, direction: DESCENDING }]
    first: 50
    after: $after
  ) {
    nodes {
      id
      jobNumber
      title
      jobStatus
      billingFrequency
      totalPrice
      startAt
      endAt
      instructions
      client {
        id
        name
      }
      property {
        id
        address {
          street1
          city
          province
          postalCode
        }
      }
      visits(first: 3) {
        nodes {
          id
          startAt
          endAt
          isComplete
          visitStatus
        }
        totalCount
      }
      lineItems(first: 10) {
        nodes {
          id
          name
          quantity
          unitPrice
          totalPrice
          taxable
        }
      }
      customFields {
        ... on CustomFieldText {
          label
          valueText
        }
        ... on CustomFieldNumeric {
          label
          valueNumeric
        }
        ... on CustomFieldTrueFalse {
          label
          valueTrueFalse
        }
      }
    }
    pageInfo { hasNextPage endCursor }
    totalCount
  }
}
```
```

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

### List Active Jobs with Filtering and Pagination

Source: https://context7.com/hightreequency/jobberschema/llms.txt

Use this query to list active and upcoming jobs within a specific date range. It supports pagination using the `after` cursor and sorts results by creation date.

```graphql
query ListActiveJobs($after: String) {
  jobs(
    filter: {
      jobStatus: [active, upcoming]
      startDate: { from: "2025-01-01T00:00:00Z", to: "2025-12-31T23:59:59Z" }
    }
    sort: [{ key: CREATED_AT, direction: DESCENDING }]
    first: 50
    after: $after
  ) {
    nodes {
      id
      jobNumber
      title
      jobStatus
      billingFrequency
      totalPrice
      startAt
      endAt
      instructions
      client {
        id
        name
      }
      property {
        id
        address {
          street1
          city
          province
          postalCode
        }
      }
      visits(first: 3) {
        nodes {
          id
          startAt
          endAt
          isComplete
          visitStatus
        }
        totalCount
      }
      lineItems(first: 10) {
        nodes {
          id
          name
          quantity
          unitPrice
          totalPrice
          taxable
        }
      }
      customFields {
        ... on CustomFieldText {
          label
          valueText
        }
        ... on CustomFieldNumeric {
          label
          valueNumeric
        }
        ... on CustomFieldTrueFalse {
          label
          valueTrueFalse
        }
      }
    }
    pageInfo { hasNextPage endCursor }
    totalCount
  }
}
```

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

### Record a Business Expense

Source: https://context7.com/hightreequency/jobberschema/llms.txt

Use `expenseCreate` to log business expenses, optionally linking them to a job and specifying who paid and who should be reimbursed. Ensure the `date` is in ISO 8601 format.

```graphql
mutation CreateExpense {
  expenseCreate(
    expense: {
      title: "Mulch and soil supplies"
      description: "4 cubic yards mulch + 20 bags topsoil from Green Thumb Supply"
      total: 312.50
      date: "2025-06-10T00:00:00Z"
      linkedJobId: "Z2lkOi8vSm9iYmVyL0pvYi8xMjM="
      paidByUserId: "Z2lkOi8vSm9iYmVyL1VzZXIvNDU2"
      reimbursableToUserId: "Z2lkOi8vSm9iYmVyL1VzZXIvNDU2"
    }
  ) {
    expense {
      id
      title
      total
      date
      linkedJob { id jobNumber }
      paidBy { id name { full } }
      createdAt
    }
    userErrors { message path }
  }
}
```

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

### quoteCreate / quoteEdit

Source: https://context7.com/hightreequency/jobberschema/llms.txt

Create or update a quote with line items and pricing. `quoteCreate` creates a new quote linked to a client, while `quoteEdit` updates a quote's top-level fields. Line items are managed separately.

```APIDOC
## Mutation: `quoteCreate` / `quoteEdit`

### Description
Create or update a quote with line items and pricing.

`quoteCreate` creates a new quote linked to a client (and optionally a request). `quoteEdit` updates a quote's top-level fields. Line items are managed separately via `quoteCreateLineItems` / `quoteEditLineItems` / `quoteDeleteLineItems`.

### Method
`mutation`

### Endpoint
`/graphql` (Assumed for GraphQL mutations)

### Request Body Example (quoteCreate)
```graphql
mutation CreateQuote {
  quoteCreate(
    quote: {
      clientId: "Z2lkOi8vSm9iYmVyL0NsaWVudC80NTY="
      title: "Spring Cleanup Package"
      message: "Thank you for choosing Sunrise Landscaping!"
      depositAmount: 150.00
    }
  ) {
    quote {
      id
      quoteNumber
      quoteStatus
      amounts { subtotal total depositAmount }
      createdAt
    }
    userErrors { message path }
  }
}
```

### Request Body Example (quoteEdit)
(Note: `quoteEdit` details are described but not provided in a code example in the source.)

### Response Example (quoteCreate)
(Response structure is implied by the query, but a concrete example is not provided in the source.)
```

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

### Fetch a single client by ID

Source: https://context7.com/hightreequency/jobberschema/llms.txt

Fetches a single client by its opaque `EncodedId`. Includes related jobs, invoices, and tags.

```graphql
# Fetch a single client by ID
query GetClient {
  client(id: "Z2lkOi8vSm9iYmVyL0NsaWVudC80NTY=") {
    id
    name
    isLead
    jobs(first: 5) {
      nodes {
        id
        jobNumber
        jobStatus
        totalPrice
      }
    }
    invoices(first: 5) {
      nodes {
        id
        invoiceNumber
        invoiceStatus
        amounts {
          total
          outstanding
        }
      }
    }
    tags {
      nodes {
        id
        label
      }
    }
  }
}
```

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

### Query account details

Source: https://context7.com/hightreequency/jobberschema/llms.txt

Retrieve the authenticated account's profile and enabled features. Returns the top-level Account object for the authenticated user's Jobber account.

```graphql
query GetAccount {
  account {
    id
    name
    phone
    industry
    createdAt
    features {
      name
      enabled
      available
      discoverable
    }
  }
}
```

```bash
curl -X POST https://api.getjobber.com/api/graphql \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-JOBBER-GRAPHQL-VERSION: 2025-01-20" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ account { id name phone industry createdAt features { name enabled available } } }"}'
```

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

### List Webhook Endpoints

Source: https://context7.com/hightreequency/jobberschema/llms.txt

Retrieves a list of all configured webhook endpoints and their subscribed event topics.

```APIDOC
## Query: `webhookEndpoints`

**List configured webhook endpoints.**

Returns all webhook subscriptions registered on the account, showing their URL and the event topic they subscribe to.

```graphql
query ListWebhooks {
  webhookEndpoints(first: 50) {
    nodes {
      id
      url
      topic
      account { id name }
      createdAt
      updatedAt
    }
    totalCount
  }
}
```
```

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

### Query: `invoices` / `invoice`

Source: https://context7.com/hightreequency/jobberschema/llms.txt

List or fetch invoices with status filtering and full amounts breakdown. Can be filtered by InvoiceStatusTypeEnum and provides a complete financial breakdown.

```APIDOC
## Query: `invoices` / `invoice`

### Description
List or fetch invoices with status filtering and full amounts breakdown.

### Query
```graphql
query ListUnpaidInvoices($after: String) {
  invoices(
    filter: {
      invoiceStatus: [awaiting_payment, past_due]
    }
    sort: [{ key: CREATED_AT, direction: DESCENDING }]
    first: 25
    after: $after
  ) {
    nodes {
      id
      invoiceNumber
      subject
      invoiceStatus
      dueDate
      issuedDate
      client {
        id
        name
        emails {
          address
          primary
        }
      }
      amounts {
        subtotal
        discountAmount
        taxAmount
        total
        outstanding
        depositAmount
        tipsAmount
        paymentsTotal
      }
      taxDetails {
        taxName
        taxRate
      }
      lineItems(first: 20) {
        nodes {
          id
          name
          quantity
          unitPrice
          totalPrice
          taxable
        }
      }
      createdAt
      updatedAt
    }
    pageInfo { hasNextPage endCursor }
    totalCount
  }
}
```
```

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

### List Expense Records with Filtering and Sorting

Source: https://context7.com/hightreequency/jobberschema/llms.txt

Use this query to retrieve expense records. It supports filtering by date range and sorting by creation date, update date, or expense date. Pagination is handled via `first` and `after` cursors.

```graphql
query ListExpenses($from: ISO8601DateTime!, $to: ISO8601DateTime!) {
  expenses(
    filter: {
      date: { from: $from, to: $to }
    }
    sort: { key: DATE, direction: DESCENDING }
    first: 50
  ) {
    nodes {
      id
      title
      description
      date
      total
      linkedJob { id jobNumber title }
      paidBy { id name { full } }
      reimbursableTo { id name { full } }
      enteredBy { id name { full } }
      createdAt
      updatedAt
    }
    pageInfo { hasNextPage endCursor }
    totalCount
  }
}
```

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

### Register a webhook

Source: https://context7.com/hightreequency/jobberschema/llms.txt

Allows users to register a new webhook endpoint to receive notifications for specific events.

```APIDOC
## Register a webhook

mutation CreateWebhook {
  webhookEndpointCreate(
    input: {
      url: "https://your-app.example.com/webhooks/jobber"
      topic: VISIT_COMPLETE
    }
  ) {
    webhookEndpoint {
      id
      url
      topic
      createdAt
    }
    userErrors { message path }
  }
}
```