TOP

ServiceTrade API

Table of Contents

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

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

Company

Name Type Value
id integer id of the company
uri string resource identifier of the company
name string name of the company

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

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

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.

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

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.

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
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 integer 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"
                },
                "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"
                        }
                    }
                ],
                "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"
                },
                "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"
                        }
                    }
                ],
                "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"
        },
        "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"
                }
            }
        ],
        "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"
        },
        "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"
                }
            }
        ],
        "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.

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

Note: locationId, jobId or appointmentId 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.

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]" />

The following entities support attachments. Starred resources also have dedicated attachment endpoints; when using these resource-specific endpoints, it is unnecessary to provide an entityId and entityType parameter, unless otherwise noted.

Response Codes

Verb Example URL Code Reason
GET /attachment 200
GET /attachment 405 missing required query params
GET /attachment/123 200
GET /attachment/123 404 attachment 123 not found (or not accessible by the user)
GET /attachment/123/thumbnail 200
GET /attachment/123/thunbnail 404 attachment 123 not found (or not accessible by the user)
POST /attachment 200 attachment created
POST /attachment 400 invalid parameters or error uploading or processing the attachment
POST /attachment/123 200 update the attachment
POST /attachment/123 404 attachment 123 not found (or not accessible by the user)
PUT /attachment 405 not allowed
PUT /attachment/123 200 update the attachment
PUT /attachment/123 404 attachment 123 not found (or not accessible by the user)
PUT /attachment/123 404 attachment not found (or not accessible by the user)
PUT /attachment/123 403 attachment not editable by the user
DELETE /attachment 405 not allowed
DELETE /attachment/123 204 attachment deleted
DELETE /attachment/123 404 attachment not found (or not accessible by the user)
DELETE /attachment/123 403 attachment not editable by the user

Query Params

Name Type Value
entityId integer id of the entity to which the file is attached (required)
entityType entity type entity type constant of the entity to which the file is attached (required)
purposeId attachment purpose type only return attachments with this purpose
includeRelatedEntities boolean include attachments of service requests related to job/quote (If not job or quote then flag is ignored).
createdAfter integer created on or after this timestamp
createdBefore integer created on or before this timestamp
updatedAfter integer updated on or after this timestamp
updatedBefore integer updated on or before this timestamp

Parameters for POST

Name Type Required Value
meta[] array form encoded array of values
description string description of the content of the attachment
jsonp string name of the Javascript callback in which to wrap the response
purposeId attachment purpose type yes purpose constant for the attachment (cannot be updated)
entityId integer yes id of the entity to attach to (cannot be updated)
entityType entity type yes entity type constant of the entity to attach to (cannot be updated)
visibility array(string) visibility granted to these types of viewers outside of the account; combination of: public, customer, subcontractor. "public" indicates global visibility and overrides the other values. Will default to account default if no value is provided on POST.

Returned Elements

Name Type Value
uri string resource identifier of the attachment
id integer attachment id
contentUrl string full url to the binary data content of the attachment
checksum string MD5 checksum of the binary data content
meta object context specific metadata about the attachment, as a JSON object
fileName string human readable file name (display name)
fileType string attachment MIME type
description string
purposeId attachment purpose type attachment context (e. g. deficiency picture, invoice document)
purpose string human readable purpose
visibility array(string) visibility granted to these types of viewers outside of the account; combination of: public, customer, subcontractor. "public" indicates global visibility and overrides the other values.
created integer Unix timestamp of the attachment’s creation date and time
updated integer Unix timestamp of the attachment’s last update
entity.uri string resource identifier of the entity to which this attachment is attached
entity.id integer id of the entity to which this attachment is attached
entity.type entity type entity type constant
creator User resource identifier of the user who created the attachment

Retrieve attachment 10

GET /attachment/10

200
{
    "data": {
        "uri": "https://api.servicetrade.com/api/attachment/10",
        "id": 10,
        "contentUrl": "http://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": "http://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":"http:\/\/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": "http://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": "http://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": "http://s3.amazonaws.com/snaap-attachments/10_f8afb9b11d8b9bd795e1a01774cfe6be.png",
                "medium": "http://s3.amazonaws.com/snaap-attachments/10_62aca89a93a4974f10ef0297c738bef6.png",
                "large": "http://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).

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.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,
      "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,
      "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.

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

Clockin/Clockout

The clockin and clockout resources are used to clock in and out of a job, or to retrieve information about clock events.

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

NOTE: If jobId parameter is provided and type parameter is not provided, results will be returned as matched pairs of clock events (where each clock in is matched with its corresponding clock out). Otherwise, a flat list of clock events will be returned.

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 ivr objects
pairedEvents array (object) list of pairs of job ivr objects
activityTime array (object) list of total times spent in each activity
uri string resource identifier for the given ivr event
id string ivr 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

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"
          }
        },
        "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"
          }
        },
        "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"
          }
        },
        "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"
      }
    },
    "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"
      }
    },
    "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"
      }
    },
    "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"
      }
    },
    "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"
              }
            },
            "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"
              }
            },
            "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"
              }
            },
            "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"
              }
            },
            "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
          }
        }
    ]
  }
}

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"
          }
        },
        "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"
          }
        },
        "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.)

