API Docsbeta
Please submit all support requests to help@vericlock.com
Overview
The VeriClock API is a RESTful API. All requests are either HTTP GET or POSTs and are directed at the VeriClock API endpoint:https://api.vericlock.com
Currently all API actions are done in the context of a VeriClock user and are limited and restricted by the users specific set of permissions. For example a user that is an administrator has full API access. A user that is a regular employee will only be able to clock in/out, not be able to create jobs or employees, etc...
Request Format
All API requests must contain the following HTTP Headers:| Header | Description of Value |
|---|---|
| vericlock_api_public_key | Your API Public Key in standard guid format: abcd1234-1234-1234-1234-abcd12345678 |
| vericlock_domain | The unique part of your access url. If your access URL is: your_domain.vericlock.com then the value for vericlock_domain would be your_domain Do not include the vericlock.com suffix. |
| vericlock_authtoken | The guid authentication token received after authenticating. This is required for all API routes except authentication itself |
| vericlock_signature | The HMAC signature for the request. See below on how to generate. |
| content-type | application/json - Required only for HTTP POST requests that post a JSON body |
All JSON object parameters, unless specified as [Required] can be considered optional and omitted if desired.
VeriClock Signature
The private key is binary
The URI is path of the API call ie. /api/1.0/employee/query
The URI is path of the API call ie. /api/1.0/employee/query
private function _generateSignature($uri, $privateKey, $bodyStr)
{
$hashStr = $uri . $bodyStr;
$sig = hash_hmac('sha256', $hashStr, $privateKey);
return $sig;
}
Response Format
The HTTP Response code will indicate whether the request was successful or not. 2xx responses indicate success. 4xx responses indicate some sort of user error, and the response JSON object will have more information. 5xx is an error on our side, and again the response JSON object may have additional information.All content in the response body will be a JSON object related to the API request made. Usually a JSON object or JSON array.
Authentication
Most API functions require authentication to occur first.
Authenticate
Description
Login & Authenticate with VeriClock's servers.
HTTP POST
https://api.vericlock.com/1.0/auth
https://api.vericlock.com/1.0/auth
Post Body
{
"user":string, //(Required)[string] employee email address
"password":string //(Required)[string] plain text password
}
Response
{
"authToken": "d35b1486-43ca-42bb-828d-9f35bc4be2d4"
}
Logout
Description
Purposely invalidate your authentication token - otherwise it will invalidate naturally due to inactivity
HTTP POST
https://api.vericlock.com/api/1.0/logout
https://api.vericlock.com/api/1.0/logout
Post Details
Empty
Employee
Methods for creating, updating and retrieving employees.
Create Employee
Description
Create a new employee. Returns the newly created job on success.
HTTP POST
https://api.vericlock.com/api/1.0/employee/create
https://api.vericlock.com/api/1.0/employee/create
Post Body
{ //Employee Object, Describes an employee
"phoneID":string, //[string] Numeric/touch-tone ID
"firstName":string, //(Required)[string] First name
"middleName":string, //[string] Middle initial (or name)
"lastName":string, //[string] Last name
"emailAddress":string, //[string] Email address
"password":string, //[string] Password - plaintext (salted and hashed server side)
"status":string, //[string] [active,inactive,deleted] Active status
"type":string, //[string] [normal,admin] Employee type
"groupGuid":string, //[string] Group the employee belongs to
"customData":object, //[object] A custom JSON object to store with the employee
"personalDetails":{ //An employee's contact and other personal details
"addressLine1":string, //[string] Address Line 1
"addressLine2":string, //[string] Address Line 2
"city":string, //[string] City
"countryCode":string, //[string] ISO 3166-1 Alpha 2 two character country code.
"stateCode":string, //[string] Two character state or province code - only applicable to USA/Canada
"postalCode":string, //[string] Zip/Postal Code
"phoneHome":string, //[string] Home phone number / phone number 1
"phoneMobile":string, //[string] Mobile phone number / phone number 2
"phoneOther":string, //[string] Other phone number / phone number 3
"gender":string, //[string] [male,female,] Employee's gender
"driversLicense":string, //[string] Zip/Postal Code
"taxNumber":string, //[string] Zip/Postal Code
"birthday":string //[string] Employee's date of birth
},
"employmentDetails":{ //An employee's employement details
"startDate":string, //[string] Employment start date
"endDate":string //[string] Employment end date
},
"settings":{ //An employee's customized settings
"phone":{ //Phone specific settings
"clockInReport":string,//[string] [required,optional,disabled] Is a report required on clock in
"clockOutReport":string,//[string] [required,optional,disabled] Is a report required on clock out
"pinType":string, //[string] [none,custom] Type of phone pin that is configured. ['none', 'custom']. 'custom' means the employee must enter their phonePin when clocking in by phone or SMS
"pin":string //[string] Phone or SMS numeric PIN code - must be digits only.
},
"web":{ //Web specific settings
"clockInReport":string,//[string] [required,optional,disabled] Is a report required on clock in
"clockOutReport":string//[string] [required,optional,disabled] Is a report required on clock out
},
"gpsSettings":{ //GPS specific settings
"basicGeoTagging":string//[string] [enabled,disabled] Collect GPS coordinates on clock in and out on supported mobile devices (Mobile Web/App)
},
"location":{ //Employee GEO Tagging Settings
"web":{ //Web browser based geo location - mobile browser
"tagInOut":string, //[string] [enabled,disabled] GEO tag when employee clocks in/out
"accuracy":integer, //[integer] When looking for a gps location, stop when a position with this level of accuracy is found
"timeout":integer //[integer] When looking for a gps location, stop after this many seconds
},
"app":{ //App based geo location - iOS App, Android App, etc...
"tagInOut":string, //[string] [enabled,disabled] GEO tag when employee clocks in/out
"accuracy":integer, //[integer] When looking for a gps location, stop when a position with this level of accuracy is found
"timeout":integer, //[integer] When looking for a gps location, stop after this many seconds
"continuousTracking":string//[string] [enabled,disabled] GEO Tag at regular intervals during employee's shift. Can be taxing on battery life.
},
"network":{ //App based geo location - iOS App, Android App, etc...
"tagInOut":string, //[string] [always,sometimes,disabled] GEO tag when employee clocks in/out
"frequency":integer //[integer] When tagInOut is set to sometimes, events will randomly be tagged using network location using this frequency as a %
}
},
"permissions":{ //Employee access permissions
"canViewOwnTimeSheet":boolean,//[boolean] Employee can view their own timesheet
"canEditOwnTimeSheet":boolean,//[boolean] Employee can edit their own timesheet
"activityNotes":string //[string] [disabled,textOnly,textAndFiles] Employee can upload activity notes and/or files
}
}
}
Response
{
"guid": "86d3dcda-03e9-4461-b4d0-5424b62e303b",
"status": "active",
"type": "normal",
"firstName": "Walter",
"middleName": "Hartwell",
"lastName": "White",
"fullName": "Walter Hartwell White",
"emailAddress": "wwhite@vericlock.com",
"phoneID": "625",
"publicPhoneID": "100*625",
"clockState": "clockedOut",
"groupGuid": null,
"customData": {
"nickname": "Heisenberg",
"internalEmployeeID": "1"
},
"personalDetails": {
"addressLine1": "3828 Piermont dr",
"addressLine2": null,
"city": "Albuquerque",
"countryCode": "US",
"stateCode": "NM",
"postalCode": "87111",
"phoneHome": "+1-505-555-1234",
"phoneMobile": "+1-505-555-9876",
"phoneOther": null,
"gender": "male",
"driversLicense": null,
"taxNumber": null,
"birthday": "1959-09-07"
},
"employmentDetails": {
"startDate": "2009-09-08",
"endDate": null,
"payRate": null,
"salary": 36000000,
"jobTitle": null
},
"dailyBudgetMins": {
"mon": null,
"tue": null,
"wed": null,
"thu": null,
"fri": null,
"sat": null,
"sun": null
},
"settings": {
"phone": {
"clockInReport": "disabled",
"clockOutReport": "required",
"pinType": "none"
},
"web": {
"clockInReport": "disabled",
"clockOutReport": "required"
},
"gpsSettings": {
"basicGeoTagging": "disabled",
"gpsAccuracyMeters": 75,
"gpsTimeoutSeconds": 15,
"continuousTracking": "disabled"
},
"permissions": {
"canViewOwnTimeSheet": true,
"canEditOwnTimeSheet": false,
"canViewJobDetails": false,
"canViewServiceItemDetails": false,
"activityNotes": "textAndFiles",
"offlineClock": true,
"canEditJobs": false
},
"location": {
"web": {
"tagInOut": "disabled"
},
"app": {
"tagInOut": "disabled"
},
"network": {
"tagInOut": "disabled"
}
}
}
}
Notes
Note that a few extra fields are returned:
guid: employee guid, used to identify the employee in subsequent requests
clockInState: clocked in state of employee: clockedIn or clockedOut
publicPhoneID: the numeric ID used on public phone in/sms numbers
Update Employee
Description
Update an employee with the posted employee object. The posted employee may be incomplete; only set fields will be updated.
HTTP POST
https://api.vericlock.com/api/1.0/employee/:employeeGuid/update
https://api.vericlock.com/api/1.0/employee/:employeeGuid/update
URI Parameters
| Parameter | Type | Required | Optional | Description |
|---|---|---|---|
| employeeGuid | string | Required | Employee's guid |
Post Body
{ //Employee Object, Describes an employee
"phoneID":string, //[string] Numeric/touch-tone ID
"firstName":string, //[string] First name
"middleName":string, //[string] Middle initial (or name)
"lastName":string, //[string] Last name
"emailAddress":string, //[string] Email address
"password":string, //[string] Password - plaintext (salted and hashed server side)
"status":string, //[string] [active,inactive,deleted] Active status
"type":string, //[string] [normal,admin] Employee type
"groupGuid":string, //[string] Group the employee belongs to
"customData":object, //[object] A custom JSON object to store with the employee
"personalDetails":{ //An employee's contact and other personal details
"addressLine1":string, //[string] Address Line 1
"addressLine2":string, //[string] Address Line 2
"city":string, //[string] City
"countryCode":string, //[string] ISO 3166-1 Alpha 2 two character country code.
"stateCode":string, //[string] Two character state or province code - only applicable to USA/Canada
"postalCode":string, //[string] Zip/Postal Code
"phoneHome":string, //[string] Home phone number / phone number 1
"phoneMobile":string, //[string] Mobile phone number / phone number 2
"phoneOther":string, //[string] Other phone number / phone number 3
"gender":string, //[string] [male,female,] Employee's gender
"driversLicense":string, //[string] Zip/Postal Code
"taxNumber":string, //[string] Zip/Postal Code
"birthday":string //[string] Employee's date of birth
},
"employmentDetails":{ //An employee's employement details
"startDate":string, //[string] Employment start date
"endDate":string //[string] Employment end date
},
"settings":{ //An employee's customized settings
"phone":{ //Phone specific settings
"clockInReport":string,//[string] [required,optional,disabled] Is a report required on clock in
"clockOutReport":string,//[string] [required,optional,disabled] Is a report required on clock out
"pinType":string, //[string] [none,custom] Type of phone pin that is configured. ['none', 'custom']. 'custom' means the employee must enter their phonePin when clocking in by phone or SMS
"pin":string //[string] Phone or SMS numeric PIN code - must be digits only.
},
"web":{ //Web specific settings
"clockInReport":string,//[string] [required,optional,disabled] Is a report required on clock in
"clockOutReport":string//[string] [required,optional,disabled] Is a report required on clock out
},
"gpsSettings":{ //GPS specific settings
"basicGeoTagging":string//[string] [enabled,disabled] Collect GPS coordinates on clock in and out on supported mobile devices (Mobile Web/App)
},
"location":{ //Employee GEO Tagging Settings
"web":{ //Web browser based geo location - mobile browser
"tagInOut":string, //[string] [enabled,disabled] GEO tag when employee clocks in/out
"accuracy":integer, //[integer] When looking for a gps location, stop when a position with this level of accuracy is found
"timeout":integer //[integer] When looking for a gps location, stop after this many seconds
},
"app":{ //App based geo location - iOS App, Android App, etc...
"tagInOut":string, //[string] [enabled,disabled] GEO tag when employee clocks in/out
"accuracy":integer, //[integer] When looking for a gps location, stop when a position with this level of accuracy is found
"timeout":integer, //[integer] When looking for a gps location, stop after this many seconds
"continuousTracking":string//[string] [enabled,disabled] GEO Tag at regular intervals during employee's shift. Can be taxing on battery life.
},
"network":{ //App based geo location - iOS App, Android App, etc...
"tagInOut":string, //[string] [always,sometimes,disabled] GEO tag when employee clocks in/out
"frequency":integer //[integer] When tagInOut is set to sometimes, events will randomly be tagged using network location using this frequency as a %
}
},
"permissions":{ //Employee access permissions
"canViewOwnTimeSheet":boolean,//[boolean] Employee can view their own timesheet
"canEditOwnTimeSheet":boolean,//[boolean] Employee can edit their own timesheet
"activityNotes":string //[string] [disabled,textOnly,textAndFiles] Employee can upload activity notes and/or files
}
}
}
Response
{
"guid": "86d3dcda-03e9-4461-b4d0-5424b62e303b",
"status": "active",
"type": "normal",
"firstName": "Walter",
"middleName": "Hartwell",
"lastName": "White",
"fullName": "Walter Hartwell White",
"emailAddress": "wwhite@vericlock.com",
"phoneID": "625",
"publicPhoneID": "100*625",
"clockState": "clockedOut",
"groupGuid": null,
"customData": {
"nickname": "Heisenberg",
"internalEmployeeID": "1"
},
"personalDetails": {
"addressLine1": "3828 Piermont dr",
"addressLine2": null,
"city": "Albuquerque",
"countryCode": "US",
"stateCode": "NM",
"postalCode": "87111",
"phoneHome": "+1-505-555-1234",
"phoneMobile": "+1-505-555-9876",
"phoneOther": null,
"gender": "male",
"driversLicense": null,
"taxNumber": null,
"birthday": "1959-09-07"
},
"employmentDetails": {
"startDate": "2009-09-08",
"endDate": null,
"payRate": null,
"salary": 36000000,
"jobTitle": null
},
"dailyBudgetMins": {
"mon": null,
"tue": null,
"wed": null,
"thu": null,
"fri": null,
"sat": null,
"sun": null
},
"settings": {
"phone": {
"clockInReport": "disabled",
"clockOutReport": "required",
"pinType": "none"
},
"web": {
"clockInReport": "disabled",
"clockOutReport": "required"
},
"gpsSettings": {
"basicGeoTagging": "disabled",
"gpsAccuracyMeters": 75,
"gpsTimeoutSeconds": 15,
"continuousTracking": "disabled"
},
"permissions": {
"canViewOwnTimeSheet": true,
"canEditOwnTimeSheet": false,
"canViewJobDetails": false,
"canViewServiceItemDetails": false,
"activityNotes": "textAndFiles",
"offlineClock": true,
"canEditJobs": false
},
"location": {
"web": {
"tagInOut": "disabled"
},
"app": {
"tagInOut": "disabled"
},
"network": {
"tagInOut": "disabled"
}
}
}
}
Notes
* Updating an employee from a status of deleted to active or inactive requires the phoneID be unique.
* Some fields are not directly changeable such as guid, clockInState and publicPhoneID
Get Employee
Description
Get a specific employee by guid
HTTP GET
https://api.vericlock.com/api/1.0/employee/:employeeGuid
https://api.vericlock.com/api/1.0/employee/:employeeGuid
URI Parameters
| Parameter | Type | Required | Optional | Description |
|---|---|---|---|
| employeeGuid | string | Required | Employee's guid |
Response
{
"guid": "86d3dcda-03e9-4461-b4d0-5424b62e303b",
"status": "active",
"type": "normal",
"firstName": "Walter",
"middleName": "Hartwell",
"lastName": "White",
"fullName": "Walter Hartwell White",
"emailAddress": "wwhite@vericlock.com",
"phoneID": "625",
"publicPhoneID": "100*625",
"clockState": "clockedOut",
"groupGuid": null,
"customData": {
"nickname": "Heisenberg",
"internalEmployeeID": "1"
},
"personalDetails": {
"addressLine1": "3828 Piermont dr",
"addressLine2": null,
"city": "Albuquerque",
"countryCode": "US",
"stateCode": "NM",
"postalCode": "87111",
"phoneHome": "+1-505-555-1234",
"phoneMobile": "+1-505-555-9876",
"phoneOther": null,
"gender": "male",
"driversLicense": null,
"taxNumber": null,
"birthday": "1959-09-07"
},
"employmentDetails": {
"startDate": "2009-09-08",
"endDate": null,
"payRate": null,
"salary": 36000000,
"jobTitle": null
},
"dailyBudgetMins": {
"mon": null,
"tue": null,
"wed": null,
"thu": null,
"fri": null,
"sat": null,
"sun": null
},
"settings": {
"phone": {
"clockInReport": "disabled",
"clockOutReport": "required",
"pinType": "none"
},
"web": {
"clockInReport": "disabled",
"clockOutReport": "required"
},
"gpsSettings": {
"basicGeoTagging": "disabled",
"gpsAccuracyMeters": 75,
"gpsTimeoutSeconds": 15,
"continuousTracking": "disabled"
},
"permissions": {
"canViewOwnTimeSheet": true,
"canEditOwnTimeSheet": false,
"canViewJobDetails": false,
"canViewServiceItemDetails": false,
"activityNotes": "textAndFiles",
"offlineClock": true,
"canEditJobs": false
},
"location": {
"web": {
"tagInOut": "disabled"
},
"app": {
"tagInOut": "disabled"
},
"network": {
"tagInOut": "disabled"
}
}
}
}
Query For Employees
Description
Search VeriClock for employees matching query parameters. If no query parameters are supplied, returns a list of all active employees.
HTTP POST
https://api.vericlock.com/api/1.0/employee/query
https://api.vericlock.com/api/1.0/employee/query
Post Body
{
"status":string //[string] [active,inactive,deleted,activeInactive] Employee's status
}
Response
[
{
"guid": "b64fc891-55ab-4419-82b9-3c398acfcd08",
"firstName": "Walter",
"lastName": "White"
},
{
"guid": "b735a3ab-609c-4655-9446-898b2d4fc92b",
"firstName": "Skyler",
"lastName": "White"
}
]
Notes
Returned employee objects are complete objects, the above example omits fields for clarity.
Job
Methods for retrieving Jobs, and creating new Jobs.
Create Job
Description
Creates a new job. Returns the newly created job on success.
HTTP POST
https://api.vericlock.com/api/1.0/job/create
https://api.vericlock.com/api/1.0/job/create
Post Body
{ //Job Object, Describes a job
"name":string, //(Required)[string] Name for the job.
"description":string, //[string] Description of the job.
"code":undefined, //[undefined] Numeric job code used to identify the job.
"status":string, //[string] [active,inactive,deleted] Job's active status.
"accessControl":string, //[string] [none,allowList,denyList] Access control method in use
"parentGuid":string, //[string] Job's optional parent job guid.
"employeeAccessList":array,//[array] List of employees, by guid, affected by the access control policy
"groupAccessList":array, //[array] List of groups, by guid, affected by the access control policy
"otExempt":boolean, //[boolean] If true, job will not contribute to overtime
"thirdPartyContactGuid":undefined//[undefined] undefined
}
Response
{
"guid": "69be515d-d54f-4bcc-8f28-72a4789c9107",
"parentGuid": null,
"createDate": "2009-01-01T00:00:00.000Z",
"code": 100,
"name": "Lab Cleanup",
"description": "Cleaning up the lab - ensure all surfaces are scrubbed",
"status": "active",
"accessControl": "none",
"budgetDollars": null,
"budgetHours": null,
"budgetDollarsMonthly": null,
"budgetHoursMonthly": null,
"budgetDollarsWeekly": null,
"budgetHoursWeekly": null,
"budgetDollarsDaily": null,
"budgetHoursDaily": null,
"budgetDollarsPayroll": null,
"budgetHoursPayroll": null,
"otExempt": false,
"thirdPartyContactGuid": null,
"employeeAccessList": null,
"groupAccessList": null
}
Update Job
Description
Updates a job referenced by jobGuid with the posted job object. The posted job may be incomplete; only set fields will be updated.
HTTP POST
https://api.vericlock.com/api/1.0/job/:jobGuid/update
https://api.vericlock.com/api/1.0/job/:jobGuid/update
URI Parameters
| Parameter | Type | Required | Optional | Description |
|---|---|---|---|
| jobGuid | string | Required | Job's guid |
Post Body
{ //Job Object, Describes a job
"name":string, //[string] Name for the job.
"description":string, //[string] Description of the job.
"code":undefined, //[undefined] Numeric job code used to identify the job.
"status":string, //[string] [active,inactive,deleted] Job's active status.
"accessControl":string, //[string] [none,allowList,denyList] Access control method in use
"parentGuid":string, //[string] Job's optional parent job guid.
"employeeAccessList":array,//[array] List of employees, by guid, affected by the access control policy
"groupAccessList":array, //[array] List of groups, by guid, affected by the access control policy
"otExempt":boolean, //[boolean] If true, job will not contribute to overtime
"thirdPartyContactGuid":undefined//[undefined] undefined
}
Response
{
"guid": "69be515d-d54f-4bcc-8f28-72a4789c9107",
"parentGuid": null,
"createDate": "2009-01-01T00:00:00.000Z",
"code": 100,
"name": "Lab Cleanup",
"description": "Cleaning up the lab - ensure all surfaces are scrubbed",
"status": "active",
"accessControl": "none",
"budgetDollars": null,
"budgetHours": null,
"budgetDollarsMonthly": null,
"budgetHoursMonthly": null,
"budgetDollarsWeekly": null,
"budgetHoursWeekly": null,
"budgetDollarsDaily": null,
"budgetHoursDaily": null,
"budgetDollarsPayroll": null,
"budgetHoursPayroll": null,
"otExempt": false,
"thirdPartyContactGuid": null,
"employeeAccessList": null,
"groupAccessList": null
}
Get a Job
Description
Returns a job object referenced by the supplied guid
HTTP GET
https://api.vericlock.com/api/1.0/job/:jobGuid
https://api.vericlock.com/api/1.0/job/:jobGuid
URI Parameters
| Parameter | Type | Required | Optional | Description |
|---|---|---|---|
| jobGuid | string | Required | Job's guid |
Response
{
"guid": "69be515d-d54f-4bcc-8f28-72a4789c9107",
"parentGuid": null,
"createDate": "2009-01-01T00:00:00.000Z",
"code": 100,
"name": "Lab Cleanup",
"description": "Cleaning up the lab - ensure all surfaces are scrubbed",
"status": "active",
"accessControl": "none",
"budgetDollars": null,
"budgetHours": null,
"budgetDollarsMonthly": null,
"budgetHoursMonthly": null,
"budgetDollarsWeekly": null,
"budgetHoursWeekly": null,
"budgetDollarsDaily": null,
"budgetHoursDaily": null,
"budgetDollarsPayroll": null,
"budgetHoursPayroll": null,
"otExempt": false,
"thirdPartyContactGuid": null,
"employeeAccessList": null,
"groupAccessList": null
}
Get Jobs
Description
Returns a list of jobs. Defaults to all active and inactive jobs (ignoring deleted jobs). Can be filtered by additional body parameters.
HTTP POST
https://api.vericlock.com/api/1.0/job/query
https://api.vericlock.com/api/1.0/job/query
Post Body
{
"status":string, //[string] [active,inactive,deleted,activeInactive] Active status to filter by. Note: activeInactive will select both active and inactive jobs
"searchText":string, //[string] Searches job list by code/name/description for occurrences of this text
"searchResultLimit":integer,//[integer] Sends at most this many results back when using searchText
"includeAccessControlList":boolean,//[boolean]
"jobCode":string //[string] Searches for a job matching this job code
}
Response
[
{
"guid": "afa3a958-156c-4fbc-a570-7c39beed11be",
"name": "Lab Cleanup",
"code": 100
},
{
"guid": "e4923257-d8e6-4518-a9f2-9c06ee924f7a",
"name": "Supply Inventory",
"code": 200
}
]
Notes
Returned job objects are complete objects, the above example omits fields for clarity.
Get the cost for a job
Description
Returns the cost for a job referenced by the supplied guid
HTTP GET
https://api.vericlock.com/api/1.0/job/:jobGuid/getCost/:budgetType
https://api.vericlock.com/api/1.0/job/:jobGuid/getCost/:budgetType
URI Parameters
| Parameter | Type | Required | Optional | Description |
|---|---|---|---|
| jobGuid | string | Required | Job's guid |
| budgetType | string | Required | Type of job cost report Valid Values: [allTime, monthly, weekly, daily, payroll] |
Response
{
"totalDollars": 1650,
"totalHours": 24.25,
"hasTimeGuard": false,
"missingRatesByPayrollItem": [
{
"_payrollItem": {
"Regular": true
},
"employeeFullName": "Walter White",
"employeeGuid": "5c235f53-2222-3333-4444-abc6ec86ed77",
"payrollItems": [
"Regular"
]
}
],
"missingPayrollItemsByTimeType": []
}
Group
Methods for clocking groups in and out of the service.
Gets the groups
Description
Gets the groups
HTTP POST
https://api.vericlock.com/api/1.0/group/query
https://api.vericlock.com/api/1.0/group/query
Post Body
{
"managingEmployeeGuid":string//[string] Employee's guid. If specified, all groups managed by this employee is returned.
}
Response
[
{
"guid": "19d9fd56-b893-4391-6ebe-f1d93e1c2c7e",
"name": "Sales Team",
"description": "",
"employees": [
"...employees in group list..."
]
},
{
"guid": "68c0cc25-eeaf-48f5-8f4c-d69135a871f9",
"name": "Tech Team",
"description": "",
"employees": [
"...employees in group list..."
]
}
]
Get a Group by guid
Description
Get a Group by guid
HTTP GET
https://api.vericlock.com/api/1.0/group/:groupGuid/
https://api.vericlock.com/api/1.0/group/:groupGuid/
URI Parameters
| Parameter | Type | Required | Optional | Description |
|---|---|---|---|
| groupGuid | string | Required | Group's guid |
Response
{
"guid": "19d9fd56-b893-4391-6ebe-f1d93e1c2c7e",
"name": "Sales Team",
"description": "",
"employees": [
"...employees in group list..."
]
}
Create Group
Description
Creates a group
HTTP POST
https://api.vericlock.com/api/1.0/group/create
https://api.vericlock.com/api/1.0/group/create
Post Body
{ //Group Object. Describes a group
"name":string, //(Required)[string] undefined
"description":string //[string] undefined
}
Response
{
"guid": "19d9fd56-b893-4391-6ebe-f1d93e1c2c7e",
"name": "Sales Team",
"description": "",
"employees": [
"...employees in group list..."
]
}
Timesheet
Methods for retrieving time data.
Time Sheet Query
Description
Retrieve all clock events that match the posted search criteria
HTTP POST
https://api.vericlock.com/api/1.0/timesheet/query
https://api.vericlock.com/api/1.0/timesheet/query
Post Body
{ //A time sheet query object describes what time data to retrieve
"searchPeriod":{ //Search time frame
"start":string, //(Required)[string] Search period begins at this date-time
"end":string, //(Required)[string] Search period ends at this date-time
"searchType":string, //[string] [inOutTimeInclusive,inTimeInclusive,inOrOutTimeInclusive] Changes how search interprets start and end time ranges. inTimeInclusive will only consider a clock event's clock in time, inOutTimeInclusive will consider both the clock in time AND out time, both must be in the search window, and 'inOrOutTimeInclusive' either the clock event's start or end time must be within the search window. Default is 'inOutTimeInclusive'
"includeInProgressEvents":boolean//[boolean] Include clock events of employees still clocked in - duration, cost, etc will assume a time up to the current moment
},
"applyScheduledDeductions":boolean,//[boolean] Apply the scheduled time deductions to all events
"activeFilter":string, //[string] [active,deleted,all] Allows the inclusive of deleted events as well or exclusively. Default is 'active'
"approvedFilter":string, //[string] [all,approved,unapproved] Filter for only approved timesheet entries. One of ['all','approved','unapproved']. Default is 'all'
"employeeList":array, //[array] Array of employee guid's
"jobList":array, //[array] Array of job guid's
"includeEmployeeIds":array,//[array] undefined
"excludeEmployeeIds":array,//[array] undefined
"includeGroupIds":array, //[array] undefined
"excludeGroupIds":array, //[array] undefined
"includeJobIds":array, //[array] undefined
"excludeJobIds":array, //[array] undefined
"includeServiceItemIds":array,//[array] undefined
"excludeServiceItemIds":array,//[array] undefined
"requestExtraData":{ //Data returned will be minimal unless additional fields or objects are requested
"reportsIn":boolean, //[boolean] Include clock in reports for each clock event
"reportsOut":boolean, //[boolean] Include clock out reports for each clock event
"customFieldsIn":boolean,//[boolean] Include clock in custom field data for each clock event
"customFieldsOut":boolean,//[boolean] Include clock out custom field data for each clock event
"editEmployee":boolean, //[boolean] Include the last employee to edit each clock event
"editReport":boolean, //[boolean] Include all edit notes for each clock event
"webInfoIn":boolean, //[boolean] Include clock in details for web clocks if available. IP, Browser, etc...
"phoneInfoIn":boolean, //[boolean] Include clock in details for phone clocks if available. Caller ID, etc...
"smsInfoIn":boolean, //[boolean] Include clock in details for sms clocks if available. Caller ID, etc...
"appInfoIn":boolean, //[boolean] Include clock in details for app clocks if available. IP, Device, etc...
"gpsInfoIn":boolean, //[boolean] Include clock in GPS info if available. Lat, Lng, etc...
"webInfoOut":boolean, //[boolean] Include clock out details for web clocks if available. IP, Browser, etc...
"phoneInfoOut":boolean, //[boolean] Include clock out details for phone clocks if available. Caller ID, etc...
"smsInfoOut":boolean, //[boolean] Include clock out details for sms clocks if available. Caller ID, etc...
"appInfoOut":boolean, //[boolean] Include clock out details for app clocks if available. IP, Device, etc...
"gpsInfoOut":boolean //[boolean] Include clock out GPS info if available. Lat, Lng, etc...
}
}
Response
[
{
"guid": "4eb20d5c-25f9-4007-800e-df020b54950b",
"rootGuid": "4eb20d5c-25f9-4007-800e-df020b54950b",
"employeeGuid": "303df126-e829-4d8e-af0f-a366666d0b67",
"jobGuid": "2c42113f-b7a6-4fb7-a4ec-afd5d1e97fd6",
"jobCode": null,
"jobName": null,
"serviceItemGuid": null,
"serviceItemCode": null,
"serviceItemName": null,
"start": "2009-01-01T08:05:00.000Z",
"end": "2009-01-01T17:49:00.000Z",
"duration": 584,
"clockInReportId": null,
"inDetails": {
"method": "phone",
"report": {
"type": "audio",
"url": "https://url.to.the.report/mp3/or/wav"
},
"callerID": "+15055551234",
"calledNumber": "+15055550000",
"callLength": "37"
},
"clockOutReportId": null,
"outDetails": {
"method": "web",
"report": {
"type": "text",
"value": "Lab session went perfectly"
},
"ipAddress": "192.168.0.25",
"userAgent": "chrome browser"
},
"deleted": false,
"flagged": {
"accessControlCallerIDClockIn": true
},
"approved": true
},
{
"guid": "e44b6297-5c81-40d2-bb2d-ae459dbce024",
"rootGuid": "e44b6297-5c81-40d2-bb2d-ae459dbce024",
"employeeGuid": "ee2028d4-d99b-411d-87ee-4f30b31c1f1b",
"jobGuid": "b3b1dc82-54d7-407b-a071-b195b44697ad",
"jobCode": null,
"jobName": null,
"serviceItemGuid": null,
"serviceItemCode": null,
"serviceItemName": null,
"start": "2009-02-01T08:27:00.000Z",
"end": "2009-02-01T12:12:00.000Z",
"duration": 225,
"clockInReportId": null,
"inDetails": {
"method": "sms",
"callerID": "+15055551234",
"calledNumber": "+15055550000",
"rawSMS": "in 625 100"
},
"clockOutReportId": null,
"outDetails": {
"method": "mobileWeb",
"ipAddress": "192.168.0.119",
"userAgent": "iphone/safari browser",
"geoTagging": {
"latitude": "49.264585002149",
"longitude": "-123.12476435135",
"accuracy": 25
}
},
"deleted": false,
"flagged": {
"accessControlCallerIDClockIn": true,
"jobRulesAssignmentMismatch": true
},
"approved": true
},
{
"guid": "e44b6297-5c81-40d2-bb2d-ae459dbce024",
"rootGuid": "e44b6297-5c81-40d2-bb2d-ae459dbce024",
"employeeGuid": "b19d5a8d-8d8b-445b-b55d-e91b4c4a1c90",
"jobGuid": "04743dc5-06fa-4119-a858-fadc955b8253",
"jobCode": null,
"jobName": null,
"serviceItemGuid": null,
"serviceItemCode": null,
"serviceItemName": null,
"start": "2009-02-01T08:27:00.000Z",
"end": "2009-02-01T12:12:00.000Z",
"duration": 225,
"clockInReportId": null,
"inDetails": {
"method": "phone",
"callerID": "+15055551234",
"calledNumber": "+15055550000"
},
"clockOutReportId": null,
"outDetails": {
"method": "phone",
"callerID": "+15055551234",
"calledNumber": "+15055550000"
},
"deleted": false,
"flagged": {
"accessControlCallerIDClockIn": true,
"accessControlCallerIDClockOut": true
}
}
]
Notes
duration: in minutes
inDetails.method: 'phone', 'sms', 'web', 'mobileWeb', 'edit', 'manualEntry'
Payroll
Gets the payroll items
Description
Gets the payroll items
HTTP POST
https://api.vericlock.com/api/1.0/payroll/query
https://api.vericlock.com/api/1.0/payroll/query
Post Body
{
"guid":string, //[string] Payroll Item's guid
"status":string //[string] [active,inactive,deleted] Payroll Item's status
}
Create payroll item
Description
Creates a new payroll item. Returns the newly created payroll item on success.
HTTP POST
https://api.vericlock.com/api/1.0/payroll/create
https://api.vericlock.com/api/1.0/payroll/create
Post Body
{ //PayrollItem Object. Describes a payroll item
"name":string, //(Required)[string] Name for the payroll item.
"description":string, //[string] Description of the payroll item.
"status":string, //[string] [active,inactive,deleted] Payroll item's active status
"type":string, //[string] [hourly,overtime,salary] Payroll item's pay type
"linkedGuid":string, //[string] Guid of linked payroll item
"multiplier":number //[number] Multiplier for the payroll item rate. This is only valid if linkedGuid is valid
}
Response
{
"guid": "491d25f7-77f9-4e06-aef1-ef990b469a84",
"name": "Painting overtime",
"description": "Overtime payroll for painting",
"status": "active",
"type": "hourly",
"linkedGuid": null,
"linkedName": null,
"multiplier": null,
"createdDate": "2020-01-13T23:02:52.000Z"
}
Update payroll items
Description
Update a payroll item with the posted payroll item object. The posted payroll item may be incomplete, only set fields will be updated.
HTTP POST
https://api.vericlock.com/api/1.0/payroll/:guid/update
https://api.vericlock.com/api/1.0/payroll/:guid/update
URI Parameters
| Parameter | Type | Required | Optional | Description |
|---|---|---|---|
| guid | string | Required | Payroll item's guid |
Post Body
{ //PayrollItem Object. Describes a payroll item
"name":string, //[string] Name for the payroll item.
"description":string, //[string] Description of the payroll item.
"status":string, //[string] [active,inactive,deleted] Payroll item's active status
"type":string, //[string] [hourly,overtime,salary] Payroll item's pay type
"linkedGuid":string, //[string] Guid of linked payroll item
"multiplier":number //[number] Multiplier for the payroll item rate. This is only valid if linkedGuid is valid
}
Response
{
"guid": "491d25f7-77f9-4e06-aef1-ef990b469a84",
"name": "Painting overtime",
"description": "Overtime payroll for painting",
"status": "active",
"type": "hourly",
"linkedGuid": null,
"linkedName": null,
"multiplier": null,
"createdDate": "2020-01-13T23:02:52.000Z"
}
Notes
* Some fields are not directly changeable such as guid
Gets payroll item rules
Description
Gets the list of payroll item rules
HTTP POST
https://api.vericlock.com/api/1.0/payroll/queryRules
https://api.vericlock.com/api/1.0/payroll/queryRules
Post Body
{
"payType":integer, //[integer] Pay type
"jobGuid":string, //[string] Job's guid
"serviceItemGuid":string, //[string] Service item's guid
"employeeGuid":string, //[string] Employee's guid
"groupGuid":string, //[string] Group's guid
"payrollItemGuid":string //[string] Payroll item's guid
}
Creates a payroll item rule
Description
Creates a payroll item rule
HTTP POST
https://api.vericlock.com/api/1.0/payroll/createRule
https://api.vericlock.com/api/1.0/payroll/createRule
Post Body
{
"payType":integer, //(Required)[integer] Pay type
"jobGuid":string, //[string] Job's guid
"serviceItemGuid":string, //[string] Service item's guid
"employeeGuid":string, //[string] Employee's guid
"groupGuid":string, //[string] Group's guid
"payrollItemGuid":string //[string] Payroll item's guid
}
Delete a payroll item rule
Description
Delete a payroll item rule
HTTP POST
https://api.vericlock.com/api/1.0/payroll/deleteRule
https://api.vericlock.com/api/1.0/payroll/deleteRule
Post Body
{
"payType":integer, //(Required)[integer] Pay type
"jobGuid":string, //[string] Job's guid
"serviceItemGuid":string, //[string] Service item's guid
"employeeGuid":string, //[string] Employee's guid
"groupGuid":string, //[string] Group's guid
"payrollItemGuid":string //[string] Payroll item's guid
}
Queries payroll info for specified employee
Description
Queries payroll info for specified employee
HTTP POST
https://api.vericlock.com/api/1.0/payroll/queryPayrollInfo
https://api.vericlock.com/api/1.0/payroll/queryPayrollInfo
Post Body
{
"employeeGuid":string //(Required)[string] Employee's guid
}
Saves payroll info for specified employee
Description
Saves payroll info for specified employee
HTTP POST
https://api.vericlock.com/api/1.0/payroll/savePayrollInfo
https://api.vericlock.com/api/1.0/payroll/savePayrollInfo
Post Body
{
"payrollInfo":array //(Required)[array] Employee's payroll info
}
ServiceItem
Create service item
Description
Creates a new service item. Returns the newly created service item on success.
HTTP POST
https://api.vericlock.com/api/1.0/serviceItem/create
https://api.vericlock.com/api/1.0/serviceItem/create
Post Body
{ //ServiceItem Object. Describes a service item
"name":string, //(Required)[string] Name for the service item.
"serviceItemCode":number, //[number] Service item code
"description":string, //[string] Description of the service item.
"status":string, //[string] [active,inactive,deleted] Service item's active status
"parentGuid":string, //[string] Service item's optional parent guid.
"otExempt":boolean //[boolean] If true, a shift with this service item will not contribute to overtime
}
Response
{
"guid": "9aa79087-f428-4ea3-9477-8b150559dcaa",
"serviceItemCode": 55,
"name": "Driving",
"description": "Driving to a job site",
"status": "active",
"parentGuid": null,
"createdDate": "2020-01-13T23:02:52.000Z",
"otExempt": false
}
Update service items
Description
Update a service item with the posted service item object. The posted service item may be incomplete, only set fields will be updated.
HTTP POST
https://api.vericlock.com/api/1.0/serviceItem/:guid/update
https://api.vericlock.com/api/1.0/serviceItem/:guid/update
URI Parameters
| Parameter | Type | Required | Optional | Description |
|---|---|---|---|
| guid | string | Required | Service item's guid |
Post Body
{ //ServiceItem Object. Describes a service item
"name":string, //[string] Name for the service item.
"serviceItemCode":number, //[number] Service item code
"description":string, //[string] Description of the service item.
"status":string, //[string] [active,inactive,deleted] Service item's active status
"parentGuid":string, //[string] Service item's optional parent guid.
"otExempt":boolean //[boolean] If true, a shift with this service item will not contribute to overtime
}
Response
{
"guid": "9aa79087-f428-4ea3-9477-8b150559dcaa",
"serviceItemCode": 55,
"name": "Driving",
"description": "Driving to a job site",
"status": "active",
"parentGuid": null,
"createdDate": "2020-01-13T23:02:52.000Z",
"otExempt": false
}
Notes
* Some fields are not directly changeable such as guid
Settings - Clock Access Control
Methods for changing the clock in/out access control settings
Create caller ID Access Rule
Description
Creates/updates a caller ID access rule for job referenced by URI parameter :jobGuid
HTTP POST
https://api.vericlock.com/api/1.0/settings/accessControl/callerID/:jobGuid
https://api.vericlock.com/api/1.0/settings/accessControl/callerID/:jobGuid
URI Parameters
| Parameter | Type | Required | Optional | Description |
|---|---|---|---|
| jobGuid | string | Required | The GUID of the job this rule will apply to or 'global' for the global rules |
Post Body
{
"permission":string, //(Required)[string] [allow,deny] Permission type
"flagOnly":boolean, //[boolean] Flag Only - if true, clocks matching rule are not blocked, but are instead flagged only
"phoneNumber":string, //[string] Phone number for the rule, blank for generic base case. International format.
"notes":string //[string] Short description about the phone number
}
Get caller ID Access Rule
Description
Retrieves all or a specific caller ID access rule referenced by URI parameter :jobGuid
HTTP GET
https://api.vericlock.com/api/1.0/settings/accessControl/callerID/:jobGuid
https://api.vericlock.com/api/1.0/settings/accessControl/callerID/:jobGuid
URI Parameters
| Parameter | Type | Required | Optional | Description |
|---|---|---|---|
| jobGuid | string | Optional | The GUID of the job this rule will apply to - use 'global' to refer to the global rules. Leave empty to retrieve all rules. |
Removes a caller ID access rule
Description
URI parameter :jobGuid refers to the rule to be deleted.
HTTP DELETE
https://api.vericlock.com/api/1.0/settings/accessControl/callerID/:jobGuid
https://api.vericlock.com/api/1.0/settings/accessControl/callerID/:jobGuid
URI Parameters
| Parameter | Type | Required | Optional | Description |
|---|---|---|---|
| jobGuid | string | Optional | The GUID of the job this rule will apply to - use 'global' to refer to the global rules. |
Post Body
{
"phoneNumber":string //[string] Phone number for the rule, blank for generic base case, wildcard * for entire rule. International format.
}
Create IP Address Access Rule
Description
Creates/updates a IP Address access rule for job referenced by URI parameter :jobGuid
HTTP POST
https://api.vericlock.com/api/1.0/settings/accessControl/ipAddress/:jobGuid
https://api.vericlock.com/api/1.0/settings/accessControl/ipAddress/:jobGuid
URI Parameters
| Parameter | Type | Required | Optional | Description |
|---|---|---|---|
| jobGuid | string | Required | The GUID of the job this rule will apply to or 'global' for the global rules |
Post Body
{
"permission":string, //(Required)[string] [allow,deny] Permission type
"flagOnly":boolean, //[boolean] Flag Only - if true, clocks matching rule are not blocked, but are instead flagged only
"ipAddress":string, //[string] IP Address for the rule, blank for generic base case, wildcard * for entire rule..
"notes":string //[string] Short description about the IP address
}
Get IP Address Access Rule
Description
Retrieves all or a specific IP Address access rule referenced by URI parameter :jobGuid
HTTP GET
https://api.vericlock.com/api/1.0/settings/accessControl/ipAddress/:jobGuid
https://api.vericlock.com/api/1.0/settings/accessControl/ipAddress/:jobGuid
URI Parameters
| Parameter | Type | Required | Optional | Description |
|---|---|---|---|
| jobGuid | string | Optional | The GUID of the job this rule will apply to - use 'global' to refer to the global rules. Leave empty to retrieve all rules. |
Removes an IP Address access rule
Description
URI parameter :jobGuid refers to the rule to be deleted.
HTTP DELETE
https://api.vericlock.com/api/1.0/settings/accessControl/ipAddress/:jobGuid
https://api.vericlock.com/api/1.0/settings/accessControl/ipAddress/:jobGuid
URI Parameters
| Parameter | Type | Required | Optional | Description |
|---|---|---|---|
| jobGuid | string | Optional | The GUID of the job this rule will apply to - use 'global' to refer to the global rules. |
Post Body
{
"ipAddress":string //[string] IP Address for the rule, blank for generic base case, wildcard * for entire rule..
}
Clock
Clock in/out employees
Clock In Group
Description
Clock in list of employees - authenticated user must be the employees' manager or be an administrator
HTTP POST
https://api.vericlock.com/api/1.0/clock/group/in
https://api.vericlock.com/api/1.0/clock/group/in
Post Body
{
"employeeGuids":array, //(Required)[array] List of employees guids
"jobGuid":string, //[string] Job guid
"serviceItemGuid":string, //[string] Service item guid
"report":string, //[string] A text clock in report to be attached to the clock event
"returnClockRootId":boolean//[boolean] undefined
}
Response
{
"23930782-390b-439f-88b6-7576593b3c6f": true,
"9583b0b8-7eda-42ec-bbf0-7cdc8a7c48b8": true,
"390bb0b8-439f-490b-7576-239307824324": false
}
Notes
* The response lists the employee guids and true or false indicating if the clock in was successful - the primary reason for failure is due to already being clocked in
* Job Rules (if enabled and applicable) are applied as though this is a 'web' clock
* 'customFieldData' is and available field to attach custom data, but requires additional info, details coming soon...
Clock Out Group
Description
Clock out list of employees - authenticated user must be the employees' manager or be an administrator
HTTP POST
https://api.vericlock.com/api/1.0/clock/group/out
https://api.vericlock.com/api/1.0/clock/group/out
Post Body
{
"employeeGuids":array, //(Required)[array] List of employees guids
"report":string, //[string] A text clock out report to be attached to the clock event
"flags":integer //[integer] undefined
}
Response
{
"23930782-390b-439f-88b6-7576593b3c6f": true,
"9583b0b8-7eda-42ec-bbf0-7cdc8a7c48b8": true,
"390bb0b8-439f-490b-7576-239307824324": false
}
Notes
* The response lists the employee guids and true or false indicating if the clock out was successful - the primary reason for failure is due to already being clocked out
* 'customFieldData' coming soon
Deep Link
Deep link handler
Schedule
Schedule
Webhooks
function _validateSignature($privateKey, $data, $signature)
{
$sig = hash_hmac('sha256', $data, $privateKey);
return ($sig === $signature);
}
- $privateKey is binary.
- $data is the URI ('/' if blank) concatenated with the request body
- $signature is the HEX string in the http header: VERICLOCK_SIGNATURE