servicepytan.requests module

class servicepytan.requests.Endpoint(folder, endpoint, conn=None)

Bases: object

Primary class for interacting with the API by establishing an endpoint object.

The core way of getting and changing data in ServiceTitan using the library is to create an endpoint object. Each method pulls the data in a different way and may or may not apply to a certain endpoint. You will need to consult the developer docs to identify the exact parameters needed for a given endpoint and which methods will apply.

folder

A string indicating the group of endpoints you want to address.

endpoint

A string indicating the endpoint you want to address.

conn

a dictionary containing the credential config.

__init__(folder, endpoint, conn=None)

Inits Endpoint with folder, endpoint and allows for getting necessary credentials from the config file.

get_one(id, modifier='', query={})

Retrieve one record using the record id.

Fetches a single record from the API endpoint using its unique identifier. Optionally supports modifiers to access sub-resources and query parameters for additional filtering.

Parameters:

• id – The unique identifier of the record to retrieve

• modifier – Optional sub-resource path (e.g., “notes” to get job notes)

• query – Optional dictionary of query parameters for filtering

Returns:

JSON response containing the requested record data

Return type:

dict

Raises:

requests.HTTPError – If the API request fails

Examples

>>> endpoint = Endpoint("jpm", "jobs", conn)
>>> job = endpoint.get_one(id="12345678")
>>> job_notes = endpoint.get_one(id="12345678", modifier="notes")

get_many(query={}, id='', modifier='')

Retrieve one page of results with query options to customize.

Fetches a single page of results from the API endpoint. Even though this is a “get_many” request, it can still use an id and modifier for accessing sub-resources (e.g., getting Notes for a specific Job).

Parameters:

• query – Dictionary of query parameters for filtering and pagination

• id – Optional record ID for accessing sub-resources

• modifier – Optional sub-resource path

Returns:

JSON response containing paginated results with ‘data’ and ‘hasMore’ fields

Return type:

dict

Raises:

requests.HTTPError – If the API request fails

Examples

>>> endpoint = Endpoint("jpm", "jobs", conn)
>>> page_data = endpoint.get_many(query={"pageSize": 50, "page": 1})
>>> job_notes = endpoint.get_many(id="12345678", modifier="notes")

get_all(query={}, id='', modifier='')

Retrieve all pages of results for your query.

Automatically handles pagination by making multiple API calls to fetch all available records that match the query criteria. This method continues fetching pages until no more data is available.

Parameters:

• query – Dictionary of query parameters for filtering (page parameter will be managed automatically)

• id – Optional record ID for accessing sub-resources

• modifier – Optional sub-resource path

Returns:

Combined list of all records from all pages

Return type:

list

Raises:

requests.HTTPError – If any API request fails

Examples

>>> endpoint = Endpoint("jpm", "jobs", conn)
>>> all_jobs = endpoint.get_all(query={"jobStatus": "Completed"})
>>> all_job_notes = endpoint.get_all(id="12345678", modifier="notes")

create(payload)

Create a new record via POST request.

Sends a POST request to create a new resource in the API endpoint. The payload should contain all required fields for the resource type.

Parameters:

payload – Dictionary containing the data for the new record

Returns:

JSON response from the API, typically containing the created record

Return type:

dict

Raises:

requests.HTTPError – If the API request fails

Examples

>>> endpoint = Endpoint("jpm", "jobs", conn)
>>> new_job = {
...     "summary": "New Job",
...     "customerId": 12345,
...     "businessUnitId": 67890
... }
>>> created_job = endpoint.create(new_job)

update(id, payload, modifier='', request_type='PUT')

Update an existing record via PUT or PATCH request.

Sends a PUT or PATCH request to update an existing resource. PUT is used for complete updates while PATCH can be used for partial updates.

Parameters:

• id – The unique identifier of the record to update

• payload – Dictionary containing the updated data

• modifier – Optional sub-resource path for updating specific parts

• request_type – HTTP method type (“PUT” or “PATCH”), defaults to “PUT”

Returns:

JSON response from the API

Return type:

dict

Raises:

requests.HTTPError – If the API request fails

Examples

>>> endpoint = Endpoint("jpm", "jobs", conn)
>>> updates = {"summary": "Updated Job Summary"}
>>> updated_job = endpoint.update("12345678", updates)
>>> updated_job = endpoint.update("12345678", updates, request_type="PATCH")

delete(id, modifier='')

Delete a record via DELETE request.

Sends a DELETE request to remove a resource from the API endpoint.

Parameters:

• id – The unique identifier of the record to delete

• modifier – Optional sub-resource path for deleting specific parts

Returns:

JSON response from the API

Return type:

dict

Raises:

requests.HTTPError – If the API request fails

Examples

>>> endpoint = Endpoint("jpm", "jobs", conn)
>>> result = endpoint.delete("12345678")

delete_subitem(id, modifier_id, modifier)

Delete a sub-item of a record via DELETE request.

Sends a DELETE request to remove a specific sub-resource that belongs to a parent resource. This is useful for deleting nested items like notes, attachments, or other related records.

Parameters:

• id – The unique identifier of the parent record

• modifier_id – The unique identifier of the sub-item to delete

• modifier – The sub-resource type (e.g., “notes”, “attachments”)

Returns:

JSON response from the API

Return type:

dict

Raises:

requests.HTTPError – If the API request fails

Examples

>>> endpoint = Endpoint("jpm", "jobs", conn)
>>> result = endpoint.delete_subitem("12345678", "note_id", "notes")

export_one(export_endpoint, export_from='', include_recent_changes=False)

Export one page of data from an export endpoint.

Retrieves one page of export data from ServiceTitan’s export endpoints, which are optimized for bulk data extraction and typically return larger datasets than regular API endpoints.

Parameters:

• export_endpoint – The specific export endpoint to call

• export_from – Continuation token from previous export call for pagination

• include_recent_changes – Whether to include recent changes in the export

Returns:

JSON response containing export data and pagination information

Return type:

dict

Raises:

requests.HTTPError – If the API request fails

Examples

>>> endpoint = Endpoint("jpm", "export", conn)
>>> export_data = endpoint.export_one("jobs")
>>> next_page = endpoint.export_one("jobs", export_from=export_data["continueFrom"])

export_all(export_endpoint, export_from='', include_recent_changes=False)

Export all data from an export endpoint.

Retrieves all available data from ServiceTitan’s export endpoints by automatically handling pagination. This method continues making requests until all data has been retrieved.

Parameters:

• export_endpoint – The specific export endpoint to call

• export_from – Starting continuation token (empty string to start from beginning)

• include_recent_changes – Whether to include recent changes in the export

Returns:

Combined list of all exported records

Return type:

list

Raises:

requests.HTTPError – If any API request fails

Examples

>>> endpoint = Endpoint("jpm", "export", conn)
>>> all_jobs = endpoint.export_all("jobs")
>>> recent_jobs = endpoint.export_all("jobs", include_recent_changes=True)

download(id, modifier='', filename=None)

Download a file from the specified endpoint.

Sends a GET request to download a file associated with the record. The modifier can specify the type of file to download (e.g., “attachments”).

Parameters:

• id – The unique identifier of the record

• modifier – Optional sub-resource path for downloading specific files

• filename – Optional filename to save the downloaded file as

Returns:

The content of the downloaded file

Return type:

bytes

Raises:

requests.HTTPError – If the API request fails

Examples

>>> endpoint = Endpoint("forms", "jobs/attachment", conn)
>>> file_content = endpoint.download("12345678")