Comment visibility is a combination of privacy level and context. One or more of the following visibility flags may be applied to a comment: 'public', 'schedule', 'tech' , 'billing'. Comments not flagged as 'public', are only visible to users belonging to the same company as the comment's author. Comments flagged with 'schedule' are displayed more prominently in places where scheduling activities are being performed. Comments flagged as 'tech' are displayed more prominently for in places where technicians are likely to use them (such as in the tech mobile applications). Comments flagged with 'billing' are displayed more prominently in places where billing activities are being performed.

The following entities support comments. Starred resources also have dedicated comment endpoints; when using these resource-specific endpoints, it is unnecessary to provide an entityId and entityType parameter, unless otherwise noted.

Cascaded Comments

Comments for some types of entities may include "cascaded" comments that are inherited from their parent records, as follows:

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"
                }
            }
        },
        {
            "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"
                }
            }
        }
    ]
}

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"
                }
            }
        },
        {
            "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"
                }
            }
        },
        {
            "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"
                }
            }
        },
    ]
}

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"
                }
            }
        },
        {
            "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"
                }
            }
        }
    ]
}

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

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

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

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.

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')
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'), '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.

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

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

}

Return to Top

Contract

The contract resource is used to retrieve lists of contracts or detailed information about a single contract.

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"
                },
                "customer": {
                    "id": 36,
                    "uri": "https://api.servicetrade.com/api/company/36",
                    "name": "Hwy 55 Burgers"
                },
                "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"
                },
                "customer": {
                    "id": 36,
                    "uri": "https://api.servicetrade.com/api/company/36",
                    "name": "Hwy 55 Burgers"
                },
                "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"
        },
        "customer": {
            "id": 36,
            "uri": "https://api.servicetrade.com/api/company/36",
            "name": "Hwy 55 Burgers"
        },
        "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"
        },
        "customer": {
            "id": 36,
            "uri": "https://api.servicetrade.com/api/company/36",
            "name": "Hwy 55 Burgers"
        },
        "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"
        },
        "customer": {
            "id": 36,
            "uri": "https://api.servicetrade.com/api/company/36",
            "name": "Hwy 55 Burgers"
        },
        "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"
        },
        "customer": {
            "id": 34,
            "uri": "https://api.servicetrade.com/api/company/34",
            "name": "StandAlone Safety"
        },
        "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"
        },
        "customer": {
            "id": 36,
            "uri": "https://api.servicetrade.com/api/company/36",
            "name": "Hwy 55 Burgers"
        },
        "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.

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.

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"
                    }
                },
                "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"
                    }
                }
                "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"
                    }
                },
                "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"
            }
        },
        "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"
        }
    },
    "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"
            }
        },
        "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.

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

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.

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"
                    }
                },
                "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"
            }
        },
        "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.

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.

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.

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

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

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

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.

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", "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 "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. 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", "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"
            },
            "vendor": {
                "id": 6,
                "name": "DunnWell",
                "uri": "https://api.servicetrade.com/api/company/6"
            },
            "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"
                }
            },
            "customer": {
                "id": 6,
                "name": "DunnWell",
                "uri": "https://api.servicetrade.com/api/company/6"
            }
            "vendor": {
                "id": 9,
                "name": "Super Awesome Company, Inc",
                "uri": "https://api.servicetrade.com/api/company/9"
            },
            "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"
            }
        },
        "customer": {
            "id": 6,
            "name": "DunnWell",
            "uri": "https://api.servicetrade.com/api/company/6"
        },
        "vendor": {
            "id": 9,
            "name": "Super Awesome Company, Inc",
            "uri": "https://api.servicetrade.com/api/company/9"
        },
        "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"
            }
        },
        "customer": {
            "id": 6,
            "name": "DunnWell",
            "uri": "https://api.servicetrade.com/api/company/6"
        },
        "vendor": {
            "id": 9,
            "name": "Super Awesome Company, Inc",
            "uri": "https://api.servicetrade.com/api/company/9"
        },
        "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.

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.

