Making First API call
We recommend you develop and test in the Integration environment before switching to production.
Steps to make a successful API call
First your application should call the ServiceTitan OAuth API and pass Client ID & Secret Key for authorization. If the authorization is successful, you will get back an access token.
Next your application should call the resource API endpoint and pass the access token along with the app key. If the validation is successful, then your GET/PUT/POST/DELETE operation will be successful.
HTTPS protocol
All ServiceTitan API resources are protected by Secure Sockets Layer (SSL) encryption. Any call you make to a ServiceTitan API resource must use the HTTPS scheme in the URL. SSL establishes an encrypted link between the ServiceTitan resource server and your application. This link ensures that all data passed between the resource server and your application remains private.
Using cURL to make your first ServiceTitan API Call
The cURL command line tool below is used to retrieve an OAuth 2.0 access token and make a simple call to the ServiceTitan API.
To obtain an access token
Make a call to the Auth token endpoint using a URL. You have to pass your ClientID and clientSecret. Example URL format:
https://auth-integration.servicetitan.io/connect/token
client_id
client_secret
grant_type—This should be set to “client_credentials”
Example cURL command for retrieving an access token:
Request:
curl --request POST \
--url https://auth-integration.servicetitan.io/connect/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data grant_type=client_credentials \
--data client_id=%client_id% \
--data client_secret=%client_secret% \
Running the above command returns a JSON block similar to the following example:
Response
{
"access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IkM2QTRDMjA2MjE3OEYyMEI4NzkyNjg2MTJGNkMwNEE1NzUwRjU3NzdSUzI1NiIsInR5cCI6ImF0K2p3dCIsIng1dCI6InhxVENCaUY0OGd1SGttaGhMMndFcFhVUFYzYyJ9.eyJuYmYiOjE2MjkxNDYyODksImV4cCI6MTYyOTE0NzE4OSwiaXNzIjoiaHR0cHM6Ly9wdWJsaWMtYXBpLWF1dGguc3QuZGV2IiwiY2xpZW50X2lkIjoiY2lkLjl2Ym9hNXRiYmEzMGpuaXN6ZG8wMWZ0NGwiLCJ0ZW5hbnQiOiI4NDUwIiwianRpIjoiNTRBNzM0RkJFNzBFQzU4Q0VFM0U3NUMxNjNDMUU0NjUiLCJpYXQiOjE2MjkxNDYyODksInNjb3BlIjpbInRuLmFjYy5pbnZvaWNlczpyIl19.coWQGRmbQmE9G-KADciVQeiXXoGm-g5y4_B79SUSYezCi6S7x3_W506vsCTPq7iPwEe5XGAofiWFEWf2v8CSq1cQJrIVVisHqTeygUbAYRBcj1iuNA6fCGvl72wY8uh0F_IzJ8UVp6Vdvklvupl3zelakJNVlmA0dSYtQnc9RN2whKNrqEuUDJRD5aYctAUv6z_-WpedMueOfAn8iUXcxvgbS4vXc96aZQX-v-0VLS7ZE457Y-HMhEPPGZ5UV27CHrZd6ohyJ-GldI849SJsQnwPjjeyJqjF_bb9PpDqxzKyzeS1f_bptPNahwYmGFYWnqZNw4fHjIQFdmzHl_3BOw",
"expires_in": 900,
"token_type": "Bearer",
"scope": "sup.po.purchaseorders:r sup.po.purchaseorders:w sup.vc.accounts:r sup.vc.accounts:w sup.vc.groups:r sup.vc.groups:w sup.vc.items:r sup.vc.items:w"
}
Making a call to the ServiceTitan Resource API
Now that ServiceTitan has successfully retrieved an access token, ServiceTitan can use it to make our first call to the ServiceTitan Resource API.
For this example, we’ll use the simple https://supplychain.servicetitan.io/supplychain/po/v2/vendor/{vendor}/purchase-orders endpoint to view the list of purchase orders that are available for a vendor to either accept or reject.
This will show that ServiceTitan can successfully contact the ServiceTitan API server and return information. Again, we’ll use cURL to show this.
Request:
curl --request GET \
--url https://supplychain.servicetitan.io/supplychain/po/v2/vendor/{vendor}/purchase-orders \
--header 'Authorization: Bearer <access token>' \
--header 'ST-App-Key: <app key>'
Where <access token> is the string value for the access token ServiceTitan retrieved in the previous step.
<app key> is the application key (see Create an App).
If ServiceTitan executes the above cURL command with a valid access token, it returns a JSON block similar to this example:
Response:
{
"page": 1,
"pageSize": 50,
"totalCount": 1,
"hasMore": false,
"data": [
{
"tenantId": "633728148",
"originalId": "81720938",
"vendorCustomerId": "2222",
"number": "12345678-001",
"requiredOn": "2023-09-29T07:00:00Z",
"createdOn": "2023-09-28T22:47:16.9005048",
"createdBy": "Purchaser Name",
"location": {
"inventoryLocationId": "111",
"inventoryLocation": "ServiceTitan Warehouse",
"shipToDescription": "ServiceTitan Warehouse",
"shipTo": {
"street": "801 North Brand Boulevard",
"unit": null,
"city": "Glendale",
"state": "CA",
"zip": "91203",
"country": "USA"
}
},
"customer": {
"tenantName": "Test",
"technicianId": null,
"technicianName": null,
"contactEmployeeId": "3333",
"contactEmployeeName": "Purchaser Name",
"vendorContactEmployeeId": "12345",
"contactEmployeeOfficePhone": "1111111111",
"contactEmployeeMobilePhone": null,
"contactEmployeeEmail": "[email protected]"
},
"vendor": {
"vendorId": "Vendor123",
"vendorName": "Best Vendor",
"vendorMemo": "Vendor Notes",
"vendorSubAccountId": "7256",
"vendorSubAccountName": "Commercial Account",
"vendorBranchId": null
},
"tax": {
"shippingAmount": 0.00,
"tax": 0.00,
"taxRate": 0.0000000000,
"taxSchema": 0
},
"items": [
{
"vendorPartNumber": "AAA 12345",
"description": "Battery",
"quantity": 1.0000000000000000000,
"unitCost": 3.1278000000,
"technician": null
},
]
}
],
}
}