ServiceTrade API

Getting Started
Conventions and Units
Embedded Object Reference
Resource Reference
1. Account Settings
2. Activity
3. Appointment
4. Asset
5. Asset Definition
6. Attachment
7. Authentication
8. Brand
9. Budget
10. Budget Category
11. Budget Line Item
12. Clockin/Clockout
13. Comment
14. Company
15. Contact
16. Contract
17. Contract Rule
18. Deficiency
19. EULA
20. ExternalId
21. ExternalSync
22. ExternalSystem
23. Heartbeat
24. History
25. Import
26. Invoice
27. Invoice Item
28. InvoiceRecurrence
29. InvoiceRecurrence Item
30. Job
31. Job Context
32. JobItem
33. LegacyLookup
34. LibItem
35. Location
36. MasterAgreement
37. Message
38. Payment
39. Payment terms
40. Quote
41. Quote Item
42. QuoteRequest
43. QuoteTemplate
44. QuoteTemplate Item
45. Region
46. Role
47. Service Item
48. Service Line
49. ServiceRecurrence
50. ServiceRequest
51. ServiceTemplate
52. Tag
53. Tax Rate
54. TaxGroup
55. Terms
56. Token
57. User
58. User Value
59. Warehouse
60. 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
45	Budget
46	Budget Category

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

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

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
assetDefinitions	array	Asset Definition ids selected 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"
        ],
        "assetDefinitions": [
            9,
            16,
            17
        ],
        "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.

Asset
Brand
Company
Contract
Deficiency
Import
Job*
Location
Quote
Quote Request
Service Request
User

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	not permissioned
POST	/budget/123/revise	404	budget not found
POST	/budget/123/revise	409	budget is not in a revisible state
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	on 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

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
        }
    }
}

Modify an existing budget

POST /budget/67/revise

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": "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
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

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": "http://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

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.

Company*
Deficiency
Invoice
Job*
Location*
Quote*
Contract
Service Request

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	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)
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.
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
location	Location	contract only applies to this location 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"
                },
                "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"
                },
                "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,
                "location": 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,
        "location": 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,
        "location": 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,
        "location": 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,
        "location": 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,
        "location": 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

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]
- Available Verbs: GET
Resource URL: /externalid/[entityType]/[entityId]/[externalSystem]
- Available Verbs: GET, POST, PUT
Resource URL: /externalid/[entityType]/[externalSystem]/[value]
Resource URL: /externalid/[entityType]/[externalSystem]/?value=[value]
- Available Verbs: GET

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

Name	Type	Value

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: 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 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 statues: open, in_progress, closed, void, canceled
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
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)
serviceLineId	integer	what line of service this request is for
status	string	(optional) one of open, in_progress, closed, canceled, void (defaults to 'open')
jobId	integer	(optional) assigns the serviceRequest to a specific job
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
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)
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
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"
                },
                "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"
        },
        "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"
        },
        "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:

Asset
Company
Contract
Deficiency
Invoice
Job
Location
Quote

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

The only combinations of query parameters that are valid are:

contactId & jobId
userId & jobId
contactId & quoteId
userId & quoteId
contactId & invoiceId
userId & invoiceId

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	warhouse id
name	string	warhouse name
status	string	warhouse 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 warhouse’s creation date and time
updated	integer	Unix timestamp of the warhouse’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

Field
status

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

ServiceTrade API

Table of Contents

Getting Started

Requests

Here is a sample HTTP request

Response Codes Common to All Requests

Returned Elements Common to All Requests

Here is a sample response:

Conventions and Units

Pagination

Dates and Times

Distance

Latitude and Longitude

Constants

Entity Types

Attachment Purpose

Embedded Object Reference

Account

Account Type

Activity

Address

Appointment

Asset

Asset Definition

Brand

Budget

Budget Category

Budget Line Item

Company

Deficiency

Contact

Invoice

Job

Job Item

Invoice Item

Invoice Recurrence

Invoice Recurrence Item

LibItem

Location

Payment Terms

Quote

Quote Item

Quote Template Item

Quote Request

Role

Region

Service Item

Service Line

Service Recurrence

Service Request

Service Template

Tag

Tax Group

Terms

User

Webhook

Resource Reference

Account Settings

Response Codes

Returned Elements

Retrieve user account settings

Activity

Response Codes

Returned Elements

Retrieve all available activities

Retrieve information for a single activity

Retrieve information for an activity which does not exist

Appointment

Response Codes

Query Params

Parameters for POST

Parameters for POST appointment/servicerequest

Parameters for PUT

Returned Elements

Retrieve all appointments that match a given job number

Retrieve all appointments in a given area, includes the distance from given coordinates

No appointment matches found

Retrieve information for a single appointment

Retrieve information for a appointment which does not exist

Create an appointment for a job