Note that an invoice recurrence can be in three possible states:

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"
                    },
                    "vendor": {
                        "id": 31,
                        "uri": "https://api.servicetrade.com/api/company/313",
                        "name": "Lawn Shield Services"
                    },
                    "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"
                    },
                    "vendor": {
                        "id": 31,
                        "uri": "https://api.servicetrade.com/api/company/313",
                        "name": "Lawn Shield Services"
                    },
                    "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"
        },
        "vendor": {
            "id": 31,
            "uri": "https://api.servicetrade.com/api/company/313",
            "name": "Lawn Shield Services"
        },
        "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"
        },
        "vendor": {
            "id": 34,
            "uri": "http://api.servicetrade.com/api/company/34",
            "name": "StandAlone Safety"
        },
        "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.

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.

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

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
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
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"
                    },
                    "customer": {
                        "id": 39,
                        "uri": "https://api.servicetrade.com/api/company/39",
                        "name": "Big Bang Burger Bar"
                    },
                    "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"
                        }
                    }
                    "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"
                        }
                    }
                    "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,
                    "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"
                    },
                    "customer": {
                        "id": 39,
                        "uri": "https://api.servicetrade.com/api/company/39",
                        "name": "Big Bang Burger Bar"
                    },
                    "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,
                    "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"
                                }
                            }
                        ],
                        "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"
                    },
                    "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"
                    },
                    "customer": {
                        "id": 39,
                        "uri": "https://api.servicetrade.com/api/company/39",
                        "name": "Big Bang Burger Bar"
                    },
                    "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,
                    "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,
                    "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"
                    },
                    "customer": {
                        "id": 39,
                        "uri": "https://api.servicetrade.com/api/company/39",
                        "name": "Big Bang Burger Bar"
                    },
                    "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,
                    "currentAppointment": null,
                    "assignedOffice": null,
                    "offices": [],
                    "tags": [],
                    "externalIds": {
                        "peachtree": "332-FOOSBAR",
                        "salesforce": "na1.salesforce.com/01I90000000jOLr"
                    },
                    "terms": null,
                    "contract": null,
                    "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"
                    },
                    "customer": {
                        "id": 39,
                        "uri": "https://api.servicetrade.com/api/company/39",
                        "name": "Big Bang Burger Bar"
                    },
                    "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,
                    "currentAppointment": null,
                    "assignedOffice": null,
                    "offices": [],
                    "tags": [],
                    "externalIds": {
                        "peachtree": "332-FOOSBAR",
                        "salesforce": "na1.salesforce.com/01I90000000jOLr"
                    },
                    "terms": null,
                    "contract": null,
                    "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"
                    },
                    "customer": {
                        "id": 39,
                        "uri": "https://api.servicetrade.com/api/company/39",
                        "name": "Big Bang Burger Bar"
                    },
                    "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,
                    "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,
                    "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"
                    },
                    "customer": {
                        "id": 39,
                        "uri": "https://api.servicetrade.com/api/company/39",
                        "name": "Big Bang Burger Bar"
                    },
                    "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,
                    "currentAppointment": null,
                    "assignedOffice": null,
                    "offices": [],
                    "tags": [],
                    "externalIds": {
                        "peachtree": "332-FOOSBAR",
                        "salesforce": "na1.salesforce.com/01I90000000jOLr"
                    },
                    "terms": null,
                    "contract": null,
                    "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"
                    },
                    "customer": {
                        "id": 39,
                        "uri": "https://api.servicetrade.com/api/company/39",
                        "name": "Big Bang Burger Bar"
                    },
                    "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,
                    "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,
                    "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"
            },
            "customer": {
                "id": 39,
                "uri": "https://api.servicetrade.com/api/company/39",
                "name": "Big Bang Burger Bar"
            },
            "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"
                }
            },
            "sales": 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,
            "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"
                    },
                    "customer": {
                        "id": 39,
                        "uri": "https://api.servicetrade.com/api/company/39",
                        "name": "Big Bang Burger Bar"
                    },
                    "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,
                    "assignedOffice": null,
                    "offices": [],
                    "tags": [],
                    "externalIds": {
                        "peachtree": "332-FOOSBAR",
                        "salesforce": "na1.salesforce.com/01I90000000jOLr"
                    },
                    "terms": null,
                    "contract": null,
                    "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"
                    },
                    "customer": {
                        "id": 39,
                        "uri": "https://api.servicetrade.com/api/company/39",
                        "name": "Big Bang Burger Bar"
                    },
                    "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,
                    "assignedOffice": null,
                    "offices": [],
                    "tags": [],
                    "externalIds": {
                        "peachtree": "332-FOOSBAR",
                        "salesforce": "na1.salesforce.com/01I90000000jOLr"
                    },
                    "terms": null,
                    "contract": null,
                    "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"
                    },
                    "customer": {
                        "id": 39,
                        "uri": "https://api.servicetrade.com/api/company/39",
                        "name": "Big Bang Burger Bar"
                    },
                    "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,
                    "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,
                    "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.

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.

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.

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.

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 on POST 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.

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'), '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
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.

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.

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"
            }
        },
        "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"
            }
        },
        "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.

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

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.

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
PUT /quote 200
PUT /quote 400 invalid post 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", "items", "noprices", "time_and_materials", "by_type", "type_detail"). Defaults to ("public", "items"). 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 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", "items", "noprices", "time_and_materials", "by_type", "type_detail"). Defaults to ("public", "items"). 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

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", "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"
                    },
                    "vendor": {
                        "id": 9,
                        "name": "Super Awesome Company, Inc",
                        "uri": "https://api.servicetrade.com/api/company/9"
                    },
                    "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"
                    },
                    "vendor": {
                        "id": 16,
                        "name": "Dragon Fire Systems",
                        "uri": "https://api.servicetrade.com/api/company/16"
                    },
                    "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"
            },
            "vendor": {
                "id": 9,
                "name": "Super Awesome Company, Inc",
                "uri": "https://api.servicetrade.com/api/company/9"
            },
            "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"
                    },
                    "vendor": {
                        "id": 9,
                        "name": "Super Awesome Company, Inc",
                        "uri": "https://api.servicetrade.com/api/company/9"
                    },
                    "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"
                    },
                    "vendor": {
                        "id": 9,
                        "name": "Super Awesome Company, Inc",
                        "uri": "https://api.servicetrade.com/api/company/9"
                    },
                    "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"
                    },
                    "vendor": {
                        "id": 9,
                        "name": "Super Awesome Company, Inc",
                        "uri": "https://api.servicetrade.com/api/company/9"
                    },
                    "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"
                },
                "vendor": {
                    "id": 9,
                    "name": "Super Awesome Company, Inc",
                    "uri": "https://api.servicetrade.com/api/company/9"
                },
                "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"
                },
                "vendor": {
                    "id": 9,
                    "name": "Super Awesome Company, Inc",
                    "uri": "https://api.servicetrade.com/api/company/9"
                },
                "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"
        },
        "vendor": {
            "id": 34,
            "uri": "https://api.servicetrade.com/api/company/34",
            "name": "StandAlone Safety"
        },
        "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"
        },
        "vendor": {
                "id": 9,
                "name": "Super Awesome Company, Inc",
                "uri": "https://api.servicetrade.com/api/company/9"
        },
        "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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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)
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
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.

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.

