Reading and Writing Data Using the ServiceTitan API

Hey there, fellow JavaScript devs! Ready to dive into the world of ServiceTitan API integration? Let's get our hands dirty with some code and learn how to sync data like pros.

Introduction

ServiceTitan's API is your gateway to a treasure trove of field service management data. Whether you're building a custom dashboard or integrating with other tools, mastering this API is crucial for creating seamless, user-facing integrations. Let's explore how to keep your data in perfect harmony across systems.

Authentication: Your API Passport

First things first – we need to get past the bouncer. ServiceTitan uses OAuth 2.0, so let's set that up:

const axios = require('axios');

async function getAccessToken(clientId, clientSecret) {
  const response = await axios.post('https://auth.servicetitan.io/connect/token', {
    grant_type: 'client_credentials',
    client_id: clientId,
    client_secret: clientSecret,
    scope: 'api'
  });
  return response.data.access_token;
}

Pro tip: Store this token securely and refresh it before it expires. Your future self will thank you!

Reading Data: Fetch Like a Boss

Now that we're in, let's grab some data. ServiceTitan's endpoints are intuitive, but watch out for pagination and rate limits:

async function getCustomers(accessToken, page = 1, pageSize = 100) {
  const response = await axios.get('https://api.servicetitan.io/v2/customers', {
    headers: { Authorization: `Bearer ${accessToken}` },
    params: { page, pageSize }
  });
  return response.data;
}

Writing Data: Create and Conquer

Time to make our mark. Let's create a new job:

async function createJob(accessToken, jobData) {
  try {
    const response = await axios.post('https://api.servicetitan.io/v2/jobs', jobData, {
      headers: { Authorization: `Bearer ${accessToken}` }
    });
    return response.data;
  } catch (error) {
    console.error('Job creation failed:', error.response.data);
    throw error;
  }
}

Remember, always validate your data before sending it. ServiceTitan's API will let you know if something's amiss, but it's better to catch issues early.

Real-time Sync: Stay in the Loop

Webhooks are your best friend for real-time updates. Set them up in your ServiceTitan account, then create an endpoint to handle them:

app.post('/webhook', (req, res) => {
  const event = req.body;
  // Process the event
  console.log('Received webhook:', event);
  // Update your local database accordingly
  res.sendStatus(200);
});

Optimizing Data Sync: Work Smarter, Not Harder

Why sync everything when you can just grab what's changed? Implement delta sync to keep things speedy:

async function syncChangedRecords(lastSyncTime) {
  const changedRecords = await getCustomers(accessToken, 1, 100, {
    modifiedSince: lastSyncTime
  });
  // Update your local database with changedRecords
}

Error Handling: When Life Gives You Lemons

APIs can be fickle. Let's implement some retry logic with exponential backoff:

async function retryApiCall(apiFunction, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await apiFunction();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, 2 ** i * 1000));
    }
  }
}

Testing and Debugging: Trust, but Verify

Always use ServiceTitan's sandbox environment for testing. Set up a basic test suite to catch issues before they hit production:

describe('ServiceTitan API', () => {
  it('should fetch customers successfully', async () => {
    const customers = await getCustomers(testAccessToken);
    expect(customers.length).toBeGreaterThan(0);
  });
});

Best Practices: The Cherry on Top

1. Keep your local data in sync with regular polling or webhook updates.
2. Respect rate limits – nobody likes a data hog.
3. Encrypt sensitive data at rest and in transit. Security first!

Wrapping Up

There you have it – a whirlwind tour of the ServiceTitan API. With these tools in your belt, you're ready to build some seriously cool integrations. Remember, the API docs are your new best friend, so keep them close.

Happy coding, and may your data always be in sync! 🚀