Introducing ServicePytan: A Python Library for the ServiceTitan API v2
Making it easier to connect to and interact with ServiceTitan https://servicepytan.readthedocs.io
Motivation
Working with any REST API can be cumbersome when you need to gather data or complete operations across multiple different endpoints. Furthermore, it can be difficult to decipher everything that is required to successfully set up, authenticate, and make a request. Python is my language of choice for any data work, so it was natural to want to reach for a Python library that would make it straightforward to get data out of ServiceTitan without custom code for each application. I was motivated by libraries like pygsheets and kaggle_api, among others, that significantly lowers the barriers to accessing REST APIs.
With the sunsetting of the ServiceTitan v1 API and transition to v2 in June 2022, it was time to either rewrite all of my boilerplate code or make the library I’ve always wanted.
Getting Started
Always recommend creating a virtual environment.
# MacOS / Linux
python -m venv .venv
source ./.venv/bin/activate
# Windows
python -m venv .venv
./.venv/Scripts/activateInstalling the ServicePytan
pip install servicepytan
# For the most up to date version
pip install git+https://github.com/elliotpalmer/servicepytanIf you have not set up your account and configured your application with ServiceTitan follow these instructions: https://servicepytan.readthedocs.io/en/latest/prerequisites.html
Create Your Credential File (Note: These are fake credentials but look similar)
Making your first request
Main API
Creating the Endpoint
servicepytan.Endpoint("jpm", "jobs")This is the primary way to interact with each of the endpoints provided by the ServiceTitan API. Each endpoint is organized into a grouping outlined in the API documentation.
# Endpoint URL the library helps to build
# https://api.servicetitan.io/jpm/v2/tenant/{tenant}/appointmentsappointments = servicepytan.Endpoint("jpm", "appointments")
For each different endpoint, you simply identify the folder and endpoint defined in the documentation and then use one of five provided methods for each action.
# Retrieve an individual item based on an id number
servicepytan.Endpoint("jpm", "appointments").get_one(1234567)options = {
"pageSize":"50", # Number of jobs to return per API Request
"active":"true", # Only jobs that are active
"startsOnOrAfter":"2022-04-06T00:04:00Z", # Date in UTC Timezone
"startsBefore":"2022-04-07T00:04:00Z" # Date in UTC Timezone
}# Retrieve one "page" of records (defaults to 50
servicepytan.Endpoint("jpm", "appointments").get_many(options)# Retrieve all records possible for the request through consecutive
# requests. Defaults to 100 page size until all records are returned.
servicepytan.Endpoint("jpm", "appointments").get_all(options)# CRUD Operations
servicepytan.Endpoint("jpm", "appointments").update(1234567)
servicepytan.Endpoint("jpm", "appointments").create({<job data>})
servicepytan.Endpoint("jpm", "appointments").delete(1234567)
Each of the endpoints accepts different parameters based on the type of action and data you are expecting. Data retrieval actions will require an item id (e.g. job number, appointment number, etc) or options (e.g. appointment date range, job status, technician id, etc). Create, update, and delete actions will require additional data to define the object being changed. Reference the specifics in the developer documents.
Next Steps
This is the first release of the library and I fully expect there to be major and breaking changes in the near future; however, I hope members of the community will find this useful and consider opening issues or making pull requests to make the library as useful as possible.