The following entities support tags:

Response Codes

Verb Example URL Code Reason
GET /tag 200
GET /tag/123 200
GET /tag/123 404 tag 123 not found
POST /tag 200
POST /tag 403 no permission
POST /tag 404 tried to create a tag for an object that wasn't found
POST /tag 405 not allowed
POST /tag/123/merge 200 merge a tag into another
POST /tag/123/merge 403 no permission
POST /tag/123/merge 400 invalid params
PUT /tag/123 200 rename tag
PUT /tag/123 409 new tag name already in use
PUT /tag/123 403 no permission
DELETE /tag 204 tag deleted
DELETE /tag 403 no permission
DELETE /tag 404 attempting to delete from an entity that wasn't found
DELETE /tag 405 not allowed

Query Params

Name Type Required Value
entityId integer No tags attached to this entity id only (if set, must also provide entityType)
entityType entity type No tags attached to this entity type only (if set, must also provide entityId)
name string No return tags with names containing this text
counts boolean No if true, response includes a count of how many entities this tag is assigned to, grouped by entity type

POST Parameters

Name Type Required Value
entityId integer No the id of the entity to apply the tag to (if set, you must also provide entityType and either id or name)
entityType integer No the type of the entity to apply the tag to (if set, you must also provide entityId and either id or name)
id integer No the id of the tag you wish to apply, must also provide entityId and entityType
name string No the name of the tag you wish to create - if one by that name already exists it will be returned without creating a duplicate

Merge Parameters

The merge endpoint replaces this tag (the loser) with another (the winner) on all entities that are assigned the losing tag. The loser is then deleted.

Name Type Required Value
replacementId integer Yes the id of the tag you wish to merge this tag into, the "winner"

PUT Parameters

Name Type Required Value
name string Yes the new name for this tag - must not already exist

DELETE Parameters

