Custom Check-In/Out

2 minute read

Report the time spent on a custom activity, for example, having a lunch break, being in a meeting, or conducting research. You should receive the same MechanicId for both API requests.

For this type, no permissions are required. However, note that custom work types do not exist by default. First, subscribers should contact their ServiceChannel representatives and ask them to configure the required custom types. After that, the custom check-in/out type would be available for you.

The custom check-in/out records in the Service Automation UI after you report the custom activity via API.

Get Work Types

Before you can report the time spent on some specific activities, get the list of the subscriber’s work types.

GET /worktypes

Parameter Parameter type Example value
subscriberId
required for providers only		 Path 2014917243

Example request:

GET https://sb2api.servicechannel.com/v3/worktypes?subscriberId=2014917243 HTTP/1.1
Authorization: Bearer {access_token}

Example response:

[
   {
      "Id": 1,
      "Name": "Repair"
   },
   {
      "Id": 2,
      "Name": "Travel"
   },
   {
      "Id": 5,
      "Name": "Research"
   }
]

Response code: HTTP/1.1 200 OK

Use the response to get the following field:

Required field Response body field
WorkTypeId Id

Report Custom Check-In

To start a custom activity, use this API call:

POST /workorders/{workorderId}/universalCheckIn

Header Value
Content-Type application/json
Parameter Parameter type Example value
workorderId Path 107002896
Check-in request Body See below

Check-in request fields description

Attribute Description Required Default
WorkTypeId The unique ID of the work type. Required  
UserId The user ID of the technician that is checking in. Use the same UserId for one pair of check-in and check-out records. Optional The current user’s ID
TechsCount The number of technicians that are checking in. Optional 1
Latitude The latitude of the technician’s current position. Optional  
Longitude The longitude of the technician’s current position. Optional  
CheckInTime The date and time of the check-in. Either indicate the time in UTC or pass the current time and add the UTC offset, for example, 2018-10-30T11:00:00-04:00. No permission:
do not provide.
XML permission:
optional.
GPS permission:
do not provide.
XML + GPS:
optional.		 The current date and time

Example request:

POST https://sb2api.servicechannel.com/v3/workorders/107002896/universalCheckIn HTTP/1.1
Authorization: Bearer {access_token}
Content-Type: application/json

{
   "WorkTypeId": 5,
   "UserId": 1544987,
   "TechsCount": 2,
   "Latitude": 40.736618,
   "Longitude": -73.991806,
   "CheckInTime": "2018-10-23T15:00:00Z"
}

Example response:

{
   "MechanicId": 144996287
}

Response code: HTTP/1.1 200 OK

Report Custom Check-Out

To stop reporting the custom activity, use this API request:

POST /workorders/{workorderId}/universalCheckOut

Header Value
Content-Type application/json
Parameter Parameter type Example value
workorderId Path 107002896
Check-out request Body See below

Check-out request fields description

Attribute Description Required Default
WorkTypeId The unique ID of the work type. Required  
ActionStatus The status of the action.
Possible values: Complete, Cancel. Both values result in recording a check-out.
Complete means that the technician has finished the custom activity.
Cancel means the technician needs to pause the time reported as “custom activity”, for example, to have a break outside of the location.		 Optional Complete
UserId The user ID of the technician that is checking out. Use the same UserId for one pair of check-in and check-out records. Optional The current user’s ID
Latitude The latitude of the technician’s current position. Optional  
Longitude The longitude of the technician’s current position. Optional  
CheckOutTime The date and time of the check-out. Either indicate the time in UTC or pass the current time and add the UTC offset, for example, 2018-10-30T11:00:00-04:00. No permission:
do not provide.
XML permission:
optional.
GPS permission:
do not provide.
XML + GPS:
optional.		 The current date and time

Example request:

POST https://sb2api.servicechannel.com/v3/workorders/107002896/universalCheckOut HTTP/1.1
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "WorkTypeId": 5,
  "ActionStatus": "Complete",
  "UserId": 1544987,
  "Latitude": 40.736618,
  "Longitude": -73.991806,
  "CheckOutTime": "2018-07-02T11:30:00Z"
}

Example response:

{
   "MechanicId": 144996287
}

Response code: HTTP/1.1 200 OK

Updated: