Time Portal provides an API for programmatically inserting and updating data via HTTP requests. This allows external applications to maintain information such as an Employee List that can be synchronized with Time Portal.
An API Key is required to access the API and can be obtained by contacting the Time Portal Customer Service Team.
Basic Usage
The API can be called by submitting an HTTP POST request to https://app.timeportal.io/api/import/data with JSON data in the body as illustrated:
The above example represents a subset of the information that can be submitted to the API which can also be used to insert or update information for Employees, Locations, Growers, Jobs and much more.
As illustrated below, the HTTP Response will include JSON data that includes the complete Import Data Object Model which is described in a later section of this article.
Notice the summary information near the top of the response provides overall error information as well as a count of inserted/updated records. Within each record, fields such as "IsError", "ErrorMessage" and "IsDuplicate" provide record-level success indications.
When submitting Employee records, the "Number" field is used as a key to determine if the record should be inserted or updated. In the above example, the value for "IsNew" in the response indicates that the record was inserted. A subsequent request with the same JSON data would result in a value of false for "IsNew" and a value of true for "IsUpdated" for both Employees.
When submitting Job, Location, Crop/Variety and other types of records, the "Code" or "Name" fields are used as the key to determine if the record should be inserted or updated.
Since boolean fields such as "IsActive" will default to false, a value of true should be provided for each Employee that should be considered active.
The Import Data Object Model
The JSON object below describes the Import Data Object Model. As illustrated in the Basic Usage section, it is not necessary to submit the entire data object but calling programs may find it useful to examine extended response properties in order to determine which records were successfully inserted or updated.
- Properties such as "CannedNotes", "Crews", "CropVarieties" and "Employees" represent arrays of JSON objects for each type of entity. For the purpose of this document, an empty object has been placed into each of the array properties in order to identify fields available in each model. Empty arrays will normally appear as open/close square brackets "[]".
- It is not necessary to submit the entire JSON object which is described below however the HTTP Response will include the serialized Import Data Object Model with all of the properties for each submitted entity. Notice that every entity type includes properties such as ErrorMessage, IsError, IsNew, IsUpdate, IsDuplicate, IsNoChange which can be used to confirm successful submission of each record.
- Most fields have a data type of string and the data type for fields with names that end in "Id" or "Count" are number (integer.) Some fields such as "minimumWage" are number (decimal) and fields that start with "Is" are boolean.
- Each record type includes a field whose name starts with "New" and can be used to update the key field. For example, an Employee's number can be updated by specifying the original value in the "Number" field and the updated value in the "NewEmployeeNumber" field. Once a record's key field has been updated, subsequent requests to the API should use the updated value to perform updates and avoid insertion of a record using the former key value.
{
"ApiKey": null,
"ErrorMessage": null,
"DuplicateRecordCount": 0,
"InsertRecordCount": 0,
"UpdateRecordCount": 0,
"ErrorRecordCount": 0,
"HasDataErrors": false,
"ErrorRecords": [],
"CannedNotes": [
{
"CannedNoteId": 0,
"CompanyId": 0,
"EntityTypeId": 0,
"Name": null,
"NameSpanish": null,
"Text": null,
"NewName": null,
"Id": 0,
"Key": null,
"Badge": null,
"EntityType": 30,
"ErrorMessage": null,
"IsError": false,
"IsNew": false,
"IsUpdate": false,
"IsDuplicate": false,
"IsNoChange": false,
"IsImportRecord": false
}
],
"Crews": [
{
"Code": null,
"CompanyId": 0,
"CrewId": 0,
"HourlyRate": null,
"IsActive": false,
"LeaderId": null,
"LeaderName": null,
"MinimumWage": null,
"Name": null,
"NewCode": null,
"Id": 0,
"Key": null,
"Badge": null,
"EntityType": 7,
"ErrorMessage": null,
"IsError": false,
"IsNew": false,
"IsUpdate": false,
"IsDuplicate": false,
"IsNoChange": false,
"IsImportRecord": false
}
],
"CropVarieties": [
{
"CropVarietyId": 0,
"CompanyId": 0,
"Name": null,
"Description": null,
"NameSpanish": null,
"IsActive": false,
"NewName": null,
"Id": 0,
"Key": null,
"Badge": null,
"EntityType": 8,
"ErrorMessage": null,
"IsError": false,
"IsNew": false,
"IsUpdate": false,
"IsDuplicate": false,
"IsNoChange": false,
"IsImportRecord": false
}
],
"Employees": [
{
"BadgeNumber": null,
"CompanyId": 0,
"ContractNumber": null,
"CrewCode": null,
"CrewId": null,
"CrewName": null,
"CustomDataJson": null,
"DateOfBirth": null,
"EmployeeId": 0,
"FirstName": null,
"HourlyRate": null,
"MinimumWage": null,
"IsActive": false,
"IsH2A": false,
"LastName": null,
"MiddleName": null,
"MobileRoleId": 0,
"Number": null,
"PayrollJson": null,
"PhoneNumber": null,
"Photo": null,
"TeamId": null,
"TeamName": null,
"DefaultJobId": null,
"WorkerContractId": null,
"ContractStartDate": null,
"ContractEndDate": null,
"EmployeeContractStartDate": null,
"EmployeeContractEndDate": null,
"NewEmployeeNumber": null,
"FormDataJson": null,
"Id": 0,
"Key": null,
"Badge": null,
"EntityType": 9,
"FullName": "",
"MobileRoleName": "None",
"ErrorMessage": null,
"IsError": false,
"IsNew": false,
"IsUpdate": false,
"IsDuplicate": false,
"IsNoChange": false,
"IsImportRecord": false
}
],
"Growers": [
{
"IsGrower": true,
"IsHarvester": false,
"IsHauler": false,
"IsProcessor": false,
"ProfileId": 0,
"CompanyId": 0,
"Code": null,
"Name": null,
"IsActive": false,
"NewCode": null,
"Id": 0,
"Key": null,
"Badge": null,
"EntityType": 4,
"ErrorMessage": null,
"IsError": false,
"IsNew": false,
"IsUpdate": false,
"IsDuplicate": false,
"IsNoChange": false,
"IsImportRecord": false
}
],
"Jobs": [
{
"Code": null,
"CompanyId": 0,
"HasPrecedence": false,
"HourlyRate": null,
"IsBreak": false,
"IsTimeIgnored": false,
"JobId": 0,
"Name": null,
"PayrollJson": null,
"PayType": null,
"PayTypeId": 0,
"PieceRate": null,
"Uom": null,
"UomId": null,
"WorkerCompCode": null,
"WorkerCompId": null,
"IsDefaultForPayType": false,
"MinimumWage": null,
"NameSpanish": null,
"UomSpanish": null,
"IsActive": false,
"NewCode": null,
"Id": 0,
"Key": null,
"Badge": null,
"EntityType": 16,
"ErrorMessage": null,
"IsError": false,
"IsNew": false,
"IsUpdate": false,
"IsDuplicate": false,
"IsNoChange": false,
"IsImportRecord": false
}
],
"Locations": [
{
"LocationId": 0,
"CompanyId": 0,
"Name": null,
"NameSpanish": null,
"Description": null,
"IsActive": false,
"GeoJson": null,
"GeoJsonCenter": null,
"Acres": 0.0,
"Address": null,
"Notes": null,
"IsDestination": false,
"ProfileCode": null,
"ProfileId": null,
"NewName": null,
"Id": 0,
"Key": null,
"Badge": null,
"EntityType": 1,
"ErrorMessage": null,
"IsError": false,
"IsNew": false,
"IsUpdate": false,
"IsDuplicate": false,
"IsNoChange": false,
"IsImportRecord": false
}
],
"Reasons": [
{
"ReasonId": 0,
"Code": null,
"CompanyId": 0,
"Description": null,
"DescriptionSpanish": null,
"IsActive": false,
"IsMissedHoursAppliedTo34Guarantee": false,
"IsNoShow": false,
"NewCode": null,
"Key": null,
"Id": 0,
"Badge": null,
"EntityType": 26,
"ErrorMessage": null,
"IsError": false,
"IsNew": false,
"IsUpdate": false,
"IsDuplicate": false,
"IsNoChange": false,
"IsImportRecord": false
}
],
"Uoms": [
{
"UomId": 0,
"CompanyId": 0,
"Name": null,
"NameSpanish": null,
"NewName": null,
"Key": null,
"Id": 0,
"Badge": null,
"EntityType": 22,
"ErrorMessage": null,
"IsError": false,
"IsNew": false,
"IsUpdate": false,
"IsDuplicate": false,
"IsNoChange": false,
"IsImportRecord": false
}
],
"Teams": [
{
"TeamId": 0,
"Name": null,
"BadgeNumber": null,
"CompanyId": 0,
"IsActive": false,
"NewName": null,
"Id": 0,
"Key": null,
"Badge": null,
"EntityType": 56,
"ErrorMessage": null,
"IsError": false,
"IsNew": false,
"IsUpdate": false,
"IsDuplicate": false,
"IsNoChange": false,
"IsImportRecord": false
}
]
}
Comments
0 comments
Please sign in to leave a comment.