GPS Check-In/Out

3 minute read

Report the time spent on work and record the GPS coordinates of the technician’s current position. You should receive the same MechanicId for both API requests.

Important: Don’t forget that the GPS check-in/out permission is required for this type. Also, when the location has no coordinates, you cannot use the GPS check-in/out.

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

Report GPS Check-In

To start recording the work activity and provide the technician’s current position, send 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. Optional 1
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. Required and should be in the location range.  
Longitude The longitude of the technician’s current position. Same rules as for Latitude.  
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. 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": 1,
   "UserId": 1544987,
   "TechsCount": 2,
   "Latitude": 40.736618,
   "Longitude": -73.991806,
   "CheckInTime": "2018-10-23T08:30:00Z"
}

Example response:

{
   "MechanicId": 148797641
}

Response code: HTTP/1.1 200 OK

Note: When you check in, the WO status is automatically changed to IN PROGRESS / ON SITE.

Report GPS Check-Out

To stop tracking the technician’s work activity, send 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. Optional 1
PrimaryStatus The status that you set for the WO when checking out.
Possible values: NoStatusChange, InProgress, WaitingForQuote, PartsOnOrder, Incomplete, and Completed.		 Required.
Not required when ActionStatus = Cancel.		 NoStatusChange
ExtendedStatus The extended status that you set for the WO when checking out. Optional.
Not required when ActionStatus = Cancel.		  
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 their job and can stop the time reported as “repair”.
Cancel means the technician needs to pause the time reported as “repair”, for example, to have a break outside of the location.		 Optional Complete
Resolution The comment entered when checking out. Usually describes what was done during the recorded time. Optional  
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. Required and 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. 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": 1,
   "PrimaryStatus": "Incomplete",
   "ActionStatus": "Complete",
   "Resolution": "We need more time to complete this job",
   "UserId": 1544987,
   "Latitude": 40.736618,
   "Longitude": -73.991806,
   "CheckOutTime": "2018-10-23T09:30:00Z"
}

Example response:

{
   "MechanicId": 148797641
}

Response code: HTTP/1.1 200 OK

Updated: