ServiceTrade API
Table of Contents
- Getting Started
- Conventions and Units
- Embedded Object Reference
- Resource Reference
- Account Settings
- Activity
- Appointment
- Asset
- Asset Definition
- Attachment
- Authentication
- Brand
- Budget
- Budget Category
- Budget Line Item
- Change Order
- Change Order Category
- Change Order Line Item
- Clockin/Clockout
- Comment
- Company
- Contact
- Contract
- Contract Rule
- Deficiency
- EULA
- Entity Filter
- ExternalId
- ExternalSync
- ExternalSystem
- Heartbeat
- History
- Import
- Invoice
- Invoice Item
- InvoiceRecurrence
- InvoiceRecurrence Item
- Job
- Job Context
- JobItem
- LegacyLookup
- LibItem
- Location
- MasterAgreement
- Message
- Payment
- Payment terms
- Quote
- Quote Item
- QuoteRequest
- QuoteTemplate
- QuoteTemplate Item
- Region
- Role
- Service Item
- Service Line
- ServiceRecurrence
- ServiceRequest
- ServiceTemplate
- Tag
- Tax Rate
- TaxGroup
- Terms
- Token
- User
- User Value
- Warehouse
- Webhook
Getting Started
The ServiceTrade API (henceforth "API") is a RESTful web service that allows interaction with ServiceTrade's system.
Requests
An API request consists of an HTTP verb ("GET", "POST", "PUT", "DELETE"), an endpoint host ("https://api.servicetrade.com/api"), a resource URL ("/foo/123"), optional query parameters and optional request data. If a request requires request data, the data must be a provided in a valid JSON string and appear in the body of the request.
All API requests return a JSON response with optional "messages" and "data" properties. The "messages" property may contain a "success" property and/or an "error" property. The value of these properties is an array of strings.
Here is a sample HTTP request
The sample includes headers to demonstrate a few important points for making sending requests to the API:
POST /api/foo/123 HTTP/1.1
Host: api.servicetrade.com
Content-Type: application/json
Cookie: PHPSESSID=some_access_token_from_the_auth_endpoint
{"name":"Object Name","radius":321,"createdAt":12345235}
Note that the body of the request is sent as a JSON object. Also, this is an authenticated request, so it sends a "Cookie" header called "PHPSESSID" with an authentication token value from the Authentication endpoint.
Response Codes Common to All Requests
Code |
Reason |
200 |
request successful, response body contains results |
204 |
request successful, empty response body |
400 |
missing, incomplete or invalid parameters |
401 |
unauthorized request |
403 |
not allowed to perform action |
404 |
requested URI not found |
405 |
method not implemented |
500 |
unknown application error |
Returned Elements Common to All Requests
The "data" property contains any response data as a JSON object.
Name |
Type |
Value |
messages |
object |
top-level container for system messages |
messages.success |
array (string) |
individual success messages |
messages.error |
array (string) |
individual error messages |
messages.validation |
object |
keyed by parameter, list of parameters that failed to validate |
data |
object |
container for data returned by a request |
data.totalPages |
integer |
number of pages for list resources |
data.page |
integer |
current page of a list resource |
In the resource descriptions below, returned elements are assumed to be inside the "data" container.
Here is a sample response:
{
"messages": {
"success": [
"Success message one",
"Another success message"
],
"error": [
"This is the only error"
],
"validation": {
"fieldA": ["Must be numeric"],
"fieldB": ["Must be timestamp", "Must be later than current time"],
}
},
"data": {
"foo": "bar",
"baz": "qux",
"someObject": {
"name": "Bob",
"occupation": "API Example"
},
"anArray": [
"first value",
"second value"
]
}
}
Conventions and Units
The following unit and type conventions apply to data and parameters sent in requests and data returned in responses.
Pagination
The response "data" element for a list resource will contain a "totalPages" count and a "page" number. Page numbers start at 1. If totalPages is greater than 1,
a client can send a "page=n" parameter with a GET request where n is the desired page. Note that different resources may have different numbers of results per page.
Dates and Times
Dates and date-times are represented as Unix timestamps (seconds since January 1, 1970 at midnight UTC.) These will be represented as type "integer" in responses.
Distance
The unit of distance is miles. These will be represented as type "double" in responses.
Distances of less than a mile are represented as a decimal, e. g. 31.7 feet = .006 miles
Latitude and Longitude
All latitude and longitude values are represented in decimal degrees. These will be represented as type "double" in responses.
Constants
Some endpoints may require passing a constant as either a query parameter or field in the request body. Where indicated, those constants are mapped here.
Entity Types
Value |
Meaning |
1 |
Asset Type |
2 |
Asset |
3 |
Job |
4 |
User |
5 |
Company |
6 |
Invoice |
7 |
Invoice Item |
8 |
Quote Request |
9 |
Quote |
10 |
Deficiency |
11 |
Location |
12 |
Attachment |
13 |
Account |
14 |
Import |
15 |
Clock Event |
16 |
Appointment |
17 |
Service Line |
18 |
Service Request |
19 |
Job Context |
20 |
Service Recurrence |
21 |
Comment |
22 |
Contact |
23 |
Job Item |
24 |
Lib Item |
25 |
Tag |
26 |
Webhook |
27 |
Region |
28 |
ServiceItem |
29 |
Message |
30 |
Contract |
31 |
PriceModel |
32 |
QuoteItem |
33 |
External ID |
34 |
Terms |
35 |
Role |
36 |
ExternalSync |
37 |
Warehouse |
38 |
Brand |
39 |
Invoice Recurrence |
40 |
Invoice Recurrence Item |
41 |
Mailing Address |
42 |
Payment Terms |
43 |
Payment |
44 |
Tax Group |
45 |
Tax Group Postal Code |
46 |
Budget |
47 |
Budget Category |
48 |
Budget Line Item |
49 |
Change Order |
50 |
Change Order Category |
51 |
Change Order Line Item |
52 |
Project |
53 |
Entity Filter |
Attachment Purpose
Value |
Meaning |
1 |
Job Paperwork |
2 |
Job Vendor Bill |
3 |
Job Quality Control Picture |
5 |
Deficiency Repair Proposal |
7 |
Generic Attachment (attachments that do not fall into a more specific category) |
8 |
Avatar Image |
9 |
Import |
10 |
Blank Paperwork |
11 |
Work Acknowledgement |
12 |
Logo |
14 |
Job Invoice |
Embedded Object Reference
Many resources will contain sub-objects that are a more lightweight version of a larger resource. For example, Location resources contain a Company embedded object, which contains a subset of the full Company resource information.
In the returned elements reference sections of each reference, if a resource contains an embedded object, its type will be listed as one of the types below. If a specific resource provides more data in the embedded object than is listed here, it will be listed in the resources return values.
Account
Name |
Type |
Value |
id |
integer |
id of the account |
name |
string |
name of the account |
Account Type
Name |
Type |
Value |
id |
integer |
id of the account type |
name |
string |
name of the account type |
Activity
Name |
Type |
Value |
id |
integer |
id of the activity |
name |
string |
name of the activity |
description |
string |
description of the activity |
Address
Name |
Type |
Value |
street |
string |
|
city |
string |
|
state |
string |
|
postalCode |
string |
|
Appointment
Name |
Type |
Value |
id |
integer |
id of the appointment |
uri |
string |
resource identifier of the appointment |
name |
string |
name of the appointment |
Asset
Name |
Type |
Value |
id |
integer |
id of the asset |
uri |
string |
resource identifier of the asset |
name |
string |
name of the asset |
Asset Definition
Name |
Type |
Value |
id |
integer |
id of the asset definition |
uri |
string |
resource identifier of the asset definition |
type |
string |
type of the asset |
display |
string |
display name for the asset type |
Brand
Name |
Type |
Value |
id |
integer |
id of the brand |
uri |
string |
resource identifier of the brand |
name |
string |
name of the brand |
Budget
Name |
Type |
Value |
id |
integer |
id of the budget |
uri |
string |
resource identifier of the budget |
referenceNumber |
string |
reference number that this budget line is known by |
sequence |
integer |
0 for baseline, otherwise the revision number of the budget |
status |
string |
status of the budget |
type |
string |
type of the budget |
Budget Category
Name |
Type |
Value |
id |
integer |
id of the budget category |
uri |
string |
resource identifier of the budget category |
referenceNumber |
string |
reference number that this budget line is known by |
cost |
double |
cost of category |
libItemType |
string |
lib item type for category |
orderIndex |
integer |
order to display |
Budget Line Item
Name |
Type |
Value |
id |
integer |
id of the budget line item |
uri |
string |
resource identifier of the budget line item |
referenceNumber |
string |
reference number that this budget line is known by |
name |
string |
name of line item |
cost |
double |
cost of line item |
quantity |
double |
quantity of line item |
total |
double |
cost total of line item |
libItemType |
string |
lib item type for line item |
orderIndex |
integer |
order to display |
Company
Name |
Type |
Value |
id |
integer |
id of the company |
uri |
string |
resource identifier of the company |
name |
string |
name of the company |
status |
string |
one of pending, active, on_hold, or inactive |
Change Order
Name |
Type |
Value |
id |
integer |
id of the company |
uri |
string |
resource identifier of the company |
status |
string |
one of draft, pending, rejected, approved, or applied |
type |
string |
one of external or internal |
Change Order Line Item
Name |
Type |
Value |
id |
integer |
id of the company |
uri |
string |
resource identifier of the company |
referenceNumber |
string |
reference number that the affected budget line is known by |
changeAction |
string |
action taken by this change order line item |
name |
string |
name of line item |
cost |
double |
cost of line item |
quantity |
double |
quantity of line item |
libItemType |
string |
lib item type for line item |
orderIndex |
integer |
order to display |
Deficiency
Name |
Type |
Value |
id |
integer |
id of the deficiency |
uri |
string |
resource identifier of the deficiency |
name |
string |
name of the deficiency |
description |
string |
description of the deficiency |
Contact
Name |
Type |
Value |
id |
integer |
id of the contact |
uri |
string |
resource identifier of the contact |
firstName |
string |
contact first name |
lastName |
string |
contact last name |
type |
string |
contact type, free form string describing what type of contact this is |
phone |
string |
contact phone |
mobile |
string |
contact mobile |
alternatePhone |
string |
contact alternate phone |
email |
string |
contact email |
Entity Filter
Name |
Type |
Value |
id |
integer |
id of the entity filter |
uri |
string |
resource identifier of the entity filter |
name |
string |
name of the entity filter |
Invoice
Name |
Type |
Value |
id |
integer |
id of the invoice |
uri |
string |
resource identifier of the invoice |
name |
string |
name of the invoice |
Job
Name |
Type |
Value |
id |
integer |
id of the job |
uri |
string |
resource identifier of the job |
name |
string |
name of the job |
number |
integer |
external job identifier |
type |
string |
one of: unknown, repair, construction, upgrade, service_call, urgent_service_call, priority_service_call, emergency_service_call, cleaning, inspection, survey, preventative_maintenance, delivery, sales, installation |
primaryContact |
Contact |
the primary contact of this job |
Job Item
Name |
Type |
Value |
id |
integer |
id of the item |
uri |
string |
resource identifier of the item |
description |
string |
name of the item |
cost |
double |
cost of the item |
usedOn |
integer (timestamp) |
date on which the item was used |
Invoice Item
Name |
Type |
Value |
id |
integer |
item id |
uri |
string |
resource identifier for the given item |
description |
string |
item description |
quantity |
double |
item quantity |
price |
double |
item unit price |
subtotal |
double |
total price (quantity * price) not including taxes |
taxRate |
double |
tax rate as a percentage (5.5 indicates 5.5%) |
taxGroup |
Tax Group |
tax group applying to this item |
taxAmount |
double |
tax amount in dollars |
totalPrice |
double |
total including taxes |
orderIndex |
integer |
order in which item appears in list of invoice items |
libItem |
Libitem |
libitem that this item is an instance of |
serviceLine |
Service Line |
service line associated with this item |
jobItem |
Job Item |
jobItem this item was created from |
Invoice Recurrence
Name |
Type |
Value |
id |
integer |
id of the item |
uri |
string |
resource identifier of the item |
Invoice Recurrence Item
Name |
Type |
Value |
id |
integer |
id of the item |
uri |
string |
resource identifier of the item |
description |
string |
name of the item |
quantity |
double |
quantity of the item |
price |
double |
price of the item |
cost |
double |
cost of the item |
LibItem
Name |
Type |
Value |
id |
integer |
id of the item |
uri |
string |
resource identifier of the item |
name |
string |
name of the item |
type |
type |
type of the item |
code |
string |
lib item code |
isGeneric |
boolean |
true indicates this item is used for representing generic or ad-hoc items |
Location
Name |
Type |
Value |
id |
integer |
id of the location |
uri |
string |
resource identifier of the location |
name |
string |
name of the location |
legacyId |
string |
legacy identifier for the location |
lat |
double |
location geocode latitude |
lon |
double |
location geocode longitude |
address |
Address |
address of the location |
phoneNumber |
string |
phone number of the location formatted as (XXX) XXX-XXXX |
email |
string |
email address of the location |
primaryContact |
Contact |
information for the primary contact at the location |
taxable |
boolean |
should invoice items for invoices at this location be taxable by default? |
status |
string |
one of pending, active, or inactive |
Payment Terms
Name |
Type |
Value |
id |
integer |
id of the payment terms |
uri |
string |
resource identifier of the payment terms |
name |
string |
payment terms name |
orderIndex |
integer |
payment terms order index |
Quote
Name |
Type |
Value |
id |
integer |
id of the quote |
uri |
string |
resource identifier of the quote |
name |
string |
name of the quote |
status |
string |
status of the quote |
Quote Item
Name |
Type |
Value |
id |
integer |
id of the item |
uri |
string |
resource identifier of the item |
description |
string |
name of the item |
Quote Template Item
Name |
Type |
Value |
id |
integer |
id of the item |
uri |
string |
resource identifier of the item |
description |
string |
name of the item |
Quote Request
Name |
Type |
Value |
id |
integer |
id of the quote request |
uri |
string |
resource identifier of the quote request |
name |
string |
name of the quote request |
status |
string |
status, one of: canceled, unsent, approved, quote_received, all_canceled, all_rejected, waiting |
Role
Name |
Type |
Value |
id |
integer |
id of the role |
uri |
string |
resource identifier of the role |
name |
string |
name of the role |
Region
Name |
Type |
Value |
id |
integer |
id of the region |
uri |
string |
resource identifier of the region |
name |
string |
name of the region |
Service Item
Name |
Type |
Value |
id |
integer |
item id |
uri |
string |
resource identifier for the given item |
description |
string |
item description |
quantity |
double |
item quantity |
price |
double |
item unit price |
orderIndex |
integer |
order in which item appears in list of invoice items |
libItem |
Libitem |
libitem that this item is an instance of |
Service Line
Name |
Type |
Value |
id |
integer |
id of the service line |
name |
string |
name of the service line |
trade |
string |
general trade category to which this service line belongs (e. g. Fire Protection, HVAC) |
abbr |
string |
service line abbreviation |
icon |
string |
url to image of the visual representaion of this service line |
Service Recurrence
Name |
Type |
Value |
id |
integer |
id of the service recurrence |
uri |
string |
resource identifier of the service recurrence |
description |
string |
description of the service |
frequency |
string |
frequency of recurrence, one of: daily, weekly, monthly, quarterly, semiannually, yearly |
interval |
integer |
interval of recurrence |
repeatWeekday |
boolean |
recurrence repeats on a specific day or date (e. g. the 1st Tuesday, or the 3rd Friday) |
Service Request
Name |
Type |
Value |
id |
integer |
id of the service request |
uri |
string |
resource identifier of the service request |
description |
string |
description of the service request |
Service Template
Name |
Type |
Value |
id |
integer |
id of the service template |
uri |
string |
resource identifier of the service template |
name |
string |
name of the template |
description |
string |
description of the service |
frequency |
string |
frequency of template , one of: daily, weekly, monthly, quarterly, semiannually, yearly |
interval |
integer |
interval of template |
repeatWeekday |
boolean |
template repeats on a specific day or date (e. g. the 1st Tuesday, or the 3rd Friday) |
Tag
Name |
Type |
Value |
id |
integer |
id of the tag |
uri |
string |
resource identifier of the tag |
name |
string |
name of the tag |
Tax Group
Name |
Type |
Value |
id |
integer |
id of the tax group |
uri |
string |
resource identifier of the tax group |
code |
string |
Tax Group Code |
name |
string |
Tax Group Name |
combinedRate |
double |
Combined tax rate as a decimal (e.g. 8.5% rate is represented as 0.085) |
state |
string |
State abbreviation |
Terms
Name |
Type |
Value |
id |
integer |
id of the terms |
uri |
string |
resource identifier of the terms |
name |
string |
terms name |
content |
string |
terms content |
User
Name |
Type |
Value |
id |
integer |
id of the user |
uri |
string |
resource identifier of the user |
name |
string |
name of the user |
status |
string |
status of the user: active, inactive |
email |
string |
email address of the user |
avatar |
object |
list of urls for user avatars |
avatar.small |
string |
32 x 32 avatar image |
avatar.medium |
string |
64 x 64 avatar image |
avatar.large |
string |
128 x 128 avatar image |
isTech |
boolean |
is the user technician |
isHelper |
boolean |
is the user helper |
Webhook
Name |
Type |
Value |
id |
integer |
id of the webhook |
uri |
string |
resource identifier of the webhook |
hookUrl |
string |
endpoint url for the webhook |
enabled |
boolean |
is the webhook currently active? |
confirmed |
boolean |
has the webhook been confirmed? |
includeChangesets |
boolean |
will changesets be included in updated webhook messages? |
Resource Reference
Account Settings
The account settings resource is used to retrieve account settings.
- Resource URL: /accountsettings
- Available Verbs: GET
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/accountsettings |
200 |
|
GET |
/accountsettings |
401 |
unauthorized |
POST |
/accountsettings |
405 |
not allowed |
PUT |
/accountsettings |
405 |
not allowed |
DELETE |
/accountsettings |
405 |
not allowed |
Returned Elements
Name |
Type |
Value |
jobTypes |
array |
Job Type names selected in scope of current account |
itemTypes |
array |
Item Type names selected in scope of current account |
mobileJobTaskWorkflow |
array |
Task driven workflow selected in scope of current account (comment/attachment/review) |
mobileJobItemConfirmation |
array |
Part usage confirmation selected in scope of current account (jobs/projects) |
assetDefinitions |
array |
Asset Definition ids selected in scope of current account |
changeOrderTermsId |
integer |
default Terms and Conditions applied for Change Orders in scope of current account |
jobTermsId |
integer |
default Terms and Conditions applied for Jobs in scope of current account |
quoteTermsId |
integer |
default Terms and Conditions applied for Quotes in scope of current account |
invoiceTermsId |
integer |
default Terms and Conditions applied for Invoices in scope of current account |
attachmentVisibility |
array |
default visibility applied for Attachments in scope of current account |
deficiencyVisibility |
array |
default visibility applied for Deficiencies in scope of current account |
commentVisibility |
array |
default visibility applied for Deficiencies in scope of current account |
jobItemVisibility |
array |
default visibility applied for Deficiencies in scope of current account |
quoteDetailLevel |
array |
default Detail Level applied for Quotes in scope of account |
invoiceDetailLevel |
array |
default Detail Level applied for Invoices in scope of account |
salesTaxSource |
string |
Source of sales tax data, one of: manual, taxgroup |
Retrieve user account settings
GET /accountsettings
200
{
"data": {
"jobTypes": [
"service_call",
"priority_service_call",
"urgent_service_call",
"emergency_service_call",
"cleaning",
"construction",
"delivery",
"pickup",
"exchange",
"inspection",
"priority_inspection",
"reinspection",
"installation",
"retrofit",
"preventative_maintenance",
"planned_maintenance",
"quality_assurance",
"repair",
"inspection_repair",
"sales",
"survey",
"upgrade",
"warranty",
"replacement",
"design",
"buildout",
"hookup",
"testing",
"consultation",
"training",
"administrative",
"unknown"
],
"itemTypes": [
"part",
"material",
"labor",
"equipment",
"inspection",
"service",
"subcontractor",
"fee",
"general_conditions",
"other"
],
"mobileJobTaskWorkflow": [
"comment",
"attachment",
"deficiency"
],
"mobileJobItemConfirmation": [
"jobs",
"projects"
],
"assetDefinitions": [
9,
16,
17
],
"changeOrderTermsId": 2,
"jobTermsId": 3,
"quoteTermsId": null,
"invoiceTermsId": 4,
"attachmentVisibility": [
"private"
],
"deficiencyVisibility": [
"private"
],
"commentVisibility": [
"private",
"tech",
"schedule"
],
"jobItemVisibility": [
"public"
],
"quoteDetailLevel": [
"public",
"items",
"time_and_materials"
],
"invoiceDetailLevel": [
"public",
"items_by_type",
"type_detail"
],
"salesTaxSource": "taxgroup"
}
}
Return to Top
Activity
The activity resource is used to retrieve lists of available permissions that can be assigned to user roles
- Resource URL: /activity/[activityId]
- Available Verbs: GET
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/activity |
200 |
|
GET |
/activity/location.edit |
200 |
|
GET |
/activity/doesnt.exist |
404 |
activity "doesnt.exist" not found |
POST |
/activity |
405 |
not allowed |
PUT |
/activity |
405 |
not allowed |
DELETE |
/activity |
405 |
not allowed |
Returned Elements
Name |
Type |
Value |
activities |
array (Activity) |
list of activity objects |
Retrieve all available activities
GET /activity
200
{
"data": {
"totalPages": 1,
"page": 1,
"activities": [
{
"id": "job.manage",
"name": "Manage Jobs",
"description": "Manage defining, assigning, canceling, and copying jobs, and modifying their job items"
},{
"id": "location.view",
"name": "View Location Info for My Company",
"description": "View information about your company's locations"
},{
"id": "location.edit",
"name": "Edit Location Info for My Company",
"description": "Edit your own company location information"
},{
"id": "quote.export",
"name": "Bulk Export Quote Data",
"description": "Can bulk export quote data to other formats like CSV."
}
]
}
}
Retrieve information for a single activity
GET /activity/job.manage
200
{
"data": {
"id": "job.manage",
"name": "Manage Jobs",
"description": "Manage defining, assigning, canceling, and copying jobs, and modifying their job items"
}
}
Retrieve information for an activity which does not exist
GET /activity/foo.bar
404
Return to Top
Appointment
The appointment resource is used to retrieve lists of appointments or detailed information about a single appointment. Services can be added to an appointment when the appointment is created or afterwards. Added services must belong to the job that the appointment is created for.
- Resource URL: /appointment/[appointmentId]
- Available Verbs: GET, POST, PUT, DELETE
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/appointment |
200 |
|
GET |
/appointment/123 |
200 |
|
GET |
/appointment/123 |
404 |
appointment 123 not found |
POST |
/appointment |
200 |
appointment created |
POST |
/appointment |
400 |
bad data for create |
POST |
/appointment/123/servicerequest |
200 |
service added to appointment |
POST |
/appointment/123/servicerequest |
404 |
appointment or service not found |
POST |
/appointment/123/servicerequest |
400 |
could not add service to appointment |
PUT |
/appointment |
405 |
not allowed |
PUT |
/appointment/123 |
200 |
appointment updated |
PUT |
/appointment/123 |
404 |
appointment 123 not found |
PUT |
/appointment/123/servicerequest/456 |
200 |
service updated on appointment |
PUT |
/appointment/123/servicerequest/456 |
404 |
appointment or service not found, or service not on appointment |
PUT |
/appointment/123/servicerequest/456 |
400 |
could not update service on appointment |
DELETE |
/appointment |
405 |
not allowed |
DELETE |
/appointment/123 |
204 |
appointment deleted |
DELETE |
/appointment/456 |
404 |
appointment is not in 'unscheduled' status (or not accessible by the user) |
DELETE |
/appointment/789 |
409 |
appointment is referenced by other entities |
Query Params
Name |
Type |
Value |
jobNumber |
integer |
returns only appointments for the given job number |
jobType |
array |
returns only appointments for the given job types |
jobId |
integer |
return appointments for this job id |
locationId |
integer |
return appointments for any of this list of comma separated location ids |
locationName |
string |
return appointments for locations whose names match this substring |
lat |
double |
latitude of current location; must also supply lon |
lon |
double |
longitude of current location; must also supply lat |
radius |
double |
radius in miles to search around; must also supply lat and lon |
released |
boolean |
filter on whether this appointment has been released to its assigned techs |
status |
string |
comma delimited list of statuses: "scheduled", "unscheduled", "canceled_by_vendor", "canceled_by_customer", "completed", "no_show"; if not supplied, defaults to all statuses except "unscheduled" |
serviceLineIds |
string |
comma delimited list of integers of service line ids for services associated with the appointment |
techIds |
string |
comma delimited list of integers of user ids for technicians assigned |
officeIds |
string |
comma delimited list of integers of office ids for offices servicing the appointment location |
assignedOfficeIds |
string |
comma delimited list of integers of office ids, returns appointments for jobs assigned to these offices |
regionIds |
string |
comma delimited list of integers of region ids, returns only appointments at locations within any of those regions |
vendorId |
integer |
return appointments for this vendor |
customerId |
integer |
return appointments for jobs for any of this list of comma separated customer ids |
customerName |
string |
return appointments for jobs whose customer names match this substring |
primeContractorId |
integer |
return appointments for jobs from this prime contractor |
jobOwnerIds |
string |
return appointments for jobs whose job owner is any of this list of comma separated user ids |
jobSalesIds |
string |
return appointments for jobs whose job salesperson is any of this list of comma separated user ids |
assigned |
boolean |
if true, return appointments with at least one technician assigned; else return appointments with no technicians assigned |
subcontracted |
boolean |
if true, return appointments whose job has different prime contractor and vendor; if false return appointments where the prime and vendor are the same |
windowBeginsBefore |
integer |
timestamp, matches appointments whose window begin is on or before |
windowBeginsAfter |
integer |
timestamp, matches appointments whose window begin is on or after |
windowEndsBefore |
integer |
timestamp, matches appointments whose window end is on or before |
windowEndsAfter |
integer |
timestamp, matches appointments whose window end is on or after |
dueByBefore |
integer |
timestamp, matches appointments whose due by is on or before |
dueByAfter |
integer |
timestamp, matches appointments whose due by is on or after |
jobEstimatedPriceFrom |
double |
Only return appointments whose job has an estimated price greater than or equal (null price excluded) |
jobEstimatedPriceTo |
double |
Only return appointments whose job has an estimated price less than or equal (null price excluded) |
jobDueByBefore |
integer |
timestamp, matches appointments for jobs due on or before |
jobDueByAfter |
integer |
timestamp, matches appointments for jobs due on or after |
jobTags |
string |
comma-separated list of tag strings, only appointments whose job has all tags will be returned |
limit |
integer |
limit the appointments returned - takes radius into account if specified (default 2000, maximum 2000) |
createdBefore |
integer |
timestamp, matches records created on or before |
createdAfter |
integer |
timestamp, matches records created on or after |
updatedBefore |
integer |
timestamp, matches records updated on or before |
updatedAfter |
integer |
timestamp, matches records updated on or after |
sort |
string |
field to sort by, one of: windowStart, jobDueBy, jobTypeWeight, distance (only if lat/lon params are provided). See details below. |
sortOrder |
string |
order of sort, either ASC or DESC (ASC is the default) |
Sort order notes: If lat and lon query params are provided, the default sort is ascending distance from the provided lat/lon point. Otherwise, the default sort is windowStart.
If the sort is jobTypeWeight, appointments will be returned in the following order: Emergency job types first, then urgent job types, then priority job types, then all other job types. For jobTypeWeight sorting only, the secondary sort is job due date, ordered in the opposite direction of the requested sortOrder. To return appointments with the highest importance and earliest due appointments first, use &sort=jobTypeWeight&sortOrder=DESC
.
Parameters for POST
Name |
Type |
Required |
Value |
jobId |
integer |
yes |
job of which this appointment is in fulfilment |
status |
string |
no |
one of "scheduled", "unscheduled", "canceled_by_vendor", "canceled_by_customer", "completed", "no_show", defaults to "scheduled" |
serviceRequestIds |
array (integer) |
no |
services to be fulfilled on this appointment (services must belong to the job represented by jobId) |
techIds |
array (integer) |
no |
technicians assigned to this appointment |
windowStart |
integer |
no |
Unix timestamp of the appointment's window start. If not provided, defaults to null for unscheduled and to current time for all other appointment statuses. |
windowEnd |
integer |
no |
Unix timestamp of the appointment’s window end. If not provided, defaults to null for unscheduled and to current time for all other appointment statuses. |
released |
boolean |
no |
should this appointment be visible to the assigned techs? defaults to false if you have appointment releasing enabled for your account, true otherwise |
Parameters for POST appointment/servicerequest
Name |
Type |
Required |
Value |
serviceRequestId |
integer |
yes |
service to add to this appointment (service must belong to the appointment's job) |
completion |
string |
no |
state of the service related to the appointment; one of "pending" (default), "not_done", "done", "invalid" |
Parameters for PUT
Name |
Type |
Value |
status |
string |
one of "scheduled", "canceled_by_vendor", "canceled_by_customer", "completed", "no_show" |
serviceRequestIds |
array (integer) |
services to be fulfilled on this appointment (services must belong to the job represented by jobId) |
techIds |
array (integer) |
technicians assigned to this appointment |
windowStart |
integer |
Unix timestamp of the appointment's window start date and time |
windowEnd |
integer |
Unix timestamp of the appointment’s window end date and time |
released |
boolean |
should this appointment be visible to the assigned techs? |
Returned Elements
Name |
Type |
Value |
appointments |
array (Appointment) |
list of appointment objects |
status |
string |
one of: scheduled, canceled_by_vendor, canceled_by_customer, completed, no_show |
windowStart |
integer |
Unix timestamp of the appointment's scheduled window start date and time |
windowEnd |
integer |
Unix timestamp of the appointment’s scheduled window end date and time |
location |
Location |
id of the location of the appointment |
location.distance |
double |
distance in miles from the current location if able to calculate, null otherwise |
vendor |
Company |
id of vendor of this appointment |
dueBy |
integer |
Unix timestamp of the appointment’s due by date and time |
serviceRequests |
array (Service Request) |
list of services for this appointment |
serviceRequest.status |
string |
status of the service on its own; one of "open", "in_progress", "closed", "void", "canceled" |
serviceRequest.completion |
string |
state of the service related to the appointment; one of "pending", "not_done", "done", "invalid" |
serviceRequest.description |
string |
description of work to be completed |
serviceRequest.serviceLine |
Service Line |
service line to which this service belongs |
serviceRequest.asset |
Asset |
associated asset to this service request, or null if there is none |
serviceRequest.windowStart |
integer |
Unix timestamp of when the service's window starts |
serviceRequest.windowEnd |
integer |
Unix timestamp of when the service's window ends |
serviceRequest.estimatedPrice |
double |
the estimated price of the service request; null if there is none, or if the user does not have permission to view estimated prices |
serviceRequest.duration |
integer |
the estimated duration of the service request in seconds |
job |
Job |
id of the job for this appointment |
job.description |
string |
description of the appointment's job |
job.jobTypeWeight |
integer |
the numeric priority weight of this job based on its type; higher numbers have higher importance |
job.dueBy |
integer |
Unix timestamp of when the job is due or null for no due date |
job.tags |
array (Tag) |
list of tags on the appointment's job |
job.estimatedPrice |
double |
the estimated price on the job; null if there is none, or if the user does not have permission to view estimated prices |
techs |
array (User) |
list of users assigned to this appointment |
offices |
array (Location) |
list of offices that service this appointment's location |
released |
boolean |
has this appointment been released to its assigned techs? |
created |
integer |
Unix timestamp of this record's creation time |
updated |
integer |
Unix timestamp of when this record was last updated |
Retrieve all appointments that match a given job number
GET /appointment?jobNumber=209375
200
{
"data": {
"totalPages": 1,
"page": 1,
"appointments": [
{
"id": 9,
"uri": "https://api.servicetrade.com/api/appointment/9",
"name": "Appointment #9",
"status": "scheduled",
"windowStart": 1322143200,
"windowEnd": 1322176260,
"location": {
"id": 47,
"uri": "https://api.servicetrade.com/api/location/47",
"name": "Salmon Ella's Seafood Shack",
"legacyId": 3432,
"lat": 35.291712,
"lon": -78.595006,
"distance": null,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "123 Herring Bone Way",
"city": "Wilmington",
"state": "NC",
"postalCode": "28403"
},
"distance": null,
"taxable": false,
"status": "active"
},
"vendor": {
"id": 9,
"uri": "https://api.servicetrade.com/api/company/9",
"name": "Super Awesome Company, Inc",
"status": "active"
},
"dueBy": 1322690442,
"serviceRequests": [
{
"id": 11,
"uri": "https://api.servicetrade.com/api/servicerequest/11",
"name": "",
"completion": "pending",
"description": "Fix the broken flanges",
"serviceLine": {
"id": 43,
"name": "Sprinkler",
"trade": "Fire Protection",
"abbr": "SP",
"icon": "https://app.servicetrade.com/image/icons/service_lines/32/SP.png"
},
"asset": null,
"windowStart": 1322680442,
"windowEnd": 1322690442,
"duration": null,
"estimatedPrice": null
}
],
"job": {
"id": 30,
"uri": "https://api.servicetrade.com/api/job/30",
"number": 209375,
"type": "inspection",
"name": "Job 209375",
"tags": [],
"dueBy": 1322143200,
"estimatedPrice": null
},
"techs": [
{
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"email": "joe@testcompany.com",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
}
],
"offices": [
{
"id": 23,
"uri": "https://api.servicetrade.com/api/location/23",
"name": "Central Office",
"legacyId": 3443,
"lat": 35.291712,
"lon": -78.595006,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "742 Super Awesome Ct.",
"city": "Durham",
"state": "NC",
"postalCode": "27703"
},
"taxable": false
}
],
"released": true,
"created": 1399993795,
"updated": 1399994065
}
]
}
}
Retrieve all appointments in a given area, includes the distance from given coordinates
GET /appointment?lat=30.50012&lon=-84.34233&radius=500
200
{
"data": {
"totalPages": 1,
"page": 1,
"appointments": [
{
"id": 9,
"uri": "https://api.servicetrade.com/api/appointment/9",
"name": "Appointment #9",
"status": "scheduled",
"windowStart": 1322143200,
"windowEnd": 1322176260,
"location": {
"id": 10,
"uri": "https://api.servicetrade.com/api/location/10",
"name": "Belk #54 - Georgia Square",
"legacyId": null,
"lat": 33.940828,
"lon": -83.45787,
"distance": 243.3,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "3700-175 Atlanta Highway",
"city": "Athens",
"state": "GA",
"postalCode": "30606"
},
"distance": null,
"taxable": false,
"status": "active"
},
"vendor": {
"id": 9,
"uri": "https://api.servicetrade.com/api/company/9",
"name": "Super Awesome Company, Inc",
"status": "active"
},
"dueBy": 1322690442,
"serviceRequests": [
{
"id": 11,
"uri": "https://api.servicetrade.com/api/servicerequest/11",
"name": "",
"completion": "pending",
"description": "Fix the broken flanges",
"serviceLine": {
"id": 43,
"name": "Sprinkler",
"trade": "Fire Protection",
"abbr": "SP",
"icon": "https://app.servicetrade.com/image/icons/service_lines/32/SP.png"
},
"asset": null,
"windowStart": 1322680442,
"windowEnd": 1322690442,
"duration": null,
"estimatedPrice": null
}
],
"job": {
"id": 30,
"uri": "https://api.servicetrade.com/api/job/30",
"number": 209375,
"type": "inspection",
"name": "Job 209375",
"tags": [],
"dueBy": 1322143200,
"estimatedPrice": null
},
"techs": [
{
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"email": "joe@testcompany.com",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
}
],
"offices": [],
"released": true,
"created": 1399993795,
"updated": 1399994065
}
]
}
}
No appointment matches found
GET /appointment?jobNumber=4564256
200
{
"data": {
"totalPages": 1,
"page": 1,
"appointments": []
}
}
Retrieve information for a single appointment
GET /appointment/9
200
{
"data": {
"id": 9,
"uri": "https://api.servicetrade.com/api/appointment/9",
"name": "Appointment #9",
"status": "scheduled",
"windowStart": 1322143200,
"windowEnd": 1322176260,
"location": {
"id": 47,
"uri": "https://api.servicetrade.com/api/location/47",
"name": "Salmon Ella's Seafood Shack",
"legacyId": 3432,
"lat": 35.291712,
"lon": -78.595006,
"distance": null,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "123 Herring Bone Way",
"city": "Wilmington",
"state": "NC",
"postalCode": "28403"
},
"distance": null,
"taxable": false,
"status": "active"
},
"vendor": {
"id": 9,
"uri": "https://api.servicetrade.com/api/company/9",
"name": "Super Awesome Company, Inc",
"status": "active"
},
"dueBy": 1322690442,
"serviceRequests": [
{
"id": 11,
"uri": "https://api.servicetrade.com/api/servicerequest/11",
"name": "",
"completion": "pending",
"description": "Fix the broken flanges",
"serviceLine": {
"id": 43,
"name": "Sprinkler",
"trade": "Fire Protection",
"abbr": "SP",
"icon": "https://app.servicetrade.com/image/icons/service_lines/32/SP.png"
},
"asset": null,
"windowStart": 1322680442,
"windowEnd": 1322690442,
"duration": null,
"estimatedPrice": null
}
],
"job": {
"id": 30,
"uri": "https://api.servicetrade.com/api/job/30",
"number": 209375,
"type": "inspection",
"name": "Job 209375",
"tags": [],
"dueBy": 1322143200,
"estimatedPrice": null
},
"techs": [
{
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"email": "joe@testcompany.com",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
}
],
"offices": [
{
"id": 23,
"uri": "https://api.servicetrade.com/api/location/23",
"name": "Central Office",
"lat": 35.291712,
"lon": -78.595006,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "742 Super Awesome Ct.",
"city": "Durham",
"state": "NC",
"postalCode": "27703"
},
"taxable": false
}
],
"released": true,
"created": 1399993795,
"updated": 1399994065
}
}
Retrieve information for a appointment which does not exist
GET /appointment/987
404
Create an appointment for a job
POST /appointment
{"jobId":30,"windowStart":1343241126,"windowEnd":1343346050,"techIds":[6],"serviceRequestIds":[11]}
200
{
"data": {
"id": 221,
"uri": "https://api.servicetrade.com/api/appointment/221",
"name": "Appointment #221",
"status": "scheduled",
"windowStart": 1343241126,
"windowEnd": 1343346050,
"location": {
"id": 47,
"uri": "https://api.servicetrade.com/api/location/47",
"name": "Salmon Ella's Seafood Shack",
"legacyId": 3432,
"lat": 35.291712,
"lon": -78.595006,
"distance": null,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "123 Herring Bone Way",
"city": "Wilmington",
"state": "NC",
"postalCode": "28403"
},
"distance": null,
"taxable": false,
"status": "active"
},
"vendor": {
"id": 9,
"uri": "https://api.servicetrade.com/api/company/9",
"name": "Super Awesome Company, Inc",
"status": "active"
},
"dueBy": 1322690442,
"serviceRequests": [
{
"id": 11,
"uri": "https://api.servicetrade.com/api/servicerequest/11",
"name": "",
"completion": "pending",
"description": "Fix the broken flanges",
"serviceLine": {
"id": 43,
"name": "Sprinkler",
"trade": "Fire Protection",
"abbr": "SP",
"icon": "https://app.servicetrade.com/image/icons/service_lines/32/SP.png"
},
"asset": null,
"windowStart": 1343241126,
"windowEnd": 1343346050,
"duration": null,
"estimatedPrice": null
}
],
"job": {
"id": 30,
"uri": "https://api.servicetrade.com/api/job/30",
"number": 209375,
"type": "inspection",
"name": "Job 209375",
"tags": [],
"dueBy": 1322143200,
"estimatedPrice": null
},
"techs": [
{
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"email": "joe@testcompany.com",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
}
],
"offices": [],
"released": true,
"created": 1399993795,
"updated": 1399994065
}
}
Add a service to an existing appointment
POST /appointment/221/servicerequest
{"serviceRequestId":11,"completion":"not_done"}
200
{
"data": {
"id": 11,
"uri": "https://api.servicetrade.com/api/servicerequest/11",
"name": "",
"completion": "not_done"
}
}
Update a service's status related to an appointment
PUT /appointment/221/servicerequest/11
{"completion":"done"}
200
{
"data": {
"id": 11,
"uri": "https://api.servicetrade.com/api/servicerequest/11",
"name": "",
"completion": "done"
}
}
Return to Top
Asset
The asset resource is used to retrieve lists of assets or detailed information about a single asset.
- Resource URL: /asset/[assetId]
- Available Verbs: GET, POST, PUT, DELETE
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/asset |
405 |
not allowed |
GET |
/asset/123 |
200 |
|
GET |
/asset/123 |
404 |
asset 123 not found |
GET |
/asset/123/deficiency |
200 |
retrieve list of deficiencies for this asset |
GET |
/asset/123/deficiency/10 |
200 |
retrieve deficiency info |
POST |
/asset |
200 |
asset created |
POST |
/asset |
400 |
bad data for create |
POST |
/asset/123 |
405 |
not allowed |
POST |
/asset/123/deficiency |
200 |
report a deficiency for this asset |
PUT |
/asset/123 |
200 |
asset updated |
PUT |
/asset/123 |
400 |
bad data for update |
PUT |
/asset/123 |
404 |
asset 123 not found (or not accessible by the user) |
DELETE |
/asset |
405 |
not allowed |
DELETE |
/asset/123 |
204 |
asset deleted |
DELETE |
/asset/123 |
404 |
asset 123 not found (or not accessible by the user) |
DELETE |
/asset/123 |
409 |
asset is referenced by other entities |
Query Params
Name |
Type |
Value |
locationId |
integer |
returns all assets at the given location |
appointmentId |
integer |
returns all assets on non-canceled services assigned to an appointment |
jobId |
integer |
if provided, returns all assets on non-canceled services assigned to that job |
serviceLineIds |
string |
comma-separated list of service line ids |
type |
string |
returns all assets of the given type |
status |
string |
comma-separated list of statuses: "active", "inactive" (will default to "active" if not supplied) |
parentId |
integer |
returns all assets subassets of the given parent asset |
name |
string |
returns all assets whose name includes this string (case insensitive) |
search |
string |
Performs simple search across asset text fields |
includeChildAssets |
boolean |
if provided, returns set of assets is whatever assets where returned by the other search params plus all those assets children |
createdBefore |
integer |
timestamp, matches records created on or before |
createdAfter |
integer |
timestamp, matches records created on or after |
updatedBefore |
integer |
timestamp, matches records updated on or before |
updatedAfter |
integer |
timestamp, matches records updated on or after |
Note: locationId, jobId, appointmentId, createdBefore, createdAfter, updatedBefore, or updatedAfter must be set for all queries
POST/PUT Parameters
Name |
Type |
Value |
type |
string |
Type of asset. Required for POST. Supported on POST only. |
locationId |
integer |
Location to which the asset belongs. Required for POST. Supported on POST only. |
properties |
object |
Set of key/value property pairs specific to this type of asset. Required for POST. |
status |
string |
Status of asset; one of: 'active' or 'inactive'. If not provided for POST, defaults to 'active'. |
orderIndex |
integer |
Items are listed from low to high value, null is the default value. Optional |
parentId |
integer |
Sets the parent asset of this asset. Parent asset type must be allowable for this asset type. |
The properties available for each asset type can be retrieved from the asset definition endpoint.
Returned Elements
Name |
Type |
Value |
assets |
array (Asset) |
list of asset objects |
name |
string |
Instance-specific name of this asset |
location |
Location |
asset location |
serviceLine |
ServiceLine |
asset service line |
type |
string |
type of asset |
status |
string |
one of 'active' or 'inactive' |
legacyId |
integer |
|
display |
string |
Human-readable type description |
properties |
object |
set of key/value property pairs specific to this type of asset |
parent |
Asset |
asset's parent asset |
created |
integer |
Unix timestamp of this record's creation time |
updated |
integer |
Unix timestamp of when this record was last updated |
orderIndex |
integer |
items are listed from low to high value, null is the default value |
assetDefinition |
AssetDefinition |
asset definition |
externalIds |
object |
a key/value object of external system ids, only returned if account has external integrations defined |
Retrieve all assets that match a given location
GET /asset?locationId=2
200
{
"data": {
"totalPages": 1,
"page": 1,
"assets": [
{
"id": 1,
"uri": "https://api.servicetrade.com/api/asset/1",
"location": {
"id": 2,
"uri": "https://api.servicetrade.com/api/location/2",
"legacyId": 4567,
"name": "Chuck E. Cheese #13 - Orange",
"lat": 33.520876,
"lon": -80.882115,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "2390 Chestnut Street, Suite C3",
"city": "Orange",
"state": "SC",
"postalCode": "29115"
},
"taxable": false,
"status": "active"
},
"serviceLine": null,
"legacyId": 44222,
"type": "location",
"status": "active",
"display": "Location",
"name": "Building",
"properties": {},
"parent": null,
"created": 1460130947,
"updated": 1460130947,
"orderIndex": null,
"assetDefinition": {
"id": 16,
"uri": "https://api.servicetrade.com/api/assetdefinition/16",
"type": "location",
"display": "Location"
},
"externalIds": {
'externalSys1': 'abc123'
}
},
{
"id": 27,
"uri": "https://api.servicetrade.com/api/asset/27",
"location": {
"id": 2,
"uri": "https://api.servicetrade.com/api/location/2",
"legacyId": 4567,
"name": "Chuck E. Cheese #13 - Orange",
"lat": 33.520876,
"lon": -80.882115,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "2390 Chestnut Street, Suite C3",
"city": "Orange",
"state": "SC",
"postalCode": "29115"
},
"taxable": false,
"status": "active"
},
"serviceLine": {
"id": 5,
"name": "Sprinkler",
"trade": "Fire Protection",
"icon": "https://app.servicetrade.com/image/icons/service_lines/32/SP.png",
"abbr": "SP"
},
"legacyId": 44221,
"type": "panic_door",
"status": "active",
"display": "Panic Door",
"name": "Panic Door #3",
"properties": {
"location": "Kitchen, back wall",
"manufacturer": "SlamCo"
},
"parent": {
"id": 1,
"uri": "https://api.servicetrade.com/api/asset/1",
"name": "Location - Building"
},
"created": 1460130947,
"updated": 1460130947,
"orderIndex": null,
"assetDefinition": {
"id": 18,
"uri": "https://api.servicetrade.com/api/assetdefinition/18",
"type": "panic_door",
"display": "Panic Door"
},
"externalIds": {
'externalSys1': 'abc123'
}
}
]
}
}
No asset matches found
GET /asset?locationId=9999999
200
{
"data": {
"totalPages": 1,
"page": 1,
"assets": []
}
}
Retrieve information for a single asset
GET /asset/33
200
{
"data": {
"id": 27,
"uri": "https://api.servicetrade.com/api/asset/27",
"location": {
"id": 2,
"uri": "https://api.servicetrade.com/api/location/2",
"legacyId": 4567,
"name": "Chuck E. Cheese #13 - Orange",
"lat": 33.520876,
"lon": -80.882115,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "2390 Chestnut Street, Suite C3",
"city": "Orange",
"state": "SC",
"postalCode": "29115"
},
"taxable": false,
"status": "active"
},
"serviceLine": {
"id": 5,
"name": "Sprinkler",
"trade": "Fire Protection",
"icon": "https://app.servicetrade.com/image/icons/service_lines/32/SP.png",
"abbr": "SP"
},
"legacyId": 44221,
"type": "panic_door",
"status": "active",
"display": "Panic Door",
"name": "Panic Door #3",
"properties": {
"location": "Kitchen, back wall",
"manufacturer": "SlamCo"
},
"parent": {
"id": 1,
"uri": "https://api.servicetrade.com/api/asset/1",
"name": "Location - Building"
},
"created": 1460130947,
"updated": 1460130947,
"orderIndex": null,
"assetDefinition": {
"id": 18,
"uri": "https://api.servicetrade.com/api/assetdefinition/18",
"type": "panic_door",
"display": "Panic Door"
},
"externalIds": {
'externalSys1': 'abc123'
}
}
}
Retrieve information for a asset which does not exist
GET /asset/987
404
Create an asset
POST /asset
{"type": "grease_containment", "locationId": 2, "properties": {"type": "Grease Guard", "manufacturer": "GreaseTek"}}
200
{
"data": {
"id": 102,
"uri": "https://api.servicetrade.com/api/asset/102",
"name": "",
"location": {
"id": 33,
"uri": "https://api.servicetrade.com/api/location/33",
"legacyId": 4567,
"name": "Foo's Bar",
"lat": 12.34,
"lon": -45.67,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "123 Typewriter Way",
"city": "Aiburg",
"state": "NC",
"postalCode": "23462"
},
"taxable": false,
"status": "active"
},
"serviceLine": {
"id": 5,
"name": "Sprinkler",
"trade": "Fire Protection",
"icon": "https://app.servicetrade.com/image/icons/service_lines/32/SP.png",
"abbr": "SP"
},
"legacyId": null,
"type": "grease_containment",
"status": "active",
"display": "Grease Containment",
"properties": {
"name": null,
"type": "Grease Guard",
"manufacturer": "GreaseTek",
"model": null
},
"parent": {
"id": 1,
"uri": "https://api.servicetrade.com/api/asset/105",
"name": "Location - Building"
},
"created": 1460130947,
"updated": 1460130947,
"orderIndex": null,
"assetDefinition": {
"id": 22,
"uri": "https://api.servicetrade.com/api/assetdefinition/22",
"type": "grease_containment",
"display": "Grease Containment"
},
"externalIds": {
'externalSys1': 'abc123'
}
}
}
Update an existing asset
PUT /asset/102
{"properties": {"type": "Grease Stopper", "manufacturer": "Fixit Co"}}
200
{
"data": {
"id": 102,
"uri": "https://api.servicetrade.com/api/asset/102",
"name": "",
"location": {
"id": 33,
"uri": "https://api.servicetrade.com/api/location/33",
"legacyId": 4567,
"name": "Foo's Bar",
"lat": 12.34,
"lon": -45.67,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "123 Typewriter Way",
"city": "Aiburg",
"state": "NC",
"postalCode": "23462"
},
"taxable": false,
"status": "active"
},
"serviceLine": {
"id": 5,
"name": "Sprinkler",
"trade": "Fire Protection",
"icon": "https://app.servicetrade.com/image/icons/service_lines/32/SP.png",
"abbr": "SP"
},
"legacyId": null,
"type": "grease_containment",
"status": "active",
"display": "Grease Containment",
"properties": {
"name": null,
"type": "Grease Stopper",
"manufacturer": "Fixit Co",
"model": null
},
"parent": {
"id": 1,
"uri": "https://api.servicetrade.com/api/asset/105",
"name": "Location - Building"
},
"created": 1460130947,
"updated": 1460130947,
"orderIndex": null,
"assetDefinition": {
"id": 22,
"uri": "https://api.servicetrade.com/api/assetdefinition/22",
"type": "grease_containment",
"display": "Grease Containment"
},
"externalIds": {
'externalSys1': 'abc123'
}
}
}
Return to Top
Asset Definition
The assetdefinition resource is used to retrieve asset definitions.
- Resource URL: /assetdefinition/[id or type]
- Available Verbs: GET
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/assetdefinition |
200 |
|
GET |
/assetdefinition/123 |
200 |
|
GET |
/assetdefinition/alarm |
200 |
|
GET |
/assetdefinition/456 |
404 |
assetdefinition 456 not found |
GET |
/assetdefinition/widget |
404 |
assetdefinition of type 'widget' not found |
Query Params
Name |
Type |
Value |
active |
boolean |
true to get just asset definitions enabled in the requesting user's account, false or omit to get all definitions |
updatedAfter |
integer |
return only definitions whose last update time is on or after the given timestamp |
updatedBefore |
integer |
return only definitions whose last update time is on or before the given timestamp |
Returned Elements
Name |
Type |
Value |
assetDefinitions |
array (AssetDefinition) |
list of assetDefinition objects |
display |
string |
Human-readable type description |
instanceName |
string |
Instance-specific name template for this asset type |
type |
string |
The type of asset definition |
serviceLine |
ServiceLine |
what serviceLine this asset applies to |
properties |
object |
key/value property pairs specific to this type of asset |
parentAssetTypes |
array (AssetDefinition) |
list of assetDefinition object types that could be the parent of this type |
active |
boolean |
is this definition active for the requesting user's account? |
created |
integer |
Unix timestamp of this record's creation time |
updated |
integer |
Unix timestamp of when this record was last updated |
Property descriptors
The "properties" element is an object where the keys are the names of properties allowed for that asset type,
and the value is an object describing that property. Each property has a type and may also have other modifiers,
recommended display text, and validation constraints.
Type |
Meaning |
string |
string, meant for single-line lengths |
text |
string, meant for multiline lengths |
boolean |
true/false value |
int |
integer |
float |
floating-point value |
date |
specific date |
monthyear |
a date representing a whole month |
Modifier |
Meaning |
required |
If true, an asset is not valid without a value provided for this property |
display |
Recommended human-readable label for this property, for use in forms |
default |
If given, forms should populate the value of this field with this value when no other value has been given. |
options |
An array of acceptable values for this property. Forms usually use a <select> element for displaying these. |
other |
If given, values not listed in options can be accepted. The value of this modifier is a recommended description for selecting other values. |
collection |
If true, the value of this property will be an array. Forms should allow multiple input elements for this value. |
unique |
If true, all values in a collection must be unique. |
min |
If given, a collection must have at least this many values |
max |
If given, a collection may have no more than this many values |
range |
If given, the number of years (in both directions) in the monthyear range between which values can be accepted (monthyear type only) |
Retrieve all asset definitions
GET /assetdefinition
200
{
"data": {
"totalPages": 1,
"page": 1,
"assetDefinitions": [
{
"id": 1,
"uri": "https://api.servicetrade.com/api/assetdefinition/1",
"type": "alarm",
"display": "Alarm System",
"instanceName": "%manufacturer% %model%",
"serviceLine": {
"id": 1,
"name": "Alarm Systems",
"trade": "Fire Protection",
"abbr": "AL",
"icon": "https://api.servicetrade.com/image/icons/service_lines/32/AL.png"
},
"properties": {
"location_in_site": {
"type": "string",
"orderIndex": 0
},
"manufacturer": {
"type": "string",
"required": true,
"orderIndex": 1
},
"model": {
"type": "string",
"required": true,
"orderIndex": 2
},
"remote_manufacturer": {
"type": "string",
"orderIndex": 3
},
"remote_model": {
"type": "string",
"orderIndex": 4
},
"power_supply_manufacturer": {
"type": "string",
"orderIndex": 5
},
"power_supply_model": {
"type": "string",
"orderIndex": 6
},
"battery_size": {
"type": "float",
"orderIndex": 0
},
"battery_qty": {
"type": "int",
"orderIndex": 7
},
"notes": {
"type": "text",
"orderIndex": 8
}
},
"parentAssetTypes": [
{
"id": 16,
"uri": "http://api.servicetrade.com/api/assetdefinition/16",
"type": "location"
}
],
"active": true,
"created": 1423492206,
"updated": 1423492206
},
{
"id": 16,
"uri": "https://api.servicetrade.com/api/assetdefinition/16",
"type": "location",
"display": "Location",
"instanceName": "Building",
"serviceLine": null,
"properties": {
"notes": {
"type": "text"
}
},
"parentAssetTypes": [],
"active": true,
"created": 1423492206,
"updated": 1423492206
}
]
}
}
Retrieve information for a single asset definition by type
GET /assetdefinition/location
200
{
"data": {
"id": 16,
"uri": "https://api.servicetrade.com/api/assetdefinition/16",
"type": "location",
"display": "Location",
"instanceName": "Building",
"serviceLine": null,
"properties": {
"notes": {
"type": "text"
}
},
"parentAssetTypes": [],
"active": true,
"created": 1423492206,
"updated": 1423492206
}
}
Return to Top
Attachment
The attachment resource is used to attach arbitrary files (documents, images, audio, etc.) to specific entities (jobs, quote requests, etc.)
Uploading attachments works slightly differently than other resources, in that the binary data of the file must be sent as part of a multipart form-data post. The meta data associated with the file is sent along with the binary data as other parts of the multipart form. To send a meta field of "foo" create a form field like: <input name="meta[foo]" />
- Resource URL: /attachment/[attachmentId]
- Available Verbs: GET, POST, PUT, DELETE
- Authentication Required: yes
The following entities support attachments. Starred resources also have dedicated attachment endpoints; when using these resource-specific endpoints, it is unnecessary to provide an entityId and entityType parameter, unless otherwise noted.
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/attachment |
200 |
|
GET |
/attachment |
405 |
missing required query params |
GET |
/attachment/123 |
200 |
|
GET |
/attachment/123 |
404 |
attachment 123 not found (or not accessible by the user) |
GET |
/attachment/123/thumbnail |
200 |
|
GET |
/attachment/123/thunbnail |
404 |
attachment 123 not found (or not accessible by the user) |
POST |
/attachment |
200 |
attachment created |
POST |
/attachment |
400 |
invalid parameters or error uploading or processing the attachment |
POST |
/attachment/123 |
200 |
update the attachment |
POST |
/attachment/123 |
404 |
attachment 123 not found (or not accessible by the user) |
PUT |
/attachment |
405 |
not allowed |
PUT |
/attachment/123 |
200 |
update the attachment |
PUT |
/attachment/123 |
404 |
attachment 123 not found (or not accessible by the user) |
PUT |
/attachment/123 |
404 |
attachment not found (or not accessible by the user) |
PUT |
/attachment/123 |
403 |
attachment not editable by the user |
DELETE |
/attachment |
405 |
not allowed |
DELETE |
/attachment/123 |
204 |
attachment deleted |
DELETE |
/attachment/123 |
404 |
attachment not found (or not accessible by the user) |
DELETE |
/attachment/123 |
403 |
attachment not editable by the user |
Query Params
Name |
Type |
Value |
entityId |
integer |
id of the entity to which the file is attached (required) |
entityType |
entity type |
entity type constant of the entity to which the file is attached (required) |
purposeId |
attachment purpose type |
only return attachments with this purpose |
includeRelatedEntities |
boolean |
include attachments of service requests related to job/quote (If not job or quote then flag is ignored). |
createdAfter |
integer |
created on or after this timestamp |
createdBefore |
integer |
created on or before this timestamp |
updatedAfter |
integer |
updated on or after this timestamp |
updatedBefore |
integer |
updated on or before this timestamp |
Parameters for POST
Name |
Type |
Required |
Value |
meta[] |
array |
|
form encoded array of values |
description |
string |
|
description of the content of the attachment |
jsonp |
string |
|
name of the Javascript callback in which to wrap the response |
purposeId |
attachment purpose type |
yes |
purpose constant for the attachment (cannot be updated) |
entityId |
integer |
yes |
id of the entity to attach to (cannot be updated) |
entityType |
entity type |
yes |
entity type constant of the entity to attach to (cannot be updated) |
visibility |
array(string) |
|
visibility granted to these types of viewers outside of the account; combination of: public, customer, subcontractor. "public" indicates global visibility and overrides the other values. Will default to account default if no value is provided on POST. |
Returned Elements
Name |
Type |
Value |
uri |
string |
resource identifier of the attachment |
id |
integer |
attachment id |
contentUrl |
string |
full url to the binary data content of the attachment |
checksum |
string |
MD5 checksum of the binary data content |
meta |
object |
context specific metadata about the attachment, as a JSON object |
fileName |
string |
human readable file name (display name) |
fileType |
string |
attachment MIME type |
description |
string |
|
purposeId |
attachment purpose type |
attachment context (e. g. deficiency picture, invoice document) |
purpose |
string |
human readable purpose |
visibility |
array(string) |
visibility granted to these types of viewers outside of the account; combination of: public, customer, subcontractor. "public" indicates global visibility and overrides the other values. |
created |
integer |
Unix timestamp of the attachment’s creation date and time |
updated |
integer |
Unix timestamp of the attachment’s last update |
entity.uri |
string |
resource identifier of the entity to which this attachment is attached |
entity.id |
integer |
id of the entity to which this attachment is attached |
entity.type |
entity type |
entity type constant |
creator |
User |
resource identifier of the user who created the attachment |
Retrieve attachment 10
GET /attachment/10
200
{
"data": {
"uri": "https://api.servicetrade.com/api/attachment/10",
"id": 10,
"contentUrl": "https://s3.amazonaws.com/snaap-attachments/10_b4b9d661d5235753b4827c61b9b3dd96.png",
"meta": {
"key0": "value0",
"key1": "value1"
},
"checksum": "b4b9d661d5235753b4827c61b9b3dd96",
"fileName": "brokenFoobars.png",
"fileType": "image/png",
"description": "The foo bars above the oscillating wingo are borked",
"purposeId": 3,
"purpose": "Job Picture",
"visibility": ["public"],
"created": 1327082916,
"updated": 1327082916,
"entity": {
"uri": "https://api.servicetrade.com/api/job/41",
"id": 41,
"type": 3
},
"creator": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User"
}
}
}
Delete attachment 10
DELETE /attachment/10
204
Upload a file
POST /attachment
Content-Type:multipart/form-data; boundary=----boundaryGywPoFXO23hZFxNn
------boundaryGywPoFXO23hZFxNn
Content-Disposition: form-data; name="purposeId"
3
------boundaryGywPoFXO23hZFxNn
Content-Disposition: form-data; name="entityType"
3
------boundaryGywPoFXO23hZFxNn
Content-Disposition: form-data; name="entityId"
41
------boundaryGywPoFXO23hZFxNn
Content-Disposition: form-data; name="description"
The foo bars above the oscillating wingo are borked
------boundaryGywPoFXO23hZFxNn
Content-Disposition: form-data; name="uploadedFile"; filename="brokenFoobars.png"
Content-Type: image/png
...binary image data goes here...
------boundaryGywPoFXO23hZFxNn--
200
{
"data": {
"uri": "https://api.servicetrade.com/api/attachment/10",
"id": 10,
"contentUrl": "https://s3.amazonaws.com/snaap-attachments/10_b4b9d661d5235753b4827c61b9b3dd96.png",
"checksum": "b4b9d661d5235753b4827c61b9b3dd96",
"meta": {},
"fileName": "brokenFoobars.png",
"fileType": "image/png",
"description": "The foo bars above the oscillating wingo are borked",
"purposeId": 3,
"purpose": "Job Picture",
"visibility": ["public"],
"created": 1327082916,
"updated": 1327082916,
"entity": {
"uri": "https://api.servicetrade.com/api/job/41",
"id": 41,
"type": 3
},
"creator": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User"
}
}
}
Upload a file wrapped in a JSONP callback
POST /attachment
Content-Type:multipart/form-data; boundary=----boundaryGywPoFXO23hZFxNn
------boundaryGywPoFXO23hZFxNn
Content-Disposition: form-data; name="purposeId"
2
------boundaryGywPoFXO23hZFxNn
Content-Disposition: form-data; name="entityType"
3
------boundaryGywPoFXO23hZFxNn
Content-Disposition: form-data; name="entityId"
41
------boundaryGywPoFXO23hZFxNn
Content-Disposition: form-data; name="description"
The foo bars above the oscillating wingo are borked
------boundaryGywPoFXO23hZFxNn
Content-Disposition: form-data; name="jsonp"
console.log
------boundaryGywPoFXO23hZFxNn
Content-Disposition: form-data; name="uploadedFile"; filename="brokenFoobars.png"
Content-Type: image/png
...binary image data goes here...
------boundaryGywPoFXO23hZFxNn--
200
<!DOCTYPE html>
<html>
<head>
<title>SNaaP - jsonp response</title>
</head>
<body>
<script type="text/javascript">console.log({"status":{"code":200,"message":"File Upload Complete"},
"data":{"uri":"https:\/\/api.servicetrade.com\/api\/attachment\/10","id":10,
"contentUrl":"https:\/\/s3.amazonaws.com\/snaap-attachments\/10_b4b9d661d5235753b4827c61b9b3dd96.png",
"meta":{},"checksum":"b4b9d661d5235753b4827c61b9b3dd96","fileName":"brokenFoobars.png","fileType":"image\/png",
"description":"The foo bars above the oscillating wingo are borked","purposeId":2,"purpose":"Vendor Invoice",
"created":1327082916,"updated": 1327082916,"entity":{"uri":"https:\/\/api.servicetrade.com\/api\/job\/41","id":41,"type":3},
"creator":{"id": 6,"uri": "https:\/\/api.servicetrade.com\/api\/user\/6","name": "Joe User"}}});</script></body>
</html>
Update an attachment (can use POST or PUT)
POST /attachment/10
{"description":"Foo bars above the Qux Capacitor", "meta":{"author":"Arthur","discovered":1327081621}}
200
{
"data": {
"uri": "https://api.servicetrade.com/api/attachment/10",
"id": 10,
"contentUrl": "https://s3.amazonaws.com/snaap-attachments/10_b4b9d661d5235753b4827c61b9b3dd96.png",
"checksum": "b4b9d661d5235753b4827c61b9b3dd96",
"meta": {
"author":"Arthur",
"discovered":1327081621
},
"fileName": "brokenFoobars.png",
"fileType": "image/png",
"description": "Foo bars above the Qux Capacitor",
"purposeId": 3,
"purpose": "Job Picture",
"visibility": ["public"],
"created": 1327082916,
"updated": 1327082916,
"entity": {
"uri": "https://api.servicetrade.com/api/job/41",
"id": 41,
"type": 3
},
"creator": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User"
}
}
}
Update a user avatar, cropping to a smaller area
PUT /attachment/10
{"meta": {"bounds": {"topLeft":[86, 38], "topRight":[372, 38], "bottomRight":[86, 324], "bottomLeft":[372, 324]}}}
200
{
"data": {
"uri": "https://api.servicetrade.com/api/attachment/10",
"id": 10,
"contentUrl": "https://s3.amazonaws.com/snaap-attachments/10_b4b9d661d5235753b4827c61b9b3dd96.png",
"checksum": "b4b9d661d5235753b4827c61b9b3dd96",
"meta": {
"bounds": {
"topLeft": [5, 5],
"topRight": [372, 38],
"bottomLeft": [86, 324],
"bottomRight": [372, 324]
},
"small": "https://s3.amazonaws.com/snaap-attachments/10_f8afb9b11d8b9bd795e1a01774cfe6be.png",
"medium": "https://s3.amazonaws.com/snaap-attachments/10_62aca89a93a4974f10ef0297c738bef6.png",
"large": "https://s3.amazonaws.com/snaap-attachments/10_8bb04ca9bbb37c75e519d27eddc335df.png"
},
"fileName": "JoesProfile.png",
"fileType": "image/png",
"purposeId": 8,
"visibility": ["public"],
"purpose": "Avatar",
"created": 1327082916,
"updated": 1327082916,
"entity": {
"uri": "https://api.servicetrade.com/api/user/6",
"id": 6,
"type": 4
},
"creator": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User"
}
}
}
Retrieve thumbnail for attachment 10, not a user avatar
GET /attachment/10/thumbnail
200
{
"data": {
"medium": "https://s3.amazonaws.com/snaap-attachments/50_be71c5e25f70d48dd5002d7ac14a6078.png"
}
}
Retrieve thumbnail for attachment 10, user avatar
GET /attachment/10/thumbnail
200
{
"data": {
"small": "https://s3.amazonaws.com/snaap-attachments/50_be71c5e25f70d48dd5002d7ac14a6078.png",
"medium": "https://s3.amazonaws.com/snaap-attachments/58_260ec6ce5dd73740ced00e58f26745c6.png",
"large": "https://s3.amazonaws.com/snaap-attachments/53_ab99873453ab878cc87769874424ee2a.png"
}
}
Return to Top
Authentication
The authentication resource is used to initialize a session. It creates a session token that must be sent along with any request to a protected resource.
The API uses HTTP cookies to maintain an authenticated session. The first time a call to the authentication resource occurs, the API will send back a session id that the HTTP client should send back as a cookie on each subsequent request. If the cookie is not sent on a request to a resource that requires an authenticated session, the request will fail. There is a soft limit of 100 open sessions per user at any given time, and a hard limit of 200. Once you exceed 200, the oldest sessions will be cleaned up to get you back to the soft limit (100).
- Resource URL: /auth
- Available Verbs: GET, POST, DELETE
- Authentication Required: no
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/auth |
200 |
|
GET |
/auth |
404 |
no active login session found |
POST |
/auth |
200 |
|
POST |
/auth |
400 |
username and/or password not given |
POST |
/auth |
403 |
username/password mismatch |
POST |
/auth/foo |
405 |
not allowed |
PUT |
/auth |
405 |
not allowed |
DELETE |
/auth |
204 |
session closed |
DELETE |
/auth |
404 |
no active login session found |
Returned Elements
Name |
Type |
Value |
authenticated |
boolean |
whether the authentication was successful |
eulaNeeded |
boolean |
whether the user needs to accepted the most recent EULA |
authToken |
string |
authentication token; also sent as a cookie in an HTTP header |
user |
User |
|
user.id |
integer |
user id |
user.uri |
string |
resource identifier of the user |
user.email |
string |
|
user.avatar |
array (objects) |
user avatar URIs |
user.firstName |
string |
|
user.lastName |
string |
|
user.username |
string |
|
user.phone |
string |
|
user.isTech |
boolean |
|
user.isHelper |
boolean |
|
user.company |
Company |
Company the user works for |
user.account |
Account |
|
user.serviceLines |
array (Service Line) |
Service lines that the user works on |
Authentication request and successful response
POST /auth
{"username":"joeuser","password":"joepassword"}
200
{
"data": {
"authenticated": true,
"eulaNeeded": true,
"authToken": "l27jeieniupcco67mh8emet201",
"user": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Art Bernard",
"status": "active",
"firstName": "Art",
"lastName": "Bernard",
"username": "abernard",
"email": "art@example.com",
"phone": "9197063119",
"isTech": false,
"isHelper": true,
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"company": {
"id": 321,
"uri": "https://api.servicetrade.com/api/company/321",
"name": "Fire Inspection Pros, Inc."
},
"account": {
"id": 567,
"name": "Fire Inspection Pros, Inc."
},
"serviceLines": []
}
}
}
Authentication failure
POST /auth
{"username":"joeuser","password":"badpassword"}
403
{
"messages": {
"error": [
"Invalid credentials provided"
]
},
"data": {
"authenticated": false,
"eulaNeeded": true,
"authToken": "l27jeieniupcco67mh8emet201",
"user": null
}
}
Retrieveing authentication information for the currently logged in user
GET /auth
200
{
"data": {
"authenticated": true,
"eulaNeeded": false,
"authToken": "l27jeieniupcco67mh8emet201",
"user": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Art Bernard",
"status": "active",
"firstName": "Art",
"lastName": "Bernard",
"username": "abernard",
"email": "art@example.com",
"phone": "9197063119",
"isTech": false,
"isHelper": true,
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"company": {
"id": 321,
"uri": "https://api.servicetrade.com/api/company/321",
"name": "Fire Inspection Pros, Inc."
},
"account": {
"id": 567,
"name": "Fire Inspection Pros, Inc."
},
"serviceLines": []
}
}
}
No currently active session
GET /auth
404
{
"messages": {
"error": [
"No active session found for given auth token"
]
},
"data": {
"authenticated": false
"eulaNeeded": true,
"authToken": "l27jeieniupcco67mh8emet201",
"user": null
}
}
Return to Top
Brand
The brand resource is used to retrieve the list of brands for a company or detailed information about a single brand.
- Resource URL: /company/[companyId]/brand/[brandId]
- Available Verbs: GET, POST, PUT
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/company/123/brand |
200 |
|
GET |
/company/123/brand/456 |
200 |
|
GET |
/company/123/brand/456 |
404 |
brand or company not found |
POST |
/company/123/brand |
200 |
brand created |
PUT |
/company/123/brand/456 |
200 |
|
PUT |
/company/123/brand/456 |
404 |
brand or company not found |
DELETE |
/company/123/brand |
405 |
not allowed |
Query Params
Name |
Type |
Value |
name |
string |
returns only brands whose name includes this string (case insensitive) |
Parameters for POST/PUT
Name |
Type |
Required |
Value |
name |
string |
yes |
name identifier of the brand |
displayName |
string |
no |
display name of the brand |
logoId |
integer |
no |
logo id for brand or null to clear |
webSite |
string |
no |
web site of the brand |
details |
string |
no |
details of the brand |
Returned Elements
Name |
Type |
Value |
brands |
array (Brand) |
list of brand objects |
name |
string |
name of brand |
displayName |
string |
display name of brand |
company |
Company |
id of the company to which this brand belongs |
logo |
Attachment |
logo attachment |
webSite |
string |
web site of the brand |
details |
string |
details of the brand |
Retrieve all brands that match a given name
GET /company/123/brand?name=sea
200
{
"data": {
"totalPages": 1,
"page": 1,
"brands": [
{
"id": 9,
"uri": "https://api.servicetrade.com/api/company/123/brand/6",
"name": "Seafood Et Al"
"displayName": "Seafood Et Al"
"company": {
"id": 123,
"uri": "https://api.servicetrade.com/api/company/123",
"name": "GoodFud International"
},
"logo": null,
"webSite": null,
"details": null
},
{
"id": 10,
"uri": "https://api.servicetrade.com/api/company/123/brand/10",
"name": "Fruit of the Sea",
"displayName": "Fruit of the Sea",
"company": {
"id": 123,
"uri": "https://api.servicetrade.com/api/company/123",
"name": "GoodFud International"
},
"logo": null,
"webSite": null,
"details": null
}
]
}
}
No brand matches found
GET /company/123/brand?name=ygiuygiug
200
{
"data": {
"totalPages": 1,
"page": 1,
"brands": []
}
}
Retrieve information for a single brand
GET /company/123/brand/9
200
{
"data": {
"id": 9,
"uri": "https://api.servicetrade.com/api/company/123/brand/6",
"name": "Seafood Et Al",
"displayName": "Seafood Et Al",
"company": {
"id": 123,
"uri": "https://api.servicetrade.com/api/company/123",
"name": "GoodFud International"
},
"logo": null,
"webSite": null,
"details": null
}
}
Retrieve information for a brand which does not exist
GET /company/123/brand/987
404
Create a new brand
POST /company/123/brand
{"name":"Brand X"}
200
{
"data": {
"id": 32,
"uri": "https://api.servicetrade.com/api/company/123/brand/32",
"name": "Brand X",
"displayName": "Brand X",
"company": {
"id": 123,
"uri": "https://api.servicetrade.com/api/company/123",
"name": "GoodFud International"
},
"logo": null,
"webSite": null,
"details": null
}
}
Return to Top
Budget
The budget resource is used to retrieve the list of budgets for a job or detailed information about a single budget.
- Resource URL: /budget/[budgetId]
- Available Verbs: GET, POST, PUT
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/budget |
405 |
unconditional index not allowed, provide jobId or referenceNumber |
GET |
/budget?jobId=123 |
200 |
|
GET |
/budget?jobId=123 |
403 |
no permission |
GET |
/budget?referenceNumber=123 |
200 |
|
GET |
/budget?referenceNumber=123 |
403 |
no permission |
GET |
/budget/123 |
200 |
|
GET |
/budget/123 |
404 |
budget not found |
GET |
/budget/123 |
403 |
no permission |
POST |
/budget |
200 |
budget created |
POST |
/budget |
409 |
attempted to create a new budget for a job with a non-voided budget |
POST |
/budget |
403 |
no permission |
POST |
/budget |
400 |
invalid post data |
POST |
/budget/123/revise |
200 |
revise a budget |
POST |
/budget/123/revise |
403 |
no permission |
POST |
/budget/123/revise |
404 |
budget not found |
POST |
/budget/123/revise |
409 |
budget is not in a revisible state |
POST |
/budget/123/revise?changeOrderId=123 |
200 |
|
POST |
/budget/123/revise?changeOrderId=123 |
409 |
budget is not in a revisible state, or change order not in approved status |
POST |
/budget/123/revise?changeOrderId=123 |
400 |
change order does not apply to this budget |
POST |
/budget/123/revise?changeOrderId=123 |
403 |
no permission |
POST |
/budget/123/revise?changeOrderId=123 |
404 |
change order or budget not found |
PUT |
/budget/123 |
200 |
|
PUT |
/budget/123 |
404 |
budget not found |
PUT |
/budget/123 |
409 |
attempted to unvoid a budget for a job with a non-voided budget |
PUT |
/budget/123 |
403 |
no permission |
PUT |
/budget/123 |
400 |
invalid PUT data |
DELETE |
/budget/123 |
405 |
not allowed |
Query Params
Name |
Type |
Value |
jobId |
integer |
returns all budgets for the job represented by jobId |
referenceNumber |
string |
returns all budgets versions for the job budget of referenceNumber |
status |
string |
returns all budgets for given comma delimited list of statuses (any combination of locked, unlocked and void) |
isCurrent |
boolean |
if set to true only returns current active budget versions. isCurrent=false returns only non-active budget versions. |
isLatest |
boolean |
requires jobId to also be set. returns the single budget that is the current revision of the active budget or if there is no active budget the most recent voided budget (or null if neither exists). isLatest=false is ignored. |
Note: to query the budget endpoint you must provide at least one parameter.
Parameters for POST/PUT
Name |
Type |
Required on POST |
Allowed on PUT? |
Value |
status |
string |
yes |
yes |
one of "locked", "unlocked", or "void". "void" is only allowed on PUT, not POST |
type |
string |
yes |
no |
one of "high_level" or "granular" |
parentId |
integer |
no |
no |
budget id for the budget version this revises on post, or null for a new baseline |
jobId |
integer |
yes |
no |
job id of the job the budget is for |
ownerId |
integer |
no |
yes |
owner id for the budget |
Note: total is not explicitly set but calculated from a high_level type budget's BudgetCategories or a granular budget's BudgetItems
Parameters for revise
Name |
Type |
Required |
Value |
changeOrderId |
integer |
no |
If this is provided, the change order changes will be applied to the revision |
Returned Elements
Name |
Type |
Value |
id |
integer |
item id |
uri |
string |
resource identifier for the given item |
job |
Job |
job that this budget is for |
status |
string |
status of the budget |
type |
string |
type of the budget |
baseline |
Budget |
baseline for which this budget is a revision, or null |
parent |
Budget |
previous version of this budget, or null |
referenceNumber |
string |
reference number that this budget line is known by |
sequence |
integer |
0 for baseline, otherwise the revision number of the budget |
total |
double |
cost total for this budget |
totalPrice |
double |
price total for this budget. null signifies no price information. |
lastLock |
integer |
if this budget is locked, the day and time for when it happened as a UNIX timestamp |
lastLockUser |
User |
if this budget is locked, the user who did it |
isCurrent |
boolean |
is this the most current budget version for this budget line? |
categories |
array BudgetCategory |
budget categories of the budget |
lineItems |
array BudgetLineItem |
budget line items of the budget |
owner |
User |
the budget's owner |
Retrieve all budgets for a job
GET /budget?jobId=68
{
"data": {
"totalPages": 1,
"page": 1,
"budgets": [
{
"id": 67,
"uri": "https://api.servicetrade.com/api/budget/67",
"referenceNumber": "67",
"sequence": 0,
"status": "locked",
"type": high_level,
"job": {
"id": 182,
"uri": "https://api.servicetrade.com/api/job/182",
"number": 10000059,
"name": "Job #10000059",
"type": "repair"
},
"total": 100.00,
"baseline": null,
"parent": null,
"lastLock": 1639498693,
"lastLockUser": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"email": "joe@testcompany.com",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
}
"isCurrent": 1,
"categories": [],
"lineItems": [],
"owner": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"email": "joe@testcompany.com",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
}
},
{
"id": 68,
"uri": "https://api.servicetrade.com/api/budget/68",
"referenceNumber": "67",
"sequence": 1,
"status": "unlocked",
"type": high_level,
"job": {
"id": 182,
"uri": "https://api.servicetrade.com/api/job/182",
"number": 10000059,
"name": "Job #10000059",
"type": "repair"
},
"total": 123.45,
"baseline": {
"id": 67,
"uri": "https://api.servicetrade.com/api/budget/67",
"referenceNumber": 67,
"sequence": 0,
"status": "locked",
"type": "high_level"
},
"parent": {
"id": 67,
"uri": "https://api.servicetrade.com/api/budget/67",
"referenceNumber": 67,
"sequence": 0,
"status": "locked",
"type": "high_level"
},
"lastLock": null,
"lastLockUser": null,
"isCurrent": 1,
"categories": [],
"lineItems": [],
"owner": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"email": "joe@testcompany.com",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
}
}
]
}
}
Retrieve all budgets for a reference number
GET /budget?referenceNumber=68
{
"data": {
"totalPages": 1,
"page": 1,
"budgets": [
{
"id": 67,
"uri": "https://api.servicetrade.com/api/budget/67",
"referenceNumber": "67",
"sequence": 0,
"status": "locked",
"type": high_level,
"job": {
"id": 182,
"uri": "https://api.servicetrade.com/api/job/182",
"number": 10000059,
"name": "Job #10000059",
"type": "repair"
},
"total": 100.00,
"baseline": null,
"parent": null,
"lastLock": 1639498693,
"lastLockUser": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"email": "joe@testcompany.com",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
}
"isCurrent": 1,
"categories": [],
"lineItems": [],
"owner": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"email": "joe@testcompany.com",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
}
},
{
"id": 68,
"uri": "https://api.servicetrade.com/api/budget/68",
"referenceNumber": "67",
"sequence": 1,
"status": "unlocked",
"type": high_level,
"job": {
"id": 182,
"uri": "https://api.servicetrade.com/api/job/182",
"number": 10000059,
"name": "Job #10000059",
"type": "repair"
},
"total": 123.45,
"baseline": {
"id": 67,
"uri": "https://api.servicetrade.com/api/budget/67",
"referenceNumber": 67,
"sequence": 0,
"status": "locked",
"type": "high_level"
},
"parent": {
"id": 67,
"uri": "https://api.servicetrade.com/api/budget/67",
"referenceNumber": 67,
"sequence": 0,
"status": "locked",
"type": "high_level"
},
"lastLock": null,
"lastLockUser": null,
"isCurrent": 1,
"categories": [],
"lineItems": [],
"owner": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"email": "joe@testcompany.com",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
}
}
]
}
}
Retrieve a budget by id
GET /budget/68
{
"data": {
"id": 68,
"uri": "https://api.servicetrade.com/api/budget/68",
"referenceNumber": "67",
"sequence": 1,
"status": "unlocked",
"type": high_level,
"job": {
"id": 182,
"uri": "https://api.servicetrade.com/api/job/182",
"number": 10000059,
"name": "Job #10000059",
"type": "repair"
},
"total": 123.45,
"baseline": {
"id": 67,
"uri": "https://api.servicetrade.com/api/budget/67",
"referenceNumber": 67,
"sequence": 0,
"status": "locked",
"type": "high_level"
},
"parent": {
"id": 67,
"uri": "https://api.servicetrade.com/api/budget/67",
"referenceNumber": 67,
"sequence": 0,
"status": "locked",
"type": "high_level"
},
"lastLock": null,
"lastLockUser": null,
"isCurrent": 1,
"categories": [],
"lineItems": [],
"owner": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"email": "joe@testcompany.com",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
}
}
}
Create a new budget
POST /budget
{"jobId": 182, "status": "unlocked", "type": "high_level", "parentId": 67}
200
{
"data": {
"id": 68,
"uri": "https://api.servicetrade.com/api/budget/68",
"referenceNumber": "67",
"sequence": 1,
"status": "unlocked",
"type": high_level,
"job": {
"id": 182,
"uri": "https://api.servicetrade.com/api/job/182",
"number": 10000059,
"name": "Job #10000059",
"type": "repair"
},
"total": 0,
"baseline": {
"id": 67,
"uri": "https://api.servicetrade.com/api/budget/67",
"referenceNumber": 67,
"sequence": 0,
"status": "locked",
"type": "high_level"
},
"parent": {
"id": 67,
"uri": "https://api.servicetrade.com/api/budget/67",
"referenceNumber": 67,
"sequence": 0,
"status": "locked",
"type": "high_level"
},
"lastLock": null,
"lastLockUser": null,
"isCurrent": 1,
"categories": [],
"lineItems": [],
"owner": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"email": "joe@testcompany.com",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
}
}
}
Modify an existing budget
PUT /budget/68
{"status": "void"}
200
{
"data": {
"id": 68,
"uri": "https://api.servicetrade.com/api/budget/68",
"referenceNumber": "67",
"sequence": 1,
"status": "void",
"type": high_level,
"job": {
"id": 182,
"uri": "https://api.servicetrade.com/api/job/182",
"number": 10000059,
"name": "Job #10000059",
"type": "repair"
},
"total": 0,
"baseline": {
"id": 67,
"uri": "https://api.servicetrade.com/api/budget/67",
"referenceNumber": 67,
"sequence": 0,
"status": "void",
"type": "high_level"
},
"parent": {
"id": 67,
"uri": "https://api.servicetrade.com/api/budget/67",
"referenceNumber": 67,
"sequence": 0,
"status": "void",
"type": "high_level"
},
"lastLock": null,
"lastLockUser": null,
"isCurrent": 1,
"categories": [],
"lineItems": [],
"owner": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"email": "joe@testcompany.com",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
}
}
}
Revise an existing budget by creating an identical revision
POST /budget/67/revise
200
{
"data": {
"id": 68,
"uri": "https://api.servicetrade.com/api/budget/68",
"referenceNumber": "67",
"sequence": 1,
"status": "locked",
"type": high_level,
"job": {
"id": 182,
"uri": "https://api.servicetrade.com/api/job/182",
"number": 10000059,
"name": "Job #10000059",
"type": "repair"
},
"total": 0,
"baseline": {
"id": 67,
"uri": "https://api.servicetrade.com/api/budget/67",
"referenceNumber": 67,
"sequence": 0,
"status": "void",
"type": "high_level"
},
"parent": {
"id": 67,
"uri": "https://api.servicetrade.com/api/budget/67",
"referenceNumber": 67,
"sequence": 0,
"status": "void",
"type": "high_level"
},
"lastLock": null,
"lastLockUser": null,
"isCurrent": 1,
"categories": [],
"lineItems": [],
"owner": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"email": "joe@testcompany.com",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
}
}
}
Modify an existing budget by creating a revision from a change order
POST /budget/67/revise?changeOrderId=3942
200
{
"data": {
"id": 68,
"uri": "https://api.servicetrade.com/api/budget/68",
"referenceNumber": "67",
"sequence": 1,
"status": "locked",
"type": high_level,
"job": {
"id": 182,
"uri": "https://api.servicetrade.com/api/job/182",
"number": 10000059,
"name": "Job #10000059",
"type": "repair"
},
"total": 0,
"baseline": {
"id": 67,
"uri": "https://api.servicetrade.com/api/budget/67",
"referenceNumber": 67,
"sequence": 0,
"status": "void",
"type": "high_level"
},
"parent": {
"id": 67,
"uri": "https://api.servicetrade.com/api/budget/67",
"referenceNumber": 67,
"sequence": 0,
"status": "void",
"type": "high_level"
},
"lastLock": null,
"lastLockUser": null,
"isCurrent": 1,
"categories": [],
"lineItems": [],
"owner": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"email": "joe@testcompany.com",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
}
}
}
Return to Top
Budget Category
The budget category resource is used to retrieve a list of budget categories for a budget.
- Resource URL: /budgetcategory/[budgetCategoryId]
- Available Verbs: GET, POST, PUT, DELETE
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/budgetcategory |
405 |
unconditional index not allowed, provide budgetId or referenceNumber |
GET |
/budgetcategory?budgetId=123 |
200 |
|
GET |
/budgetcategory?referenceNumber=123 |
200 |
|
GET |
/budgetcategory/123 |
200 |
|
GET |
/budgetcategory/123 |
404 |
budget category not found |
GET |
/budget/555/category/123 |
200 |
nested route request |
POST |
/budgetcategory |
200 |
budget category created |
POST |
/budgetcategory |
403 |
no permission |
PUT |
/budgetcategory/123 |
200 |
|
PUT |
/budget/555/category/123 |
200 |
nested route request |
PUT |
/budgetcategory/123 |
404 |
budget category not found |
PUT |
/budgetcategory/123 |
403 |
no permission |
DELETE |
/budgetcategory/123 |
204 |
|
DELETE |
/budgetcategory/123 |
403 |
no permission |
Query Params
Name |
Type |
Value |
budgetId |
integer |
returns all budget categories for the budget represented by budgetId |
referenceNumber |
string |
returns all budget categories with the referenceNumber |
Note: to query the budget category endpoint you must provide at least one parameter.
Parameters for POST/PUT
Name |
Type |
Required on POST |
Allowed on PUT? |
Value |
budgetId |
integer |
yes |
no |
budget id for the budget this belongs to |
libItemType |
string |
yes |
yes |
category type corresponding to a lib item type, one of: part, material, labor, equipment, inspection, service, subcontractor, fee, general_conditions, or other |
serviceRequestId |
integer |
no |
yes |
service request id for the associated service, or null for none |
cost |
float |
yes |
yes |
cost of the category |
price |
float |
no |
yes |
optional price estimate for this category, null indicates no price estimate and is the default |
quantity |
float |
no |
yes |
optional hours estimate for a type 'labor' category, may not be non-null on any other type of category |
orderIndex |
integer |
no |
yes |
indicates order of display with other categories on the budget |
referenceNumber |
integer |
no |
no |
Desired reference number for the category. If not provided one will be generated. This is for associating the conterpart category on other versions of this budget. |
Returned Elements
Name |
Type |
Value |
id |
integer |
budget category id |
uri |
string |
resource identifier for the given budget category |
budget |
Budget |
budget that this category belongs to |
libItemType |
string |
category type (always a lib item type) |
serviceRequest |
Service Request |
associated service request or null |
cost |
float |
cost for this category |
price |
float |
price estimate for this category |
quantity |
float |
hours estimate for a type 'labor' category or null |
orderIndex |
integer |
indicates order of display with other categories on the budget |
referenceNumber |
string |
identifier to associate counterpart category with thw corresponding categories on other budget versions |
Retrieve all budget categories for a budget
GET /budgetcategory?budgetId=871
{
"data": {
"totalPages": 1
"page": 1
"budgetCategories": [
{
"id": 470,
"uri": "https://api.servicetrade.com/api/budgetcategory/470",
"referenceNumber": "470",
"libItemType": "labor",
"cost": 241.11,
"price": null,
"quantity": null,
"orderIndex": 1,
"budget": {
"id": 871,
"uri": "https://api.servicetrade.com/api/budget/871",
"referenceNumber": "871",
"sequence": 0,
"status": "unlocked",
"type": "high_level"
},
"serviceRequest": null
},
{
"id": 471,
"uri": "https://api.servicetrade.com/api/budgetcategory/471",
"referenceNumber": "471",
"libItemType": "part",
"cost": 521.51,
"price": null,
"quantity": null,
"orderIndex": 2,
"budget": {
"id": 871,
"uri": "https://api.servicetrade.com/api/budget/871",
"referenceNumber": "871",
"sequence": 0,
"status": "unlocked",
"type": "high_level"
},
"serviceRequest": {
"id": 470,
"uri": "https://api.servicetrade.com/api/servicerequest/470",
"description": "Fire Alarm Installation"
}
}
]
}
}
Retrieve all budget categories for a reference number
GET /budgetcategory?referenceNumber=471
{
"data": {
"totalPages": 1
"page": 1
"budgetCategories": [
{
"id": 555,
"uri": "https://api.servicetrade.com/api/budgetcategory/555",
"referenceNumber": "555",
"libItemType": "part",
"cost": 631.51,
"price": null,
"quantity": null,
"orderIndex": 2,
"budget": {
"id": 979,
"uri": "https://api.servicetrade.com/api/budget/979",
"referenceNumber": "871",
"sequence": 1,
"status": "unlocked",
"type": "high_level"
},
"serviceRequest": {
"id": 470,
"uri": "https://api.servicetrade.com/api/servicerequest/470",
"description": "Fire Alarm Installation"
}
},
{
"id": 471,
"uri": "https://api.servicetrade.com/api/budgetcategory/471",
"referenceNumber": "471",
"libItemType": "part",
"cost": 521.51,
"price": null,
"quantity": null,
"orderIndex": 2,
"budget": {
"id": 871,
"uri": "https://api.servicetrade.com/api/budget/871",
"referenceNumber": "871",
"sequence": 0,
"status": "locked",
"type": "high_level"
},
"serviceRequest": {
"id": 470,
"uri": "https://api.servicetrade.com/api/servicerequest/470",
"description": "Fire Alarm Installation"
}
}
]
}
}
Retrieve a budget by id
GET /budgetcategory/471
{
"id": 471,
"uri": "https://api.servicetrade.com/api/budgetcategory/471",
"referenceNumber": "471",
"libItemType": "part",
"cost": 521.51,
"price": null,
"quantity": null,
"orderIndex": 2,
"budget": {
"id": 871,
"uri": "https://api.servicetrade.com/api/budget/871",
"referenceNumber": "871",
"sequence": 0,
"status": "unlocked",
"type": "high_level"
},
"serviceRequest": {
"id": 470,
"uri": "https://api.servicetrade.com/api/servicerequest/470",
"description": "Fire Alarm Installation"
}
}
Create a new budget category
POST /budgetcategory
{"budgetId" => 871, "libItemType": "fee", "cost": 111.02, "orderIndex": 3, "referenceNumber": 500}
200
{
"id": 481,
"uri": "https://api.servicetrade.com/api/budgetcategory/481",
"referenceNumber": "500",
"libItemType": "fee",
"cost": 111.02,
"price": null,
"quantity": null,
"orderIndex": 3,
"budget": {
"id": 871,
"uri": "https://api.servicetrade.com/api/budget/871",
"referenceNumber": "871",
"sequence": 0,
"status": "unlocked",
"type": "high_level"
},
"serviceRequest": null
}
Modify an existing budget category
PUT /budgetcategory/481
{"libItemType": "material", "cost": 100}
200
{
"id": 481,
"uri": "https://api.servicetrade.com/api/budgetcategory/481",
"referenceNumber": "500",
"libItemType": "material",
"cost": 100,
"price": null,
"quantity": null,
"orderIndex": 3,
"budget": {
"id": 871,
"uri": "https://api.servicetrade.com/api/budget/871",
"referenceNumber": "871",
"sequence": 0,
"status": "unlocked",
"type": "high_level"
},
"serviceRequest": null
}
Delete a budget category
DELETE /budgetcategory/481
204
Return to Top
Budget Line Item
The budget line item resource is used to retrieve a list of budget line items for a budget.
- Resource URL: /budgetlineitem/[budgetLineItemId]
- Available Verbs: GET, POST, PUT, DELETE
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/budgetlineitem |
405 |
unconditional index not allowed, provide budgetId or referenceNumber |
GET |
/budgetlineitem?budgetId=123 |
200 |
|
GET |
/budgetlineitem?referenceNumber=123 |
200 |
|
GET |
/budgetlineitem/123 |
200 |
|
GET |
/budgetlineitem/123 |
404 |
budget line item not found |
GET |
/budget/555/lineitem/123 |
200 |
nested route request |
POST |
/budgetlineitem |
200 |
budget line item created |
POST |
/budgetlineitem |
403 |
no permission |
POST |
/budgetlineitem/123/copytojob |
200 |
copies budget line item to job item and assigns to itself |
POST |
/budgetlineitem/123/copytojob |
409 |
budget line item already has a job item or budget line item has a voided budget |
PUT |
/budgetlineitem/123 |
200 |
|
PUT |
/budget/555/lineitem/123 |
200 |
nested route request |
PUT |
/budgetlineitem/123 |
404 |
budget line item not found |
PUT |
/budgetlineitem/123 |
403 |
no permission |
DELETE |
/budgetlineitem/123 |
204 |
|
DELETE |
/budgetlineitem/123 |
403 |
no permission |
Query Params
Name |
Type |
Value |
budgetId |
integer |
returns all budgets line items for the budget represented by budgetId |
referenceNumber |
string |
returns all budget categories with the referenceNumber |
Note: to query the budget line item endpoint you must provide at least one parameter.
Parameters for POST/PUT
Name |
Type |
Required on POST |
Allowed on PUT? |
Value |
budgetId |
integer |
yes |
no |
budget id for the budget this belongs to |
jobItemId |
integer |
no |
yes |
id of the jobItem associated with the budget line item if there is one |
libItemId |
integer |
no |
yes |
id of the libItem for the budget line item, absense of this means you are creating an "other" item of the service line indicated by serviceLineId |
libItemType |
string |
no |
yes |
category type or line item type corresponding to a lib item type, one of: part, material, labor, equipment, inspection, service, subcontractor, fee, general_conditions, or other. This defaults to the lib item's libItemType but can be set to a different value. |
name |
string |
yes |
yes |
display name for the associated (actual or planned) job item. Required on POST. It can be set to match the lib item name or something different. |
serviceLineId |
integer |
see note |
yes |
defaults to service line of the lib item if it has one, but it can be set to a different value. Required in the case of a lib item without an assigned service line. |
serviceRequestId |
integer |
no |
yes |
service request id for the associated service, or null for none |
cost |
float |
yes |
yes |
per each cost of the line item |
price |
float |
no |
yes |
per each price of the line item. optional and nullable. |
quantity |
float |
yes |
yes |
quantity of this item budgeted |
orderIndex |
integer |
no |
yes |
indicates order of display with other categories on the budget |
referenceNumber |
integer |
no |
no |
Desired reference number for the line item. If not provided one will be generated. This is for associating the conterpart line item on other versions of this budget. |
Returned Elements
Name |
Type |
Value |
id |
integer |
item id |
uri |
string |
resource identifier for the given budget line item |
budget |
Budget |
budget that this line item belongs to |
jobItem |
Job Item |
job item reflecting this budget line item |
libItem |
Lib Item |
lib item budgeted |
libItemType |
string |
lib item type (budget category) to which this line item applies |
name |
string |
display name for the associated (actual or planned) job item |
serviceLine |
Service Line |
service line assigned to this line item |
serviceRequest |
Service Request |
associated service request or null |
cost |
float |
per each cost for this line item |
price |
float |
per each price for this line item. null signifies no price information. |
quantity |
float |
quantity for this line item |
total |
float |
total cost for this line item |
totalPrice |
float |
total price for this line item. null signifies no price information. |
orderIndex |
integer |
indicates order of display with other categories on the budget |
referenceNumber |
string |
identifier to associate counterpart line item with thw corresponding categories on other budget versions |
Parameters for copytojob
NONE
Returned Elements
returns jobItem elements similar to jobItem API calls
Name |
Type |
Value |
id |
integer |
job item id |
name |
string |
display name of the job item |
libItem |
Libitem |
libItem of the job item |
serviceLine |
Service Line |
serviceLine of the job item |
quantity |
float |
quantity of the job item |
cost |
float |
cost of this item, else null |
job |
Job |
the job the item belongs to |
quoteItem |
Quoteitem |
quoteItem that resulted in this job item |
serviceRequest |
:service Request |
serviceRequest that this item is to address |
visibility |
array(string) |
visibility granted to these types of viewers outside of the account; combination of: public, customer, subcontractor. "public" indicates global visibility and overrides the other values. |
usedOn |
integer |
Unix timestamp for when the item was used |
created |
integer |
Unix timestamp of this record's creation time |
updated |
integer |
Unix timestamp of when this record was last updated |
source |
object |
used to indicate where this job item came from |
orderIndex |
integer |
The position the item is displayed in on the job page, with 0 being closest to the top |
externalIds |
object |
a key/value object of external system ids, only returned if account has external integrations defined |
Retrieve all budget categories for a budget
GET /budgetlineitem?budgetId=55
{
"data": {
"totalPages": 1
"page": 1
"budgetCategories": [
{
"id": 1554,
"uri": "https://api.servicetrade.com/api/budgetlineitem/1554",
"referenceNumber": 110,
"name": "Labor (AL)",
"libItemType": "labor",
"cost": 100,
"quantity": 2.5,
"total": 250,
"price": null,
"totalPrice": null,
"orderIndex": 1,
"budget":
{
"id": 55,
"uri": "https://api.servicetrade.com/api/budget/55",
"referenceNumber": 55,
"sequence": 0,
"status": "unlocked",
"type": "granular"
},
"jobItem": null,
"serviceRequest":
{
"id": 138,
"uri": "https://api.servicetrade.com/api/servicerequest/138",
"description": "Install new smoke alarms"
},
"serviceLine":
{
"id": 14,
"name": "Alarm",
"trade": "Fire Protection",
"abbr": "AL",
"icon": "http://vvm1/image/icons/service_lines/32/AL.png"
},
"libItem":
{
"id": 2700,
"uri": "https://api.servicetrade.com/api/libitem/2700",
"name": "Labor (AL)",
"type": "labor",
"code": null,
"isGeneric": false,
"externalIds":
{
}
}
},
{
"id": 1555,
"uri": "https://api.servicetrade.com/api/budgetlineitem/1555",
"referenceNumber": 111,
"name": "Smoke Alarm",
"libItemType": "part",
"cost": 100,
"quantity": 2,
"total": 200,
"price": null,
"totalPrice": null,
"orderIndex": 2,
"budget":
{
"id": 55,
"uri": "https://api.servicetrade.com/api/budget/55",
"referenceNumber": 55,
"sequence": 0,
"status": "unlocked",
"type": "granular"
},
"jobItem": null,
"serviceRequest":
{
"id": 138,
"uri": "https://api.servicetrade.com/api/servicerequest/138",
"description": "Install new smoke alarms"
},
"serviceLine":
{
"id": 14,
"name": "Alarm",
"trade": "Fire Protection",
"abbr": "AL",
"icon": "http://vvm1/image/icons/service_lines/32/AL.png"
},
"libItem":
{
"id": 2710,
"uri": "https://api.servicetrade.com/api/libitem/2710",
"name": "Smoke Alarm",
"type": "part",
"code": null,
"isGeneric": false,
"externalIds":
{
}
}
}
]
}
}
Retrieve all budget categories for a reference number
GET /budgetlineitem?referenceNumber=111
{
"data": {
"totalPages": 1
"page": 1
"budgetCategories": [
{
"id": 1555,
"uri": "https://api.servicetrade.com/api/budgetlineitem/1555",
"referenceNumber": 111,
"name": "Smoke Alarm",
"libItemType": "part",
"cost": 100,
"quantity": 2,
"total": 200,
"price": null,
"totalPrice": null,
"orderIndex": 2,
"budget":
{
"id": 55,
"uri": "https://api.servicetrade.com/api/budget/55",
"referenceNumber": 55,
"sequence": 0,
"status": "locked",
"type": "granular"
},
"jobItem": null,
"serviceRequest":
{
"id": 138,
"uri": "https://api.servicetrade.com/api/servicerequest/138",
"description": "Install new smoke alarms"
},
"serviceLine":
{
"id": 14,
"name": "Alarm",
"trade": "Fire Protection",
"abbr": "AL",
"icon": "http://vvm1/image/icons/service_lines/32/AL.png"
},
"libItem":
{
"id": 2710,
"uri": "https://api.servicetrade.com/api/libitem/2710",
"name": "Smoke Alarm",
"type": "part",
"code": null,
"isGeneric": false,
"externalIds":
{
}
}
},
{
"id": 1565,
"uri": "https://api.servicetrade.com/api/budgetlineitem/1565",
"referenceNumber": 111,
"name": "Smoke Alarm",
"libItemType": "part",
"cost": 100,
"quantity": 3,
"total": 300,
"price": null,
"totalPrice": null,
"orderIndex": 2,
"budget":
{
"id": 155,
"uri": "https://api.servicetrade.com/api/budget/155",
"referenceNumber": 55,
"sequence": 1,
"status": "unlocked",
"type": "granular"
},
"serviceRequest":
{
"id": 138,
"uri": "https://api.servicetrade.com/api/servicerequest/138",
"description": "Install new smoke alarms"
},
"serviceLine":
{
"id": 14,
"name": "Alarm",
"trade": "Fire Protection",
"abbr": "AL",
"icon": "http://vvm1/image/icons/service_lines/32/AL.png"
},
"libItem":
{
"id": 2710,
"uri": "https://api.servicetrade.com/api/libitem/2710",
"name": "Smoke Alarm",
"type": "part",
"code": null,
"isGeneric": false,
"externalIds":
{
}
}
}
]
}
}
Retrieve a budget by id
GET /budgetlineitem/1555
{
"id": 1555,
"uri": "https://api.servicetrade.com/api/budgetlineitem/1555",
"referenceNumber": 111,
"name": "Smoke Alarm",
"libItemType": "part",
"cost": 100,
"quantity": 2,
"total": 200,
"price": null,
"totalPrice": null,
"orderIndex": 2,
"budget":
{
"id": 55,
"uri": "https://api.servicetrade.com/api/budget/55",
"referenceNumber": 55,
"sequence": 1,
"status": "unlocked",
"type": "granular"
},
"jobItem": null,
"serviceRequest":
{
"id": 138,
"uri": "https://api.servicetrade.com/api/servicerequest/138",
"description": "Install new smoke alarms"
},
"serviceLine":
{
"id": 14,
"name": "Alarm",
"trade": "Fire Protection",
"abbr": "AL",
"icon": "http://vvm1/image/icons/service_lines/32/AL.png"
},
"libItem":
{
"id": 2710,
"uri": "https://api.servicetrade.com/api/libitem/2710",
"name": "Smoke Alarm",
"type": "part",
"code": null,
"isGeneric": false,
"externalIds":
{
}
}
}
Create a new budget line item
POST /budgetlineitem
{"budgetId" => 55, "name" => "Smoke Alarm", "libItemId": 2710, "cost": 100, "quantity": 2, "orderIndex": 1, "referenceNumber": 111}
GET /budgetlineitem/1555
{
"id": 1555,
"uri": "https://api.servicetrade.com/api/budgetlineitem/1555",
"referenceNumber": 111,
"name": "Smoke Alarm",
"libItemType": "part",
"cost": 100,
"quantity": 2,
"total": 200,
"price": null,
"totalPrice": null,
"orderIndex": 2,
"budget":
{
"id": 55,
"uri": "https://api.servicetrade.com/api/budget/55",
"referenceNumber": 55,
"sequence": 1,
"status": "unlocked",
"type": "granular"
},
"jobItem": null,
"serviceRequest":
{
"id": 138,
"uri": "https://api.servicetrade.com/api/servicerequest/138",
"description": "Install new smoke alarms"
},
"serviceLine":
{
"id": 14,
"name": "Alarm",
"trade": "Fire Protection",
"abbr": "AL",
"icon": "http://vvm1/image/icons/service_lines/32/AL.png"
},
"libItem":
{
"id": 2710,
"uri": "https://api.servicetrade.com/api/libitem/2710",
"name": "Smoke Alarm",
"type": "part",
"code": null,
"isGeneric": false,
"externalIds":
{
}
}
}
Modify an existing budget line item
PUT /budgetlineitem/481
{"name": "Wet Sprinkler", "libItemId": 1444, "serviceLineId": 20, "cost": 150}
GET /budgetlineitem/1555
{
"id": 1555,
"uri": "https://api.servicetrade.com/api/budgetlineitem/1555",
"referenceNumber": 111,
"name": "Wet Sprinkler",
"libItemType": "part",
"cost": 150,
"quantity": 2,
"total": 300,
"price": null,
"totalPrice": null,
"orderIndex": 2,
"budget":
{
"id": 55,
"uri": "https://api.servicetrade.com/api/budget/55",
"referenceNumber": 55,
"sequence": 1,
"status": "unlocked",
"type": "granular"
},
"jobItem": null,
"serviceRequest":
{
"id": 138,
"uri": "https://api.servicetrade.com/api/servicerequest/138",
"description": "Install new smoke alarms"
},
"serviceLine":
{
"id": 20,
"name": "Sprinkler",
"trade": "Fire Protection",
"abbr": "SP",
"icon": "https://vvm1/image/icons/service_lines/32/SP.png"
},
"libItem":
{
"id": 1444,
"uri": "https://api.servicetrade.com/api/libitem/1444",
"name": "Wet Sprinkler",
"type": "part",
"code": null,
"isGeneric": false,
"externalIds":
{
}
}
}
Delete a budget line item
DELETE /budgetlineitem/555
204
Create Job Item, copy BudgetLineItems element to it and add new JobItem to BudgetLineItem (can be used on locked budgets)
POST /budgetlineitem/123/copytojob
{
"data": {
"id": 10,
"name": "3 Tank Suppression System Inspection",
"libItem": {
"id": 477,
"uri": "https://api.servicetrade.com/api/libitem/477",
"name": "3 Tank Suppression System Inspection",
"type": "Inspection",
"code": null
},
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/SUPP.png"
},
"quantity": 1,
"cost": 122,
"job": {
"id": 123,
"uri": "https://api.servicetrade.com/api/job/123",
"number": 10300676,
"name": "Inspection Job #10300676",
"type": "inspection",
"primaryContact": "John Lennon"
},
"quoteItem": {
"id": 877,
"uri": "https://api.servicetrade.com/api/quoteitem/877",
"name": "3 Tank Suppression System Inspection"
},
"serviceRequest": {
"id": 1742,
"uri": "https://api.servicetrade.com/api/servicerequest/1742",
"description": "Semi-Annual Preventative Maintenance"
},
"source": null,
"visibility": ["public"],
"usedOn": 1399994065,
"created": 1399993795,
"updated": 1399994065,
"orderIndex": 3
}
}
Return to Top
Change Order
The change order resource is used to retrieve the list of change orders for a budget or detailed information about a single change order.
- Resource URL: /changeorder/[changeorderId]
- Available Verbs: GET, POST, PUT
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/changeorder |
405 |
unconditional index not allowed, provide budgetId |
GET |
/changeorder?budgetId=123 |
200 |
|
GET |
/changeorder?budgetId=123 |
403 |
no permission |
GET |
/changeorder/123 |
200 |
|
GET |
/changeorder/123 |
404 |
changeorder not found |
GET |
/changeorder/123 |
403 |
no permission |
GET |
/changeorder/123/attachment |
200 |
retrieve list of generic attachments |
GET |
/changeorder/123/attachment/10 |
200 |
retrieve attachment info |
POST |
/changeorder |
400 |
missing, incomplete, or invalid parameters |
POST |
/changeorder?budgetId=123 |
200 |
changeorder created |
POST |
/changeorder?budgetId=123 |
403 |
no permission |
POST |
/changeorder?budgetId=123 |
409 |
attempted to create a new changeorder for a budget that is not locked |
POST |
/changeorder?budgetId=123 |
400 |
invalid post data |
POST |
/changeorder/123/attachment |
200 |
upload an audio or other attachment |
PUT |
/changeorder/123 |
200 |
|
PUT |
/changeorder/123 |
404 |
budget not found |
DELETE |
/changeorder/123 |
405 |
not allowed |
Query Params
Name |
Type |
Value |
budgetId |
integer |
returns all change orders for the budget represented by budgetId |
baselineBudgetId |
integer |
returns all change orders for the budget represented by baselineBudgetId |
status |
string |
returns all change orders for given comma delimited list of statuses (any combination of draft, pending, rejected, approved, applied) |
Note: to query the changeorder endpoint you must provide at least one parameter.
Parameters for POST/PUT
Name |
Type |
Required on POST |
Allowed on PUT? |
Value |
status |
string |
yes |
yes |
Only statuses 'draft' and 'pending' are allowed on POST. Any of these statuses (+ approved, rejected, applied, canceled) may be set on PUT. |
type |
string |
yes |
no |
one of "internal" or "external". external change order are ones requiring customer review, while internal change orders are for internal changes to a budget. |
baselineBudgetId |
integer |
no |
no |
sets the baseline budget to whose history the change order applies |
budgetId |
integer |
yes |
no |
sets the budget that the change order will potentially (or did) modify |
notes |
string |
no |
yes |
sets the notes that are displayed and printed on the change order |
responseUser |
id |
no |
yes |
sets the responding user (by id) to a external change order request upon reponse (deprecated) |
responseUserId |
id |
no |
yes |
sets the responding user (by id) to a external change order request upon reponse |
responseNotes |
string |
no |
yes |
sets the optional notes for reason a request was rejected |
ownerId |
integer |
no |
yes |
owner id for the change order |
Returned Elements
Name |
Type |
Value |
id |
integer |
item id |
uri |
string |
resource identifier for the given item |
status |
string |
status of the change order |
type |
string |
type of the change order |
budget |
Budget |
budget that this change order is for |
baselineBudget |
Budget |
baseline budget for which this change order is a revision |
owner |
User |
the change order's owner |
notes |
string |
display notes for this change order, or null |
responseUser |
User |
user responding to external request type change order, or null |
responseNotes |
integer |
response user's feedback to rejected change order, or null |
categories |
array Change Order Category |
updated budget categories contained in change order, or null |
lineItems |
array Change Order Line Item |
updated line items contained in change order, or null |
referenceNumber |
string |
human-readable reference number for the change order on the budget |
terms |
Terms |
terms and conditions associated with this change order |
pendingServiceRequests |
array Service Request |
pending service requests introduced by this change order |
Retrieve change order by id
GET /changeorder/593952451821633
{
"data": {
"id": 593952451821633,
"uri": "http://localhost/api/changeOrder/593952451821633",
"status": "pending",
"type": "internal",
"budget": {
"id": 593952266174529,
"uri": "http://localhost/api/budget/593952266174529",
"referenceNumber": "593952266174529",
"sequence": 0,
"status": "locked",
"type": "high_level"
},
"baselineBudget": null,
"owner": {
"id": 575592395259968,
"uri": "http://localhost/api/user/575592395259968",
"name": "Stan Dalone",
"status": "active",
"email": "uuxiiuit+standalone@gmail.com",
"avatar": {
"small": "http://localhost/image/avatar-small.png",
"medium": "http://localhost/image/avatar-medium.png",
"large": "http://localhost/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"ResponseUser": null,
"ResponseNotes": null,
"notes": null,
"categories": [],
"lineItems": [],
"referenceNumber": "INT-0001",
"terms": {
id: 1,
uri: "http://localhost:8989/api/terms/1",
name: "Some Terms and Conditions"
},
"pendingServiceRequests": []
}
}
Retrieve all change orders for a budget
GET /changeorder?budgetId=588180849147969
{
"data": {
"totalPages": 1,
"page": 1,
"change_orders": [
{
"id": 588187459027009,
"uri": "http://localhost/api/changeOrder/588187459027009",
"status": "pending",
"type": "internal",
"budget": {
"id": 588180849147969,
"uri": "http://localhost/api/budget/588180849147969",
"referenceNumber": "588180849147969",
"sequence": 0,
"status": "locked",
"type": "high_level"
},
"baselineBudget": null,
"owner": {
"id": 575592395259968,
"uri": "http://localhost/api/user/575592395259968",
"name": "Stan Dalone",
"status": "active",
"email": "uuxiiuit+standalone@gmail.com",
"avatar": {
"small": "http://localhost/image/avatar-small.png",
"medium": "http://localhost/image/avatar-medium.png",
"large": "http://localhost/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"ResponseUser": null,
"ResponseNotes": null,
"notes": null,
"categories": [],
"lineItems": [],
"referenceNumber": "INT-0001",
"terms": {
id: 1,
uri: "http://localhost:8989/api/terms/1",
name: "Some Terms and Conditions"
},
"pendingServiceRequests": []
},
{
"id": 588203766530113,
"uri": "http://localhost/api/changeOrder/588203766530113",
"status": "pending",
"type": "internal",
"budget": {
"id": 588180849147969,
"uri": "http://localhost/api/budget/588180849147969",
"referenceNumber": "588180849147969",
"sequence": 0,
"status": "locked",
"type": "high_level"
},
"baselineBudget": null,
"owner": {
"id": 575592395259968,
"uri": "http://localhost/api/user/575592395259968",
"name": "Stan Dalone",
"status": "active",
"email": "uuxiiuit+standalone@gmail.com",
"avatar": {
"small": "http://localhost/image/avatar-small.png",
"medium": "http://localhost/image/avatar-medium.png",
"large": "http://localhost/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"ResponseUser": null,
"ResponseNotes": null,
"notes": null,
"categories": [],
"lineItems": [],
"referenceNumber": "INT-0002",
"terms": {
id: 1,
uri: "http://localhost:8989/api/terms/1",
name: "Some Terms and Conditions"
},
"pendingServiceRequests": []
},
{
"id": 588203813994561,
"uri": "http://localhost/api/changeOrder/588203813994561",
"status": "pending",
"type": "internal",
"budget": {
"id": 588180849147969,
"uri": "http://localhost/api/budget/588180849147969",
"referenceNumber": "588180849147969",
"sequence": 0,
"status": "locked",
"type": "high_level"
},
"baselineBudget": null,
"owner": {
"id": 575592395259968,
"uri": "http://localhost/api/user/575592395259968",
"name": "Stan Dalone",
"status": "active",
"email": "uuxiiuit+standalone@gmail.com",
"avatar": {
"small": "http://localhost/image/avatar-small.png",
"medium": "http://localhost/image/avatar-medium.png",
"large": "http://localhost/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"ResponseUser": null,
"ResponseNotes": null,
"notes": null,
"categories": [],
"lineItems": [],
"referenceNumber": "INT-0003",
"terms": {
id: 1,
uri: "http://localhost:8989/api/terms/1",
name: "Some Terms and Conditions"
},
"pendingServiceRequests": []
}
]
}
}
Create a new change order
POST /changeorder
{"budgetId":"593952266174529","status":"pending","type":"internal"}
200
{
"data": {
"id": 593954664169537,
"uri": "http://localhost/api/changeOrder/593954664169537",
"status": "pending",
"type": "internal",
"budget": {
"id": 593952266174529,
"uri": "http://localhost/api/budget/593952266174529",
"referenceNumber": "593952266174529",
"sequence": 0,
"status": "locked",
"type": "high_level"
},
"baselineBudget": null,
"owner": {
"id": 575592395259968,
"uri": "http://localhost/api/user/575592395259968",
"name": "Stan Dalone",
"status": "active",
"email": "uuxiiuit+standalone@gmail.com",
"avatar": {
"small": "http://localhost/image/avatar-small.png",
"medium": "http://localhost/image/avatar-medium.png",
"large": "http://localhost/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"ResponseUser": null,
"ResponseNotes": null,
"notes": null,
"categories": [],
"lineItems": [],
"referenceNumber": "INT-0001",
"terms": {
id: 1,
uri: "http://localhost:8989/api/terms/1",
name: "Some Terms and Conditions"
},
"pendingServiceRequests": []
}
}
Modify an existing change order
PUT /changeorder/593954664169537
{"status": "pending"}
200
{
"data": {
"id": 593954664169537,
"uri": "http://localhost/api/changeOrder/593954664169537",
"status": "pending",
"type": "internal",
"budget": {
"id": 593952266174529,
"uri": "http://localhost/api/budget/593952266174529",
"referenceNumber": "593952266174529",
"sequence": 0,
"status": "locked",
"type": "high_level"
},
"baselineBudget": null,
"owner": {
"id": 575592395259968,
"uri": "http://localhost/api/user/575592395259968",
"name": "Stan Dalone",
"status": "active",
"email": "uuxiiuit+standalone@gmail.com",
"avatar": {
"small": "http://localhost/image/avatar-small.png",
"medium": "http://localhost/image/avatar-medium.png",
"large": "http://localhost/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"ResponseUser": null,
"ResponseNotes": null,
"notes": null,
"categories": [],
"lineItems": [],
"referenceNumber": "INT-0001",
"terms": {
id: 1,
uri: "http://localhost:8989/api/terms/1",
name: "Some Terms and Conditions"
},
"pendingServiceRequests": []
}
}
Delete an existing change order
DELETE ../api/changeorder/593954664169537
Response hash (formatted / raw): 0 / 0
405
Return to Top
Change Order Category
The change order category resource is used to retrieve a list of change order categories for a change order.
- Resource URL: /changeordercategory/[changeOrderCategoryId]
- Available Verbs: GET, POST, PUT, DELETE
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/changeordercategory |
405 |
unconditional index not allowed, provide changeOrderId |
GET |
/changeordercategory?changeOrderCategoryId=123 |
200 |
|
GET |
/changeordercategory/123 |
200 |
|
GET |
/changeordercategory/123 |
404 |
changeordercategory not found |
GET |
/changeordercategory/123 |
403 |
no permission |
POST |
/changeordercategory |
200 |
changeordercategory created |
POST |
/changeordercategory |
403 |
no permission |
POST |
/changeordercategory |
400 |
invalid post data |
PUT |
/changeordercategory/123 |
200 |
|
PUT |
/changeordercategory/123 |
404 |
changeordercategory not found |
PUT |
/changeordercategory/123 |
403 |
no permission |
PUT |
/changeordercategory/123 |
400 |
invalid PUT data |
DELETE |
/changeordercategory/123 |
204 |
|
DELETE |
/changeordercategory/123 |
403 |
no permission |
Query Params
Name |
Type |
Value |
changeOrderId |
integer |
returns all change order categories for this change order |
referenceNumber |
string |
returns all change order categories for this reference number |
Note: to query the changeordercategory endpoint you must provide at least one parameter.
Parameters for POST/PUT, general fields
Name |
Type |
Required on POST |
Allowed on PUT? |
Value |
changeOrderId |
integer |
yes |
no |
change order that this change order category this belongs to |
changeAction |
string |
yes |
no |
one of "add", "change", or "delete" |
referenceNumber |
string |
sometimes* |
no |
reference number of the budget category this change order category applies to; required if the action is "change" or "delete", but not required for "add" |
notes |
string |
no |
yes |
notes applying to this specific change |
Parameters for POST/PUT, budget category field changes
Name |
Type |
Required on POST |
Allowed on PUT? |
Value |
libItemType |
string |
no |
yes |
value for budget category: category type or line item type corresponding to a lib item type, one of: part, material, labor, equipment, inspection, service, subcontractor, fee, general_conditions, or other. This defaults to the lib item's libItemType but can be set to a different value. |
serviceRequestId |
integer |
no |
yes |
value for budget category: service request id for the associated service, or null for none |
cost |
float |
for "add" only |
yes |
value for budget category: per each cost of the category |
price |
float |
no |
yes |
value for budget category: per each price of the labor category hours. optional and nullable. |
quantity |
float |
for "add" only |
yes |
value for budget category: quantity, only type labor categories will be able to set a non-null value |
orderIndex |
integer |
no |
yes |
value for budget category: indicates order of display with other categories on the budget |
Note: any fields not provided on POST for a "change" action will cause the change order category to populate the current value from the budget category provided by referenceNumber (see change action POST example below to see what that looks like)
Returned Elements
Name |
Type |
Value |
id |
integer |
category id |
uri |
string |
resource identifier for the given category |
changeOrder |
ChangeOrder |
change order that this change order category belongs to |
changeAction |
string |
action of the change order category |
referenceNumber |
string |
reference number of the budget category being modified |
notes |
string |
notes applying to this specific change |
libItemType |
string |
new value for libItemType (or null if the action is "delete") |
serviceRequestId |
integer |
new value for serviceRequestId (or null if the action is "delete") |
cost |
float |
new value for cost (or null if the action is "delete") |
price |
float |
new value for price (or null if the action is "delete") |
quantity |
float |
new value for quantity (or null if the action is "delete") |
orderIndex |
integer |
new value for orderIndex (or null if the action is "delete") |
Retrieve all change order categories for a change order
GET /changeordercategory?changeOrderId=599654169493569
200
{
"data": {
"totalPages": 1,
"page": 1,
"changeOrderCategories": [
{
"id": 599658110533697,
"uri": "https://api.servicetrade.com/api/changeordercategory/599658110533697",
"referenceNumber": "599649131413569",
"changeAction": "change",
"name": null,
"libItemType": "fee",
"cost": 1000,
"quantity": 10,
"orderIndex": 0,
"serviceRequest": null,
"price": 1500,
"changeOrder": {
"id": 599654169493569,
"uri": "https://api.servicetrade.com/api/changeorder/599654169493569",
"status": "pending",
"type": "internal"
}
},
{
"id": 599659531681857,
"uri": "https://api.servicetrade.com/api/changeordercategory/599659531681857",
"referenceNumber": "599649131413569",
"changeAction": "delete",
"name": null,
"libItemType": null,
"cost": 0,
"quantity": 10,
"orderIndex": null,
"serviceRequest": null,
"price": null,
"changeOrder": {
"id": 599654169493569,
"uri": "https://api.servicetrade.com/api/changeorder/599654169493569",
"status": "pending",
"type": "internal"
}
}
]
}
}
Retrieve a specific change order category by id
GET /changeordercategory/599658110533697
200
{
"data": {
"id": 599658110533697,
"uri": "https://api.servicetrade.com/api/changeordercategory/599658110533697",
"referenceNumber": "599649131413569",
"changeAction": "change",
"name": null,
"libItemType": "fee",
"cost": 1000,
"quantity": 10,
"orderIndex": 0,
"serviceRequest": null,
"price": 1500,
"changeOrder": {
"id": 599654169493569,
"uri": "https://api.servicetrade.com/api/changeorder/599654169493569",
"status": "pending",
"type": "internal"
}
}
}
POST a new change order category (change action example)
POST /changeordercategory
{"changeOrderId":"599654169493569", "changeAction":"change", "referenceNumber":"599649131413569", "quantity": 10}
200
{
"data": {
"id": 599658110533697,
"uri": "https://api.servicetrade.com/api/changeordercategory/599658110533697",
"referenceNumber": "599649131413569",
"changeAction": "change",
"name": null,
"libItemType": "fee",
"cost": 1000,
"quantity": 10,
"orderIndex": 0,
"serviceRequest": null,
"price": 1500,
"changeOrder": {
"id": 599654169493569,
"uri": "https://api.servicetrade.com/api/changeorder/599654169493569",
"status": "pending",
"type": "internal"
}
}
}
POST a new change order category (delete action example)
POST /changeordercategory
{"changeOrderId":"599654169493569", "changeAction":"delete", "referenceNumber":"599649131413569", "quantity": 10}
200
{
"data": {
"id": 599659531681857,
"uri": "https://api.servicetrade.com/api/changeordercategory/599659531681857",
"referenceNumber": "599649131413569",
"changeAction": "delete",
"name": null,
"libItemType": null,
"cost": 0,
"quantity": 10,
"orderIndex": null,
"serviceRequest": null,
"price": null,
"changeOrder": {
"id": 599654169493569,
"uri": "https://api.servicetrade.com/api/changeorder/599654169493569",
"status": "pending",
"type": "internal"
}
}
}
POST a new change order category (add action example)
POST /changeordercategory
{"changeOrderId":"599654169493569", "changeAction":"add", "quantity": 8, "cost":"100.00"}
200
{
"data": {
"id": 599661879164993,
"uri": "https://api.servicetrade.com/api/changeordercategory/599661879164993",
"referenceNumber": null,
"changeAction": "add",
"name": null,
"libItemType": null,
"cost": 100,
"quantity": 8,
"orderIndex": null,
"serviceRequest": null,
"price": null,
"changeOrder": {
"id": 599654169493569,
"uri": "https://api.servicetrade.com/api/changeorder/599654169493569",
"status": "pending",
"type": "internal"
}
}
}
Modify an existing change order category
PUT /changeordercategory/595475687899137
{"quantity": 5}
200
{
"data": {
"id": 599658110533697,
"uri": "https://api.servicetrade.com/api/changeordercategory/599658110533697",
"referenceNumber": "599649131413569",
"changeAction": "change",
"name": null,
"libItemType": "fee",
"cost": 1000,
"quantity": 5,
"orderIndex": 0,
"serviceRequest": null,
"price": 1500,
"changeOrder": {
"id": 599654169493569,
"uri": "https://api.servicetrade.com/api/changeorder/599654169493569",
"status": "pending",
"type": "internal"
}
}
}
DELETE a change order category
DELETE /changeordercategory/599661879164993
204
Return to Top
Change Order Line Item
The change order line item resource is used to retrieve the list of change order line items for a change order that applies to a granular budget
- Resource URL: /changeorderlineitem/[changeOrderLineItemId]
- Available Verbs: GET, POST, PUT, DELETE
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/changeorderlineitem |
405 |
unconditional index not allowed, provide jobId or referenceNumber |
GET |
/changeorderlineitem?changeOrderLineItemId=123 |
200 |
|
GET |
/changeorderlineitem/123 |
200 |
|
GET |
/changeorderlineitem/123 |
404 |
changeorderlineitem not found |
GET |
/changeorderlineitem/123 |
403 |
no permission |
POST |
/changeorderlineitem |
200 |
changeorderlineitem created |
POST |
/changeorderlineitem |
403 |
no permission |
POST |
/changeorderlineitem |
400 |
invalid post data |
PUT |
/changeorderlineitem/123 |
200 |
|
PUT |
/changeorderlineitem/123 |
404 |
changeorderlineitem not found |
PUT |
/changeorderlineitem/123 |
403 |
no permission |
PUT |
/changeorderlineitem/123 |
400 |
invalid PUT data |
DELETE |
/changeorderlineitem/123 |
204 |
|
DELETE |
/changeorderlineitem/123 |
403 |
no permission |
Query Params
Name |
Type |
Value |
changeOrderId |
integer |
returns all change order line items for this change order |
referenceNumber |
string |
returns all change order line items for this reference number |
Note: to query the changeorderlineitem endpoint you must provide at least one parameter.
Parameters for POST/PUT, general fields
Name |
Type |
Required on POST |
Allowed on PUT? |
Value |
changeOrderId |
integer |
yes |
no |
change order that this change order line item belongs to |
changeAction |
string |
yes |
no |
one of "add", "change", or "delete" |
referenceNumber |
string |
sometimes* |
no |
reference number of the budget line item this change order line item applies to; required if the action is "change" or "delete", but not required for "add" |
notes |
string |
no |
yes |
notes applying to this specific change |
Parameters for POST/PUT, change order line item's budget line item field changes
Name |
Type |
Required on POST |
Allowed on PUT? |
Value |
jobItemId |
integer |
no |
yes |
value for budget line item: id of the jobItem associated with the budget line item if there is one |
libItemId |
integer |
no |
yes |
value for budget line item: id of the libItem for the budget line item, absense of this means you are creating an "other" item of the service line indicated by serviceLineId |
libItemType |
string |
no |
yes |
value for budget line item: category type or line item type corresponding to a lib item type, one of: part, material, labor, equipment, inspection, service, subcontractor, fee, general_conditions, or other. This defaults to the lib item's libItemType but can be set to a different value. |
name |
string |
for "add" only |
yes |
value for budget line item: display name for the associated (actual or planned) job item. Required on POST. It can be set to match the lib item name or something different. |
serviceLineId |
integer |
no |
yes |
value for budget line item: defaults to service line of the lib item if it has one, but it can be set to a different value. Required in the case of a lib item without an assigned service line. |
serviceRequestId |
integer |
no |
yes |
value for budget line item: service request id for the associated service, or null for none |
cost |
float |
for "add" only |
yes |
value for budget line item: per each cost of the line item |
price |
float |
no |
yes |
value for budget line item: per each price of the line item. optional and nullable. |
quantity |
float |
for "add" only |
yes |
value for budget line item: quantity of this item budgeted |
orderIndex |
integer |
no |
yes |
value for budget line item: indicates order of display with other categories on the budget |
Note: any fields not provided on POST for a "change" action will cause the change order line item to populate the current value from the budget line item provided by referenceNumber (see change action POST example below to see what that looks like)
Returned Elements
Name |
Type |
Value |
id |
integer |
item id |
uri |
string |
resource identifier for the given item |
changeOrder |
Change Order |
change order that this change order line item belongs to |
changeAction |
string |
action of the change order line item |
referenceNumber |
string |
reference number of the budget line item being modified |
notes |
string |
notes applying to this specific change |
jobItem |
Job Item |
new value for jobItemId (or null if the action is "delete") |
libItem |
Libitem |
new value for libItemId (or null if the action is "delete") |
libItemType |
string |
new value for libItemType (or null if the action is "delete") |
name |
string |
new value for name (or null if the action is "delete") |
serviceLine |
Service Line |
new value for serviceLineId (or null if the action is "delete") |
serviceRequest |
Service Request |
new value for serviceRequestId (or null if the action is "delete") |
cost |
float |
new value for cost (or null if the action is "delete") |
price |
float |
new value for price (or null if the action is "delete") |
quantity |
float |
new value for quantity (or null if the action is "delete") |
orderIndex |
integer |
new value for orderIndex (or null if the action is "delete") |
Retrieve all change order line items for a change order
GET ../api/changeorderlineitem?changeOrderId=595466086236161
200
{
"data": {
"totalPages": 1,
"page": 1,
"changeOrderLineItems": [
{
"id": 595470078558209,
"uri": "https://api.servicetrade.com/api/changeorderlineitem/595470078558209",
"referenceNumber": "595459152592897",
"changeAction": "delete",
"name": null,
"notes": null,
"libItemType": null,
"cost": null,
"quantity": null,
"orderIndex": null,
"libItem": null,
"jobItem": null,
"serviceRequest": null,
"serviceLine": null,
"price": null,
"changeOrder": {
"id": 595466086236161,
"uri": "https://api.servicetrade.com/api/changeorder/595466086236161",
"status": "pending",
"type": "external"
}
},
{
"id": 595475687899137,
"uri": "https://api.servicetrade.com/api/changeorderlineitem/595475687899137",
"referenceNumber": "595459152658433",
"changeAction": "change",
"name": "Corner Pullies",
"notes": null,
"libItemType": "part",
"cost": 6.5,
"quantity": 5,
"orderIndex": 0,
"libItem": {
"id": 594187077779459,
"uri": "https://api.servicetrade.com/api/libitem/594187077779459",
"name": "Corner Pullies",
"type": "part",
"code": "PULLEY",
"isGeneric": false,
"externalIds": {
"fattmerchant": "",
"peachtree": ""
}
},
"jobItem": {
"id": 595459151233025,
"uri": "https://api.servicetrade.com/api/jobitem/595459151233025",
"description": "Corner Pullies",
"cost": null,
"usedOn": null
},
"serviceRequest": null,
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "https://app.servicetrade.com/image/icons/service_lines/32/SUPP.png"
},
"price": null,
"changeOrder": {
"id": 595466086236161,
"uri": "https://api.servicetrade.com/api/changeorder/595466086236161",
"status": "pending",
"type": "external"
}
}
]
}
}
Retrieve a specific change order line item by id
GET ../api/changeorderlineitem/595475687899137
or
GET ../api/changeorder/595466086236161/lineitem/595475687899137
200
{
"data": {
"id": 595475687899137,
"uri": "https://api.servicetrade.com/api/changeorderlineitem/595475687899137",
"referenceNumber": "595459152658433",
"changeAction": "change",
"name": "Corner Pullies",
"notes": null,
"libItemType": "part",
"cost": 6.5,
"quantity": 5,
"orderIndex": 0,
"libItem": {
"id": 594187077779459,
"uri": "https://api.servicetrade.com/api/libitem/594187077779459",
"name": "Corner Pullies",
"type": "part",
"code": "PULLEY",
"isGeneric": false,
"externalIds": {
"fattmerchant": "",
"peachtree": ""
}
},
"jobItem": {
"id": 595459151233025,
"uri": "https://api.servicetrade.com/api/jobitem/595459151233025",
"description": "Corner Pullies",
"cost": null,
"usedOn": null
},
"serviceRequest": null,
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "https://app.servicetrade.com/image/icons/service_lines/32/SUPP.png"
},
"price": null,
"changeOrder": {
"id": 595466086236161,
"uri": "https://api.servicetrade.com/api/changeorder/595466086236161",
"status": "pending",
"type": "external"
}
}
}
POST a new change order line item (delete action example)
POST /changeorderlineitem
{"changeOrderId":"595466086236161", "changeAction":"delete", "referenceNumber":"595459152592897"}
200
{
"data": {
"id": 595470078558209,
"uri": "https://api.servicetrade.com/api/changeorderlineitem/595470078558209",
"referenceNumber": "595459152592897",
"changeAction": "delete",
"name": null,
"notes": null,
"libItemType": null,
"cost": null,
"quantity": null,
"orderIndex": null,
"libItem": null,
"jobItem": null,
"serviceRequest": null,
"serviceLine": null,
"price": null,
"changeOrder": {
"id": 595466086236161,
"uri": "https://api.servicetrade.com/api/changeorder/595466086236161",
"status": "pending",
"type": "external"
}
}
}
POST a new change order line item (change action example)
POST /changeorderlineitem
{"changeOrderId":"595466086236161", "changeAction":"change", "referenceNumber":"595459152658433", "quantity": 10}
200
{
"data": {
"id": 595475687899137,
"uri": "https://api.servicetrade.com/api/changeorderlineitem/595475687899137",
"referenceNumber": "595459152658433",
"changeAction": "change",
"name": "Corner Pullies",
"notes": null,
"libItemType": "part",
"cost": 6.5,
"quantity": 10,
"orderIndex": 0,
"libItem": {
"id": 594187077779459,
"uri": "https://api.servicetrade.com/api/libitem/594187077779459",
"name": "Corner Pullies",
"type": "part",
"code": "PULLEY",
"isGeneric": false,
"externalIds": {
"fattmerchant": "",
"peachtree": ""
}
},
"jobItem": {
"id": 595459151233025,
"uri": "https://api.servicetrade.com/api/jobitem/595459151233025",
"description": "Corner Pullies",
"cost": null,
"usedOn": null
},
"serviceRequest": null,
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "https://app.servicetrade.com/image/icons/service_lines/32/SUPP.png"
},
"price": null,
"changeOrder": {
"id": 595466086236161,
"uri": "https://api.servicetrade.com/api/changeorder/595466086236161",
"status": "pending",
"type": "external"
}
}
}
Modify an existing change order line item
PUT
/changeorderlineitem/595475687899137
{"quantity": 5}
200
{
"data": {
"id": 595475687899137,
"uri": "https://api.servicetrade.com/api/changeorderlineitem/595475687899137",
"referenceNumber": "595459152658433",
"changeAction": "change",
"name": "Corner Pullies",
"notes": null,
"libItemType": "part",
"cost": 6.5,
"quantity": 5,
"orderIndex": 0,
"libItem": {
"id": 594187077779459,
"uri": "https://api.servicetrade.com/api/libitem/594187077779459",
"name": "Corner Pullies",
"type": "part",
"code": "PULLEY",
"isGeneric": false,
"externalIds": {
"fattmerchant": "",
"peachtree": ""
}
},
"jobItem": {
"id": 595459151233025,
"uri": "https://api.servicetrade.com/api/jobitem/595459151233025",
"description": "Corner Pullies",
"cost": null,
"usedOn": null
},
"serviceRequest": null,
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "https://app.servicetrade.com/image/icons/service_lines/32/SUPP.png"
},
"price": null,
"changeOrder": {
"id": 595466086236161,
"uri": "https://api.servicetrade.com/api/changeorder/595466086236161",
"status": "pending",
"type": "external"
}
}
}
DELETE a change order line item
DELETE ../api/changeorderlineitem/595475687899137
204
Return to Top
Clockin/Clockout
The clockin and clockout resources are used to clock in and out of a job, or to retrieve information about clock events.
- Resource URL: /clock
- Resource URL: /job/[jobId]/clockin/[eventId]
- Resource URL: /job/[jobId]/clockout/[eventId]
- Resource URL: /job/[jobId]/clockevent
- Available Verbs: GET, POST, PUT, DELETE
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/job/123/clockin |
200 |
|
GET |
/job/123/clockin |
404 |
job 123 not found (or not accessible by the user) |
GET |
/job/123/clockin/456 |
200 |
|
GET |
/job/123/clockin/456 |
404 |
job 123 not found (or not accessible by the user), or event 456 does not exist or is not a clock-in event |
POST |
/job/123/clockin |
200 |
|
POST |
/job/123/clockin |
400 |
bad POST parameter |
POST |
/job/123/clockin |
404 |
job 123 not found (or not accessible by the user) |
POST |
/job/123/clockout |
403 |
cannot create a clock-out without a corresponding clock-in |
POST |
/job/123/clockin/456 |
405 |
not allowed |
POST |
/job/123/clockin/456 |
409 |
conflict: There is already a clock-in event at this time for this user on this appointment |
PUT |
/job/123/clockin |
405 |
not allowed |
PUT |
/job/123/clockin/456 |
200 |
|
DELETE |
/job/123/clockin |
405 |
not allowed |
DELETE |
/job/123/clockin/456 |
405 |
not allowed |
GET |
/clock |
200 |
|
GET |
/clock |
403 |
must provide at least one filter |
GET |
/clock/456 |
200 |
|
GET |
/clock/456 |
404 |
clock event does not exist |
POST |
/clock |
405 |
not allowed |
POST |
/clock/456 |
405 |
not allowed |
PUT |
/clock |
405 |
not allowed |
PUT |
/clock/456 |
200 |
|
DELETE |
/clock |
405 |
not allowed |
DELETE |
/clock/456 |
204 |
|
Query Params
Name |
Type |
Value |
userId |
integer |
user id who created the event |
userIds |
string |
comma-separated list of user ids |
startTime |
integer |
Unix timestamp of start of time range |
endTime |
integer |
Unix timestamp of end of time range |
source |
string |
Source of clock events; one of: mobile, ivr, manual |
activity |
string |
Activity type being clocked into/out of; one of: onsite, offsite, enroute |
type |
string |
Type of clock event; one of: clock-in, clock-out |
openClockEvents |
boolean |
Return only open clock events (clock-ins without a corresponding clock-out) associated with non-completed jobs - requires userId or userIds |
jobId |
integer |
Return only events related to this job |
appointmentId |
integer |
Return only events related to this appointment |
paired |
boolean |
Return paired events related to this job or appointment (this flag will explicitly tell whether to return paired or flat results); requires either a jobId or an appointmentId to be provided. If not provided, defaults to true if a jobId is provided, and false otherwise. See the note in Returned Elements below for more information. |
POST Parameters Clock-in
Name |
Type |
Required |
Value |
activity |
string |
no |
one of: onsite (default), offsite, enroute |
started |
boolean |
no |
was the job able to be started successfully with this clock-in? only for "onsite" |
eventTime |
integer |
no |
Unix timestamp when the event occurred (defaults to current time) |
lat |
double |
no |
latitude of the event |
lon |
double |
no |
longitude of the event |
source |
string |
no |
one of: mobile (default), ivr, manual |
callerIdNum |
string |
no |
unused, provided for future use |
callerIdName |
string |
no |
unused, provided for future use |
userId |
integer |
no |
user who created the event (defaults to current user) |
appointmentId |
integer |
no |
appointment for this job into which this user is clocking in |
POST Parameters Clock-out
Name |
Type |
Required |
Value |
activity |
string |
no |
one of: onsite (default), offsite, enroute |
completed |
boolean |
no |
was the job able to be completed successfully with this clock-out? only for "onsite" |
eventTime |
integer |
no |
Unix timestamp when the event occurred (defaults to current time) |
deficiency |
boolean |
no |
was a deficiency found with this clock-out? only for "onsite" |
otherTradeDeficiency |
boolean |
no |
was an other deficiency found with this clock-out? only for "onsite" |
redTag |
boolean |
no |
was a red tag found with this clock-out? only for "onsite" |
lat |
double |
no |
latitude of the event |
lon |
double |
no |
longitude of the event |
source |
string |
no |
one of: mobile (default), ivr, manual |
callerIdNum |
string |
no |
unused, provided for future use |
callerIdName |
string |
no |
unused, provided for future use |
userId |
integer |
no |
user who created the event (defaults to current user) |
appointmentId |
integer |
no |
appointment for this job into which this user is clocking out |
PUT Parameters Clock-in or Clock-out
Name |
Type |
Required |
Value |
activity |
string |
no |
one of: onsite (default), offsite, enroute |
eventType |
integer |
no |
one of: clock-in, clock-out |
eventTime |
integer |
no |
Unix timestamp when the event occurred (defaults to current time) |
lat |
double |
no |
latitude of the event |
lon |
double |
no |
longitude of the event |
source |
string |
no |
one of: mobile (default), ivr, manual |
userId |
integer |
no |
user who created the event (defaults to current user) |
appointmentId |
integer |
no |
appointment for this job into which this user is clocking in |
Returned Elements
Name |
Type |
Value |
events |
array (object) |
list of job clock objects; returned if the "paired" query parameter is false |
pairedEvents |
array (object) |
list of pairs of job clock objects; returned if the "paired" parameter flag is true |
unpairedEvents |
array (object) |
list of job clock objects; returned if the "paired" parameter flag is true |
activityTime |
array (object) |
list of total times spent in each activity |
uri |
string |
resource identifier for the given clock event |
id |
string |
clock event id |
eventTime |
integer |
timestamp at which the event was created |
eventType |
string |
one of: clock-in, clock-out |
activity |
string |
one of: onsite, offsite, enroute |
source |
string |
where the clock event came from |
started |
boolean |
was the job able to be started successfully with this clock-in? |
completed |
boolean |
was the job able to be completed successfully with this clock-out? |
deficiency |
boolean |
was a deficiency found with this clock-out? |
otherTradeDeficiency |
boolean |
was an other deficiency found with this clock-out? |
redTag |
boolean |
was a red tag found with this clock-out? |
lat |
double |
latitude of the event |
lon |
double |
longitude of the event |
callerIdNum |
string |
unused, provided for future use |
callerIdName |
string |
unused, provided for future use |
user |
User |
user that created the event |
job |
Job |
job to which the event is attached |
appointment |
Appointment |
appointment to which the event is attached |
NOTE: If the "paired" flag is true (either explicitly or by default), results will be returned as matched pairs of clock events (where each clock in is matched with its corresponding clock out) in a "pairedEvents" array, with all remaining unpaired clock in events returned in an "unpairedEvents" array. Otherwise, a flat list of clock events will be returned in an "events" array.
Retrieve all clock in events for a job
GET /job/123/clockin
200
{
"data": {
"totalPages": 1,
"page": 1,
"events": [
{
"id": 29877,
"uri": "https://api.servicetrade.com/api/clock/29877",
"user": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"job": {
"id": 123,
"uri": "https://api.servicetrade.com/api/job/123",
"number": 54321,
"type": "inspection",
"name": "Job 54321"
},
"appointment": null,
"eventTime": 1321990759,
"eventType": "clock-in",
"activity": "onsite",
"source": "mobile",
"deficiency": false,
"otherTradeDeficiency": false,
"redTag": false,
"started": false,
"completed": false,
"callerIdNum": null,
"callerIdName": null,
"lat": 12.34,
"lon": -45.67
},
{
"id": 29879,
"uri": "https://api.servicetrade.com/api/clock/29879",
"user": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"job": {
"id": 123,
"uri": "https://api.servicetrade.com/api/job/123",
"number": 54321,
"type": "inspection",
"name": "Job 54321"
},
"appointment": null,
"eventTime": 1321990784,
"eventType": "clock-in",
"activity": "enroute",
"source": "mobile",
"deficiency": false,
"otherTradeDeficiency": false,
"redTag": false,
"started": true,
"completed": false,
"callerIdNum": null,
"callerIdName": null,
"lat": 12.34,
"lon": -45.67
}
]
}
}
Retrieve all clock out events for a job
GET /job/123/clockout
200
{
"data": {
"totalPages": 1,
"page": 1,
"events": [
{
"id": 30135,
"uri": "https://api.servicetrade.com/api/clock/30135",
"user": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"job": {
"id": 123,
"uri": "https://api.servicetrade.com/api/job/123",
"number": 54321,
"type": "inspection",
"name": "Job 54321"
},
"appointment": null,
"eventTime": 1321990789,
"eventType": "clock-out",
"activity": "enroute",
"source": "mobile",
"deficiency": true,
"otherTradeDeficiency": false,
"redTag": false,
"started": false,
"completed": true,
"callerIdNum": null,
"callerIdName": null,
"lat": 12.34,
"lon": -45.67
}
]
}
}
Retrieve all clock in events for a non-existent job
GET /job/321/clockin
404
Retrieve a specific clock out event
GET /job/123/clockout/30135
200
{
"data": {
"id": 30135,
"uri": "https://api.servicetrade.com/api/clock/30135",
"user": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"job": {
"id": 123,
"uri": "https://api.servicetrade.com/api/job/123",
"number": 54321,
"type": "inspection",
"name": "Job 54321"
},
"appointment": null,
"eventTime": 1321990789,
"eventType": "clock-out",
"activity": "enroute",
"source": "mobile",
"deficiency": true,
"otherTradeDeficiency": true,
"redTag": false,
"started": false,
"completed": true,
"callerIdNum": null,
"callerIdName": null,
"lat": 12.34,
"lon": -45.67
}
}
Retrieve a specific clock out event that does not exist
GET /clock/858492
404
Attempting to clock out of a job that is not open
POST /job/111/clockout
403
{
"messages": {
"error": [
"Cannot create a clock-out event without a corresponding clock-in"
]
}
}
Create a clock in event
POST /job/123/clockin
{"started":true,"lat":12.34,"lon":-45.67,"appointmentId":27}
200
{
"data": {
"id": 29877,
"uri": "https://api.servicetrade.com/api/clock/29877",
"user": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"job": {
"id": 123,
"uri": "https://api.servicetrade.com/api/job/123",
"number": 54321,
"type": "inspection",
"name": "Job 54321"
},
"appointment": {
"id": 27,
"uri": "https://api.servicetrade.com/api/appointment/27",
"name": "Appointment #27"
},
"eventTime": 1321990759,
"eventType": "clock-in",
"activity": "onsite",
"source": "mobile",
"deficiency": false,
"otherTradeDeficiency": false,
"redTag": false,
"started": true,
"completed": false,
"callerIdNum": null,
"callerIdName": null,
"lat": 12.34,
"lon": -45.67
}
}
Create a clock in event for a specific activity
POST /job/123/clockin
{"activity":"enroute","lat":12.34,"lon":-45.67}
200
{
"data": {
"id": 29877,
"uri": "https://api.servicetrade.com/api/clock/29877",
"user": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"job": {
"id": 123,
"uri": "https://api.servicetrade.com/api/job/123",
"number": 54321,
"type": "inspection",
"name": "Job 54321"
},
"appointment": null,
"eventTime": 1321991001,
"eventType": "clock-in",
"activity": "enroute",
"source": "mobile",
"deficiency": false,
"otherTradeDeficiency": false,
"redTag": false,
"started": true,
"completed": false,
"callerIdNum": null,
"callerIdName": null,
"lat": 12.34,
"lon": -45.67
}
}
Create a clock out event
POST /job/123/clockout
{"completed":true,"deficiency":false,"redtag":true,"otherTradeDeficiency":true,"lat":12.34,"lon":-45.67}
200
{
"data": {
"id": 30135,
"uri": "https://api.servicetrade.com/api/clock/30135",
"user": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"job": {
"id": 123,
"uri": "https://api.servicetrade.com/api/job/123",
"number": 54321,
"type": "inspection",
"name": "Job 54321"
},
"appointment": null,
"eventTime": 1321990789,
"eventType": "clock-out",
"activity": "onsite",
"source": "mobile",
"deficiency": false,
"otherTradeDeficiency": true,
"redTag": true,
"started": false,
"completed": true,
"callerIdNum": null,
"callerIdName": null,
"lat": 12.34,
"lon": -45.67
}
}
Clock into a job that already has an open clock event for that user
POST /job/123/clockin
{"userId": 423, "appointmentId": 38, "eventTime": 1583944618, "lat":12.34,"lon":-45.67}
409 {
"messages": {
"error": [
"There is already a clock-in event at this time for this user on this appointment"
]
}
}
Retrieve all clock event pairs for a job
GET /job/123/clockevent
200
{
"data": {
"totalPages": 1,
"page": 1,
"activityTime": {
"onsite": 3600,
"offsite": 0,
"enroute": 1800
},
"pairedEvents": [
{
"elapsedTime": 3600,
"start": {
"id": 29877,
"uri": "https://api.servicetrade.com/api/clock/29877",
"user": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"job": {
"id": 123,
"uri": "https://api.servicetrade.com/api/job/123",
"number": 54321,
"type": "inspection",
"name": "Job 54321"
},
"appointment": null,
"eventTime": 1321990759,
"eventType": "clock-in",
"activity": "onsite",
"source": "mobile",
"deficiency": false,
"otherTradeDeficiency": false,
"redTag": false,
"started": false,
"completed": false,
"callerIdNum": null,
"callerIdName": null,
"lat": 12.34,
"lon": -45.67
},
"end": {
"id": 29880,
"uri": "https://api.servicetrade.com/api/clock/29880",
"user": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"job": {
"id": 123,
"uri": "https://api.servicetrade.com/api/job/123",
"number": 54321,
"type": "inspection",
"name": "Job 54321"
},
"appointment": null,
"eventTime": 1321991119,
"eventType": "clock-out",
"activity": "onsite",
"source": "mobile",
"deficiency": false,
"otherTradeDeficiency": false,
"redTag": false,
"started": false,
"completed": false,
"callerIdNum": null,
"callerIdName": null,
"lat": 12.34,
"lon": -45.67
}
},
{
"elapsedTime": 1800,
"start": {
"id": 298734,
"uri": "https://api.servicetrade.com/api/clock/29834",
"user": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"job": {
"id": 123,
"uri": "https://api.servicetrade.com/api/job/123",
"number": 54321,
"type": "inspection",
"name": "Job 54321"
},
"eventTime": 1321989021,
"eventType": "clock-in",
"activity": "enroute",
"source": "mobile",
"deficiency": false,
"otherTradeDeficiency": false,
"redTag": false,
"started": false,
"completed": false,
"callerIdNum": null,
"callerIdName": null,
"lat": 12.34,
"lon": -45.67
},
"end": {
"id": 29724,
"uri": "https://api.servicetrade.com/api/clock/29724",
"user": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"job": {
"id": 123,
"uri": "https://api.servicetrade.com/api/job/123",
"number": 54321,
"type": "inspection",
"name": "Job 54321"
},
"appointment": null,
"eventTime": 1321990821,
"eventType": "clock-out",
"activity": "enroute",
"source": "mobile",
"deficiency": false,
"otherTradeDeficiency": false,
"redTag": false,
"started": false,
"completed": false,
"callerIdNum": null,
"callerIdName": null,
"lat": 12.34,
"lon": -45.67
}
}
],
"unpairedEvents": []
}
}
Retrieve all onsite events for given users in a time range
GET /clock?userIds=6,23&startTime=1321990000&endTime=1321100000&activity=onsite
200
{
"data": {
"totalPages": 1,
"page": 1,
"events": [
{
"id": 30135,
"uri": "http://api.servicetrade.com/api/clock/30135",
"user": {
"id": 6,
"uri": "http://api.servicetrade.com/api/user/6",
"name": "Joe User",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"job": {
"id": 123,
"uri": "http://api.servicetrade.com/api/job/123",
"number": 54321,
"type": "inspection",
"name": "Job 54321"
},
"appointment": null,
"eventTime": 1321990789,
"eventType": "clock-out",
"activity": "onsite",
"source": "mobile",
"deficiency": true,
"otherTradeDeficiency": false,
"redTag": false,
"started": false,
"completed": true,
"callerIdNum": null,
"callerIdName": null,
"lat": 12.34,
"lon": -45.67
},
{
"id": 30243,
"uri": "http://api.servicetrade.com/api/clock/30243",
"user": {
"id": 23,
"uri": "http://api.servicetrade.com/api/user/23",
"name": "Arthur Dent",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"job": {
"id": 78,
"uri": "http://api.servicetrade.com/api/job/78",
"number": 54473,
"type": "inspection",
"name": "Job 54473"
},
"appointment": null,
"eventTime": 1321992145,
"eventType": "clock-in",
"activity": "onsite",
"source": "mobile",
"deficiency": false,
"otherTradeDeficiency": false,
"redTag": false,
"started": false,
"completed": true,
"callerIdNum": null,
"callerIdName": null,
"lat": 34.12,
"lon": -67.45
}
]
}
}
Return to Top
Comment
The comment resource is used to create and retrieve text comments for specific entities (jobs, locations, quotes, etc.)
- Resource URL: /comment/[commentId]
- Available Verbs: GET, POST, PUT, DELETE
- Authentication Required: yes
Comment visibility is a combination of privacy level and context. One or more of the following visibility flags may be applied to a comment: 'public', 'schedule', 'tech' , 'billing'. Comments not flagged as 'public', are only visible to users belonging to the same company as the comment's author. Comments flagged with 'schedule' are displayed more prominently in places where scheduling activities are being performed. Comments flagged as 'tech' are displayed more prominently for in places where technicians are likely to use them (such as in the tech mobile applications). Comments flagged with 'billing' are displayed more prominently in places where billing activities are being performed.
The following entities support comments. Starred resources also have dedicated comment endpoints; when using these resource-specific endpoints, it is unnecessary to provide an entityId and entityType parameter, unless otherwise noted.
Cascaded Comments
Comments for some types of entities may include "cascaded" comments that are inherited from their parent records, as follows:
- Job entities include comments with either the 'tech' or 'schedule' flag for the job's location
- Job entities include comments with either the 'tech' or 'schedule' flag for the job's customer company (this will not be the job's location's company if the job's customer was changed)
- Location entities include comments with either the 'tech' or 'schedule' flag for the location's company
Cascaded comments have the entityType and entityId of the entity from which they were inherited.
Cascaded comments are included only when a specific entity is retrieved by its entityType/entityId (or through one of the dedicated comment endpoints described above), and no additional search parameters other than visibility (optional) are provided. For instance, a request for /api/comment?entityType=3&entityId=12345
would return all comments for job ID 12345, plus all comments cascaded from that job's parent location and customer company. A request for /api/comment?entityType=3&entityId=12345&visibility=tech
would return all tech comments for job ID 12345, plus all tech comments cascaded from that job's parent location and customer company.
However, a request for /api/comment?entityType=3&entityId=12345&authorId=56789
would return only comments directly on job ID 12345 that were authored by user ID 56789, but not any comments cascaded from the job's parent location and customer company (regardless of authorship).
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/comment |
405 |
not allowed |
GET |
/comment/123 |
200 |
|
GET |
/comment/123 |
404 |
comment 123 not found (or not accessible by the user) |
POST |
/comment |
200 |
|
POST |
/comment |
400 |
invalid data |
POST |
/comment |
403 |
error creating the comment |
POST |
/comment/123 |
405 |
not allowed |
PUT |
/comment |
405 |
not allowed |
PUT |
/comment/123 |
200 |
update the comment |
PUT |
/comment/123 |
404 |
comment 123 not found (or not accessible by the user) |
PUT |
/comment |
400 |
invalid data |
DELETE |
/comment |
405 |
not allowed |
DELETE |
/comment/123 |
204 |
comment deleted |
DELETE |
/comment/123 |
404 |
comment 123 not found (or not accessible by the user) |
Query Params
Name |
Type |
Value |
entityId |
integer |
id of the entity (required, unless one of the following is supplied: createdAfter, createdBefore, updatedAfter, updatedBefore) |
entityType |
entity type |
entity type constant of the entity (required) |
visibility |
string |
comma delimited list of visibilities to match (matches any given): public, schedule, tech, billing. By default all comments are returned. |
authorId |
integer |
id of the user who created the comment |
includeRelatedEntities |
boolean |
include comments of service requests related to job/quote (If not job or quote then flag is ignored) |
createdAfter |
integer |
timestamp, matches records created on or after |
createdBefore |
integer |
timestamp, matches records created on or before |
updatedAfter |
integer |
timestamp, matches records updated on or after |
updatedBefore |
integer |
timestamp, matches records updated on or before |
Parameters for POST / PUT
Name |
Type |
Required |
Value |
content |
string |
yes |
text of the comment |
visibility |
array (string) |
no |
privacy level and context; combination of: public, schedule, tech, billing. If not provided, or if it is an empty array, the visibility of the comment will not be public and will be neither a schedule nor a tech comment. If posting a comment to the asset, the only accepted visibilities are public and tech. |
entityId |
integer |
yes |
id of the entity to comment on |
entityType |
entity type |
yes |
entity type constant of the entity to comment on |
Returned Elements
Name |
Type |
Value |
uri |
string |
resource identifier of the comment |
id |
integer |
comment id |
content |
string |
comment text |
visibility |
array (string) |
privacy level and context; combination of: public, schedule, tech, billing |
created |
integer |
Unix timestamp of the comment’s creation date and time |
updated |
integer |
Unix timestamp of the comment’s most recent update date and time |
entity.uri |
string |
resource identifier of the entity to which this comment is attached |
entity.id |
integer |
id of the entity to which this comment is attached |
entity.type |
entity type |
entity type constant |
author |
User |
author of the comment |
Retrieve comments for job 41
GET /comment?entityId=41&entityType=3
200
{
"totalPages": 1,
"page": 1,
"comments": [
{
"uri": "https://api.servicetrade.com/api/comment/10",
"id": 10,
"content": "This job needs more work.",
"created": 1327082916,
"updated": 1327082916,
"visibility": ["public"],
"entity": {
"uri": "https://api.servicetrade.com/api/job/41",
"id": 41,
"type": 3
},
"author": {
"uri": "https://api.servicetrade.com/api/user/6",
"id": 6,
"name": "Joe User",
"status": "active",
"avatar": {
"small": "https://api.servicetrade.com/image/avatar-small.png",
"medium": "https://api.servicetrade.com/image/avatar-medium.png",
"large": "https://api.servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
}
},
{
"uri": "https://api.servicetrade.com/api/comment/17",
"id": 17,
"content": "Work got done; manager to verify.",
"created": 1327089932,
"updated": 1327082916,
"visibility": ["public"],
"entity": {
"uri": "https://api.servicetrade.com/api/job/41",
"id": 41,
"type": 3
},
"author": {
"uri": "https://api.servicetrade.com/api/user/6",
"id": 6,
"name": "Joe User",
"status": "active",
"avatar": {
"small": "https://api.servicetrade.com/image/avatar-small.png",
"medium": "https://api.servicetrade.com/image/avatar-medium.png",
"large": "https://api.servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
}
}
]
}
Retrieve comments for job 41 plus job's service request comments
GET /comment?entityId=41&entityType=3&includeRelatedEntities=1
200
{
"totalPages": 1,
"page": 1,
"comments": [
{
"uri": "https://api.servicetrade.com/api/comment/10",
"id": 10,
"content": "This job needs more work.",
"created": 1327082916,
"updated": 1327082916,
"visibility": ["public"],
"entity": {
"uri": "https://api.servicetrade.com/api/job/41",
"id": 41,
"type": 3
},
"author": {
"uri": "https://api.servicetrade.com/api/user/6",
"id": 6,
"name": "Joe User",
"status": "active",
"avatar": {
"small": "https://api.servicetrade.com/image/avatar-small.png",
"medium": "https://api.servicetrade.com/image/avatar-medium.png",
"large": "https://api.servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
}
},
{
"uri": "https://api.servicetrade.com/api/comment/17",
"id": 17,
"content": "Work got done; manager to verify.",
"created": 1327089932,
"updated": 1327082916,
"visibility": ["public"],
"entity": {
"uri": "https://api.servicetrade.com/api/job/41",
"id": 41,
"type": 3
},
"author": {
"uri": "https://api.servicetrade.com/api/user/6",
"id": 6,
"name": "Joe User",
"status": "active",
"avatar": {
"small": "https://api.servicetrade.com/image/avatar-small.png",
"medium": "https://api.servicetrade.com/image/avatar-medium.png",
"large": "https://api.servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
}
},
{
"uri": "http://api.servicetrade.com/api/comment/95",
"id": 95,
"content": "Service Request Comment (Job).",
"created": 1327099932,
"updated": 1327099932,
"visibility": ["public"],
"entity": {
"uri": "http://api.servicetrade.com/api/servicerequest/153",
"id": 153,
"type": 18
},
"author": {
"id": 21,
"uri": "http://api.servicetrade.com/api/user/21",
"name": "Joe User",
"status": "active",
"email": "uuxiiuit+standalone@gmail.com",
"avatar": {
"small": "http://api.servicetrade.com/image/avatar-small.png",
"medium": "http://api.servicetrade.com/image/avatar-medium.png",
"large": "http://api.servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
}
},
]
}
Retrieve job comments created in a time range
GET /comment?&entityType=3&createdAfter=1327035600&createdBefore=1327122000
200
{
"totalPages": 1,
"page": 1,
"comments": [
{
"uri": "https://api.servicetrade.com/api/comment/10",
"id": 10,
"content": "This job needs more work.",
"created": 1327082916,
"updated": 1327082916,
"visibility": ["public"],
"entity": {
"uri": "https://api.servicetrade.com/api/job/41",
"id": 41,
"type": 3
},
"author": {
"uri": "https://api.servicetrade.com/api/user/6",
"id": 6,
"name": "Joe User",
"status": "active",
"avatar": {
"small": "https://api.servicetrade.com/image/avatar-small.png",
"medium": "https://api.servicetrade.com/image/avatar-medium.png",
"large": "https://api.servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
}
},
{
"uri": "https://api.servicetrade.com/api/comment/23",
"id": 23,
"content": "May require a return visit.",
"created": 1327089932,
"updated": 1327082916,
"visibility": ["public","tech"],
"entity": {
"uri": "https://api.servicetrade.com/api/job/43",
"id": 43,
"type": 3
},
"author": {
"uri": "https://api.servicetrade.com/api/user/6",
"id": 21,
"name": "Stan Dalone",
"status": "active",
"avatar": {
"small": "https://api.servicetrade.com/image/avatar-small.png",
"medium": "https://api.servicetrade.com/image/avatar-medium.png",
"large": "https://api.servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
}
}
]
}
Retrieve comment 10
GET /comment/10
200
{
"data": {
"uri": "https://api.servicetrade.com/api/comment/10",
"id": 10,
"content": "This job needs more work.",
"created": 1327082916,
"updated": 1327082916,
"visibility": ["public"],
"entity": {
"uri": "https://api.servicetrade.com/api/job/41",
"id": 41,
"type": 3
},
"author": {
"uri": "https://api.servicetrade.com/api/user/6",
"id": 6,
"name": "Joe User",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
}
}
}
Create comment, not providing entity information
POST /comment
{"content":"This job needs more work."}
403
{
"messages": {
"error": [
"Invalid Entity ID for comment"
]
}
}
Create comment
POST /comment
{"entityId":41, "entityType":3, "content":"This job needs more work.", "visibility":["tech"]}
200
{
"data": {
"uri": "https://api.servicetrade.com/api/comment/10",
"id": 10,
"content": "This job needs more work.",
"created": 1327082916,
"updated": 1327082916,
"visibility": ["tech"],
"entity": {
"uri": "https://api.servicetrade.com/api/job/41",
"id": 41,
"type": 3
},
"author": {
"uri": "https://api.servicetrade.com/api/user/6",
"id": 6,
"name": "Joe User",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
}
}
}
Update comment visibility flags
PUT /comment/10
{"visibility":["public","tech"]}
200
{
"data": {
"uri": "https://api.servicetrade.com/api/comment/10",
"id": 10,
"content": "This job needs more work.",
"created": 1327082916,
"updated": 1327082916,
"visibility": ["public","tech"],
"entity": {
"uri": "https://api.servicetrade.com/api/job/41",
"id": 41,
"type": 3
},
"author": {
"uri": "https://api.servicetrade.com/api/user/6",
"id": 6,
"name": "Joe User",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
}
}
}
Delete comment 10
DELETE /comment/10
204
Return to Top
Company
The company resource is used to retrieve lists of companys or detailed information about a single company.
- Resource URL: /company/[companyId]
- Available Verbs: GET, POST, PUT, DELETE
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/company |
200 |
|
GET |
/company/123 |
200 |
|
GET |
/company/123 |
404 |
company 123 not found |
GET |
/company/123/comment |
200 |
retrieve list of comments |
GET |
/company/123/comment/67 |
200 |
retrieve comment info |
POST |
/company |
200 |
|
POST |
/company |
400 |
malformed request |
POST |
/company |
403 |
not allowed |
POST |
/company/123/comment |
200 |
create a comment - see Comment for details |
POST |
/company/123/merge |
200 |
merge a company into another |
POST |
/company/123/merge |
403 |
no permission |
POST |
/company/123/merge |
400 |
invalid params |
PUT |
/company |
200 |
|
PUT |
/company |
400 |
malformed request |
PUT |
/company |
403 |
not allowed |
PUT |
/company |
404 |
company not found |
DELETE |
/company/123 |
204 |
company deleted |
DELETE |
/company/123 |
403 |
do not have permission to do this |
DELETE |
/company/123 |
404 |
company not found |
DELETE |
/company/123 |
409 |
cannot delete company because it has associated |
Query Params
Name |
Type |
Value |
name |
string |
returns all companies whose name includes this string (case insensitive) |
refNumber |
string |
returns all companies with this reference number as an exact match |
city |
string |
returns all companies whose city includes this string (case insensitive) |
state |
string |
returns all companies whose 2-letter state abbreviation is equal to this string (case insensitive) |
postalCode |
string |
returns all companies whose postal code includes this string (case insensitive) |
isVendor |
boolean |
returns only companies who are listed as service vendors |
isPartsVendor |
boolean |
returns only companies who are listed as parts vendors |
isCustomer |
boolean |
returns only companies who are listed as customers |
isContractor |
boolean |
returns only companies who are listed as vendors or prime contractors |
isContractee |
boolean |
returns only companies who are listed as customers or prime contractors |
status |
string |
one of ('active', 'pending', 'inactive', 'on_hold') |
createdBefore |
integer |
timestamp, matches records created on or before |
createdAfter |
integer |
timestamp, matches records created on or after |
updatedBefore |
integer |
timestamp, matches records updated on or before |
updatedAfter |
integer |
timestamp, matches records updated on or after |
tag |
string |
comma-separated list of tag strings, only companies with all tags will be returned |
officeId |
string |
comma-separated list of integers, only companies with at least one location assigned to any of given offices will be returned |
PUT/POST Parameters
Name |
Required |
Type |
Value |
name |
for POST |
string |
The name of the company |
refNumber |
no |
string |
Reference number for identifying this company. This reference number is set automatically if not specified, using a counter that increments by 1 for each new company created without specifying a reference number. Companies created before this field existed will have a refNumber that matches the id, unless it is updated later by the User. |
address |
for POST |
Address |
Overrides individual address fields |
addressStreet |
no |
string |
The street of the address for the company (alias for address.street) |
addressCity |
no |
string |
The city of the address for the company (alias for address.city) |
addressState |
no |
string |
The state of the address for the company (alias for address.state) |
addressPostalCode |
no |
string |
The postal code of the address for the company (alias for address.postalCode) |
customer |
no |
boolean |
Is this company a customer? True by default. |
vendor |
no |
boolean |
Is this company a service vendor? False by default. |
partsVendor |
no |
boolean |
Is this company a parts vendor? False by default. |
primeContractor |
no |
boolean |
Is this company a prime contractor? False by default. |
phoneNumber |
no |
string |
Phone number contact for the company. |
status |
no |
string |
one of ('active', 'pending', 'inactive', 'on_hold'), 'active' is the default |
Merge Parameters
The merge endpoint replaces this company (the loser) with another (the winner) on all entities that are assigned the losing company. The loser is then deleted.
Name |
Type |
Required |
Value |
replacementId |
integer |
Yes |
the id of the company you wish to merge this company into, the "winner" |
Returned Elements
Name |
Type |
Value |
companies |
array (Company) |
list of company objects |
status |
string |
status of company |
customer |
boolean |
company is sometimes a customer |
vendor |
boolean |
company is sometimes a service vendor |
partsVendor |
boolean |
company is sometimes a parts vendor |
primeContractor |
boolean |
company is sometimes a prime contractor |
shareId |
integer |
shared id for companies joined across accounts |
managingAccount |
Account |
if company is managed by another ServiceTrade account, the name and id of that account |
address |
Address |
|
phoneNumber |
string |
company phone number |
serviceLinesProvided |
array (Service Line) |
for vendor companies, the list of service lines that vendor provides |
externalIds |
object |
a key/value object of external system ids, only returned if account has external integrations defined |
defaultBrand |
Brand |
the default brand to associate with activity at this company |
logo |
object |
logo attachment, if there is one, object or null for none |
logo.id |
integer |
logo attachment id |
logo.uri |
string |
logo attachment uri |
logo.contentUrl |
string |
logo attachment's content url (location of the actual image) |
logo.aspect |
string |
"tall" or "wide", tall if the aspect ratio is tall or exactly correct, wide if it is wide. The expected ratio is 2.71875 |
tags |
array (Tag) |
array of tags |
created |
integer |
Unix timestamp of this record's creation time |
updated |
integer |
Unix timestamp of when this record was last updated |
Retrieve all companies that match a given name
GET /company?name=pro
200
{
"data": {
"totalPages": 1,
"page": 1,
"companies": [
{
"uri": "https://api.servicetrade.com/api/company/11",
"id": 11,
"refNumber": "11",
"name": "Professional Fire Services",
"status": "active",
"customer": false,
"vendor": true,
"partsVendor": false,
"primeContractor": false,
"shareId": null,
"address": {
"street": "107 Arcadia Street",
"city": "Hewitt",
"state": "TX",
"postalCode": "76643"
},
"serviceLinesProvided": [
{
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "https://api.servicetrade.com/image/icons/service_lines/32/SUPP.png"
},
{
"id": 3,
"name": "Portable Extinguishers",
"trade": "Fire Protection",
"abbr": "EXT",
"icon": "https://api.servicetrade.com/image/icons/service_lines/32/EXT.png"
}
],
"phoneNumber": "555-555-5555",
"defaultBrand": null,
"logo": {
"id": 7,
"uri": "https://api.servicetrade.com/api/attachment/7",
"contentUrl": "https://s3.amazonaws.com/servicetrade-attachments/7_f73b7e20c14a80420c270b8311e0d9a4.png",
"aspect": "tall"
},
"tags": [],
"created": 1399993795,
"updated": 1399994065
},
{
"uri": "https://api.servicetrade.com/api/company/12",
"id": 12,
"refNumber": "12",
"name": "Fire Prevention Pros, Inc.",
"status": "active",
"customer": false,
"vendor": true,
"partsVendor": false,
"primeContractor": false,
"shareId": 43363,
"address": {
"street": "PO. Box 89768",
"city": "Augusta",
"state": "GA",
"postalCode": "30906"
},
"serviceLinesProvided": [
{
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "https://api.servicetrade.com/image/icons/service_lines/32/SUPP.png"
},
{
"id": 6,
"name": "Backflow",
"trade": "Fire Protection",
"abbr": "BF",
"icon": "https://api.servicetrade.com/image/icons/service_lines/32/BF.png"
}
],
"phoneNumber": "555-555-5555",
"defaultBrand": null,
"logo": null,
"tags": [],
"created": 1399993795,
"updated": 1399994065
}
]
}
}
No company matches found
GET /company?name=ygiuygiug
200
{
"data": {
"totalPages": 1,
"page": 1,
"companies": []
}
}
Retrieve information for a single company
GET /company/33
200
{
"data": {
"uri": "https://api.servicetrade.com/api/company/6",
"id": 33,
"refNumber": "33",
"name": "Wet Blanket Fire Prevention",
"status": "active",
"customer": false,
"vendor": true,
"partsVendor": false,
"primeContractor": false,
"shareId": null,
"address": {
"street": "7501 Capital Blvd, STE 250",
"city": "AUSTIN",
"state": "TX",
"postalCode": "78735"
},
"serviceLinesProvided": [
{
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "https://api.servicetrade.com/image/icons/service_lines/32/SUPP.png"
}
],
"phoneNumber": "555-555-5555",
"defaultBrand": null,
"logo": null,
"tags": [],
"externalIds": {
"system_one": "BD-523"
},
"created": 1399993795,
"updated": 1399994065
}
}
Retrieve information for a company which does not exist
GET /company/987
404
Create a new company
POST /company
{"name": "Buystuff Inc", "addressStreet": "202 Retail Lane", "addressCity": "Cary", "addressState": "NC", "addressPostalCode": "27513"}
200
{
"data": {
"id": 257,
"refNumber": "257",
"uri": "https://api.servicetrade.com/api/company/257",
"name": "Buystuff Inc",
"status": "active",
"customer": true,
"vendor": false,
"partsVendor": false,
"primeContractor": false,
"managingAccount": null,
"shareId": null,
"address": {
"street": "202 Retail Lane",
"city": "Cary",
"state": "NC",
"postalCode": "27513"
},
"serviceLinesProvided": [],
"phoneNumber": null,
"defaultBrand": null,
"logo": null,
"tags": [],
"created": 1399993795,
"updated": 1399994065
}
}
Merge a company into another
POST /company/123/merge
{"replacementId": 456}
200
{
"data": {
"id": 456,
"refNumber": "456",
"uri": "https://api.servicetrade.com/api/company/456",
"name": "Buystuff Inc",
"status": "active",
"customer": true,
"vendor": false,
"partsVendor": false,
"primeContractor": false,
"managingAccount": null,
"shareId": null,
"address": {
"street": "202 Retail Lane",
"city": "Cary",
"state": "NC",
"postalCode": "27513"
},
"phoneNumber": null,
"serviceLinesProvided": [],
"defaultBrand": null,
"logo": null,
"tags": [],
"created": 1606319030,
"updated": 1606319030
}
}
Return to Top
Contact
The contact resource is used to retrieve lists of contacts or detailed information about a single contact.
- Resource URL: /contact/[contactId]
- Available Verbs: GET, POST, PUT, DELETE
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/contact |
200 |
|
GET |
/contact/123 |
200 |
|
POST |
/contact |
200 |
|
POST |
/contact |
400 |
missing, incomplete or invalid parameters |
POST |
/contact |
403 |
do not have permission to do this |
POST |
/contact/123/merge |
200 |
merge a contact into another |
POST |
/contact/123/merge |
403 |
no permission |
POST |
/contact/123/merge |
400 |
invalid params |
PUT |
/contact/123 |
200 |
|
PUT |
/contact/123 |
400 |
missing, incomplete or invalid parameters |
PUT |
/contact/123 |
403 |
do not have permission to do this |
PUT |
/contact/123 |
404 |
contact 123 not found |
PUT |
/contact/123 |
409 |
attempted to make inconsistent change, such as removing a contact from a location where it is the primary contact |
DELETE |
/contact |
405 |
not allowed |
POST |
/contact/123/location/456 |
200 |
contact associated with location |
PUT |
/contact/123/location/456 |
200 |
contact associated with location |
DELETE |
/contact/123/location/456 |
200 |
contact no longer associated with location |
POST |
/contact/123/company/456 |
200 |
contact associated with company |
PUT |
/contact/123/company/456 |
200 |
contact associated with company |
DELETE |
/contact/123/company/456 |
200 |
contact no longer associated with company |
Query Params
Name |
Type |
Value |
companyId |
integer |
Return only contacts belonging to the company with this id or one of its locations. To only include contacts directly related to the company, also include a locationId parameter set to the empty string (see example titled "Get all contacts assigned diectly to a specific company. Excludes location only contacts."). |
locationId |
integer |
return only contacts belonging to the location with this id |
search |
string |
match against contact name, phone numbers, or email address |
email |
string |
exact match against contact email address |
updatedAfter |
integer |
return only contacts whose last update time is on or after the given timestamp |
updatedBefore |
integer |
return only contacts whose last update time is on or before the given timestamp |
createdBefore |
integer |
returns only contacts created on or before the given timestamp |
createdAfter |
integer |
returns only contacts created on or after the given timestamp |
POST/PUT Parameters
Name |
Type |
Value |
companyIds |
array |
(optional) ids of company to which this contact belongs |
locationIds |
array |
(optional) ids of location to which this contact belongs |
status |
string |
(optional) one of ('public','private','inactive') Defaults to 'private' |
type |
string |
user type, free form string describing what type of contact this is |
firstName |
string |
contact first name |
lastName |
string |
contact last name |
phone |
string |
(optional) contact phone |
mobile |
string |
(optional) contact mobile |
alternatePhone |
string |
(optional) contact alternate phone |
email |
string |
(optional) contact email |
companyId |
integer |
DEPRECATED (optional) id of company to which this contact belongs |
locationId |
integer |
DEPRECATED (optional) id of location to which this contact belongs. Only a location relationship will be created if both companyId and locationId are provided |
Merge Parameters
The merge endpoint replaces this contact (the loser) with another (the winner) on all entities that are assigned the losing contact. The loser is then deleted.
Name |
Type |
Required |
Value |
replacementId |
integer |
Yes |
the id of the contact you wish to merge this contact into, the "winner" |
Returned Elements
Name |
Type |
Value |
contacts |
array (Contact) |
array of contacts |
status |
string |
status, of ('public','private','inactive') |
companies |
array of Company |
list of companies the contact is directly assigned to |
locations |
array of Location |
list of locations the contact is assigned to |
company |
Company |
contact company DEPRECATED |
location |
Location |
contact location DEPRECATED |
externalIds |
object |
a key/value object of external system ids, only returned if account has external integrations defined |
Get all contacts assigned to a specific location
GET /contact?locationId=14
200
{
"data": {
"totalPages": 1,
"page": 1,
"contacts": [
{
"id": 14,
"uri": "https://api.servicetrade.com/api/contact/14",
"firstName": "Ted",
"lastName": "Smith",
"phone": "530-867-5309",
"mobile": "",
"alternatePhone": "",
"email": "uuxiiuit+neal@gmail.com",
"type": "management",
"companies" : [],
"locations" : [
{
"id": 14,
"uri": "https://api.servicetrade.com/api/location/14",
"name": "Cato #11297 - Vienna",
"legacyId": null,
"lat": 39.305294,
"lon": -81.550631,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "605 Grand Central Avenue, Unit 104",
"city": "Vienna",
"state": "WV",
"postalCode": "26105"
},
"taxable": false
}
],
"company": {
"id": 3,
"uri": "https://api.servicetrade.com/api/company/3",
"name": "Cato Corporation"
},
"location": {
"id": 14,
"uri": "https://api.servicetrade.com/api/location/14",
"name": "Cato #11297 - Vienna",
"legacyId": null,
"lat": 39.305294,
"lon": -81.550631,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "605 Grand Central Avenue, Unit 104",
"city": "Vienna",
"state": "WV",
"postalCode": "26105"
},
"taxable": false,
"status": "active"
},
"status": "private",
"created": 1347915466,
"updated": 1347915466,
"externalIds": {
"peachtree": "332-FOOSBAR",
"salesforce": "na1.salesforce.com/01I90000000jOLr"
}
}
]
}
}
Get all contacts assigned to a specific company or one of its locations
GET /contact?companyId=5
200
{
"data": {
"totalPages": 1,
"page": 1,
"contacts": [
{
"id": 27,
"uri": "https://api.servicetrade.com/api/contact/27",
"firstName": "Marty",
"lastName": "Bites",
"phone": "520-867-5309",
"mobile": "",
"alternatePhone": "",
"email": "uuxiiuit+neal@gmail.com",
"type": "management",
"companies" : [],
"locations" : [
{
"id": 25,
"uri": "https://api.servicetrade.com/api/location/25",
"name": "Cook Out #70 - Indian Trail",
"legacyId": null,
"lat": 35.039462,
"lon": -80.605065,
"alternatePhone": "",
"email": "",
"primaryContact": null,
"address": {
"street": "13703 B Hwy 74",
"city": "Indian Trail",
"state": "NC",
"postalCode": "28079"
},
"taxable": false
}
],
"company": {
"id": 5,
"uri": "https://api.servicetrade.com/api/company/5",
"name": "Cook Out"
},
"location": {
"id": 25,
"uri": "https://api.servicetrade.com/api/location/25",
"name": "Cook Out #70 - Indian Trail",
"legacyId": null,
"lat": 35.039462,
"lon": -80.605065,
"alternatePhone": "",
"email": "",
"primaryContact": null,
"address": {
"street": "13703 B Hwy 74",
"city": "Indian Trail",
"state": "NC",
"postalCode": "28079"
},
"taxable": false,
"status": "active"
},
"status": "private",
"externalIds": {
"peachtree": "332-FOOSBAR",
"salesforce": "na1.salesforce.com/01I90000000jOLr"
}
},
{
"id": 28,
"uri": "https://api.servicetrade.com/api/contact/28",
"firstName": "Marty",
"lastName": "Bites",
"phone": "520-867-5309",
"mobile": "",
"alternatePhone": "",
"email": "uuxiiuit+neal@gmail.com",
"type": "management",
"companies" : [],
"locations" : [
{
"id": 26,
"uri": "https://api.servicetrade.com/api/location/26",
"name": "Cook Out #75 - Lenoir",
"legacyId": null,
"lat": 35.922314,
"lon": -81.524935,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "510 Blowing Rock Blvd NE",
"city": "Lenoir",
"state": "NC",
"postalCode": "28645"
},
"taxable": false
}
],
"company": {
"id": 5,
"uri": "https://api.servicetrade.com/api/company/5",
"name": "Cook Out"
},
"location": {
"id": 26,
"uri": "https://api.servicetrade.com/api/location/26",
"name": "Cook Out #75 - Lenoir",
"legacyId": null,
"lat": 35.922314,
"lon": -81.524935,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "510 Blowing Rock Blvd NE",
"city": "Lenoir",
"state": "NC",
"postalCode": "28645"
},
"taxable": false,
"status": "active"
},
"status": "private",
"created": 1347915466,
"updated": 1347915466,
"externalIds": {
"peachtree": "332-FOOSBAR@",
"salesforce": "na1.salesforce.com/01I90000000jOLr2"
}
}
]
}
}
Get all contacts assigned diectly to a specific company. Excludes location only contacts.
GET /contact?companyId=5&locationId=
200
{
"data": {
"totalPages": 1,
"page": 1,
"contacts": [
{
"id": 28,
"uri": "https://api.servicetrade.com/api/contact/28",
"firstName": "Marty",
"lastName": "Bites",
"phone": "520-867-5309",
"mobile": "",
"alternatePhone": "",
"email": "uuxiiuit+neal@gmail.com",
"type": "management",
"companies" : [
{
"id": 5,
"uri": "https://api.servicetrade.com/api/company/5",
"name": "Cook Out"
},
],
"locations" : [
{
"id": 26,
"uri": "https://api.servicetrade.com/api/location/26",
"name": "Cook Out #75 - Lenoir",
"legacyId": null,
"lat": 35.922314,
"lon": -81.524935,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "510 Blowing Rock Blvd NE",
"city": "Lenoir",
"state": "NC",
"postalCode": "28645"
},
"taxable": false
}
],
"company": {
"id": 5,
"uri": "https://api.servicetrade.com/api/company/5",
"name": "Cook Out"
},
"location": {
"id": 26,
"uri": "https://api.servicetrade.com/api/location/26",
"name": "Cook Out #75 - Lenoir",
"legacyId": null,
"lat": 35.922314,
"lon": -81.524935,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "510 Blowing Rock Blvd NE",
"city": "Lenoir",
"state": "NC",
"postalCode": "28645"
},
"taxable": false,
"status": "active"
},
"status": "private",
"created": 1347915466,
"updated": 1347915466,
"externalIds": {
"peachtree": "332-FOOSBAR",
"salesforce": "na1.salesforce.com/01I90000000jOLr"
}
}
]
}
}
Retrieve information for a contact which does not exist
GET /contact/987
404
Create a new contact
POST /contact
{"companyIds": [5], "locationIds": [28], "type": "sales", "firstName": "Marco", "lastName": "Polo", "phone": "111-222-3333", "email": "marco.polo@email.com", "status": "public"}
200
{
"data": {
"id": 130,
"uri": "https://api.servicetrade.com/api/contact/130",
"firstName": "Marco",
"lastName": "Polo",
"phone": "111-222-3333",
"mobile": "",
"alternatePhone": "",
"email": "marco.polo@email.com",
"type": "sales",
"companies" : [],
"locations" : [
{
"id": 28,
"uri": "https://api.servicetrade.com/api/location/28",
"name": "Johnny Carino's #048 - San Antonio Bandera",
"legacyId": null,
"lat": 29.551518,
"lon": -98.666403,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "11719 Bandera Rd.",
"city": "San Antonio",
"state": "TX",
"postalCode": "78250"
},
"taxable": false
}
],
"company": {
"id": 5,
"uri": "https://api.servicetrade.com/api/company/5",
"name": "Cook Out"
},
"location": {
"id": 28,
"uri": "https://api.servicetrade.com/api/location/28",
"name": "Johnny Carino's #048 - San Antonio Bandera",
"legacyId": null,
"lat": 29.551518,
"lon": -98.666403,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "11719 Bandera Rd.",
"city": "San Antonio",
"state": "TX",
"postalCode": "78250"
},
"taxable": false,
"status": "active"
},
"status": "public",
"created": 1347915466,
"updated": 1347915466
}
}
Modify values on an existing contact
PUT /contact/130
{"type": "management", "firstName": "Mark", "status": "private"}
200
{
"data": {
"id": 130,
"uri": "https://api.servicetrade.com/api/contact/130",
"firstName": "Mark",
"lastName": "Polo",
"phone": "111-222-3333",
"mobile": "",
"alternatePhone": "",
"email": "marco.polo@email.com",
"type": "management",
"companies" : [],
"locations" : [
{
"id": 28,
"uri": "https://api.servicetrade.com/api/location/28",
"name": "Johnny Carino's #048 - San Antonio Bandera",
"legacyId": null,
"lat": 29.551518,
"lon": -98.666403,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "11719 Bandera Rd.",
"city": "San Antonio",
"state": "TX",
"postalCode": "78250"
},
"taxable": false
}
],
"company": {
"id": 5,
"uri": "https://api.servicetrade.com/api/company/5",
"name": "Cook Out"
},
"location": {
"id": 28,
"uri": "https://api.servicetrade.com/api/location/28",
"name": "Johnny Carino's #048 - San Antonio Bandera",
"legacyId": null,
"lat": 29.551518,
"lon": -98.666403,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "11719 Bandera Rd.",
"city": "San Antonio",
"state": "TX",
"postalCode": "78250"
},
"taxable": false,
"status": "active"
},
"status": "private",
"created": 1347915466,
"updated": 1347915466,
"externalIds": {
"peachtree": "332-FOOSBAR",
"salesforce": "na1.salesforce.com/01I90000000jOLr"
}
}
}
}
Merge a contact into another
POST /api/contact/123/merge
{"replacementId": 456}
200
{
"data": {
"id": 456,
"uri": "https://api.servicetrade.com/api/contact/456",
"firstName": "Rusty",
"lastName": "LaRue",
"phone": "252-522-2224",
"mobile": "",
"alternatePhone": "89217776644",
"email": "test@email.com",
"type": "management",
"companies": [],
"locations": [
{
"id": 76,
"uri": "https://api.servicetrade.com/api/location/76",
"name": "Hwy 55 Burgers - Kinston 1",
"refNumber": "9",
"legacyId": null,
"lat": 35.261827,
"lon": -77.647204,
"phoneNumber": "(252) 522-2224",
"email": "uuxiiuit+location@gmail.com",
"primaryContact": {
"id": 76,
"uri": "https://api.servicetrade.com/api/contact/76",
"firstName": "Rusty",
"lastName": "LaRue",
"phone": "252-522-2224",
"mobile": "",
"alternatePhone": "89217776644",
"email": "test@email.com",
"type": "management"
},
"address": {
"street": "4130 West Vernon Ave",
"city": "Kinston",
"state": "NC",
"postalCode": "28504"
},
"taxable": false,
"status": "active"
}
],
"company": {
"id": 36,
"uri": "https://api.servicetrade.com/api/company/36",
"name": "Hwy 55 Burgers"
},
"location": {
"id": 76,
"uri": "https://api.servicetrade.com/api/location/76",
"name": "Hwy 55 Burgers - Kinston 1",
"refNumber": "9",
"legacyId": null,
"lat": 35.261827,
"lon": -77.647204,
"phoneNumber": "(252) 522-2224",
"email": "uuxiiuit+location@gmail.com",
"primaryContact": {
"id": 76,
"uri": "https://api.servicetrade.com/api/contact/76",
"firstName": "Rusty",
"lastName": "LaRue",
"phone": "252-522-2224",
"mobile": "",
"alternatePhone": "89217776644",
"email": "test@email.com",
"type": "management"
},
"address": {
"street": "4130 West Vernon Ave",
"city": "Kinston",
"state": "NC",
"postalCode": "28504"
},
"taxable": false,
"status": "active"
},
"status": "private",
"created": 1639640905,
"updated": 1640084725,
"externalIds": {
"fattmerchant": "",
"peachtree": ""
}
}
}
Return to Top
Contract
The contract resource is used to retrieve lists of contracts or detailed information about a single contract.
- Resource URL: /contract/[contractId]
- Available Verbs: GET, POST, PUT
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/contract |
405 |
not allowed |
GET |
/contract/123 |
200 |
|
GET |
/contract/123 |
404 |
contract 123 not found (or not accessible by the user) |
GET |
/contract/123/accept |
405 |
not allowed |
GET |
/contract?contractorId=123&locationId=456 |
200 |
|
GET |
/contract?contractorId=123&locationId=456 |
404 |
no contracts found valid for this combination |
POST |
/contract |
200 |
|
POST |
/contract |
400 |
Invalid request |
POST |
/contract |
404 |
job or quote for contract not found (or not accessible by the user) |
POST |
/contract/123/accept |
200 |
|
POST |
/contract/123/accept |
404 |
contract 123 not found (or not accessible by the user) |
POST |
/contract/123/copy |
200 |
|
POST |
/contract/123/copy |
404 |
contract 123 not found (or not accessible by the user) |
POST |
/contract/123/child |
200 |
|
POST |
/contract/123/child |
404 |
contract 123 not found (or not accessible by the user) |
PUT |
/contract/123 |
200 |
|
PUT |
/contract/123 |
400 |
Invalid request |
PUT |
/contract/123 |
403 |
No permissions |
PUT |
/contract/123 |
404 |
contract 123 not found |
DELETE |
/contract |
405 |
not allowed |
POST |
/contract/123/deactivate |
204 |
|
POST |
/contract/123/deactivate |
404 |
contract not found |
POST |
/contract/123/deactivate |
403 |
not permissioned |
POST Parameters for quote contracts
Name |
Type |
Value |
quoteId |
integer |
quote or proposal that this contract is for |
jobId |
integer |
job that was created for the given quote |
POST Parameters for default, company, and template contracts
Name |
Type |
Required for |
Value |
type |
string |
all |
type of contract, one of: default, company, template |
name |
string |
all |
name of contract |
vendorId |
integer |
default, company |
Vendor company id on contract |
customerId |
integer |
company |
Customer company id on contract |
startsOn |
integer |
optional |
Unix timestamp for when the contract takes effect |
expiresOn |
integer |
optional |
Unix timestamp for when the contract expires |
reviewOn |
integer |
optional |
Unix timestamp for when the contract should be reviewed |
ownerId |
integer |
optional |
User id owner of the contract or null if there isn't one |
salesId |
integer |
optional |
User id salesperson associated with the contract or null if there isn't one |
active |
boolean |
optional |
is contract active? defaults to true |
parentId |
integer |
optional |
id of the parent contract |
regionId |
integer |
optional |
if given, contract will only apply to jobs in this region |
officeId |
integer |
optional |
if given, contract will only apply to locations for this office |
locationId |
integer |
optional |
if given, contract will only apply to this location. Only valid for company contracts |
jobType |
string |
optional |
if given, contract will only apply for this job type |
description |
string |
optional |
freeform text description of this contract |
expectedRevenue |
float |
optional |
The revenue you expect this contract to generate over the course of its life |
expectedMargin |
float |
optional |
The margin you expect this contract to generate over the course of its life, as a percentage |
customerPo |
string |
optional |
customer purchase order number for this contract |
jobTermsId |
integer |
optional |
if given, terms will apply by default for jobs for this contract |
quoteTermsId |
integer |
optional |
if given, terms will apply by default for quotes for this contract |
invoiceTermsId |
integer |
optional |
if given, terms will apply by default for invoices for this contract |
invoiceNotes |
string |
optional |
invoices created using this contract will have these notes copied to them |
paymentTermsId |
integer |
optional |
if given, payment terms will apply by default for invoices for this contract |
invoiceDetailLevel |
array(string) |
optional |
default Detail Level applied for Invoices in scope of contract. Subset of ("public", "items", "noprices", "items_by_type", "type_detail") |
quoteDetailLevel |
array(string) |
optional |
default Detail Level applied for Quotes in scope of contract Subset of ("public", "items", "noprices", "time_and_materials", "by_type", "type_detail") |
POST Parameters for deactivate
Name |
Type |
Required |
Value |
cancelServices |
boolean |
optional |
if given will cancel related serviceRequests for contract when deactivating it |
cancelJobs |
boolean |
optional |
if given will cancel related jobs for contract when deactivating it |
cancelQuotes |
boolean |
optional |
if given will cancel related quotes for contract when deactivating it |
cancelRecurringInvoices |
boolean |
optional |
if given will cancel related recurringInvoices for contract when deactivating it |
PUT Parameters for default, company, and template contracts
Name |
Type |
Value |
name |
string |
name of contract |
vendorId |
integer |
Vendor company id on contract (only allowed on types default and company) |
customerId |
integer |
Customer company id on contract (only allowed on type company) |
startsOn |
integer |
Unix timestamp for when the contract takes effect |
expiresOn |
integer |
Unix timestamp for when the contract expires |
reviewOn |
integer |
Unix timestamp for when the contract should be reviewed |
ownerId |
integer |
User id owner of the contract or null if there isn't one |
salesId |
integer |
User id salesperson associated with the contract or null if there isn't one |
active |
boolean |
is contract active? defaults to true |
parentId |
integer |
id of the parent contract |
regionId |
integer |
if given, contract will only apply to jobs in this region |
officeId |
integer |
if given, contract will only apply to locations for this office |
locationId |
integer |
if given, contract will only apply to this location. Only valid for company contracts |
jobType |
string |
if given, contract will only apply for this job type |
description |
string |
freeform text description of this contract |
expectedRevenue |
float |
The revenue you expect this contract to generate over the course of its life |
expectedMargin |
float |
The margin you expect this contract to generate over the course of its life, as a percentage |
jobTermsId |
integer |
if given, terms will apply by default for jobs for this contract |
quoteTermsId |
integer |
if given, terms will apply by default for quotes for this contract |
invoiceTermsId |
integer |
if given, terms will apply by default for invoices for this contract |
paymentTermsId |
integer |
if given, payment terms will apply by default for invoices for this contract |
invoiceNotes |
string |
invoices created using this contract will have these notes copied to them |
invoiceDetailLevel |
array(string) |
default Detail Level applied for Invoices in scope of contract. Subset of ("public", "items", "noprices", "items_by_type", "type_detail") |
quoteDetailLevel |
array(string) |
default Detail Level applied for Quotes in scope of contract. Subset of ("public", "items", "noprices", "time_and_materials", "by_type", "type_detail") |
Query Params
Name |
Type |
Required/Notes |
Value |
jobId |
integer |
returns available contracts for this job, overrides all other query parameters |
job id |
vendorId |
integer |
must provide jobId, vendorId, or customerId |
vendor company id |
contractorId |
integer |
Deprecated, alias for vendorId |
vendor company id |
customerId |
integer |
must provide jobId, vendorId, or customerId |
customer company id |
contracteeId |
integer |
Deprecated, alias for customerId |
customer company id |
parentId |
integer |
returns child contracts of given contractId |
contract id |
possibleParentOf |
integer |
must be an existing contractId, will return a list of contracts that could be assigned as its parent |
contract id |
locationId |
integer |
no |
location id |
jobType |
string |
return only contracts that apply for this job type. Ignored if no locationId is given |
|
allMatches |
boolean |
return all contracts that might apply, not just the most specific ones. Ignored if no locationId is given. |
|
salesId |
integer |
comma-separated list of integer ids of the user assigned as the salesperson of this contract |
salesperson user id |
tag |
string |
comma-separated list of tag strings, only contracts with all tags will be returned |
|
name |
string |
return contracts whose name match this substring |
|
reviewOnAfter |
integer |
review on or after this timestamp |
|
reviewOnBefore |
integer |
review on or before this timestamp |
|
Note: Requests with a jobId will only return the most specific contracts that match all the supplied criteria.
Requests with a locationId will only return the most specific contracts that match all the supplied criteria, unless allMatches is true, in which case all contract that might apply are returned (including default contracts in cases where more specific contracts also are returned). If both a locationId and a jobType are provided, only contracts applying to the given job type are returned. If a locationId is provided but a jobType is not provided, contracts that might apply to any type of job at that location are returned.
Returned Elements
Name |
Type |
Value |
contracts |
array (object) |
list of contract objects |
id |
integer |
id of the contract |
uri |
string |
resource identifier of the contract |
name |
string |
name of the contract |
customer |
Company |
customer on the contract or null if there isn't one |
vendor |
Company |
vendor on the contract or null if there isn't one |
parent |
Contract |
contract parent or null if there isn't one |
type |
string |
The type of contract, one of: default, company, addendum, template |
startsOn |
integer |
Unix timestamp of when the contract takes effect |
expiresOn |
integer |
Unix timestamp of when the contract expires |
reviewOn |
integer |
Unix timestamp for when the contract should be reviewed |
owner |
User |
owner of the contract or null if there isn't one |
sales |
User |
salespers associated with the contract or null if there isn't one |
region |
Region |
contract only applies to jobs in this region or null for all regions |
office |
Location |
contract only applies to locations for this office or null for all offices |
locationContext |
string |
location context to which this contract applies; one of: "location" (a single location), "entityFilter" (a list of locations described by the contract's entityFilter), "all" (all locations for contract customer). The location context may be further limited by other contract properties (region, office, jobType, etc.) |
location |
Location |
contract only applies to this location or null for all locations |
entityFilter |
Entityfilter |
contract only applies to the locations in this entity filter, or null for all locations |
jobType |
string |
contract only applies for this job type or null for all job types |
active |
boolean |
is this contract active? |
accepted |
boolean |
indicates that we successfully accepted the contract (accept action only) |
externalIds |
object |
a key/value object of external system ids, only returned if account has external integrations defined |
description |
string |
freeform text description of this contract |
expectedRevenue |
float |
The revenue you expect this contract to generate over the course of its life |
expectedMargin |
float |
The margin you expect this contract to generate over the course of its life, as a percentage |
totalCost |
float |
The sum of all costs of all job items on all non-canceled, completed jobs associated with that contract |
allItemsHaveCosts |
boolean |
True if every job item on every non-canceled job associated with the contract has a non-null cost; false if at least one job item has a null cost. |
actualMargin |
float |
Actual margin percentage, based on revenue and totalCost |
customerPo |
string |
customer purchase order number for this contract |
revenue |
float |
total revenue of the contract or NULL if it has not been calculated yet |
revenueAsOf |
integer |
timestamp for which revenue is accurate |
tags |
array of Tag |
array of tags |
complexity |
string |
"simple" or "complex" to indicate contract complexity |
jobTerms |
Terms |
terms will apply by default for jobs for this contract |
quoteTerms |
Terms |
terms will apply by default for quotes for this contract |
invoiceTerms |
Terms |
terms will apply by default for invoices for this contract |
paymentTerms |
Paymentterms |
terms will apply by default for invoices for this contract |
invoiceNotes |
string |
invoices created using this contract will have these notes copied to them |
invoiceDetailLevel |
array(string) |
default Detail Level applied for Invoices in scope of contract. Subset of ("public", "items", "noprices", "items_by_type", "type_detail"), |
quoteDetailLevel |
array(string |
default Detail Level applied for Quotes in scope of contract. Subset of ("public", "items", "noprices", "time_and_materials", "by_type", "type_detail") |
created |
integer |
Unix timestamp of this contract's creation time |
updated |
integer |
Unix timestamp of when this contract was last updated |
Retrieve all contracts allowable for the vendor company and customer location
GET /contract?vendorId=34&locationId=84
200
{
"data": {
"totalPages": 1,
"page": 1,
"contracts": [
{
"id": 94,
"uri": "https://api.servicetrade.com/api/contract/94",
"name": "Hwy 55 Contract",
"active": true,
"complexity": "simple",
"expectedRevenue": 250000,
"expectedMargin": 123.45,
"totalCost": 123.45,
"allItemsHaveCosts": true,
"actualMargin": 25.50,
"vendor": {
"id": 34,
"uri": "https://api.servicetrade.com/api/company/34",
"name": "StandAlone Safety",
"status": "active"
},
"customer": {
"id": 36,
"uri": "https://api.servicetrade.com/api/company/36",
"name": "Hwy 55 Burgers",
"status": "active"
},
"parent": {
"id": 19,
"uri": "https://api.servicetrade.com/api/contract/19",
"name": "StandAlone Standard Contract"
},
"type": "company",
"startsOn": 1471049600,
"expiresOn": 1476849600,
"reviewOn": 1475849600,
"owner": null,
"sales": null,
"office": {
"id": 314,
"uri": "https://api.servicetrade.com/api/location/314",
"name": "StandAlone Safety Main Office"
},
"region": {
"id": 142,
"uri": "https://api.servicetrade.com/api/region/142",
"name": "Central Carolina"
},
"locationContext": "location",
"location": {
"id": 33,
"uri": "https://api.servicetrade.com/api/location/33",
"legacyId": 4567,
"name": "Foo's Bar",
"lat": 12.34,
"lon": -45.67,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "123 Typewriter Way",
"city": "Aiburg",
"state": "NC",
"postalCode": "23462"
},
"taxable": false,
"status": "active"
},
"entityFilter": null,
"jobType": "cleaning",
"description" : "",
"customerPo" : null,
"revenue": null,
"revenueAsOf": null,
"tags": [],
"active": true,
"complexity": "simple",
"jobTerms": {
"id": 5,
"uri": "https://api.servicetrade.com/api/terms/5",
"name": "Example terms 5"
},
"quoteTerms": {
"id": 3,
"uri": "https://api.servicetrade.com/api/terms/3",
"name": "Example terms 3"
},
"invoiceTerms": {
"id": 3,
"uri": "https://api.servicetrade.com/api/terms/1",
"name": "Example terms 1"
},
"paymentTerms": {
"id": 1,
"uri": "https://api.servicetrade.com/api/paymentterms/1",
"name": "Due Upon Receipt",
"orderIndex": 1,
},
"invoiceNotes": "Thank you for being our loyal customer!",
"invoiceDetailLevel": [
"public",
"items_by_type",
"type_detail"
],
"quoteDetailLevel": [
"public",
"items_by_type",
"type_detail"
],
"created": 1622681565,
"updated": 1622681565
},
{
"id": 95,
"uri": "https://api.servicetrade.com/api/contract/95",
"name": "Hwy 55 Contract Weekend Prices",
"complexity": "simple",
"expectedRevenue": 250000,
"expectedMargin": 123.45,
"totalCost": 123.45,
"allItemsHaveCosts": false,
"actualMargin": 33.50,
"vendor": {
"id": 34,
"uri": "https://api.servicetrade.com/api/company/34",
"name": "StandAlone Safety",
"status": "active"
},
"customer": {
"id": 36,
"uri": "https://api.servicetrade.com/api/company/36",
"name": "Hwy 55 Burgers",
"status": "active"
},
"parent": {
"id": 19,
"uri": "https://api.servicetrade.com/api/contract/19",
"name": "StandAlone Standard Contract"
},
"type": "company",
"startsOn": 1471049600,
"expiresOn": 1476849600,
"reviewOn": 1475849600,
"owner": null,
"sales": null,
"office": null,
"region": null,
"locationContext": "all",
"location": null,
"entityFilter": null,
"jobType": null,
"description" : "",
"customerPo" : null,
"revenue": null,
"revenueAsOf": null,
"tags": [],
"active": true,
"complexity": "simple",
"expectedRevenue": 250000,
"expectedMargin": 123.45,
"totalCost": 123.45,
"allItemsHaveCosts": false,
"actualMargin": 20.05,
"jobTerms": {
"id": 5,
"uri": "https://api.servicetrade.com/api/terms/5",
"name": "Example terms 5"
},
"quoteTerms": {
"id": 3,
"uri": "https://api.servicetrade.com/api/terms/3",
"name": "Example terms 3"
},
"invoiceTerms": {
"id": 3,
"uri": "https://api.servicetrade.com/api/terms/1",
"name": "Example terms 1"
},
"paymentTerms": null,
"invoiceNotes": "Invoice will be due by 15 days after services are performed.",
"invoiceDetailLevel": [
"public",
"items_by_type",
"type_detail"
],
"quoteDetailLevel": [
"public",
"items_by_type",
"type_detail"
],
"created": 1622681565,
"updated": 1622681565
}
]
}
}
Retrieve a contract by id
GET /contract/94
200
{
"data": {
"id": 94,
"uri": "https://api.servicetrade.com/api/contract/94",
"name": "Hwy 55 Contract",
"vendor": {
"id": 34,
"uri": "https://api.servicetrade.com/api/company/34",
"name": "StandAlone Safety",
"status": "active"
},
"customer": {
"id": 36,
"uri": "https://api.servicetrade.com/api/company/36",
"name": "Hwy 55 Burgers",
"status": "active"
},
"parent": {
"id": 19,
"uri": "https://api.servicetrade.com/api/contract/19",
"name": "StandAlone Standard Contract"
},
"type": "company",
"startsOn": 1471049600,
"expiresOn": 1476849600,
"reviewOn": 1475849600,
"owner": null,
"sales": null,
"office": null,
"region": null,
"locationContext": "all",
"location": null,
"entityFilter": null,
"jobType": null,
"description" : "",
"customerPo" : "abc-1234",
"revenue": null,
"revenueAsOf": null,
"tags": [],
"active": true,
"complexity": "simple",
"expectedRevenue": 250000,
"expectedMargin": 123.45,
"totalCost": 123.45,
"allItemsHaveCosts": false,
"actualMargin": 15.45,
"jobTerms": {
"id": 5,
"uri": "https://api.servicetrade.com/api/terms/5",
"name": "Example terms 5"
},
"quoteTerms": {
"id": 3,
"uri": "https://api.servicetrade.com/api/terms/3",
"name": "Example terms 3"
},
"invoiceTerms": {
"id": 3,
"uri": "https://api.servicetrade.com/api/terms/1",
"name": "Example terms 1"
},
"paymentTerms": null,
"invoiceNotes": "Thank you for being our loyal customer!",
"invoiceDetailLevel": [
"public",
"items_by_type",
"type_detail"
],
"quoteDetailLevel": [
"public",
"items_by_type",
"type_detail"
],
"created": 1622681565,
"updated": 1622681565
}
}
Retrieve detail information for a contract which does not exist or the user cannot access
GET /contract/987
404
Accept a contract, successful
POST /contract/13/accept
200
{
"data": {
"uri": "https://api.servicetrade.com/api/contract/13",
"id": 13,
"name": "Safety Technologies, Inc.",
"accepted": true
}
}
Accept a contract failed because it either doesn't exist or I don't have access to it
POST /contract/13/accept
404
Create a quote-specific contract, or return the existing one
POST /contract
{"quoteId": 123, "jobId": 345, "jobTermsId": 5, "quoteTermsId": 3, "invoiceTermsId": 6}
200
{
"data": {
"uri": "https://api.servicetrade.com/api/contract/10",
"id": 10,
"name": "Job #654 Quote",
"vendor": {
"id": 34,
"uri": "https://api.servicetrade.com/api/company/34",
"name": "StandAlone Safety",
"status": "active"
},
"customer": {
"id": 36,
"uri": "https://api.servicetrade.com/api/company/36",
"name": "Hwy 55 Burgers",
"status": "active"
},
"parent": null,
"type": "quote",
"startsOn": 1471049600,
"expiresOn": 1445522820,
"reviewOn": 1475849600,
"owner": null,
"sales": null,
"office": null,
"region": null,
"locationContext": null,
"location": null,
"entityFilter": null,
"jobType": null,
"description" : "",
"customerPo" : null,
"revenue": null,
"revenueAsOf": null,
"tags": [],
"active": true
"complexity": "simple",
"expectedRevenue": 250000,
"expectedMargin": 123.45,
"totalCost": 123.45,
"allItemsHaveCosts": true,
"actualMargin": 30.5,
"jobTerms": {
"id": 5,
"uri": "https://api.servicetrade.com/api/terms/5",
"name": "Example terms 5"
},
"quoteTerms": {
"id": 3,
"uri": "https://api.servicetrade.com/api/terms/3",
"name": "Example terms 3"
},
"invoiceTerms": {
"id": 3,
"uri": "https://api.servicetrade.com/api/terms/1",
"name": "Example terms 1"
},
"paymentTerms": null,
"invoiceNotes": "",
"invoiceDetailLevel": [
"public",
"items_by_type",
"type_detail"
],
"quoteDetailLevel": [
"public",
"items_by_type",
"type_detail"
],
"created": 1622681565,
"updated": 1622681565
}
}
Create a non-quote contract
POST /contract
{
"name": "Hwy 55 Contract",
"type": "company",
"expiresOn": 1445522820,
"customerId": 36,
"vendorId": 34,
"expectedRevenue": 250000,
"expectedMargin": 123.45,
"totalCost": 123.45,
"allItemsHaveCosts": true,
"actualMargin": 22.50
}
200
{
"data": {
"id": 2195,
"uri": "https://api.servicetrade.com/api/contract/2195",
"name": "Hwy 55 Contract",
"vendor": {
"id": 34,
"uri": "https://api.servicetrade.com/api/company/34",
"name": "StandAlone Safety",
"status": "active"
},
"customer": {
"id": 36,
"uri": "https://api.servicetrade.com/api/company/36",
"name": "Hwy 55 Burgers",
"status": "active"
},
"parent": null,
"type": "company",
"startsOn": 1471049600,
"expiresOn": 1445522820,
"reviewOn": 1475849600,
"owner": null,
"sales": null,
"office": null,
"region": null,
"locationContext": "all",
"location": null,
"entityFilter": null,
"jobType": null,
"description" : "",
"customerPo" : null,
"revenue": null,
"revenueAsOf": null,
"tags": [],
"active": true,
"complexity": "simple",
"expectedRevenue": 250000,
"expectedMargin": 123.45,
"totalCost": 123.45,
"allItemsHaveCosts": true,
"actualMargin": 17.5,
"jobTerms": {
"id": 5,
"uri": "https://api.servicetrade.com/api/terms/5",
"name": "Example terms 5"
},
"quoteTerms": {
"id": 3,
"uri": "https://api.servicetrade.com/api/terms/3",
"name": "Example terms 3"
},
"invoiceTerms": {
"id": 3,
"uri": "https://api.servicetrade.com/api/terms/1",
"name": "Example terms 1"
},
"paymentTerms": null,
"invoiceNotes": "",
"invoiceDetailLevel": [
"public",
"items_by_type",
"type_detail"
],
"quoteDetailLevel": [
"public",
"items_by_type",
"type_detail"
],
"created": 1622681565,
"updated": 1622681565
}
}
Modify a non-quote contract
PUT /contract/2195
{"name": "Hwy 55 Contract 1", "customerId": 34, "vendorId": 36, "jobTermsId": 5, "quoteTermsId": 3, "invoiceTermsId": 6}
200
{
"data": {
"id": 2195,
"uri": "https://api.servicetrade.com/api/contract/2195",
"name": "Hwy 55 Contract 1",
"vendor": {
"id": 36,
"uri": "https://api.servicetrade.com/api/company/36",
"name": "Hwy 55 Burgers",
"status": "active"
},
"customer": {
"id": 34,
"uri": "https://api.servicetrade.com/api/company/34",
"name": "StandAlone Safety",
"status": "active"
},
"parent": null,
"type": "company",
"startsOn": 1471049600,
"expiresOn": 1445486400,
"reviewOn": 1475849600,
"owner": null,
"sales": null,
"office": null,
"region": null,
"locationContext": "all",
"location": null,
"entityFilter": null,
"jobType": null,
"description" : "",
"customerPo" : null,
"revenue": null,
"revenueAsOf": null,
"tags": [],
"active": true,
"complexity": "simple",
"expectedRevenue": 250000,
"expectedMargin": 123.45,
"totalCost": 123.45,
"allItemsHaveCosts": true,
"actualMargin": 33.0,
"jobTerms": {
"id": 5,
"uri": "https://api.servicetrade.com/api/terms/5",
"name": "Example terms 5"
},
"quoteTerms": {
"id": 3,
"uri": "https://api.servicetrade.com/api/terms/3",
"name": "Example terms 3"
},
"invoiceTerms": {
"id": 3,
"uri": "https://api.servicetrade.com/api/terms/1",
"name": "Example terms 1"
},
"paymentTerms": null,
"invoiceNotes": "",
"invoiceDetailLevel": [
"public",
"items_by_type",
"type_detail"
],
"quoteDetailLevel": [
"public",
"items_by_type",
"type_detail"
],
"created": 1622681565,
"updated": 1622681565
}
}
Create a copy of a contract
POST /contract/94/copy
{"copyAttachments": true}
200
{
"data": {
"id": 294,
"uri": "https://api.servicetrade.com/api/contract/294",
"name": "Copy of Hwy 55 Contract",
"active": true,
"complexity": "simple",
"expectedRevenue": 250000,
"expectedMargin": 123.45,
"totalCost": 123.45,
"allItemsHaveCosts": true,
"actualMargin": 21.0,
"vendor": {
"id": 34,
"uri": "https://api.servicetrade.com/api/company/34",
"name": "StandAlone Safety",
"status": "active"
},
"customer": {
"id": 36,
"uri": "https://api.servicetrade.com/api/company/36",
"name": "Hwy 55 Burgers",
"status": "active"
},
"parent": {
"id": 19,
"uri": "https://api.servicetrade.com/api/contract/19",
"name": "StandAlone Standard Contract"
},
"type": "company",
"startsOn": 1471049600,
"expiresOn": 1476849600,
"reviewOn": 1475849600,
"owner": null,
"sales": null,
"office": null,
"region": null,
"locationContext": "all",
"location": null,
"entityFilter": null,
"jobType": null,
"description" : "",
"customerPo" : null,
"revenue": null,
"revenueAsOf": null,
"tags": [],
"active": true,
"complexity": "simple",
"allItemsHaveCosts": true,
"jobTerms": {
"id": 5,
"uri": "https://api.servicetrade.com/api/terms/5",
"name": "Example terms 5"
},
"quoteTerms": {
"id": 3,
"uri": "https://api.servicetrade.com/api/terms/3",
"name": "Example terms 3"
},
"invoiceTerms": {
"id": 3,
"uri": "https://api.servicetrade.com/api/terms/1",
"name": "Example terms 1"
},
"paymentTerms": null,
"invoiceNotes": "",
"invoiceDetailLevel": [
"public",
"items_by_type",
"type_detail"
],
"quoteDetailLevel": [
"public",
"items_by_type",
"type_detail"
],
"created": 1622681565,
"updated": 1622681565
}
}
Return to Top
Contract Rule
The contract rule resource is used to retrieve or define contract pricing rules.
- Resource URL: /contractrule
- Resource URL: /contract/[contractId]/rule/[ruleId]
- Available Verbs: GET, POST, PUT, DELETE
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/contractrule |
200 |
updated or created date range filter is required |
GET |
/contract/42/rule |
200 |
list all rules for this contract |
POST |
/contract/42/rule |
200 |
rule created |
POST |
/contract/42/rule |
400 |
malformed request or invalid data |
GET |
/contract/42/rule/456 |
200 |
|
GET |
/contract/42/rule/456 |
404 |
rule or contract not found |
PUT |
/contract/42/rule/456 |
200 |
rule updated |
PUT |
/contract/42/rule/456 |
400 |
malformed request or invalid data |
PUT |
/contract/42/rule/456 |
404 |
rule or contract not found |
DELETE |
/contract/42/rule/456 |
204 |
rule deleted |
DELETE |
/contract/42/rule/456 |
404 |
rule or contract not found |
Query Params
Name |
Type |
Value |
type |
string |
returns only rules of this type. One of: unit, range, bundle, stack, minimum, nte, markup, margin, admincharge, additionalcharge |
inherit |
boolean |
if true, return rules for parent contracts as well |
flatview |
boolean |
similar to inherit, but hides masked rules. Only supported for type=unit, disallowed otherwise. |
sort |
string |
sort method. options are default and display |
libItemName |
string |
return only lib items matching this string |
libItemIds |
integer |
return only lib items matching this id, or '' or 'none' for general rules only |
createdAfter |
integer |
returns only rules created on or after the given timestamp |
createdBefore |
integer |
returns only rules created on or before the given timestamp |
updatedAfter |
integer |
return only rules whose last update time is on or after the given timestamp |
updatedBefore |
integer |
return only rules whose last update time is on or before the given timestamp |
Parameters for POST/PUT
Name |
Type |
Required |
Value |
type |
string |
yes |
one of: unit, range, bundle, stack, minimum, nte, markup, margin, admincharge, additionalcharge |
name |
string |
yes |
name of the rule |
price |
numeric |
no |
defaults to 0 |
libItemIds |
array (integer) |
for POST of additionalcharge |
items for which this rule applies |
threshold |
numeric |
no |
if given, limits the quantity of items this price rule will be applied to, thresholds that apply to 'markup' rules have type numeric, all other rules have type integer. |
serviceLineId |
numeric |
for POST of additionalcharge |
defines the service line for the rule; allowed only for 'additionalcharge' rule type |
Returned Elements
Name |
Type |
Value |
type |
string |
type of this rule |
name |
string |
name of this rule |
price |
numeric |
unit price for invoice items generated by this rule. 'markup' and 'margin' rules will treat this as a percentage |
threshold |
numeric |
if given, the quantity of items this price rule will be applied to. 'markup' rules will apply to items with costs up to this amount. |
libItems |
array (Libitem) |
items this rule applies to |
serviceLine |
ServiceLine |
service line of this rule |
contract |
Contract |
the contract this rule is defined on |
created |
integer |
Unix timestamp of this rule's creation time |
updated |
integer |
Unix timestamp of when this rule was last updated |
Retrieve all rules of a given type
GET /contract/42/rule?type=unit
200
{
"data": {
"totalPages": 1,
"page": 1,
"rules": [
{
"id": 416,
"uri": "https://api.servicetrade.com/api/contract/42/rule/416",
"name": "Bursting Disc, each",
"contract": {
"id": 42,
"uri": "https://api.servicetrade.com/api/contract/42",
"name": "Standard Price List"
},
"type": "unit",
"price": 4.3,
"threshold": null,
"libItems": [
{
"id": 775,
"uri": "https://api.servicetrade.com/api/libitem/775",
"name": "Bursting Disc",
"type": "part",
"code": "BURSTDISC"
}
],
"serviceLine": null,
"created": 1622681565,
"updated": 1622681565
},
{
"id": 417,
"uri": "https://api.servicetrade.com/api/contract/42/rule/417",
"name": "Ansul LTA 101-30 Cartridge, first 5",
"contract": {
"id": 42,
"uri": "https://api.servicetrade.com/api/contract/42",
"name": "Standard Price List"
},
"type": "unit",
"price": 160.5,
"threshold": 5,
"libItems": [
{
"id": 874,
"uri": "https://api.servicetrade.com/api/libitem/874",
"name": "Ansul LTA 101-30 Cartridge",
"type": "part",
"code": null
}
],
"serviceLine": null,
"created": 1622681565,
"updated": 1622681565
},
{
"id": 418,
"uri": "https://api.servicetrade.com/api/contract/42/rule/418",
"name": "Additional Charge for Ansul LTA 101-30 Cartridge",
"contract": {
"id": 42,
"uri": "https://api.servicetrade.com/api/contract/42",
"name": "Standard Price List"
},
"type": "additionalcharge",
"price": 10.00,
"threshold": null,
"libItems": [
{
"id": 874,
"uri": "https://api.servicetrade.com/api/libitem/874",
"name": "Ansul LTA 101-30 Cartridge",
"type": "part",
"code": null
}
],
"serviceLine": [
{
"id": 987,
"name": "Line 1049345998",
"trade": "Fire Protection,
"abbr": "LINE",
"icon": "http://localdev/image/icons/service_lines/32/OTHER.png"
}
],
"created": 1622681565,
"updated": 1622681565
}
]
}
}
Retrieve information for a single rule
GET /contract/42/rule/417
200
{
"data": {
"id": 417,
"uri": "https://api.servicetrade.com/api/contract/42/rule/417",
"name": "Ansul LTA 101-30 Cartridge, first 5",
"contract": {
"id": 42,
"uri": "https://api.servicetrade.com/api/contract/42",
"name": "Standard Price List"
},
"type": "unit",
"price": 160.5,
"threshold": 5,
"libItems": [
{
"id": 874,
"uri": "https://api.servicetrade.com/api/libitem/874",
"name": "Ansul LTA 101-30 Cartridge",
"type": "part",
"code": null
}
],
"serviceLine": null,
"created": 1622681565,
"updated": 1622681565
}
}
Create a new rule
POST /contract/88/rule
{"type": "stack", "name":"Extinguisher Inspection, up to 10", "price": 30.00, "threshold": 10, "libItemIds": [624]}
200
{
"data": {
"id": 418,
"uri": "https://api.servicetrade.com/api/contract/88/rule/418",
"name": "Extinguisher Inspection, up to 10",
"contract": {
"id": 88,
"uri": "https://api.servicetrade.com/api/contract/88",
"name": "Discount Price List"
},
"type": "stack",
"price": 30,
"threshold": 10,
"libItems": [
{
"id": 624,
"uri": "https://api.servicetrade.com/api/libitem/624",
"name": "Portable Extinguisher Inspection",
"type": "inspection",
"code": null
}
],
"serviceLine": null,
"created": 1622681565,
"updated": 1622681565
}
}
POST /contract/88/rule
{"type": "additionalcharge", "name":"Additional Charge for Portable Extinguisher Inspection", "price": 5.00, "libItemIds": [624], "serviceLineId": 987}
200
{
"data": {
"id": 419,
"uri": "https://api.servicetrade.com/api/contract/88/rule/419",
"name": "Additional Charge for Portable Extinguisher Inspection",
"contract": {
"id": 88,
"uri": "https://api.servicetrade.com/api/contract/88",
"name": "Discount Price List"
},
"type": "additionalcharge",
"price": 10,
"threshold": null,
"libItems": [
{
"id": 624,
"uri": "https://api.servicetrade.com/api/libitem/624",
"name": "Portable Extinguisher Inspection",
"type": "inspection",
"code": null
}
],
"serviceLine": [
{
"id": 987,
"name": "Line 1049345998",
"trade": "Fire Protection,
"abbr": "LINE",
"icon": "http://localdev/image/icons/service_lines/32/OTHER.png"
}
],
"created": 1622681565,
"updated": 1622681565
}
}
Update a rule
PUT /contract/88/rule/418
{"price": 39.99}
200
{
"data": {
"id": 418,
"uri": "https://api.servicetrade.com/api/contract/88/rule/418",
"name": "Extinguisher Inspection, up to 10",
"contract": {
"id": 88,
"uri": "https://api.servicetrade.com/api/contract/88",
"name": "Discount Price List"
},
"type": "stack",
"price": 39.99,
"threshold": 10,
"libItemIds": [
{
"id": 624,
"uri": "https://api.servicetrade.com/api/libitem/624",
"name": "Portable Extinguisher Inspection",
"type": "inspection",
"code": null
}
],
"serviceLine": null,
"created": 1622681565,
"updated": 1622681565
}
}
Delete a rule
DELETE /contract/88/rule/418
204
Return to Top
Deficiency
The deficiency resource is used to retrieve lists of deficiencies or detailed information about a single deficiency.
- Resource URL: /deficiency/[deficiencyId]
- Available Verbs: GET, POST, PUT, DELETE
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/deficiency |
200 |
|
GET |
/deficiency/123 |
200 |
|
GET |
/deficiency/123 |
404 |
deficiency 123 not found |
GET |
/deficiency/123/attachment |
200 |
retrieve list of attachments |
GET |
/deficiency/123/attachment/10 |
200 |
retrieve attachment info |
GET |
/deficiency |
400 |
bad GET parameters |
POST |
/deficiency |
200 |
reports a new deficiency |
POST |
/deficiency |
400 |
bad POST parameters |
POST |
/deficiency/123 |
200 |
update an existing deficiency |
POST |
/deficiency/999 |
404 |
deficiency 999 not found |
POST |
/deficiency/123/attachment |
200 |
upload an image or other attachment |
PUT |
/deficiency |
405 |
not allowed |
PUT |
/deficiency/123 |
200 |
update an existing deficiency |
PUT |
/deficiency/999 |
404 |
deficiency 999 not found |
DELETE |
/deficiency |
405 |
not allowed |
DELETE |
/deficiency/123 |
404 |
deficiency 123 not found (or not accessible by the user) |
DELETE |
/deficiency/123 |
204 |
deficiency deleted |
DELETE |
/deficiency/123 |
409 |
deficiency is referenced by other entities |
Query Params
Name |
Type |
Value |
refNumber |
string |
find deficiencies by refNumber exact match |
severity |
string |
returns all deficiencies of the given severity (inoperable, deficient, suggested) |
status |
string |
returns all deficiencies of the given status (new, invalid, verified, fixed) |
lastReportedStatus |
string |
alias for "status" |
resolution |
string |
returns all deficiencies of the given resolution (new, invalid, fixed, out_for_quote, notified, rejected) |
assetId |
integer |
returns only deficiencies reported on the given asset |
locationId |
string |
comma delimited list of integers of location ids, returns only deficiencies reported at the given locations |
companyId |
string |
comma delimited list of integers of company ids, returns only deficiencies reported at locations belonging to the given companies |
officeIds |
string |
comma delimited list of integers of office ids, returns only deficiencies reported at the locations mapped to given offices |
regionIds |
string |
comma delimited list of integers of region ids, returns only deficiencies at locations within any of those regions |
quoteRequestId |
mixed |
returns only deficiencies with quotes that address them, either an integer or the string 'false' to return un-quoted deficiencies |
ownerId |
string |
comma delimited list of integers of user ids, returns only deficiencies owned by those users |
salesId |
string |
comma delimited list of integers of user ids, returns only deficiencies with those users assigned as salesperson |
createdBefore |
integer |
timestamp, matches records created on or before |
createdAfter |
integer |
timestamp, matches records created on or after |
updatedBefore |
integer |
timestamp, matches records updated on or before |
updatedAfter |
integer |
timestamp, matches records updated on or after |
tag |
string |
comma-separated list of tag strings, only deficiencies with all tags will be returned |
reportingJobId |
integer |
returns all deficiencies that have at any point in history had it's job field set to this job id |
POST/PUT Parameters
Name |
Type |
Required |
Value |
assetId |
integer |
for POST |
must be an existing assetId |
refNumber |
string |
no |
Reference number for identifying this deficiency. This reference number is set automatically if not specified, using a counter that increments by 1 for each new deficiency created without specifying a reference number. Deficiencies created before this field existed will have a refNumber that matches the id, unless it is updated later by the User. |
severity |
string |
no |
one of (inoperable, deficient, suggested), default is "inoperable" |
description |
string |
no |
description of the deficiency |
status |
string |
no |
most recently reported status of deficiency; one of (new, invalid, verified, fixed) |
resolution |
string |
no |
most recently reported lifecycle state of deficiency; one of (new, invalid, fixed, out_for_quote, notified, rejected) |
proposedFix |
string |
no |
description of proposed fix |
jobId |
integer |
no |
job that resulted in this deficiency report |
serviceLineId |
integer |
no |
service line for this deficiency (if different from the asset's service line) |
ownerId |
integer |
no |
user assigned as the owner of this deficiency, default is null |
salesId |
integer |
no |
user assigned as the salesperson of this deficiency, default is null. If salesId is not provided but jobId is provided, and that job has an assigned salesperson, then that job's salesperson will be assigned. |
reporterId |
integer |
no |
user who reported this deficiency, default is currently logged-in user |
reportSource |
string |
no |
one of (manual, lsn, ivr, mobile, jcw), default is "mobile" |
visibility |
array(string) |
no |
visibility granted to these types of viewers outside of the account; combination of: public, customer, subcontractor. "public" indicates global visibility and overrides the other values. Will default to account default if no value is provided on POST. |
Returned Elements
Name |
Type |
Value |
totalPages |
integer |
total number of results pages |
page |
integer |
current result page |
deficiencies |
array (object) |
list of deficiency objects |
id |
string |
deficiency id |
refNumber |
string |
reference number for identifying this deficiency |
uri |
string |
resource identifier for the given deficiency |
reportedOn |
integer |
unix timestamp of when this deficiency was first reported |
severity |
string |
severity of deficiency |
title |
string |
(read-only) human-readable short title of the form "severity - asset name" |
status |
string |
most recently reported status of deficiency |
lastReportedStatus |
string |
alias for "status" |
resolution |
string |
current lifecycle state of deficiency |
reportSource |
string |
what method was used to report this deficiency most recently |
description |
string |
deficiency description |
proposedFix |
string |
proposed fix, if any |
owner |
User |
the user who is assigned as the owner of the deficiency |
sales |
User |
the user who is assigned as the salesperson of the deficiency |
reporter |
User |
the user who reported the deficiency |
asset |
Asset |
asset this deficiency was reported against |
location |
Location |
location of the asset the deficiency was reported against |
serviceLine |
ServiceLine |
deficiency service line |
job |
Job |
most recent job that reported or repaired this deficiency |
visibility |
array(string) |
visibility granted to these types of viewers outside of the account; combination of: public, customer, subcontractor. "public" indicates global visibility and overrides the other values. |
created |
integer |
Unix timestamp of this record's creation time |
updated |
integer |
Unix timestamp of when this record was last updated |
externalIds |
object |
a key/value object of external system ids, only returned if account has external integrations defined |
Retrieve all deficiencies on a given asset
GET /deficiency?assetId=2
200
{
"data": {
"totalPages": 1,
"page": 1,
"deficiencies": [
{
"id": 1,
"refNumber": "1",
"uri": "https://api.servicetrade.com/api/deficiency/1",
"reportedOn": 1340649918,
"severity": "inoperable",
"title": "Inoperable - Panic Door",
"status": "verified",
"lastReportedStatus": "verified",
"resolution": "new",
"reportSource": "mobile",
"description": "Panic door is glued shut with solidified pepperoni vapor and old cheese.",
"proposedFix": "",
"owner": {
"id": 4,
"uri": "https://api.servicetrade.com/api/user/4",
"name": "Fixit Felix",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"sales": {
"id": 16,
"uri": "https://api.servicetrade.com/api/user/16",
"name": "Sammy Sales",
"email": "sammy@testcompany.com",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
}
"reporter": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"asset": {
"id": 2,
"uri": "https://api.servicetrade.com/api/asset/2",
"type": "panic_door",
"name": "Panic Door - Panic Door"
},
"location": {
"id": 33,
"uri": "https://api.servicetrade.com/api/location/33",
"legacyId": 4567,
"name": "Foo's Bar",
"lat": 12.34,
"lon": -45.67,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "123 Typewriter Way",
"city": "Aiburg",
"state": "NC",
"postalCode": "23462"
},
"taxable": false,
"status": "active"
},
"serviceLine": {
"id": 2,
"name": "Emergency / Exit Lights",
"trade": "Fire Protection",
"abbr": "ELIGHT",
"icon": "https://api.servicetrade.com/image/icons/service_lines/32/ELIGHT.png"
},
"job": {
"id": 41,
"uri": "https://api.servicetrade.com/api/job/41",
"number": 207464,
"type": "inspection",
"name": "Job 207464"
},
"visibility": ["public"],
"created": 1399993795,
"updated": 1399994065,
"externalIds": {
"peachtree": "1234 TT9"
}
}
]
}
}
No deficiency matches found
GET /deficiency?assetId=99999
200
{
"data": {
"totalPages": 1,
"page": 1,
"deficiencies": []
}
}
Retrieve information for a single deficiency
GET /deficiency/33
200
{
"data": {
"id": 33,
"refNumber": "33",
"uri": "https://api.servicetrade.com/api/deficiency/33",
"reportedOn": 1340649918,
"severity": "suggested",
"title": "Suggested - Building",
"status": "new",
"lastReportedStatus": "new",
"resolution": "out_for_quote",
"reportSource": "ivr",
"description": "Grease buildup makes the tile floor dangerously slippery",
"proposedFix": "",
"owner": null,
"sales": null,
"reporter": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"asset": {
"id": 3,
"uri": "https://api.servicetrade.com/api/asset/3",
"type": "location",
"name": "Location - Building"
},
"location": {
"id": 33,
"uri": "https://api.servicetrade.com/api/location/33",
"legacyId": 4567,
"name": "Foo's Bar",
"lat": 12.34,
"lon": -45.67,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "123 Typewriter Way",
"city": "Aiburg",
"state": "NC",
"postalCode": "23462"
},
"taxable": false,
"status": "active"
},
"serviceLine": {
"id": 2,
"name": "Emergency / Exit Lights",
"trade": "Fire Protection",
"abbr": "ELIGHT",
"icon": "https://api.servicetrade.com/image/icons/service_lines/32/ELIGHT.png"
},
"job": null,
"visibility": ["public"],
"created": 1399993795,
"updated": 1399994065,
"externalIds": {
"peachtree": "1234 TT9"
}
}
}
Retrieve information for a deficiency which does not exist
GET /deficiency/987
404
Report a new deficiency
POST /deficiency
{"assetId":123,"severity":"inoperable","description":"Elight battery does not hold charge"}
200
{
"data": {
"id": 18,
"refNumber": "18",
"uri": "https://api.servicetrade.com/api/deficiency/18",
"reportedOn": 1340649918,
"severity": "inoperable",
"title": "Inoperable - Emergency Light",
"status": "new",
"lastReportedStatus": "new",
"resolution": "new",
"reportSource": "mobile",
"description": "Elight battery does not hold charge",
"proposedFix": "",
"owner": null,
"sales": null,
"reporter": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"asset": {
"id": 123,
"uri": "https://api.servicetrade.com/api/asset/123",
"type": "elight",
"name": "Emergency Light - Kitchen"
},
"location": {
"id": 33,
"uri": "https://api.servicetrade.com/api/location/33",
"legacyId": 4567,
"name": "Foo's Bar",
"lat": 12.34,
"lon": -45.67,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "123 Typewriter Way",
"city": "Aiburg",
"state": "NC",
"postalCode": "23462"
},
"taxable": false,
"status": "active"
},
"serviceLine": {
"id": 2,
"name": "Emergency / Exit Lights",
"trade": "Fire Protection",
"abbr": "ELIGHT",
"icon": "https://api.servicetrade.com/image/icons/service_lines/32/ELIGHT.png"
},
"job": null,
"visibility": ["public"],
"created": 1399993795,
"updated": 1399994065,
"externalIds": {
"peachtree": "1234 TT9"
}
}
}
Update an existing deficiency
PUT /deficiency/123
{"description":"Elight battery does not hold charge, and bulb is burned out","proposedFix":"Replace entire unit", "status":"fixed"}
200
{
"data": {
"id": 18,
"refNumber": "18",
"uri": "https://api.servicetrade.com/api/deficiency/18",
"reportedOn": 1340649918,
"severity": "inoperable",
"title": "Inoperable - Emergency Light",
"status": "fixed",
"lastReportedStatus": "fixed",
"resolution": "fixed",
"reportSource": "jcw",
"description": "Elight battery does not hold charge, and bulb is burned out",
"proposedFix": "Replace entire unit",
"owner": null,
"sales": null,
"reporter": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"asset": {
"id": 123,
"uri": "https://api.servicetrade.com/api/asset/123",
"type": "elight",
"name": "Emergency Light - Kitchen"
},
"location": {
"id": 33,
"uri": "https://api.servicetrade.com/api/location/33",
"legacyId": 4567,
"name": "Foo's Bar",
"lat": 12.34,
"lon": -45.67,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "123 Typewriter Way",
"city": "Aiburg",
"state": "NC",
"postalCode": "23462"
},
"taxable": false,
"status": "active"
},
"serviceLine": {
"id": 2,
"name": "Emergency / Exit Lights",
"trade": "Fire Protection",
"abbr": "ELIGHT",
"icon": "https://api.servicetrade.com/image/icons/service_lines/32/ELIGHT.png"
},
"job": null,
"visibility": ["public"],
"created": 1399993795,
"updated": 1399994065,
"externalIds": {
"peachtree": "1234 TT9"
}
}
}
Return to Top
EULA
The EULA resource is used to request if the currently authenticated user has accepted the most recent end-user license agreement.
- Resource URL: /eula
- Available Verbs: GET, POST
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/eula |
200 |
|
GET |
/eula |
204 |
no current EULA exists (no acceptance necessary) |
POST |
/eula |
200 |
current user accepts the current EULA |
POST |
/eula |
204 |
no current EULA exists (no acceptance necessary) |
PUT |
/eula |
405 |
not allowed |
DELETE |
/eula |
405 |
not allowed |
Returned Elements
Name |
Type |
Value |
eulaText |
string |
text of the most recent EULA |
eulaAccepted |
boolean |
whteher the user has accepted the most recent EULA |
Sample request and response
GET /eula
200
{
"data": {
"eulaText": "This is the current EULA",
"eulaAccepted": true
}
}
No EULA to accept
GET /eula
204
Accepting the current EULA
POST /eula
200
{
"data": {
"eulaText": "This is the current EULA",
"eulaAccepted": true
}
}
Return to Top
Entity Filter
The entity filter resource is used to retrieve entity filters. Entity filters can be used to modify the location context of a contract.
- Resource URL: /entityfilter/[entityFilterId]
- Available Verbs: GET
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/entityfilter |
200 |
|
GET |
/entityfilter/123 |
200 |
|
GET |
/entityfilter/123 |
404 |
entityfilter 123 not found |
POST |
/entityfilter |
405 |
not allowed |
PUT |
/entityfilter |
405 |
not allowed |
DELETE |
/entityfilter |
405 |
not allowed |
Query Params
Name |
Type |
Value |
name |
string |
string to find in the filter name |
type |
string |
return only filters of this type; one of: 'location' |
Returned Elements
Note that the 'company' and 'locations' properties are returned only in response to an individual GET request of a specific entity filter by its ID. They are not returned in list GET responses.
Name |
Type |
Value |
uri |
string |
resource identifier of the entity filter |
id |
integer |
entity filter id |
name |
string |
entity filter name |
type |
string |
the type of filter; one of: 'location' |
company |
Company |
company associated with this entity |
locations |
array Location |
list of locations associated with this entity; will be empty if the contract applies to all of a customer company's locations |
Get list of entity filters
GET /entityfilter
200
{
"data": {
"totalPages": 1,
"page": 1,
"entityFilters": [
{
"id": 100000000000002,
"uri": "https://api.servicetrade.com/api/entityfilter/100000000000002",
"name": "Delco Sites",
"type": "location"
},
{
"id": 100000000000003,
"uri": "https://api.servicetrade.com/api/entityfilter/100000000000003",
"name": "In-N-Out Burgers - West Coast",
"type": "location"
}
]
}
}
Get entity filter by id
GET /entityfilter/100000000000002
200
{
"data": {
"id": 100000000000002,
"uri": "https://api.servicetrade.com/api/entityfilter/100000000000002",
"name": "Delco Sites",
"type": "location",
"company": {
"id": 100000000000018,
"uri": "https://api.servicetrade.com/api/company/100000000000018",
"name": "Delco",
"status": "active"
},
"locations": null
}
}
Return to Top
ExternalId
The ExternalId resource is used to associate ServiceTrade entities with external identifiers.
It can return and modify external identifiers for a given entity, or it can return an entity for a given external identifier.
Supported entity types: asset, company, contact, contract, deficiency, location, job, jobitem, libitem, quote, user
- Authentication Required: yes
- Resource URL: /externalid/[entityType]/[entityId]
- Resource URL: /externalid/[entityType]/[entityId]/[externalSystem]
- Available Verbs: GET, POST, PUT
- Resource URL: /externalid/[entityType]/[externalSystem]/[value]
- Resource URL: /externalid/[entityType]/[externalSystem]/?value=[value]
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/externalid |
405 |
not allowed |
GET |
/externalid/location |
405 |
not allowed |
GET |
/externalid/company |
405 |
not allowed |
GET |
/externalid/user |
405 |
not allowed |
GET |
/externalid/contract |
405 |
not allowed |
GET |
/externalid/foo |
404 |
invalid entity type |
GET |
/externalid/{entity}/123 |
200 |
returns all external ids for that {entity} |
GET |
/externalid/{entity}/123 |
404 |
{entity} 123 not found |
GET |
/externalid/{entity}/123/system_foo |
404 |
no external system with that name was found |
GET |
/externalid/{entity}/123/system_name |
200 |
returns that system's external id for that {entity} |
POST |
/externalid/{entity}/123/system_name |
200 |
sets that system's external id for that {entity} |
POST |
/externalid/{entity}/123/system_foo |
404 |
no external system with that name was found |
PUT |
/externalid/{entity}/123/system_name |
200 |
sets that system's external id for that {entity} |
PUT |
/externalid/{entity}/123/system_foo |
404 |
no external system with that name was found |
DELETE |
/externalid/{entity}/123/system_name |
405 |
not allowed |
GET |
/externalid/{entity}/system_name/ENT1 |
200 |
returns {entity} object identified in system_name by 'ENT1' |
GET |
/externalid/{entity}/system_name/ENT2 |
404 |
no {entity} object was found in system_name identified by 'ENT2' |
POST |
/externalid/{entity}/system_name/ENT1 |
405 |
not allowed |
PUT |
/externalid/{entity}/system_name/ENT1 |
405 |
not allowed |
DELETE |
/externalid/{entity}/system_name/ENT1 |
405 |
not allowed |
Query Params
Name |
Type |
Value |
entityType |
entity type |
entity type constant of the entity (required) |
entityId |
integer |
id of the entity (required if looking up external ids) |
externalSystem |
string |
name of the external system to look up or set a value for (required for POST/PUT/DELETE) |
value |
string |
external id to look up the snaap entity by |
POST/PUT Params
Name |
Type |
Required |
Value |
entityType |
entity type |
Yes |
Sets externalId for this type of entity |
entityId |
integer |
Yes |
Sets externalId for this entity |
systemName |
string |
Yes |
Unique name of an external system integration instance |
value |
string |
No |
The value of the external id for the given entity type and entity id in the given system. If an empty string is given for a PUT, the existing value will be removed. |
syncId |
integer |
No |
If set, links this externalId to an externalSync record. If not set and this system can sync this entity, a manual externalSync record will be created |
Returned Elements
Name |
Type |
Value |
value |
string |
external system's id for the ServiceTrade entity |
Sample request and response
GET /externalid/location/123/system_name
200
{
"data": {
"value": "S1-123",
}
}
GET /externalid/location/123
200
{
"data": {
"values": {
"system_name": "S1-123",
"other_system": "Loc543"
}
}
}
POST /externalid/location/123/system_name
{"value":"S1-NewId123"}
200
{
"data": {
"value": "S1-NewId123",
}
}
GET /externalid/location/system_name/S1-NewId123
200
{
"data": {
"id": 820,
"uri": "https://api.servicetrade.com/api/location/820",
"name": "Burger Bistro",
"legacyId": null,
"lat": 35.774097,
"lon": -78.857784,
"address": {
"street": "101 Burger Way",
"city": "Cary",
"state": "NC",
"postalCode": "27519"
},
"taxable": false,
"geocodeQuality": 99,
"phoneNumber": "",
"email": "",
"generalManager": "",
"primaryContact": null,
"updated": 1377020736,
"company": {
"id": 30,
"uri": "https://api.servicetrade.com/company/30",
"name": "Burgers International"
},
"externalIds": {
"system_name": "S1-NewId123"
}
}
}
GET /externalid/company/123/system_name
200
{
"data": {
"value": "AB-376",
}
}
GET /externalid/company/123
200
{
"data": {
"values": {
"system_name": "AB-376",
"other_system": "Teb56"
}
}
}
POST /externalid/company/123/system_name
{"value":"AB-CD534"}
200
{
"data": {
"value": "AB-CD534",
}
}
GET /externalid/company/system_name/AB-CD534
200
{
"data": {
"id": 36,
"uri": "https://api.servicetrade.com/api/company/36",
"name": "Burger Bistro Corp",
"status": "active",
"customer": true,
"vendor": false,
"primeContractor": false,
"managingAccount": null,
"shareId": null,
"address": {
"street": "102 Commercial Avenue",
"city": "Mount Olive",
"state": "NC",
"postalCode": "28365"
},
"phoneNumber": null,
"serviceLinesProvided": [],
"externalIds": {
"system_name": "AB-CD534"
}
}
}
Return to Top
ExternalSync
The externalsync resource is used to send records to external systems, and to retrieve the status of existing external system sync attempts.
- Resource URL: /externalsync/[externalSyncId]
- Available Verbs: GET, POST, PUT
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/externalsync |
200 |
|
GET |
/externalsync/123 |
200 |
|
GET |
/externalsync/123 |
404 |
externalsync 123 not found |
POST |
/externalsync |
200 |
externalsync created |
POST |
/externalsync |
400 |
externalsync not created: malformed data |
POST |
/externalsync |
403 |
externalsyncs cannot be created by user |
PUT |
/externalsync/123 |
200 |
|
PUT |
/externalsync/123 |
400 |
externalsync not updated: malformed data |
PUT |
/externalsync/123 |
403 |
externalsync 123 not editable by user |
PUT |
/externalsync/123 |
404 |
externalsync 123 not found |
Query Params
Name |
Type |
Value |
status |
string |
Return sync records in this status. One of 'manual', 'pending', 'sending', 'ok', or 'failed' |
entityType |
entity type |
Return sync records for this type of entity |
entityId |
integer |
Return sync records for just this entity. Requires entityType to be sent also. |
isCurrent |
boolean |
Return only the most recent sync for each system |
POST Parameters
Name |
Type |
Required |
Value |
entityType |
entity type |
Yes |
Type of entity being synced |
entityId |
integer |
Yes |
id of entity being synced |
systemId |
integer |
Yes |
id of a external system integration |
status |
string |
|
One of 'manual', 'pending', 'sending', 'ok', or 'failed'. Defaults to 'pending'. |
details |
object |
|
context specific details about the sync, as a JSON object |
userId |
integer |
|
id of the user initiating the sync. Defaults to the requesting user. |
parentId |
integer |
|
id of the sync that triggered this sync |
Returned Elements
Name |
Type |
Value |
uri |
string |
resource identifier of the externalsync |
id |
integer |
quote template id |
entity.uri |
string |
resource identifier of the entity to be synced |
entity.id |
integer |
id of the entity to be synced |
entity.type |
entity type |
entity type constant |
system.id |
integer |
id of the external system integration |
system.name |
string |
name of the external system integration |
status |
string |
One of 'manual', 'pending', 'sending', 'ok', or 'failed' |
user |
User |
resource identifier of the user who initiated the sync |
parent |
Externalsync |
the sync that triggered this sync |
details |
object |
context specific details about the sync |
created |
integer |
Unix timestamp of the sync record's creation date and time |
updated |
integer |
Unix timestamp of the sync record's last update date and time |
Retrieve all externalsync records
GET /externalsync
200
{
"data": {
"totalPages": 1,
"page": 1,
"externalSyncs": [
{
"id": 222,
"uri": "https://api.servicetrade.com/api/externalsync/222",
"entity": {
"id": 45,
"uri": "https://api.servicetrade.com/api/job/45",
"number": 10300001,
"name": "Inspection Job #10300001",
"type": 3
},
"system": {
"id": 2,
"name": "dcs"
},
"status": "pending",
"user": {
"id": 21,
"uri": "https://api.servicetrade.com/api/user/21",
"name": "Stan Dalone",
"status": "active",
"avatar": {
"small": "https://api.servicetrade.com/image/avatar-small.png",
"medium": "https://api.servicetrade.com/image/avatar-medium.png",
"large": "https://api.servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"parent": null,
"details": {
"include_job_items": false
},
"created": 1370266418,
"updated": 1370544276
}
]
}
}
Create an externalsync
POST /externalsync
{"systemId": 2, "entityId": 46, "entityType": 3, "details": {"include_job_items": true}}
200
{
"data": {
"id": 222,
"uri": "https://api.servicetrade.com/api/externalsync/222",
"entity": {
"id": 45,
"uri": "https://api.servicetrade.com/api/job/46",
"number": 10300002,
"name": "Inspection Job #10300002",
"type": 3
},
"system": {
"id": 2,
"name": "dcs"
},
"status": "pending",
"user": {
"id": 21,
"uri": "https://api.servicetrade.com/api/user/21",
"name": "Stan Dalone",
"status": "active",
"avatar": {
"small": "https://api.servicetrade.com/image/avatar-small.png",
"medium": "https://api.servicetrade.com/image/avatar-medium.png",
"large": "https://api.servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"parent": null,
"details": {
"include_job_items": true
},
"created": 1370266418,
"updated": 1370544276
}
}
Return to Top
ExternalSystem
The ExternalSystem resource is used to associate ServiceTrade with external systems.
It can return and modify configuration settings for external systems.
The syncableTypes array for a system indicates what types of entities can sync with that system. For 'standard' systems only, this value may be set in POST/PUT requests. For other system types it is a read-only value that is computed based on the system type and configuration.
- Authentication Required: yes
- Resource URL: /externalsystem
- Available Verbs: GET, POST
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/externalsystem |
401 |
not logged in |
GET |
/externalsystem |
200 |
|
GET |
/externalsystem/123 |
200 |
|
POST |
/externalsystem |
200 |
create a new external system |
POST |
/externalsystem |
401 |
not logged in |
POST |
/externalsystem |
403 |
not an account admin |
POST |
/externalsystem |
400 |
invalid parameters provided |
PUT |
/externalsystem/123 |
200 |
|
PUT |
/externalsystem/123 |
403 |
not an account admin |
DELETE |
/externalsystem/123 |
405 |
DELETE action not yet implemented |
POST/PUT Params
Name |
Type |
Required |
Value |
name |
string |
yes |
Sets external system ID |
type |
string |
no |
Sets external system type, defaults to 'standard'. Cannot be changed for existing systems |
label |
string |
yes |
Sets display name |
syncableTypes |
array |
no |
For 'standard' systems only, sets the types of entities that can sync to this system. May include: 'invoice' |
Returned Elements
Name |
Type |
Value |
id |
int |
ServiceTrade's id for the external system |
name |
string |
The external system's name |
label |
string |
The display name of the external system |
type |
string |
one of ['standard', 'quickbooks', 'intacct', 'nearbynow', 'dcspectrum', 'fattmerchant'] |
syncableTypes |
array |
Lists the types of entities that can sync to this system. May include: 'invoice', 'job' |
properties |
json |
read-only key/value configuration settings related to the external system, where keys depends on system type |
created |
int |
Unix time stamp when the external system was registered with ServiceTrade |
updated |
int |
Unix time stamp when the external system was last updated with ServiceTrade |
Retrieve the list of existing systems
GET /externalsystem
200
{
"data": [
{
"id": 1,
"name": "peachtree",
"label": "Peachtree",
"type": "standard",
"syncableTypes": [],
"created": 1555970058,
"updated": 1555970058
},
{
"id": 27,
"name": "timberline",
"label": "Sage Timberline",
"type": "standard",
"syncableTypes": ["invoice"],
"created": 1555970758,
"updated": 1555970758
}
]
}
Create a new system
POST /externalsystem
{
"name": "test",
"type": "standard",
"label": "system test"
}
200
{
"data": {
"id": 21,
"name": "test",
"label": "system test",
"type": "standard",
"syncableTypes": [],
"created": 1558471348,
"updated": 1558471348
}
}
Update an existing system
PUT /externalsystem/21
{
"label": "Custom Accounting System 3000",
"syncableTypes": ["invoice"],
}
200
{
"data": {
"id": 21,
"name": "test",
"label": "Custom Accounting System 3000",
"type": "standard",
"syncableTypes": ["invoice"],
"created": 1558471348,
"updated": 1558471432
}
}
Return to Top
Heartbeat
The heartbeat resource is used to determine if the server is responding to API requests.
- Resource URL: /
- Available Verbs: GET
- Authentication Required: no
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/ |
200 |
|
POST |
/ |
405 |
not allowed |
PUT |
/ |
405 |
not allowed |
DELETE |
/ |
405 |
not allowed |
Returned Elements
Name |
Type |
Value |
version |
string |
current API version |
serverTime |
integer |
the current Unix timestamp on the server |
Sample request and response
GET /
200
{
"data": {
"version": "1.2.3",
"serverTime": 1318537441
}
}
Return to Top
History
The history resource is used to retrieve a list of events that have happened to an entity. Not all changes to all entities are recorded as history events.
The following entity types are supported: job, quote, location, company, asset, contact, contract, invoice, user, tax group.
- Resource URL: /history
- Available Verbs: GET
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/history |
200 |
|
GET |
/history |
400 |
entityId or entityType missing |
GET |
/history |
404 |
entity not found |
Query Params
Name |
Type |
Value |
entityId |
integer |
id of the entity to get the history of (required) |
entityType |
entity type |
entity type constant of the entity to get the history of (required) |
Returned Elements
Name |
Type |
Value |
user |
User |
resource identifier of the user who performed this action |
entity.uri |
string |
resource identifier of the entity to which this event is attached |
entity.id |
integer |
id of the entity to which this event is attached |
entity.type |
entity type |
entity type constant |
properties |
object/array |
context specific details about the event, as a JSON object |
created |
integer |
Unix timestamp of when this event occurred |
updated |
integer |
Unix timestamp of when this event occurred |
Get the history of quote 160951
GET /history?entityType=9&entityId=160951
200
{
"data": {
"totalPages": 1,
"page": 1,
"histories": [
{
"user": {
"id": 2590,
"uri": "https://api.servicetrade.com/api/user/2590",
"name": "Wesley Cox",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"entity": {
"uri": "https://api.servicetrade.com/api/quote/160951",
"id": 160951,
"type": 9
},
"properties": {
"eventTime": {
"date": "2016-06-15 14:18:11.000000",
"timezone_type": 3,
"timezone": "America/New_York"
},
"avatarSrc": "https://servicetrade.com/image/avatar-small.png",
"fullName": "Wesley Cox",
"actionEvent": "saved",
"windowStart": null,
"windowEnd": null,
"ip": "100.14.35.226",
"quoteType": "quote",
"quoteAction": "saved a draft of",
"quoteViewIp": null,
"recipients": null,
"userEmail": null,
"quoteJob": null,
"description": null,
"eventTemplateName": "history/quote-action"
},
"created": 1466014691,
"updated": 1466014691
}
]
}
}
Return to Top
Import
The import resource is used to retrieve detailed information about a single import
- Resource URL: /import/[importId]
- Available Verbs: GET, POST, DELETE
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/import |
405 |
not allowed |
GET |
/import/123 |
200 |
|
GET |
/import/123 |
404 |
import 123 not found |
POST |
/import |
200 |
created a new import |
POST |
/import |
400 |
could not create new import, bad request |
POST |
/import |
403 |
not allowed to create imports of given type |
PUT |
/import |
405 |
not allowed |
DELETE |
/import |
405 |
not allowed |
DELETE |
/import/123 |
204 |
success if the import does not yet have an uploaded file |
DELETE |
/import/123 |
404 |
import 123 not found |
DELETE |
/import/123 |
403 |
import not in s state that allows deletion |
POST Parameters
Name |
Type |
Required |
Value |
type |
string |
Yes |
one of: location, service, recurrence, item, invoice_update, tax_group_postal_code, asset |
subtype |
string |
No |
This is usually null. tax_group_postal_code imports can be "default" or "taxrates.com". asset imports can have a subtype based on their asset type. |
Returned Elements
Name |
Type |
Value |
id |
integer |
import id |
uri |
string |
resource identifier for the given import |
created |
integer |
unix timestamp when the import was created |
type |
string |
import type |
status |
string |
status of the import [new, pending, done] |
total |
integer |
total number of rows in the import |
processed |
integer |
count of rows processed |
successCount |
integer |
count of rows successfully imported |
failureCount |
integer |
count of rows unsuccessfully imported |
creator |
User |
user who created the import |
Retrieve information for a single import
GET /import/33
200
{
"data": {
"id": 33,
"uri": "https://api.servicetrade.com/api/import/33",
"created": 1322143200,
"type": "location",
"subtype": null,
"status": "pending",
"total": 2000,
"processed": 1100,
"successCount": 1000,
"failureCount": 100,
"creator": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
}
}
}
Retrieve information for an import which does not exist
GET /import/987
404
Create import
POST /import
{"type":"location"}
200
{
"data": {
"id": 8930,
"uri": "https://api.servicetrade.com/api/import/8930",
"created": 1322143200,
"type": "location",
"subtype": null,
"status": "pending",
"total": 0,
"processed": 0,
"successCount": 0,
"failureCount": 0,
"creator": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
}
}
}
Delete import 10
DELETE /import/10
204
Return to Top
Invoice
The invoices resource is used to retrieve lists of invoices and vendor bills (collectively, "invoices") or detailed information about a single invoice.
An "external" invoice represents an invoice created outside of ServiceTrade. If one is created without including any items then no contract pricing rules
will be applied to it. But if an external invoice is POSTed with a list of items and a contract then the contract pricing rules will be applied normally.
- Resource URL: /invoice/[invoiceId]
- Available Verbs: GET, POST, PUT
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/invoice |
200 |
|
GET |
/invoice/123 |
200 |
|
GET |
/invoice/123 |
404 |
invoice 123 not found |
POST |
/invoice |
200 |
invoice created |
POST |
/job/123/invoice |
200 |
invoice created for job 123 using the specified contractId |
POST |
/job/123/invoice |
403 |
not allowed |
POST |
/job/123/invoice |
404 |
job or contract not found |
POST |
/job/123/invoice |
409 |
conflict, contract does not apply to job |
POST |
/invoice |
400 |
missing, incomplete, or invalid parameters |
POST |
/invoice |
403 |
user is not allowed to manage invoices |
POST |
/invoice |
409 |
conflict, contract does not apply to job |
POST |
/invoice/recurring |
200 |
instantiate an invoice from one or more invoice recurrences |
POST |
/invoice/recurring |
400 |
missing, incomplete, or invalid parameters |
POST |
/invoice/recurring |
403 |
not permissioned |
PUT |
/invoice |
405 |
not allowed |
PUT |
/invoice/123 |
200 |
invoice updated |
PUT |
/invoice/123 |
405 |
invoice 123 not found |
PUT |
/invoice/123 |
404 |
invoice 123 not acccessible by the user (or user is not allowed to manage invoices) |
DELETE |
/invoice |
405 |
not allowed |
Query Params
Name |
Type |
Value |
assignedUserId |
integer |
user responsible for this invoice (internal review) |
jobId |
integer |
job to which this invoice is attached |
customerId |
integer |
customer for this invoice |
contractId |
integer |
contract to which this invoice is attached |
assignedOfficeIds |
string |
comma-separated list of integers of office ids, returns invoices served by these offices |
type |
string |
comma-separated list of possible types: "invoice", "vendorbill", or "external" |
status |
string |
comma-separated list of statuses to match, one of: ('ok', 'internal_review', 'pending_accounting', 'processed', 'paid', 'sent', 'failed', 'void'). Note that the 'sent' and 'paid' statuses are deprecated. Use the 'sent' property to find invoices that have been sent to customers. Use the 'paid' property to find invoices by their payment status. |
createdAfter |
integer |
created on or after this timestamp |
createdBefore |
integer |
created on or before this timestamp |
updatedAfter |
integer |
updated on or after this timestamp |
updatedBefore |
integer |
updated on or before this timestamp |
transactionDateBefore |
integer |
transactionDate on or before this timestamp |
transactionDateAfter |
integer |
transactionDate on or after this timestamp |
dueDateBefore |
integer |
dueDate on or before this timestamp |
dueDateAfter |
integer |
dueDate on or after this timestamp |
tag |
string |
comma-separated list of tag strings, only invoices with all tags will be returned |
partial |
boolean |
if true will only match partial invoices, false will only match final invoices |
paid |
string |
'paid' for fully paid invoices, 'unpaid' for unpaid invoices, 'partial' for invoices not fully paid and with at least one non-voided payment |
sent |
boolean |
if true will only match sent invoices, false will only match unsent invoices |
invoiceRecurrenceId |
integer |
invoices generated for this invoice recurrence |
sort |
string |
field to sort by, one of: name, transactionDate; defaults to name. |
limit |
integer |
limit the number of invoices returned (default 2000, maximum 2000) |
POST/PUT Parameters
Name |
Type |
Required |
Value |
type |
string |
for POST, unless contractId is provided |
sets the type of invoice to one of ('invoice', 'vendorbill', 'external', 'unknown'). This is a POST only field. |
status |
string |
for POST, unless contractId is provided |
sets the invoice status to one of ('ok', 'internal_review', 'pending_accounting', 'processed', 'paid', 'sent', 'failed', 'void') Note: some status transitions are invalid, and that 'sent' and 'paid' statuses are deprecated. Use the 'sent' property to indicate that an invoice has been sent to a customer. Use the payment endpoint to record payments for invoices. |
jobId |
integer |
no |
sets the job to which this invoice is attached. This is a POST only field. |
locationId |
integer |
no |
sets the location of the invoice. This is a POST only field. Not to be used with jobId, as location, customer, and vendor are determined from the job if set. |
customerId |
integer |
for POST, if no jobId |
sets the customer of the invoice. This is a POST only field. Not to be used with jobId, as location, customer, and vendor are determined from the job if set. |
vendorId |
integer |
for POST, if no jobId |
sets the vendor of the invoice. This is a POST only field. Not to be used with jobId, as location, customer, and vendor are determined from the job if set. |
name |
string |
no |
invoice name |
invoiceNumber |
string |
no |
sets the invoice's human readable number to match an external accounting system |
notes |
string |
no |
sets the notes that are displayed and printed on the invoice |
customerPo |
string |
no |
customer purchase order number for this invoice. If not provided on POST, if a job is supplied and that job has a purchase order number, the job's purchase order number will be assigned; if a job is not supplied (or if the supplied job has no purchase order number), the supplied contract's purchase order number will be assigned. |
partial |
boolean |
no |
sets this invoice as non-final |
sent |
boolean |
no |
sets the sent status of this invoice |
assignedUserId |
integer |
no |
sets the user to which this invoice is assigned |
contractId |
integer |
no |
If set, an invoice is generated for the jobId using the contractId. The contractId must be provided if invoice items should be generated from job items. If the contractId is for a contract that does not apply to the job, the API will return a 409 error. |
assignedOfficeId |
integer |
no |
id of the office assigned to this invoice (if not provided, will be calculated from the invoice's job or the invoice location's office assignments and the owner's office assignment) |
transactionDate |
integer |
no |
Unix timestamp indicating the date on which this invoice was transacted. Defaults to creation date if not provided. |
visibility |
array(string) |
no |
Visibility. Subset of ("public", "by_service", "items", "noprices", "items_by_type", "type_detail"). Defaults to ("public", "items"). If "public" is set, the grand total will be displayed to the customer. If "by_service" is set, the results will be grouped by service. If "items" is set, the individual line items on the quote will be displayed to the customer. If "noprices" is set, line items will NOT show pricing and tax to the customer. If "items_by_type" is set, one summary line item per item type will be shown to customer. If "type_detail" is set along with "items_by_type", item quantities will be show to customer grouped by item type. |
items |
array |
no |
If given, these will become the invoice items. If not given, the job's items will be used. If given, contractId must also be supplied. Required, unless a jobId and contractId are given. This is a POST only field. |
items.quantity |
double |
for POST |
how many units of this item are being charged on this line |
items.price |
double |
no |
the unit price being charged for this line item, defaults to 0 unless a contract price is set |
items.cost |
double |
no |
the cost of this line item, used for applying markup, defaults to the libItem's standard cost or 0 if not set |
items.description |
string |
if no libItem |
item description |
items.libItemId |
integer |
if no description |
libitem that this item is an instance of |
items.serviceLineId |
integer |
if no libItem or libItem has no service line |
id of the service line |
items.orderIndex |
integer |
no |
items are listed from low to high value, null is the default value |
items.taxRate |
double |
no |
tax rate as a percentage (5.25 = 5.25%) |
items.taxGroup |
double |
no |
tax group id which governs the tax rate of this item. If both a tax group and tax rate are provided on POST, the tax group must agree with the tax rate. If just the tax group is provided on POST, the tax rate will be set from the tax group. On PUT, these fields are independent from each other and no consistency is enforced. |
items.jobItemId |
integer |
no |
jobItem that this line item is charging for |
items.serviceRequestId |
boolean |
no |
serviceRequest that this line item is to be associated with. If not provided no association will be made |
applyTax |
boolean |
no |
POST only, should the new invoice have default taxes applied if location tax flag is true on any taxable lib items if there is only one tax rate found for the postal code of the location? |
termsId |
integer |
no |
terms to which this invoice is attached |
paymentTermsId |
integer |
no |
payment terms which apply to this invoice |
dueDate |
integer |
no |
Unix timestamp indicating the date on which the invoice is due |
POST Parameters for /invoice/recurring action to create invoice from one or more recurrences
Name |
Type |
Required |
Value |
invoiceRecurrenceId |
string, comma delimitted list of invoice recurrence ids |
yes |
the recurrences from which to make an invoice |
Returned Elements
Name |
Type |
Value |
invoices |
array (object) |
list of invoice objects |
id |
string |
invoice id |
uri |
string |
resource identifier for the given invoice |
name |
string |
invoice name |
type |
string |
"invoice" or "vendorbill" |
status |
string |
status of invoice |
invoiceNumber |
string |
human readable number of invoice in external accounting system |
refNumber |
string |
human readable invoice "reference" number, alias of invoiceNumber |
taxAmount |
double |
tax amount in dollars |
subtotal |
double |
total price (quantity * price) not including taxes |
totalPrice |
double |
total amount of the invoice including taxes |
totalPaidAmount |
double |
total amount of the non-void payments associated with this invoice |
location |
Location |
location of the job of this invoice |
job |
Job |
job that this invoice is for |
customer |
Company |
invoice customer |
vendor |
Company |
invoice vendor |
assignedUser |
User |
user currently assigned to handle the invoice |
customerPo |
string |
customer purchase order number for this invoice |
notes |
string |
display notes for this invoice |
partial |
boolean |
indicates that this invoice is non-final |
paid |
boolean |
indicates that this invoice is completely paid |
sent |
boolean |
indicates that this invoice has been sent at least once |
items |
array Invoiceitem |
line items on the invoice |
tags |
array Tag |
tags on the invoice |
transactionDate |
integer |
invoice transaction date is for the day indicated by this timestamp |
contract |
Contract |
invoice contract |
assignedOffice |
Office |
invoice office |
paymentTerms |
Paymentterms |
payment terms for the invoice. Note that the dueDate can be set to something inconsistent with the payment terms |
dueDate |
integer |
timestamp, the date the invoice is due. null signifies no due date |
created |
integer |
invoice was created at this timestamp |
updated |
integer |
invoice was last updated at this timestamp |
visibility |
array (string) |
visibility options, a subset of ("public", "by_service", "items", "noprices", "items_by_type", "type_detail"), empty implies private |
Retrieve all invoice for a given job that need review for a given user
GET /invoice?status=internal_review&jobId=123&assignedUserId=456
200
{
"data": {
"totalPages": 1,
"page": 1,
"invoices": [
{
"uri": "https://api.servicetrade.com/api/invoice/1",
"id": 1,
"name": "Invoice for Job 345632",
"type": "invoice",
"status": "internal_review",
"invoiceNumber": "INV-345632",
"refNumber": "INV-345632",
"taxAmount": 2.00,
"subtotal": 100.00,
"totalPrice": 102.00,
"location": {
"id": 8,
"uri": "https://api.servicetrade.com/api/location/8",
"legacyId": 4567,
"name": "Belk #401 Winder",
"lat": 33.943941,
"lon": -83.756069,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "916 Loganville, Highway, Suite 100",
"city": "Winder",
"state": "GA",
"postalCode": "30620"
},
"taxable": false,
"status": "active"
}
},
"terms": {
"id": 3,
"uri": "https://api.servicetrade.com/api/terms/3",
"name": "Standalone Job Terms"
},
"job": {
"id": 123,
"name": "Job #345632",
"number": 345632,
"type": "inspection",
"uri": "https://api.servicetrade.com/api/job/123"
},
"visibility": [
"public",
"items"
],
"assignedUser": null,
"customer": {
"id": 2,
"name": "Belk",
"uri": "https://api.servicetrade.com/api/company/2",
"status": "active"
},
"vendor": {
"id": 6,
"name": "DunnWell",
"uri": "https://api.servicetrade.com/api/company/6",
"status": "active"
},
"customerPo": "PO # 12345",
"notes": null,
"partial": true,
"paid": false,
"sent": false,
"items": [],
"tags": [],
"transactionDate": 1377111510,
"paymentTerms": 3,
"dueDate": 1406577320,
"contract": null,
"assignedOffice": {
"id": 123,
"uri": "https://api.servicetrade.com/api/location/69",
"name": "StandAlone Satellite Office",
"legacyId": null,
"lat": 35.611172,
"lon": -78.060822,
"phoneNumber": "(919) 555-0002",
"email": "uuxiiuit+location@gmail.com",
"primaryContact": null,
"address": {
"street": "8071 Newsome Mill Rd",
"city": "Lucama",
"state": "NC",
"postalCode": "27851"
},
"taxable": false
},
"updated": 1406562341,
"created": 1377111510
},
{
"uri": "https://api.servicetrade.com/api/invoice/4",
"id": 4,
"name": "Vendor Bill for Job 345632",
"type": "vendorbill",
"status": "internal_review",
"invoiceNumber": "INV-345632",
"refNumber": "INV-345632",
"taxAmount": 2.00,
"subtotal": 100.00,
"totalPrice": 102.00,
"location": {
"id": 8,
"uri": "https://api.servicetrade.com/api/location/8",
"legacyId": 4567,
"name": "Belk #401 Winder",
"lat": 33.943941,
"lon": -83.756069,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "916 Loganville, Highway, Suite 100",
"city": "Winder",
"state": "GA",
"postalCode": "30620"
},
"taxable": false,
"status": "active"
},
"terms": {
"id": 3,
"uri": "https://api.servicetrade.com/api/terms/3",
"name": "Standalone Job Terms"
},
"job": {
"id": 123,
"name": "Job #345632",
"number": 345632,
"type": "inspection",
"uri": "https://api.servicetrade.com/api/job/123"
},
"assignedUser": {
"id": 456,
"name": "Arthur Dent",
"uri": "https://api.servicetrade.com/api/user/456",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"customer": {
"id": 6,
"name": "DunnWell",
"uri": "https://api.servicetrade.com/api/company/6",
"status": "active"
}
"vendor": {
"id": 9,
"name": "Super Awesome Company, Inc",
"uri": "https://api.servicetrade.com/api/company/9",
"status": "active"
},
"customerPo": "PO # 5678",
"notes": null,
"partial": false,
"paid": false,
"sent": false,
"items": [
{
"id": 2765,
"uri": "https://api.servicetrade.com/api/invoiceitem/2",
"description": "4 Tank Suppression System Inspection",
"quantity": 1,
"price": 50,
"subtotal": 50,
"taxRate": 0,
"taxGroup": null,
"taxAmount": 0,
"totalPrice": 50,
"serviceLine": {
"id": 5,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "https://app.servicetrade.com/image/icons/service_lines/32/SUP.png"
},
"libItem": {
"id": 408,
"uri": "https://api.servicetrade.com/api/libitem/408",
"name": "4 Tank Suppression System Inspection",
"type": "Service",
"code": "4TNKINSP"
},
"jobItem": {
"id": 319,
"uri": "http://snaap.dev:20080/api/jobitem/319",
"description": "4 Tank Suppression System Inspection",
"cost": null,
"usedOn": 1399994065
},
"serviceRequest": null,
},
{
"id": 2658,
"uri": "https://api.servicetrade.com/api/invoiceitem/2",
"description": "3 Tank Suppression System Inspection",
"quantity": 1,
"price": 50,
"subtotal": 50,
"taxRate": 0,
"taxGroup": null,
"taxAmount": 0,
"totalPrice": 50,
"serviceLine": {
"id": 5,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "https://app.servicetrade.com/image/icons/service_lines/32/SUP.png"
},
"libItem": {
"id": 409,
"uri": "https://api.servicetrade.com/api/libitem/408",
"name": "3 Tank Suppression System Inspection",
"type": "Service",
"code": "3TNKINSP"
},
"jobItem": null,
"serviceRequest": null,
},
],
"tags": [],
"transactionDate": 1377111510
"assignedOffice": {
"id": 123,
"uri": "https://api.servicetrade.com/api/location/69",
"name": "StandAlone Satellite Office",
"legacyId": null,
"lat": 35.611172,
"lon": -78.060822,
"phoneNumber": "(919) 555-0002",
"email": "uuxiiuit+location@gmail.com",
"primaryContact": null,
"address": {
"street": "8071 Newsome Mill Rd",
"city": "Lucama",
"state": "NC",
"postalCode": "27851"
},
"taxable": false
},
"paymentTerms": 3,
"dueDate": 1406577320,
"contract": null,
"updated": 1406562341,
"created": 1377111510
}
]
}
}
No invoice matches found
GET /invoice?jobId=78
200
{
"data": {
"totalPages": 1,
"page": 1,
"invoices": []
}
}
Retrieve information for a single invoice
GET /invoice/4
200
{
"data": {
"uri": "https://api.servicetrade.com/api/invoice/4",
"id": 4,
"name": "Vendor Bill for Job 345632",
"type": "vendorbill",
"status": "ok",
"invoiceNumber": 4,
"refNumber": "4",
"taxAmount": 2.00,
"subtotal": 100.00,
"totalPrice": 102.00,
"location": {
"id": 8,
"legacyId": 4567,
"name": "Belk #401 Winder",
"uri": "https://api.servicetrade.com/api/location/8",
"lat": 33.943941,
"lon": -83.756069,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "916 Loganville, Highway, Suite 100",
"city": "Winder",
"state": "GA",
"postalCode": "30620"
},
"taxable": false,
"status": "active"
},
"terms": {
"id": 3,
"uri": "https://api.servicetrade.com/api/terms/3",
"name": "Standalone Job Terms"
},
"job": {
"id": 123,
"name": "Job #345632",
"number": 345632,
"type": "inspection",
"uri": "https://api.servicetrade.com/api/job/123"
},
"visibility": [
"public",
"items"
],
"assignedUser": {
"id": 456,
"name": "Arthur Dent",
"uri": "https://api.servicetrade.com/api/user/456",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"customer": {
"id": 6,
"name": "DunnWell",
"uri": "https://api.servicetrade.com/api/company/6",
"status": "active"
},
"vendor": {
"id": 9,
"name": "Super Awesome Company, Inc",
"uri": "https://api.servicetrade.com/api/company/9",
"status": "active"
},
"customerPo": "PO # 555",
"notes": null,
"partial": false,
"paid": false,
"sent": false,
"items": [
{
"id": 2658,
"uri": "https://api.servicetrade.com/api/invoiceitem/2",
"description": "3 Tank Suppression System Inspection",
"quantity": 1,
"price": 100,
"subtotal": 100,
"taxRate": 0,
"taxGroup": null,
"taxAmount": 0,
"totalPrice": 100,
"serviceLine": {
"id": 5,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "https://app.servicetrade.com/image/icons/service_lines/32/SUP.png"
},
"libItem": {
"id": 409,
"uri": "https://api.servicetrade.com/api/libitem/408",
"name": "Personal Item",
"type": "Part",
"code": "PERSONAL"
},
"jobItem": null
"serviceRequest": null
}
],
"tags": [
{
"id": 1,
"uri": "http://0.0.0.0:80/api/tag/1",
"name": "one"
}
],
"transactionDate": 1377111510,
"assignedOffice": {
"id": 123,
"uri": "https://api.servicetrade.com/api/location/69",
"name": "StandAlone Satellite Office",
"legacyId": null,
"lat": 35.611172,
"lon": -78.060822,
"phoneNumber": "(919) 555-0002",
"email": "uuxiiuit+location@gmail.com",
"primaryContact": null,
"address": {
"street": "8071 Newsome Mill Rd",
"city": "Lucama",
"state": "NC",
"postalCode": "27851"
},
"taxable": false
},
"paymentTerms": 3,
"dueDate": 1406577320,
"contract": null,
"updated": 1406562341,
"created": 1377111510
}
}
Retrieve information for an invoice which does not exist
GET /invoice/567
404
Create an invoice with a specified set of line items
POST /invoice
{"type":"invoice","status":"ok","jobId":123,"items":[{"description":"Misc Parts","serviceLineId":4,"quantity":3,"price":24.00}, {"libItemId":7,"quantity":1,"serviceRequestId":256}]}
200
{
"data": {
"uri": "https://api.servicetrade.com/api/invoice/5",
"id": 5,
"name": "Invoice for Job 345632",
"type": "invoice",
"status": "ok",
"invoiceNumber": 5,
"refNumber": "5",
"taxAmount": 0.00,
"subtotal": 72.00,
"totalPrice": 72.00,
"location": {
"id": 8,
"legacyId": 4567,
"name": "Belk #401 Winder",
"uri": "https://api.servicetrade.com/api/location/8",
"lat": 33.943941,
"lon": -83.756069,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "916 Loganville, Highway, Suite 100",
"city": "Winder",
"state": "GA",
"postalCode": "30620"
},
"taxable": false,
"status": "active"
},
"terms": {
"id": 3,
"uri": "https://api.servicetrade.com/api/terms/3",
"name": "Standalone Job Terms"
},
"job": {
"id": 123,
"name": "Job #345632",
"number": 345632,
"type": "inspection",
"uri": "https://api.servicetrade.com/api/job/123"
},
"visibility": [
"public",
"items"
],
"assignedUser": {
"id": 456,
"name": "Arthur Dent",
"uri": "https://api.servicetrade.com/api/user/456",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"customer": {
"id": 6,
"name": "DunnWell",
"uri": "https://api.servicetrade.com/api/company/6",
"status": "active"
},
"vendor": {
"id": 9,
"name": "Super Awesome Company, Inc",
"uri": "https://api.servicetrade.com/api/company/9",
"status": "active"
},
"customerPo": null,
"notes": null,
"partial": false,
"paid": false,
"sent": false,
"items": [
{
"id": 2659,
"uri": "https://api.servicetrade.com/api/invoiceitem/2659",
"description": "Misc Parts",
"quantity": 3,
"price": 24.00,
"taxRate": 0.000,
"taxGroup": null,
"taxAmount": 0.00,
"subtotal": 72.00,
"totalPrice": 72.00,
"invoice": {
"id": 5,
"uri": "https://api.servicetrade.com/api/invoice/5",
"name": "Invoice for Job 345632"
},
"libItem": {
"id": 470,
"uri": "https://api.servicetrade.com/api/libitem/470",
"name": "Other"
},
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/SUPP.png"
},
"jobItem": null,
"serviceRequest": null,
},
{
"id": 2660,
"uri": "https://api.servicetrade.com/api/invoiceitem/2660",
"description": "CCW Zirconium Flange",
"quantity": 1,
"price": 0.00,
"taxRate": 0.000,
"taxAmount": 0.00,
"subtotal": 0.00,
"totalPrice": 0.00,
"invoice": {
"id": 5,
"uri": "https://api.servicetrade.com/api/invoice/5",
"name": "Invoice for Job 345632"
},
"libItem": {
"id": 471,
"uri": "https://api.servicetrade.com/api/libitem/471",
"name": "CCW Zirconium Flange",
"type": "Part",
"code": "CCW-ZC-FLNG"
},
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/SUPP.png"
},
"jobItem": null,
"serviceRequest": {
"id": 256,
"uri": "http://localhost/api/servicerequest/256"
"description": "SR 1945778353"
}
}
],
"tags": [],
"transactionDate": 1377111510,
"assignedOffice": {
"id": 123,
"uri": "https://api.servicetrade.com/api/location/69",
"name": "StandAlone Satellite Office",
"legacyId": null,
"lat": 35.611172,
"lon": -78.060822,
"phoneNumber": "(919) 555-0002",
"email": "uuxiiuit+location@gmail.com",
"primaryContact": null,
"address": {
"street": "8071 Newsome Mill Rd",
"city": "Lucama",
"state": "NC",
"postalCode": "27851"
},
"taxable": false
},
"paymentTerms": 3,
"dueDate": 1406577320,
"contract": null,
"updated": 1406562341,
"created": 1377111510
}
}
Return to Top
Invoice Item
The invoice item resource is used to retrieve or modify line items related to a single invoice.
- Resource URL: /invoice/[invoiceId]/item/[itemId]
- Resource URL: /invoiceitem/[itemId]
- Available Verbs: GET, POST, PUT, DELETE
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/invoice/123/item |
200 |
|
GET |
/invoiceitem?invoiceId=123 |
200 |
|
GET |
/invoice/123/item/456 |
200 |
|
GET |
/invoiceitem/456 |
200 |
|
GET |
/invoice/123/item/456 |
404 |
invoice 123 not found, or invoice item 456 not found on invoice 123 |
GET |
/invoiceitem/456 |
404 |
invoice item 456 not found |
GET |
/invoiceitem |
404 |
invoiceId must be specified when searching for invoice items |
POST |
/invoiceitem |
200 |
|
POST |
/invoice/123/item |
200 |
|
POST |
/invoice/123/item |
400 |
parameters invalid |
POST |
/invoice/123/item |
403 |
do not have permission to modify invoice 123 |
POST |
/invoice/123/item |
404 |
invoice 123 not found |
POST |
/invoice/123/item |
409 |
tax group and tax rate disagree on tax amount |
PUT |
/invoiceitem |
405 |
not allowed without id |
PUT |
/invoiceitem/456 |
200 |
|
PUT |
/invoice/123/item/456 |
200 |
|
PUT |
/invoice/123/item/456 |
400 |
parameters invalid |
PUT |
/invoice/123/item/456 |
403 |
do not have permission to modify invoice 123 |
PUT |
/invoice/123/item/456 |
404 |
invoice 123 not found |
DELETE |
/invoiceitem |
405 |
not allowed without id |
DELETE |
/invoice/123/item/456 |
403 |
do not have permission to modify invoice 123 |
DELETE |
/invoice/123/item/456 |
404 |
invoice 123 not found |
DELETE |
/invoice/123/item/456 |
204 |
invoice item deleted |
Query Params
Name |
Type |
Value |
invoiceId |
integer |
(Required) invoice to which this item belongs |
POST/PUT Parameters
Name |
Type |
Required |
Value |
invoiceId |
integer |
yes |
sets the invoice to which this item is belongs |
quantity |
double |
yes |
how many units of this item are being charged on this line |
price |
double |
yes |
the unit price being charged for this line item |
description |
string |
if no libItem |
item description |
libItemId |
integer |
if no description |
libitem that this item is an instance of |
serviceLineId |
integer |
if no libItem or libItem has no service line |
id of the service line |
orderIndex |
integer |
no |
items are listed from low to high value, null is the default value |
taxRate |
double |
no |
tax rate as a percentage (5.25 = 5.25%) |
taxGroupId |
integer |
no |
tax group id which governs the tax rate of this item. If both a tax group and tax rate are provided on POST, the tax group must agree with the tax rate. If just the tax group is provided on POST, the tax rate will be set from the tax group. On PUT, these fields are independent from each other and no consistency is enforced. |
jobItemId |
integer |
no |
indicates which jobItem this item was created from |
serviceRequestId |
integer |
no |
indicates which Job Service Request the item is associated with it |
Returned Elements
Name |
Type |
Value |
id |
integer |
item id |
uri |
string |
resource identifier for the given item |
description |
string |
item description |
quantity |
double |
item quantity |
price |
double |
item unit price |
subtotal |
double |
total price (quantity * price) not including taxes |
taxRate |
double |
tax rate as a percentage (5.5 indicates 5.5%) |
taxGroup |
TaxGroup |
tax group governing this item |
taxAmount |
double |
tax amount in dollars |
totalPrice |
double |
total including taxes |
orderIndex |
integer |
order in which item appears in list of invoice items |
libItem |
Libitem |
libitem that this item is an instance of |
serviceLine |
Service Line |
service line associated with this item |
jobItem |
Job Item |
jobItem this item was created from |
invoice |
Invoice |
invoice to which this item belongs |
serviceRequest |
Service Request |
serviceRequest of the invoice item |
invoiceRecurrence |
Invoice Recurrence |
invoice recurrence that this invoice item came from, or null if it doesn't relate to any invoice recurrence |
windowStart |
integer |
Unix timestamp of window start of related invoice recurrence instance, if applicable |
windowEnd |
integer |
Unix timestamp of window end of related invoice recurrence instance, if applicable |
created |
integer |
Unix timestamp of this record's creation time |
updated |
integer |
Unix timestamp of when this record was last updated |
Retrieve all invoice items for a given invoice
GET /invoice/45/item
GET /invoiceitem?invoiceId=45
200
{
"data": {
"totalPages": 1,
"page": 1,
"items": [
{
"id": 11,
"uri": "https://api.servicetrade.com/api/invoiceitem/11",
"description": "Towel",
"quantity": 1,
"price": 100.00,
"taxRate": 5.000,
"taxGroup": null,
"taxAmount": 5.00,
"subtotal": 100.00,
"totalPrice": 105.00,
"invoice": {
"id": 45,
"uri": "https://api.servicetrade.com/api/invoice/45",
"name": "Invoice #3230004-SQKY-CLN"
},
"libItem": {
"id": 408,
"uri": "https://api.servicetrade.com/api/libitem/408",
"name": "Personal Item",
"type": "Part",
"code": "PERSONAL"
},
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/SUPP.png"
},
"jobItem": {
"id": 341,
"uri": "https://api.servicetrade.com/api/jobitem/341",
"description": "Towel",
"cost": null,
"usedOn": 1399994065
},
"serviceRequest": null,
"invoiceRecurrence": null,
"windowStart": null,
"windowEnd": null
},
{
"id": 13,
"uri": "https://api.servicetrade.com/api/invoiceitem/13",
"description": "Unknown Charge",
"quantity": 2,
"price": 100.00,
"taxRate": 5.000,
"taxGroup": null,
"taxAmount": 10.00,
"subtotal": 200.00,
"totalPrice": 210.00,
"invoice": {
"id": 45,
"uri": "https://api.servicetrade.com/api/invoice/45",
"name": "Invoice #3230004-SQKY-CLN"
},
"libItem": {
"id": 283,
"uri": "https://api.servicetrade.com/api/libitem/283",
"name": "Other",
"type": "Other",
"code": "OTHER-UNK"
},
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/SUPP.png"
},
"serviceRequest": null,
"jobItem": null,
"invoiceRecurrence": null,
"windowStart": null,
"windowEnd": null
}
]
}
}
No items found on invoice
GET /invoice/78/item
200
{
"data": {
"totalPages": 1,
"page": 1,
"items": []
}
}
Retrieve information for a single invoice item
GET /invoiceitem/11
200
{
"data": {
"id": 11,
"uri": "https://api.servicetrade.com/api/invoiceitem/11",
"description": "Towel",
"quantity": 2,
"price": 100.00,
"taxRate": 5.000,
"taxGroup": null,
"taxAmount": 10.00,
"subtotal": 200.00,
"totalPrice": 210.00,
"invoice": {
"id": 45,
"uri": "https://api.servicetrade.com/api/invoice/45",
"name": "Invoice #3230004-SQKY-CLN"
},
"libItem": {
"id": 408,
"uri": "https://api.servicetrade.com/api/libitem/408",
"name": "Personal Item",
"type": "Part",
"code": "PERSONAL"
},
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/SUPP.png"
},
"serviceRequest": null,
"jobItem": null,
"invoiceRecurrence": null,
"windowStart": null,
"windowEnd": null
}
}
Add an item to an invoice
POST /invoice/78/item
{"description":"CCW Zirconium Flange","quantity":3,"price":24.00}
200
{
"data": {
"id": 13,
"uri": "https://api.servicetrade.com/api/invoiceitem/13",
"description": "CCW Zirconium Flange",
"quantity": 2,
"price": 100.00,
"taxRate": 5.000,
"taxGroup": null,
"taxAmount": 10.00,
"subtotal": 200.00,
"totalPrice": 210.00,
"invoice": {
"id": 78,
"uri": "https://api.servicetrade.com/api/invoice/78",
"name": "Invoice #7721402-WAH"
},
"libItem": {
"id": 471,
"uri": "https://api.servicetrade.com/api/libitem/471",
"name": "CCW Zirconium Flange",
"type": "Part",
"code": "CCW-ZC-FLNG"
},
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/SUPP.png"
},
"jobItem": null,
"serviceRequest": null,
"invoiceRecurrence": null,
"windowStart": null,
"windowEnd": null
}
}
Return to Top
InvoiceRecurrence
The invoicerecurrence resource is used to update and retrieve invoice recurrences.
To end an invoice recurrence, PUT an endsOn date to that recurrence.
- Resource URL: /invoicerecurrence/[invoiceRecurrenceId]
- Available Verbs: GET, POST, PUT
- Authentication Required: yes
Note that an invoice recurrence can be in three possible states:
- Active: The endsOn is null or in the future, and there is a nextDue that is before it
- Complete: The endsOn is in the future but nextDue is set after this value. It will require no more invoices.
- Expired: The endsOn is in the past. There may or may not be uninvoiced items (if nextDue is earlier than endsOn, there is).
The Recurring Invoices accordion on the location page will only show Active invoice recurrences.
An invoice recurrence can be used to generate invoices only if it has at least one Invoice Recurrence Item.
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/invoicerecurrence |
200 |
|
GET |
/invoicerecurrence/123 |
200 |
|
GET |
/invoicerecurrence/123 |
404 |
invoicerecurrence 123 not found (or not accessible by the user) |
POST |
/invoicerecurrence |
200 |
invoicerecurrence created |
POST |
/invoicerecurrence |
400 |
invoicerecurrence not created: malformed data |
PUT |
/invoicerecurrence |
405 |
not allowed |
PUT |
/invoicerecurrence/123 |
200 |
|
PUT |
/invoicerecurrence/123 |
400 |
invoicerecurrence not updated: malformed data |
PUT |
/invoicerecurrence/123 |
404 |
invoicerecurrence 123 not found (or not accessible by the user) |
DELETE |
/invoicerecurrence |
405 |
not allowed |
DELETE |
/invoicerecurrence/123 |
405 |
not allowed |
Query Params
Name |
Type |
Value |
nextInvoiceAfter |
integer |
next due on or after this timestamp |
nextInvoiceBefore |
integer |
next due on or before this timestamp |
customerId |
string |
comma delimited list of integers, return only invoice recurrences applying to the customers |
locationId |
string |
comma delimited list of integers, return only invoice recurrences applying to the locations |
officeId |
string |
comma delimited list of integers, return only invoice recurrences applying to locations assigned to these offices |
contractId |
string |
comma delimited list of integers, return only invoice recurrences applying to the contracts |
serviceLineId |
string |
comma delimited list of integers, return only invoice recurrences applying to the service lines |
noEndsOn |
boolean |
returns only recurrences that have no endsOn date |
POST/PUT Parameters
Name |
Type |
POST only? |
Required for create? |
Value |
locationId |
integer |
yes |
yes |
location the to be billed for |
endsOn |
integer |
|
no |
when the recurring invoices are to end (null for no set date). When endsOn is set, all unused invoice recurrence instances will be deleted, regardless of the date. |
description |
string |
|
yes |
description of this recurring invoice |
serviceLineId |
integer |
|
yes |
what line of service this recurrence is for |
contractId |
integer |
yes |
yes |
identifies the contract for this recurrence, contract must be valid for location |
frequency |
string |
|
yes |
frequency of recurrence, one of: monthly, yearly. |
interval |
integer |
|
yes |
interval of recurrence. Think of it this way: "this recurrence happens every [interval] [frequency]'s". Supported on POST only. |
customerId |
integer |
yes |
no |
customer to be invoiced. If this is null, invoices will be generated using the contract's customer if there is one, or else the location's company. |
vendorId |
integer |
yes |
no |
vendor who is invoicing (defaults to account's prime company) |
nextDue |
integer |
|
yes |
Unix timestamp of the next time an invoice is due. Note that dueness doesn't have to be on the first day of the month but invoice recurrence instances will always reflect full calendar pages of a billable event. So, for example, a monthly invoice recurrence with a next_due on Aug 15 will be for Aug 1 - Aug 31 the next time it is billed. |
Returned Elements
Name |
Type |
Value |
uri |
string |
resource identifier of the invoice recurrence |
id |
integer |
invoice recurrence id |
description |
string |
invoice recurrence description |
serviceLine |
Service Line |
service line |
customer |
Customer |
|
vendor |
Vendor |
|
location |
Location |
|
nextDue |
integer |
Unix timestamp of the invoice recurrence’s next due date and time |
endsOn |
integer |
Unix timestamp of the invoice recurrence’s ends on date and time |
created |
integer |
Unix timestamp of the invoice recurrence’s creation date and time |
frequency |
string |
frequency of recurrence, one of: monthly, yearly |
interval |
integer |
interval of recurrence. Think of it this way: "this recurrence happens every [interval] [frequency]'s" |
contract |
Contract |
|
items |
array Invoice Recurrence Item |
items that will be invoiced |
Retrieve all invoice recurrences in your account
GET /invoicerecurrence
200
{
"data": {
"totalPages": 1
"page": 1
"invoiceRecurrences": [
{
"uri": "https://api.servicetrade.com/api/invoicerecurrence/377"
"id": 377
"description": "Lawn care services, front"
"serviceLine": {
"id": 198,
"name": "Lawn Care",
"trade": "Landscaping",
"abbr": "LNCAR",
"icon": "https://app.servicetrade.com/image/icons/service_lines/32/OTHER.png",
},
"location": {
"id": 69,
"uri": "https://api.servicetrade.com/api/location/70",
"name": "Big Bang Burger Bar - Hope Mills",
"legacyId": null,
"phoneNumber": "(910) 860-2200",
"generalManager": "Tony Rutland",
"email": "trutland@example.com",
"primaryContact": null,
"address": {
"street": "3020 N. Main St., Suite 338",
"city": "Hope Mills",
"state": "NC",
"postalCode": "28348"
},
"taxable": false,
"status": "active"
},
"customer": {
"id": 39,
"uri": "https://api.servicetrade.com/api/company/39",
"name": "Big Bang Burger Bar",
"status": "active"
},
"vendor": {
"id": 31,
"uri": "https://api.servicetrade.com/api/company/313",
"name": "Lawn Shield Services",
"status": "active"
},
"contract": {
"id": 1999,
"uri": "http://api.servicetrade.com/api/contract/1999",
"name": "Default Pricing Contract"
},
"frequency": "monthly",
"interval": 1,
"nextDue": 1567487660,
"endsOn": null,
"items": [],
"created": 1565213231
},
{
"uri": "https://api.servicetrade.com/api/invoicerecurrence/378"
"id": 378
"description": "Lawn care services, back"
"serviceLine": {
"id": 198,
"name": "Lawn Care",
"trade": "Landscaping",
"abbr": "LNCAR",
"icon": "https://app.servicetrade.com/image/icons/service_lines/32/OTHER.png",
},
"location": {
"id": 69,
"uri": "https://api.servicetrade.com/api/location/70",
"name": "Big Bang Burger Bar - Hope Mills",
"legacyId": null,
"phoneNumber": "(910) 860-2200",
"generalManager": "Tony Rutland",
"email": "trutland@example.com",
"primaryContact": null,
"address": {
"street": "3020 N. Main St., Suite 338",
"city": "Hope Mills",
"state": "NC",
"postalCode": "28348"
},
"taxable": false,
"status": "active"
},
"customer": {
"id": 39,
"uri": "https://api.servicetrade.com/api/company/39",
"name": "Big Bang Burger Bar",
"status": "active"
},
"vendor": {
"id": 31,
"uri": "https://api.servicetrade.com/api/company/313",
"name": "Lawn Shield Services",
"status": "active"
},
"contract": {
"id": 1999,
"uri": "http://api.servicetrade.com/api/contract/1999",
"name": "Default Pricing Contract"
},
"frequency": "monthly",
"interval": 1,
"nextDue": 1567487660,
"endsOn": null,
"items": [],
"created": 1565213231
}
]
}
}
Retrieve information for one invoice recurrences in your account
GET /invoicerecurrence/377
200
{
"data": {
"uri": "https://api.servicetrade.com/api/invoicerecurrence/377"
"id": 377
"description": "Lawn care services, front"
"serviceLine": {
"id": 198,
"name": "Lawn Care",
"trade": "Landscaping",
"abbr": "LNCAR",
"icon": "https://app.servicetrade.com/image/icons/service_lines/32/OTHER.png",
},
"location": {
"id": 69,
"uri": "https://api.servicetrade.com/api/location/70",
"name": "Big Bang Burger Bar - Hope Mills",
"legacyId": null,
"phoneNumber": "(910) 860-2200",
"generalManager": "Tony Rutland",
"email": "trutland@example.com",
"primaryContact": null,
"address": {
"street": "3020 N. Main St., Suite 338",
"city": "Hope Mills",
"state": "NC",
"postalCode": "28348"
},
"taxable": false,
"status": "active"
},
"customer": {
"id": 39,
"uri": "https://api.servicetrade.com/api/company/39",
"name": "Big Bang Burger Bar",
"status": "active"
},
"vendor": {
"id": 31,
"uri": "https://api.servicetrade.com/api/company/313",
"name": "Lawn Shield Services",
"status": "active"
},
"contract": {
"id": 1999,
"uri": "http://api.servicetrade.com/api/contract/1999",
"name": "Default Pricing Contract"
},
"frequency": "monthly",
"interval": 1,
"nextDue": 1567487660,
"endsOn": null,
"items": [],
"created": 1565213231
}
}
Create a new invoice recurrence
POST /invoicerecurrence
{
"locationId": 114,
"contractId": 19,
"description": "subscription",
"frequency": "monthly",
"interval": 1,
"customerId": 36,
"nextDue": 1567123200,
"serviceLineId": 3
}
200
{
"data": {
"uri": "http://api.servicetrade.com/api/invoicerecurrence/242",
"id": 242,
"description": "subscription",
"serviceLine": {
"id": 3,
"name": "Portable Extinguishers",
"trade": "Fire Protection",
"abbr": "EXT",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/EXT.png"
},
"location": {
"id": 114,
"uri": "http://api.servicetrade.com/api/location/114",
"name": "Dickey's BBQ - Florence",
"legacyId": null,
"lat": 34.230043,
"lon": -79.799757,
"phoneNumber": "(843) 407-6129",
"email": "uuxiiuit+location@gmail.com",
"primaryContact": {
"id": 114,
"uri": "http://api.servicetrade.com/api/contact/114",
"firstName": "Lonnie",
"lastName": "Baxter",
"phone": "843-407-6129",
"mobile": "",
"alternatePhone": "",
"email": "uuxiiuit+location@gmail.com",
"type": "management"
},
"address": {
"street": "2003 West Lucas",
"city": "Florence",
"state": "SC",
"postalCode": "29501"
},
"taxable": false,
"status": "active"
},
"customer": {
"id": 36,
"uri": "http://api.servicetrade.com/api/company/36",
"name": "Hwy 55 Burgers",
"status": "active"
},
"vendor": {
"id": 34,
"uri": "http://api.servicetrade.com/api/company/34",
"name": "StandAlone Safety",
"status": "active"
},
"contract": {
"id": 19,
"uri": "http://api.servicetrade.com/api/contract/19",
"name": "StandAlone Standard Contract"
},
"frequency": "monthly",
"interval": 1,
"nextDue": 1567123200,
"endsOn": null,
"items": [],
"created": 1565920063
}
}
Return to Top
InvoiceRecurrence Item
The invoice recurrence item resource is used to retrieve or modify line items related to a single invoice recurrence.
- Resource URL: /invoicerecurrence/[invoiceRecurrenceId]/item/[itemId]
- Resource URL: /invoiceitem/[itemId]
- Available Verbs: GET, POST, PUT, DELETE
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/invoicerecurrence/123/item |
200 |
|
GET |
/invoicerecurrenceitem?invoiceId=123 |
200 |
|
GET |
/invoicerecurrence/123/item/456 |
200 |
|
GET |
/invoicerecurrenceitem/456 |
200 |
|
GET |
/invoicerecurrence/123/item/456 |
404 |
invoice recurrence 123 not found, or invoice recurrence item 456 not found on invoice 123 |
GET |
/invoicerecurrenceitem/456 |
404 |
invoice recurrence item 456 not found |
GET |
/invoicerecurrenceitem |
404 |
invoiceRecurrenceId must be specified when searching for invoice recurrence items |
POST |
/invoicerecurrenceitem |
200 |
|
POST |
/invoicerecurrence/123/item |
200 |
|
POST |
/invoicerecurrence/123/item |
400 |
parameters invalid |
POST |
/invoicerecurrence/123/item |
403 |
do not have permission to modify invoice recurrence 123 |
POST |
/invoicerecurrence/123/item |
404 |
invoice recurrence 123 not found |
PUT |
/invoicerecurrenceitem |
405 |
not allowed without id |
PUT |
/invoicerecurrenceitem/456 |
200 |
|
PUT |
/invoicerecurrence/123/item/456 |
200 |
|
PUT |
/invoicerecurrence/123/item/456 |
400 |
parameters invalid |
PUT |
/invoicerecurrence/123/item/456 |
403 |
do not have permission to modify invoice recurrence 123 |
PUT |
/invoicerecurrence/123/item/456 |
404 |
invoice recurrence 123 not found |
DELETE |
/invoicerecurrenceitem |
405 |
not allowed without id |
DELETE |
/invoicerecurrence/123/item/456 |
403 |
do not have permission to modify invoice recurrence 123 |
DELETE |
/invoicerecurrence/123/item/456 |
404 |
invoice recurrence 123 not found |
DELETE |
/invoicerecurrence/123/item/456 |
204 |
invoice recurrence item deleted |
Query Params
Name |
Type |
Value |
invoiceRecurrenceId |
integer |
(Required) invoice to which this item belongs |
POST/PUT Parameters
Name |
Type |
Required |
Value |
invoiceRecurrenceId |
integer |
yes |
sets the invoice recurrence to which this item belongs |
quantity |
double |
yes |
how many units of this item are being charged on this line |
price |
double |
no |
the unit price being charged for this line item |
cost |
double |
no |
the unit cost for this line item |
description |
string |
if no libItemId |
item description |
libItemId |
integer |
if no description |
libitem that this item is an instance of |
serviceLineId |
integer |
if no libItemId or libItem has no service line |
id of the service line |
orderIndex |
integer |
no |
items are listed from low to high value, null is the default value |
taxable |
boolean |
no |
is this item taxable? defaults to true. |
Returned Elements
Name |
Type |
Value |
uri |
string |
resource identifier of the invoice recurrence item |
id |
integer |
invoice recurrence item id |
description |
string |
invoice recurrence item description |
serviceLine |
Service Line |
service line |
libItem |
Lib Item |
lib item |
quantity |
float |
quantity of the job item |
cost |
float |
cost of this item, else null |
price |
float |
price of this item, else null |
Retrieve data for one invoice item
GET /invoicerecurrenceitem/127
200
{
"data": {
"id": 127,
"uri": "https://api.servicetrade.com/api/invoicerecurrenceitem/127",
"description": "BatteryLead",
"quantity": 3,
"price": null,
"cost": null,
"invoiceRecurrence": {
"id": 242,
"uri": "https://api.servicetrade.com/api/invoicerecurrence/242"
},
"serviceLine": {
"id": 2,
"name": "Emergency / Exit Lights",
"trade": "Fire Protection",
"abbr": "ELIGHT",
"icon": "https://app.servicetrade.com/image/icons/service_lines/32/ELIGHT.png"
},
"libItem": {
"id": 781,
"uri": "https://api.servicetrade.com/api/libitem/781",
"name": "Battery Lead",
"type": "Part",
"code": null,
"externalIds": {
"peachtree": ""
}
},
"orderIndex": null,
"taxable": true
}
}
Retrieve all invoice recurrences item for a recurrence
GET /invoicerecurrenceitem/invoiceRecurrenceId=242
200
{
"data": {
"totalPages": 1,
"page": 1,
"invoiceRecurrenceItems": [
{
"id": 127,
"uri": "https://api.servicetrade.com/api/invoicerecurrenceitem/127",
"description": "BatteryLead",
"quantity": 3,
"price": null,
"cost": null,
"invoiceRecurrence": {
"id": 242,
"uri": "https://api.servicetrade.com/api/invoicerecurrence/242"
},
"serviceLine": {
"id": 2,
"name": "Emergency / Exit Lights",
"trade": "Fire Protection",
"abbr": "ELIGHT",
"icon": "https://app.servicetrade.com/image/icons/service_lines/32/ELIGHT.png"
},
"libItem": {
"id": 781,
"uri": "https://api.servicetrade.com/api/libitem/781",
"name": "Battery Lead",
"type": "Part",
"code": null,
"externalIds": {
"peachtree": ""
}
},
"orderIndex": null,
"taxable": true
},
{
"id": 128,
"uri": "https://api.servicetrade.com/api/invoicerecurrenceitem/128",
"description": "Bulbs",
"quantity": 3,
"price": null,
"cost": null,
"invoiceRecurrence": {
"id": 242,
"uri": "https://api.servicetrade.com/api/invoicerecurrence/242"
},
"serviceLine": {
"id": 2,
"name": "Emergency / Exit Lights",
"trade": "Fire Protection",
"abbr": "ELIGHT",
"icon": "https://api.servicetrade.com/image/icons/service_lines/32/ELIGHT.png"
},
"libItem": {
"id": 1090,
"uri": "https://api.servicetrade.com/api/libitem/1090",
"name": "Bulbs - DC",
"type": "Part",
"code": null,
"externalIds": {
"peachtree": ""
}
},
"orderIndex": null,
"taxable": true
}
]
}
}
Add an item to an invoice recurrence
POST /invoicerecurrenceitem
{
"invoiceRecurrenceId": 242,
"quantity": 3,
"libItemId": 1090,
"description": "Bulbs",
"serviceLineId": 2
}
200
{
"data": {
"id": 128,
"uri": "http://api.servicetrade.com/api/invoicerecurrenceitem/128",
"description": "Bulbs",
"quantity": 3,
"price": null,
"cost": null,
"invoiceRecurrence": {
"id": 242,
"uri": "http://api.servicetrade.com/api/invoicerecurrence/242"
},
"serviceLine": {
"id": 2,
"name": "Emergency / Exit Lights",
"trade": "Fire Protection",
"abbr": "ELIGHT",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/ELIGHT.png"
},
"libItem": {
"id": 1090,
"uri": "http://api.servicetrade.com/api/libitem/1090",
"name": "Bulbs - DC",
"type": "Part",
"code": null,
"externalIds": {
"peachtree": ""
}
},
"orderIndex": null,
"taxable": true
}
}
Return to Top
Job
The job resource is used to retrieve lists of jobs or detailed information about a single job.
- Resource URL: /job/[jobId]
- Available Verbs: GET, POST, PUT
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/job |
200 |
|
GET |
/job |
400 |
missing, incomplete or invalid parameters |
GET |
/job/123 |
200 |
|
GET |
/job/123 |
404 |
job 123 not found (or not accessible by the user) |
GET |
/job/123/attachment |
200 |
retrieve list of generic attachments |
GET |
/job/123/attachment/10 |
200 |
retrieve attachment info |
GET |
/job/123/paperwork |
200 |
retrieve list of job paperwork |
GET |
/job/123/paperwork/10 |
200 |
retrieve paperwork info |
GET |
/job/123/blankpaperwork |
200 |
retrieve list of job blank paperwork |
GET |
/job/123/blankpaperwork/10 |
200 |
retrieve a blank paperwork |
GET |
/job/123/vendorinvoice |
200 |
retrieve list of vendor invoices |
GET |
/job/123/vendorinvoice/10 |
200 |
retrieve vendor invoice info |
GET |
/job/123/picture |
200 |
retrieve list of quality control pictures |
GET |
/job/123/picture/67 |
200 |
retrieve picture info |
GET |
/job/123/comment |
200 |
retrieve list of comments |
GET |
/job/123/comment/67 |
200 |
retrieve comment info |
POST |
/job |
200 |
job created |
POST |
/job |
400 |
missing, incomplete or invalid parameters |
POST |
/job/123/attachment |
200 |
upload an audio or other attachment |
POST |
/job/123/paperwork |
200 |
upload job paperwork |
POST |
/job/123/vendorinvoice |
200 |
upload vendor invoice |
POST |
/job/123/picture |
200 |
upload quality control picture |
POST |
/job/123/comment |
200 |
create a comment - see Comment for details |
POST |
/job/123/invoice |
200 |
invoice created for job 123 using the specified contractId |
POST |
/job/123/invoice |
403 |
not allowed |
POST |
/job/123/invoice |
404 |
job or contract not found |
POST |
/job/123/invoice |
409 |
conflict, contract does not apply to job |
PUT |
/job |
405 |
not allowed |
PUT |
/job/123 |
200 |
job updated |
PUT |
/job/123 |
404 |
job 123 not found (or not accessible by the user) |
PUT |
/job/123 |
409 |
budgeted field may only be changed on an open job |
PUT |
/job/123 |
409 |
budgeted field may only be changed when there is no active budget |
DELETE |
/job |
405 |
not allowed |
Query Params
Name |
Type |
Value |
id |
integer |
id for a single job |
jobIds |
string |
comma-separated list of job ids |
lat |
double |
latitude of current location; must also supply lon |
lon |
double |
longitude of current location; must also supply lat |
radius |
double |
radius in miles to search around; must also supply lat and lon |
status |
string |
job status; one of: all (all statuses except canceled), new, scheduled, canceled, bidding, completed, pending_invoice, sending_invoice, invoiced, closed (defaults to 'scheduled' if not supplied, unless a job number is supplied); invoiced status is DEPRECATED and should not be used; use isInvoiced to find invoiced jobs. |
isInvoiced |
boolean |
filter jobs by invoiced status (if true, only jobs with a non-voided customer invoice will be returned) |
type |
string |
comma-separated list of: unknown, repair, construction, consultation, upgrade, service_call, urgent_service_call, priority_service_call, emergency_service_call, cleaning, inspection, priority_inspection, reinspection, survey, planned_maintenance, preventative_maintenance, quality_assurance, inspection_repair, delivery, pickup, exchange, sales, installation, warranty, training, testing, administrative, replacement, design, buildout, hookup, start_up, retrofit |
number |
integer |
comma-separated list of job numbers; if this parameter is supplied, all job statuses are searched unless a specific status is also supplied |
refNumber |
string |
a job number; if this parameter is supplied, returns all jobs with this reference number as an exact match. If number is supplied, this parameter is ignored. |
ivrStatus |
string |
job’s clockin status; one of: open (only one supported currently) |
locationId |
string |
comma-separated list of ids of the location of the job |
vendorId |
string |
comma-separated list of ids of the vendor which performed the job |
customerId |
string |
comma-separated list of ids of the customer for whom the job was performed |
techId |
integer |
return jobs with the tech assigned to an appointment on the job (DEPRECATED: use techIds) |
techIds |
string |
comma-separated list of integers of user ids for technicians assigned to an appointment on the job |
ownerId |
integer |
id of the user assigned as the owner of this job |
salesId |
integer |
comma-separated list of integer ids of the user assigned as the salesperson of this job |
contractId |
integer |
comma-separated list of integer ids of the contact set on the job, or to search for jobs with no contracts set set to the empty string or 'none' |
assignedOfficeIds |
string |
comma-separated list of integers of office ids, returns only jobs assigned to these offices |
officeIds |
string |
comma-separated list of integers of office ids, returns jobs served by these offices |
appointmentStatus |
string |
comma-separated list: unscheduled, scheduled, canceled_by_vendor, canceled_by_customer, completed, no_show |
regionIds |
string |
comma delimited list of integers of region ids, returns only jobs at locations within any of those regions |
termsId |
integer |
return only jobs that have these terms explicitly assigned |
sort |
string |
how to sort results; one of: distance, clockin (distance requires lat and lon to be set) |
longForm |
boolean |
returns the long form job object defaults to false |
dueByBegin |
integer |
Unix timestamp, only return jobs due on this date or later |
dueByEnd |
integer |
Unix timestamp, only return jobs due on this date or earlier |
completedOnBegin |
integer |
Unix timestamp, only return jobs completed at this time or later |
completedOnEnd |
integer |
Unix timestamp, only return jobs completed at this time or earlier |
scheduleDateFrom |
integer |
Unix timestamp, only return jobs with appointments scheduled at this time or later. If scheduleDateTo is also provided, only return jobs with appointments scheduled in this range. |
scheduleDateTo |
integer |
Unix timestamp, only return jobs with appointments scheduled at this time or earlier. If scheduleDateFrom is also provided, only return jobs with appointments scheduled in this range. |
noDueBy |
integer |
truthy value to return only jobs without a due by |
estimatedPriceFrom |
double |
Only return jobs with an estimated price greater than or equal (null price excluded) |
estimatedPriceTo |
double |
Only return jobs with an estimated price less than or equal (null price excluded) |
serviceLineIds |
string |
comma-separated list of service line ids |
tag |
string |
comma-separated list of tag strings, only jobs with all tags will be returned |
limit |
integer |
limit the jobs returned - takes radius into account if specified (default 2000, maximum 2000) |
createdBefore |
integer |
timestamp, matches records created on or before |
createdAfter |
integer |
timestamp, matches records created on or after |
updatedBefore |
integer |
timestamp, matches records updated on or before |
updatedAfter |
integer |
timestamp, matches records updated on or after |
POST/PUT Parameters
Name |
Type |
Value |
locationId |
integer |
location the job is to be performed at. Valid on post only |
vendorId |
integer |
id of vendor company assigned to this job |
customerId |
integer |
(optional) id of customer company assigned to this job (if not given, location company is used) |
brokerId |
integer |
(optional) id of broker company assigned to this job (if not given, vendor company is used) |
ownerId |
integer |
(optional) id of the user assigned as the owner of this job |
salesId |
integer |
(optional) id of the user assigned as the salesperson of this job |
termsId |
integer |
(optional) id of the Terms and Conditions to use for this job. If this is not provided, but a contract id is provided and that contract has job Terms and Conditions, then those will be used. Otherwise, the account's default job Terms and Conditions will be used. |
contractId |
integer |
(optional) id of the contract to use for this job |
primaryContactId |
integer |
(optional) id of contact that should be the primary contact. Contact must be assigned to job's location, or the location's company, or the job's customer. Null will clear current primary contact designation. |
assignedOfficeId |
integer |
(optional) id of the office assigned to this job (if not provided, will be calculated from the location's office assignments and the owner's office assignment) |
type |
string |
one of: unknown, repair, construction, consultation, upgrade, service_call, urgent_service_call, priority_service_call, emergency_service_call, cleaning, inspection, priority_inspection, reinspection, survey, planned_maintenance, preventative_maintenance, quality_assurance, inspection_repair, delivery, pickup, exchange, sales, installation, warranty, training, testing, administrative, replacement, design, buildout, hookup, start_up, retrofit |
status |
string |
(optional) one of: new, scheduled, canceled, bidding, completed, pending_invoice, sending_invoice, invoiced, closed. invoiced status is DEPRECATED and should not be used. |
visibility |
array(string) |
(optional) visibility granted to these types of viewers outside of the account; combination of: public, customer, subcontractor, description, appointments. |
serviceRequestIds |
array (integer) |
(optional) services to be fulfilled by this job (services must belong to the job's location) |
customerPo |
string(40) |
(optional) customer purchase order number for this job |
description |
string |
(optional) description of job |
autoAssignContract |
boolean |
(optional, POST only) if job default contract can be uniquely determined, set it to that value |
budgeted |
boolean |
(optional) Are budgets enabled for this job? (will not create a new budget or destroy an existing one). Can only be changed on a job that is not canceled or completed. This field can only be changed by a user with budget.manage or budget.manage.owner permissions. Otherwise the field value on the PUT/POST request will be ignored. |
Setting the number field manually is no longer supported. This will be automatically generated.
The POST/PUT parameters for creating an invoice via the job endpoint are documented in the invoice endpoint documentation.
Most of the time, the job.manage activity is required to modify fields. The exception to this is that someone with job.tech who is assigned to the job may change customerPo or description (just these two fields) on a PUT request.
Returned Elements
Name |
Type |
Value |
jobs |
array (Job) |
list of job objects |
type |
string |
one of: unknown, repair, construction, consultation, upgrade, service_call, urgent_service_call, priority_service_call, emergency_service_call, cleaning, inspection, priority_inspection, survey, planned_maintenance, preventative_maintenance, delivery, pickup, exchange, sales, installation |
jobTypeWeight |
integer |
the numeric priority weight of this job based on its type; higher numbers have higher importance |
status |
string |
job status; possible values: new, scheduled, canceled, bidding, completed, pending_invoice, sending_invoice, invoiced, closed |
number |
integer |
job reference number |
refNumber |
string |
alias for number, as a string |
customerPo |
string |
customer purchase order number for this job |
visibility |
array(string) |
visibility granted to these types of viewers outside of the account; combination of: public, customer, subcontractor, description, appointments. |
description |
string |
description of the job |
scheduledDate |
integer |
unix timestamp of the most recent open appointment for the job |
estimatedPrice |
double |
the estimated price of the job (total of all non-canceled service requests) |
latestClockIn |
integer |
unix timestamp of the most recent IVR clock-in |
ivrOpen |
boolean |
true if the last IVR event was a clock-in, otherwise false - based on the authenticated user making the call |
ivrActivity |
string |
the current open IVR activity (one of: onsite, offsite, enroute), otherwise null if no activity is open |
serviceLine |
string |
DEPRECATED, use serviceRequests array instead |
deficienciesFound |
boolean |
DEPRECATED |
otherTradeDeficienciesFound |
boolean |
DEPRECATED |
redTagsFound |
boolean |
DEPRECATED |
dueBy |
integer |
Unix timestamp of when the job is due or null for no due date |
completedOn |
integer |
Unix timestamp of when the job was completed or null if job is open or canceled |
vendor |
Company |
vendor of this job |
customer |
Company |
customer of this job |
location |
Location |
location where the job occurred |
owner |
User |
user who has been assigned as the owner of this job |
sales |
User |
user who has been assigned as the salesperson of this job |
primaryContact |
Contact |
the primary contact of this job |
location.distance |
double |
distance in miles from the current location if able to calculate, null otherwise |
location.phoneNumber |
string |
formatted as (XXX) XXX-XXXX |
location.generalManager |
string |
name of general manager at the location |
notes |
array (object) |
array of note objects related to this job |
serviceRequests |
array (Service Request) |
list of service objects |
serviceRequests.description |
string |
service description |
serviceRequests.status |
string |
servicerequest status (open, in_progress, closed, canceled, void) |
serviceRequests.serviceLine |
string |
service service line |
serviceRequests.serviceLineId |
integer |
service service line id |
serviceRequests.serviceLineIcon |
string |
url to the icon for the serivce line |
serviceRequests.windowStart |
integer |
Unix timestamp of when the service's window starts |
serviceRequests.windowEnd |
integer |
Unix timestamp of when the service's window ends |
serviceRequests.estimatedPrice |
double |
the estimated price of the service request |
serviceRequests.duration |
integer |
the estimated duration of the service request in seconds |
serviceRequests.preferredTechs |
array (User) |
tech(s) preferred for this work, if any ends |
currentAppointment |
Appointment |
earliest scheduled appointment for this job if there is one, otherwise the earliest non-canceled appointment for this job if there is one |
currentAppointment.techs |
array (User) |
users assigned to the appointment |
currentAppointment.status |
string |
status of the current active appointment |
currentAppointment.windowStart |
integer |
Unix timestamp of the appointment's window start date and time |
currentAppointment.windowEnd |
integer |
Unix timestamp of the appointment's window start date and time |
currentAppointment.released |
boolean |
has this appointment been released to its assigned techs yet? |
schedulingComments |
array (object) |
scheduling comments for this job |
schedulingComments.id |
integer |
comment id |
schedulingComments.job_id |
integer |
id of the comment's job |
schedulingComments.uri |
string |
URI for the comment |
schedulingComments.content |
string |
comment text |
assignedOffice |
Location |
office the job is assigned to |
offices |
array (Location) |
list of offices that service this job's location |
tags |
array (Tag) |
list of tags on the job |
externalIds |
object |
a key/value object of external system ids, only returned if account has external integrations defined |
terms |
Terms |
terms for this job |
contract |
Contract |
contract for this job |
budgeted |
boolean |
are budgets enabled for this job? |
created |
integer |
Unix timestamp of this record's creation time |
updated |
integer |
Unix timestamp of when this record was last updated |
Retrieve all jobs
GET /job
200
{
"data": {
"totalPages": 1,
"page": 1,
"jobs": [
{
"uri": "https://api.servicetrade.com/api/job/123",
"id": 123
"type": "repair",
"status": "scheduled",
"number": 112233,
"refNumber": "112233",
"customerPo": "FB-426BR00A",
"visibility": ["public"],
"description": "Fix the hood in the back.",
"scheduledDate": 1318874093,
"estimatedPrice": 123.45,
"latestClockIn": null,
"ivrOpen": false,
"ivrActivity": null,
"serviceLine": "FP",
"dueBy": 1348538400,
"completedOn": null,
"vendor": {
"id": 31,
"uri": "https://api.servicetrade.com/api/company/31",
"name": "Fire Shield Services",
"status": "active"
},
"customer": {
"id": 39,
"uri": "https://api.servicetrade.com/api/company/39",
"name": "Big Bang Burger Bar",
"status": "active"
},
"location": {
"id": 33,
"uri": "https://api.servicetrade.com/api/location/33",
"legacyId": 4567,
"name": "Foo's Bar",
"lat": 12.34,
"lon": -45.67,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "123 Typewriter Way",
"city": "Aiburg",
"state": "NC",
"postalCode": "23462"
},
"taxable": false,
"status": "active"
},
"owner": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"email": "joe@testcompany.com",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
}
"sales": {
"id": 16,
"uri": "https://api.servicetrade.com/api/user/16",
"name": "Sammy Sales",
"email": "sammy@testcompany.com",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"primaryContact": null,
"currentAppointment": null,
"assignedOffice": {
"id": 69,
"uri": "https://api.servicetrade.com/api/location/69",
"name": "StandAlone Satellite Office",
"legacyId": null,
"lat": 35.611172,
"lon": -78.060822,
"phoneNumber": "(919) 555-0002",
"email": "uuxiiuit+location@gmail.com",
"primaryContact": null,
"address": {
"street": "8071 Newsome Mill Rd",
"city": "Lucama",
"state": "NC",
"postalCode": "27851"
},
"taxable": false
},
"offices": [
{
"id": 23,
"uri": "https://api.servicetrade.com/api/location/23",
"name": "Central Office",
"lat": 35.291712,
"lon": -78.595006,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "742 Super Awesome Ct.",
"city": "Durham",
"state": "NC",
"postalCode": "27703"
},
"taxable": false
}
],
"tags": [],
"externalIds": {
"peachtree": "332-FOOSBAR",
"salesforce": "na1.salesforce.com/01I90000000jOLr"
},
"terms": null,
"contract": null,
"budgeted": false,
"created": 1399993795,
"updated": 1399994065
},
{
"uri": "https://api.servicetrade.com/api/job/456",
"id": 456
"type": "inspection",
"status": "scheduled",
"number": 445566,
"refNumber": "445566",
"customerPo": null,
"visibility": ["public"],
"description": "Inspect the hood in the front.",
"scheduledDate": 1318874093,
"estimatedPrice": null,
"latestClockIn": null,
"ivrOpen": false,
"ivrActivity": null,
"serviceLine": "FP",
"dueBy": null,
"completedOn": null,
"vendor": {
"id": 31,
"uri": "https://api.servicetrade.com/api/company/31",
"name": "Fire Shield Services",
"status": "active"
},
"customer": {
"id": 39,
"uri": "https://api.servicetrade.com/api/company/39",
"name": "Big Bang Burger Bar",
"status": "active"
},
"location": {
"id": 33,
"uri": "https://api.servicetrade.com/api/location/33",
"legacyId": 4567,
"name": "Salmon Ella's Seafood Shack",
"lat": 35.291712,
"lon": -78.595006,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "123 Herring Bone Way",
"city": "Wilmington",
"state": "NC",
"postalCode": "28403"
},
"taxable": false,
"status": "active"
},
"owner": null,
"sales": null,
"primaryContact": null,
"currentAppointment": {
"id": 754,
"uri": "https://api.servicetrade.com/api/appointment/754",
"name": "Appointment #754",
"status": "scheduled",
"techs": [
{
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"email": "joe@testcompany.com",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
}
],
"released": true
},
"assignedOffice": {
"id": 69,
"uri": "https://api.servicetrade.com/api/location/69",
"name": "StandAlone Satellite Office",
"legacyId": null,
"lat": 35.611172,
"lon": -78.060822,
"phoneNumber": "(919) 555-0002",
"email": "uuxiiuit+location@gmail.com",
"primaryContact": null,
"address": {
"street": "8071 Newsome Mill Rd",
"city": "Lucama",
"state": "NC",
"postalCode": "27851"
},
"taxable": false
},
"offices": [
{
"id": 23,
"uri": "https://api.servicetrade.com/api/location/23",
"name": "Central Office",
"lat": 35.291712,
"lon": -78.595006,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "742 Super Awesome Ct.",
"city": "Durham",
"state": "NC",
"postalCode": "27703"
},
"taxable": false
}
],
"tags": [],
"externalIds": {
"peachtree": "332-FOOSBAR",
"salesforce": "na1.salesforce.com/01I90000000jOLr"
},
"terms": {
"id": 42,
"uri": "https://api.servicetrade.com/api/terms/42",
"name": "Default Job Terms and Conditions"
},
"contract": {
"id": 238,
"uri": "https://api.servicetrade.com/api/contract/238",
"name": "Default Price List"
},
"budgeted": false,
"created": 1399993795,
"updated": 1399994065
}
]
}
}
Retrieve all jobs around a given location
GET /job?lat=34.11&lon=-76.73&radius=110
200
{
"data": {
"totalPages": 1,
"page": 1,
"jobs": [
{
"uri": "https://api.servicetrade.com/api/job/234",
"id" : 234
"type": "repair",
"status": "scheduled",
"number": 112233,
"refNumber": "112233",
"customerPo": null,
"visibility": ["public"],
"description": "Repair the hood in the front.",
"scheduledDate": 1318874093,
"estimatedPrice": 123.45,
"latestClockIn": null,
"ivrOpen": false,
"ivrActivity": null,
"serviceLine": "FP",
"dueBy": null,
"completedOn": null,
"vendor": {
"id": 31,
"uri": "https://api.servicetrade.com/api/company/31",
"name": "Fire Shield Services",
"status": "active"
},
"customer": {
"id": 39,
"uri": "https://api.servicetrade.com/api/company/39",
"name": "Big Bang Burger Bar",
"status": "active"
},
"location": {
"id": 33,
"uri": "https://api.servicetrade.com/api/location/33",
"legacyId": 4567,
"name": "Foo's Bar",
"lat": 35.26882,
"lon": -77.640204,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "123 Typewriter Way",
"city": "Aiburg",
"state": "NC",
"postalCode": "23462"
},
"taxable": false,
"status": "active",
"distance": 101.41
},
"owner": null,
"sales": null,
"primaryContact": null,
"currentAppointment": null,
"assignedOffice": {
"id": 69,
"uri": "https://api.servicetrade.com/api/location/69",
"name": "StandAlone Satellite Office",
"legacyId": null,
"lat": 35.611172,
"lon": -78.060822,
"phoneNumber": "(919) 555-0002",
"email": "uuxiiuit+location@gmail.com",
"primaryContact": null,
"address": {
"street": "8071 Newsome Mill Rd",
"city": "Lucama",
"state": "NC",
"postalCode": "27851"
},
"taxable": false
},
"offices": [
{
"id": 23,
"uri": "https://api.servicetrade.com/api/location/23",
"name": "Central Office",
"lat": 35.291712,
"lon": -78.595006,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "742 Super Awesome Ct.",
"city": "Durham",
"state": "NC",
"postalCode": "27703"
},
"taxable": false
}
],
"tags": [],
"externalIds": {
"peachtree": "332-FOOSBAR",
"salesforce": "na1.salesforce.com/01I90000000jOLr"
},
"terms": null,
"contract": null,
"budgeted": false,
"created": 1399993795,
"updated": 1399994065
},
{
"uri": "https://api.servicetrade.com/api/job/255",
"id" : 255
"type": "repair",
"status": "scheduled",
"number": 162789,
"refNumber": "162789",
"customerPo": null,
"visibility": ["public"],
"description": "fix suppression system over pizza oven",
"scheduledDate": 1318887498,
"estimatedPrice": null,
"latestClockIn": null,
"ivrOpen": false,
"ivrActivity": null,
"serviceLine": "FP",
"dueBy": null,
"completedOn": null,
"vendor": {
"id": 31,
"uri": "https://api.servicetrade.com/api/company/31",
"name": "Fire Shield Services",
"status": "active"
},
"customer": {
"id": 39,
"uri": "https://api.servicetrade.com/api/company/39",
"name": "Big Bang Burger Bar",
"status": "active"
},
"location": {
"id": 77,
"uri": "https://api.servicetrade.com/api/location/77",
"legacyId": 4567,
"name": "Cosimo's Pizza",
"lat": 35.37688,
"lon": -77.440204,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "9836 Pepperoni Ln.",
"city": "Durham",
"state": "NC",
"postalCode": "27703"
},
"taxable": false,
"status": "active",
"distance": 80.11
},
"owner": null,
"sales": null,
"primaryContact": null,
"currentAppointment": null,
"assignedOffice": null,
"offices": [],
"tags": [],
"externalIds": {
"peachtree": "332-FOOSBAR",
"salesforce": "na1.salesforce.com/01I90000000jOLr"
},
"terms": null,
"contract": null,
"budgeted": false,
"created": 1399993795,
"updated": 1399994065
}
]
}
}
Retrieve all jobs around a given location, sort by distance
GET /job?lat=34.11&lon=-76.73&radius=200&sort=distance
200
{
"data": {
"totalPages": 1,
"page": 1,
"jobs": [
{
"uri": "https://api.servicetrade.com/api/job/255",
"id" : 255
"type": "repair",
"status": "scheduled",
"number": 162789,
"refNumber": "162789",
"customerPo": null,
"visibility": ["public"],
"description": "fix suppression system over pizza oven",
"scheduledDate": 1318887498,
"estimatedPrice": null,
"latestClockIn": null,
"ivrOpen": false,
"ivrActivity": null,
"serviceLine": "FP",
"dueBy": null,
"completedOn": null,
"vendor": {
"id": 31,
"uri": "https://api.servicetrade.com/api/company/31",
"name": "Fire Shield Services",
"status": "active"
},
"customer": {
"id": 39,
"uri": "https://api.servicetrade.com/api/company/39",
"name": "Big Bang Burger Bar",
"status": "active"
},
"location": {
"id": 77,
"uri": "https://api.servicetrade.com/api/location/77",
"legacyId": 4567,
"name": "Cosimo's Pizza",
"lat": 35.37688,
"lon": -77.440204,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "9836 Pepperoni Ln.",
"city": "Durham",
"state": "NC",
"postalCode": "27703"
},
"taxable": false,
"status": "active",
"distance": 80.111
},
"owner": null,
"sales": null,
"primaryContact": null,
"currentAppointment": null,
"assignedOffice": null,
"offices": [],
"tags": [],
"externalIds": {
"peachtree": "332-FOOSBAR",
"salesforce": "na1.salesforce.com/01I90000000jOLr"
},
"terms": null,
"contract": null,
"budgeted": false,
"created": 1399993795,
"updated": 1399994065
},
{
"uri": "https://api.servicetrade.com/api/job/234",
"id" : 234
"type": "repair",
"status": "scheduled",
"number": 112233,
"refNumber": "112233",
"customerPo": null,
"visibility": ["public"],
"description": "Repair the hood in the front.",
"scheduledDate": 1318874093,
"estimatedPrice": null,
"latestClockIn": null,
"ivrOpen": false,
"ivrActivity": null,
"serviceLine": "FP",
"dueBy": null,
"completedOn": null,
"vendor": {
"id": 31,
"uri": "https://api.servicetrade.com/api/company/31",
"name": "Fire Shield Services",
"status": "active"
},
"customer": {
"id": 39,
"uri": "https://api.servicetrade.com/api/company/39",
"name": "Big Bang Burger Bar",
"status": "active"
},
"location": {
"id": 33,
"uri": "https://api.servicetrade.com/api/location/33",
"legacyId": 4567,
"name": "Foo's Bar",
"lat": 35.26882,
"lon": -77.640204,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "123 Typewriter Way",
"city": "Aiburg",
"state": "NC",
"postalCode": "23462"
},
"taxable": false,
"status": "active",
"distance": 101.41
},
"owner": null,
"sales": null,
"primaryContact": null,
"currentAppointment": null,
"assignedOffice": null,
"offices": [
{
"id": 23,
"uri": "https://api.servicetrade.com/api/location/23",
"name": "Central Office",
"lat": 35.291712,
"lon": -78.595006,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "742 Super Awesome Ct.",
"city": "Durham",
"state": "NC",
"postalCode": "27703"
},
"taxable": false
}
],
"tags": [],
"externalIds": {
"peachtree": "332-FOOSBAR",
"salesforce": "na1.salesforce.com/01I90000000jOLr"
},
"terms": null,
"contract": null,
"budgeted": false,
"created": 1399993795,
"updated": 1399994065
},
{
"uri": "https://api.servicetrade.com/api/job/211",
"id" : 211
"type": "inspection",
"status": "scheduled",
"number": 125687,
"refNumber": "125687",
"customerPo": null,
"visibility": ["public"],
"description": "Annual sprinkler inspection",
"scheduledDate": 1318872067,
"estimatedPrice": 123.45,
"latestClockIn": null,
"ivrOpen": false,
"ivrActivity": null,
"serviceLine": "FP",
"dueBy": null,
"completedOn": null,
"vendor": {
"id": 31,
"uri": "https://api.servicetrade.com/api/company/31",
"name": "Fire Shield Services",
"status": "active"
},
"customer": {
"id": 39,
"uri": "https://api.servicetrade.com/api/company/39",
"name": "Big Bang Burger Bar",
"status": "active"
},
"location": {
"id": 45,
"uri": "https://api.servicetrade.com/api/location/45",
"legacyId": 4567,
"name": "Seafood? Eat It",
"lat": 35.291712,
"lon": -78.595006,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "123 Herring Bone Way",
"city": "Wilmington",
"state": "NC",
"postalCode": "28403"
},
"taxable": false,
"status": "active",
"distance": 145.41
},
"owner": null,
"sales": null,
"primaryContact": null,
"currentAppointment": null,
"assignedOffice": null,
"offices": [],
"tags": [],
"externalIds": {
"peachtree": "332-FOOSBAR",
"salesforce": "na1.salesforce.com/01I90000000jOLr"
},
"terms": null,
"contract": null,
"budgeted": false,
"created": 1399993795,
"updated": 1399994065
}
]
}
}
Retrieve all jobs for a specific vendor
GET /job?vendorId=11
200
{
"data": {
"totalPages": 1,
"page": 1,
"jobs": [
{
"uri": "https://api.servicetrade.com/api/job/234",
"id" : 234
"type": "repair",
"status": "scheduled",
"number": 112233,
"refNumber": "112233",
"customerPo": null,
"visibility": ["public"],
"description": "Repair the hood in the front.",
"scheduledDate": 1318874093,
"estimatedPrice": null,
"latestClockIn": null,
"ivrOpen": false,
"ivrActivity": null,
"serviceLine": "FP",
"dueBy": null,
"completedOn": null,
"vendor": {
"id": 31,
"uri": "https://api.servicetrade.com/api/company/31",
"name": "Fire Shield Services",
"status": "active"
},
"customer": {
"id": 39,
"uri": "https://api.servicetrade.com/api/company/39",
"name": "Big Bang Burger Bar",
"status": "active"
},
"location": {
"id": 33,
"uri": "https://api.servicetrade.com/api/location/33",
"legacyId": 4567,
"name": "Foo's Bar",
"lat": 35.26882,
"lon": -77.640204,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "123 Typewriter Way",
"city": "Aiburg",
"state": "NC",
"postalCode": "23462"
},
"taxable": false,
"status": "active",
"distance": 101.41
},
"owner": null,
"sales": null,
"primaryContact": null,
"currentAppointment": null,
"assignedOffice": null,
"offices": [
{
"id": 23,
"uri": "https://api.servicetrade.com/api/location/23",
"name": "Central Office",
"lat": 35.291712,
"lon": -78.595006,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "742 Super Awesome Ct.",
"city": "Durham",
"state": "NC",
"postalCode": "27703"
},
"taxable": false
}
],
"tags": [],
"externalIds": {
"peachtree": "332-FOOSBAR",
"salesforce": "na1.salesforce.com/01I90000000jOLr"
},
"terms": null,
"contract": null,
"budgeted": false,
"created": 1399993795,
"updated": 1399994065
}
]
}
}
Missing parameter
GET /job?lat=12.15&radius=2000
400
Missing parameter (sort by distance requires lat and lon)
GET /job?sort=distance
400
Retrieve detail information for a single job
GET /job/13
200
{
"data": {
"uri": "https://api.servicetrade.com/api/job/13",
"id": 13,
"type": "repair",
"status": "scheduled",
"number": 112233,
"refNumber": "112233",
"customerPo": null,
"visibility": ["public"],
"description": "Repair the hood in the front.",
"scheduledDate": 1318874093,
"estimatedPrice": null,
"latestClockIn": null,
"ivrOpen": false,
"ivrActivity": null,
"serviceLine": "FP",
"currentAppointment": null,
"deficienciesFound": true,
"otherTradeDeficienciesFound": false,
"redTagsFound": false,
"vendor": {
"id": 31,
"uri": "https://api.servicetrade.com/api/company/31",
"name": "Fire Shield Services",
"status": "active"
},
"customer": {
"id": 39,
"uri": "https://api.servicetrade.com/api/company/39",
"name": "Big Bang Burger Bar",
"status": "active"
},
"location": {
"id": 33,
"uri": "https://api.servicetrade.com/api/location/33",
"legacyId": 4567,
"name": "Foo's Bar",
"lat": 35.26882,
"lon": -77.640204,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "123 Typewriter Way",
"city": "Aiburg",
"state": "NC",
"postalCode": "23462"
},
"taxable": false,
"status": "active",
"distance": null,
"generalManager": "Alan Turing"
},
"owner": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"email": "joe@testcompany.com",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"sales": null,
"primaryContact": null,
"notes": [
{
"type": "jobComments",
"text": "please use the side entrance if after hours"
},
{
"type": "locTechComments",
"text": "call MGR if you find problems that will run over the NTE"
}
],
"serviceRequests": [
{
"uri": "https://api.servicetrade.com/api/servicerequest/41",
"id": 41,
"description": "Portable Extinguisher Inspection",
"status": "open",
"serviceLine": "Portable Extinguishers",
"serviceLineId": 123,
"serviceLineIcon": "https://app.servicetrade.com/image/icons/service_lines/32/EXT.png",
"windowStart": 1322680442,
"windowEnd": 1322690442,
"estimatedPrice": null,
"duration": null,
"preferredTechs": []
},
{
"uri": "https://api.servicetrade.com/api/servicerequest/42",
"id": 42,
"description": "Emergency/Exit Lights Inspection",
"status": "open",
"serviceLine": "Emergency / Exit Lights",
"serviceLineId": 111,
"serviceLineIcon": "https://app.servicetrade.com/image/icons/service_lines/32/LIGHT.png",
"windowStart": 1322680442,
"windowEnd": 1322690442,
"estimatedPrice": null,
"duration": null,
"preferredTechs": []
},
{
"uri": "https://api.servicetrade.com/api/servicerequest/43",
"id": 43,
"description": "3 Tank Suppression System Inspection",
"status": "open",
"serviceLine": "Fire Suppression",
"serviceLineId": 113,
"serviceLineIcon": "https://app.servicetrade.com/image/icons/service_lines/32/FP.png",
"windowStart": 1322680442,
"windowEnd": 1322690442,
"estimatedPrice": null,
"duration": null,
"preferredTechs": []
}
],
"schedulingComments": [
{
"uri": "https://api.servicetrade.com/api/comment/43",
"id": 1,
"job_id": 13,
"content": "They close early on Tuesdays (3pm)"
}
],
"assignedOffice": null,
"offices": [
{
"id": 23,
"uri": "https://api.servicetrade.com/api/location/23",
"name": "Central Office",
"lat": 35.291712,
"lon": -78.595006,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "742 Super Awesome Ct.",
"city": "Durham",
"state": "NC",
"postalCode": "27703"
},
"taxable": false
}
],
"tags": [],
"externalIds": {
"peachtree": "332-FOOSBAR",
"salesforce": "na1.salesforce.com/01I90000000jOLr"
},
"terms": null,
"contract": null,
"budgeted": false,
"created": 1399993795,
"updated": 1399994065
}
}
Retrieve detail information for a job which does not exist or the user cannot access
GET /job/987
404
Get a list of jobs that are open
GET /job?ivrStatus=open
200
{
"data": {
"totalPages": 1,
"page": 1,
"jobs": [
{
"uri": "https://api.servicetrade.com/api/job/4",
"id": 4,
"type": "inspection",
"status": "scheduled",
"number": 116701,
"refNumber": "116701",
"customerPo": null,
"visibility": ["public"],
"description": null,
"scheduledDate": null,
"estimatedPrice": null,
"latestClockIn": 1322680442,
"ivrOpen": true,
"ivrActivity": "onsite",
"serviceLine": "FP",
"currentAppointment": null,
"vendor": {
"id": 31,
"uri": "https://api.servicetrade.com/api/company/31",
"name": "Fire Shield Services",
"status": "active"
},
"customer": {
"id": 39,
"uri": "https://api.servicetrade.com/api/company/39",
"name": "Big Bang Burger Bar",
"status": "active"
},
"location": {
"id": 11,
"uri": "https://api.servicetrade.com/api/location/11",
"legacyId": 4567,
"name": "Belk #347 - Spotsylvania Mall",
"lat": 38.292186,
"lon": -77.575163,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "Route 3 500 Spotsylvania Mall",
"city": "Fredericksburg",
"state": "VA",
"postalCode": "22407"
},
"taxable": false,
"status": "active",
"distance": null
},
"owner": null,
"sales": null,
"primaryContact": null,
"assignedOffice": null,
"offices": [],
"tags": [],
"externalIds": {
"peachtree": "332-FOOSBAR",
"salesforce": "na1.salesforce.com/01I90000000jOLr"
},
"terms": null,
"contract": null,
"budgeted": false,
"created": 1399993795,
"updated": 1399994065
},
{
"uri": "https://api.servicetrade.com/api/job/2",
"id": 2,
"type": "inspection",
"status": "scheduled",
"number": 116699,
"refNumber": "116699",
"customerPo": null,
"visibility": ["public"],
"description": null,
"scheduledDate": null,
"estimatedPrice": 123.45,
"latestClockIn": 1322679823,
"ivrOpen": true,
"ivrActivity": "onsite",
"serviceLine": "FP",
"currentAppointment": null,
"vendor": {
"id": 31,
"uri": "https://api.servicetrade.com/api/company/31",
"name": "Fire Shield Services",
"status": "active"
},
"customer": {
"id": 39,
"uri": "https://api.servicetrade.com/api/company/39",
"name": "Big Bang Burger Bar",
"status": "active"
},
"location": {
"id": 9,
"uri": "https://api.servicetrade.com/api/location/9",
"legacyId": 4567,
"name": "Belk #538 - Applewood",
"legacyId": null,
"lat": 34.698602,
"lon": -82.886865,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "1581 Highway 123 West",
"city": "Seneca",
"state": "SC",
"postalCode": "29678"
},
"taxable": false,
"status": "active",
"distance": null
},
"owner": null,
"sales": null,
"primaryContact": null,
"assignedOffice": null,
"offices": [],
"tags": [],
"externalIds": {
"peachtree": "332-FOOSBAR",
"salesforce": "na1.salesforce.com/01I90000000jOLr"
},
"terms": null,
"contract": null,
"budgeted": false,
"created": 1399993795,
"updated": 1399994065
}
]
}
}
Search for jobs due in a time range
GET /job?status=new&locationId=255&dueByBegin=1334548800&dueByEnd=1335240000
200
{
"data": {
"totalPages": 1,
"page": 1,
"jobs": [
{
"uri": "https://api.servicetrade.com/api/job/339",
"id": 339,
"type": "upgrade",
"status": "new",
"number": 10000269,
"refNumber": "10000269",
"customerPo": null,
"visibility": ["public"],
"description": null,
"scheduledDate": null,
"estimatedPrice": 123.45,
"latestClockIn": null,
"ivrOpen": false,
"ivrActivity": null,
"serviceLine": "FP",
"dueBy": 1334894400,
"completedOn": null,
"vendor": {
"id": 31,
"uri": "https://api.servicetrade.com/api/company/31",
"name": "Fire Shield Services",
"status": "active"
},
"customer": {
"id": 39,
"uri": "https://api.servicetrade.com/api/company/39",
"name": "Big Bang Burger Bar",
"status": "active"
},
"location": {
"id": 255,
"uri": "https://api.servicetrade.com/api/location/255",
"name": "Big Bob's Burger Barn",
"legacyId": 1838701237,
"lat": 35.291813,
"lon": -78.594853,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "678 Feedtrough Ave.",
"city": "Garner",
"state": "NC",
"postalCode": "27529"
},
"taxable": false,
"status": "active",
"distance": null
},
"owner": null,
"sales": null,
"primaryContact": null,
"currentAppointment": null,
"assignedOffice": null,
"offices": [
{
"id": 23,
"uri": "https://api.servicetrade.com/api/location/23",
"name": "Central Office",
"lat": 35.291712,
"lon": -78.595006,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "742 Super Awesome Ct.",
"city": "Durham",
"state": "NC",
"postalCode": "27703"
},
"taxable": false
}
],
"tags": [],
"externalIds": {
"peachtree": "332-FOOSBAR",
"salesforce": "na1.salesforce.com/01I90000000jOLr"
},
"terms": null,
"contract": null,
"budgeted": false,
"created": 1399993795,
"updated": 1399994065
}
]
}
}
Upload an attachment
POST /job/123/attachment
Content-Type:multipart/form-data; boundary=----boundaryGywPoFXO23hZFxNn
------boundaryGywPoFXO23hZFxNn
Content-Disposition: form-data; name="uploadedFile"; filename="voicemail.wav"
Content-Type: audio/wav
...binary audio data goes here...
------boundaryGywPoFXO23hZFxNn--
200
{
"data": {
"uri": "https://api.servicetrade.com/api/attachment/10",
"id": 10,
"contentUrl": "http://s3.amazonaws.com/snaap-attachments/10_b4b9d661d5235753b4827c61b9b3dd96.wav",
"checksum": "b4b9d661d5235753b4827c61b9b3dd96",
"meta": [],
"fileName": "voicemail.wav",
"fileType": "audio/wav",
"description": "",
"purposeId": 7,
"purpose": "Job Attachment",
"created": 1327082916,
"updated": 1327082916,
"entity": {
"uri": "https://api.servicetrade.com/api/job/123",
"id": 123,
"type": 3
}
}
}
List attachments
GET /job/123/attachment
200
{
"data": {
"totalPages": 1,
"page": 1,
"attachments": [
{
"data": {
"uri": "https://api.servicetrade.com/api/attachment/10",
"id": 10,
"contentUrl": "http://s3.amazonaws.com/snaap-attachments/10_b4b9d661d5235753b4827c61b9b3dd96.wav",
"checksum": "b4b9d661d5235753b4827c61b9b3dd96",
"meta": [],
"fileName": "voicemail.wav",
"fileType": "audio/wav",
"description": "",
"purposeId": 7,
"purpose": "Job Attachment",
"created": 1327082916,
"updated": 1327082916,
"entity": {
"uri": "https://api.servicetrade.com/api/job/123",
"id": 123,
"type": 3
}
}
}
]
}
}
Upload photo of job paperwork
To signify that an attachment should be processed as a photograph of a document, set the meta value "camdoc" to 1.
When the attachment object is returned its meta.camdoc property will be set to 2 to indicate sucessful document recognition,
or 3 to indicate failure.
POST /job/123/paperwork
Content-Type:multipart/form-data; boundary=----boundaryGywPoFXO23hZFxNn
------boundaryGywPoFXO23hZFxNn
Content-Disposition: form-data; name="meta[camdoc]"
1
------boundaryGywPoFXO23hZFxNn
Content-Disposition: form-data; name="uploadedFile"; filename="paper_photo.jpg"
Content-Type: image/jpeg
...binary image data goes here...
------boundaryGywPoFXO23hZFxNn--
200
{
"data": {
"uri": "https://api.servicetrade.com/api/attachment/10",
"id": 10,
"contentUrl": "http://s3.amazonaws.com/snaap-attachments/10_b4b9d661d5235753b4827c61b9b3dd96.jpg",
"checksum": "b4b9d661d5235753b4827c61b9b3dd96",
"meta": {
"originalImage": "http://s3.amazonaws.com/snaap-attachments/10_236bd2211eef9b81375536ae68eefc8f.jpg",
"camdoc": 2
},
"fileName": "paper_photo.jpg",
"fileType": "image/jpeg",
"description": "",
"purposeId": 7,
"purpose": "Job Paperwork",
"created": 1327082916,
"updated": 1327082916,
"entity": {
"uri": "https://api.servicetrade.com/api/job/123",
"id": 123,
"type": 3
}
}
}
Return to Top
Job Context
The job context resource is used to retrieve lists of job contexts or detailed information about a single job context.
- Resource URL: /jobcontext/[jobContextId]
- Available Verbs: GET, POST, PUT, DELETE
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/jobContext |
200 |
|
GET |
/jobContext/123 |
200 |
|
GET |
/jobContext/123 |
404 |
jobContext 123 not found |
POST |
/jobContext |
200 |
|
POST |
/jobContext |
404 |
tried to create a context for an object that wasn't found |
POST |
/jobContext |
405 |
not allowed |
PUT |
/jobContext/123 |
200 |
|
PUT |
/jobContext/123 |
405 |
not allowed |
DELETE |
/jobContext |
405 |
not allowed |
DELETE |
/jobContext/123 |
200 |
|
DELETE |
/jobContext/123 |
404 |
context not found |
Query Params
POST Parameters
Name |
Type |
Value |
customerId |
integer |
company id of customer for which this context applies |
locationId |
integer |
location id of job location for which this context applies |
officeId |
integer |
office id of the office for the job location for which this context applies |
regionId |
integer |
region id of the region for the job location for which this context applies |
serviceLineId |
integer |
what line of service this context applies to |
jobType |
string |
what job type this context applies to, one of: unknown, repair, construction, consultation, upgrade, service_call, urgent_service_call, priority_service_call, emergency_service_call, cleaning, inspection, priority_inspection, reinspection, survey, planned_maintenance, preventative_maintenance, quality_assurance, inspection_repair, delivery, pickup, exchange, sales, installation, warranty, training, testing, administrative, replacement, design, buildout, hookup, start_up, retrofit |
Returned Elements
Name |
Type |
Value |
jobContexts |
array (object) |
list of job context objects |
id |
integer |
job context id |
uri |
string |
resource identifier for the given job context |
customer |
Company |
customer company or null |
location |
Location |
job location or null |
office |
Location |
job location office or null |
region |
Region |
job location region or null |
serviceLine |
Service Line |
job service line or null |
jobType |
string |
job type or null |
attachments |
array (object) |
attachments on the job context |
attachment.id |
integer |
job context id |
attachment.uri |
string |
resource identifier for the given job context |
Get all the job contexts on the current account
GET /jobcontext
200
{
"data": {
"totalPages": 1,
"page": 1,
"jobContexts": [
{
"uri": "https://api.servicetrade.com/api/jobcontext/78",
"id": 78,
"customer": null,
"serviceLine": null,
"jobType": null,
"attachments": []
},
{
"uri": "https://api.servicetrade.com/api/jobcontext/79",
"id": 79,
"customer": {
"id": 5,
"uri": "https://api.servicetrade.com/api/company/5",
"name": "Cook Out"
},
"location": {
"id": 15,
"uri": "https://api.servicetrade.com/api/location/15",
"name": "Cook Out - North Main",
"legacyId": 4567,
"lat": 35.26882,
"lon": -77.640204,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "55 North Main",
"city": "Fooburg",
"state": "NC",
"postalCode": "27272"
},
"taxable": false,
"status": "active"
},
"office": null,
"region": null,
"serviceLine": null,
"jobType": "emergency_service_call",
"attachments": [
{
"id": 445,
"uri": "https://api.servicetrade.com/api/attachment/455"
}
]
}
]
}
}
Request a job context (and create if it doesn't yet exist)
POST /jobcontext?customerId=5
200
{
"data": {
"uri": "https://api.servicetrade.com/api/jobcontext/79",
"id": 79,
"customer": {
"id": 5,
"uri": "https://api.servicetrade.com/api/company/5",
"name": "Cook Out"
},
"location": null,
"office": null,
"region": null,
"serviceLine": null,
"jobType": null,
"attachments": [
{
"id": 445,
"uri": "https://api.servicetrade.com/api/attachment/455"
}
]
}
}
Get a job context by id
GET /jobcontext/79
200
{
"data": {
"uri": "https://api.servicetrade.com/api/jobcontext/79",
"id": 79,
"customer": {
"id": 5,
"uri": "https://api.servicetrade.com/api/company/5",
"name": "Cook Out"
},
"location": null,
"office": null,
"region": null,
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "https://api.servicetrade.com/image/icons/service_lines/32/SUPP.png"
},
"jobType": null,
"attachments": []
}
}
Delete a job context
DELETE /jobcontext/79
200
Return to Top
JobItem
The job item resource is used to retrieve a list of a job's job items or information about a single job item. It can also be used to modify a job's list of job items.
- Resource URL: /jobItem/[jobItemId]
- Available Verbs: GET, POST, PUT, DELETE
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/jobitem |
200 |
|
GET |
/jobitem/123 |
200 |
|
GET |
/jobitem/123 |
404 |
job item 123 not found |
POST |
/jobitem |
200 |
|
POST |
/jobitem |
400 |
malformed request |
POST |
/jobitem |
403 |
no permission |
PUT |
/jobitem/123 |
200 |
|
PUT |
/jobitem/123 |
400 |
malformed request |
PUT |
/jobitem/123 |
403 |
no permission |
DELETE |
/jobitem |
204 |
|
DELETE |
/jobitem |
403 |
no permission |
Query Params
Name |
Type |
Required |
Value |
jobId |
integer |
Yes (if no job item id or jobOfficeId provided) |
return job items on this job |
jobOfficeId |
integer |
Yes (if no job item id or jobOfficeId provided) |
return job items for jobs at this office |
createdBefore |
integer |
Yes (if no job item id or jobOfficeId or jobId provided) |
timestamp, matches records created on or before |
createdAfter |
integer |
Yes (if no job item id or jobOfficeId or jobId provided) |
timestamp, matches records created on or after |
updatedBefore |
integer |
Yes (if no job item id or jobOfficeId or jobId provided) |
timestamp, matches records updated on or before |
updatedAfter |
integer |
Yes (if no job item id or jobOfficeId or jobId provided) |
timestamp, matches records updated on or after |
usedOnBefore |
integer |
Yes (if no job item id or jobOfficeId or jobId provided) |
timestamp, matches records used on or before |
usedOnAfter |
integer |
Yes (if no job item id or jobOfficeId or jobId provided) |
timestamp, matches records used on or after |
libItemType |
string |
No |
single or comma separated values of lib item types (lowercase names) |
POST Parameters
Name |
Type |
Required |
Value |
jobId |
integer |
Yes |
id of job to attach item to |
name |
string |
Yes |
display name of the job item |
libItemId |
integer |
No |
id of the libItem for the job item, absense of this means you are creating an "other" item of the service line indicated by serviceLineId |
serviceLineId |
integer |
Only if libItemId is absent or points to a lib item with no service line |
id of the serviceLine |
quantity |
float |
Yes |
quantity of the job item |
cost |
float |
no |
cost of this item; can be null. |
serviceRequestId |
integer |
no |
id of serviceRequest that this item is to address, which must be associated with this items's job |
visibility |
array(string) |
No |
(optional) visibility granted to these types of viewers outside of the account; combination of: public, customer, subcontractor. "public" indicates global visibility and overrides the other values. Will default to account default if no value is provided on POST. |
orderIndex |
integer |
no |
items are listed from low to high value, null is the default value |
usedOn |
integer (timestamp) |
no |
Unix timestamp for when the item was used |
source |
object |
no |
used to indicate where this job item came from |
source.type |
string |
no |
item source type, one of: refnumber, tech, warehouse, partsvendor |
source.value |
string |
no |
if source type is refnumber, the reference number for that source. if source type is partsvendor, the PO number for that order |
source.userId |
integer |
If source.type is tech |
only present if source type is tech, the tech's userId |
source.warehouseId |
integer |
If source.type is warehouse |
only present if source type is warehouse, the warehouse's id |
source.companyId |
integer |
no |
only present if source type is partsvendor, the vendor company's id |
source.status |
string |
If source.type is partsvendor |
parts order status, one of: unordered, ordered, received |
source.deliveryDate |
integer (timestamp) |
no |
only preset when source type is partsvendor, Unix timestamp for when the item is to be delivered |
PUT Parameters
Name |
Type |
Required |
Value |
name |
string |
No |
display name of the job item |
libItemId |
integer |
No |
id of the libItem for the job item |
serviceLineId |
integer |
Only if libItemId points to a lib item with no service line |
id of the serviceLIne |
quantity |
float |
No |
quantity of the job item |
cost |
float |
no |
cost of this item; can be null. |
serviceRequestId |
integer |
no |
id of serviceRequest that this item is to address, which must be associated with this items's job |
visibility |
array(string) |
No |
(optional) visibility granted to these types of viewers outside of the account; combination of: public, customer, subcontractor. "public" indicates global visibility and overrides the other values. Will default to account default if no value is provided on POST. |
orderIndex |
integer |
no |
items are listed from low to high value, null is the default value |
usedOn |
integer (timestamp) |
no |
Unix timestamp for when the item was used |
source |
object |
no |
used to indicate where this job item came from |
source.type |
string |
no |
item source type, one of: refnumber, tech, warehouse, partsvendor |
source.value |
string |
no |
only present if source type is refnumber, the reference number for that source |
source.userId |
integer |
If source.type is tech |
only present if source type is tech, the tech's userId |
source.warehouseId |
integer |
If source.type is warehouse |
only present if source type is warehouse, the warehouse's id |
source.companyId |
integer |
no |
only present if source type is partsvendor, the vendor company's id |
source.status |
string |
If source.type is partsvendor |
parts order status, one of: unordered, ordered, received |
source.deliveryDate |
integer (timestamp) |
no |
only preset when source type is partsvendor, Unix timestamp for when the item is to be delivered |
Returned Elements
Name |
Type |
Value |
totalPages |
integer |
total number of results pages |
page |
integer |
current result page |
id |
integer |
job item id |
uri |
string |
resource identifier for the given job item |
name |
string |
display name of the job item |
libItem |
Libitem |
libItem of the job item |
serviceLine |
Service Line |
serviceLine of the job item |
quantity |
float |
quantity of the job item |
cost |
float |
cost of this item, else null |
job |
Job |
the job the item belongs to |
quoteItem |
Quoteitem |
quoteItem that resulted in this job item |
serviceRequest |
:service Request |
serviceRequest that this item is to address |
visibility |
array(string) |
visibility granted to these types of viewers outside of the account; combination of: public, customer, subcontractor. "public" indicates global visibility and overrides the other values. |
usedOn |
integer |
Unix timestamp for when the item was used |
created |
integer |
Unix timestamp of this record's creation time |
updated |
integer |
Unix timestamp of when this record was last updated |
source |
object |
used to indicate where this job item came from |
source.type |
string |
item source type, one of: refnumber, tech, warehouse, partsvendor |
source.value |
string |
only present if item type is refnumber, the reference number for that source |
source.userId |
integer |
only present if item type is tech, the tech's userId |
source.warehouseId |
integer |
only present if source type is warehouse, the warehouse's id |
source.companyId |
integer |
only present if source type is partsvendor, the vendor company's id |
source.status |
string |
only present if source type is partsvendor, parts order status, one of: unordered, ordered, received |
source.deliveryDate |
integer |
only preset when source type is partsvendor, Unix timestamp for when the item is to be delivered |
orderIndex |
integer |
The position the item is displayed in on the job page, with 0 being closest to the top |
externalIds |
object |
a key/value object of external system ids, only returned if account has external integrations defined |
Retrieve all job items for a particular job
GET /jobitem?jobId=123
200
{
"data": {
"totalPages": 1,
"page": 1,
"jobItems": [
{
"uri": "https://api.servicetrade.com/api/jobitem/10",
"id": 10,
"name": "3 Tank Suppression System Inspection",
"libItem": {
"id": 477,
"uri": "https://api.servicetrade.com/api/libitem/477",
"name": "3 Tank Suppression System Inspection",
"type": "Inspection",
"code": null
},
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/SUPP.png"
},
"quantity": 1,
"cost": null,
"job": {
"id": 123,
"uri": "https://api.servicetrade.com/api/job/123",
"number": 10300676,
"name": "Inspection Job #10300676",
"type": "inspection"
},
"quoteItem": {
"id": 877,
"uri": "https://api.servicetrade.com/api/quoteitem/877",
"name": "3 Tank Suppression System Inspection"
},
"serviceRequest": {
"id": 1742,
"uri": "https://api.servicetrade.com/api/servicerequest/1742",
"description": "Semi-Annual Preventative Maintenance"
},
"source": null,
"visibility": ["public"],
"usedOn": 1399994065,
"created": 1399993795,
"updated": 1399994065
},
{
"uri": "https://api.servicetrade.com/api/jobitem/11",
"id": 11,
"name": "1 Tank Suppression System Inspection",
"libItem": {
"id": 474,
"uri": "https://api.servicetrade.com/api/libitem/474",
"name": "1 Tank Suppression System Inspection",
"type": "Inspection",
"code": null
},
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/SUPP.png"
},
"quantity": 2,
"cost": null,
"job": {
"id": 123,
"uri": "https://api.servicetrade.com/api/job/123",
"number": 10300676,
"name": "Inspection Job #10300676",
"type": "inspection"
},
"quoteItem": null,
"serviceRequest": null,
"source": null,
"visibility": ["public"],
"usedOn": 1399994065,
"created": 1399993795,
"updated": 1399994065
}
]
}
}
Retrieve a job item by id
GET /jobitem/434
200
{
"data": {
"uri": "https://api.servicetrade.com/api/jobitem/434",
"id": 434,
"name": "Flux Capacitor",
"libItem": {
"id": 670,
"uri": "https://api.servicetrade.com/api/libitem/670",
"name": "Other",
"type": "Other",
"code": null
},
"serviceLine": {
"id": 2,
"name": "Emergency / Exit Lights",
"trade": "Fire Protection",
"abbr": "ELIGHT",
"icon": "https://app.servicetrade.com/image/icons/service_lines/32/ELIGHT.png"
},
"quantity": 1,
"cost": 19.85,
"job": {
"id": 50,
"uri": "https://api.servicetrade.com/api/job/50",
"number": 10300006,
"name": "Inspection Job #10300006",
"type": "inspection"
},
"quoteItem": null,
"serviceRequest": {
"id": 1742,
"uri": "https://api.servicetrade.com/api/servicerequest/1742",
"description": "Semi-Annual Preventative Maintenance"
},
"source": {
"type": "refnumber",
"value": "E-BRN-1985"
},
"visibility": ["public"],
"usedOn": 1399994065,
"created": 1399993795,
"updated": 1399994065,
"externalIds": {
"ABC-1234": "this is external ID"
}
}
}
Modify an existing job item
PUT /jobitem/434
{"name": "Vanilla Fudge Capacitor", "libItemId": 551, "quantity": 3, "source": {"type": "tech", "userId": 315}}
200
{
"data": {
"uri": "https://api.servicetrade.com/api/jobitem/434",
"id": 434,
"name": "Vanilla Fudge Capacitor",
"libItem": {
"id": 551,
"uri": "https://api.servicetrade.com/api/libitem/551",
"name": "G2 Grease Guard-Rooftop Solutions Service",
"type": "Service",
"code": null
},
"serviceLine": {
"id": 8,
"name": "Grease Containment",
"trade": "Kitchen Exhaust Cleaning",
"abbr": "GC",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/GC.png"
},
"quantity": 3,
"cost": null,
"job": {
"id": 50,
"uri": "https://api.servicetrade.com/api/job/50",
"number": 10300006,
"name": "Inspection Job #10300006",
"type": "inspection"
},
"quoteItem": null,
"serviceRequest": {
"id": 1742,
"uri": "https://api.servicetrade.com/api/servicerequest/1742",
"description": "Semi-Annual Preventative Maintenance"
},
"source": {
"type": "tech",
"userId": "315"
},
"visibility": ["public"],
"usedOn": 1399994065,
"created": 1399993795,
"updated": 1399994065,
"externalIds": {
"ABC-1234": "this is external ID"
}
}
}
Create a new job item on an existing job of a known lib item type
POST /jobitem
{"name": "G2 Grease Guard-Rooftop Solutions Service", "libItemId": 551, "quantity": 3, "jobId": 318}
200
{
"data": {
"uri": "https://api.servicetrade.com/api/jobitem/543",
"id": 543,
"name": "G2 Grease Guard-Rooftop Solutions Service",
"libItem": {
"id": 551,
"uri": "https://api.servicetrade.com/api/libitem/551",
"name": "G2 Grease Guard-Rooftop Solutions Service",
"type": "Service",
"code": null
},
"serviceLine": {
"id": 8,
"name": "Grease Containment",
"trade": "Kitchen Exhaust Cleaning",
"abbr": "GC",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/GC.png"
},
"quantity": 3,
"cost": null,
"job": {
"id": 318,
"uri": "https://api.servicetrade.com/api/job/318",
"number": 10303673,
"name": "Inspection Job #10303673",
"type": "inspection"
},
"quoteItem": null,
"serviceRequest": null,
"source": null,
"visibility": ["public"],
"usedOn": 1399994065,
"created": 1399993795,
"updated": 1399994065,
"externalIds": {
"ABC-1234": "this is external ID"
}
}
}
Create a new job item on an existing job of an unknown lib item type
POST /jobitem
{"name": "New Fangled Device", "serviceLineId": 4, "quantity": 1, "jobId": 318}
200
{
"data": {
"uri": "https://api.servicetrade.com/api/jobitem/543",
"id": 405,
"name": "New Fangled Device",
"libItem": {
"id": 1057,
"uri": "https://api.servicetrade.com/api/libitem/1057",
"name": "Other",
"type": "Other",
"code": null
},
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/SUPP.png"
},
"quantity": 1,
"cost": null,
"job": {
"id": 318,
"uri": "https://api.servicetrade.com/api/job/318",
"number": 10303673,
"name": "Inspection Job #10303673",
"type": "inspection"
},
"quoteItem": null,
"serviceRequest": null,
"source": null,
"visibility": ["public"],
"usedOn": 1399994065,
"created": 1399993795,
"updated": 1399994065,
"externalIds": {
"ABC-1234": "this is external ID"
}
}
}
Delete a job item
DELETE /jobitem/434
200
Return to Top
LegacyLookup
The LegacyLookup resource is used to get a snaap id that corresponds to a known legacy id for a specific entity. Supported entity types: company, location.
- Resource URL: /legacylookup/[entityType]/[legacyId]
- Available Verbs: GET
- Authentication Required: yes
Query Params
Name |
Type |
Value |
reverse |
integer |
1 to flag a reverse lookup; currently only supported for company |
type |
string |
"customer" or "vendor" (default); currently only supported for company |
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/legacylookup |
405 |
not allowed |
GET |
/legacylookup/company |
405 |
not allowed |
GET |
/legacylookup/job |
405 |
not allowed |
GET |
/legacylookup/location |
405 |
not allowed |
GET |
/legacylookup/foo |
404 |
invalid entity type |
GET |
/legacylookup/company/123 |
200 |
|
GET |
/legacylookup/company/123?type=customer |
200 |
lookup a customer company |
GET |
/legacylookup/company/123 |
404 |
entity of that type with that legacy id does not exist |
GET |
/legacylookup/job/123 |
200 |
|
GET |
/legacylookup/job/123 |
404 |
entity of that type with that legacy id does not exist |
GET |
/legacylookup/location/123 |
200 |
|
GET |
/legacylookup/location/123 |
404 |
entity of that type with that legacy id does not exist |
GET |
/legacylookup/serviceline/123 |
200 |
|
GET |
/legacylookup/serviceline/123 |
404 |
entity of that type with that legacy id does not exist |
GET |
/legacylookup/user/123 |
200 |
|
GET |
/legacylookup/user/123 |
404 |
entity of that type with that legacy id does not exist |
POST |
/legacylookup |
405 |
not allowed |
PUT |
/legacylookup |
405 |
not allowed |
DELETE |
/legacylookup |
405 |
not allowed |
Returned Elements
Name |
Type |
Value |
id |
integer |
snaap id for the entity |
companyId |
integer |
snaap id for the entity's company (user entityType only) |
Sample request and response
GET /legacylookup/company/123
200
{
"data": {
"id": 456,
}
}
GET /legacylookup/company/987?type=customer
200
{
"data": {
"id": 321,
}
}
GET /legacylookup/company/456?reverse=1
200
{
"data": {
"legacyId": 123,
}
}
GET /legacylookup/job/123
200
{
"data": {
"id": 456,
}
}
GET /legacylookup/location/123
200
{
"data": {
"id": 456,
}
}
GET /legacylookup/user/123
200
{
"data": {
"id": 456,
"companyId": 78,
}
}
Return to Top
LibItem
The libitem resource is used to retrieve lists of lib items or information about a single lib item.
Lib Items are parts, services, fees or other entities that are used as a basis for invoice and job line-items. Lib Items are used in pricing contracts, and the price of a single lib item can vary depending on the contract's rules.
To see an item's pricing according to a given contract, a contract ID or contract context must be provided. A contract context consists of a contractor id (entity performing the work), a contractee id (entity requesting the work), and a location id (where the work will be performed.) A context can be provided when retrieving an item list or a single item, and will be applied to every item returned. Note that some items may not be specified in the given context, and will have an unknown price. A logged in user can only see contexts in which their company is the contractor or contractee entity.
- Resource URL: /libitem/[libItemId]
- Available Verbs: GET, POST, PUT
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/libitem |
200 |
|
GET |
/libitem/123 |
200 |
|
GET |
/libitem/123 |
404 |
lib item 123 not found |
POST |
/libitem |
200 |
|
POST |
/libitem |
400 |
invalid parameters |
PUT |
/libitem |
405 |
not allowed |
PUT |
/libitem/123 |
200 |
|
PUT |
/libitem/123 |
400 |
invalid parameters |
PUT |
/libitem/123 |
404 |
lib item 123 not found |
DELETE |
/libitem |
405 |
not allowed |
Query Params
Name |
Type |
Value |
search |
string |
string to match against either the item code or lib item name |
code |
string |
string to match against the item code |
name |
string |
string to find in the lib item name |
type |
string |
lib item type, one of: "inspection", "service", "part", "labor", "fee", "material", "general_conditions", "equipment", "subcontractor", "other" |
companyIds |
string |
comma delimited list of company ids - will include company specific lib items for these companies in addition to global items. if not specified, this will default to the current user's company |
contractId |
integer |
contract to use to determine specific pricing; overrides contractorId, contracteeId and locationId |
contractorId |
integer |
contractor to use to determine specific pricing; must also supply contracteeId and locationId |
contracteeId |
integer |
contractee to use to determine specific pricing; must also supply contractorId and locationId |
locationId |
integer |
location of service to use to determine specific pricing; must also supply contractorId and contracteeId |
serviceLineIds |
string |
comma delimitted list of integers, list of service line ids to limit the results to |
basePrice |
double |
base price to apply margin to, if no contract price is found |
baseCost |
double |
base cost to apply markup to, if no standard cost is found |
active |
boolean |
if true, only return active lib items; if false, only return inactive lib items; if not specified, defaults to true. |
techId |
integer |
if given, return item cost as it applies to that user |
excludeContractId |
integer |
if given, only return lib items that don't have a rule on this contract |
createdBefore |
integer |
timestamp, matches records created on or before |
createdAfter |
integer |
timestamp, matches records created on or after |
updatedBefore |
integer |
timestamp, matches records updated on or before |
updatedAfter |
integer |
timestamp, matches records updated on or after |
POST/PUT Parameters
Name |
Type |
Required |
Value |
name |
string |
on POST |
item display name |
code |
string |
no |
item code, must be unique, 100 characters max length |
type |
string |
on POST |
lib item type, one of: "inspection", "service", "part", "labor", "fee", "material", "general_conditions", "equipment", "subcontractor", "other" |
cost |
double |
no |
standard cost of this item; can be null. |
serviceLineId |
integer |
no |
id of the this item's service line |
companyId |
integer |
no |
id of the company that this item is specific to. If provided, this item will only be available on jobs and quotes for which this company is the customer, the vendor, or the location owner. |
active |
boolean |
no |
whether item code is active; if not specified, defaults to true. |
taxable |
boolean |
no |
should invoice items using this lib item be taxable by default, defaults to true. |
techId |
integer |
no |
PUT ONLY. if given, sets a labor item's cost as it applies to that user |
Returned Elements
Name |
Type |
Value |
libItems |
array (Libitem) |
list of lib item objects |
active |
boolean |
is the item currently active (inactive items are kept for data integrity |
taxable |
boolean |
should invoice items using this lib item be taxable by default |
price |
double |
only populated when providing a contract context which exists and to which the session user has access, else null |
cost |
double |
standard cost of this item, else null |
company |
Company |
company that this item is specific to, if any |
serviceLine |
Service Line |
serviceLine of this item |
isGeneric |
boolean |
true indicates this item is used for representing generic or ad-hoc items |
serviceLine.abbreviation |
string |
Deprecated. Use serviceLine.abbr instead. |
externalIds |
object |
a key/value object of external system ids, only returned if account has external integrations defined |
priceRuleType |
string or null |
The type of rule that generated the price. |
created |
integer |
Unix timestamp of this record's creation time |
updated |
integer |
Unix timestamp of when this record was last updated |
Retrieve all lib items that match a given name
GET /libitem?name=cap
200
{
"data": {
"totalPages": 1,
"page": 1,
"libItems": [
{
"uri": "https://api.servicetrade.com/api/libitem/104",
"id": 104,
"code": "BCAP-M",
"name": "Blow-off Cap, Metal",
"type": "Other",
"active": true,
"price": null,
"priceRuleType": null,
"taxable": true,
"cost": null,
"company": null,
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/SUPP.png",
"abbr": "SUPP",
"abbreviation": "SUPP"
},
"isGeneric": false,
"created": 1399993795,
"updated": 1399994065
},
{
"uri": "https://api.servicetrade.com/api/libitem/105",
"id": 105,
"code": "BCAP-R",
"name": "Blow-off Cap, Rubber",
"type": "Other",
"active": true,
"price": null,
"priceRuleType": null,
"taxable": true,
"cost": null,
"company": null,
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/SUPP.png",
"abbr": "SUPP",
"abbreviation": "SUPP"
},
"isGeneric": false,
"created": 1399993795,
"updated": 1399994065
}
]
}
}
Retrieve all lib items that match a list of service lines
GET /libitem?serviceLineIds=4,27
200
{
"data": {
"totalPages": 1,
"page": 1,
"libItems": [
{
"uri": "https://api.servicetrade.com/api/libitem/104",
"id": 104,
"code": "BCAP-M",
"name": "Blow-off Cap, Metal",
"type": "Other",
"active": true,
"price": null,
"priceRuleType": null,
"taxable": true,
"cost": 4.25,
"company": null,
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/SUPP.png",
"abbr": "SUPP",
"abbreviation": "SUPP"
},
"isGeneric": false,
"created": 1399993795,
"updated": 1399994065
},
{
"uri": "https://api.servicetrade.com/api/libitem/105",
"id": 105,
"code": "BCAP-R",
"name": "Blow-off Cap, Rubber",
"type": "Other",
"active": true,
"price": null,
"priceRuleType": null,
"taxable": true,
"cost": 3.25,
"company": null,
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/SUPP.png",
"abbr": "SUPP",
"abbreviation": "SUPP"
},
"isGeneric": false,
"created": 1399993795,
"updated": 1399994065
},
{
"uri": "https://api.servicetrade.com/api/libitem/567",
"id": 105,
"code": null,
"name": "Vent Cover",
"type": "Other",
"active": true,
"price": null,
"priceRuleType": null,
"taxable": true,
"cost": null,
"company": null,
"serviceLine": {
"id": 27,
"name": "HVAC",
"trade": "HVAC",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/OTHER.png",
"abbr": "HVAC",
"abbreviation": "HVAC"
},
"isGeneric": false,
"created": 1399993795,
"updated": 1399994065
}
]
}
}
No lib item matches found
GET /libitem?name=foobarbazqux
200
{
"data": {
"totalPages": 1,
"page": 1,
"libItems": []
}
}
Retrieve information for a single lib item
GET /libitem/104
200
{
"data": {
"uri": "https://api.servicetrade.com/api/libitem/104",
"id": 104,
"code": "BCAP-M",
"name": "Blow-off Cap, Metal",
"type": "Other",
"active": true,
"price": null,
"priceRuleType": null,
"taxable": true,
"cost": 4.25,
"company": null,
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/SUPP.png",
"abbr": "SUPP",
"abbreviation": "SUPP"
},
"isGeneric": false,
"created": 1399993795,
"updated": 1399994065
}
}
Retrieve information for a single lib item, in a contract context
GET /libitem/104?contractorId=16&contracteeId=1&locationId=44
200
{
"data": {
"uri": "https://api.servicetrade.com/api/libitem/104",
"id": 104,
"code": "BCAP-M",
"name": "Blow-off Cap, Metal",
"type": "Other",
"active": true,
"price": 8.50,
"priceRuleType": "unit",
"taxable": true,
"cost": 4.25,
"company": null,
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/SUPP.png",
"abbr": "SUPP",
"abbreviation": "SUPP"
}
}
}
Retrieve information for a lib item which does not exist
GET /libitem/9999999
404
Create a new lib item
POST /libitem
{"name":"Widget, Left-handed","type":"part","serviceLineId":4,"code":"WDGT-L","cost":5.99,"companyId":5631}
200
{
"data": {
"uri": "https://api.servicetrade.com/api/libitem/2323",
"id": 2323,
"name": "Widget, Left-handed",
"code": "WDGT-L",
"type": "part",
"typeId": 3,
"active": true,
"price": null,
"priceRuleType": null,
"taxable": true,
"cost": 5.99,
"company": {
"id": 5631,
"uri": "https://api.servicetrade.com/api/company/5631",
"name": "Sinister Services"
},
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "https://api.servicetrade.com/image/icons/service_lines/32/SUPP.png",
"abbreviation": "SUPP"
}
}
}
Return to Top
Location
The location resource is used to retrieve lists of locations or detailed information about a single location.
- Resource URL: /location/[locationId]
- Available Verbs: GET, POST, PUT, DELETE
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/location |
200 |
|
GET |
/location/123 |
200 |
|
GET |
/location/123 |
404 |
location 123 not found |
GET |
/location/123/asset |
200 |
retrieve list of assets |
GET |
/location/123/asset/10 |
200 |
retrieve asset info |
GET |
/location/123/comment |
200 |
retrieve list of comments |
GET |
/location/123/comment/67 |
200 |
retrieve comment info |
POST |
/location |
400 |
missing, incomplete or invalid parameters |
POST |
/location |
403 |
do not have permission to do this |
POST |
/location |
404 |
company not found |
POST |
/location/123/comment |
200 |
create a comment - see Comment for details |
POST |
/location/123/merge |
200 |
merge a location into another |
POST |
/location/123/merge |
403 |
no permission |
POST |
/location/123/merge |
400 |
invalid params |
PUT |
/location/123 |
200 |
|
PUT |
/location/123 |
403 |
do not have permission to do this |
PUT |
/location/123 |
404 |
location 123 not found |
DELETE |
/location/123 |
204 |
location deleted |
DELETE |
/location/123 |
403 |
do not have permission to do this |
DELETE |
/location/123 |
404 |
location not found |
DELETE |
/location/123 |
409 |
cannot delete location because it has associated data |
Query Params
Name |
Type |
Value |
name |
string |
string to find in the location name or store number |
refNumber |
string |
find locations by refNumber exact match |
companyId |
string |
comma delimited list of integers of company ids, return only locations belonging to any of these companies |
isCustomer |
boolean |
returns only customer locations, default true |
isVendor |
boolean |
returns only vendor offices |
updatedAfter |
integer |
return only locations whose last update time is on or after the given timestamp |
updatedBefore |
integer |
return only locations whose last update time is on or before the given timestamp |
createdBefore |
integer |
timestamp, matches records created on or before |
createdAfter |
integer |
timestamp, matches records created on or after |
officeIds |
string |
comma delimited list of integers of office ids for offices servicing the location |
regionIds |
string |
comma delimited list of integers of region ids, returns only locations within any of those regions |
status |
string |
comma delimited list of statuses, returns only locations which have one of those statuses, one or more of: 'active', 'inactive', 'pending' |
companyStatus |
string |
returns only locations whose company has this status, one of: 'active', 'inactive', 'pending' |
tag |
string |
comma-separated list of tag strings, only locations with all tags will be returned |
limit |
integer |
limit the locations returned (default 10, maximum 5000) |
PUT/POST Parameters
Name |
Required |
Type |
Value |
name |
for POST |
string |
The name of the location |
refNumber |
no |
string |
reference number for identifying this location. This reference number is set automatically if not specified, using a counter that increments by 1 for each new location created without specifying a reference number. Locations created before this field existed will have a refNumber that matches the id, unless it is updated later by the User. |
address |
for POST |
Address |
Overrides individual address fields |
addressStreet |
no |
string |
The street of the address for the location (alias for address.street) |
addressCity |
no |
string |
The city of the address for the location (alias for address.city) |
addressState |
no |
string |
The state of the address for the location (alias for address.state) |
addressPostalCode |
no |
string |
The postal code of the address for the location (alias for address.postalCode) |
companyId |
for POST |
string |
The ID for the company to which the location belongs |
officeIds |
no |
array (integer) |
Offices assigned to this location (if not given, defaults to vendor company's primary office) |
phoneNumber |
no |
string |
Phone number for the location itself (not a phone number for a contact). |
email |
no |
string |
Email address for the location itself (not an email address for a contact). |
storeNumber |
no |
string |
Store number for the location. This field is deprecated. Please use refNumber instead. |
primaryContactId |
no |
integer |
id of contact that should be the primary contact. Request will error out if the contact has been assigned to a different location or company. Null to clear current primary contact designation. |
lat |
no |
float |
GPS latitude |
lon |
no |
float |
GPS longitude |
status |
no |
string |
one of ('active', 'pending', 'inactive', 'on_hold), 'active' is the default |
taxable |
no |
boolean |
should invoice items for invoices at this location be taxable by default? |
brandId |
no |
integer |
id of the brand to associate with this location or null for none |
Merge Parameters
The merge endpoint replaces this location (the loser) with another (the winner) on all entities that are assigned the losing location. The loser is then deleted.
Name |
Type |
Required |
Value |
replacementId |
integer |
Yes |
the id of the location you wish to merge this location into, the "winner" |
Returned Elements
Name |
Type |
Value |
locations |
array (Location) |
list of location objects |
refNumber |
string |
reference number for identifying this location |
storeNumber |
string |
Store number for the location. This field is deprecated and may be removed in a future release. |
status |
string |
status of location |
company |
Company |
id of company to which this location belongs |
brand |
Brand |
the default brand to associate with activity at this location |
primaryContact |
Contact |
the primary contact of this location |
offices |
array (Location) |
list of offices which serve this location |
geocodeQuality |
integer |
indicates how precise the latitude and longitude values are |
generalManager |
string |
name of the primary contact at the location |
created |
integer |
unix timestamp of this record's creation time |
updated |
integer |
unix timestamp of when this record was last updated |
externalIds |
object |
a key/value object of external system ids, only returned if account has external integrations defined |
taxable |
boolean |
should invoice items for invoices at this location be taxable by default? |
tags |
array (Tag) |
array of tags |
remitToSource |
string |
the source of the remit to address |
remitToAddress |
array |
the remit to address based on the remit to source |
Retrieve all locations that match a given name
GET /location?name=Foo
200
{
"data": {
"totalPages": 1,
"page": 1,
"locations": [
{
"uri": "https://api.servicetrade.com/api/location/42",
"id": 42,
"refNumber": "42",
"name": "Bar Food",
"lat": 12.34,
"lon": -45.67,
"geocodeQuality": 87,
"distance": null,
"phoneNumber": "(321) 555-5623",
"email": "joe@barfood.com",
"generalManager": "Joe Guy",
"primaryContact": {
"id": 16,
"uri": "https://api.servicetrade.com/api/contact/14",
"firstName": "Joe",
"lastName": "Guy",
"phone": "530-867-5309",
"mobile": "",
"alternatePhone": "",
"email": "uuxiiuit+neal@gmail.com",
"type": "management"
},
"created": 1347915466,
"updated": 1347915466,
"address": {
"street": "983 Streetsberry Lane",
"city": "Blackstone",
"state": "WV",
"postalCode": "34523"
},
"storeNumber": "100-A",
"status": "active",
"taxable": true,
"company": {
"uri": "https://api.servicetrade.com/api/company/37",
"id": 37,
"name": "Beer Knutz, LLC"
},
"brand": null,
"tags": [],
"offices": [
{
"id": 68,
"uri": "https://api.servicetrade.com/api/location/68",
"name": "Bartender's Friend Cleaning - Main Office",
"legacyId": null,
"lat": 36.516086,
"lon": -78.31879,
"address": {
"street": "118 Friendly Rd",
"city": "Manson",
"state": "NC",
"postalCode": "27553"
},
"taxable": false
}
],
"remitToAddress": {
"street": "123 Typewriter Way",
"city": "Aiburg",
"state": "NC",
"postalCode": "23462"
"phone": "333-444-5555"
"email": "uuxiiuit+neal@gmail.com"
},
"remitToSource": "office"
},{
"uri": "https://api.servicetrade.com/api/location/33",
"id": 33,
"refNumber": "33",
"name": "Foo's Bar",
"lat": 12.34,
"lon": -45.67,
"geocodeQuality": 87,
"distance": null,
"phoneNumber": "(555) 555-2526",
"email": "alan@turing.com",
"generalManager": "Alan Turing",
"primaryContact": {
"id": 15,
"uri": "https://api.servicetrade.com/api/contact/14",
"firstName": "Alan",
"lastName": "Turning",
"phone": "530-867-5309",
"mobile": "",
"alternatePhone": "",
"email": "uuxiiuit+neal@gmail.com",
"type": "management"
},
"created": 1347915466,
"updated": 1347915466,
"address": {
"street": "123 Typewriter Way",
"city": "Aiburg",
"state": "NC",
"postalCode": "23462"
},
"storeNumber": "100-A",
"status": "active",
"taxable": true,
"company": {
"uri": "https://api.servicetrade.com/api/company/12",
"id": 12,
"name": "Good Eats, Inc."
},
"brand": null,
"tags": [],
"offices": [
{
"id": 69,
"uri": "https://api.servicetrade.com/api/location/69",
"name": "Better Than Your Plumbing Maintenance Co - NC Satellite"
"legacyId": null,
"lat": 35.526086,
"lon": -79.31379,
"address": {
"street": "1219 Broad St",
"city": "Durham",
"state": "NC",
"postalCode": "27716"
},
"taxable": false
}
]
"remitToAddress": null,
"remitToSource": ""
}
]
}
}
No location matches found
GET /location?name=Baz
200
{
"data": {
"totalPages": 1,
"page": 1,
"locations": []
}
}
Retrieve information for a single location
GET /location/33
200
{
"data": {
"uri": "https://api.servicetrade.com/api/location/33",
"id": 33,
"refNumber": "33",
"name": "Foo's Bar",
"lat": 12.34,
"lon": -45.67,
"geocodeQuality": 87,
"distance": null,
"phoneNumber": "(555) 555-2526",
"email": "alan@turing.com",
"generalManager": "Alan Turing",
"primaryContact": {
"id": 15,
"uri": "https://api.servicetrade.com/api/contact/14",
"firstName": "Alan",
"lastName": "Turning",
"phone": "530-867-5309",
"mobile": "",
"alternatePhone": "",
"email": "uuxiiuit+neal@gmail.com",
"type": "management"
},
"created": 1347915466,
"updated": 1347915466,
"address": {
"street": "123 Typewriter Way",
"city": "Aiburg",
"state": "NC",
"postalCode": "23462"
},
"status": "active",
"taxable": true,
"storeNumber": "100-A",
"company": {
"uri": "https://api.servicetrade.com/api/company/12",
"id": 12,
"name": "Good Eats, Inc."
},
"brand": null,
"tags": [],
"offices": [
{
"id": 69,
"uri": "https://api.servicetrade.com/api/location/69",
"name": "Better Than Your Plumbing Maintenance Co - NC Satellite",
"legacyId": null,
"lat": 35.526086,
"lon": -79.31379,
"address": {
"street": "1219 Broad St",
"city": "Durham",
"state": "NC",
"postalCode": "27716"
},
"taxable": false
}
],
"remitToAddress": {
"street": "123 Typewriter Way",
"city": "Aiburg",
"state": "NC",
"postalCode": "23462"
"phone": "333-444-5555"
"email": "uuxiiuit+neal@gmail.com"
},
"remitToSource": "office",
"externalIds": {
"peachtree": "332-FOOSBAR",
"salesforce": "na1.salesforce.com/01I90000000jOLr"
}
}
}
Retrieve information for a location which does not exist
GET /location/987
404
List assets at a location
GET /location/2/asset
200
{
"data": {
"totalPages": 1,
"page": 1,
"assets": [
{
"id": 1,
"uri": "https://api.servicetrade.com/api/asset/1",
"location": {
"id": 2,
"uri": "https://api.servicetrade.com/api/location/2",
"name": "Chuck E. Cheese #13 - Orange",
"lat": 33.520876,
"lon": -80.882115,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "2390 Chestnut Street, Suite C3",
"city": "Orange",
"state": "SC",
"postalCode": "29115"
}
"taxable": false,
"status": "active"
},
"type": "location",
"display": "Location",
"name": "Building",
"properties": {}
},
{
"id": 27,
"uri": "https://api.servicetrade.com/api/asset/27",
"location": {
"id": 2,
"uri": "https://api.servicetrade.com/api/location/2",
"name": "Chuck E. Cheese #13 - Orange",
"lat": 33.520876,
"lon": -80.882115,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "2390 Chestnut Street, Suite C3",
"city": "Orange",
"state": "SC",
"postalCode": "29115"
},
"taxable": false,
"status": "active"
},
"type": "panic_door",
"display": "Panic Door",
"name": "Panic Door",
"properties": {}
},
]
}
}
Create a new location
POST /location
{"companyId": 30, "name": "Burger Bistro", "addressStreet": "101 Burger Way", "addressCity": "Cary", "addressState": "NC", "addressPostalCode": 27519, "officeIds": [870]}
200
{
"data": {
"id": 820,
"refNumber": "820",
"uri": "https://api.servicetrade.com/api/location/820",
"name": "Burger Bistro",
"legacyId": null,
"lat": 35.774097,
"lon": -78.857784,
"address": {
"street": "101 Burger Way",
"city": "Cary",
"state": "NC",
"postalCode": "27519"
},
"status": "active",
"taxable": true,
"storeNumber": "100-A",
"geocodeQuality": 99,
"phoneNumber": "",
"email": "",
"generalManager": "",
"primaryContact": null,
"created": 1377020736,
"updated": 1377020736,
"company": {
"id": 30,
"uri": "https://api.servicetrade.com/company/30",
"name": "Burgers International"
},
"brand": null,
"tags": [],
"offices": [
{
"id": 870,
"uri": "https://api.servicetrade.com/api/location/870",
"name": "Better Than Your Plumbing Maintenance Co - Main Office",
"legacyId": null,
"lat": 35.526086,
"lon": -79.31379,
"address": {
"street": "1533 S Main St",
"city": "Winston-Salem",
"state": "NC",
"postalCode": "27127"
},
"taxable": false
}
]
}
}
Assign new primary contact
PUT /location/14
{ "primaryContactId": 14 }
200
{
"data": {
"id": 14,
"refNumber": "14",
"uri": "https://api.servicetrade.com/api/location/14",
"name": "Cato #11297 - Vienna",
"legacyId": null,
"lat": 12.345678,
"lon": -9.876543,
"geocodeQuality": 87,
"phoneNumber": "(530) 867-5309",
"email": "uuxiiuit+neal@gmail.com",
"generalManager": "Ted Smith",
"primaryContact": {
"id": 14,
"uri": "https://api.servicetrade.com/api/contact/14",
"firstName": "Ted",
"lastName": "Smith",
"phone": "530-867-5309",
"mobile": "",
"alternatePhone": "",
"email": "uuxiiuit+neal@gmail.com",
"type": "management"
},
"created": 1365097836,
"updated": 1365097836,
"address": {
"street": "605 Grand Central Avenue, Unit 104",
"city": "Vienna",
"state": "WV",
"postalCode": "26105"
},
"status": "active",
"taxable": true,
"storeNumber": "100-A",
"company": {
"id": 3,
"uri": "https://api.servicetrade.com/api/company/3",
"name": "Cato Corporation"
},
"brand": null,
"tags": [],
"offices": [
{
"id": 870,
"uri": "https://api.servicetrade.com/api/location/870",
"name": "Better Than Your Plumbing Maintenance Co - WV Satellite"
"legacyId": null,
"lat": 35.526086,
"lon": -79.31379,
"address": {
"street": "1 John Marshall Dr",
"city": "Huntington",
"state": "WV",
"postalCode": "25755"
},
"taxable": false
}
]
}
}
Merge a location into another
POST /api/location/123/merge
{"replacementId": 456}
200
{
"data": {
"uri": "https://api.servicetrade.com/api/location/456",
"id": 456,
"refNumber": "456",
"name": "Foo's Bar",
"legacyId": null,
"lat": 12.34,
"lon": -45.67,
"phoneNumber": "(555) 555-2526",
"email": "alan@turing.com",
"primaryContact": {
"id": 15,
"uri": "https://api.servicetrade.com/api/contact/14",
"firstName": "Alan",
"lastName": "Turning",
"phone": "530-867-5309",
"mobile": "",
"alternatePhone": "",
"email": "uuxiiuit+neal@gmail.com",
"type": "management"
},
"address": {
"street": "123 Typewriter Way",
"city": "Aiburg",
"state": "NC",
"postalCode": "23462"
},
"taxable": false
}
}
Return to Top
MasterAgreement
The MasterAgreement resource is used to request if the currently authenticated user has accepted the most recent master agreement.
- Resource URL: /masteragreement
- Available Verbs: GET, POST
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/masteragreement |
200 |
|
GET |
/masteragreement |
204 |
no current Master Agreement exists (no acceptance necessary) |
POST |
/masteragreement |
200 |
current user accepts the current Master Agreement |
POST |
/masteragreement |
204 |
no current Master Agreement exists (no acceptance necessary) |
PUT |
/masteragreement |
405 |
not allowed |
DELETE |
/masteragreement |
405 |
not allowed |
Returned Elements
Name |
Type |
Value |
masterAgreementText |
string |
text of the most recent Master Agreement |
masterAgreementAccepted |
boolean |
whether the user has accepted the most recent Master Agreement |
Sample request and response
GET /masteragreement
200
{
"data": {
"masterAgreementText": "This is the current Master Agreement",
"masterAgreementAccepted": true
}
}
No Master Agreement to accept
GET /masteragreement
204
Accepting the current Master Agreement
POST /masteragreement
200
{
"data": {
"masterAgreementText": "This is the current MasterAgreement",
"masterAgreementAccepted": true
}
}
Return to Top
Message
The message resource is used to send messages to contacts.
- Resource URL: /message/[params]
- Available Verbs: GET, POST
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/message |
405 |
not allowed |
GET |
/message/123 |
200 |
|
GET |
/message |
403 |
no permission |
GET |
/message |
404 |
entity not found |
GET |
/message |
405 |
not allowed |
POST |
/message |
200 |
|
POST |
/message |
403 |
no permission |
POST |
/message |
404 |
entity not found |
POST |
/message/123 |
405 |
not allowed |
POST |
/message/123/send |
405 |
|
PUT |
/message |
405 |
not allowed |
DELETE |
/message |
405 |
not allowed |
General Parameters for POST
Name |
Type |
Required |
Value |
contactIds |
string |
yes |
comma delimited ids of the contact to send the message to |
contactTypes |
array |
no |
If given, only contacts with a type that is in this array will be sent the message. Case insensitive. |
mode |
string |
yes |
One of: email, bulk_email. This is the mode of communication to use to send the message. bulk_email is the recommended mode for when there is more than one recipient. |
template |
string |
yes |
One of: ChangeOrder, TechEnRoute, ServiceLink, Quote, QuoteApproved, Invoice, InvoiceLink, WorkAcknowledgement. The name of template to use. |
params |
object |
yes |
parameters for template |
send |
boolean |
no |
send the message upon creation? default is false. |
POST Parameters for Template ChangeOrder
Name |
Type |
Required |
Value |
changeOrderId |
integer |
yes |
id of the change order |
subject |
string |
no |
customized email subject |
message |
string |
no |
customized message to include in the email body |
POST Parameters for Template TechEnRoute
Name |
Type |
Required |
Value |
appointmentId |
integer |
yes |
id of the appointment for which the tech is en route |
techId |
integer |
yes |
user id of the tech who is en route |
arrivalTime |
integer |
no |
Unix timestamp of the expected arrival time |
POST Parameters for Template ServiceLink
Name |
Type |
Required |
Value |
jobId |
integer |
yes |
id of the job the Service Link is for |
subject |
string |
no |
customized email subject |
message |
string |
no |
customized message to include in the email body |
serviceReviewTechId |
integer |
no |
if given, tech id from which to send a Service Review request. Both serviceReviewTechId and serviceReviewContactId must be given in order to send a Service Review request. |
serviceReviewContactId |
integer |
no |
if given, contact id to which to send a Service Review request. Both serviceReviewTechId and serviceReviewContactId must be given in order to send a Service Review request. |
serviceReviewDescription |
integer |
no |
an optional message to include in the Service Review request about the work performed |
POST Parameters for Template Quote
Name |
Type |
Required |
Value |
quoteId |
integer |
yes |
id of the quote that the contact will be shown |
subject |
string |
no |
customized email subject |
message |
string |
no |
customized message to include in the email body |
showTotal |
string |
no |
show total quote amount in the email, default is true |
POST Parameters for Template QuoteApproved
Name |
Type |
Required |
Value |
quoteId |
integer |
yes |
id of the quote that the contact has approved |
POST Parameters for Template Invoice
Name |
Type |
Required |
Value |
invoiceId |
integer |
yes |
id of the invoice that the contact will be shown |
subject |
string |
no |
customized email subject |
message |
string |
no |
customized message to include in the email body |
POST Parameters for Template WorkAcknowledgement
Name |
Type |
Required |
Value |
appointmentId |
integer |
yes |
id of the appointment for work acknowledgement |
officeId |
integer |
no |
If office id is supplied then office's brand name (if active or inactive) will be shown as the sender of the email, otherwise the user's full name will be used |
Returned Elements
Name |
Type |
Value |
uri |
string |
resource identifier of the attachment |
id |
integer |
attachment id |
template |
string |
message template |
mode |
string |
message mode |
subject |
string |
message subject |
contacts |
array (Contact) |
list of recipient contacts |
body |
string |
message body |
sent |
integer or null |
unix timestamp of when the message was last sent or null if it has never been sent |
totalCount |
integer |
count of how many recipient emails were attempted |
successCount |
integer |
count of how many recipient emails were delivered successfully |
failureCount |
integer |
count of how many recipient emails failed, including bounces, complaints, and other failures |
bounceCount |
integer |
count of how many recipient emails bounced |
complaintCount |
integer |
count of how many recipient emails received complaints |
Retrieve message 112233
GET /message/112233
200
{
"totalPages": 1,
"page": 1,
"data": {
"uri": "https://api.servicetrade.com/api/message/112233",
"id": 112233,
"template": "TechEnRoute",
"mode": "email",
"sender": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"contacts": [
{
"id": 123,
"uri": "https://api.servicetrade.com/api/contact/123",
"firstName": "Joe",
"lastName": "Guy",
"phone": "530-867-5309",
"mobile": "",
"alternatePhone": "",
"email": "uuxiiuit+neal@gmail.com",
"type": "management"
}
],
"params": {
"appointmentId": 1122,
"techId": 3344,
"arrivalTime": 1322680442
},
"sent": 1322680048,
"failureCount": 1,
"successCount": 0,
"bounceCount": 0,
"complaintCount": 1,
"totalCount": 1
}
}
Create and send a message
POST /message
{"contactIds": "123", "contactTypes": ["on-site", "scheduling"], "mode": "email", "template": "TechEnRoute", "send": true,
"params": {"appointmentId": 1122, "techId": 3344, "arrivalTime": 1322680442}}
200
{
"totalPages": 1,
"page": 1,
"data": {
"uri": "https://api.servicetrade.com/api/message/112233",
"id": 112233,
"template": "TechEnRoute",
"mode": "email",
"sender": {
"id": 6,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Joe User",
"status": "active",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"contacts": [
{
"id": 123,
"uri": "https://api.servicetrade.com/api/contact/123",
"firstName": "Joe",
"lastName": "Guy",
"phone": "530-867-5309",
"mobile": "",
"alternatePhone": "",
"email": "uuxiiuit+neal@gmail.com",
"type": "management"
}
],
"params" : {
"appointmentId": 1122,
"techId": 3344,
"arrivalTime": 1322680442
},
"sent": 1322680048,
"failureCount": 0,
"successCount": 1,
"bounceCount": 0,
"complaintCount": 0,
"totalCount": 1
}
}
Return to Top
Payment
The payment resource is used to retrieve list of payments associated with an invoice or detailed information about a single payment.
- Resource URL: /payment/[paymentId]
- Available Verbs: GET, POST, PUT
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/payment |
200 |
|
GET |
/payment/123 |
200 |
|
GET |
/payment/123 |
404 |
payment 123 not found |
POST |
/payment |
200 |
payment created |
POST |
/invoice/123/payment |
200 |
payment created for invoice 123 |
POST |
/invoice/123/payment |
403 |
not allowed |
POST |
/invoice/123/payment |
404 |
invoice not found |
POST |
/payment |
400 |
missing, incomplete, or invalid parameters |
POST |
/payment |
403 |
user is not allowed to manage payments |
PUT |
/payment |
405 |
not allowed |
PUT |
/payment/123 |
200 |
payment updated |
PUT |
/payment/123 |
405 |
payment 123 not found |
PUT |
/payment/123 |
404 |
payment 123 not acccessible by the user (or user is not allowed to manage payments) |
DELETE |
/payment |
405 |
not allowed |
Query Params
Name |
Type |
Value |
invoiceId |
integer |
invoice to which this payment is attached |
customerId |
integer |
customer for this invoice |
transactionDateBefore |
integer |
transactionDate on or before this timestamp |
transactionDateAfter |
integer |
transactionDate on or after this timestamp |
limit |
integer |
limit the number of invoices returned (default 2000, maximum 2000) |
POST/PUT Parameters
Name |
Type |
Required |
Value |
transactionDate |
integer |
no |
Unix timestamp indicating the date on which this invoice was transacted. Defaults to now on POST if not provided. |
invoiceId |
integer |
for POST |
sets the invoice to which this payment is attached. This is a POST only field. |
customerId |
integer |
for POST |
sets the customer of the payment. This is a POST only field. |
paymentMethod |
string |
for POST |
sets the payment method of the payment to one of ('cash', 'check', ach', 'credit_card'). This is a POST only field. |
source |
string |
for POST |
sets the source of payment to one of ('fattmerchant', 'manual'). This is a POST only field. |
amount |
double |
yes |
the amount of this payment, defaults to the invoice's total cost or 0 if not set. Can not be negative. |
referenceNumber |
string |
yes |
sets the reference number of the payment given to us by the payment source. |
status |
string |
yes |
sets the invoice status to one of ('applied', 'void'). 'void' is only acceptable transition on PUT. |
Returned Elements
Name |
Type |
Value |
uri |
string |
resource identifier for the given payment |
id |
string |
payment id |
transactionDate |
integer |
payment transaction date is for the day indicated by this timestamp |
creator |
User |
the user that created that initiated this payment |
invoice |
Invoice |
payment invoice |
customer |
Company |
payment customer |
paymentMethod |
string |
the payment method used |
source |
string |
the source system that is processing this payment |
amount |
double |
the amount this payment is for |
referenceNumber |
string |
a reference number from the source system for this payment |
status |
string |
status of the payment |
created |
integer |
payment was created at this timestamp |
updated |
integer |
payment was last updated at this timestamp |
Retrieve all payments for a given invoice
GET /payment?invoiceId=3
200
{
"data": {
"totalPages": 1,
"page": 1,
"payments": [
{
"transactionDate": 1598587200,
"creator": {
"id": 21,
"uri": "https://api.servicetrade.com/api/user/21",
"name": "Arthur Dent",
"status": "active",
"email": "uuxiiuit+standalone@gmail.com",
"avatar": {
"small": "https://api.servicetrade.com/avatar-small.png",
"medium": "https://api.servicetrade.com/avatar-medium.png",
"large": "https://api.servicetrade.com/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"invoice": {
"id": 3,
"uri": "https://api.servicetrade.com/api/invoice/3",
"name": "Invoice for Job #10300011"
},
"customer": {
"id": 34,
"uri": "https://api.servicetrade.com/api/company/34",
"name": "DunnWell"
},
"paymentMethod": "credit_card",
"source": "fattmerchant",
"amount": 2,
"referenceNumber": "123456789",
"status": "applied",
"created": 1598639693,
"updated": 1598639693
},
{
"transactionDate": 1598587201,
"creator": {
"id": 21,
"uri": "https://api.servicetrade.com/api/user/21",
"name": "Arthur Dent",
"status": "active",
"email": "uuxiiuit+standalone@gmail.com",
"avatar": {
"small": "https://api.servicetrade.com/image/avatar-small.png",
"medium": "https://api.servicetrade.com/image/avatar-medium.png",
"large": "https://api.servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"invoice": {
"id": 3,
"uri": "https://api.servicetrade.com/api/invoice/3",
"name": "Invoice for Job #10300011"
},
"customer": {
"id": 34,
"uri": https://api.servicetrade.com/api/company/34",
"name": "DunnWell"
},
"paymentMethod": "credit_card",
"source": "fattmerchant",
"amount": 2,
"referenceNumber": "987654321",
"status": "void",
"created": 1598642732,
"updated": 1598642732
}
]
}
}
No invoice matches found
GET /payment?invoiceId=999999
200
{
"data": {
"totalPages": 1,
"page": 1,
"payments": []
}
}
Retrieve information for a single payment
GET /payment/1
200
{
"data": {
"id": 1,
"uri": "https://api.servicetrade.com/api/payment/1",
"name": "",
"transactionDate": 1598587200,
"creator": {
"id": 21,
"uri": "https://api.servicetrade.com/api/user/21",
"name": "Arthur Dent",
"status": "active",
"email": "uuxiiuit+standalone@gmail.com",
"avatar": {
"small": "https://api.servicetrade.com/image/avatar-small.png",
"medium": "https://api.servicetrade.com/image/avatar-medium.png",
"large": "https://api.servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"invoice": {
"id": 3,
"uri": "https://api.servicetrade.com/api/invoice/3",
"name": "Invoice for Job #10300011"
},
"customer": {
"id": 34,
"uri": "https://api.servicetrade.com/api/company/34",
"name": "DunnWell"
},
"paymentMethod": "credit_card",
"source": "fattmerchant",
"amount": 2,
"referenceNumber": "123456789",
"status": "applied",
"created": 1598639693,
"updated": 1598639693
}
}
Retrieve information for a payment which does not exist
GET /payment/567
404
Create a payment
POST /payment
{"paymentMethod":"credit_card","source":"fattmerchant","status":"applied","customerId":34,"invoiceId":3,"referenceNumber": "123456789","amount": "2.00"}
200
{
"data": {
"id": 1,
"uri": "https://api.servicetrade.com/api/payment/1",
"name": "",
"transactionDate": 1598587200,
"creator": {
"id": 21,
"uri": "https://api.servicetrade.com/api/user/21",
"name": "Arthur Dent",
"status": "active",
"email": "uuxiiuit+standalone@gmail.com",
"avatar": {
"small": "https://api.servicetrade.com/image/avatar-small.png",
"medium": "https://api.servicetrade.com/image/avatar-medium.png",
"large": "https://api.servicetrade.com/image/avatar-large.png"
},
"isTech": true,
"isHelper": false
},
"invoice": {
"id": 3,
"uri": "https://api.servicetrade.com/api/invoice/3",
"name": "Invoice for Job #10300011"
},
"customer": {
"id": 34,
"uri": "https://api.servicetrade.com/api/company/34",
"name": "DunnWell"
},
"paymentMethod": "credit_card",
"source": "fattmerchant",
"amount": 2,
"referenceNumber": "123456789",
"status": "applied",
"created": 1598639693,
"updated": 1598639693
}
}
Return to Top
Payment terms
The paymentterms resource is used to retrieve the list of payment terms
- Resource URL: /paymentterms/[paymenttermsId]
- Available Verbs: GET
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/paymentterms |
200 |
|
GET |
/paymentterms/5 |
200 |
|
GET |
/paymentterms/999 |
404 |
paymentterms 999 not found |
POST |
/paymentterms |
405 |
not allowed |
PUT |
/paymentterms |
405 |
not allowed |
DELETE |
/paymentterms |
405 |
not allowed |
Returned Elements
Name |
Type |
Value |
paymentterms |
array (Paymentterms) |
list of payment terms objects |
Retrieve all available paymentterms
GET /paymentterms
200
{
"data": {
"totalPages": 1,
"page": 1,
"paymenttermss": [
{
"id": 1,
"uri": "https://api.servicetrade.com/api/paymentterms/1",
"name": "Net 10",
"orderIndex": 1
},
{
"id": 2,
"uri": "https://api.servicetrade.com/api/paymentterms/2",
"name": "Net 15",
"orderIndex": 2
},
{
"id": 5,
"uri": "https://api.servicetrade.com/api/paymentterms/5",
"name": "Net 30",
"orderIndex": 5
},
]
}
}
Retrieve information for a single paymentterms
GET /paymentterms/5
200
{
"data": {
"id": 5,
"uri": "https://api.servicetrade.com/api/paymentterms/5",
"name": "Net 30",
"orderIndex": 5
}
}
Retrieve information for a paymentterms which does not exist
GET /activity/999
404
Return to Top
Quote
The quotes resource is used to retrieve lists of quotes or detailed information about a single quote.
In ServiceTrade's data model, quotes have two components: quotes and quote requests. The quote request contains information about the customer and the services to be quoted. The quote contains information about the vendor who will perform the quoted services, including the items to be used and their prices. This model allows multiple quotes to "respond" to a single quote request; for instance, when competing quotes from several different vendors for the same scope of work are desired.
POSTing a quote without providing a quoteRequestId will automatically create a quote request and associate the newly created quote with it. The resulting quote request will have a type of "simple". For simple quote request/quote pairs, most properties of the quote request can be changed by PUTing their values directly to the quote object (see 'Parameters for PUT' below); for quotes associated with "advanced" quote requests, only the properties of the quote itself can be changed by PUTing to the quote object. Most use cases are handled by simple quotes/quote requests.
More information is available in the documentation for the quote request resource.
- Resource URL: /quote/[quoteId]
- Available Verbs: GET, POST, PUT
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/quote |
200 |
|
GET |
/quote/123 |
200 |
|
GET |
/quote/123 |
404 |
quote 123 not found |
GET |
/quote/123/comment |
200 |
list quote comments |
POST |
/quote |
200 |
|
POST |
/quote |
400 |
invalid post data |
POST |
/quote |
403 |
not permissioned |
POST |
/quote/123/comment |
200 |
create a comment - see Comment for details |
POST |
/quote/123/submit |
200 |
submit a quote |
POST |
/quote/123/submit |
403 |
not permissioned |
POST |
/quote/123/submit |
409 |
quote not in draft or new status |
POST |
/quote/123/approve |
200 |
approve a quote |
POST |
/quote/123/approve |
403 |
not permissioned |
POST |
/quote/123/approve |
409 |
quote not in submitted status |
POST |
/quote/123/reject |
200 |
reject a quote |
POST |
/quote/123/reject |
403 |
not permissioned |
POST |
/quote/123/reject |
409 |
quote not in submitted status |
POST |
/quote/123/cancel |
200 |
cancel a quote |
POST |
/quote/123/cancel |
403 |
not permissioned |
POST |
/quote/123/cancel |
409 |
quote not in uncanceled status |
POST |
/quote/123/copy |
200 |
copy a quote |
POST |
/quote/123/copy |
403 |
not permissioned |
POST |
/quote/123/copy |
409 |
invalid quote type for copy |
POST |
/quote/123/requestchanges |
200 |
request changes for a quote |
POST |
/quote/123/requestchanges |
403 |
not permissioned |
POST |
/quote/123/requestchanges |
409 |
quote not in submitted status |
POST |
/quote/123/reopen |
200 |
reopen a quote |
POST |
/quote/123/reopen |
403 |
not permissioned |
POST |
/quote/123/reopen |
409 |
quote not in canceled or rejected status |
POST |
/quote/123/makechanges |
200 |
makechanges a quote |
POST |
/quote/123/makechanges |
403 |
not permissioned |
POST |
/quote/123/makechanges |
409 |
quote not in submitted status |
POST |
/quote/123/viewed |
200 |
create a viewed event for a quote |
POST |
/quote/123/viewed |
403 |
not permissioned |
POST |
/quote/123/viewed |
409 |
quote in canceled status |
POST |
/quote/123/job |
200 |
add quote to a new or existing job |
POST |
/quote/123/job |
403 |
not permissioned |
POST |
/quote/123/job |
409 |
quote not in accepted status |
POST |
/quote/123/job |
409 |
attempted to create a budget for a job with an existing non-voided budget |
PUT |
/quote |
200 |
|
PUT |
/quote |
400 |
invalid put data |
PUT |
/quote |
403 |
not permissioned |
DELETE |
/quote |
405 |
not allowed |
Query Params
Name |
Type |
Value |
refNumber |
string |
find quote by refNumber exact match |
name |
string |
string to find in the quote name or store number |
status |
string |
comma delimited list of statuses to match |
vendorId |
string |
return only quotes for vendor with this company id |
customerId |
string |
return only quotes for quote request customer (the managing company) with this company id |
locationId |
string |
comma delimited list of integers, return only quotes applying to the locations |
assignedOfficeIds |
string |
comma-separated list of integers of office ids, returns only quotes assigned to these offices |
locationOwnerId |
string |
return only quotes applying to the location owner company |
userId |
string |
return only quotes assigned to the userId or quotes that are unassigned |
termsId |
integer |
return only quotes that have these terms explicitly assigned |
salesId |
string |
comma-separated list of integer ids of the user assigned as the salesperson of this quote |
assignedToId |
string |
return only quotes assigned to the user with this Id |
jobId |
string |
comma delimited list, return only accepted quotes whose service requests will be fulfilled by these jobs |
deficiencyId |
integer |
return only quotes having a service request to repair this deficiency |
expiresOnAfter |
integer |
return only quotes whose expiration date is on or after the given timestamp |
expiresOnBefore |
integer |
return only quotes whose expiration date is on or before the given timestamp |
regionIds |
string |
comma delimited list of integers of region ids, returns only quotes at locations within any of those regions |
createdAfter |
integer |
return only quotes whose creation time is on or after the given timestamp |
createdBefore |
integer |
return only quotes whose creation time is on or before the given timestamp |
updatedAfter |
integer |
return only quotes whose last update time is on or after the given timestamp |
updatedBefore |
integer |
return only quotes whose last update time is on or before the given timestamp |
sort |
string |
field to sort by, one of: name, created, updated, status (name is the default) |
sortOrder |
string |
order of sort, either ASC or DESC (ASC is the default) |
tag |
string |
comma-separated list of tag strings, only quotes with all tags will be returned |
Parameters for POST
Name |
Type |
Required |
Value |
refNumber |
string |
no |
reference number for identifying this quote. This reference number is set automatically if not specified, using a counter that increments by 1 for each new quote created without specifying a reference number. Quotes created before this field existed will have a refNumber that matches the id, unless it is updated later by the User. |
vendorId |
integer |
yes |
company performing the work of the quote and managing the quote request |
locationId |
integer |
yes |
location at which the work is being performed |
customerId |
integer |
no |
customer company of the work. Defaults to location company if not provided |
name |
name |
yes |
name of quote, and title of quote request |
visibility |
array(string) |
no |
Visibility. Subset of ("public", "by_service", "items", "noprices", "time_and_materials", "by_type", "type_detail"). Invalid if provided and empty. Defaults to ("public", "items") if not provided. If "by_service" is set, the results will be grouped by service. If "items" is set, the individual line items on the quote should be shown to the customer. If "noprices" is set, line items will NOT show pricing and tax to the customer. If "by_type" is set, one summary line item per item type will be shown to customer. If "type_detail" is set along with "by_type", item quantities will be shown to customer grouped by item type. |
expiresOn |
integer |
no |
Unix timestamp of quote expiration. Defaults to null. |
assignedTo |
integer |
no |
user to whom the quote is assigned. Defaults to null. |
salesId |
integer |
no |
user assigned as the salesperson of this quote. Defaults to null. |
notes |
string |
no |
description of the work to be done. |
description |
string |
yes |
description of the work to be quoted. This is stored on the quote request. |
jobType |
string |
yes |
job type that the quote should generate. This is stored on the quote request. One of: unknown, repair, construction, upgrade, service_call, urgent_service_call, priority_service_call, emergency_service_call, cleaning, inspection, priority_inspection, survey, preventative_maintenance, quality_assurance, delivery, pickup, exchange, sales, installation, warranty |
customerPo |
string |
no |
customer-provided purchase order number |
customerPoRequired |
boolean |
no |
Does this quote require a customer PO number in order to be accepted? Defaults to false. |
serviceRequestIds |
array (integer) |
yes |
services to be fulfilled on this quote/quote request (services must belong to the provided location) |
status |
string |
no |
initial status, one of "new" or "draft". Defaults to "new". |
contractId |
integer |
no |
contract used to supply price data to this quote |
assignedOfficeId |
integer |
no |
id of the office assigned to this quote (if not provided, will be calculated from the location's office assignments and the assignedTo's office assignment) |
termsId |
integer |
no |
(optional) id of the Terms and Conditions to use for this quote. If this is not provided, but a contract id is provided and that contract has quote Terms and Conditions, then those will be used. Otherwise, the account's default quote Terms and Conditions will be used. |
Parameters for PUT
Name |
Type |
Value |
refNumber |
string |
reference number for identifying this quote |
name |
name |
name of quote |
visibility |
array(string) |
Visibility. Subset of ("public", "by_service", "items", "noprices", "time_and_materials", "by_type", "type_detail"). Invalid if provided and empty. Defaults to ("public", "items") if not provided. If "by_service" is set, the results will be grouped by service. If "items" is set, the individual line items on the quote should be displayed to the customer. If "noprices" is set, line items will NOT show pricing and tax to the customer. If "by_type" is set, one summary line item per item type will be shown to customer. If "type_detail" is set along with "by_type", item quantities will be show to customer grouped by item type. |
expiresOn |
integer |
Unix timestamp of quote expiration. |
assignedTo |
integer |
user to whom the quote is assigned. |
salesId |
integer |
user assigned as the salesperson of this quote. |
notes |
string |
description of the work to be done. |
description |
string |
description of the work to be quoted. This is stored on the quote request. |
jobType |
string |
job type that the quote should generate. This is stored on the quote request. One of: unknown, repair, construction, upgrade, service_call, urgent_service_call, priority_service_call, emergency_service_call, cleaning, inspection, priority_inspection, survey, preventative_maintenance, quality_assurance, delivery, pickup, exchange, sales, installation, warranty |
customerPo |
string |
customer-provided purchase order number |
customerPoRequired |
boolean |
Does this quote require a customer PO number in order to be accepted? Defaults to false. |
serviceRequestIds |
array (integer) |
services to be fulfilled on this quote/quote request (services must belong to the provided location) |
contractId |
integer |
contract used to supply price data to this quote |
termsId |
integer |
id for terms object which applies. defaults to your account's default quote terms. null is allowed |
Parameters for approve
Name |
Type |
Required |
Value |
contactId |
integer |
no |
If this quote is approved on behalf of a contact the contact's Id |
signature |
string |
no |
A JSON-encoded array of line segments, each an object with x and y elements that are arrays of coordinates |
Parameters for reject
Name |
Type |
Required |
Value |
details |
string |
no |
The reason the quote was rejected. A comment will be created that will include this information. |
Parameters for requestchanges
Name |
Type |
Required |
Value |
contactId |
integer |
no |
Changes requested on behalf of the given contact. If not provided, the change request will be attributed to the logged-in user. |
details |
string |
no |
Instructions for the requested change. A comment will be created that will include this information. |
Parameters for reopen
Name |
Type |
Required |
Value |
details |
string |
no |
Instructions for the desired change. A comment will be created that will include this information. |
Parameters for submit
Name |
Type |
Required |
Value |
customerPoRequired |
boolean |
no |
Does this quote require a customer PO number in order to be accepted? Defaults to false. |
Parameters for copy
Name |
Type |
Required |
Value |
locationId |
integer |
no |
Assign new quote to this location. If not provided, use the original quote's location. |
customerId |
integer |
no |
Assign new quote to this customer. If not provided, use the original quote's customer. |
copyAttachments |
boolean |
no |
Should attachments be copied to the new quote. Default false. |
copyComments |
boolean |
no |
Should comments be copied to the new quote. Default false. |
Parameters for viewed
Name |
Type |
Required |
Value |
contactId |
integer |
no |
Viewed by the given contact. If not provided, the quote view action will be attributed to the logged-in user. |
Parameters for job
Name |
Type |
Required |
Value |
jobId |
string |
no |
If provided, assign quote to an existing job. If not provided, create a new job. |
copyAttachments |
boolean |
no |
If provided and true, quote attachments are copied to the job |
copyComments |
boolean |
no |
If provided and true, quote comments are copied to the job |
customerPo |
string |
no |
If provided when a job id is not, the new job will be assigned this customerPo |
dueDate |
string |
no |
If provided when a job id is not, the new job will be assigned this due date, and it will cap the window end of each service on the quote |
addBudget |
boolean |
no |
If provided and true, a granular budget in unlocked status will be created on the job from the quote information. |
The job endpoint applies the quote to a new or existing job and then returns that job if successful.
Returned Elements
Name |
Type |
Value |
quotes |
array (object) |
list of quote objects |
id |
string |
quote id |
refNumber |
string |
reference number for identifying this quote |
uri |
string |
resource identifier for the given quote |
name |
string |
quote name |
status |
string |
status of quote |
notes |
string |
description of the work to be done |
customer |
Company |
customer company |
vendor |
Company |
vendor who will provide the work |
location |
Location |
location where the work is to be performed |
deficiencySeverity |
string |
severity of the worst deficiency this quote is meant to fix. One of: null, "suggested", "deficient", "inoperable" |
deficiencyJobs |
array (object) |
jobs on which deficiencies were found that this quote is meant to fix |
respondBy |
integer |
Unix timestamp of day and time by which the quote needs to be submitted |
expiresOn |
integer |
Unix timestamp of day and time until which the quote the is valid |
created |
integer |
Unix timestamp of day and time when the quote was created |
updated |
integer |
Unix timestamp of day and time when the quote was last updated |
subtotal |
string |
total price of quote, not including taxes |
taxAmount |
string |
quote tax amount |
totalPrice |
string |
total price of quote, including taxes |
quoteRequest |
Quote Request |
quoterequest object |
contract |
Contract |
contract used to supply price data to this quote |
assignedTo |
object |
user object |
assignedTo.id |
integer |
user id |
assignedTo.uri |
string |
user resource identifier |
assignedTo.email |
string |
user email address |
assignedTo.legacyId |
integer |
external identifier |
owner |
object |
user object |
owner.uri |
string |
user resource identifier |
owner.id |
integer |
user id |
owner.email |
string |
user email address |
owner.legacyId |
integer |
external identifier |
sales |
User |
user who has been assigned as the salesperson of this quote |
serviceLines |
array (Service Line) |
array of service line objects |
jobs |
array (Job) |
array of jobs that will fulfill the services on this quote |
visibility |
array (string) |
visibility options, a subset of ("public", "by_service", "items", "noprices", "time_and_materials", "by_type", "type_detail"), empty implies private |
tags |
array (Tag) |
array of tags |
customerPo |
string |
customer purchase order number associated with this quote |
description |
string |
quote request description |
jobType |
string |
job type specified by quote request |
serviceRequests |
array (Service Request) |
service requests to be fulfilled on this quote |
terms |
Terms |
terms and conditions of this quote |
externalIds |
object |
a key/value object of external system ids, only returned if quote has external integrations defined |
assignedOffice |
Location |
office the quote is assigned to |
Retrieve all quotes that match a given status
GET /quote?status=draft
200
{
"data": {
"totalPages": 1,
"page": 1,
"quotes": [
{
"uri": "https://api.servicetrade.com/api/quote/2",
"id": 2,
"refNumber": "2",
"name": "Q-102",
"notes": "how do you like this one?",
"customer": {
"id": 2,
"name": "Belk",
"uri": "https://api.servicetrade.com/api/company/2",
"status": "active"
},
"vendor": {
"id": 9,
"name": "Super Awesome Company, Inc",
"uri": "https://api.servicetrade.com/api/company/9",
"status": "active"
},
"location": {
"id": 8,
"uri": "https://api.servicetrade.com/api/location/8",
"legacyId": 4567,
"name": "Belk #401 Winder",
"lat": 33.943941,
"lon": -83.756069,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "916 Loganville, Highway, Suite 100",
"city": "Winder",
"state": "GA",
"postalCode": "30620"
},
"taxable": false,
"status": "active"
},
"deficiencySeverity": "deficient",
"deficiencyJobs": [
{
"id": 19,
"uri": "https://api.servicetrade.com/api/job/19",
"number": 133247,
"type": "inspection",
"name": "Inspection Job #133247"
}
],
"status": "draft",
"respondBy": 1309795200,
"expiresOn": 1309994373,
"created": 1307611510
"updated": 1347915466,
"subtotal": "102.00",
"taxAmount": "0.00",
"totalPrice": "102.00",
"quoteRequest": {
"uri": "https://api.servicetrade.com/api/quoterequest/12",
"id": 12,
"name": "QR-112",
"status": "quote_received",
"type": "advanced"
},
"contract": null,
"assignedTo": {
"uri": "https://api.servicetrade.com/api/user/3",
"id": 3,
"email": "bob@testcompany.com",
"legacyId": null
},
"owner": {
"uri": "https://api.servicetrade.com/api/user/21",
"id": 21,
"email": "steve@testcompany.com",
"legacyId": null
},
"sales": {
"uri": "https://api.servicetrade.com/api/user/28",
"id": 28,
"email": "sammy.sales@testcompany.com",
},
"serviceLines": [
{
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/SUPP.png",
"abbr": "SUPP",
"abbreviation": "SUPP"
}
],
"jobs": [],
"visibility": ["public", "items"],
"items": [],
"tags": [],
"customerPo": null,
"customerPoRequired": false,
"description": "make repairs",
"jobType": "repair",
"serviceRequests": [
{
"id": 5765,
"uri": "https://api.servicetrade.com/api/servicerequest/55",
"name": "make the needed repair"
}
],
"terms": {
"id": 334,
"uri": "https://api.servicetrade.com/api/terms/334",
"name": "Basic Terms"
},
"externalIds": {
"ABC-1234": "this is external ID"
}
},
{
"uri": "https://api.servicetrade.com/api/quote/3",
"id": 3,
"refNumber": "3",
"name": "Q-103",
"notes": "please let me know soon",
"customer": {
"id": 2,
"name": "Belk",
"uri": "https://api.servicetrade.com/api/company/2",
"status": "active"
},
"vendor": {
"id": 16,
"name": "Dragon Fire Systems",
"uri": "https://api.servicetrade.com/api/company/16",
"status": "active"
},
"location": {
"id": 8,
"uri": "https://api.servicetrade.com/api/location/8",
"legacyId": 4567,
"name": "Belk #401 Winder",
"lat": 33.943941,
"lon": -83.756069,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "916 Loganville, Highway, Suite 100",
"city": "Winder",
"state": "GA",
"postalCode": "30620"
},
"taxable": false,
"status": "active"
},
"deficiencySeverity": null,
"deficiencyJobs": [],
"status": "draft",
"respondBy": 1309795200,
"expiresOn": 1309994373,
"created": 1307611510
"updated": 1347915466,
"subtotal": "100.00",
"taxAmount": "3.00",
"totalPrice": "103.00",
"quoteRequest": {
"uri": "https://api.servicetrade.com/api/quoterequest/17",
"id": 17,
"name": "QR-117",
"status": "quote_received"
},
"contract": null,
"assignedTo": null,
"owner": {
"uri": "https://api.servicetrade.com/api/user/21",
"id": 21,
"email": "steve@testcompany.com",
"legacyId": null
},
"sales": null,
"serviceLines": [
{
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/SUPP.png",
"abbr": "SUPP",
"abbreviation": "SUPP"
}
],
"jobs": [],
"visibility": ["public", "items"],
"items": [],
"tags": [],
"customerPo": null,
"customerPoRequired": false,
"description": "make repairs",
"jobType": "repair",
"serviceRequests": [
{
"id": 5765,
"uri": "https://api.servicetrade.com/api/servicerequest/55",
"name": "make the needed repair"
}
],
"terms": {
"id": 334,
"uri": "https://api.servicetrade.com/api/terms/334",
"name": "Basic Terms"
},
"externalIds": {
"ABC-1234": "this is external ID"
},
"assignedOffice": {
"id": 69,
"uri": "https://api.servicetrade.com/api/location/69",
"name": "StandAlone Satellite Office",
"legacyId": null,
"lat": 35.611172,
"lon": -78.060822,
"phoneNumber": "(919) 555-0002",
"email": "uuxiiuit+location@gmail.com",
"primaryContact": null,
"address": {
"street": "8071 Newsome Mill Rd",
"city": "Lucama",
"state": "NC",
"postalCode": "27851"
},
"taxable": false
}
}
]
}
}
No quote matches found
GET /quote?name=kjghikjgug
200
{
"data": {
"totalPages": 1,
"page": 1,
"quotes": []
}
}
Retrieve information for a single quote
GET /quote/2
200
{
"data": {
"uri": "https://api.servicetrade.com/api/quote/2",
"id": 2,
"refNumber": "2",
"name": "Q-102",
"notes": "how do you like this one?",
"customer": {
"id": 2,
"name": "Belk",
"uri": "https://api.servicetrade.com/api/company/2",
"status": "active"
},
"vendor": {
"id": 9,
"name": "Super Awesome Company, Inc",
"uri": "https://api.servicetrade.com/api/company/9",
"status": "active"
},
"location": {
"id": 8,
"uri": "https://api.servicetrade.com/api/location/8",
"legacyId": 4567,
"name": "Belk #401 Winder",
"lat": 33.943941,
"lon": -83.756069,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "916 Loganville, Highway, Suite 100",
"city": "Winder",
"state": "GA",
"postalCode": "30620"
},
"taxable": false,
"status": "active"
},
"deficiencySeverity": "deficient",
"deficiencyJobs": [
{
"id": 19,
"uri": "https://api.servicetrade.com/api/job/19",
"number": 133247,
"type": "inspection",
"name": "Inspection Job #133247"
}
],
"status": "draft",
"respondBy": 1309795200,
"expiresOn": 1309994373,
"created": 1307611510,
"updated": 1347971216,
"subtotal": "102.00",
"taxAmount": "0.00",
"totalPrice": "102.00",
"quoteRequest": {
"uri": "https://api.servicetrade.com/api/quoterequest/12",
"id": 12,
"name": "QR-112",
"status": "quote_received",
"type": "advanced"
},
"contract": null,
"assignedTo": {
"uri": "https://api.servicetrade.com/api/user/3",
"id": 3,
"email": "bob@testcompany.com",
"legacyId": null
},
"owner": {
"uri": "https://api.servicetrade.com/api/user/21",
"id": 21,
"email": "steve@testcompany.com",
"legacyId": null
},
"sales": null,
"serviceLines": [],
"jobs": [],
"visibility": ["public", "items"],
"items": [],
"tags": [],
"customerPo": null,
"customerPoRequired": false,
"description": "make repairs",
"jobType": "repair",
"serviceRequests": [
{
"id": 5765,
"uri": "https://api.servicetrade.com/api/servicerequest/55",
"name": "make the needed repair"
}
],
"terms": {
"id": 334,
"uri": "https://api.servicetrade.com/api/terms/334",
"name": "Basic Terms"
},
"externalIds": {
"ABC-1234": "this is external ID"
},
"assignedOffice": {
"id": 69,
"uri": "https://api.servicetrade.com/api/location/69",
"name": "StandAlone Satellite Office",
"legacyId": null,
"lat": 35.611172,
"lon": -78.060822,
"phoneNumber": "(919) 555-0002",
"email": "uuxiiuit+location@gmail.com",
"primaryContact": null,
"address": {
"street": "8071 Newsome Mill Rd",
"city": "Lucama",
"state": "NC",
"postalCode": "27851"
},
"taxable": false
}
}
}
Return all open or draft quotes for a specific vendor, sort oldest to newest created
GET /api/quote?vendorId=9&status=new,draft&sort=created&sortOrder=DESC
200
{
"data": {
"totalPages": 1,
"page": 1,
"quotes": [
{
"uri": "https://api.servicetrade.com/api/quote/2",
"id": 2,
"refNumber": "2",
"name": "Q-102",
"notes": "how do you like this one?",
"customer": {
"id": 2,
"name": "Belk",
"uri": "https://api.servicetrade.com/api/company/2",
"status": "active"
},
"vendor": {
"id": 9,
"name": "Super Awesome Company, Inc",
"uri": "https://api.servicetrade.com/api/company/9",
"status": "active"
},
"location": {
"id": 8,
"uri": "https://api.servicetrade.com/api/location/8",
"legacyId": 4567,
"name": "Belk #401 Winder",
"lat": 33.943941,
"lon": -83.756069,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "916 Loganville, Highway, Suite 100",
"city": "Winder",
"state": "GA",
"postalCode": "30620"
},
"taxable": false,
"status": "active"
},
"deficiencySeverity": "deficient",
"deficiencyJobs": [
{
"id": 19,
"uri": "https://api.servicetrade.com/api/job/19",
"number": 133247,
"type": "inspection",
"name": "Inspection Job #133247"
}
],
"status": "draft",
"respondBy": 1309795200,
"expiresOn": 1309994373,
"created": 1307611510
"updated": 1406562350,
"subtotal": "102.00",
"taxAmount": "0.00",
"totalPrice": "102.00",
"quoteRequest": {
"uri": "https://api.servicetrade.com/api/quoterequest/12",
"id": 12,
"name": "QR-112",
"status": "quote_received",
"type": "advanced"
},
"contract": null,
"assignedTo": {
"uri": "https://api.servicetrade.com/api/user/3",
"id": 3,
"email": "bob@testcompany.com",
"legacyId": null
},
"owner": {
"uri": "https://api.servicetrade.com/api/user/21",
"id": 21,
"email": "steve@testcompany.com",
"legacyId": null
},
"sales": null,
"serviceLines": [],
"jobs": [],
"visibility": ["public", "items"],
"items": [],
"tags": [],
"customerPo": null,
"customerPoRequired": false,
"description": "make repairs",
"jobType": "repair",
"serviceRequests": [
{
"id": 5765,
"uri": "https://api.servicetrade.com/api/servicerequest/55",
"name": "make the needed repair"
}
],
"terms": {
"id": 334,
"uri": "https://api.servicetrade.com/api/terms/334",
"name": "Basic Terms"
},
"externalIds": {
"ABC-1234": "this is external ID"
},
"assignedOffice": {
"id": 69,
"uri": "https://api.servicetrade.com/api/location/69",
"name": "StandAlone Satellite Office",
"legacyId": null,
"lat": 35.611172,
"lon": -78.060822,
"phoneNumber": "(919) 555-0002",
"email": "uuxiiuit+location@gmail.com",
"primaryContact": null,
"address": {
"street": "8071 Newsome Mill Rd",
"city": "Lucama",
"state": "NC",
"postalCode": "27851"
},
"taxable": false
},
},
{
"uri": "https://api.servicetrade.com/api/quote/6",
"id": 6,
"refNumber": "6",
"name": "Q-401",
"notes": "",
"customer": {
"id": 7,
"name": "Red Robin International",
"uri": "https://api.servicetrade.com/api/company/7",
"status": "active"
},
"vendor": {
"id": 9,
"name": "Super Awesome Company, Inc",
"uri": "https://api.servicetrade.com/api/company/9",
"status": "active"
},
"location": {
"id": 31,
"uri": "https://api.servicetrade.com/api/location/31",
"legacyId": 4567,
"name": "Red Robin #667 - Columbia",
"lat": 34.130338,
"lon": -80.875458,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "247 Forum Drive",
"city": "Columbia",
"state": "SC",
"postalCode": "29229"
}
"taxable": false,
"status": "active"
},
"deficiencySeverity": "inoperable",
"deficiencyJobs": [
{
"id": 587,
"uri": "https://api.servicetrade.com/api/job/587",
"number": 985750,
"type": "inspection",
"name": "Inspection Job #985750"
}
],
"status": "new",
"respondBy": 1309795200,
"expiresOn": 1309994373,
"created": 1307611510
"updated": 1406562341,
"subtotal": "0.00",
"taxAmount": "0.00",
"totalPrice": "0.00",
"quoteRequest": {
"uri": "https://api.servicetrade.com/api/quoterequest/32",
"id": 32,
"name": "QR-320",
"status": "quote_received",
"type": "advanced"
},
"contract": null,
"assignedTo": null,
"owner": {
"uri": "https://api.servicetrade.com/api/user/21",
"id": 21,
"email": "steve@testcompany.com",
"legacyId": null
},
"sales": null,
"serviceLines": [],
"jobs": [],
"visibility": ["public", "items"],
"items": [],
"tags": [],
"customerPo": null,
"customerPoRequired": false,
"description": "make repairs",
"jobType": "repair",
"serviceRequests": [
{
"id": 5765,
"uri": "https://api.servicetrade.com/api/servicerequest/55",
"name": "make the needed repair"
}
],
"terms": {
"id": 334,
"uri": "https://api.servicetrade.com/api/terms/334",
"name": "Basic Terms"
},
"externalIds": {
"ABC-1234": "this is external ID"
},
"assignedOffice": {
"id": 69,
"uri": "https://api.servicetrade.com/api/location/69",
"name": "StandAlone Satellite Office",
"legacyId": null,
"lat": 35.611172,
"lon": -78.060822,
"phoneNumber": "(919) 555-0002",
"email": "uuxiiuit+location@gmail.com",
"primaryContact": null,
"address": {
"street": "8071 Newsome Mill Rd",
"city": "Lucama",
"state": "NC",
"postalCode": "27851"
},
"taxable": false
},
}
]
}
}
Return all submitted quotes for a specific customer, sort oldest to newest updated
GET /api/quote?vendorId=9&status=submitted&sort=updated&sortOrder=DESC
200
{
"data": {
"totalPages": 1,
"page": 1,
"quotes": [
{
"uri": "https://api.servicetrade.com/api/quote/4",
"id": 4,
"refNumber": "4",
"name": "Q-201",
"notes": "we will do a great job",
"customer": {
"id": 2,
"name": "Belk",
"uri": "https://api.servicetrade.com/api/company/2",
"status": "active"
},
"vendor": {
"id": 9,
"name": "Super Awesome Company, Inc",
"uri": "https://api.servicetrade.com/api/company/9",
"status": "active"
},
"location": {
"id": 10,
"uri": "https://api.servicetrade.com/api/location/10",
"legacyId": 4567,
"name": "Belk #54 - Georgia Square",
"lat": 33.940828,
"lon": -83.45787,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "3700-175 Atlanta Highway",
"city": "Athens",
"state": "GA",
"postalCode": "30606"
}
"taxable": false,
"status": "active"
},
"deficiencySeverity": "suggested",
"deficiencyJobs": [
{
"id": 783,
"uri": "https://api.servicetrade.com/api/job/783",
"number": 421546,
"type": "inspection",
"name": "Inspection Job #421546"
}
],
"status": "submitted",
"respondBy": 1309795200,
"expiresOn": 1309994373,
"created": 1307611510
"updated": 1406562341,
"subtotal": "190.00",
"taxAmount": "11.00",
"totalPrice": "201.00",
"quoteRequest": {
"uri": "https://api.servicetrade.com/api/quoterequest/55",
"id": 55,
"name": "QR-545",
"status": "quote_received",
"type": "advanced"
},
"contract": null,
"assignedTo": null,
"owner": {
"uri": "https://api.servicetrade.com/api/user/21",
"id": 21,
"email": "steve@testcompany.com",
"legacyId": null
},
"sales": null,
"serviceLines": [],
"jobs": [],
"visibility": ["public", "items"],
"items": [],
"tags": [],
"customerPo": null,
"customerPoRequired": false,
"description": "make repairs",
"jobType": "repair",
"serviceRequests": [
{
"id": 5765,
"uri": "https://api.servicetrade.com/api/servicerequest/55",
"name": "make the needed repair"
}
],
"terms": {
"id": 334,
"uri": "https://api.servicetrade.com/api/terms/334",
"name": "Basic Terms"
},
"externalIds": {
"ABC-1234": "this is external ID"
},
"assignedOffice": {
"id": 69,
"uri": "https://api.servicetrade.com/api/location/69",
"name": "StandAlone Satellite Office",
"legacyId": null,
"lat": 35.611172,
"lon": -78.060822,
"phoneNumber": "(919) 555-0002",
"email": "uuxiiuit+location@gmail.com",
"primaryContact": null,
"address": {
"street": "8071 Newsome Mill Rd",
"city": "Lucama",
"state": "NC",
"postalCode": "27851"
},
"taxable": false
},
}
]
}
}
Retrieve information for a location which does not exist
GET /quote/987
404
Example of filtering by user id, returns quotes assigned to this user and all unassigned quotes
GET /quote?vendorId=9&customerId=2&userId=3
200
{
"data": {
"totalPages": 1,
"page": 1,
"quotes": [
{
"uri": "https://api.servicetrade.com/api/quote/2",
"id": 2,
"refNumber": "2",
"name": "Q-102",
"notes": "how do you like this one?",
"customer": {
"id": 2,
"name": "Belk",
"uri": "https://api.servicetrade.com/api/company/2",
"status": "active"
},
"vendor": {
"id": 9,
"name": "Super Awesome Company, Inc",
"uri": "https://api.servicetrade.com/api/company/9",
"status": "active"
},
"location": {
"id": 8,
"uri": "https://api.servicetrade.com/api/location/8",
"legacyId": 4567,
"name": "Belk #401 Winder",
"lat": 33.943941,
"lon": -83.756069,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "916 Loganville, Highway, Suite 100",
"city": "Winder",
"state": "GA",
"postalCode": "30620"
},
"taxable": false,
"status": "active"
},
"deficiencySeverity": "deficient",
"deficiencyJobs": [
{
"id": 19,
"uri": "https://api.servicetrade.com/api/job/19",
"number": 133247,
"type": "inspection",
"name": "Inspection Job #133247"
}
],
"status": "draft",
"respondBy": 1309795200,
"expiresOn": 1309994373,
"created": 1307611510
"updated": 1406562341,
"subtotal": "102.00",
"taxAmount": "0.00",
"totalPrice": "102.00",
"quoteRequest": {
"uri": "https://api.servicetrade.com/api/quoterequest/12",
"id": 12,
"name": "QR-112",
"status": "quote_received",
"type": "advanced"
},
"contract": null,
"assignedTo": {
"uri": "https://api.servicetrade.com/api/user/3",
"id": 3,
"email": "bob@testcompany.com",
"legacyId": null
},
"owner": {
"uri": "https://api.servicetrade.com/api/user/21",
"id": 21,
"email": "steve@testcompany.com",
"legacyId": null
},
"sales": null,
"serviceLines": [],
"jobs": [],
"visibility": ["public", "items"],
"items": [],
"tags": [],
"customerPo": null,
"customerPoRequired": false,
"description": "make repairs",
"jobType": "repair",
"serviceRequests": [
{
"id": 5765,
"uri": "https://api.servicetrade.com/api/servicerequest/55",
"name": "make the needed repair"
}
],
"terms": {
"id": 334,
"uri": "https://api.servicetrade.com/api/terms/334",
"name": "Basic Terms"
},
"externalIds": {
"ABC-1234": "this is external ID"
},
"assignedOffice": {
"id": 69,
"uri": "https://api.servicetrade.com/api/location/69",
"name": "StandAlone Satellite Office",
"legacyId": null,
"lat": 35.611172,
"lon": -78.060822,
"phoneNumber": "(919) 555-0002",
"email": "uuxiiuit+location@gmail.com",
"primaryContact": null,
"address": {
"street": "8071 Newsome Mill Rd",
"city": "Lucama",
"state": "NC",
"postalCode": "27851"
},
"taxable": false
},
},
{
"uri": "https://api.servicetrade.com/api/quote/4",
"id": 4,
"refNumber": "4",
"name": "Q-201",
"notes": "we will do a great job",
"customer": {
"id": 2,
"name": "Belk",
"uri": "https://api.servicetrade.com/api/company/2",
"status": "active"
},
"vendor": {
"id": 9,
"name": "Super Awesome Company, Inc",
"uri": "https://api.servicetrade.com/api/company/9",
"status": "active"
},
"location": {
"id": 10,
"uri": "https://api.servicetrade.com/api/location/10",
"legacyId": 4567,
"name": "Belk #54 - Georgia Square",
"lat": 33.940828,
"lon": -83.45787,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "3700-175 Atlanta Highway",
"city": "Athens",
"state": "GA",
"postalCode": "30606"
},
"taxable": false,
"status": "active"
},
"deficiencySeverity": null,
"deficiencyJobs": [],
"status": "submitted",
"respondBy": 1309795200,
"expiresOn": 1309994373,
"created": 1307611510
"updated": 1409533100,
"subtotal": "190.00",
"taxAmount": "11.00",
"totalPrice": "201.00",
"quoteRequest": {
"uri": "https://api.servicetrade.com/api/quoterequest/55",
"id": 55,
"name": "QR-545",
"status": "quote_received",
"type": "advanced"
},
"assignedTo": null,
"serviceLines": [],
"jobs": [],
"visibility": ["public", "items"],
"items": [],
"tags": [],
"customerPo": null,
"customerPoRequired": false,
"description": "make repairs",
"jobType": "repair",
"serviceRequests": [
{
"id": 5765,
"uri": "https://api.servicetrade.com/api/servicerequest/55",
"name": "make the needed repair"
}
],
"terms": {
"id": 334,
"uri": "https://api.servicetrade.com/api/terms/334",
"name": "Basic Terms"
},
"externalIds": {
"ABC-1234": "this is external ID"
},
"assignedOffice": {
"id": 69,
"uri": "https://api.servicetrade.com/api/location/69",
"name": "StandAlone Satellite Office",
"legacyId": null,
"lat": 35.611172,
"lon": -78.060822,
"phoneNumber": "(919) 555-0002",
"email": "uuxiiuit+location@gmail.com",
"primaryContact": null,
"address": {
"street": "8071 Newsome Mill Rd",
"city": "Lucama",
"state": "NC",
"postalCode": "27851"
},
"taxable": false
}
}
]
}
}
Example of POSTing a new quote and simple quote request pair
POST /quote
{"vendorId":34, "locationId":80, "name":"Important Quote", "jobType":"repair", "serviceRequestIds":[78], "description":"repair it"}
200
{
"data": {
"id": 953,
"refNumber": "2",
"uri": "https://api.servicetrade.com/api/quote/953",
"name": "Important Quote",
"status": "new",
"notes": "",
"customer": {
"id": 36,
"uri": "https://api.servicetrade.com/api/company/36",
"name": "Hwy 55 Burgers",
"status": "active"
},
"vendor": {
"id": 34,
"uri": "https://api.servicetrade.com/api/company/34",
"name": "StandAlone Safety",
"status": "active"
},
"location": {
"id": 80,
"uri": "https://api.servicetrade.com/api/location/80",
"name": "Hwy 55 Burgers - Knightdale",
"legacyId": null,
"lat": 35.741073,
"lon": -78.445495,
"phoneNumber": "(919) 555-9841",
"email": "knightdale@burg55.us",
"primaryContact": {
"id": 80,
"uri": "https://api.servicetrade.com/api/contact/80",
"firstName": "Steve",
"lastName": "Blake",
"phone": "919-555-9841",
"mobile": "",
"alternatePhone": "",
"email": "knightdale-manager@burg55.us",
"type": "management"
},
"address": {
"street": "1011 Smithfield Road",
"city": "Knightdale",
"state": "NC",
"postalCode": "28545"
},
"taxable": false,
"status": "active"
},
"deficiencySeverity": null,
"deficiencyJobs": [],
"respondBy": null,
"expiresOn": null,
"created": 1458051032,
"updated": 1458051032,
"subtotal": "0.00",
"taxAmount": "0.00",
"totalPrice": "0.00",
"quoteRequest": {
"id": 977,
"uri": "https://api.servicetrade.com/api/quoterequest/977",
"name": "Important Quote",
"status": "waiting",
"type": "simple"
},
"contract": null,
"assignedTo": null,
"owner": {
"uri": "https://api.servicetrade.com/api/user/21",
"id": 21,
"email": "steve@testcompany.com",
"legacyId": null
},
"sales": null,
"serviceLines": [
{
"id": 1,
"name": "Alarm Systems",
"trade": "Fire Protection",
"abbr": "AL",
"icon": "https://api.servicetrade.com/image/icons/service_lines/32/AL.png",
"abbreviation": "AL"
}
],
"jobs": [
{
"id": 68,
"uri": "https://api.servicetrade.com/api/job/68",
"number": 10300024,
"name": "Installation Job #10300024",
"type": "installation"
}
],
"visibility": [
"public",
"items"
],
"items": [],
"tags": [],
"customerPo": null,
"customerPoRequired": false,
"description": "repair it",
"jobType": "repair",
"serviceRequests": [
{
"id": 78,
"uri": "https://api.servicetrade.com/api/servicerequest/78",
"description": "Inspect range reduction stereoptics"
}
],
"terms": {
"id": 334,
"uri": "https://api.servicetrade.com/api/terms/334",
"name": "Basic Terms"
}
}
}
Example of PUTing changes to a quote
PUT /quote/2
{"notes": "Test alarm system"}
200
{
"data": {
"uri": "https://api.servicetrade.com/api/quote/2",
"id": 2,
"refNumber": "2",
"name": "Q-102",
"notes": "Test alarm system",
"customer": {
"id": 2,
"name": "Belk",
"uri": "https://api.servicetrade.com/api/company/2",
"status": "active"
},
"vendor": {
"id": 9,
"name": "Super Awesome Company, Inc",
"uri": "https://api.servicetrade.com/api/company/9",
"status": "active"
},
"location": {
"id": 8,
"uri": "https://api.servicetrade.com/api/location/8",
"legacyId": 4567,
"name": "Belk #401 Winder",
"legacyId": null,
"lat": 33.943941,
"lon": -83.756069,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "916 Loganville, Highway, Suite 100",
"city": "Winder",
"state": "GA",
"postalCode": "30620"
},
"taxable": false,
"status": "active"
},
"deficiencySeverity": "deficient",
"deficiencyJobs": [
{
"id": 19,
"uri": "https://api.servicetrade.com/api/job/19",
"number": 133247,
"type": "inspection",
"name": "Inspection Job #133247"
}
],
"status": "draft",
"respondBy": 1309795200,
"expiresOn": 1309994373,
"created": 1307611510,
"updated": 1347971216,
"subtotal": "102.00",
"taxAmount": "0.00",
"totalPrice": "102.00",
"quoteRequest": {
"uri": "https://api.servicetrade.com/api/quoterequest/12",
"id": 12,
"name": "QR-112",
"status": "quote_received",
"type": "advanced"
},
"contract": null,
"assignedTo": {
"uri": "https://api.servicetrade.com/api/user/3",
"id": 3,
"email": "bob@testcompany.com",
"legacyId": null
},
"owner": {
"uri": "https://api.servicetrade.com/api/user/21",
"id": 21,
"email": "steve@testcompany.com",
"legacyId": null
},
"sales": null,
"serviceLines": [],
"jobs": [],
"visibility": ["public", "items"],
"items": [],
"tags": [],
"customerPo": null,
"customerPoRequired": false,
"description": "make repairs",
"jobType": "repair",
"serviceRequests": [
{
"id": 5765,
"uri": "https://api.servicetrade.com/api/servicerequest/55",
"name": "make the needed repair"
}
]
"terms": {
"id": 334,
"uri": "https://api.servicetrade.com/api/terms/334",
"name": "Basic Terms"
}
}
}
Return to Top
Quote Item
Retrieve or modify line items related to a quote.
- Resource URL: /quote/[quoteId]/item/[itemId]
- Resource URL: /quoteitem/[itemId]
- Available Verbs: GET, POST, PUT, DELETE
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/quote/123/item |
200 |
|
GET |
/quoteitem?quoteId=123 |
200 |
|
GET |
/quote/123/item/456 |
200 |
|
GET |
/quoteitem/456 |
200 |
|
GET |
/quote/123/item/456 |
404 |
quote 123 not found, or quote item 456 not found on quote 123 |
GET |
/quoteitem/456 |
404 |
quote item 456 not found |
GET |
/quoteitem |
404 |
quoteId must be specified when searching for quote items |
POST |
/quoteitem |
200 |
|
POST |
/quote/123/item |
200 |
|
POST |
/quote/123/item |
400 |
parameters invalid |
POST |
/quote/123/item |
403 |
do not have permission to modify quote 123 |
POST |
/quote/123/item |
404 |
quote 123 not found |
PUT |
/quoteitem/456 |
200 |
|
PUT |
/quote/123/item/456 |
200 |
|
PUT |
/quote/123/item/456 |
400 |
parameters invalid |
PUT |
/quote/123/item/456 |
403 |
do not have permission to modify quote 123 |
PUT |
/quote/123/item/456 |
404 |
quote 123 not found |
DELETE |
/quote/123/item/456 |
403 |
do not have permission to modify quote 123 |
DELETE |
/quote/123/item/456 |
404 |
quote 123 not found |
DELETE |
/quote/123/item/456 |
204 |
quote item deleted |
Query Params
Name |
Type |
Value |
quoteId |
integer |
quote to which this item belongs. Required. |
POST/PUT Parameters
Name |
Type |
Required |
Value |
quoteId |
integer |
yes |
sets the quote to which this item belongs |
quantity |
float |
yes |
how many units of this item are being charged on this line |
price |
float |
yes |
the unit price being charged for this line item |
taxRate |
float |
no |
tax rate for this line item |
cost |
float |
no |
cost of this item, can be null |
description |
string |
if no libItem |
item description |
libItemId |
integer |
if no description |
libitem that this item is an instance of |
serviceLineId |
integer |
if no libItem or libItem has no service line |
id of the service line |
serviceRequestId |
integer |
no |
id of the service request the quote item is associated with, if any |
orderIndex |
integer |
no |
items are listed from low to high value, null is the default value |
Returned Elements
Name |
Type |
Value |
items |
array (Quote Item) |
list of quoteitem objects |
libItem |
Libitem |
libItem of the service item |
serviceLine |
Service Line |
serviceLine of the service item |
serviceRequest |
Service Request |
serviceLine of the service item |
quote |
Quote |
quote to which this item belongs |
price |
float |
unit price of the service item |
quantity |
float |
quantity of the service item |
taxRate |
float |
quantity of the service item |
cost |
float |
cost of this item, or null |
Retrieve all quote items for a given quote
GET /quote/45/item
GET /quoteitem?quoteId=45
200
{
"data": {
"totalPages": 1,
"page": 1,
"items": [
{
"id": 11,
"uri": "https://api.servicetrade.com/api/quoteitem/11",
"description": "Towel",
"quantity": 1,
"price": 100.00,
"taxRate": 7.5,
"cost": null,
"quote": {
"id": 45,
"uri": "https://api.servicetrade.com/api/quote/45",
"name": "Quote #3230004-SQKY-CLN"
},
"libItem": {
"id": 408,
"uri": "https://api.servicetrade.com/api/libitem/408",
"name": "Personal Item",
"type": "Part",
"code": "PERSONAL"
},
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/SUPP.png"
},
"serviceRequest": {
"id": 1742,
"uri": "https://api.servicetrade.com/api/servicerequest/1742",
"description": "Semi-Annual Preventative Maintenance"
}
},
{
"id": 13,
"uri": "https://api.servicetrade.com/api/quoteitem/13",
"description": "Unknown Charge",
"quantity": 2,
"price": 100.00,
"taxRate": 7.5,
"cost": null,
"quote": {
"id": 45,
"uri": "https://api.servicetrade.com/api/quote/45",
"name": "Quote #3230004-SQKY-CLN"
},
"libItem": {
"id": 283,
"uri": "https://api.servicetrade.com/api/libitem/283",
"name": "Other",
"type": "Other",
"code": "OTHER-UNK"
},
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/SUPP.png"
},
"serviceRequest": null
}
]
}
}
No items found on quote
GET /quote/78/item
200
{
"data": {
"totalPages": 1,
"page": 1,
"items": []
}
}
Retrieve information for a single quote item
GET /quoteitem/11
200
{
"data": {
"id": 11,
"uri": "https://api.servicetrade.com/api/quoteitem/11",
"description": "Towel",
"quantity": 2,
"price": 100.00,
"taxRate": 7.5,
"cost": null,
"quote": {
"id": 45,
"uri": "https://api.servicetrade.com/api/quote/45",
"name": "Quote #3230004-SQKY-CLN"
},
"libItem": {
"id": 408,
"uri": "https://api.servicetrade.com/api/libitem/408",
"name": "Personal Item",
"type": "Part",
"code": "PERSONAL"
},
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/SUPP.png"
},
"serviceRequest": null
}
}
Add an item to an quote
POST /quote/78/item
{"description":"CCW Zirconium Flange","quantity":3,"price":24.00,"cost":16.25}
200
{
"data": {
"id": 13,
"uri": "https://api.servicetrade.com/api/quoteitem/13",
"description": "CCW Zirconium Flange",
"quantity": 2,
"price": 100.00,
"taxRate": null,
"cost": 16.25,
"quote": {
"id": 78,
"uri": "https://api.servicetrade.com/api/quote/78",
"name": "Quote #7721402-WAH"
},
"libItem": {
"id": 471,
"uri": "https://api.servicetrade.com/api/libitem/471",
"name": "CCW Zirconium Flange",
"type": "Part",
"code": "CCW-ZC-FLNG"
},
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/SUPP.png"
},
"serviceRequest": null
}
}
Return to Top
QuoteRequest
The quoterequest resource is used to retrieve lists of quote requests. A quote request may be associated with one or more quotes which "respond" to that quote request, and the status of a quote request is affected by the status of its associated quotes. A quote request may be associated with a parent quote to support complex subcontracted quote situations.
When a quote is created without being associated with an existing quote request, a new quote request is automatically created for that quote, and the resulting quote request has a type of "simple".
More information is available in the documentation for the quote resource.
- Resource URL: /quoterequest/
- Available Verbs: GET
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/quoterequest |
200 |
|
GET |
/quoterequest/123 |
200 |
|
GET |
/quoterequest/123 |
404 |
not found or user does not have permission to view |
POST |
|
405 |
not allowed |
PUT |
|
405 |
not allowed |
DELETE |
|
405 |
not allowed |
Query Params
Name |
Type |
Value |
locationId |
integer |
return only quote requests that apply to this location |
vendorId |
integer |
return only quote requests where the parent quote's vendor has this company id |
quoteStatus |
string |
Comma separated list of statuses, return only quote requests with parent quotes whose status is in this list |
status |
string |
Comma separated list of statuses, return only quote requests whose status is in this list |
Returned Elements
Name |
Type |
Value |
quoterequests |
array (object) |
list of quoterequest objects |
id |
integer |
quote request id |
uri |
string |
resource identifier for the given quote request |
title |
string |
quote request title |
description |
string |
detailed description of the quote request |
status |
string |
status of quote request |
respondBy |
integer |
unix timestamp of day and time by which the quote needs to be submitted |
redTag |
boolean |
DEPRECATED whether the deficiency for this request is a red tag or not |
company |
Company |
company managing the quoting process |
location |
Location |
location where the quoted work will take place |
serviceRequests |
array (Service Request) |
list of services to be completed |
quotes |
array (Quote) |
list of child quote objects |
parentQuote |
Quote |
parent quote object, or null if there isn't one |
type |
string |
type of quote request: "simple" or "advanced" |
quoteStatus |
string |
status of parent quote, or null if there isn't one |
Retrieve all quote requests that match a given request status and location
GET /quoterequest?status=waiting&locationId=8
200
{
"data": {
"totalPages": 1,
"page": 1,
"quoterequests": [
{
"uri": "https://api.servicetrade.com/api/quoterequest/1",
"id": 1,
"title": "QR-001",
"description": "fix stuff at Belk",
"company": {
"id": 2,
"name": "Belk",
"uri": "https://api.servicetrade.com/api/company/2"
},
"location": {
"id": 8,
"uri": "https://api.servicetrade.com/api/location/8",
"legacyId": 4567,
"name": "Belk #401 Winder",
"lat": 33.943941,
"lon": -83.756069,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "916 Loganville, Highway, Suite 100",
"city": "Winder",
"state": "GA",
"postalCode": "30620"
},
"taxable": false,
"status": "active"
},
"serviceRequests": [
{
"id": 11,
"uri": "https://api.servicetrade.com/api/servicerequest/11",
"name": ""
}
],
"status": "waiting",
"respondBy": 1309795200,
"redTag": false,
"quotes": [
{
"id": 1,
"uri": "https://api.servicetrade.com/api/quote/1",
"name": "Q-101",
"status": "rejected"
},
{
"id": 2,
"uri": "https://api.servicetrade.com/api/quote/2",
"name": "Q-102",
"status": "draft"
},
{
"id": 3,
"uri": "https://api.servicetrade.com/api/quote/3",
"name": "Q-103",
"status": "draft"
}
],
"parentQuote": null,
"type": "simple,
"quoteStatus": "draft"
}
]
}
}
No quote matches found
GET /quoterequest?vendorId=9999999
200
{
"data": {
"totalPages": 1,
"page": 1,
"quoterequests": []
}
}
Retrieve a single quote request
GET /quoterequest/1
200
{
"data": {
"uri": "https://api.servicetrade.com/api/quoterequest/1",
"id": 1,
"title": "QR-001",
"description": "fix stuff at Belk",
"company": {
"id": 2,
"name": "Belk",
"uri": "https://api.servicetrade.com/api/company/2"
},
"location": {
"id": 8,
"uri": "https://api.servicetrade.com/api/location/8",
"legacyId": 4567,
"name": "Belk #401 Winder",
"lat": 33.943941,
"lon": -83.756069,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "916 Loganville, Highway, Suite 100",
"city": "Winder",
"state": "GA",
"postalCode": "30620"
},
"taxable": false,
"status": "active"
},
"serviceRequests": [
{
"id": 11,
"uri": "https://api.servicetrade.com/api/servicerequest/11",
"name": ""
}
],
"status": "waiting",
"respondBy": 1309795200,
"redTag": false,
"quotes": [
{
"id": 14,
"uri": "https://api.servicetrade.com/api/quote/14",
"name": "American Fire Quote for Belk Repair Job",
"status": "accepted"
},
{
"id": 15,
"uri": "https://api.servicetrade.com/api/quote/15",
"name": "Rapid Fire Quote for Belk Repair Job",
"status": "rejected"
}
],
"parentQuote": {
"id": 13,
"uri": "https://api.servicetrade.com/api/quote/13",
"name": "Customer quote for CEC Repair",
"status": "draft"
},
"type": "simple,
"quoteStatus": "draft"
}
}
Return to Top
QuoteTemplate
The quotetemplate resource is used to update and retrieve quote templates.
- Resource URL: /quotetemplate/[quoteTemplateId]
- Available Verbs: GET, POST, PUT, DELETE
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/quotetemplate |
200 |
|
GET |
/quotetemplate/123 |
200 |
|
GET |
/quotetemplate/123 |
404 |
quotetemplate 123 not found |
POST |
/quotetemplate |
200 |
quotetemplate created |
POST |
/quotetemplate |
400 |
quotetemplate not created: malformed data |
POST |
/quotetemplate |
403 |
quotetemplates cannot be created by user |
PUT |
/quotetemplate/123 |
200 |
|
PUT |
/quotetemplate/123 |
400 |
quotetemplate not updated: malformed data |
PUT |
/quotetemplate/123 |
403 |
quotetemplate 123 not editable by user |
PUT |
/quotetemplate/123 |
404 |
quotetemplate 123 not found |
DELETE |
/quotetemplate |
405 |
not allowed |
DELETE |
/quotetemplate/123 |
404 |
quotetemplate 123 not found |
DELETE |
/quotetemplate/123 |
403 |
quotetemplate 123 not editable by user |
DELETE |
/quotetemplate/123 |
409 |
quotetemplate still has child items |
DELETE |
/quotetemplate/123 |
204 |
quotetemplate 123 deleted |
Query Params
Name |
Type |
Value |
name |
string |
string to find in the quote template name |
companyIds |
string |
comma delimited list of companies ids, to find quote templates related to any those companies |
POST/PUT Parameters
Name |
Type |
Required for create? |
Value |
name |
string |
yes |
name for the template, used in lists |
description |
string |
no |
description of the quotes that will result from this template |
companyId |
integer |
no |
if given, template only applies to quotes for this company |
termsId |
integer |
no |
id for terms object which applies, defaults to null |
Returned Elements
Name |
Type |
Value |
uri |
string |
resource identifier of the quotetemplate |
id |
integer |
quote template id |
name |
string |
quote template name |
description |
string |
quote template description |
items |
array Quotetemplateitem |
quote template line items |
terms |
Terms |
terms and conditions of this quote template |
created |
integer |
Unix timestamp of the quote template’s creation date and time |
updated |
integer |
Unix timestamp of the quote template’s last update date and time |
Retrieve all quote templates in your account
GET /quotetemplate
200
{
"data": {
"totalPages": 1,
"page": 1,
"quoteTemplates": [
{
"id": 222,
"uri": "https://api.servicetrade.com/api/quotetemplate/222",
"name": "Quarterly Inspection",
"description": "Inspect all the quarters, and make sure they are shiny",
"company": null,
"items": [],
"terms": null,
"created": 1370266418,
"updated": 1370544276
},
{
"id": 223,
"uri": "https://api.servicetrade.com/api/quotetemplate/223",
"name": "Annual Flush",
"description": "Flush all the intercoolers",
"company": null,
"items": [],
"terms": {
"id": 334,
"uri": "https://api.servicetrade.com/api/terms/334",
"name": "Basic Terms"
}
"created": 1370266450,
"updated": 1371456236
}
]
}
}
Retrieve one quote template
GET /quotetemplate/222
200
{
"data": {
"id": 222,
"uri": "https://api.servicetrade.com/api/quotetemplate/222",
"name": "Quarterly Inspection",
"description": "Inspect all the quarters, and make sure they are shiny",
"company": null,
"items": [],
"terms": null,
"created": 1370266418,
"updated": 1370266418
}
}
Create a template
POST /quotetemplate
{"name": "Quarterly Inspection", "description": "Inspect all the quarters, and make sure they are shiny"}
200
{
"data": {
"id": 222,
"uri": "https://api.servicetrade.com/api/quotetemplate/222",
"name": "Quarterly Inspection",
"description": "Inspect all the quarters, and make sure they are shiny",
"company": null,
"items": [],
"terms": null,
"created": 1370266418,
"updated": 1370266418
}
}
Return to Top
QuoteTemplate Item
Retrieve or modify line items related to a quote.
- Resource URL: /quotetemplate/[quoteTemplateId]/item/[itemId]
- Resource URL: /quotetemplateitem/[itemId]
- Available Verbs: GET, POST, PUT, DELETE
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/quotetemplate/123/item |
200 |
|
GET |
/quotetemplateitem?quoteTemplateId=123 |
200 |
|
GET |
/quotetemplate/123/item/456 |
200 |
|
GET |
/quotetemplateitem/456 |
200 |
|
GET |
/quotetemplate/123/item/456 |
404 |
quote 123 not found, or quote item 456 not found on quote 123 |
GET |
/quotetemplateitem/456 |
404 |
quote item 456 not found |
GET |
/quotetemplateitem |
404 |
quoteTemplateId must be specified when searching for quote items |
POST |
/quotetemplateitem |
200 |
|
POST |
/quotetemplate/123/item |
200 |
|
POST |
/quotetemplate/123/item |
400 |
parameters invalid |
POST |
/quotetemplate/123/item |
403 |
do not have permission to modify quote 123 |
POST |
/quotetemplate/123/item |
404 |
quote 123 not found |
PUT |
/quotetemplateitem/456 |
200 |
|
PUT |
/quotetemplate/123/item/456 |
200 |
|
PUT |
/quotetemplate/123/item/456 |
400 |
parameters invalid |
PUT |
/quotetemplate/123/item/456 |
403 |
do not have permission to modify quote 123 |
PUT |
/quotetemplate/123/item/456 |
404 |
quote 123 not found |
DELETE |
/quotetemplate/123/item/456 |
403 |
do not have permission to modify quote 123 |
DELETE |
/quotetemplate/123/item/456 |
404 |
quote 123 not found |
DELETE |
/quotetemplate/123/item/456 |
204 |
quote item deleted |
Query Params
Name |
Type |
Value |
quoteTemplateId |
integer |
quote template to which this item belongs. Required. |
POST/PUT Parameters
Name |
Type |
Required |
Value |
quoteTemplateId |
integer |
yes |
sets the quote to which this item belongs |
quantity |
float |
yes |
how many units of this item are being charged on this line |
description |
string |
if no libItem |
item description |
libItemId |
integer |
if no description |
libitem that this item is an instance of |
serviceLineId |
integer |
if no libItem or libItem has no service line |
id of the service line |
orderIndex |
integer |
no |
items are listed from low to high value, null is the default value |
Returned Elements
Name |
Type |
Value |
items |
array (Quotetemplateitem) |
list of quotetemplateitem objects |
libItem |
Libitem |
libItem of the quote item |
serviceLine |
Service Line |
serviceLine of the quote item |
quoteTemplate |
Quotetemplate |
quote template to which this item belongs |
quantity |
float |
quantity of the quote item |
Retrieve all quote items for a given quote
GET /quotetemplate/45/item
GET /quotetemplateitem?quoteTemplateId=45
200
{
"data": {
"totalPages": 1,
"page": 1,
"items": [
{
"id": 11,
"uri": "https://api.servicetrade.com/api/quotetemplateitem/11",
"description": "Towel",
"quantity": 1,
"quote": {
"id": 45,
"uri": "https://api.servicetrade.com/api/quotetemplate/45",
"name": "Quote #3230004-SQKY-CLN"
},
"libItem": {
"id": 408,
"uri": "https://api.servicetrade.com/api/libitem/408",
"name": "Personal Item",
"type": "Part",
"code": "PERSONAL"
},
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/SUPP.png"
}
},
{
"id": 13,
"uri": "https://api.servicetrade.com/api/quotetemplateitem/13",
"description": "Unknown Charge",
"quantity": 2,
"quote": {
"id": 45,
"uri": "https://api.servicetrade.com/api/quotetemplate/45",
"name": "Quote #3230004-SQKY-CLN"
},
"libItem": {
"id": 283,
"uri": "https://api.servicetrade.com/api/libitem/283",
"name": "Other",
"type": "Other",
"code": "OTHER-UNK"
},
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/SUPP.png"
}
}
]
}
}
No items found on quote template
GET /quotetemplate/78/item
200
{
"data": {
"totalPages": 1,
"page": 1,
"items": []
}
}
Retrieve information for a single quote template item
GET /quotetemplateitem/11
200
{
"data": {
"id": 11,
"uri": "https://api.servicetrade.com/api/quotetemplateitem/11",
"description": "Towel",
"quantity": 2,
"quote": {
"id": 45,
"uri": "https://api.servicetrade.com/api/quotetemplate/45",
"name": "Quote #3230004-SQKY-CLN"
},
"libItem": {
"id": 408,
"uri": "https://api.servicetrade.com/api/libitem/408",
"name": "Personal Item",
"type": "Part",
"code": "PERSONAL"
},
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/SUPP.png"
}
}
}
Add an item to a quote template
POST /quotetemplate/78/item
{"description":"CCW Zirconium Flange","quantity":3}
200
{
"data": {
"id": 13,
"uri": "https://api.servicetrade.com/api/quotetemplateitem/13",
"description": "CCW Zirconium Flange",
"quantity": 2,
"quote": {
"id": 78,
"uri": "https://api.servicetrade.com/api/quotetemplate/78",
"name": "Quote #7721402-WAH"
},
"libItem": {
"id": 471,
"uri": "https://api.servicetrade.com/api/libitem/471",
"name": "CCW Zirconium Flange",
"type": "Part",
"code": "CCW-ZC-FLNG"
},
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/SUPP.png"
}
}
}
Return to Top
Region
The region resource is used to retrieve or define geographic regions.
- Resource URL: /region/[regionId]
- Available Verbs: GET, POST, PUT, DELETE
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/region |
200 |
|
GET |
/region/456 |
200 |
|
GET |
/region/456 |
404 |
region not found |
POST |
/region |
200 |
region created |
PUT |
/region |
405 |
not allowed |
PUT |
/region/456 |
200 |
region updated |
DELETE |
/region |
405 |
not allowed |
DELETE |
/region/456 |
200 |
region deleted |
DELETE |
/region/456 |
404 |
region not found |
DELETE |
/region/456/cache |
200 |
clears and recalculates which locations are within this region |
Query Params
Name |
Type |
Value |
name |
string |
returns only regions whose name includes this string (case insensitive) |
officeIds |
string |
comma delimited list of integers of office ids this region is assigned to |
contains |
array |
Array of 'lat' and 'lon', will return regions that contain that point |
Parameters for POST/PUT
Name |
Type |
Required |
Value |
name |
string |
yes |
name of the region |
points |
array of array |
yes |
array of points that define the boundaries of the region, each point a 2-element array of [latitude, longitude] |
color |
string |
no |
an HTML color string specifying a preferred color for drawing this region |
officeIds |
array (integer) |
no |
offices to which this region should be assigned |
Returned Elements
Name |
Type |
Value |
name |
string |
name of this region |
color |
string |
an HTML color string specifying a preferred color for drawing this region |
points |
array of array |
array of points that define the boundaries of the region, each point a 2-element array of [latitude, longitude] |
offices |
array (Location) |
list of offices this region is assigned to |
Retrieve all regions that match a given name
GET /region?name=Tri
200
{
"data": {
"totalPages": 1,
"page": 1,
"regions": [
{
"id": 333,
"uri": "https://api.servicetrade.com/api/region/333",
"name": "Bermuda Triangle",
"color": "#ff9000",
"points": [
[25.774252, -80.190262],
[18.466465, -66.118292],
[32.321384, -64.75737]
],
"offices": []
}
]
}
}
Retrieve all regions that contain a geographic point
GET /region?contains[lat]=27&contains[lon]=70
200
{
"data": {
"totalPages": 1,
"page": 1,
"regions": [
{
"id": 333,
"uri": "https://api.servicetrade.com/api/region/333",
"name": "Bermuda Triangle",
"color": "#ff9000",
"points": [
[25.774252, -80.190262],
[18.466465, -66.118292],
[32.321384, -64.75737]
],
"offices": []
}
]
}
}
Retrieve information for a single region
GET /region/333
200
{
"data": {
"id": 333,
"uri": "https://api.servicetrade.com/api/region/333",
"name": "Bermuda Triangle",
"color": "#ff9000",
"points": [
[25.774252, -80.190262],
[18.466465, -66.118292],
[32.321384, -64.75737]
],
"offices": [
{
"id": 70,
"uri": "https://api.servicetrade.com/api/location/70",
"name": "StandAlone Satellite Office",
"lat": 32.969788,
"lon": -80.007392,
"phoneNumber": "(843) 555-1233",
"email": "standalone@example.com",
"primaryContact": {
"id": 702,
"uri": "https://api.servicetrade.com/api/contact/702",
"firstName": "Stan",
"lastName": "Dalone",
"phone": "843-555-1233",
"mobile": "",
"alternatePhone": "",
"email": "stan@example.com",
"type": "management"
},
"address": {
"street": "1500 Red Bank Road",
"city": "Goose Creek",
"state": "SC",
"postalCode": "29445"
}
}
]
}
}
Create a new region
POST /region
{"name":"Area 51", "points":[ [36.125, -115.45], [36.125,-115.56], [37.175,-115.56], [37.175,-115.45] ]}
200
{
"data": {
"id": 32,
"uri": "https://api.servicetrade.com/api/region/32",
"name": "Area 51"
"color": null,
"points":[
[36.125, -115.45],
[36.125, -115.56],
[37.175, -115.56],
[37.175, -115.45]
],
"offices": []
}
}
Update a region
PUT /region/32
{"color":"#000"}
200
{
"data": {
"id": 32,
"uri": "https://api.servicetrade.com/api/region/32",
"name": "Area 51"
"color": "#000",
"points":[
[36.125, -115.45],
[36.125, -115.56],
[37.175, -115.56],
[37.175, -115.45]
],
"offices": []
}
}
Return to Top
Role
The role resource is used to retrieve lists of roles or detailed information about a single role.
- Resource URL: /role/[roleId]
- Available Verbs: GET
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/role |
200 |
|
GET |
/role/123 |
200 |
|
GET |
/role/123 |
404 |
role 123 not found |
POST |
/role |
405 |
not allowed |
PUT |
/role/123 |
405 |
not allowed |
DELETE |
/role |
405 |
not allowed |
Query Params
Name |
Type |
Value |
userId |
integer |
id of the user for whom you want a list of assigned roles. |
Returned Elements
Name |
Type |
Value |
name |
string |
user full name |
description |
string |
user status |
activities |
array |
list of permission activities this role has |
global |
boolean |
Is this role global (one of the default roles)? True for yes, False for custom account role. |
Retrieve information for a single role
GET /api/role/10
200
{
"data": {
"id": 10,
"uri": "https://api.servicetrade.com/api/role/10",
"name": "Company Admin",
"description": "Company Administrator",
"activities": [
"company.edit",
"company.edit.other",
"location.create",
"location.edit",
"location.edit.other",
"location.view",
"service.assignment.self",
"user.edit",
"user.view"
],
"global": false
}
}
Retrieve information for a role which does not exist
GET /role/987
404
Get roles assigned to a user.
GET /api/role?userId=28
or
GET /api/user/28/role
200
{
"data": {
"totalPages": 1,
"page": 1,
"roles": [
{
"id": 11,
"uri": "https://api.servicetrade.com/api/role/11",
"name": "Account Tech",
"description": "Tech for a stand alone account",
"activities": [
"admin.attachment",
"api.ivr",
"api.job.list",
"appointment.edit",
"asset.edit",
"company.view.other",
"deficiency.edit",
"deficiency.report",
"job.items",
"job.tech",
"job.view.other",
"location.view",
"user.view"
],
"global": true
},
{
"id": 13,
"uri": "https://api.servicetrade.com/api/role/13",
"name": "Account Manager",
"description": "Manager for a stand alone account",
"activities": [
"admin.attachment",
"admin.comment",
"admin.contact",
"admin.contract",
"admin.job",
"admin.libitem",
"admin.service.assignment",
"api.ivr",
"api.job.list",
"appointment.edit",
"asset.edit",
"company.create",
"company.edit.other",
"company.view.other",
"contact.edit",
"contract.edit",
"contract.view",
"deficiency.edit",
"deficiency.report",
"invoice.manage",
"invoice.view",
"invoice.view.other",
"job.cost",
"job.items",
"job.manage",
"job.price",
"job.schedule",
"location.create.other",
"location.edit.other",
"location.view",
"location.view.other",
"quote.edit",
"quote.request",
"quote.view",
"quotetemplate.manage",
"service.assignment.other",
"service.assignment.self",
"tag.edit",
"tag.manage",
"user.view"
],
"global": true
}
]
}
}
Return to Top
Service Item
Retrieve or modify line items related to a single service or recurrence.
- Resource URL: /servicerequest/[serviceRequestId]/item/[itemId]
- Resource URL: /serviceitem/[itemId]
- Available Verbs: GET, POST, PUT, DELETE
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/servicerequest/123/item |
200 |
|
GET |
/serviceitem?serviceRequestId=123 |
200 |
|
GET |
/servicerequest/123/item/456 |
200 |
|
GET |
/serviceitem/456 |
200 |
|
GET |
/servicerequest/123/item/456 |
404 |
servicerequest 123 not found, or servicerequest item 456 not found on servicerequest 123 |
GET |
/serviceitem/456 |
404 |
servicerequest item 456 not found |
GET |
/serviceitem |
404 |
serviceRequestId or serviceRecurrenceId must be specified when searching for servicerequest items |
POST |
/serviceitem |
200 |
|
POST |
/servicerequest/123/item |
200 |
|
POST |
/servicerequest/123/item |
400 |
parameters invalid |
POST |
/servicerequest/123/item |
403 |
do not have permission to modify servicerequest 123 |
POST |
/servicerequest/123/item |
404 |
servicerequest 123 not found |
PUT |
/serviceitem/456 |
200 |
|
PUT |
/servicerequest/123/item/456 |
200 |
|
PUT |
/servicerequest/123/item/456 |
400 |
parameters invalid |
PUT |
/servicerequest/123/item/456 |
403 |
do not have permission to modify servicerequest 123 |
PUT |
/servicerequest/123/item/456 |
404 |
servicerequest 123 not found |
DELETE |
/servicerequest/123/item/456 |
403 |
do not have permission to modify servicerequest 123 |
DELETE |
/servicerequest/123/item/456 |
404 |
servicerequest 123 not found |
DELETE |
/servicerequest/123/item/456 |
204 |
servicerequest item deleted |
Query Params
Name |
Type |
Value |
serviceRequestId |
integer |
servicerequest to which this item belongs. One of serviceRequestId, serviceRecurrenceId, or serviceTemplateId is required. |
serviceRecurrenceId |
integer |
service recurrence to which this item belongs. One of serviceRequestId, serviceRecurrenceId, or serviceTemplateId is required. |
serviceTemplateId |
integer |
service template to which this item belongs. One of serviceRequestId, serviceRecurrenceId, or serviceTemplateId is required. |
POST/PUT Parameters
Name |
Type |
Required |
Value |
serviceRequestId |
integer |
conditional |
sets the servicerequest to which this item belongs. One of serviceRequestId, serviceRecurrenceId, or serviceTemplateId is required. |
serviceRecurrenceId |
integer |
conditional |
sets the service recurrence to which this item belongs. One of serviceRequestId, serviceRecurrenceId, or serviceTemplateId is required. |
serviceTemplateId |
integer |
conditional |
sets the service template to which this item belongs. One of serviceRequestId, serviceRecurrenceId, or serviceTemplateId is required. |
quantity |
double |
on POST |
how many units of this item are being charged on this line |
price |
double |
no |
the unit price being charged for this line item |
description |
string |
if no libItem |
item description |
libItemId |
integer |
if no description |
libitem that this item is an instance of |
serviceLineId |
integer |
if no libItem or libItem has no service line |
id of the service line |
orderIndex |
integer |
no |
items are listed from low to high value, null is the default value |
Returned Elements
Name |
Type |
Value |
serviceitems |
array (Service Item) |
list of serviceitem objects |
libItem |
Libitem |
libItem of the service item |
serviceLine |
Service Line |
serviceLine of the service item |
serviceRequest |
Service Request |
servicerequest to which this item belongs |
serviceRecurrence |
Service Recurrence |
service recurrence to which this item belongs |
serviceTemplate |
Service Template |
service template to which this item belongs |
price |
float |
unit price of the service item |
quantity |
float |
quantity of the service item |
Retrieve all servicerequest items for a given servicerequest
GET /servicerequest/45/item
GET /serviceitem?serviceRequestId=45
200
{
"data": {
"totalPages": 1,
"page": 1,
"serviceitems": [
{
"id": 11,
"uri": "https://api.servicetrade.com/api/serviceitem/11",
"description": "Towel",
"quantity": 1,
"price": 100.00,
"serviceRequest": {
"id": 45,
"uri": "https://api.servicetrade.com/api/servicerequest/45",
"name": "ServiceRequest #3230004-SQKY-CLN"
},
"serviceRecurrence": null,
"libItem": {
"id": 408,
"uri": "https://api.servicetrade.com/api/libitem/408",
"name": "Personal Item",
"type": "Part",
"code": "PERSONAL"
},
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/SUPP.png"
}
},
{
"id": 13,
"uri": "https://api.servicetrade.com/api/serviceitem/13",
"description": "Unknown Charge",
"quantity": 2,
"price": 100.00,
"serviceRequest": {
"id": 45,
"uri": "https://api.servicetrade.com/api/servicerequest/45",
"name": "ServiceRequest #3230004-SQKY-CLN"
},
"serviceRecurrence": null,
"libItem": {
"id": 283,
"uri": "https://api.servicetrade.com/api/libitem/283",
"name": "Other",
"type": "Other",
"code": "OTHER-UNK"
},
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/SUPP.png"
}
}
]
}
}
No items found on servicerequest
GET /servicerequest/78/item
200
{
"data": {
"totalPages": 1,
"page": 1,
"serviceitems": []
}
}
Retrieve information for a single servicerequest item
GET /serviceitem/11
200
{
"data": {
"id": 11,
"uri": "https://api.servicetrade.com/api/serviceitem/11",
"description": "Towel",
"quantity": 2,
"price": 100.00,
"serviceRequest": {
"id": 45,
"uri": "https://api.servicetrade.com/api/servicerequest/45",
"name": "ServiceRequest #3230004-SQKY-CLN"
},
"serviceRecurrence": null,
"libItem": {
"id": 408,
"uri": "https://api.servicetrade.com/api/libitem/408",
"name": "Personal Item",
"type": "Part",
"code": "PERSONAL"
},
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/SUPP.png"
}
}
}
Add an item to an servicerequest
POST /servicerequest/78/item
{"description":"CCW Zirconium Flange","quantity":3,"price":24.00}
200
{
"data": {
"id": 13,
"uri": "https://api.servicetrade.com/api/serviceitem/13",
"description": "CCW Zirconium Flange",
"quantity": 2,
"price": 100.00,
"serviceRequest": {
"id": 78,
"uri": "https://api.servicetrade.com/api/servicerequest/78",
"name": "ServiceRequest #7721402-WAH"
},
"serviceRecurrence": null,
"libItem": {
"id": 471,
"uri": "https://api.servicetrade.com/api/libitem/471",
"name": "CCW Zirconium Flange",
"type": "Part",
"code": "CCW-ZC-FLNG"
},
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "http://app.servicetrade.com/image/icons/service_lines/32/SUPP.png"
}
}
}
Return to Top
Service Line
The serviceline resource is used to retrieve the list of service lines and details about them.
- Resource URL: /serviceline/[serviceLineId]
- Available Verbs: GET
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/serviceline |
200 |
|
GET |
/serviceline/123 |
200 |
|
GET |
/serviceline/123 |
404 |
service line not found |
POST |
/serviceline |
405 |
not allowed |
PUT |
/serviceline/123 |
405 |
not allowed |
DELETE |
/serviceline/123 |
405 |
not allowed |
Query Params
Name |
Type |
Value |
tradeName |
string |
returns only service lines with a trade name that matches this string (case insensitive) |
showAll |
boolean |
return all service lines in the system, even ones the requesting user's company does not provide. default value is false. |
Returned Elements
Name |
Type |
Value |
id |
integer |
|
name |
string |
|
trade |
object |
|
trade.name |
string |
|
icon |
string |
|
Retrieve all servicelines with a trade that matches a given name
GET /serviceline/?tradeName=Basket
200
{
"data": {
"totalPages": 1,
"page": 1,
"servicelines": [
{
"id": 90,
"name": "Basic Weaves",
"trade": "Underwater Basket Weaving",
"abbr": "UWB",
"icon": "https://api.servicetrade.com/image/icons/service_lines/32/OTHER.png"
},
{
"id": 84,
"name": "Advanced Weaves",
"trade": "Underwater Basket Weaving",
"abbr": "UWA",
"icon": "https://api.servicetrade.com/image/icons/service_lines/32/OTHER.png"
},
{
"id": 84,
"name": "Stats Gathering",
"trade": "Fantasy Basketball",
"abbr": "FBSTAT",
"icon": "https://api.servicetrade.com/image/icons/service_lines/32/OTHER.png"
}
}
No trade matches found
GET /serviceline?tradeName=asdfasdf
200
{
"data": {
"totalPages": 1,
"page": 1,
"servicelines": []
}
}
Retrieve information for a single service line
GET /serviceline/90
200
{
"data": {
"id": 90,
"name": "Basic Weaves",
"trade": "Underwater Basket Weaving",
"abbr": "UWB",
"icon": "https://api.servicetrade.com/image/icons/service_lines/32/OTHER.png"
}
}
Return to Top
ServiceRecurrence
The servicereccurence resource is used to update and retrieve service recurrences.
To end a service recurrence, PUT an endsOn date to that recurrence.
To modify the schedule (frequency, interval, or start/end date) of an existing service recurrence, POST a new service recurrence and provide the existing recurrence's ID as the serviceRecurrenceId parameter, along with parameters for the schedule values that should be changed. All values not provided will be copied from the existing recurrence. The existing service recurrence will be ended and the newly created service recurrence will get the existing recurrence as its parent.
- Resource URL: /servicerecurrence/[serviceRecurrenceId]
- Available Verbs: GET, POST, PUT
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/servicerecurrence |
200 |
|
GET |
/servicerecurrence/123 |
200 |
|
GET |
/servicerecurrence/123 |
404 |
servicerecurrence 123 not found (or not accessible by the user) |
POST |
/servicerecurrence |
200 |
servicerecurrence created |
POST |
/servicerecurrence |
400 |
servicerecurrence not created: malformed data |
PUT |
/servicerecurrence |
405 |
not allowed |
PUT |
/servicerecurrence/123 |
200 |
|
PUT |
/servicerecurrence/123 |
400 |
servicerecurrence not updated: malformed data |
PUT |
/servicerecurrence/123 |
404 |
servicerecurrence 123 not found (or not accessible by the user) |
DELETE |
/servicerecurrence |
405 |
not allowed |
DELETE |
/servicerecurrence/123 |
405 |
not allowed |
Query Params
Name |
Type |
Value |
locationIds |
integer |
return recurrences for this comma delimited list of integer location ids |
assetIds |
string |
return recurrences for the comma delimited list of integer asset ids |
description |
string |
return recurrences with a description containing this string |
serviceLineIds |
string |
return recurrences for the comma delimited list of service line ids |
officeIds |
string |
return recurrences at locations served by offices in this comma delimited list |
preferredTechIds |
string |
comma delimited list of integers of user ids for preferred technicians on the recurrence |
contractId |
string |
return recurrences associated with this comma delimited list of contract ids |
endsOnAfter |
integer |
(optional) return recurrences that end on or after the timestamp or have no endsOn set |
excludeUnapproved |
boolean |
exclude any recurrences that are waiting on a quote approval |
createdAfter |
integer |
returns only recurrences created on or after the given timestamp |
createdBefore |
integer |
returns only recurrences created on or before the given timestamp |
updatedAfter |
integer |
return only recurrences whose last update time is on or after the given timestamp |
updatedBefore |
integer |
return only recurrences whose last update time is on or before the given timestamp |
POST/PUT Parameters
Name |
Type |
Required for create? |
Value |
locationId |
integer |
yes |
location the service is to be performed at (Note: this is a POST only field, you are not allowed to change the locationId with a PUT request) |
serviceRequestId |
integer |
no |
If this service request has a recurrence, return a new recurrence whose parent is the original recurrence, end the original recurrence, and set the new recurrence's parent to the old one. Also, this service request will now belong to the new recurrence and have a new id. Currently, only a service request with a recurrence is allowed in this field. (Deprecated: use serviceRecurrenceId instead) |
serviceRecurrenceId |
integer |
no |
return a new recurrence whose parent is the original recurrence, end the original recurrence, and set the new recurrence's parent to the old one. Supported on POST only. Recurrence supplied must be active (not ended). |
endsOn |
integer |
no |
Unix timestamp of the servicerequest’s ends on date and time, and service requests past that time will be cleaned up if not assigned to a job |
description |
string |
yes |
description of this recurring service |
estimatedPrice |
double |
no |
estimated price for an instance of this recurrence |
duration |
integer |
no |
how long this service is expected to take, in seconds |
preferredStartTime |
integer |
no |
number of seconds representing the hour and minute of the preferred start time of the service (e. g. 35100 = 9:45 AM) |
preferredTechIds |
array (integer) |
no |
technicians preferred for this work (if this is provided, preferredVendorId should be null) |
preferredVendorId |
integer |
no |
vendorId of the vendor company preferred for this work (if this is provided, preferredTechIds should be empty) |
serviceLineId |
integer |
yes |
what line of service this recurrence is for |
assetId |
integer |
no |
what asset this service is specific to, asset must belong to location |
contractId |
integer |
no |
identifies the contract for this service, contract must be valid for service location |
firstStart |
integer |
no |
Unix timestamp of the service recurrence’s first service request window start date and time. If supplied, firstEnd must also be supplied. Supported on POST only. |
firstEnd |
integer |
no |
Unix timestamp of the service recurrence’s first service request window end date and time. If supplied, firstStart must also be supplied. Supported on POST only. |
frequency |
string |
no |
frequency of recurrence, one of: daily, weekly, monthly, yearly. Supported on POST only. |
interval |
integer |
no |
interval of recurrence. Think of it this way: "this recurrence happens every [interval] [frequency]'s". Supported on POST only. |
repeatWeekday |
boolean |
no |
Is the recurrence tied to a specific day in a specific week (e. g. the 1st Tuesday, or the 3rd Friday). Only applies if frequency is monthly; defaults to false if not supplied. Supported on POST only. |
Returned Elements
Name |
Type |
Value |
uri |
string |
resource identifier of the servicerecurrence |
id |
integer |
service recurrence id |
description |
string |
service recurrence description |
serviceLine |
Service Line |
service line |
asset |
Asset |
asset to service |
location |
Location |
location resource |
firstStart |
integer |
Unix timestamp of the service recurrence’s first service request window start date and time |
firstEnd |
integer |
Unix timestamp of the service recurrence’s first service request window end date and time |
endsOn |
integer |
Unix timestamp of the service recurrence’s ends on date and time |
created |
integer |
Unix timestamp of the service recurrence’s creation date and time |
frequency |
string |
frequency of recurrence, one of: daily, weekly, monthly, quarterly, semiannually, yearly |
interval |
integer |
interval of recurrence. Think of it this way: "this recurrence happens every [interval] [frequency]'s" |
repeatWeekday |
boolean |
Is the recurrence tied to a specific day in a specific week (e. g. the 1st Tuesday, or the 3rd Friday). Only applies if frequency is monthly. |
parent.id |
integer |
id for the recurrence that is the parent of this one |
parent.uri |
string |
uri for the recurrence that is the parent of this one |
contract |
Contract |
|
preferredTechs |
User |
tech(s) preferred for this service |
preferredVendor |
Company |
vendor company preferred for this service |
estimatedPrice |
double |
estimated price for one instance of this recurrence |
duration |
integer |
how long this service is expected to take, in seconds |
preferredStartTime |
integer |
preferred start time, in seconds representing hour and minute (e. g. 35100 = 9:45 AM) |
items |
array Serviceitem |
items that will be used in fulfilling this service |
Retrieve all servicerecurrences in your account
GET /servicerecurrence
200
{
"data": {
"totalPages": 1,
"page": 1,
"serviceRecurrences": [
{
"uri": "https://api.servicetrade.com/api/servicerecurrence/222",
"id": 222,
"description": "inspection",
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "https://api.servicetrade.com/image/icons/service_lines/32/SUPP.png"
},
"asset": null,
"contract": {
"id": 1999,
"uri": "http://api.servicetrade.com/api/contract/1999",
"name": "Default Pricing Contract"
},
"location": {
"id": 69,
"uri": "https://api.servicetrade.com/api/location/69",
"name": "Hwy 55 Burgers - Hope Mills",
"legacyId": null,
"phoneNumber": "(910) 860-2200",
"generalManager": "Tony Rutland",
"email": "trutland@example.com",
"primaryContact": null,
"address": {
"street": "3020 N. Main St., Suite 338",
"city": "Hope Mills",
"state": "NC",
"postalCode": "28348"
},
"taxable": false,
"status": "active"
},
"firstStart": 1370145600,
"firstEnd": 1370750399,
"endsOn": null,
"created": 1370266418,
"frequency": "monthly",
"interval": 1,
"repeatWeekday": false,
"parent": null,
"preferredTechs": [],
"preferredVendor": null,
"duration": 0,
"preferredStartTime": 0,
"estimatedPrice": 12.34,
"items": [
{
"id": 372,
"uri": "https://api.servicetrade.com/api/servicerecurrence/372",
"description": "Full system inspection"
}
]
},
{
"uri": "https://api.servicetrade.com/api/servicerecurrence/223",
"id": 223,
"description": "inspection",
"serviceLine": {
"id": 3,
"name": "Portable Extinguishers",
"trade": "Fire Protection",
"abbr": "EXT",
"icon": "https://api.servicetrade.com/image/icons/service_lines/32/EXT.png"
},
"asset": null,
"contract": {
"id": 1999,
"uri": "http://api.servicetrade.com/api/contract/1999",
"name": "Default Pricing Contract"
},
"location": {
"id": 69,
"uri": "https://api.servicetrade.com/api/location/69",
"name": "Hwy 55 Burgers - Hope Mills",
"legacyId": null,
"phoneNumber": "(910) 860-2200",
"generalManager": "Tony Rutland",
"email": "trutland@example.com",
"primaryContact": null,
"address": {
"street": "3020 N. Main St., Suite 338",
"city": "Hope Mills",
"state": "NC",
"postalCode": "28348"
},
"taxable": false,
"status": "active"
},
"firstStart": 1370059200,
"firstEnd": 1372651199,
"endsOn": null,
"created": 1370266450,
"frequency": "monthly",
"interval": 1,
"repeatWeekday": false,
"parent": null,
"preferredTechs": []
"preferredVendor": null,
"duration": 0,
"preferredStartTime": null,
"estimatedPrice": null,
"items": []
}
]
}
}
Retrieve one service recurrence
GET /servicerecurrence/222
200
{
"data": {
"uri": "https://api.servicetrade.com/api/servicerecurrence/222",
"id": 222,
"description": "inspection",
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "https://api.servicetrade.com/image/icons/service_lines/32/SUPP.png"
},
"asset": null,
"contract": {
"id": 1999,
"uri": "http://api.servicetrade.com/api/contract/1999",
"name": "Default Pricing Contract"
},
"location": {
"id": 69,
"uri": "https://api.servicetrade.com/api/location/69",
"name": "Hwy 55 Burgers - Hope Mills",
"legacyId": null,
"phoneNumber": "(910) 860-2200",
"generalManager": "Tony Rutland",
"email": "trutland@example.com",
"primaryContact": null,
"address": {
"street": "3020 N. Main St., Suite 338",
"city": "Hope Mills",
"state": "NC",
"postalCode": "28348"
},
"taxable": false,
"status": "active"
},
"firstStart": 1370145600,
"firstEnd": 1370750399,
"endsOn": null,
"created": 1370266418,
"frequency": "monthly",
"interval": 1,
"repeatWeekday": false,
"parent": null,
"preferredTechs": [],
"preferredVendor": null,
"duration": 900,
"preferredStartTime": 35100,
"estimatedPrice": 100.00,
"items": []
}
}
Modify the end of a recurrence
PUT /servicerecurrence/222
{"endsOn": 1370276418}
200
{
"data": {
"uri": "https://api.servicetrade.com/api/servicerecurrence/222",
"id": 222,
"description": "inspection",
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "https://api.servicetrade.com/image/icons/service_lines/32/SUPP.png"
},
"asset": null,
"contract": null,
"location": {
"id": 69,
"uri": "https://api.servicetrade.com/api/location/69",
"name": "Hwy 55 Burgers - Hope Mills",
"legacyId": null,
"phoneNumber": "(910) 860-2200",
"generalManager": "Tony Rutland",
"email": "trutland@example.com",
"primaryContact": null,
"address": {
"street": "3020 N. Main St., Suite 338",
"city": "Hope Mills",
"state": "NC",
"postalCode": "28348"
},
"taxable": false,
"status": "active"
},
"firstStart": 1370145600,
"firstEnd": 1370750399,
"endsOn": 1370276418,
"created": 1370266418,
"frequency": "monthly",
"interval": 1,
"repeatWeekday": false,
"parent": null,
"preferredTechs": [],
"preferredVendor": null,
"duration": 900,
"preferredStartTime": null,
"estimatedPrice": 100.00,
"items": []
}
}
Reschedule the parent recurrence of a specified service request to follow the service request
POST /servicerecurrence
{"serviceRequestId": 1060}
200
{
"data": {
"uri": "https://api.servicetrade.com/api/servicerecurrence/373",
"id": 373,
"description": "inspection",
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "https://api.servicetrade.com/image/icons/service_lines/32/SUPP.png"
},
"asset": null,
"contract": null,
"location": {
"id": 69,
"uri": "https://api.servicetrade.com/api/location/69",
"name": "Hwy 55 Burgers - Hope Mills",
"legacyId": null,
"phoneNumber": "(910) 860-2200",
"generalManager": "Tony Rutland",
"email": "trutland@example.com",
"primaryContact": null,
"address": {
"street": "3020 N. Main St., Suite 338",
"city": "Hope Mills",
"state": "NC",
"postalCode": "28348"
},
"taxable": false,
"status": "active"
},
"firstStart": 1370145600,
"firstEnd": 1370750399,
"endsOn": null,
"created": 1370370476,
"frequency": "monthly",
"interval": 1,
"repeatWeekday": false,
"parent": {
"uri": "https://api.servicetrade.com/api/servicerecurrence/372",
"id": 372
}
"preferredTechs": [],
"preferredVendor": null,
"duration": 900,
"preferredStartTime": 0,
"estimatedPrice": 100.00,
"items": []
}
}
Reschedule a recurrence by creating a new recurrence whose parent is the existing recurrence
POST /servicerecurrence
{"serviceRecurrenceId": 5431, "frequency": "daily", "interval": 2}
200
{
"data": {
"uri": "https://api.servicetrade.com/api/servicerecurrence/5432",
"id": 5432,
"description": "inspection",
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "https://api.servicetrade.com/image/icons/service_lines/32/SUPP.png"
},
"asset": null,
"contract": null,
"location": {
"id": 69,
"uri": "https://api.servicetrade.com/api/location/69",
"name": "Hwy 55 Burgers - Hope Mills",
"legacyId": null,
"phoneNumber": "(910) 860-2200",
"generalManager": "Tony Rutland",
"email": "trutland@example.com",
"primaryContact": null,
"address": {
"street": "3020 N. Main St., Suite 338",
"city": "Hope Mills",
"state": "NC",
"postalCode": "28348"
},
"taxable": false,
"status": "active"
},
"firstStart": 1370145600,
"firstEnd": 1370750399,
"endsOn": null,
"created": 1370370476,
"frequency": "daily",
"interval": 2,
"repeatWeekday": false,
"parent": {
"uri": "https://api.servicetrade.com/api/servicerecurrence/5431",
"id": 5431
}
"preferredTechs": [],
"preferredVendor": null,
"duration": 900,
"preferredStartTime": 0,
"estimatedPrice": 100.00,
"items": []
}
}
Return to Top
ServiceRequest
The servicerequest resource is used to update and retrieve services.
- Resource URL: /servicerequest/[serviceRequestId]
- Available Verbs: GET, POST, PUT
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/servicerequest |
200 |
|
GET |
/servicerequest/123 |
200 |
|
GET |
/servicerequest/123 |
404 |
servicerequest 123 not found (or not accessible by the user) |
GET |
/servicerequest/123/comment |
200 |
retrieve list of comments |
GET |
/servicerequest/123/comment/67 |
200 |
retrieve comment info |
POST |
/servicerequest |
200 |
servicerequest created |
POST |
/servicerequest |
400 |
servicerequest not created: malformed data |
POST |
/servicerequest/123 |
400 |
appointment parameter cannot be specified with a null job |
POST |
/servicerequest/123/comment |
200 |
create a comment - see Comment for details |
PUT |
/servicerequest |
405 |
not allowed |
PUT |
/servicerequest/123 |
200 |
|
PUT |
/servicerequest/123 |
400 |
servicerequest not updated: malformed data |
PUT |
/servicerequest/123 |
400 |
appointment parameter cannot be specified with a null job |
PUT |
/servicerequest/123 |
404 |
servicerequest 123 not found (or not accessible by the user) |
DELETE |
/servicerequest |
405 |
not allowed |
DELETE |
/servicerequest/123 |
405 |
not allowed |
Query Params
Name |
Type |
Value |
jobNumber |
integer |
return servicerequests associated with the job having jobNumber |
jobId |
integer |
return servicerequests associated with the job identified by jobId |
appointmentId |
integer |
return servicerequests assigned to appointments identified by appointmentId |
locationId |
integer |
return servicerequests for this location |
assetIds |
string |
return servicerequests for the comma delimited list of integers of asset ids |
locationName |
string |
return servicerequests for locations whose name contains this string |
locationTags |
string |
comma-separated list of tag strings, only servicerequests whose location has all tags will be returned |
customerName |
string |
return servicerequests where the customer company name contains this string |
description |
string |
return servicerequests with a description containing this string |
windowStart |
integer |
(deprecated, alias for windowEndAfter) Unix timestamp of the servicerequest’s window start date |
windowEnd |
integer |
(deprectaed, alias for windowStartBefore) Unix timestamp of the servicerequest’s window end date |
windowStartBefore |
integer |
(optional) return servicerequests that start before the windowStart timestamp |
windowStartAfter |
integer |
(optional) return servicerequests that start on or after the windowStart timestamp |
windowEndBefore |
integer |
(optional) return servicerequests that end before the windowEnd timestamp |
windowEndAfter |
integer |
(optional) return servicerequests that end after the windowEnd timestamp |
createdAfter |
integer |
(optional) return servicerequests that were created on or after the timestamp |
createdBefore |
integer |
(optional) return servicerequests that were created on or before the timestamp |
updatedAfter |
integer |
(optional) return servicerequests that were updated on or after the timestamp |
updatedBefore |
integer |
(optional) return servicerequests that were updated on or before the timestamp |
serviceLineIds |
string |
(optional) comma separated list of service line ids |
status |
string |
comma-separated list of statuses: open, in_progress, closed, void, canceled, pending |
recurring |
boolean |
if true, return only servicerequests associated with a recurrence; if false, return only servicerequests NOT associated with a recurrence; if not supplied, return all servicerequests regardless of recurrence association |
available |
boolean |
return servicerequests for active locations that can be safely added to a job |
deficiencyId |
integer |
return servicerequests for this deficiency |
changeOrderId |
integer |
return servicerequests for this change orders |
budgetId |
integer |
return servicerequestes for this budget |
quoteId |
string |
return servicerequests assigned to quotes in this comma delimited list of ids |
companyIds |
string |
return servicerequests at locations belonging to companies in this comma delimited list of ids |
officeIds |
string |
return servicerequests at locations served by this comma delimited list of office ids |
regionIds |
string |
return servicerequests at locations in this comma delimited list of region ids |
contractId |
string |
return servicerequests associated with this comma delimited list of contract ids |
preferredTechIds |
string |
comma delimited list of integers of user ids for preferred technicians on the service |
preferredVendorId |
string |
comma delimited list of integers of company ids for preferred vendors on the service |
serviceRecurrenceId |
integer |
return servicerequests that are part of the given recurrence |
sort |
string |
sort results, current options: 'id', 'locationName'. id is the default. |
excludeUnapproved |
boolean |
exclude any service requests that are waiting on a quote approval |
POST/PUT Parameters
Name |
Type |
Value |
description |
string |
description of service requested |
locationId |
integer |
location the service is requested at (Note: this is a POST only field, you are not allowed to change the locationId with a PUT request. LocationId cannot be null status is pending) |
serviceLineId |
integer |
what line of service this request is for |
status |
string |
(optional) one of open, in_progress, closed, pending (only valid if job_id and location_id are null), canceled, void (defaults to 'open') |
jobId |
integer |
(optional) assigns the serviceRequest to a specific job will not be null when status is pending |
assetId |
integer |
(optional) identifies the specific asset requiring service |
contractId |
integer |
(optional) identifies the contract for this service |
deficiencyId |
integer |
(optional) identifies the deficiency this service is to address |
changeOrderId |
integer |
(optional) identifies the change order this service request is associated with, if applicable |
budgetId |
integer |
(required if status is pending) identifies the budget associated with this service request |
windowStart |
integer |
(optional) Unix timestamp of the servicerequest’s window start date (if provided, must also provide windowEnd) |
windowEnd |
integer |
(optional) Unix timestamp of the servicerequest’s window end date (if provided, must also provide windowStart) |
closedOn |
integer |
(optional) Unix timestamp of the servicerequest’s closed on date and time (This may be set automatically if status is set to 'closed') |
preferredTechIds |
array (integer) |
(optional) technicians preferred for this work |
preferredVendorId |
integer |
(optional) vendorId of the vendor company preferred for this work (if this is provided, preferredTechIds should be empty) |
preferredStartTime |
integer |
(optional) number of seconds representing the hour and minute of the preferred start time of the service (e. g. 35100 = 9:45 AM) |
estimatedPrice |
double |
(optional) the estimated price of the service request |
duration |
integer |
(optional) how long this service is expected to take, in seconds |
visibility |
array(string) |
(optional) visibility granted to these types of viewers outside of the account; combination of: public, customer, subcontractor. "public" indicates global visibility and overrides the other values. Will default to account default if no value is provided on POST. |
appointmentIds |
array(integer) |
(optional) appointments to associate this service with. Requires jobId to be set. |
Returned Elements
Name |
Type |
Value |
uri |
string |
resource identifier of the servicerequest |
id |
integer |
servicerequest id |
status |
string |
servicerequest status (open, in_progress, closed, canceled, void, pending) |
description |
string |
servicerequest description |
serviceLine |
Service Line |
|
asset |
Asset |
|
location |
Location |
|
location.phoneNumber |
string |
formatted as (XXX) XXX-XXXX | |
location.generalManager |
string |
name of general manager at the location | |
location.email |
string |
email address of the location | |
job |
Job |
|
deficiency |
Deficiency |
|
changeOrder |
Change Order |
|
budget |
Budget |
|
contract |
Contract |
|
windowStart |
integer |
Unix timestamp of the servicerequest’s window start date and time |
windowEnd |
integer |
Unix timestamp of the servicerequest’s window end date and time |
closedOn |
integer |
Unix timestamp of the servicerequest’s closed on date and time |
created |
integer |
Unix timestamp of the servicerequest’s creation date and time |
updated |
integer |
Unix timestamp of the servicerequest’s last updated date and time |
serviceRecurrence |
Service Recurrence |
service recurrence |
preferredTechs |
User |
tech(s) preferred for this service |
preferredVendor |
Company |
vendor company preferred for this service |
preferredStartTime |
integer |
preferred start time, in seconds representing hour and minute (e. g. 35100 = 9:45 AM) |
estimatedPrice |
double |
the estimated price of the service request |
duration |
integer |
how long this service is expected to take, in seconds |
visibility |
array(string) |
visibility granted to these types of viewers outside of the account; combination of: public, customer, subcontractor. "public" indicates global visibility and overrides the other values. |
items |
array Serviceitem |
items that will be used in fulfilling this service |
quoteRequests |
array Quote Request |
quote requests linked to this service request |
originalWindowStart |
integer |
Unix timestamp of the servicerequest’s window original start date and time. Available only for servicerequests associated with a serviceRecurrence; otherwise null. |
originalWindowEnd |
integer |
Unix timestamp of the servicerequest’s window original end date and time. Available only for servicerequests associated with a serviceRecurrence; otherwise null. |
Retrieve all servicerequests for location 57
GET /servicerequest/?locationId=57
200
{
"data": {
"totalPages": 1,
"page": 1,
"servicerequests": [
{
"uri": "https://api.servicetrade.com/api/servicerequest/34",
"id": 34,
"status": "in_progress",
"description": "Fire Suppression: 10.20 Per MOD Jason, another company, doing unrelated work, removed the piping for some or all of the suppression system and did not reinstall it. Please respond to repair and ensure location has coverage. RCH",
"serviceLine": {
"id": 5,
"name": "Sprinkler",
"trade": "Fire Protection",
"icon": "https://app.servicetrade.com/image/icons/service_lines/32/SP.png",
"abbr": "SP"
},
"job": {
"id": 41,
"uri": "https://api.servicetrade.com/api/job/41",
"number": 207464,
"type": "inspection",
"name": "Job 207464"
},
"deficiency": {
"id": 21,
"uri": "http://api.servicetrade.com/api/deficiency/21",
"name": "Deficiency #21",
"description": "Broken foobars"
},
"changeOrder": {
"id": 21,
"uri": "http://localhost:8989/api/changeorder/21",
"status": "applied",
"type": "internal",
"referenceNumber": "INT-0001"
},
"contract": {
"id": 1999,
"uri": "http://api.servicetrade.com/api/contract/1999",
"name": "Default Pricing Contract"
},
"location": {
"id": 57,
"uri": "https://api.servicetrade.com/api/location/57",
"legacyId": 4567,
"name": "Ruby Tuesday - #4722 Kinston",
"lat": 35.264011,
"lon": -77.64003,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "3725 West Vernon Avenue",
"city": "Kinston",
"state": "NC",
"postalCode": "28504"
},
"taxable": false,
"status": "inactive"
},
"asset": null,
"windowStart": 1337140800,
"windowEnd": 1337140800,
"closedOn": 1337140800,
"created": 1337192440,
"updated": 1337192440,
"serviceRecurrence": {
"id": 2,
"frequency": "monthly",
"interval": 3
},
"preferredTechs": [],
"preferredVendor": null,
"estimatedPrice": null,
"duration": 0,
"preferredStartTime": 0,
"visibility": ["public"],
"items": [],
"quoteRequests": [],
"originalWindowStart": null,
"originalWindowEnd": null
}
]
}
}
Retrieve servicerequest 34
GET /servicerequest/34
200
{
"data": {
"uri": "https://api.servicetrade.com/api/servicerequest/34",
"id": 34,
"status": "in_progress",
"description": "Fire Suppression: 10.20 Per MOD Jason, another company, doing unrelated work, removed the piping for some or all of the suppression system and did not reinstall it. Please respond to repair and ensure location has coverage. RCH",
"serviceLine": {
"id": 5,
"name": "Sprinkler",
"trade": "Fire Protection",
"icon": "https://app.servicetrade.com/image/icons/service_lines/32/SP.png",
"abbr": "SP"
},
"job": {
"id": 41,
"uri": "https://api.servicetrade.com/api/job/41",
"number": 207464,
"type": "inspection",
"name": "Job 207464"
},
"deficiency": {
"id": 21,
"uri": "http://api.servicetrade.com/api/deficiency/21",
"name": "Deficiency #21",
"description": "Broken foobars"
},
"changeOrder": {
"id": 221,
"uri": "http://localhost:8989/api/changeorder/221",
"status": "applied",
"type": "external",
"referenceNumber": "#0001"
},
"contract": {
"id": 1999,
"uri": "http://api.servicetrade.com/api/contract/1999",
"name": "Default Pricing Contract"
},
"location": {
"id": 57,
"uri": "https://api.servicetrade.com/api/location/57",
"legacyId": 4567,
"name": "Ruby Tuesday - #4722 Kinston",
"lat": 35.264011,
"lon": -77.64003,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "3725 West Vernon Avenue",
"city": "Kinston",
"state": "NC",
"postalCode": "28504"
},
"taxable": false,
"status": "inactive"
},
"asset": null,
"windowStart": 1337140800,
"windowEnd": 1337140800,
"closedOn": 1337140800,
"created": 1337192440,
"updated": 1337192440,
"serviceRecurrence": {
"id": 2,
"frequency": "monthly",
"interval": 3
},
"preferredTechs": [],
"preferredVendor": null,
"estimatedPrice": 12.34,
"duration": 900,
"preferredStartTime": 35100,
"visibility": ["public"],
"items": [],
"quoteRequests": [],
"originalWindowStart": null,
"originalWindowEnd": null
}
}
Update servicerequest
PUT /servicerequest/34
{"status":"closed"}
200
{
"data": {
"uri": "https://api.servicetrade.com/api/servicerequest/34",
"id": 34,
"status": "closed",
"description": "Fire Suppression: 10.20 Per MOD Jason, another company, doing unrelated work, removed the piping for some or all of the suppression system and did not reinstall it. Please respond to repair and ensure location has coverage. RCH",
"serviceLine": {
"id": 5,
"name": "Sprinkler",
"trade": "Fire Protection",
"icon": "https://app.servicetrade.com/image/icons/service_lines/32/SP.png",
"abbr": "SP"
},
"job": {
"id": 41,
"uri": "https://api.servicetrade.com/api/job/41",
"number": 207464,
"type": "inspection",
"name": "Job 207464"
},
"deficiency": {
"id": 21,
"uri": "http://api.servicetrade.com/api/deficiency/21",
"name": "Deficiency #21",
"description": "Broken foobars"
},
"changeOrder": {
"id": 23,
"uri": "http://localhost:8989/api/changeorder/23",
"status": "applied",
"type": "internal",
"referenceNumber": "INT-0001"
},
"contract": null,
"location": {
"id": 57,
"uri": "https://api.servicetrade.com/api/location/57",
"legacyId": 4567,
"name": "Ruby Tuesday - #4722 Kinston",
"lat": 35.264011,
"lon": -77.64003,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "3725 West Vernon Avenue",
"city": "Kinston",
"state": "NC",
"postalCode": "28504"
},
"taxable": false,
"status": "inactive"
},
"asset": null,
"windowStart": 1337140800,
"windowEnd": 1337140800,
"closedOn": 1337140800,
"created": 1337192440,
"updated": 1337192440,
"preferredTechs": [],
"preferredVendor": null,
"estimatedPrice": 12.34,
"duration": 900,
"preferredStartTime": null,
"visibility": ["public"],
"items": [],
"quoteRequests": [],
"originalWindowStart": null,
"originalWindowEnd": null
}
}
Return to Top
ServiceTemplate
The servicetemplate resource is used to update and retrieve service templates.
- Resource URL: /servicetemplate/[serviceTemplateId]
- Available Verbs: GET, POST, PUT, DELETE
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/servicetemplate |
200 |
|
GET |
/servicetemplate/123 |
200 |
|
GET |
/servicetemplate/123 |
404 |
servicetemplate 123 not found |
POST |
/servicetemplate |
200 |
servicetemplate created |
POST |
/servicetemplate |
400 |
servicetemplate not created: malformed data |
POST |
/servicetemplate |
403 |
servicetemplates cannot be created by user |
PUT |
/servicetemplate/123 |
200 |
|
PUT |
/servicetemplate/123 |
400 |
servicetemplate not updated: malformed data |
PUT |
/servicetemplate/123 |
403 |
servicetemplate 123 not editable by user |
PUT |
/servicetemplate/123 |
404 |
servicetemplate 123 not found |
DELETE |
/servicetemplate |
405 |
not allowed |
DELETE |
/servicetemplate/123 |
204 |
servicetemplate 123 deleted |
DELETE |
/servicetemplate/123 |
403 |
servicetemplate 123 not editable by user |
DELETE |
/servicetemplate/123 |
409 |
servicetemplate cannot be deleted because it has associated items |
Query Params
Name |
Type |
Value |
name |
string |
string to find in the service template name |
POST/PUT Parameters
Name |
Type |
Required for create? |
Value |
name |
string |
yes |
name for the template, used in lists |
description |
string |
yes |
description of this service |
estimatedPrice |
double |
no |
estimated price for an instance of this service |
duration |
integer |
no |
how long this service is expected to take, in seconds |
preferredTechIds |
array (integer) |
no |
technicians preferred for this work |
preferredVendorId |
integer |
no |
vendor preferred for this work |
serviceLineId |
integer |
yes |
what line this service is part of |
frequency |
string |
no |
frequency of recurrence, one of: daily, weekly, monthly, yearly |
interval |
integer |
no |
interval of recurrence. Think of it this way: "this service happens every [interval] [frequency]'s" |
repeatWeekday |
boolean |
no |
Is the recurrence tied to a specific day in a specific week (e. g. the 1st Tuesday, or the 3rd Friday). Only applies if frequency is monthly; defaults to false if not supplied. |
Returned Elements
Name |
Type |
Value |
uri |
string |
resource identifier of the servicetemplate |
id |
integer |
service template id |
name |
string |
service template name |
description |
string |
service template description |
serviceLine |
Service Line |
service line |
frequency |
string |
frequency of recurrence, one of: daily, weekly, monthly, quarterly, semiannually, yearly |
interval |
integer |
interval of recurrence. Think of it this way: "this recurrence happens every [interval] [frequency]'s" |
repeatWeekday |
boolean |
Is the recurrence tied to a specific day in a specific week (e. g. the 1st Tuesday, or the 3rd Friday). Only applies if frequency is monthly. |
preferredTechs |
User |
tech(s) preferred for this service template |
preferredVendor |
Company |
vendor preferred for this service template |
estimatedPrice |
double |
estimated price for one instance of this service template |
duration |
integer |
how long this service is expected to take, in seconds |
created |
integer |
Unix timestamp of the service template’s creation date and time |
updated |
integer |
Unix timestamp of the service template’s last update date and time |
Retrieve all service templates in your account
GET /servicetemplate
200
{
"data": {
"totalPages": 1,
"page": 1,
"serviceTemplates": [
{
"uri": "https://api.servicetrade.com/api/servicetemplate/222",
"id": 222,
"name": "Quarterly Inspection",
"description": "Inspect all the quarters, and make sure they are shiny",
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "https://api.servicetrade.com/image/icons/service_lines/32/SUPP.png"
},
"frequency": "monthly",
"interval": 3,
"repeatWeekday": false,
"preferredTechs": [],
"preferredVendor": null,
"estimatedPrice": 12.34,
"duration": 3600,
"created": 1370266418,
"updated": 1370544276
},
{
"uri": "https://api.servicetrade.com/api/servicetemplate/223",
"id": 223,
"name": "Annual Flush",
"description": "Flush all the intercoolers",
"serviceLine": {
"id": 3,
"name": "Backflow",
"trade": "Fire Protection",
"abbr": "BF",
"icon": "https://api.servicetrade.com/image/icons/service_lines/32/BF.png"
},
"frequency": "yearly",
"interval": 1,
"repeatWeekday": true,
"preferredTechs": []
"preferredVendor": null,
"estimatedPrice": null,
"duration": 0,
"created": 1370266450,
"updated": 1371456236
}
]
}
}
Retrieve one service template
GET /servicetemplate/222
200
{
"data": {
"uri": "https://api.servicetrade.com/api/servicetemplate/222",
"id": 222,
"name": "Quarterly Inspection",
"description": "Inspect all the quarters, and make sure they are shiny",
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "https://api.servicetrade.com/image/icons/service_lines/32/SUPP.png"
},
"frequency": "monthly",
"interval": 3,
"repeatWeekday": false,
"preferredTechs": [],
"preferredVendor": null,
"estimatedPrice": 12.34,
"duration": 3600,
"created": 1370266418,
"updated": 1370544276
}
}
Create a template
POST /servicetemplate
{"name": "Quarterly Inspection", "description": "Inspect all the quarters, and make sure they are shiny", "serviceLineId": 4, "frequency": "monthly", "interval": 3}
200
{
"data": {
"uri": "https://api.servicetrade.com/api/servicetemplate/222",
"id": 222,
"name": "Quarterly Inspection",
"description": "Inspect all the quarters, and make sure they are shiny",
"serviceLine": {
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"abbr": "SUPP",
"icon": "https://api.servicetrade.com/image/icons/service_lines/32/SUPP.png"
},
"frequency": "monthly",
"interval": 3,
"repeatWeekday": false,
"preferredTechs": [],
"preferredVendor": null,
"estimatedPrice": null,
"duration": null,
"created": 1370266418,
"updated": 1370266418
}
}
Return to Top
Tag
The tag resource is used to retrieve lists of tags or detailed information about a single tag. It can also be used to add a tag
to an entity or to remove it.
- Resource URL: /tag/[tagId]
- Available Verbs: GET, POST, PUT, DELETE
- Authentication Required: yes
The following entities support tags:
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/tag |
200 |
|
GET |
/tag/123 |
200 |
|
GET |
/tag/123 |
404 |
tag 123 not found |
POST |
/tag |
200 |
|
POST |
/tag |
403 |
no permission |
POST |
/tag |
404 |
tried to create a tag for an object that wasn't found |
POST |
/tag |
405 |
not allowed |
POST |
/tag/123/merge |
200 |
merge a tag into another |
POST |
/tag/123/merge |
403 |
no permission |
POST |
/tag/123/merge |
400 |
invalid params |
PUT |
/tag/123 |
200 |
rename tag |
PUT |
/tag/123 |
409 |
new tag name already in use |
PUT |
/tag/123 |
403 |
no permission |
DELETE |
/tag |
204 |
tag deleted |
DELETE |
/tag |
403 |
no permission |
DELETE |
/tag |
404 |
attempting to delete from an entity that wasn't found |
DELETE |
/tag |
405 |
not allowed |
Query Params
Name |
Type |
Required |
Value |
entityId |
integer |
No |
tags attached to this entity id only (if set, must also provide entityType) |
entityType |
entity type |
No |
tags attached to this entity type only (if set, must also provide entityId) |
name |
string |
No |
return tags with names containing this text |
counts |
boolean |
No |
if true, response includes a count of how many entities this tag is assigned to, grouped by entity type |
POST Parameters
Name |
Type |
Required |
Value |
entityId |
integer |
No |
the id of the entity to apply the tag to (if set, you must also provide entityType and either id or name) |
entityType |
integer |
No |
the type of the entity to apply the tag to (if set, you must also provide entityId and either id or name) |
id |
integer |
No |
the id of the tag you wish to apply, must also provide entityId and entityType |
name |
string |
No |
the name of the tag you wish to create - if one by that name already exists it will be returned without creating a duplicate |
Merge Parameters
The merge endpoint replaces this tag (the loser) with another (the winner) on all entities that are assigned the losing tag. The loser is then deleted.
Name |
Type |
Required |
Value |
replacementId |
integer |
Yes |
the id of the tag you wish to merge this tag into, the "winner" |
PUT Parameters
Name |
Type |
Required |
Value |
name |
string |
Yes |
the new name for this tag - must not already exist |
DELETE Parameters
Name |
Type |
Required |
Value |
entityId |
integer |
No |
the id of the entity to remove the tag from, Required unless deleting tag from ALL entities |
entityType |
integer |
No |
the type of the entity to remove the tag from, Required unless deleting tag from ALL entities |
id |
integer |
No |
the id of the tag you wish to remove, Required if no name is provided |
name |
string |
No |
the name of the tag you wish to remove, Required if no id is provided |
Returned Elements
Name |
Type |
Value |
tags |
array (Tag) |
list of tag objects |
Get all tags
GET /api/tag?counts=1
200
{
"data": {
"totalPages": 1,
"page": 1,
"tags": [
{
"uri": "https://api.servicetrade.com/api/tag/1",
"id": 1,
"name": "Mall",
"counts": [
{
"entityType": 5,
"entityName": "Company",
"count": 3
}
]
},
{
"uri": "https://api.servicetrade.com/api/tag/12",
"id": 12,
"name": "CallManagerFirst"
}
]
}
}
Get a single tag
GET /api/tag/1
200
{
"data": {
"uri": "https://api.servicetrade.com/api/tag/1",
"id": 1,
"name": "Mall"
}
}
Create a new tag
POST /api/tag?name=MyNewTag
200
{
"data": {
"uri": "https://api.servicetrade.com/api/tag/765",
"id": 765,
"name": "MyNewTag"
}
}
Attach tag to entity using name, will create tag if it doesn't already exist
POST /api/tag?name=MyNewTag&entityId=1&entityType=11
200
{
"data": {
"uri": "https://api.servicetrade.com/api/tag/765",
"id": 765,
"name": "MyNewTag"
}
}
Attach tag to entity using id
POST /api/tag/765?entityId=1&entityType=11
200
{
"data": {
"uri": "https://api.servicetrade.com/api/tag/765",
"id": 765,
"name": "MyNewTag"
}
}
Rename an existing tag
PUT /api/tag/756
{"name": "TheNewTagName"}
200
{
"data": {
"uri": "https://api.servicetrade.com/api/tag/765",
"id": 765,
"name": "TheNewTagName"
}
}
Merge a tag into another
POST /api/tag/756/merge
{"replacementId": 987}
200
{
"data": {
"uri": "https://api.servicetrade.com/api/tag/765",
"id": 987,
"name": "MyNewFavoriteTag"
}
}
Remove tag from entity using name
DELETE /api/tag?name=MyNewTag&entityId=1&entityType=11
200
Remove tag from entity using id
DELETE /api/tag/765?entityId=1&entityType=11
200
Return to Top
Tax Rate
The tax rate resource is used to retrieve estimated sales tax rates for a location.
The stateRate, countyRate, cityRate, and otherRate fields are reserved for future use, and may not be populated.
- Resource URL: /taxrate/
- Available Verbs: GET
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/taxrate |
200 |
|
Query Params
Name |
Type |
Value |
postalCode |
string |
(required) returns sales tax rate information for this postal code |
Returned Elements
Name |
Type |
Value |
taxGroupCode |
string |
sales tax group code. |
name |
string |
description of the sales tax group |
stateRate |
double |
This field is reserved for future use, and is not currently populated. |
countyRate |
double |
This field is reserved for future use, and is not currently populated. |
cityRate |
double |
This field is reserved for future use, and is not currently populated. |
otherRate |
double |
This field is reserved for future use, and is not currently populated. |
combinedRate |
double |
combined sales tax rate as a decimal. (e.g. 8.5% rate is represented as 0.085) |
Retrieve tax rates for a given postal code
GET /taxrate/?postalCode=90210
200
{
"data": {
"totalPages": 1,
"page": 1,
"taxrates": [
{
"taxGroupCode": "WAKECO",
"name": "WAKE COUNTY",
"stateRate": null,
"countyRate": null,
"cityRate": null,
"otherRate": null,
"combinedRate": 0.0725
}
]
}
}
No tax rate information found
GET /taxrate/?postalCode=99999
200
{
"data": {
"totalPages": 1,
"page": 1,
"taxrates": []
}
}
Return to Top
TaxGroup
The taxgroup resource is used to retrieve lists of tax groups or information about a single tax group.
- Resource URL: /taxgroup/[taxGroupId]
- Available Verbs: GET, POST, PUT, DELETE
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/taxgroup |
200 |
|
GET |
/taxgroup/123 |
200 |
|
GET |
/taxgroup/123 |
404 |
tax group 123 not found |
POST |
/taxgroup |
200 |
|
POST |
/taxgroup |
400 |
invalid parameters |
PUT |
/taxgroup |
405 |
not allowed |
PUT |
/taxgroup/123 |
200 |
|
PUT |
/taxgroup/123 |
400 |
invalid parameters |
PUT |
/taxgroup/123 |
404 |
tax group 123 not found |
DELETE |
/taxgroup |
405 |
not allowed |
DELETE |
/taxgroup/123 |
204 |
tax group deleted |
Query Params
Name |
Type |
Value |
code |
string |
substring to find in the tax group code |
name |
string |
substring to find in the tax group name |
state |
string |
string that exactly equals the state |
postalCode |
string |
substring to find in the tax group postal codes |
excludeTaxGroupId |
integer |
exclude the tax group with this id from the results |
POST/PUT Parameters
Name |
Type |
Required |
Value |
code |
string |
on POST |
Tax Group Code, 40 character max length |
name |
string |
on POST |
Tax Group Name, 100 characters max length |
combinedRate |
double |
on POST |
Combined tax rate as a decimal (e.g. 8.5% rate is represented as 0.085) |
state |
string |
on POST |
State abbreviation |
postalCodes |
array (string) |
no |
array of postal code strings for this group, existing values will be overwritten on PUT |
Returned Elements
Name |
Type |
Value |
code |
string |
Tax Group Code |
name |
string |
Tax Group Name |
combinedRate |
double |
Combined tax rate as a decimal (e.g. 8.5% rate is represented as 0.085) |
state |
string |
State abbreviation |
postalCodes |
array |
Array of postal codes this tax group applies to |
Retrieve all tax groups
GET /taxgroup
200
{
"data": {
"totalPages": 1,
"page": 1,
"taxGroups": [
{
"uri": "https://api.servicetrade.com/api/taxgroup/5060",
"id": 5060,
"code": "LA",
"name": "Los Angeles",
"state": "CA",
"combinedRate": 0.0975,
"postalCodes": [
"90024"
"90025",
"90034",
"90035",
"90049",
"90056",
],
"created": 1619313017,
"updated": 1619313017
},
{
"uri": "https://api.servicetrade.com/api/taxgroup/5087",
"id": 5087,
"code": "WAKE2021",
"name": "Wake County",
"state": "NC",
"combinedRate": 0.085,
"postalCodes": [
"27513",
"27607"
],
"created": 1619314698,
"updated": 1619314698
},
{
"uri": "https://api.servicetrade.com/api/taxgroup/5088",
"id": 5088,
"code": "NYC2020",
"name": "NYC Rates",
"state": "NY",
"combinedRate": 0.095,
"postalCodes": [
"10001",
"10002",
"10003",
"10004",
"10005"
],
"created": 1619315416,
"updated": 1619315416
},
{
"uri": "https://api.servicetrade.com/api/taxgroup/5089",
"id": 5089,
"code": "NYC2021",
"name": "NYC Taxes",
"state": "NY",
"combinedRate": 0.0965,
"postalCodes": [
"10001",
"10002",
"10003",
"10004",
"10005"
],
"created": 1619315416,
"updated": 1619315416
}
]
}
}
Retrieve tax groups for a given postal code
GET /taxgroup/?postalCode=10005
200
{
"data": {
"totalPages": 1,
"page": 1,
"taxGroups": [
{
"uri": "https://api.servicetrade.com/api/taxgroup/5088",
"id": 5088,
"code": "NYC2020",
"name": "NYC Rates",
"state": "NY",
"combinedRate": 0.095,
"postalCodes": [
"10001",
"10002",
"10003",
"10004",
"10005"
],
"created": 1619315416,
"updated": 1619315416
},
{
"uri": "https://api.servicetrade.com/api/taxgroup/5089",
"id": 5089,
"code": "NYC2021",
"name": "NYC Taxes",
"state": "NY",
"combinedRate": 0.0965,
"postalCodes": [
"10001",
"10002",
"10003",
"10004",
"10005"
],
"created": 1619315416,
"updated": 1619315416
}
]
}
}
Modify an existing tax group
PUT /taxgroup/5089
{"name": "Brooklyn NYC", "combinedRate": 0.0975, "postalCodes": ["11203", "11204", "11205"]}
200
{
"data": {
"uri": "https://api.servicetrade.com/api/taxgroup/5089",
"id": 5089,
"code": "brooklyn",
"name": "Brooklyn NYC",
"state": "NYC",
"combinedRate": 0.0975,
"postalCodes": [
"11203",
"11204",
"11205"
],
"created": 1619315470,
"updated": 1619453875
}
}
Create a new tax group
POST /taxgroup
{"code": "BOS", "name": "Boston", "state": "MA", "combinedRate": 0.0975, "postalCodes": ["02108", "02109", "02110", "02111", "02113"]}
200
{
"data": {
"uri": "https://api.servicetrade.com/api/taxgroup/8166",
"id": 8166,
"code": "BOS",
"name": "Boston",
"state": "MA",
"combinedRate": 0.0975,
"postalCodes": [
"02108",
"02109",
"02110",
"02111",
"02113"
],
"created": 1619454113,
"updated": 1619454113
}
}
Delete a tax group
DELETE /taxgroup/123
204
Return to Top
Terms
The terms resource is used to retrieve lists of terms or detailed information about a single set of terms.
- Resource URL: /terms/[termsId]
- Available Verbs: GET, POST, PUT
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/terms |
200 |
|
GET |
/terms/123 |
200 |
|
GET |
/terms/123 |
404 |
terms 123 not found |
POST |
/terms |
200 |
terms created |
POST |
/terms |
400 |
bad data for create |
POST |
/terms |
403 |
not allowed |
PUT |
/terms/123 |
200 |
terms updated |
PUT |
/terms/123 |
400 |
bad data for update |
PUT |
/terms/123 |
404 |
terms 123 not found (or not accessible by the user) |
PUT |
/terms/123 |
403 |
not allowed |
DELETE |
/terms |
403 |
not allowed |
DELETE |
/terms/123 |
204 |
terms deleted |
DELETE |
/terms/123 |
404 |
terms 123 not found (or not accessible by the user) |
DELETE |
/terms/123 |
409 |
terms is referenced by other entities |
Query Params
No query parameters are supported. An index call will return all terms in your account.
POST Parameters
Name |
Type |
Required |
Value |
name |
string |
yes |
The title of these terms. |
content |
string |
yes |
The content of these terms. |
PUT Parameters
Name |
Type |
Value |
name |
string |
The title of these terms. |
content |
string |
The content of these terms. |
Returned Elements
Name |
Type |
Value |
name |
string |
The title of terms. |
content |
string |
The content of terms. |
Retrieve all terms
GET /terms
200
{
"data": {
"totalPages": 1,
"page": 1,
"terms": [
{
"id": 100000000000001,
"uri": "https://api.servicetrade.com/api/terms/1100000000000001",
"name": "Job Terms",
"content": "Terative approaches to corporate strategy foster collaborative thinking to further the overall value proposition."
},
{
"id": 100000000000002,
"uri": "https://api.servicetrade.com/api/terms/100000000000002",
"name": "Quote Terms",
"content": "Leverage agile frameworks to provide a robust synopsis for high level overviews."
}
]
}
}
Retrieve one set of terms by id
GET /terms/100000000000002
200
{
"data": {
"id": 100000000000002,
"uri": "https://api.servicetrade.com/api/terms/100000000000002",
"name": "Quote Terms",
"content": "Leverage agile frameworks to provide a robust synopsis for high level overviews."
}
}
Retrieve information for a set of terms which does not exist
GET /terms/987
404
Create a new set of terms with POST
POST /terms
{"name": "Job Terms 100000000000003", "content": "Don't immanentize the eschalon."}
200
{
"data": {
"id": 100000000000003,
"uri": "https://api.servicetrade.com/api/terms/100000000000003",
"name": "Job Terms 100000000000003",
"content": "Don't immanentize the eschalon."
}
}
Modify terms with PUT
POST /terms/100000000000003
{"content": "Immanentize the eschalon."}
200
{
"data": {
"id": 100000000000003,
"uri": "https://api.servicetrade.com/api/terms/100000000000003",
"name": "Job Terms 100000000000003",
"content": "Immanentize the eschalon."
}
}
Delete Terms
DELETE /terms/100000000000003
204
Return to Top
Token
The token resource is used to generate tokens that grant specific users limited access to specific resources.
The token must then be added to the URL of the resource. For example, a Service Link URL would be:
https://app.servicetrade.com/customer/jobsummary?id=<TOKEN>
The URL for viewing a Quote would be:
https://app.servicetrade.com/quoteview/view?id=<TOKEN>
The URL for viewing an Invoice would be:
https://app.servicetrade.com/customer/invoice?id=<TOKEN>
- Resource URL: /token
- Available Verbs: GET
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/token/ |
200 |
|
GET |
/token/ |
400 |
invalid request parameters |
GET |
/token/ |
404 |
requested resource not found |
Query Params
Name |
Type |
Value |
contactId |
integer |
id of a contact to grant access to (supplied contact must have an email address) |
userId |
integer |
id of a user to grant access to |
jobId |
integer |
id of the job to grant access to |
quoteId |
integer |
id of the quote to grant access to |
invoiceId |
integer |
id of the invoice to grant access to |
changeOrderId |
integer |
id of the change order to grant access to |
The only combinations of query parameters that are valid are:
contactId & jobId
userId & jobId
contactId & quoteId
userId & quoteId
contactId & invoiceId
userId & invoiceId
contactId & changeOrderId
userId & changeOrderId
Returned Elements
Name |
Type |
Value |
token |
string |
value to be included in a request to a protected resource |
Generate a token for a contact to view a Job's Service Link
GET /token?jobId=123&contactId=456
200
{
"data": {
"token": "ol%2FR5B63qOAyvSdX1dBFb%2BObCYgKI%2FqznCdrJd9t57zoKTxqTv6Nuaa1L2Ey54Og23m06hAGUL7q8GQ%3D"
}
}
Generate a token for a contact to view a Quote
GET /token?quoteId=123&contactId=456
200
{
"data": {
"token": "loCCqViaAlPrYnI87RnnYDuKVXup2n%2FA1l%2BdTu2sDuuXsbz4b7osprjVe8VHv7l%2Bib8qGzmWZOM%3D"
}
}
Generate a token for a contact to view an Invoice
GET /token?invoiceId=1&contactId=84
200
{
"data": {
"token": "bpplYCSa6efDb6BftKPT95rvCs0Dd2gjPP2whs8OOw76JtDagmAPFU4Hc%2BjEYe3FBrvveAyZIWQduDRW"
}
}
Return to Top
User
The user resource is used to retrieve lists of users or detailed information about a single user. Only returns active users.
- Resource URL: /user/[userId]
- Available Verbs: GET, POST, PUT, DELETE
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/user |
200 |
|
GET |
/user/123 |
200 |
|
GET |
/user/123 |
404 |
user 123 not found |
GET |
/user/123/role |
200 |
get roles assigned to user |
GET |
/user/123/role |
404 |
user 123 not found |
POST |
/user |
403 |
no permission |
POST |
/user |
200 |
|
POST |
/user/123/role/456 |
200 |
assign role 456 to user 123 |
POST |
/user/123/role/456 |
400 |
invalid role |
POST |
/user/123/role/456 |
403 |
no permission |
POST |
/user/123/role/456 |
404 |
user 123 not found |
PUT |
/user/123 |
403 |
no permission |
PUT |
/user/123 |
404 |
not found |
PUT |
/user/123 |
200 |
|
DELETE |
/user |
405 |
not allowed |
DELETE |
/user/123/role/456 |
200 |
unassign role 456 from user 123 |
DELETE |
/user/123/role/456 |
400 |
invalid role |
DELETE |
/user/123/role/456 |
403 |
no permission |
DELETE |
/user/123/role/456 |
404 |
user 123 not found |
Query Params
Name |
Type |
Value |
name |
string |
returns only users whose name, username, email, or company includes this string (case insensitive) |
companyId |
integer |
returns only users who belong to the given company (will default to the logged-in user's company if not supplied) |
locationId |
integer |
returns only users who belong to the given location |
isTech |
boolean |
(optional) returns only users that are a tech (if true/1 provided) or aren't a tech (if 0/ provided). only one of isTech/isHelper/isTechOrHelper params is allowed in a request |
isHelper |
boolean |
(optional) returns only users that are a helper (if true/1 provided) or aren't a helper (if 0/ provided). only one of isTech/isHelper/isTechOrHelper params is allowed in a request |
isTechOrHelper |
boolean |
(optional) returns only users that are either a tech or a helper (if true/1 provided) or are neither a tech nor a helper (if 0/ provided). only one of isTech/isHelper/isTechOrHelper params is allowed in a request |
isSales |
boolean |
(optional) returns only users that are a salesperson (if true/1 provided) or aren't a salesperson (if false/0 provided) |
excludeUserIds |
array |
excludes these users from the potential matches |
status |
string |
comma-separated list of statuses: "active", "pending", "inactive" (will default to "active" if not supplied) |
createdBefore |
integer |
timestamp, matches records created on or before |
createdAfter |
integer |
timestamp, matches records created on or after |
updatedBefore |
integer |
timestamp, matches records updated on or before |
updatedAfter |
integer |
timestamp, matches records updated on or after |
POST Parameters
Name |
Type |
Required |
Value |
username |
string |
Yes |
username for user, must be unique |
firstName |
string |
Yes |
first name of user |
lastName |
string |
Yes |
last name of user |
password |
string |
Yes |
password for user. must be 8 or more characters long and inlude at least one letter and at least one number |
email |
string |
Yes |
email for user |
phone |
string |
No |
phone number for user |
companyId |
integer |
Yes |
user's company |
locationId |
integer |
Yes |
user's home office |
details |
string |
No |
brief information about this user, visible to the public. |
status |
string |
No |
user's status, one of: active, inactive, pending, shadow. defaults to active if not provided. |
isSales |
boolean |
No |
is the user a salesperson? defaults to no. |
timezone |
string |
No |
user timezone identifier; if not provided, the account's time zone is used instead |
serviceLineIds |
array (ServiceLine) |
No |
the service lines a user is capable of providing service for. defaults to none. |
The user status "shadow" is reserved for system users and should not be used for users who need user interface or API access.
PUT Parameters
Name |
Type |
Value |
firstName |
string |
first name of user |
lastName |
string |
last name of user |
password |
string |
password for user. must be 8 or more characters long and inlude at least one letter and at least one number |
email |
string |
email for user |
phone |
string |
phone number for user |
companyId |
integer |
user's company |
locationId |
integer |
user's home office |
details |
string |
brief information about this user, visible to the public. |
status |
string |
user's status, one of: active, inactive, pending, shadow. defaults to active if not provided. |
isSales |
boolean |
is the user a salesperson? defaults to no. |
timezone |
string |
user timezone identifier; if not provided, the account's time zone is used instead |
serviceLineIds |
array (ServiceLine) |
the service lines a user is capable of providing service for. defaults to none. |
The user status "shadow" is reserved for system users and should not be used for users who need user interface or API access.
Returned Elements
Name |
Type |
Value |
users |
array (User) |
list of user objects |
name |
string |
user full name |
status |
string |
user status |
email |
string |
user email address |
avatar |
array (objects) |
user avatar URIs |
firstName |
string |
user first name |
lastName |
string |
user last name |
username |
string |
user login name |
phone |
string |
user phone number |
timezone |
string |
user timezone identifier |
isTech |
boolean |
is this user a technician? |
isSales |
boolean |
is this user a sales representative? |
isHelper |
boolean |
is this user a helper? |
company |
Company |
company to which this user belongs |
location |
Location |
location of this user's primary office |
account |
Account |
account to which this user belongs |
details |
string |
brief information about this user, visible to the public |
activities |
array |
list of permission activities this user has |
serviceLines |
array (Service Line) |
list of service lines provided by this user |
roles |
array (Role) |
list of roles applied to this user |
externalIds |
object |
a key/value object of external system ids, only returned if account has external integrations defined |
created |
integer |
Unix timestamp of this record's creation time |
updated |
integer |
Unix timestamp of when this record was last updated |
Retrieve all users that match a given name
GET /user?name=art
200
{
"data": {
"totalPages": 1,
"page": 1,
"users": [
{
"id": 9,
"uri": "https://api.servicetrade.com/api/user/6",
"name": "Art Bernard",
"status": "active",
"email": "art@example.com",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"firstName": "Art",
"lastName": "Bernard",
"username": "abernard",
"phone": "9197063119",
"timezone": "America/New_York",
"isTech": false,
"isSales": false,
"isHelper": false,
"company": {
"id": 321,
"uri": "https://api.servicetrade.com/api/company/321",
"name": "Fire Inspection Pros, Inc."
},
"location": {
"id": 987,
"uri": "https://api.servicetrade.com/api/location/987",
"name": "Fire Inspection Pros HQ",
"lat": 28.420369,
"lon": -81.580975,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "3 Blocks Away",
"city": "Nearsville",
"state": "TX",
"postalCode": "78134"
},
"taxable": false,
"status": "active"
},
"account": {
"id": 567,
"name": "Fire Inspection Pros, Inc."
},
"details": "Certified #NFPA22381. Licensed and insured.",
"activities": [
"company.create",
"company.edit",
"job.manage"
],
"serviceLines": [],
"roles": [
{
"id": 11,
"name": "Account Tech"
}
],
"externalIds": {
'externalSys1': 'abc123'
},
"created": 1399993795,
"updated": 1399994065
},
{
"id": 10,
"uri": "https://api.servicetrade.com/api/user/10",
"name": "Arthur Dent",
"status": "active",
"email": "arthur.dent@example.com",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"firstName": "Arthur",
"lastName": "Dent",
"username": "adent",
"phone": "9197065674",
"timezone": "America/Los_Angeles",
"isTech": false,
"isSales": false,
"isHelper": false,
"company": {
"id": 42,
"uri": "https://api.servicetrade.com/api/company/42",
"name": "Vogon Alarm Services, Ltd."
},
"location": {
"id": 645,
"uri": "https://api.servicetrade.com/api/location/645",
"name": "AlarmCert - Triangle Office",
"lat": 38.909143,
"lon": -104.972086,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "8240 West Hwy 24",
"city": "Cascade",
"state": "CO",
"postalCode": "80809"
},
"taxable": false,
"status": "active"
},
"account": {
"id": 2,
"name": "AlarmCert, LLC"
},
"details": "Certified #ADT38211. Licensed and insured.",
"activities": [
"company.create",
"company.edit",
"job.manage"
],
"serviceLines": [],
"roles": [
{
"id": 11,
"name": "Account Tech"
}
],
"externalIds": {
'externalSys1': 'abc124'
},
"created": 1399993795,
"updated": 1399994065
}
]
}
}
No user matches found
GET /user?name=ygiuygiug
200
{
"data": {
"totalPages": 1,
"page": 1,
"users": []
}
}
Retrieve information for a single user
GET /user/33
200
{
"data": {
"id": 33,
"uri": "https://api.servicetrade.com/api/user/33",
"name": "Chip Dale",
"status": "active",
"email": "rescueranger@example.com",
"avatar": {
"small": "https://servicetrade.com/image/avatar-small.png",
"medium": "https://servicetrade.com/image/avatar-medium.png",
"large": "https://servicetrade.com/image/avatar-large.png"
},
"firstName": "Chip",
"lastName": "Dale",
"username": "rescueranger",
"phone": "9197348547",
"timezone": "America/New_York",
"isTech": true,
"isSales": false,
"isHelper": false,
"company": {
"id": 631,
"uri": "https://api.servicetrade.com/api/company/631",
"name": "Sprinkler Repair Rescue"
},
"location": {
"id": 742,
"uri": "https://api.servicetrade.com/api/location/742",
"name": "Sprinkler Repair Rescue",
"lat": 33.045085,
"lon": -97.01844,
"phoneNumber": "",
"email": "",
"primaryContact": null,
"address": {
"street": "1000 Civic Circle",
"city": "Lewisville",
"state": "TX",
"postalCode": "75067"
},
"taxable": false,
"status": "active"
},
"account": {
"id": 453,
"name": "National Sprinkler Management, LLC"
}
"details": "Professional Sprinkler Rescuer",
"activities": [
"company.create",
"company.edit",
"job.manage"
],
"serviceLines": [
{
"id": 2,
"name": "Emergency / Exit Lights",
"trade": "Fire Protection",
"icon": "https://app.servicetrade.com/image/icons/service_lines/32/ELIGHT.png",
"abbr": "ELIGHT"
},
{
"id": 3,
"name": "Portable Extinguishers",
"trade": "Fire Protection",
"icon": "https://app.servicetrade.com/image/icons/service_lines/32/EXT.png",
"abbr": "EXT"
},
{
"id": 4,
"name": "Fire Suppression",
"trade": "Fire Protection",
"icon": "https://app.servicetrade.com/image/icons/service_lines/32/SUPP.png",
"abbr": "SUPP"
}
],
"roles": [
{
"id": 11,
"name": "Account Tech"
}
],
"externalIds": {
'externalSys1': 'abc122'
},
"created": 1399993795,
"updated": 1399994065
}
}
Retrieve information for a user which does not exist
GET /user/987
404
Create a new user with POST
POST /user
{"username": "New87687", "firstName": "Geordi", "lastName": "laForge", "password": "tribbles123", "email": "geordi@example.com", "companyId": 34, "locationId": 71, "status": "active"}
200
{
"data": {
"id": 1595,
"uri": "https://api.servicetrade.com/api/user/1595",
"name": "Geordi laForge",
"status": "active",
"avatar": {
"small": "https://api.servicetrade.com/image/avatar-small.png",
"medium": "https://api.servicetrade.com/image/avatar-medium.png",
"large": "https://api.servicetrade.com/image/avatar-large.png"
},
"firstName": "Geordi",
"lastName": "laForge",
"username": "New87687",
"email": "geordi@example.com",
"phone": "",
"timezone": "America/New_York",
"isTech": false,
"isSales": false,
"isHelper": false,
"company": {
"id": 34,
"uri": "https://api.servicetrade.com/api/company/34",
"name": "StandAlone Safety"
},
"location": {
"id": 71,
"uri": "https://api.servicetrade.com/api/location/71",
"name": "StandAlone Charlottesville",
"legacyId": null,
"lat": 38.066937,
"lon": -78.487234,
"phoneNumber": "(434) 555-3211",
"email": "contact+location@example.com",
"primaryContact": {
"id": 71,
"uri": "https://api.servicetrade.com/api/contact/71",
"firstName": "Stan",
"lastName": "Dalone",
"phone": "434-555-3211",
"mobile": "",
"alternatePhone": "",
"email": "contact+location@example.com",
"type": "management"
},
"address": {
"street": "1240 Seminole Trail",
"city": "Charlottesville",
"state": "VA",
"postalCode": "22901"
},
"taxable": false,
"status": "active"
},
"account": {
"id": 3,
"name": "StandAlone"
},
"details": null,
"activities": [],
"serviceLines": [],
"roles": [
{
"id": 11,
"name": "Account Tech"
}
],
"externalIds": {
"peachtree": "",
},
"created": 1399993795,
"updated": 1399994065
}
}
Make changes to a user with PUT
PUT /user/1595
{"firstName": "Commander", "lastName": "Riker", "email": "commander@example.com", "locationId": 72}
200
{
"data": {
"id": 1595,
"uri": "https://api.servicetrade.com/api/user/1595",
"name": "Commander Riker",
"status": "active",
"avatar": {
"small": "https://api.servicetrade.com/image/avatar-small.png",
"medium": "https://api.servicetrade.com/image/avatar-medium.png",
"large": "https://api.servicetrade.com/image/avatar-large.png"
},
"firstName": "Commander",
"lastName": "Riker",
"username": "New87687",
"email": "commander@example.com",
"phone": "",
"timezone": "America/New_York",
"isTech": false,
"isSales": false,
"isHelper": false,
"company": {
"id": 34,
"uri": "https://api.servicetrade.com/api/company/34",
"name": "StandAlone Safety"
},
"location": {
"id": 72,
"uri": "https://api.servicetrade.com/api/location/72",
"name": "StandAlone Santa Clara",
"legacyId": null,
"lat": 37.26213,
"lon": -121.958323,
"phoneNumber": "(408) 555-3211",
"email": "contact+location@example.com",
"primaryContact": {
"id": 72,
"uri": "https://api.servicetrade.com/api/contact/72",
"firstName": "Stan",
"lastName": "Dalone",
"phone": "408-555-3211",
"mobile": "",
"alternatePhone": "",
"email": "contact+location@example.com",
"type": "management"
},
"address": {
"street": "470 Division St.",
"city": "Campbell",
"state": "CA",
"postalCode": "95008"
},
"taxable": false,
"status": "active"
},
"account": {
"id": 3,
"name": "StandAlone"
},
"details": null,
"activities": [],
"serviceLines": [],
"roles": [
{
"id": 11,
"name": "Account Tech"
}
],
"externalIds": {
"peachtree": "",
},
"created": 1399993795,
"updated": 1399994065
}
}
}
Return to Top
User Value
Retrieve or modify user-specific values
- Resource URL: /user/[userId]/value/[valueId]
- Resource URL: /uservalue/[valueId]
- Available Verbs: GET, POST, PUT, DELETE
- Authentication Required: yes
There is a fixed set of possible user-specific value names. They are:
Name |
Settable |
Description |
lastLogin |
no |
When this user last logged in. Format: DateTime |
dismissedWelcome |
no |
Has this user dismissed the dashboard page welcome message. Format: 1 or 0 |
disableClock |
yes |
Are Dispatch Board live-updates disabled. Format: 1 or 0 |
newQuotesUi |
no |
Is the user using the current quotes UI or the legacy quotes UI. Format: 1 or 0 |
search-*-index |
yes |
Most recently used search parameters for various list pages. Format: JSON object |
defaultWarehouse |
yes |
A warehouse id to be used to preselect a warehouse any time the user is presented with a warehouse selection. |
defaultEnRouteItem |
yes |
Default en route labor item for a tech. |
defaultJobPrepItem |
yes |
Default job preparation labor item for a tech. |
defaultOnSiteItem |
yes |
Default on site labor item for a tech. |
User values that are settable can be created, edited, or deleted. User values that are not settable can be read, but not created, edited, or deleted.
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/user/123/value |
200 |
|
GET |
/uservalue?userId=123 |
200 |
|
GET |
/user/123/value/456 |
200 |
|
GET |
/uservalue/456 |
200 |
|
GET |
/user/123/value/456 |
404 |
user 123 not found, or user value 456 not found on user 123 |
GET |
/uservalue/456 |
404 |
user value 456 not found |
GET |
/uservalue |
404 |
userId must be specified when searching for user values |
POST |
/uservalue |
200 |
|
POST |
/user/123/value |
200 |
|
POST |
/user/123/value |
400 |
parameters invalid |
POST |
/user/123/value |
403 |
do not have permission to modify user 123 |
POST |
/user/123/value |
404 |
user 123 not found |
PUT |
/uservalue/456 |
200 |
|
PUT |
/user/123/value/456 |
200 |
|
PUT |
/user/123/value/456 |
400 |
parameters invalid |
PUT |
/user/123/value/456 |
403 |
do not have permission to modify user 123 |
PUT |
/user/123/value/456 |
404 |
user 123 not found |
DELETE |
/user/123/value/456 |
403 |
do not have permission to modify user 123 |
DELETE |
/user/123/value/456 |
404 |
user 123 not found |
DELETE |
/user/123/value/456 |
204 |
user value deleted |
Query Params
Name |
Type |
Value |
userId |
integer |
user to which this value belongs. Required. |
POST/PUT Parameters
Name |
Type |
Required for POST |
Value |
userId |
integer |
yes |
sets the user to whom this value is belongs |
name |
string |
yes |
the name of the value to set |
value |
string |
yes |
value |
Returned Elements
Name |
Type |
Value |
id |
integer |
id of the uservalue |
uri |
string |
resource identifier of the contract |
name |
string |
the name of the value |
value |
string |
value |
user |
User |
user to which this value belongs |
Retrieve all user values for a given user
GET /user/45/value
GET /uservalue?userId=45
200
{
"data": {
"totalPages": 1,
"page": 1,
"uservalues": [
{
"id": 11,
"uri": "https://api.servicetrade.com/api/uservalue/11",
"name": "disableClock",
"value": "0",
"user": {
"id": 21,
"uri": "https://api.servicetrade.com/api/user/21",
"name": "Stan Dalone"
}
},
{
"id": 13,
"uri": "https://api.servicetrade.com/api/uservalue/13",
"name": "dismissedWelcome",
"value": "1",
"user": {
"id": 21,
"uri": "https://api.servicetrade.com/api/user/21",
"name": "Stan Dalone"
}
}
]
}
}
Set a uservalue
POST /user/21/value
{"name":"disableClock","value":1}
200
{
"data": {
"id": 11,
"uri": "https://api.servicetrade.com/api/uservalue/11",
"name": "disableClock",
"value": "1",
"user": {
"id": 21,
"uri": "https://api.servicetrade.com/api/user/21",
"name": "Stan Dalone"
}
}
}
Change a uservalue
PUT /user/21/value/11
{"value":0}
200
{
"data": {
"id": 11,
"uri": "https://api.servicetrade.com/api/uservalue/11",
"name": "disableClock",
"value": "0",
"user": {
"id": 21,
"uri": "https://api.servicetrade.com/api/user/21",
"name": "Stan Dalone"
}
}
}
Return to Top
Warehouse
The warehouse resource is used to update and retrieve warehouses.
- Resource URL: /warehouse/[warehouseId]
- Available Verbs: GET, POST, PUT
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/warehouse |
200 |
|
GET |
/warehouse/123 |
200 |
|
GET |
/warehouse/123 |
404 |
warehouse 123 not found |
POST |
/warehouse |
200 |
warehouse created |
POST |
/warehouse |
400 |
warehouse not created: malformed data |
POST |
/warehouse |
403 |
warehouses cannot be created by user |
PUT |
/warehouse/123 |
200 |
|
PUT |
/warehouse/123 |
400 |
warehouse not updated: malformed data |
PUT |
/warehouse/123 |
403 |
warehouse 123 not editable by user |
PUT |
/warehouse/123 |
404 |
warehouse 123 not found |
DELETE |
/warehouse |
405 |
not allowed |
Query Params
Name |
Type |
Value |
officeId |
integer |
id of office whose warehouses you want to see |
status |
string |
defaults to "active", or one of "active", "inactive", "all" |
createdBefore |
integer |
timestamp, matches records created on or before |
createdAfter |
integer |
timestamp, matches records created on or after |
updatedBefore |
integer |
timestamp, matches records updated on or before |
updatedAfter |
integer |
timestamp, matches records updated on or after |
POST/PUT Parameters
Name |
Type |
Required for create? |
Value |
name |
string |
yes |
name for the template, used in lists |
status |
string |
no |
one of "active", "inactive"; defaults to "active" |
officeId |
integer |
no |
locationId of office or null. Defaults to null. |
Returned Elements
Name |
Type |
Value |
uri |
string |
resource identifier of the warehouse |
id |
integer |
warehouse id |
name |
string |
warehouse name |
status |
string |
warehouse description |
office |
Location |
office that controls this warehouse |
externalIds |
object |
a key/value object of external system ids, only returned if account has external integrations defined |
created |
integer |
Unix timestamp of the warehouse’s creation date and time |
updated |
integer |
Unix timestamp of the warehouse’s last update date and time |
Get warehouse by id
GET /warehouse/100000000000002
200
{
"data": {
"id": 100000000000002,
"uri": "https://api.servicetrade.com/api/warehouse/100000000000002",
"name": "foo",
"office": null,
"status": "active",
"externalIds": {
"accouting": "abc-123"
},
"created": 1399993795,
"updated": 1399994065
}
}
Create a new warehouse
POST /warehouse
{"name":"bar"}
200
{
"data": {
"id": 100000000000018,
"uri": "https://api.servicetrade.com/api/warehouse/100000000000018",
"name": "bar",
"office": null,
"status": "active",
}
}
Make changes to an existing warehouse
PUT /warehouse/100000000000002
{"officeId": 86}
200
{
"data": {
"id": 100000000000002,
"uri": "https://api.servicetrade.com/api/warehouse/100000000000002",
"name": "foo",
"office": {
"id": 86,
"uri": "https://api.servicetrade.com/api/location/86",
"name": "Hwy 55 Burgers - Belhaven",
"legacyId": null,
"lat": 35.552137,
"lon": -76.621729,
"phoneNumber": "(252) 943-2298",
"email": "uuxiiuit+location@gmail.com",
"primaryContact": {
"id": 86,
"uri": "https://api.servicetrade.com/api/contact/86",
"firstName": "Lonnie",
"lastName": "Baxter",
"phone": "252-943-2298",
"mobile": "",
"alternatePhone": "",
"email": "email@example.com",
"type": "management"
},
"address": {
"street": "Hwy 264 East, Bypass Belhaven Crossing",
"city": "Belhaven",
"state": "NC",
"postalCode": "27810"
},
"taxable": false
},
"status": "active",
"externalIds": {
"accouting": "abc-123"
},
"created": 1399993795,
"updated": 1399994065
}
}
Return to Top
Webhook
Webhooks allow a system that integrates with the ServiceTrade API to receive notifications about updated data without polling (continually having to ask the API for new data.)
When an entity changes, a notification message is sent to a specified URL.
The message contains enough data to identify the entity, so that the integrated system may request more data from the appropriate API endpoint for that entity.
An account can set up more than one webhook.
Each webhook will independently receive each notification message that is sent.
Webhook Requirements
In order to receive messages, the webhook URL MUST:
- Be publically accessible - The webhook URL must be available on the public Internet; ServiceTrade cannot send messages to internal URLs.
- Accept HTTP POST requests - Each message will be sent as an HTTP POST request to the webhook URL.
- Respond with HTTP status code between 200-499 - If the status code is outside this range (or not received within 5 seconds), the message will be retried. After 3 unsuccessful attempts, the message will be discarded.
Each webhook URL must respond separately to each message.
URLs that do not respond successfully will be sent the message again until they do respond, or the message has been retried a maximum number of times.
Once a URL responds to a message, the message will not be sent again to that URL.
Webhook Notification Message
Each message sent to a webhook is formatted as a JSON object.
The object containing the following fields:
messageId
- uniquely identifies the message, to aid in retry handling.
timestamp
- the time at which the message was originally sent, to aid in message ordering.
data
- a JSON array. Each element of the array is a JSON object containing identifying information about the entity, the action that affected the entity ("created", "updated", or "deleted"), and the timestamp at which the action occurred. If includeChangesets flag for webhook is set to true then we send the names of the fields with the old and new values as additional attribute called changeset
.
The following example message contains notifications for several entities:
{
"messageId": "22b80b92-fdea-4c2c-8f9d-bdfb0c7bf324",
"timestamp": "1401833057",
"data": [
{
"action": "created",
"timestamp": 1401833052,
"entity": {
"type": "job",
"id": 34872,
"uri": "https://api.servicetrade.com/api/job/34872"
}
},
{
"action": "updated",
"timestamp": 1401833052,
"entity": {
"type": "invoice",
"id": 9623,
"uri": "https://api.servicetrade.com/api/invoice/9623"
}
},
{
"action": "deleted",
"timestamp": 1401833052,
"entity": {
"type": "attachment",
"id": 453845,
"uri": "https://api.servicetrade.com/api/attachment/453845"
}
}
]
}
Message Order
The order of the entities in a single message cannot be asserted.
Additionally, the order in which messages are sent/received cannot be asserted.
The system which processes the messages should handle receiving messages out of order, or even more than once.
A unique message id, a message timestamp, and a per-entity timestamp are provided to assist this.
Confirmation
Webhooks will not receive notifications until they have been confirmed.
Confirmation is an automatic process that typically takes place immediately after creation. To be confirmed, a webhook must meet all the requirements listed in 'Webhook Requirements' above.
Disabling Webhooks
A webhook can be temporarily disabled.
No messages are sent to a disabled webhook.
When the webhook is re-enabled, it will receive messages sent after the time at which it is re-enabled.
It is possible to enable and disable each webhook independently of any others.
Enabled webhooks will continue to receive messages.
Entity Changesets
Each updated
action webhook can optionally include a changeset of certain specific fields on the entity that was changed.
Changesets will be included in webhook notification messages only when the webhook's includeChangesets
flag is set to true (see 'Parameters for POST' below).
Each member of each changeset includes the following properties:
Property |
Description |
field |
The name of the field that was changed |
oldValue |
The previous value of the field, before the update was performed |
newValue |
The updated value of the field, after the update was performed |
IMPORTANT: Changeset tracking is NOT enabled on all fields on all entities. Changesets are only tracked for certain fields for specific entities, as follows:
Job
Job Item
Field |
libItemId |
quantity |
source.companyId |
source.deliveryDate |
source.status |
source.type |
source.userId |
source.value |
source.warehouseId |
The following example message contains notifications for several entities, with changesets enabled.
Note that the changeset
can be an empty array for some updated
messages, and that created
and deleted
actions do not include a changeset:
{
"messageId": "22b80b92-fdea-4c2c-8f9d-bdfb0c7bf324",
"timestamp": "1401833057",
"data": [
{
"action": "created",
"timestamp": 1401833052,
"entity": {
"type": "job",
"id": 34872,
"uri": "https://api.servicetrade.com/api/job/34872"
}
},
{
"action": "updated",
"timestamp": 1401833052,
"entity": {
"type": "invoice",
"id": 9623,
"uri": "https://api.servicetrade.com/api/invoice/9623"
},
"changeset": []
},
{
"action": "updated",
"timestamp": 1401833052,
"entity": {
"type": "job",
"id": 35769,
"uri": "https://api.servicetrade.com/api/invoice/35789"
},
"changeset": [
{
"field": "status",
"oldValue": "scheduled",
"newValue": "completed"
}
]
},
{
"action": "deleted",
"timestamp": 1401833052,
"entity": {
"type": "attachment",
"id": 453845,
"uri": "https://api.servicetrade.com/api/attachment/453845"
}
}
]
}
Entity Types
The following is a list of entities which will send webhook notifications:
- Appointments
- Attachments with any of the following purposes:
- Generic Attachment
- Job Paperwork
- Job Picture
- Work Acknowledgement
- Job Invoice
- Job Vendor Bill
- Clock Events
- Companies
- Contacts
- Deficiencies
- Invoices
- Jobs
- Job Items (a job update webhook message is also sent for any job item creates, updates, or deletes)
- Locations
- Quotes
- Quote Items
- Users
Webhook API
The webhook resource is used to retrieve the list of webhooks for an account or detailed information about a single webhook.
- Resource URL: /webhook/[webhookId]
- Available Verbs: GET, POST, PUT, DELETE
- Authentication Required: yes
Response Codes
Verb |
Example URL |
Code |
Reason |
GET |
/webhook |
200 |
|
GET |
/webhook/123 |
200 |
|
GET |
/webhook/123 |
404 |
webhook not found |
POST |
/webhook |
200 |
webhook created |
POST |
/webhook |
400 |
bad data given |
POST |
/webhook |
403 |
no permission to create webhooks |
PUT |
/webhook/123 |
200 |
|
PUT |
/webhook/123 |
404 |
webhook not found |
PUT |
/webhook/123 |
400 |
bad data given |
PUT |
/webhook/123 |
403 |
no permission to update hook |
DELETE |
/webhook/123 |
200 |
|
DELETE |
/webhook/123 |
404 |
webhook not found |
DELETE |
/webhook/123 |
403 |
no permission to delete hook |
Parameters for POST
Name |
Type |
Required |
Value |
hookUrl |
string |
yes |
url endpoint of the webhook |
enabled |
boolean |
no |
is the endpoint currently enabled? default: true |
includeChangesets |
boolean |
no |
when this flag is set to true, a changeset attribute will be included in each updated action webhook message; see 'Entity Changesets' above. default: false |
Parameters for PUT
Name |
Type |
Required |
Value |
enabled |
boolean |
no |
is the endpoint currently enabled? |
includeChangesets |
boolean |
no |
when this flag is set to true, a changeset attribute will be included in each updated action webhook message; see 'Entity Changesets' above. default: false |
Returned Elements
Name |
Type |
Value |
webhooks |
array (Webhook) |
list of webhook objects |
Retrieve all webhooks
GET /webhook
200
{
"data": {
"totalPages": 1,
"page": 1,
"webhooks": [
{
"id": 9,
"uri": "https://api.servicetrade.com/api/webhook/9",
"hookUrl": "http://www.example.com/catcher?xuid=2346",
"enabled": true,
"confirmed": true,
"includeChangesets": true
},
{
"id": 235,
"uri": "https://api.servicetrade.com/api/webhook/235",
"hookUrl": "http://app.example.com/accounting/234536345/integration",
"enabled": false,
"confirmed": true,
"includeChangesets": false
}
]
}
}
No webhooks
GET /webhook
200
{
"data": {
"totalPages": 1,
"page": 1,
"webhooks": []
}
}
Retrieve information for a single webhook
GET /webhook/9
200
{
"data": {
"id": 9,
"uri": "https://api.servicetrade.com/api/webhook/9",
"hookUrl": "http://app.example.com/accounting/234536345/integration",
"enabled": true,
"confirmed": true,
"includeChangesets": true
}
}
Retrieve information for a webhook which does not exist
GET /webhook/45588
404
Create a new webhook
POST /webhook
{"hookUrl":"http://app.example.com/accounting/234536345/integration"}
200
{
"data": {
"id": 235,
"uri": "https://api.servicetrade.com/api/webhook/235",
"hookUrl": "http://app.example.com/accounting/234536345/integration",
"enabled": true,
"confirmed": false,
"includeChangesets": false
}
}
Disable a webhook
PUT /webhook/235
{"enabled":false}
200
{
"data": {
"id": 235,
"uri": "https://api.servicetrade.com/api/webhook/235",
"hookUrl": "http://app.example.com/accounting/234536345/integration",
"enabled": false,
"confirmed": true,
"includeChangesets": false
}
}
Return to Top