Jobber API Essential Guide

What type of API does Jobber provide?

Type of API

Jobber's API is GraphQL-based.

Key Features of Jobber's GraphQL API

• Allows developers to access and modify data on users' accounts via GraphQL
• Uses a single endpoint for all requests
• Requests are sent via POST to https://api.getjobber.com/api/graphql
• Requires an Authorization header with a bearer token for authentication
• Supports both queries (for retrieving data) and mutations (for modifying data)

Benefits of GraphQL for Jobber's API

• Strongly typed schema, improving discoverability and making it easier to validate data
• Allows clients to specify exactly what data they need, reducing over-fetching
• Single evolving version instead of multiple API versions
• Flexible permissions, allowing selective exposure of certain functions
• Efficient for complex data models with many interrelated entities

Example of Using Jobber's GraphQL API

Here's a sample mutation to create a client using Jobber's API:

mutation SampleMutation {
  clientCreate(
    input: {
      firstName: "Jane", 
      lastName: "Doe", 
      companyName: "Jane's Automotive",
      emails: [{description: MAIN, primary: true, address: "[email protected]"}]
    }
  ) {
    client {
      id
      firstName
      lastName
    }
    userErrors {
      message
      path
    }
  }
}

This example demonstrates how to create a new client record using Jobber's GraphQL API, specifying the fields to return in the response.

Does the Jobber API have webhooks?

Yes, the official Jobber API does have webhooks. Here are the key points about Jobber's webhook functionality:

Webhook Support

• Jobber's API supports webhooks, allowing real-time data to be sent to your application when certain events occur within Jobber.

Event Types

You can subscribe to the following types of webhook events:

• CLIENT_CREATE - Triggered when a new client is created
• APP_CONNECT - Triggered when an app is connected
• QUOTE_CREATE - Triggered when a new quote is created
• REQUEST_CREATE - Triggered when a new request is created
• INVOICE_CREATE - Triggered when a new invoice is created or modified
• QUOTE_APPROVAL - Triggered when a quote is approved
• JOB_COMPLETE - Triggered when a job is marked as completed

Webhook Configuration

• Webhooks are configured at the application level.
• When an event occurs, Jobber sends a POST request to the URL you provide with the event details in the body.

Webhook Payload

The webhook payload includes:

• Topic (e.g., CLIENT_CREATE)
• App ID
• Account ID
• Item ID
• Occurred At timestamp

Security and Verification

• Jobber includes a calculated signature with each webhook request.
• You should verify the authenticity of the webhook using the provided HMAC-SHA256 signature before processing it.

Best Practices

• Process webhook payloads asynchronously to ensure quick response times.
• Handle potential duplicate webhooks in an idempotent manner.
• Verify the authenticity of each webhook request before processing.

By using Jobber's webhooks, you can create real-time integrations that respond to events in Jobber, allowing for more efficient and responsive automation of workflows related to client management, job tracking, invoicing, and more.

Rate Limits and other limitations

The Jobber API has two main rate limits:

DDoS Protection Middleware

• Limits clients to 2500 requests per 5 minutes (2500 requests/300 seconds) [1]
• Implemented on a per app/account basis, not based on IP address [1]
• If exceeded, subsequent requests to that Jobber account will receive a "429 Too Many Requests" error [1]

GraphQL Query Cost Calculation

• Uses a query cost based approach for rate limiting [1]
• Each app/account combination has a maximum number of points available for making queries [1]
• Points are deducted for each query and restored over time using the leaky bucket algorithm [1]

Key Points to Consider

• The DDoS protection rate limit is typically less restrictive than the GraphQL Query Cost limit [1]
• To avoid rate limits, it's recommended to:
  1. Use pagination to collect data in batches [1]
  2. Utilize cursor-based pagination for Relay-based queries [1]
  3. Avoid deeply nested queries whenever possible [1]
  4. Apply pagination to connection types when using nested queries [1]
• If staying within limits is challenging, consider:
  1. Introducing delays between queries [1]
  2. Caching common results [1]
  3. Implementing error handling to regulate queries when being throttled [1]

Best Practices

1. Use pagination to collect data in smaller batches rather than all at once [1]
2. Implement cursor-based pagination for efficient data retrieval [1]
3. Avoid deeply nested queries to reduce query cost [1]
4. Apply pagination to all connection types in queries [1]
5. Introduce timed delays between API calls if large amounts of data are required [1]
6. Implement proper error handling to manage rate limiting scenarios [1]

By following these guidelines and best practices, developers can effectively work within the Jobber API's rate limits and ensure smooth integration with the platform.

Latest API Version

Based on the search results provided, here is the answer to your question:

The most recent version of the Jobber API is 2023-11-15.