Name Type Required Value
entityId integer No the id of the entity to remove the tag from, Required unless deleting tag from ALL entities
entityType integer No the type of the entity to remove the tag from, Required unless deleting tag from ALL entities
id integer No the id of the tag you wish to remove, Required if no name is provided
name string No the name of the tag you wish to remove, Required if no id is provided

Returned Elements

Name Type Value
tags array (Tag) list of tag objects

Get all tags

    GET /api/tag?counts=1
     200
    {
        "data": {
            "totalPages": 1,
            "page": 1,
            "tags": [
                {
                    "uri": "https://api.servicetrade.com/api/tag/1",
                    "id": 1,
                    "name": "Mall",
                    "counts": [
                        {
                            "entityType": 5,
                            "entityName": "Company",
                            "count": 3
                        }
                    ]
                },
                {
                    "uri": "https://api.servicetrade.com/api/tag/12",
                    "id": 12,
                    "name": "CallManagerFirst"
                }
            ]
        }
    }

Get a single tag

    GET /api/tag/1
     200
    {
        "data": {
            "uri": "https://api.servicetrade.com/api/tag/1",
            "id": 1,
            "name": "Mall"
        }
    }

Create a new tag

    POST /api/tag?name=MyNewTag
     200
    {
        "data": {
            "uri": "https://api.servicetrade.com/api/tag/765",
            "id": 765,
            "name": "MyNewTag"
        }
    }

Attach tag to entity using name, will create tag if it doesn't already exist

    POST /api/tag?name=MyNewTag&entityId=1&entityType=11
     200
    {
        "data": {
            "uri": "https://api.servicetrade.com/api/tag/765",
            "id": 765,
            "name": "MyNewTag"
        }
    }

Attach tag to entity using id

    POST /api/tag/765?entityId=1&entityType=11
     200
    {
        "data": {
            "uri": "https://api.servicetrade.com/api/tag/765",
            "id": 765,
            "name": "MyNewTag"
        }
    }

Rename an existing tag

    PUT /api/tag/756
    {"name": "TheNewTagName"}

    200
    {
        "data": {
            "uri": "https://api.servicetrade.com/api/tag/765",
            "id": 765,
            "name": "TheNewTagName"
        }
    }

Merge a tag into another

    POST /api/tag/756/merge
    {"replacementId": 987}

    200
    {
        "data": {
            "uri": "https://api.servicetrade.com/api/tag/765",
            "id": 987,
            "name": "MyNewFavoriteTag"
        }
    }

Remove tag from entity using name

    DELETE /api/tag?name=MyNewTag&entityId=1&entityType=11
     200

Remove tag from entity using id

    DELETE /api/tag/765?entityId=1&entityType=11
     200

Return to Top

Tax Rate

The tax rate resource is used to retrieve estimated sales tax rates for a location. The stateRate, countyRate, cityRate, and otherRate fields are reserved for future use, and may not be populated.

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.

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.

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": 1,
                "uri": "https://api.servicetrade.com/api/terms/1",
                "name": "Job Terms",
                "content": "Terative approaches to corporate strategy foster collaborative thinking to further the overall value proposition."
            },
            {
                "id": 2,
                "uri": "https://api.servicetrade.com/api/terms/2",
                "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/2

200
{
    "data": {
        "id": 2,
        "uri": "https://api.servicetrade.com/api/terms/2",
        "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 2", "content": "Don't immanentize the eschalon."}

200
{
    "data": {
        "id": 3,
        "uri": "https://api.servicetrade.com/api/terms/3",
        "name": "Job Terms 2",
        "content": "Don't immanentize the eschalon."
    }
}

Modify terms with PUT

POST /terms/3
{"content": "Immanentize the eschalon."}

200
{
    "data": {
        "id": 3,
        "uri": "https://api.servicetrade.com/api/terms/3",
        "name": "Job Terms 2",
        "content": "Immanentize the eschalon."
    }
}

Delete Terms

DELETE /terms/3

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>

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.

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)
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?
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,
                "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,
                "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,
        "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,
        "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,
        "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

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.

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/2

200
{
    "data": {
        "id": 2,
        "uri": "https://api.servicetrade.com/api/warehouse/2",
        "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": 18,
        "uri": "https://api.servicetrade.com/api/warehouse/18",
        "name": "bar",
        "office": null,
        "status": "active",
    }
}

Make changes to an existing warehouse

PUT /warehouse/2
{"officeId":86}

200
{
    "data": {
        "id": 2,
        "uri": "https://api.servicetrade.com/api/warehouse/2",
        "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:

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:

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:

Webhook API

The webhook resource is used to retrieve the list of webhooks for an account or detailed information about a single webhook.

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