Find and Filter Checklists
You can retrieve checklists configured by a subscriber via the API. The information you get in the response includes general checklist details, such as when and by whom it was created, as well as checklist questions. If responding to a question implies selecting from a range of preset options, each answer option is also returned for such questions.
Apply Filters to Checklists
When sending the API request to retrieve checklists, you can filter them by the following parameters:
- Trade: Specify either
tradeidortradeName. - Category: Enter either
categoryidorcategoryName. - Location: Provide either
locationIdorstoreId. Note that you can filter checklists by location only if the feature that enables creating checklists for specific locations is turned on for a subscriber. - Checklist: Pass either
checkListNameorchecklistidto get a specific checklist.
Expand the sections below to find out how to get valid values for trades, categories, and locations. Keep in mind that you need either the parameter ID or name and not both. For example, when passing tradeId, you should ignore tradeName.
tradeId / tradeName
Trade is the type of work a provider performs, such as Cleaning, Electrical, or IT. A trade may also represent the type of assets being serviced, for example, Elevator or Locks.
Get a list of trades passing one of the following requests, and save the Id or Name of the desired trade.
categoryid / categoryName
Category is the overall classification of a work order, such as Repair, Maintenance, or Warranty.
Subscribers can retrieve a complete list of categories through the below request. The field you are looking for is Id or Name.
Provider users can enter the name of the category for which they usually receive service requests from the client.
locationId / storeId
Location is a subscriber's property where work orders are serviced. locationId is a unique location identifier assigned automatically, while StoreId is a location number specified by a subscriber that may appear as Store Number or Location ID in the UI.
Send one of the following requests, and save either location Id or StoreId.
In the response, subscribers get a list of their properties, while providers see locations where they are permissioned to service work orders.
Note: When retrieving checklists, providers should pass subscriberId of the desired client.
Now that you have the required data, let’s filter checklists that are triggered for work orders belonging to the Electrical trade. We will use the trade name instead of ID.
GET /checklists/detail?tradeName=Electrical
| Parameter | Parameter type | Example value |
|---|---|---|
| tradeName | Query | Electrical |
| subscriberId (required for providers only) | Query | 2014917243 |
Example request for subscribers:
GET https://sb2api.servicechannel.com/v3/checklists/detail?tradeName=Electrical HTTP/1.1
Authorization: Bearer {access_token}
Example request for providers:
GET https://sb2api.servicechannel.com/v3/checklists/detail?tradeName=Electrical&subscriberId=2014917243 HTTP/1.1
Authorization: Bearer {access_token}
Example response
{
"CheckListDetails": [
{
"ChecklistName": "Outdoor Lighting Checklist",
"Id": 496,
"IsActive": true,
"CreatedDate": "2021-06-01T17:01:45.92",
"UpdatedDate": "2021-06-07T05:05:41.557",
"CreatedBy": 1543802,
"UpdatedBy": 1543802,
"Questions": [
{
"Id": 3834,
"CheckListId": 496,
"Question": "Are you wearing protective gear?",
"ShortDescription": null,
"AnswerRequired": false,
"PictureFlag": 2,
"Sequence": 0,
"QuestionType": 0,
"CheckListQuestionOptions": [],
"AnswerCanPersist": true,
"CheckListTimingType": 1
},
{
"Id": 3835,
"CheckListId": 496,
"Question": "Are all entrance lights functioning properly?",
"ShortDescription": null,
"AnswerRequired": true,
"PictureFlag": 0,
"Sequence": 0,
"QuestionType": 1,
"CheckListQuestionOptions": [
{
"Id": 4856,
"Answer": "Yes",
"Sequence": 0,
"IsConditionalFollowUp": false
},
{
"Id": 4857,
"Answer": "No (please explain)",
"Sequence": 0,
"IsConditionalFollowUp": true
}
],
"AnswerCanPersist": false,
"CheckListTimingType": 1
},
{
"Id": 3836,
"CheckListId": 496,
"Question": "Please specify if you see any dark areas in the parking lot that could be a safety risk.",
"ShortDescription": null,
"AnswerRequired": false,
"PictureFlag": 1,
"Sequence": 0,
"QuestionType": 2,
"CheckListQuestionOptions": [],
"AnswerCanPersist": false,
"CheckListTimingType": 1
},
{
"Id": 3837,
"CheckListId": 496,
"Question": "How many lights need repair or replacement?",
"ShortDescription": null,
"AnswerRequired": true,
"PictureFlag": 0,
"Sequence": 0,
"QuestionType": 4,
"CheckListQuestionOptions": [],
"AnswerCanPersist": false,
"CheckListTimingType": 1
}
]
},
{
"ChecklistName": "Lighting Maintenance Checklist",
"Id": 499,
"IsActive": true,
"CreatedDate": "2021-06-07T06:31:31.967",
"UpdatedDate": "2021-06-07T06:35:16.62",
"CreatedBy": 1543802,
"UpdatedBy": 1543802,
"Questions": [
{
"Id": 4824,
"CheckListId": 499,
"Question": "Have you checked all lights on the first floor?",
"ShortDescription": null,
"AnswerRequired": false,
"PictureFlag": 1,
"Sequence": 0,
"QuestionType": 0,
"CheckListQuestionOptions": [],
"AnswerCanPersist": false,
"CheckListTimingType": 2
},
{
"Id": 4825,
"CheckListId": 499,
"Question": "Have you checked all lights on the second floor?",
"ShortDescription": null,
"AnswerRequired": false,
"PictureFlag": 1,
"Sequence": 0,
"QuestionType": 0,
"CheckListQuestionOptions": [],
"AnswerCanPersist": false,
"CheckListTimingType": 2
},
{
"Id": 4826,
"CheckListId": 499,
"Question": "Do any lights need repair or replacement?",
"ShortDescription": null,
"AnswerRequired": false,
"PictureFlag": 0,
"Sequence": 0,
"QuestionType": 1,
"CheckListQuestionOptions": [
{
"Id": 4865,
"Answer": "Yes",
"Sequence": 0,
"IsConditionalFollowUp": false
},
{
"Id": 4866,
"Answer": "No (please explain)",
"Sequence": 0,
"IsConditionalFollowUp": true
}
],
"AnswerCanPersist": false,
"CheckListTimingType": 2
}
]
}
]
}
Response code: HTTP/1.1 200 OK
As you can see in the response, the subscriber created two checklists for the Electrical trade: Outdoor Lighting Checklist and Lighting Maintenance Checklist.
Retrieve a Specific Checklist
You can get the details of a specific checklist by its name or ID. Subscribers can view the checklist name in Admin > Tools > Checklists in Service Automation. Provider Automation users can see the checklist name on the Checklist tab of the work order details page — if checklist responses were submitted for the service request. Note that checklist names are unique for a subscriber.
When sending the request to retrieve checklists, you can save the IDs of the required checklists. Should you need to get a particular checklist in the future, pass its Id in checklistid.
GET /checklists/detail?checkListName=Outdoor Lighting Checklist
| Parameter | Parameter type | Example value |
|---|---|---|
| checkListName | Query | Outdoor Lighting Checklist |
| subscriberId (required for providers only) | Query | 2014917243 |
Example request for subscribers:
GET https://sb2api.servicechannel.com/v3/checklists/detail?checkListName=Outdoor%20Lighting%20Checklist HTTP/1.1
Authorization: Bearer {access_token}
Example request for providers:
GET https://sb2api.servicechannel.com/v3/checklists/detail?checkListName=Outdoor%20Lighting%20Checklist&subscriberId=2014917243 HTTP/1.1
Authorization: Bearer {access_token}
Example response
{
"CheckListDetails": [
{
"ChecklistName": "Outdoor Lighting Checklist",
"Id": 496,
"IsActive": true,
"CreatedDate": "2021-06-01T17:01:45.92",
"UpdatedDate": "2021-06-07T05:05:41.557",
"CreatedBy": 1543802,
"UpdatedBy": 1543802,
"Questions": [
{
"Id": 3834,
"CheckListId": 496,
"Question": "Are you wearing protective gear?",
"ShortDescription": null,
"AnswerRequired": false,
"PictureFlag": 2,
"Sequence": 0,
"QuestionType": 0,
"CheckListQuestionOptions": [],
"AnswerCanPersist": true,
"CheckListTimingType": 1
},
{
"Id": 3835,
"CheckListId": 496,
"Question": "Are all entrance lights functioning properly?",
"ShortDescription": null,
"AnswerRequired": true,
"PictureFlag": 0,
"Sequence": 0,
"QuestionType": 1,
"CheckListQuestionOptions": [
{
"Id": 4856,
"Answer": "Yes",
"Sequence": 0,
"IsConditionalFollowUp": false
},
{
"Id": 4857,
"Answer": "No (please explain)",
"Sequence": 0,
"IsConditionalFollowUp": true
}
],
"AnswerCanPersist": false,
"CheckListTimingType": 1
},
{
"Id": 3836,
"CheckListId": 496,
"Question": "Please specify if you see any dark areas in the parking lot that could be a safety risk.",
"ShortDescription": null,
"AnswerRequired": false,
"PictureFlag": 1,
"Sequence": 0,
"QuestionType": 2,
"CheckListQuestionOptions": [],
"AnswerCanPersist": false,
"CheckListTimingType": 1
},
{
"Id": 3837,
"CheckListId": 496,
"Question": "How many lights need repair or replacement?",
"ShortDescription": null,
"AnswerRequired": true,
"PictureFlag": 0,
"Sequence": 0,
"QuestionType": 4,
"CheckListQuestionOptions": [],
"AnswerCanPersist": false,
"CheckListTimingType": 1
}
]
}
]
}
Response code: HTTP/1.1 200 OK
Note: In the response, the actual values of AnswerCanPersist, CheckListTimingType, and IsConditionalFollowUp are returned for providers, while subscribers get default values.
The checklist we obtained contains 4 questions: one for each available question type.