Travel Check-In/Out

2 minute read

Report the time spent on traveling to the location. You should receive the same MechanicId for both API requests.

Important: Note that either the XML or the GPS check-in/out permission is required. Also, depending on the permissions, some parameters may be optional, required, or should not be provided at all.

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

Report Travel Check-In

To start tracking a travel activity, send the following API request:

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 and should be set to 2 (Travel)  
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. 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": 2,
   "UserId": 1544987,
   "TechsCount": 2,
   "Latitude": 37,
   "Longitude": -78,
   "CheckInTime": "2018-10-23T05:30:00Z"
}

Example response:

{
   "MechanicId": 148797638
}

Response code: HTTP/1.1 200 OK

Report Travel Check-Out

To stop recording the travel activity, issue this API call:

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 and should be set to 2 (Travel)  
ActionStatus The status of the action.
Possible values: Complete, Cancel. Both values result in recording a check-out.
Complete means that the technician has arrived at the location and can stop the time reported as “traveling”.
Cancel means the technician needs to pause the time reported as “traveling”, for example, to have a break on their way to 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. XML permission:
do not provide.
GPS permission:
required and should be in the location range.
XML + GPS:
optional but should be in the location range.
Not required when ActionStatus = Cancel.		  
Longitude The longitude of the technician’s current position. Same rules as for Latitude.  
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. 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": 2,
   "ActionStatus": "Complete",
   "UserId": 1544987,
   "Latitude": 40.736618,
   "Longitude": -73.991806,
   "CheckOutTime": "2018-10-23T06:30:00Z"
}

Example response:

{
   "MechanicId": 148797638
}

Response code: HTTP/1.1 200 OK

Updated: