Full Procurement Integration generic endpoints

Overview

ServiceTitan's Full Procurement Integration allows contractors to manage supply chain workflows, streamline pricebook management, access up-to-date product catalogs, and send electronic purchase orders directly to suppliers. These features rely on data touchpoints, known as endpoints, which facilitate communication between ServiceTitan and suppliers' systems. Learn how to use Supply Chain endpoints to manage security and data flow between ServiceTitan and your system.

What you need to get started

Before getting started, ensure you have the following prerequisites ready:

• Login Credentials: Get access to the ServiceTitan Integration API Portal.

• Postman Setup: Create an account on the Postman site and download the ServiceTitan Postman collection to test API requests and configurations.

• Architecture Overview: Familiarize yourself with ServiceTitan's architecture, generic endpoints and the supply chain system to understand how it works for your customers.

• Assess Compatibility: Analyze the existing APIs using Full Procurement Integration generic endpoints article to assess compatibility by comparing request/response specifications.

Things to know

• In the context of an endpoint, requests and responses are the two key components that allow systems to communicate with each other.

• The properties in the request body are available to use in your request templates, and the response body is what ServiceTitan is expecting you to map to in your response templates.

• The fields accountId, vendorId, and customIdentifierFields are found in every endpoint template.

• Analyze the existing APIs using Full Procurement Integration generic endpoints article to assess compatibility by comparing request/response specifications. For APIs that are not compatible, you have two options:        

  • Use the Middleware liquid templates to modify an existing API to accept/provide the data and bring it into compatibility with ServiceTitan.

  • Create a new API endpoint specifically for ServiceTitan using the generic endpoints templates.

• For a seamless and efficient integration experience, download and use our CLI Tool. This tool is designed to streamline the integration process by automating key steps, reducing manual effort, and ensuring accuracy.

• To explore more about ServiceTitan's supply chain integrations and the features offered by different suppliers, check out Available Supply Chain Integrations.

• Visit our Full Procurement Integration knowledge base landing page to access all the relevant customer-facing articles regarding supply chain workflows in ServiceTitan.

Endpoints overview

Each endpoint plays a specific role in the integration process, and following the recommended sequence ensures all required information is available at each stage.

Below is the order in which the endpoints should be used for the Full Procurement Integration:

1. Account

2. Branch (if applies)        

   • Default Branch

3. Pricing

4. Stock Level

5. Purchase Order

Caution: The errorCode and errorMessage fields included in the response bodies are not exposed to customers. These fields are intended for internal use only, such as for logging purposes.

Account

Endpoint Name: account

Service: Get Account

HTTP Method: POST

Account endpoint requests to authenticate accountId (the customer's accountId with the vendor system) and retrieve pricing and account information from your system. The values vendorIdentifiers will be echoed back on future requests from ServiceTitan.

Note: VendorIdentifiers are available for any other templates: Branch, Pricing, Purchase Order.

The request body contains the following key fields:

• accountId: The unique identifier for the account.

• customIdentifierFields: A flexible data structure that allows you to include additional identifiers, such as a postalCode, to uniquely specify or validate the account during the request, enhancing accuracy when querying or authenticating accounts. CustomIdentifierFields are shown as input fields for the customer to fill out during the Account Pairing workflow.

• vendorId: The unique identifier for the vendor making the request.

The response body includes the following fields:

• account*: Contains details of the customer's account.        

  • accountId*: The unique identifier of the account.

  • name: The name of the account or business.

  • postalCode: The postal code associated with the account.

  • pricingGroup: A group identifier for pricing rules associated with the account.

  • includeAccount: Indicates whether the account is included in additional operations or displays.

  • accounts: A list of subaccounts associated with the main account.                

    • subAccountId: Unique identifier for the subaccount.

    • name: Name of the subaccount.

    • postalCode: Postal code of the subaccount.

    • customFields: (Optional) Custom fields associated with the account that will be exposed to the user during the account mapping step of integration. The property name of each custom field will be used as column names in a table and the columns are populated by the values for the custom fields. All subAccounts must have the same customFields added. If this is not specified, default columns are SubAccountId and SubAccount Name.

• vendorIdentifiers: Key-value pairs containing additional identifiers returned by the vendor for future reference.        

  Note: These identifiers will be available in all subsequent request bodies in the customIdentifierFields object.

• success: Indicates whether the request was successfully processed or failed.

• errorCode: An error code returned when the request fails.

• errorMessage: Description of the failure reason.

This is the first step in setting up the integration, where you provide basic account information. It ensures that your system is configured and linked to ServiceTitan. Create or retrieve account details to establish the connection between your system and ServiceTitan.

To learn how the account setup works in ServiceTitan, see Set up your account for the Full Procurement Integration.

Branch

Endpoint Name: branches

Service: Get Branches

HTTP Method: GET/POST

Branch endpoint makes a request to your system for all branch information. Optionally filterable by a postal code.

Note: This is only applicable to integrations that support Branch-based purchasing or Vendor counter pickup.

The request includes:

• accountId: The unique identifier for the account.

• subAccountId: The subAccountId that is in context. This could be on the purchase order screen when a business unit is selected. The mapped subAccountId to the selected business unit would populate this value. This value will be null when there is no sub-account in context.

• postalCode: A field optionally used to filter the branches by postal code.

• vendorId: The unique identifier for the vendor making the request.

The response body has the following fields:

• branches*: A list of branches, each including:        

  • branchId*: Unique branch identifier.

  • branchName*: Name of the branch.

  • phoneNumber: Contact number for the branch.

  • contact: Primary contact person at the branch.

  • address: Physical address details, including street, unit, city, state, postal code, and country.

• success: Indicates whether the request was processed successfully.

• errorCode: Error code when the request fails.

• errorMessage: Description of the failure reason.

This lets ServiceTitan display a list of available branches when creating a purchase order. This helps the customers easily select the appropriate branch for their need to determine which branch they want to submit an order to electronically.

For more details, see Branch-based purchasing for more.

Default Branch

Endpoint Name: defaultbranch

Service: Get Default Branch

HTTP Method: GET/POST

Default Branch endpoint makes a request to your system for the default branch information for a given account.

Note: This is only applicable to integrations that support Branch-based purchasing or Vendor counter pickup.

The request includes:

• accountId: The unique identifier for the account.

• subAccountId: The subAccountId that is in context. This could be on the purchase order screen when a business unit is selected. The mapped subAccountId to the selected business unit would populate this value. This value will be null when there is no sub-account in context.

• postalCode: A field used to help identify the branch based on the postal code.

• vendorId: The unique identifier for the vendor making the request.

The response body includes:

• defaultBranch*: Contains default branch details, including:        

  • branchId*: Unique identifier for the branch.

  • branchName*: Name of the default branch.

  • pricingGroup: Pricing group assigned to this branch.

  • phoneNumber*: Contact number for the branch.

  • contact: Primary contact person at the branch.

  • address*: Physical address details, including street, unit, city, state, postal code, and country.

• success: Indicates whether the request was processed successfully.

• errorCode: Error code when the request fails.

• errorMessage: Description of the failure reason.

This ensures that the customers always access the correct, primary branch associated with a vendor account, making it easier to manage inventory and purchasing operations. The default branch is also used as the BranchId in our (nightly) cost-pulling job pricing request.

For more details, see Branch-based purchasing for more.

Pricing

Endpoint Name: pricing

Service: Post Pricing

HTTP Method: POST

Pricing endpoint makes a request to your system for real time pricing of specified items using the customer's vendorAccountId and the branchId (optional). This endpoint is also used for the nightly cost-pulling job. BranchId will be the selected branch on a PO in real time call, and the default branch (if applicable) in cost pulling scenario. Provide multiple cost/quantity values to indicate price breaks. If your API design has a different endpoint for real time stock levels of items, use the Stock Level template below.

Note: If you do not provide price break data, send quantity: 0.

The request includes:

• accountId: The unique ID of the account for which pricing is being requested.

• subAccountId: A subaccount ID for more specific pricing details.

• branchId: An identifier for a specific branch (if applicable).

• customIdentifierFields: Custom fields, such as postalCode, to help refine or validate the pricing request.

• items: A list of items, each with an itemId, quantity, and skuType to specify the products and their quantities for which pricing is being requested.

• vendorId: The unique ID of the vendor making the request.

The response body includes:

• vendorCosts: List of items with pricing and stock details, each including:        

  • accountId*: Account identifier associated with the pricing details.

  • subAccountId: Subaccount identifier, if applicable.

  • itemId*: Unique identifier for the item.

  • costs*: Pricing details for the item, including:                

    • cost*: Price per unit of the item.

    • quantity*: Quantity associated with the price. If no price breaks are offered, enter 0 for quantity.

  • stockLevel: Available stock level for the item.

• success: Indicates whether the request was processed successfully.

• errorCode: Error code when the request fails.

• errorMessage: Description of the failure reason.

This endpoint lets you share pricing information for your products. This allows for real-time pricing and availability details while creating purchase orders in ServiceTitan to ensure accurate cost calculations.

See Check real-time availability and pricing of PO items and Search and add catalog items to your purchase orders to learn how to verify real-time availability and pricing of items when creating POs.

Stock Level

Endpoint Name: stock-level

Service: Real Time Availability

HTTP Method: POST

Stock Level endpoint makes a request to your system for real time stock level of specified items using the customer's vendorAccountId and the branchId (optional) on the purchase order. The response is flexible to handle scenarios when the exact quantity is provided or just a status of each item's stock level is provided.

The request includes:

• accountId: The unique ID of the account for which pricing is being requested.

• subAccountId: A subaccount ID for more specific pricing details.

• branchId: An identifier for a specific branch (if applicable).

• customIdentifierFields: Custom fields, such as postalCode, to help refine or validate the pricing request.

• items: A list of items, each with an itemId and quantity to specify the products and their quantities for which stock level is being requested.

• shippingAddress: Details of the selected ship-to address on the purchase order.

• isVendorCounterPickup: Flag indicating whether the selected ship-to is vendor counter pickup/will call.

• vendorId: The unique ID of the vendor making the request.

The response body includes:

• accountId*: Account identifier associated with the stock levels.

• branchId*: Branch identifier associated with the stock levels.

• stockLevels: List of items with stock level details, each including:        

  • itemId*: Unique identifier for the item.

  • availability*: Stock level details for the item, including:                

    • itemCount: Optional available quantity of the item. This must be populated if using Neutral StatusDisposition.

    • disposition*: string value of a StatusDisposition enum. Possible values are:                        

      • Positive: Requested quantity < Available quantity. The item is available to be ordered at the requested quantity.

      • Negative: Requested quantity > available quantity. The item is not available to be ordered at the requested quantity. The user is shown the status message.

      • Neutral: The in stock decision is made by using the item count in the response instead of the Positive/Negative status disposition. The user is shown the available quantity and can update their purchase order to match the available quantity if the item is partially in stock.

    • status: Status message shown for items that have a negative StatusDisposition or have available quantity < requested quantity.

  • Note: Only a single availability object is supported for the availability array.

• success: Indicates whether the request was processed successfully.

• errorCode: Error code when the request fails.

• errorMessage: Description of the failure reason.

Purchase Order

Endpoint Name: purchaseorder

Service: Post Purchase Order

HTTP Method: POST

PO endpoint pushes a new purchase order electronically to your system and receives confirmation that the purchase order has been created or denied.

The request includes detailed information about the purchase order:

• purchaseOrder: Contains the order details, including:        

  • accountId: The unique identifier for the account placing the purchase order.

  • number: The unique number assigned to the purchase order.

  • requiredOn: The date and time by which the items in the purchase order are required.

  • date: The date the purchase order was placed.

  • createdBy: The name or the ID of the person who created the purchase order.

  • shippingAmount: The shipping cost associated with the purchase order.

  • total: The overall total cost of the purchase order.

  • inventoryLocation: Specifies the inventory location (warehouse/branch)

  • isVendorCounterPickup: Indicated whether a user selected 'Vendor Counter Pickup' as the PO shipTo. The shipToAddressDto will be null if this is true.

  • shipToDescription: The description of the shipping destination.

  • shipToAddressDto: The shipping address, including the street, unit, city, state, postal code and country.

• customer: Includes customer details like:        

  • name: The name of the customer placing the purchase order.

  • identifiers: Additional identifiers for the customer:                

    • pricingGroup: The pricing group specific to the customer.

    • technicianName: The name of the technician associated with the order, if applicable.

    • contactEmployeeName: The name of the contact person at the customer's organization.

    • contactEmployeeId: A unique identifier for the contact employee.

    • contactEmployeeOfficePhone: The office phone number of the contact employee.

    • contactEmployeeMobilePhone: The mobile phone number of the contact employee.

    • contactEmployeeEmail: The email address of the contact employee.

• vendor: Contains vendor details such as name, subAccountId, and branchId.        

  • name: The name of the vendor fulfilling the purchase order.

  • memo: Additional notes or instructions for the vendor.

  • subAccountId: A unique identifier for the vendor's subaccount, if applicable.

  • subAccountName: The name of the vendor's subaccount.

  • branchId: The identifier for the branch of the vendor processing the order.

• items: Lists the items being ordered, including:        

  • vendorPartNumber: The part number of the item as specified by the vendor.

  • description: A description of the item being ordered.

  • quantity: The number of units of the item being ordered.

  • unitCost: The cost per unit of the item.

  • technicianName: The name of the technician responsible for the item, if applicable.

• tax: Specifies the tax amount for the order.

• vendorId: The unique identifier of the vendor receiving the purchase order.

The response body provides the following information:

• status*: "Accepted" or "Rejected" to either accept or reject the PO

• orderReferenceNumber: The unique identifier assigned to the purchase order by your system.

• reason: The rejection reason that is exposed to the customer in the ST UI

• success: Indicates whether the purchase order was successfully created or if there was an error.

• errorCode: A code describing the type of error encountered, if the request fails.

• errorMessage: Description of the failure reason.

After setting up their accounts for supplier integration, customers can send purchase orders electronically to the supplier system. Electronic purchase orders allow for sending order details, including items, quantities, and customer information, to complete the purchase process. The system also displays the Send Status of the PO in the Purchase Order section of your Inventory/Purchasing tab.

For more information about the electronic purchase orders, see Send a purchase order electronically.

Want to learn more?

• See Full Procurement Integration authentication process

• See Full Procurement Integration CLI tool usage