Key points to consider:

1. Jobber uses API versioning to allow continuous evolution of their platform while offering developers a predictable path for feature upgrades and deprecations [1].

2. The API version is specified using the X-JOBBER-GRAPHQL-VERSION HTTP header [1].

3. Jobber recommends using the most recent active API version to benefit from bug fixes and schema improvements [1].

4. The API response includes version information under the extensions key [1].

Best practices:

1. Always specify the API version in your requests using the X-JOBBER-GRAPHQL-VERSION header [1].

2. Regularly check for new versions and upgrade your implementation to benefit from the latest features and improvements [1].

3. When upgrading to a newer version, consult the changelog to look for any breaking changes that could impact your application [1].

4. Use automatic code generation and type checking (such as with codegen) to help identify potential issues when upgrading [1].

5. Test your application thoroughly after upgrading to a new API version before updating your production environment [1].

It's important to note that Jobber releases new API versions at irregular intervals whenever a breaking or dangerous change is made. Old versions are supported for a minimum of 12 months and are accessible for up to 18 months from their release date [1]. Therefore, it's crucial to stay updated with the latest version information and plan your upgrades accordingly.

How to get a Jobber developer account and API Keys?

1. Create a Developer Center Account

First, you need to create a Developer Center account, which is separate from a regular Jobber account. You can do this by visiting the Jobber Developer Center website.

2. Create a Jobber Account for Testing

To test the API and build your app, you'll need a Jobber account. There are two options:

1. Use the developer testing signup link to get a special type of Jobber account for app and integration testing.
2. If you already have a regular 14-day trial Jobber account, you can contact Jobber's API support email to have it converted to a developer testing account.

Developer testing accounts typically have a 90-day trial period, which can be extended by contacting Jobber's API support.

3. Create Your First App

Once you have both accounts set up:

1. Sign in to your Developer Center account.
2. Navigate to the 'apps' page.
3. Click on the 'NEW' button to create your first app.

When creating your app, you'll need to provide the following information:

• App name (required)
• Developer name (required)
• OAuth Callback URL (optional)
• Manage App URL (optional)
• App description (required)
• Features & benefits (optional)
• Scopes (required)
• App logo (optional)
• Gallery images (optional)
• Webhooks (optional)

4. Set Up Authentication

Jobber uses OAuth 2.0 for app authorization. After creating your app, you'll receive a client identifier and secret. These are used to authenticate your app with the Jobber API.

5. Test Your API Integration

Before fully building out your app, you can test API requests using the GraphQL Playground tool:

1. In the Developer Center, click on the three dots next to your app.
2. Click "Test in Playground".

This will take you through the OAuth 2.0 flow and redirect you to the GraphQL Playground where you can view available queries and mutations.

What can you do with the Jobber API?

Based on the provided information, here's a list of data models you can interact with using the Jobber API, along with what is possible for each:

Clients

• Create, read, update, and delete client information
• Access and modify client properties, including:
  • Contact details (name, email, phone)
  • Billing address
  • Company information
  • Custom fields
  • Balance
  • Associated jobs, quotes, and invoices
  • Notes and attachments
  • Tags

Account

• Read account information, including:
  • Company name
  • Phone number
  • Industry
  • Features
  • Creation date

Assessments

• Create, read, update, and delete assessments
• Manage assessment details, such as:
  • Scheduling (start time, end time, duration)
  • Assigned users
  • Client and property information
  • Instructions
  • Completion status

Properties

• Create, read, update, and delete property information
• Link properties to clients

Quotes

• Create, read, update, and delete quotes
• Sync quote data between Jobber and other systems

Jobs

• Create, read, update, and delete job information
• Manage job details, including scheduling and assignments

Invoices

• Create, read, update, and delete invoice information

Requests

• Create, read, update, and delete work requests
• Sync work request data between Jobber and other systems

Custom Fields

• Create and manage custom fields for various objects (Clients, Properties, Quotes, Jobs, Invoices)
• Configure field types, default values, and data transfer settings

Users/Team Members

• Manage user information and assignments

Notes

• Create, read, update, and delete notes associated with clients

Tags

• Create, read, update, and delete tags associated with clients

Webhooks

• Configure webhooks to receive real-time updates on specific events (e.g., client creation)

Key points to consider:

• The API uses GraphQL for queries and mutations
• Rate limits are in place to ensure stability
• API versioning is used to manage changes and updates
• Error handling is crucial for maintaining robust interactions
• Custom integrations can be built to sync data between Jobber and other systems

When working with the Jobber API, it's important to follow best practices, such as using pagination for large data sets, handling errors appropriately, and staying within rate limits to ensure smooth operation of your application.