Step by Step Guide to Building a ServiceTitan API Integration in PHP

Introduction

Hey there, fellow code wrangler! Ready to dive into the world of ServiceTitan API integration? You're in for a treat. ServiceTitan's API is a powerful tool that'll let you tap into their robust field service management platform. Whether you're looking to sync data, automate processes, or create custom solutions, this guide will get you up and running in no time.

Prerequisites

Before we jump in, make sure you've got:

• A PHP environment that's locked and loaded
• Your ServiceTitan API credentials (if you don't have them, go bug your account manager)
• Guzzle installed (because who wants to deal with cURL directly, right?)

Authentication

First things first, let's get you authenticated:

$client = new GuzzleHttp\Client();
$response = $client->post('https://auth.servicetitan.io/connect/token', [
    'form_params' => [
        'grant_type' => 'client_credentials',
        'client_id' => 'YOUR_CLIENT_ID',
        'client_secret' => 'YOUR_CLIENT_SECRET',
    ]
]);

$token = json_decode($response->getBody(), true)['access_token'];

Pro tip: Implement a token refresh mechanism. Your future self will thank you.

Basic API Request Structure

Now that you're authenticated, let's structure those requests:

$client->request('GET', 'https://api.servicetitan.io/v2/endpoint', [
    'headers' => [
        'Authorization' => 'Bearer ' . $token,
        'Content-Type' => 'application/json',
    ]
]);

Implementing Core API Calls

Time to get your hands dirty with some CRUD operations:

GET Request

$response = $client->get('https://api.servicetitan.io/v2/customers/1234');
$customer = json_decode($response->getBody(), true);

POST Request

$response = $client->post('https://api.servicetitan.io/v2/jobs', [
    'json' => [
        'customerId' => 1234,
        'jobType' => 'Service',
        // ... other job details
    ]
]);

You get the idea. Rinse and repeat for PUT and DELETE.

Handling Responses

Always expect the unexpected:

try {
    $response = $client->get('https://api.servicetitan.io/v2/customers/1234');
    $data = json_decode($response->getBody(), true);
} catch (GuzzleHttp\Exception\ClientException $e) {
    $errorResponse = $e->getResponse();
    $errorData = json_decode($errorResponse->getBody(), true);
    // Handle the error like a boss
}

Pagination and Data Filtering

Don't let large datasets bog you down:

$response = $client->get('https://api.servicetitan.io/v2/customers', [
    'query' => [
        'page' => 1,
        'pageSize' => 100,
        'filter' => 'createdOn ge 2023-01-01'
    ]
]);

Webhooks

If you're setting up webhooks, remember:

1. Set up your endpoint
2. Verify the incoming payload
3. Process the data

Quick and dirty example:

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_SERVICETITAN_SIGNATURE'];

if (verifySignature($payload, $signature)) {
    $data = json_decode($payload, true);
    // Do something awesome with the data
}

Rate Limiting and Best Practices

Play nice with the API:

• Respect the rate limits (check the headers for limits)
• Cache responses when possible
• Use batch operations for bulk updates

Testing and Debugging

Use the sandbox environment to test your integration. It's like a playground, but for code!

$client = new GuzzleHttp\Client(['base_uri' => 'https://api.servicetitan-test.io']);

Example Integration Use Case

Let's say you want to create a job when a new customer is added to your CRM:

function createServiceTitanJob($customerData) {
    global $client, $token;

    // First, create or find the customer
    $customerResponse = $client->post('https://api.servicetitan.io/v2/customers', [
        'headers' => ['Authorization' => 'Bearer ' . $token],
        'json' => [
            'name' => $customerData['name'],
            'phoneNumber' => $customerData['phone'],
            // ... other customer details
        ]
    ]);
    $customer = json_decode($customerResponse->getBody(), true);

    // Now, create a job for this customer
    $jobResponse = $client->post('https://api.servicetitan.io/v2/jobs', [
        'headers' => ['Authorization' => 'Bearer ' . $token],
        'json' => [
            'customerId' => $customer['id'],
            'jobType' => 'Service',
            'summary' => 'New customer onboarding',
            // ... other job details
        ]
    ]);

    return json_decode($jobResponse->getBody(), true);
}

Conclusion

And there you have it! You're now armed with the knowledge to build a robust ServiceTitan API integration. Remember, the API documentation is your best friend, so keep it bookmarked. Happy coding, and may your integrations be ever smooth and your callbacks always resolve!