Event Stream Documentation

Introduction

People First captures many events that occur as a result of business actions within the system (e.g. a person being created, an absence being deleted, etc.). These events are stored and exposed via an event stream api. The api contains events from multiple microservices within people first. The event stream enables consumers to identify exactly what has happened in the system and when it happened. Its purpose is for systems integration: to facilitate the synchronisation of information between multiple software systems. It is not an audit facility as it does not record all events, nor does it always record before and after information.

Accessing the Event Stream API

Like all People First APIs, the Event Stream API requires authentication in order for an application to access it and make API calls. This is achieved in three parts:

Application Configuration

In order to acquire an access token and access the event stream api, the following tasks need to be carried out:

  1. An application needs to be configured within People First.
  2. An access token, permissioned with the appropriate role, needs to be acquired for that application.

For details of how to do this, please refer to the REST API Integration section in the main API documentation.

Application Authentication

An API client authenticates itself with the Event Stream service by providing a valid token within the Authorization header of each HTTP request. For details of how to do this, please refer to the Authentication section in the main API documentation.

API Authorisation

In order to access People First events via the Event Stream API, you will need an access token that has been granted the "System Integration" role.

Event Stream API

The Event Stream API is comprised of a single RESTful endpoint. The endpoint takes the form:

PEOPLE_FIRST_BASE_URI/api/v1/rtpi/eventstream

Where:

  • PEOPLE_FIRST_BASE_URI is the base URI for your People First system (see: API Requests).

Please refer to the API Requests section in the main API documentation for details of how to construct a People First API request.

In addition to the following query parameters, the Event Stream API also supports the pagination of results (see: Pagination).

API Parameters

Input type Name Description Required
Querystring eventTypes Events of this type will be included in the response. Multiple event types can be provided as separate querystring parameters (e.g. eventTypes=SalaryChanged&eventTypes=PersonNameChanged). Optional
Querystring timeOfCreationFrom Events created on or after this dateTime will be included in the response. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z) Optional
Querystring timeOfCreationTo Events created on or before this dateTime will be included in the response. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z) Optional
Querystring timeOfReceiptFrom Events received by the event stream on or after this dateTime will be included in the response. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z) Optional
Querystring timeOfReceiptTo Events received by the event stream on or before this dateTime will be included in the response. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z) Optional

Schema Definition

The event stream schema has a similar shape to other people first apis. The eventData object contains the actual event data for which the schema will vary depending on the eventType. The schema for each eventType is defined in the events section of this page.

Field lengths

The field lengths for string based fields are listed in the documentation for each event type. These field lengths are to assist integrators when consuming data from the event stream. Some fields have limitations for business purposes (such as driving licence id or ni number), others are purely technical limitations. The technical limitations are generally higher than would be expected for a given piece of data, however it is possible that these field lengths could be increased at some point. The field lengths will never decrease.

Casing

All fields are case insensitive.

Example schema for the event stream api

{
  "data": {
    "eventStream": [{
      "id": "80e3ef54-2905-42f7-87ac-eaaed55df144",
      "eventType": "personCreated",
      "timeOfCreation": "2019-11-07T09:15:11.28Z",
      "timeOfReceipt": "2019-11-07T09:15:11.29Z",
      "eventData": {
      }
    }]
  },
  "meta": {
    "links": {
      "self": {
        "href": "/rtpi/eventstream"
      },
      "first": {
        "href": "/rtpi/eventstream?page%5BLimit%5D=2&page%5BOffset%5D=0"
      },
      "last": {
        "href": "/rtpi/eventstream?page%5BLimit%5D=2&page%5BOffset%5D=6"
      },
      "next": {
        "href": "/rtpi/eventstream?page%5BLimit%5D=2&page%5BOffset%5D=4"
      },
      "previous": {
        "href": "/rtpi/eventstream?page%5BLimit%5D=2&page%5BOffset%5D=2"
      }
    },
    "paging": {
      "pageLimit": 2,
      "pageOffset": 2,
      "totalCount": 8
    }
  }
}

The timeOfCreation and timeOfReceipt are dateTimes stored in coordinated universal time (UTC).

Eventual Consistency

Event stream events are eventually consistent and will not necessarily appear in the order the events occurred in the source microservice. However, the TimeOfCreation property does indicate when the event occurred in the source microservice.

Resource Identity

All events in the event stream are related to either a person, job or occupancy. These owning resources are referenced in all events by means of a resource id and a resource reference. The id is the resource identifier within the people first apis, which is typically a guid. The reference is a customer defined identifier, which is typically a string. The resource reference allows consumers to associate resources in the two system by an identifier that may already exist in another system, rather than having to use the people first identifier.

Reference Data

Many fields in people first are reference data (aka lookup lists). All event stream events that contain reference data will have a field containing the reference data code. This will always be the api field name suffixed with "Code".

An example of a reference data field is title.

The event stream entry MUST contain a "titleCode" (e.g. 'TITLE0001').

The event stream entry MAY contain a "title". (e.g. 'Mr')

API Compatibility Considerations

As with the other People First APIs, consumers of the Event Stream API will need to be aware of the type of changes that are considered to be backwards compatible, and will need to code their applications to handle them. This applies equally to consumers of the Event Stream REST API and consumers of Event Stream Webhook requests. Further details are available here.

Webhooks

Overview

People first can be configured to send event stream data to external systems. This is commonly used to satisfy real time systems integration requirements. Webhooks can be configured for any event type and are digitally signed for security. For details of how to configure and verify webhooks see: Webhook API Integration.

Webhook request payload

When a webhook POST request is issued, the event stream data is included in the http request body. The payload also includes the eventType and the timeOfCreation. A sample webhook request payload is shown below.

Sample webhook request payload for occupancySalaryTimelineChanged

{
  "EventData": {
    "occupancyId": "763b6741-9435-4af7-8936-a9b30101f38e",
    "personalReference": "TT1136",
    "jobReference": "TR0001",
    "startDate": "2001-01-01",
    "endDate": null,
    "salaryRevisions": [
      {
        "startDate": "2001-01-01",
        "endDate": null,
        "rateOfPay": 10000,
        "frequencyCode": "A"
      }
    ]
  },
  "EventType": "OccupancySalaryTimelineChanged",
  "TimeOfCreation": "2020-04-06T08:16:05.034765Z"
}

Events

This section explores each individual event in the event stream. It describes the event schemas and explains what system actions invoke the event.

Event types
PersonCreated
PersonNameChanged
PersonDeleted
PersonAddressCreated
PersonAddressChanged
PersonContactDetailCreated
PersonContactDetailChanged
SocialSecurityNumberChanged
EmploymentPeriodStartDateChanged
SensitiveInformationChanged
EmploymentPeriodCreated
EmploymentPeriodEnded
EmploymentPeriodReinstated
JobLeaverCreated
JobLeaverReinstated
OccupancyCreated
OccupancyEnded
OccupancyReinstated
OccupancyDeleted
OccupancyStartDateChanged
ReckonableServiceDateCreated
ReckonableServiceDateChanged
ReckonableServiceDateDeleted
OccupancyHoursAndBasisCreated
OccupancyHoursAndBasisChanged
OccupancySalaryTimelineCreated
OccupancySalaryTimelineChanged
WorkingPatternCreated
WorkingPatternChanged
AbsenceLeaveCreated
AbsenceSicknessCreated
AbsenceOtherCreated
AbsenceLeaveChanged
AbsenceSicknessChanged
AbsenceOtherChanged
AbsenceLeaveDeleted
AbsenceSicknessDeleted
AbsenceOtherDeleted
AbsenceLeaveRejected
AbsenceSicknessRejected
AbsenceOtherRejected
AbsenceLeaveApproved
AbsenceSicknessApproved
AbsenceOtherApproved
BankAccountCreated
BankAccountChanged
BankAccountDeleted
CustomCardDataCreated
CustomCardDataChanged
CustomCardDataDeleted
OccupancySalaryAndHoursTimelineChanged
OpenTimePairCreated
ClosedTimePairCreated
TimePairApproved
TimePairRejected
TimePairChanged
TimePairDeleted

PersonCreated and PersonNameChanged event

A PersonCreated event will be raised when:

  • a person is created in hrm
  • a person is onboarded into hrm via recruitment

A PersonNameChanged event will be raised when:

  • any property of a person's name is changed in hrm

Field definitions for this event

Field Name Data Type Additional information
personId guid n/a
personalReference string max-length: 20
firstName string max-length: 80
lastName string max-length: 80
otherNames string max-length: 160
knownAs string max-length: 80
previousLastName string max-length: 80
titleCode string max-length: 40; reference-data

Example of this event

{
  "personId": "",
  "personalReference": "",
  "firstName": "",
  "lastName": "",
  "otherNames": "",
  "knownAs": "",
  "previousLastName": "",
  "titleCode": ""
}

PersonDeleted event

A PersonDeleted event will be raised when:

  • a person is deleted from hrm

Field definitions for this event

Field Name Data Type Additional information
personId guid n/a
personalReference string max-length: 20

Example of this event

{
"personId": "",
"personalReference": ""
}

PersonAddressCreated and PersonAddressChanged event

A PersonAddressCreated event will be raised when:

  • the first address is created in hrm

A PersonAddressChanged event will be raised when:

  • any property of a person's address is changed in hrm

Field definitions for this event

Field Name Data Type Additional information
personId guid n/a
personalReference string max-length: 20
addressLine1 string max-length: 80
addressLine2 string max-length: 80
addressLine3 string max-length: 80
addressLine4 string max-length: 80
addressLine5 string max-length: 80
addressLine6 string max-length: 80
countryCode string max-length: 40; reference-data

Example of this event

{
  "personId": "",
  "personalReference": "",
  "addressLine1": "",
  "addressLine2": "",
  "addressLine3": "",
  "addressLine4": "",
  "addressLine5": "",
  "addressLine6": "",
  "countryCode": ""
}

PersonContactDetailCreated and PersonContactDetailChanged event

A PersonContactDetailCreated event will be raised when:

  • a person's contact details are edited for a first time in hrm

A PersonContactDetailChanged event will be raised when:

  • a person's contact details are updated

Field definitions for this event

Field Name Data Type Additional information
personId guid n/a
contactType string max-length: 40; reference-data
contactDetail string max-length: 80. Depending on the contactType, field contains an email or phone number.
internationalDialingCode string max-length: 160

Example of this event

                    {
                    "personId": "",
                    "contactType": "",
                    "contactDetail": "",
                    "internationalDialingCode": ""
                    }

SocialSecurityNumberChanged event

A SocialSecurityNumberChanged event will be raised when:

  • a new social security number is added
  • any property relating to an existing social security number is changed
  • a social security number is deleted

Field definitions for this event

Field Name Data Type Additional information
personId guid n/a
personalReference string max-length: 20
socialSecurityNumber string max-length: 80
legislationCode string max-length: 40; reference-data

Example of this event

{
  "personId": "",
  "personalReference": "",
  "socialSecurityNumbers": [{
      "socialSecurityNumber": "",
      "legislationCode": ""
    }
  ]
}

EmploymentPeriodStartDateChanged event

The payload for this event contains the Person id and reference number of the person whose employment start date has been changed and the revised start date.

An EmploymentPeriodStartDateChanged event will be raised when:

  • The Employment start date of an employee is modified

Field definitions for this event

Field Name Data Type Additional information
personId guid n/a
personalReferenceNumber string max-length: 20
employmentStartDate date the revised start date of the person's Employment Period. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
employmentPeriodId guid the identify of the employment period

Example of this event

{
          "personId": "",
          "personalReferenceNumber": "",
          "employmentStartDate": ""
          "employmentPeriodId": ""
          }

SensitiveInformationChanged event

A SensitiveInformationChanged event will be raised when:

  • a person's sensitive information is added or changed

Field definitions for this event

Field Name Data Type Additional information
personId guid n/a
personalReference string max-length: 20
dateOfBirth date The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
countryOfCitizenshipCode string max-length: 40; reference-data
religionCode string max-length: 40; reference-data
countryOfBirthCode string max-length: 40; reference-data
nationalityCode string max-length: 40; reference-data
genderCode string max-length: 40; reference-data
sexualOrientationCode string max-length: 40; reference-data
maritalStatusCode string max-length: 40; reference-data
selfCertifiedDisabilityDescription string max-length: 255
legalGenderCode string max-length: 40; reference-data
regionCode string max-length: 40; reference-data
usEthnicOriginCode string max-length: 40; reference-data
singaporeanEthnicOriginCode string max-length: 40; reference-data
ukEthnicOriginCode string max-length: 40; reference-data
veteranStatusCode string max-length: 40; reference-data

Example of this event

{
  "personId": "",
  "personalReference": "",
  "dateOfBirth": "",
  "countryOfCitizenshipCode": "",
  "religionCode": "",
  "countryOfBirthCode": "",
  "nationalityCode": "",
  "genderCode": "",
  "sexualOrientationCode": "",
  "maritalStatusCode": "",
  "selfCertifiedDisabilityDescription": "",
  "regionalSensitiveInformations": [{
      "regionCode": "US",
      "usEthnicOriginCode": "",
      "veteranStatusCode": "",
      "legalGenderCode": ""
    },
    {
      "regionCode": "Singapore",
      "singaporeanEthnicOriginCode": "",
      "legalGenderCode": ""
    },
    {
      "regionCode": "UK",
      "ukEthnicOriginCode": "",
      "legalGenderCode": ""
    }
  ]
}

EmploymentPeriodCreated, EmploymentPeriodEnded and EmploymentPeriodReinstated event

An EmploymentPeriodCreated event will be raised when:

  • an employment period is created in hrm (currently in people first, this automatically happens when a person is created)

An EmploymentPeriodEnded event will be raised when:

  • a person is made a leaver (this effectively occurs when and end date is added to an employment period)

An EmploymentPeriodReinstated event will be raised when:

  • the action of making a person a leaver action is reverted (this effectively occurs when the end date is removed from an employment period)

Field definitions for this event

Field Name Data Type Additional information
personId guid n/a
personalReference string max-length: 20
startDate date The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
endDate date The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
employerName string 80
isExitInterviewCompleted boolean n/a
lastPaymentDate date The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
lastWorkingDate date The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
reEmployable string max-length: 80
reEmployableCode string max-length: 40; reference-data
reasonForLeaving string max-length: 80
reasonForLeavingCode string max-length: 40; reference-data
forwardingAddressType string max-length: 80
forwardingAddressTypeCode string max-length: 40; reference-data
line1 string max-length: 80
line2 string max-length: 80
line3 string max-length: 80
line4 string max-length: 80
line5 string max-length: 80
line6 string max-length: 80

Example of this event

{
  "personId": "",
  "personalReference": "",
  "startDate": "",
  "endDate": "",
  "employerName": "",
  "isExitInterviewCompleted": "",
  "lastPaymentDate": "",
  "lastWorkingDate": "",
  "reEmployable": "",
  "reEmployableCode": "",
  "reasonForLeaving": "",
  "reasonForLeavingCode": "",
  "forwardingAddressType": "",
  "forwardingAddressTypeCode": "",
  "forwardingAddress": ""{
    "line1": "",
    "line2": "",
    "line3": "",
    "line4": "",
    "line5": "",
    "line6": ""
  }
}

JobLeaverCreated and JobLeaverReinstated event

A JobLeaverCreated event will be raised when:

  • a user with multiple occupancies leaves one of their jobs

A JobLeaverReinstated event will be raised when:

  • the action of making a person a leaver from a job action is reverted

Field definitions for this event

Field Name Data Type Additional information
personId guid n/a
personalReferenceNumber string max-length: 20
jobReferenceNumber string max-length: 20
occupancyId guid n/a
leaveDate date The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
lastWorkingDate date The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
lastPaymentDate date The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
reasonForLeaving string max-length: 80
isReEmployable string max-length: 80
isExitInterviewCompleted boolean n/a

Example of this event

{
  "personId": "",
  "personalReferenceNumber": "",
  "jobReferenceNumber": "",
  "occupancyId": "",
  "leaveDate": "",
  "lastWorkingDate": "",
  "lastPaymentDate": "",
  "reasonForLeaving": "",
  "isReEmployable": "",
  "isExitInterviewCompleted": ""
}

OccupancyCreated, OccupancyEnded, OccupancyReinstated and OccupancyDeleted events

The payload for these events contains an array of job titles, showing the changes to job title over time. The array for the jobTitleChanged event will only contain the jobTitles after and including the one that was changed. The reason for this is that changing a job title can have an effect on a subsequent job title revisions, but it cannot affect previous ones.

An OccupancyCreated event will be raised when:

  • a person starts a new job (this effectively creates a new occupancy resource)

An OccupancyEnded event will be raised when:

  • a person finishes in a job (this effectively occurs when an end date is applied to an existing occupancy)

An OccupancyReinstated event will be raised when:

  • the ending of a person in a job is reverted (this effectively occurs when an end date is removed from an existing occupancy)

An OccupancyDeleted event will be raised when:

  • a person's association with a job is deleted (this is not the same as ending an occupancy)

Field definitions for this event

Field Name Data Type Additional information
occupancyId guid n/a
personalReference string max-length: 20
jobReference string max-length: 20
startDate date the start date of the occupancy. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
endDate date the end date of the occupancy. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
name string max-length: 80. The job title of the assigned job on the given revision dates
startDate date the start date of the job title revision. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
endDate date the end date of the job title revision. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)

Example of this event

{
  "occupancyId": "",
  "personalReference": "",
  "jobReference": "",
  "startDate": "",
  "endDate": "",
  "jobTitleRevisions": [{
    "name": "",
    "startDate": ""
    "endDate": ""
    }
  ]
}

OccupancyStartDateChanged event

The payload for this event contains the Person id and reference number of the person whose occupancy start date has been changed along with the Occupancy id and the revised start date.

An OccupancyStartDateChanged event will be raised when:

  • The Occupancy start date of an employee has been modified

Field definitions for this event

Field Name Data Type Additional information
personId guid n/a
personalReferenceNumber string max-length: 20
occupancyId guid the identify of the occupancy
occupancyStartDate date the revised start date of the person's Occupancy. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)

Example of this event

{
"personId": "",
"personalReferenceNumber": "",
"occupancyId": ""
"occupancyStartDate": ""
}

ReckonableServiceDateCreated and ReckonableServiceDateChanged event

A ReckonableServiceDateCreated event will be raised when:

  • A reckonable service date is added for an employment period that does not already have one

A ReckonableServiceDateChanged event will be raised when:

  • A reckonable service date is changed for an employment period

Field definitions for this event

Field Name Data Type Additional information
personId guid n/a
personalReferenceNumber string max-length: 20
employmentPeriodId guid n/a
reckonableServiceDate date the revised reckonable service date. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)

Example of this event

{
"personId": "",
"personalReferenceNumber": "",
"employmentPeriodId": ""
"reckonableServiceDate": ""
}

ReckonableServiceDateDeleted event

A ReckonableServiceDateDeleted event will be raised when:

  • A reckonable service date is deleted for an employment period

Field definitions for this event

Field Name Data Type Additional information
personId guid n/a
personalReferenceNumber string max-length: 20
employmentPeriodId guid n/a

Example of this event

{
"personId": "",
"personalReferenceNumber": "",
"employmentPeriodId": ""
}

OccupancyHoursAndBasisCreated and OccupancyHoursAndBasisChanged events

The payload for these events contains an array of hours and basis revisions, showing the changes to the hours and basis over time. The array will only contain the hours and bases after and including the one that was changed. The reason for this is that changing hours and bases can have an effect on a subsequent hours and basis revisions, but it cannot affect previous ones.

An OccupancyHoursAndBasisCreated event will be raised when:

  • a person is assigned to a job

An OccupancyHoursAndBasisChanged event will be raised when:

  • the hours and basis for a person is changed (hours and basis can be inherited attributes and therefore changes to the source/inherited values will raise this event)

Field definitions for this event

Field Name Data Type Additional information
occupancyId guid n/a
personalReference string max-length: 20
personId guid n/a
jobReference string max-length: 20
startDate date the start date of the occupancy. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
endDate date the end date of the occupancy. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
startDate date the start date of the hours and basis revision. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
endDate date the end date of the hours and basis revision. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
contractualHours decimal
fteHours decimal
fteValue decimal
annualWeeksWorked decimal
categoryCode string max-length: 40; reference-data
basisCode string max-length: 40; reference-data
typeCode string max-length: 40; reference-data
employmentIsTermTimeOnly boolean n/a

Example of this event

{
  "occupancyId": "",
  "personalReference": "",
  "jobReference": "",
  "startDate": "",
  "endDate": "",
  "hoursAndBasisRevisions": [{
      "startDate": "",
      "endDate": "",
      "contractualHours": "",
      "fteHours": "",
      "fteValue": "",
      "annualWeeksWorked": "",
      "categoryCode": "",
      "basisCode": "",
      "typeCode": "",
      "employmentIsTermTimeOnly": ""
    }
  ]
}

OccupancySalaryTimelineCreated and OccupancySalaryTimelineChanged events

The payload for these events contains an array of salary revisions, showing the changes to the salary over time. The array will only contain the salaries after and including the one that was changed. The reason for this is that changing salary can have an effect on a subsequent salary revisions, but it cannot affect previous ones.

An OccupancySalaryTimelineCreated event will be raised when:

  • a person is added to their first job

An OccupancySalaryTimelineChanged event will be raised when:

  • the salary for a person is changed (salary can have inherited attributes and therefore changes to the source/inherited values will raise this event)

Field definitions for this event

Field Name Data Type Additional information
occupancyId guid n/a
personalReference string max-length: 20
jobReference string max-length: 20
startDate date the start date of the occupancy. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
endDate date the end date of the occupancy. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
startDate date the start date of the salary revision. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
endDate date the end date of the salary revision. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
rateOfPay decimal
frequencyCode string reference-data

Example of this event

{
  "occupancyId": "",
  "personalReference": "",
  "jobReference": "",
  "startDate": "",
  "endDate": "",
  "salaryRevisions": [{
      "startDate": "",
      "endDate": "",
      "rateOfPay": "",
      "frequencyCode": ""
    }
  ]
}

WorkingPatternCreated and WorkingPatternChanged events

The payload for these events contains an array of working pattern revisions, showing the changes to the working pattern over time. The array will only contain the working patterns after and including the one that was changed. The reason for this is that changing working pattern can have an effect on a subsequent working pattern revisions, but it cannot affect previous ones.

A WorkingPatternCreated event will be raised when:

  • a person is added to their first job

A WorkingPatternChanged event will be raised when:

  • the working pattern for a person is changed (working pattern can be inherited attributes and therefore changes to the source/inherited values will raise this event)

Field definitions for this event

Field Name Data Type Additional information
occupancyId guid n/a
personalReference string max-length: 20
jobReference string max-length: 20
startDate date the start date of the occupancy. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
endDate date the end date of the occupancy. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
startDate date the start date of the hours and basis revision. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
endDate date the end date of the hours and basis revision. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
name string max-length: 80
startDayNumber integer n/a
numberOfDays integer n/a
dayNumber integer n/a
totalMinutes integer n/a

Example of this event

{
  "occupancyId": "",
  "personalReference": "",
  "jobReference": "",
  "startDate": "",
  "endDate": "",
  "workingPatternRevisions": [{
          "startDate": "",
          "endDate": "",
          "name": "",
          "startDayNumber": "",
          "numberOfDays": [{
            "dayNumber": "",
            "totalMinutes": ""
        }
      ]
    }
  ]
}

AbsenceLeaveCreated, AbsenceSicknessCreated, and AbsenceOtherCreated events

An AbsenceLeaveCreated, AbsenceSicknessCreated or AbsenceOtherCreated event will be raised when:

  • a leave|sickness|other absence is created for a person

Field definitions for this event

Field Name Data Type Additional information
personId guid Unique Person Identifier
personalReference string max-length: 20
occupancyId guid Unique Occupancy Identifier
jobReference string max-length: 20
absenceId guid Unique Absence Identifier
absenceTypeCode string max-length: 40; reference-data
absenceTypeName string max-length: 80; reference-data
absenceCategoryCode string max-length: 40; Indicator of category the absence type is allocated to (i.e. Leave, Sickness, Family or Other)
startDate date The start date of the absence in ISO format in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
startDatePartCode string max-length: 40; reference-data
startDateTotalMinutes integer Duration of the start day of the absence (in minutes) [booking in hours only]
endDate date The end date of the absence in ISO format in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
endDatePartCode string max-length: 40; reference-data
endDateTotalMinutes integer Duration of the end day of the absence (in minutes) [booking in hours only]
absenceStateCode string max-length: 40; reference-data. The approval state of the absence.
expectedEndDate date The expected end date (if open ended absence) in ISO format in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
sicknessReason string max-length: 80; reference-data
absenceBookedDate datetime The date and time the absence was booked in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
lostHours integer (Deprecated. Replaced by totals in minutes fields)
totalExpectedWorkingTimeInMinutes integer Sum of the hours worked over period according to their working pattern in minutes
totalLostTimeInMinutes integer Sum of the hours booked as absence over the period in minutes

Example of this event

{
  "personId": "",
  "personalReference": "",
  "occupancyId": "",
  "jobReference": "",
  "absenceId": "",
  "absenceTypeCode": "",
  "absenceTypeName": "",
  "absenceCategoryCode": "",
  "startDate": "",
  "startDatePartCode": "",
  "startDateTotalMinutes": "",
  "endDate": "",
  "endDatePartCode": "",
  "endDateTotalMinutes": "",
  "absenceStateCode": "",
  "expectedEndDate": "",
  "sicknessReason": "",
  "absenceBookedDate": "",
  "lostHours": "",
  "totalExpectedWorkingTimeInMinutes": "",
  "totalLostTimeInMinutes": ""
}

AbsenceLeaveChanged, AbsenceSicknessChanged and AbsenceOtherChanged events

An AbsenceLeaveChanged, AbsenceSicknessChanged or AbsenceOtherChanged event will be raised when:

  • any properties on a leave|sickness|other absence are changed

Field definitions for this event

Field Name Data Type Additional information
personId guid Unique Person Identifier
personalReference string max-length: 20
occupancyId guid Unique Occupancy Identifier
jobReference string max-length: 20
absenceId guid Unique Absence Identifier
absenceTypeCode string max-length: 40; reference-data
absenceTypeName string max-length: 80; reference-data
absenceCategoryCode string max-length: 40; Indicator of the category the absence type is allocated to (i.e. Leave, Sickness, Family or Other)
originalStartDate date The start date prior to the change in ISO format in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
originalStartDatePartCode string max-length: 40; reference-data. The start day part code prior to the change.
originalStartDateTotalMinutes integer Duration of the start day of the absence (in minutes) prior to the change [booking in hours only]
startDate date The start date of the absence in ISO format in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
startDatePartCode string max-length: 40; reference-data
startDateTotalMinutes integer Duration of the start day of the absence (in minutes) [booking in hours only]
originalEndDate date The end date prior to the change in ISO format in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
originalEndDatePartCode string max-length: 40; reference-data. The end day part code prior to the change.
originalEndDateTotalMinutes integer Duration of the end day of the absence (in minutes) prior to the change [booking in hours only]
endDate date The end date of the absence is in ISO format in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
endDatePartCode string max-length: 40; reference-data
endDateTotalMinutes integer Duration of the end day of the absence (in minutes) [booking in hours only]
absenceStateCode string max-length: 40; reference-data. The approval state of the absence.
previousAbsenceStateCode string max-length: 40; reference-data. The approval state prior to the change.
expectedEndDate date The expected end date of the absence (if open ended) in ISO format in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
sicknessReason string max-length: 80; reference-data
absenceBookedDate datetime The date and time the absence was booked in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
lostHours integer (Deprecated. Replaced by totals in minutes fields)
totalExpectedWorkingTimeInMinutes integer Sum of the hours worked over period according to their working pattern in minutes
totalLostTimeInMinutes integer Sum of the hours booked as absence over the period in minutes

Example of this event

{
  "personId": "",
  "personalReference": "",
  "occupancyId": "",
  "jobReference": "",
  "absenceId": "",
  "absenceTypeCode": "",
  "absenceTypeName": "",
  "absenceCategoryCode": "",
  "originalStartDate": "",
  "originalStartDatePartCode": "",
  "originalStartDateTotalMinutes": "",
  "startDate": "",
  "startDatePartCode": "",
  "startDateTotalMinutes": "",
  "originalEndDate": "",
  "originalEndDatePartCode": "",
  "originalEndDateTotalMinutes": "",
  "endDate": "",
  "endDatePartCode": "",
  "endDateTotalMinutes": "",
  "absenceStateCode": "",
  "previousAbsenceStateCode": "",
  "expectedEndDate": "",
  "sicknessReason": "",
  "absenceBookedDate": "",
  "lostHours": "",
  "totalExpectedWorkingTimeInMinutes": "",
  "totalLostTimeInMinutes": ""
}

AbsenceLeaveDeleted, AbsenceSicknessDeleted and AbsenceOtherDeleted events

An AbsenceLeaveDeleted, AbsenceSicknessDeleted or AbsenceOtherDeleted event will be raised when:

  • a leave|sickness|other absence is deleted

Field definitions for this event

Field Name Data Type Additional information
personId guid Unique Person Identifier
personalReference string max-length: 20
occupancyId guid Unique Occupancy Identifier
jobReference string max-length: 20
absenceId guid Unique Absence Identifier
absenceTypeCode string max-length: 40; reference-data
absenceTypeName string max-length: 80; reference-data
absenceCategoryCode string max-length: 40; Indicator of category the absence type is allocated to (i.e. Leave, Sickness, Family or Other)
startDate date The date is in ISO format in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
startDatePartCode string max-length: 40; reference-data
startDateTotalMinutes integer Duration of the start day of the absence (in minutes) [booking in hours only]
endDate date The date is in ISO format in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
endDatePartCode string max-length: 40; reference-data
endDateTotalMinutes integer Duration of the end day of the absence (in minutes) [booking in hours only]
expectedEndDate date The expected end date of the absence (if open ended) in ISO format in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
sicknessReason string max-length: 80; reference-data
absenceBookedDate datetime The date and time the absence was booked in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
lostHours integer (Deprecated. Replaced by totals in minutes fields)
totalExpectedWorkingTimeInMinutes integer Sum of the hours worked over period according to their working pattern in minutes
totalLostTimeInMinutes integer Sum of the hours booked as absence over the period in minutes

Example of this event

{
  "personId": "",
  "personalReference": "",
  "occupancyId": "",
  "jobReference": "",
  "absenceId": "",
  "absenceTypeCode": "",
  "absenceTypeName": "",
  "absenceCategoryCode": "",
  "startDate": "",
  "startDatePartCode": "",
  "startDateTotalMinutes": "",
  "endDate": "",
  "endDatePartCode": "",
  "endDateTotalMinutes": "",
  "expectedEndDate": "",
  "sicknessReason": "",
  "absenceBookedDate": "",
  "lostHours": "",
  "totalExpectedWorkingTimeInMinutes": "",
  "totalLostTimeInMinutes": ""
}

AbsenceLeaveRejected, AbsenceSicknessRejected and AbsenceOtherRejected events

An AbsenceLeaveRejected, AbsenceSicknessRejected or AbsenceOtherRejected event will be raised when:

  • a leave|sickness|other absence is rejected

Field definitions for this event

Field Name Data Type Additional information
personId guid Unique Person Identifier
personalReference string max-length: 20
occupancyId guid Unique Occupancy Identifier
jobReference string max-length: 20
absenceId guid Unique Absence Identifier
absenceTypeCode string max-length: 40; reference-data
absenceTypeName string max-length: 80; reference-data
absenceCategoryCode string max-length: 40; Indicator of category the absence type is allocated to (i.e. Leave, Sickness, Family or Other)
startDate date The start date of the absence in ISO format in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
startDatePartCode string max-length: 40; reference-data
startDateTotalMinutes integer Duration of the start day of the absence (in minutes) [booking in hours only]
endDate date The end date of the absence in ISO format in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
endDatePartCode string max-length: 40; reference-data
endDateTotalMinutes integer Duration of the end day of the absence (in minutes) [booking in hours only]
expectedEndDate date The expected end date of the absence (if open ended) in ISO format in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
sicknessReason string max-length: 80; reference-data
absenceBookedDate datetime The date and time the absence was booked in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
lostHours integer (Deprecated. Replaced by totals in minutes fields)
totalExpectedWorkingTimeInMinutes integer Sum of the hours worked over period according to their working pattern in minutes
totalLostTimeInMinutes integer Sum of the hours booked as absence over the period in minutes

Example of this event


{
  "personId": "",
  "personalReference": "",
  "occupancyId": "",
  "jobReference": "",
  "absenceId": "",
  "absenceTypeCode": "",
  "absenceTypeName": "",
  "absenceCategoryCode": "",
  "startDate": "",
  "startDatePartCode": "",
  "startDateTotalMinutes": "",
  "endDate": "",
  "endDatePartCode": "",
  "endDateTotalMinutes": "",
  "expectedEndDate": "",
  "sicknessReason": "",
  "absenceBookedDate": "",
  "lostHours": "",
  "totalExpectedWorkingTimeInMinutes": "",
  "totalLostTimeInMinutes": ""
}

AbsenceLeaveApproved, AbsenceSicknessApproved and AbsenceOtherApproved events

An AbsenceLeaveApproved, AbsenceSicknessApproved or AbsenceOtherApproved event will be raised when:

  • a leave|sickness|other absence is approved

Field definitions for this event

Field Name Data Type Additional information
personId guid Unique Person Identifier
personalReference string max-length: 20
occupancyId guid Unique Occupancy Identifier
jobReference string max-length: 20
absenceId guid Unique Absence Identifier
absenceTypeCode string max-length: 40; reference-data
startDate date The start date of the absence in ISO format in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
startDatePartCode string max-length: 40; reference-data
startDateTotalMinutes integer Duration of the start day of the absence (in minutes) [booking in hours only]
endDate date The end date of the absence in ISO format in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
endDatePartCode string max-length: 40; reference-data
endDateTotalMinutes integer Duration of the end day of the absence (in minutes) [booking in hours only]
expectedEndDate date The expected end date of the absence (if open ended) in ISO format in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
sicknessReason string max-length: 80; reference-data
absenceBookedDate datetime The date and time the absence was booked in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
lostHours integer (Deprecated. Replaced by totals in minutes fields)
totalExpectedWorkingTimeInMinutes integer Sum of the hours worked over period according to their working pattern in minutes
totalLostTimeInMinutes integer Sum of the hours booked as absence over the period in minutes

Example of this event


{
  "personId": "",
  "personalReference": "",
  "occupancyId": "",
  "jobReference": "",
  "absenceId": "",
  "absenceTypeCode": "",
  "absenceTypeName": "",
  "absenceCategoryCode": "",
  "startDate": "",
  "startDatePartCode": "",
  "startDateTotalMinutes": "",
  "endDate": "",
  "endDatePartCode": "",
  "endDateTotalMinutes": "",
  "expectedEndDate": "",
  "sicknessReason": "",
  "absenceBookedDate": "",
  "lostHours": "",
  "totalExpectedWorkingTimeInMinutes": "",
  "totalLostTimeInMinutes": ""
}

BankAccountCreated, BankAccountChanged and BankAccountDeleted events

The payload for these events contains an array of bank accounts related to a person.

A BankAccountCreated event will be raised when:

  • a person adds a new bank account

A BankAccountChanged event will be raised when:

  • the person updates an existing bank account

A BankAccountDeleted event will be raised when:

  • the person deletes an existing bank account

Field definitions for this event

Field Name Data Type Additional information
personId guid n/a
personalReference string max-length: 20
abaNumber string
accountHolderName string
accountNumber string
accountTypeCode string
bankAccountCountryCode string
bankAddress string
bankName string
bic string
branchName string
clabeNumber string
iban string
isPrimary boolean
percentageSplit int
rollNumber string
routingCode string
sortCode string

Example of this event


{
  "personId": "",
  "personalReference": "",
  "abaNumber": "",
  "accountHolderName": "",
  "accountNumber": "",
  "accountTypeCode": "",
  "bankAccountCountryCode": "",
  "bankAddress": "",
  "bankName": "",
  "bic": "",
  "branchName": "",
  "clabeNumber": "",
  "iban": "",
  "isPrimary": "",
  "percentageSplit": "",
  "rollNumber": "",
  "routingCode": "",
  "sortCode": ""
}

CustomCardDataCreated, CustomCardDataChanged and CustomCardDataDeleted events

The payload for these events contains custom card data.

A CustomCardDataCreated event will be raised when:

  • a new record is added against a card with integration enabled.

A CustomCardDataChanged event will be raised when:

  • an existing record is updated against a card with integration enabled.

A CustomCardDataDeleted event will be raised when:

  • a record is deleted against a card with integration enabled.

Field definitions for this event

Field Name Data Type Additional information
cardId guid The ID of the card schema.
cardName string The name of the card schema.
entityId guid The ID of the linked entity.
entityType string The entity type defined in the card schema. For example, it could be employee, occupancy, page...
dynamic dynamic Repeatable, each field name and data type are dynamic, based on the design of the card schema.

Example of this event


{
  "cardId": "00000001-0001-0001-0001-000000000001",
  "cardName": "Card Name",
  "entityId": "00000002-0002-0002-0002-000000000002",
  "entityType": "employee",
  "*textField": "Text goes here",
  "*checkboxField": true,
  "*numberField": 1234
}

*The field names would match the card schema field labels, the example mentions the data type as the field name only to illustrate the dynamic property value.

OccupancySalaryAndHoursTimelineChanged event

The payload for this event contains an array of calculated values based on the 'salary' and the 'hours and basis' revisions, showing the changes over time. The array will only contain the changes after and including the one that was changed. The reason for this is that changes can have an effect on a subsequent revisions, but it cannot affect previous ones.

An OccupancySalaryAndHoursTimelineChanged event will be raised when:

  • the salary for a person is changed (salary can have inherited attributes and therefore changes to the source/inherited values will raise this event)
  • and/or the hours and basis for a person is changed (again this can have inherited attributes and therefore changes to the source/inherited values will raise this event)

Field definitions for this event

Field Name Data Type Additional information
occupancyId guid n/a
personId guid n/a
personalReferenceNumber string max-length: 20
startDate date the start date of the salary and/or hours and basis revision. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
endDate date the end date of the salary and/or hours and basis revision. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
proRatedSalary decimal
annualHoursWorked decimal
fteValue decimal
hourlyRate decimal
hourlyRateDaily decimal
frequencyCode string reference-data
currencyCode string reference-data

Example of this event

{
  "occupancyId": "",
  "personId": "",
  "personalReferenceNumber": "",
  "salaryRevisions": [{
      "startDate": "",
      "endDate": "",
      "proRatedSalary": "",
      "annualHoursWorked": "",
      "fteValue": "",
      "hourlyRate": "",
      "hourlyRateDaily": "",
      "frequencyCode": ""
      "currencyCode": ""
    }
  ]
}

OpenTimePairCreated event

The payload for this event contains the Time-pair details.

An OpenTimePairCreated event will be raised when:

  • a person clocks-in
  • an open time-pair is manually created

An OpenTimePairCreated event will only ever contain start time details - the end time details will be null.

Field definitions for this event

Field Name Data Type Additional information
PersonalReferenceNumber string The reference number of the person to whom the time-pair belongs. Max-length: 20
PersonFirstname string The first name of the person to whom the time-pair belongs. Max-length: 80
PersonLastname string The last name of the person to whom the time-pair belongs. Max-length: 80
TimePairType string Standard or Overtime
StartTime datetime The start date of the Time-pair. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
StartTimeZone string The starting Time Zone of the Time-pair. The Time Zone is in IANA format i.e. continent or ocean followed by the name of the largest city within the region e.g. Pacific/Honolulu.
StartLongitude decimal The starting Geolocation Longitude of the Time-pair. The value is in decimal degrees format and ranges from -180 to 180. For example, Washington DC has a longitude -77.0364.
StartLatitude decimal The starting Geolocation Latitude of the Time-pair. The value is in decimal degrees format and ranges from -90 to 90. For example, Washington DC has a latitude 38.8951.
StartAccuracy decimal The starting Geolocation Accuracy of the Time-pair. The value is in decimal format and represents the radius of a circle around the longitude and latitude co-ordinates. The location of the clock-in could be anywhere within that circle.
StartTimeEntryType string The starting Time Entry Type of the Time-pair. The value can only be Automatic or Manual. Automatic implies entered by clicking on a button or some other automatic process, whereas Manual means the time-pair was entered by manually editing values.
EndTime datetime the end date of the Time-Pair. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
EndTimeZone string The end Time Zone of the Time-pair. The Time Zone is in IANA format i.e. continent or ocean followed by the name of the largest city within the region e.g. Pacific/Honolulu.
EndLongitude decimal The end Geolocation Longitude of the Time-pair. The value is in decimal degrees format and ranges from -180 to 180. For example, Washington DC has a longitude -77.0364.
EndLatitude decimal The end Geolocation Latitude of the Time-pair. The value is in decimal degrees format and ranges from -90 to 90. For example, Washington DC has a latitude 38.8951.
EndAccuracy decimal The end Geolocation Accuracy of the Time-pair. The value is in decimal format and represents the radius of a circle around the longitude and latitude co-ordinates. The location of the clock-in could be anywhere within that circle.
EndTimeEntryType string The end Time Entry Type of the Time-pair. The value can only be Automatic or Manual. Automatic implies entered by clicking on a button or some other automatic process, whereas Manual means the time-pair was entered by manually editing values.
Duration integer The difference in seconds between the time-pair's StartTime and the EndTime. Will always be a positive non-zero whole number.
PreviousDuration integer The previous difference in seconds between the time-pair's StartTime and the EndTime. Will always be a positive non-zero whole number. Only applies to time-pairs which have been modified.
PreviousStartTime datetime The previous start date of the Time-pair. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
PreviousStartTimeZone string The previous starting Time Zone of the Time-pair. The Time Zone is in IANA format i.e. continent or ocean followed by the name of the largest city within the region e.g. Pacific/Honolulu.
PreviousEndTime datetime The previous end date of the Time-pair. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
PreviousEndTimeZone string The previous end Time Zone of the Time-pair. The Time Zone is in IANA format i.e. continent or ocean followed by the name of the largest city within the region e.g. Pacific/Honolulu.
CurrentApprovalStatus string The current approval status of the Time-pair. Values are AwaitingApproval, Approved, Rejected, or Deleted.
PreviousApprovalStatus string The previous approval status of the Time-pair. Values are null, AwaitingApproval, Approved, Rejected, or Deleted.
WorkingFromHome boolean Will be true if the time-pair represent time spent working at home, or at some other location away from the normal place of work. False otherwise.
PreviousWorkingFromHome boolean Will be true if the time-pair represent time spent working at home, or at some other location away from the normal place of work. False otherwise.
OvertimeReason string When the time-pair is for overtime, then this is the reason e.g. 'Not Provided' Max-length: 40.
OvertimeReasonDetails string Represents additional information for why the overtime was worked, e.g. "Behind schedule". Max-length: 40.
PreviousOvertimeReason string When the time-pair is for overtime, then this is the previous reason e.g. 'Not Provided'. Max-length: 40.
PreviousOvertimeReasonDetails string Represents the previous additional information for why the overtime was worked, e.g. "Behind schedule". Max-length: 40.
TimeOffInLieu boolean Will be true if the time-pair is associated with Time Off In Lieu. False otherwise.
PreviousTimeOffInLieu boolean Will be true if the time-pair is associated with Time Off In Lieu. False otherwise.
TimeType string Time type associated with time-pair. Max-length: 255.
TimeCategory string Standard, Overtime or Special.
PayslipItemCode string Payslip item code associated with time-pair, can be used in payroll to pay employees. Max-length: 255.
RateOfPay decimal Rate of pay's value overriden by manager.
CurrencyIsoCode string Currency which is associated to provided rate of pay. Currency is in ISO format i.e. GBP.
WorkType string Work type field value describes the activity that was undertaken during the work period. Max-length: 255.
ExternalLocation string External location field value describes relevant external location where employees worked during their shift. Max-length: 255.
WorkReference string Field contains relevant work reference for the work they have done during their shift. Max-length: 255.
Customer string Customer field value describes relevant customer or project, which employee was working on. Max-length: 255.

Example of this event

{
  "EventData": {
    "PersonalReferenceNumber": "P100",
    "PersonFirstname": "Mark",
    "PersonLastname": "Hemingway",
    "TimePairType": "Standard",
    "StartTime": "2022-05-25T12:48:00Z",
    "StartTimeZone": "Europe/London",
    "StartLongitude": -1.1423692,
    "StartLatitude": 52.8842841,
    "StartAccuracy": 14.188,
    "StartTimeEntryType": "Automatic",
    "EndTime": null,
    "EndTimeZone": null,
    "EndLongitude": null,
    "EndLatitude": null,
    "EndAccuracy": null,
    "EndTimeEntryType": null,
    "Duration": null,
    "PreviousDuration": null,
    "PreviousStartTime": null,
    "PreviousStartTimeZone": null,
    "PreviousEndTime": null,
    "PreviousEndTimeZone": null,
    "CurrentApprovalStatus": "AwaitingApproval",
    "PreviousApprovalStatus": "",
    "WorkingFromHome": false,
    "PreviousWorkingFromHome": null,
    "OvertimeReason": null,
    "OvertimeReasonDetails": "",
    "PreviousOvertimeReason": null,
    "PreviousOvertimeReasonDetails": null,
    "TimeType": "Normal hours",
    "TimeCategory": "Standard",
    "PayslipItemCode": "PI0021",
    "RateOfPay": 15.21,
    "CurrencyIsoCode": "GBP",
    "WorkType": "Engineering",
    "ExternalLocation": "",
    "WorkReference": "38959p8ncr498bv",
    "Customer": "Project One"
  },
  "EventType": "OpenTimePairCreated",
  "TimeOfCreation": "2022-05-25T12:48:40.0660308Z"
}

ClosedTimePairCreated event

The payload for this event contains the Time-pair details.

A ClosedTimePairCreated event will be raised when:

  • a closed time-pair is manually created

A ClosedTimePairCreated event will always contain both the start time details and the end time details.

Field definitions for this event

Field Name Data Type Additional information
PersonalReferenceNumber string The reference number of the person to whom the time-pair belongs. Max-length: 20
PersonFirstname string The first name of the person to whom the time-pair belongs. Max-length: 80
PersonLastname string The last name of the person to whom the time-pair belongs. Max-length: 80
TimePairType string Standard or Overtime
StartTime datetime The start date of the Time-pair. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
StartTimeZone string The starting Time Zone of the Time-pair. The Time Zone is in IANA format i.e. continent or ocean followed by the name of the largest city within the region e.g. Pacific/Honolulu.
StartLongitude decimal The starting Geolocation Longitude of the Time-pair. The value is in decimal degrees format and ranges from -180 to 180. For example, Washington DC has a longitude -77.0364.
StartLatitude decimal The starting Geolocation Latitude of the Time-pair. The value is in decimal degrees format and ranges from -90 to 90. For example, Washington DC has a latitude 38.8951.
StartAccuracy decimal The starting Geolocation Accuracy of the Time-pair. The value is in decimal format and represents the radius of a circle around the longitude and latitude co-ordinates. The location of the clock-in could be anywhere within that circle.
StartTimeEntryType string The starting Time Entry Type of the Time-pair. The value can only be Automatic or Manual. Automatic implies entered by clicking on a button or some other automatic process, whereas Manual means the time-pair was entered by manually editing values.
EndTime datetime the end date of the Time-Pair. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
EndTimeZone string The end Time Zone of the Time-pair. The Time Zone is in IANA format i.e. continent or ocean followed by the name of the largest city within the region e.g. Pacific/Honolulu.
EndLongitude decimal The end Geolocation Longitude of the Time-pair. The value is in decimal degrees format and ranges from -180 to 180. For example, Washington DC has a longitude -77.0364.
EndLatitude decimal The end Geolocation Latitude of the Time-pair. The value is in decimal degrees format and ranges from -90 to 90. For example, Washington DC has a latitude 38.8951.
EndAccuracy decimal The end Geolocation Accuracy of the Time-pair. The value is in decimal format and represents the radius of a circle around the longitude and latitude co-ordinates. The location of the clock-in could be anywhere within that circle.
EndTimeEntryType string The end Time Entry Type of the Time-pair. The value can only be Automatic or Manual. Automatic implies entered by clicking on a button or some other automatic process, whereas Manual means the time-pair was entered by manually editing values.
Duration integer The difference in seconds between the time-pair's StartTime and the EndTime. Will always be a positive non-zero whole number.
PreviousDuration integer The previous difference in seconds between the time-pair's StartTime and the EndTime. Will always be a positive non-zero whole number. Only applies to time-pairs which have been modified.
PreviousStartTime datetime The previous start date of the Time-pair. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
PreviousStartTimeZone string The previous starting Time Zone of the Time-pair. The Time Zone is in IANA format i.e. continent or ocean followed by the name of the largest city within the region e.g. Pacific/Honolulu.
PreviousEndTime datetime The previous end date of the Time-pair. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
PreviousEndTimeZone string The previous end Time Zone of the Time-pair. The Time Zone is in IANA format i.e. continent or ocean followed by the name of the largest city within the region e.g. Pacific/Honolulu.
CurrentApprovalStatus string The current approval status of the Time-pair. Values are AwaitingApproval, Approved, Rejected, or Deleted.
PreviousApprovalStatus string The previous approval status of the Time-pair. Values are null, AwaitingApproval, Approved, Rejected, or Deleted.
WorkingFromHome boolean Will be true if the time-pair represent time spent working at home, or at some other location away from the normal place of work. False otherwise.
PreviousWorkingFromHome boolean Will be true if the time-pair represent time spent working at home, or at some other location away from the normal place of work. False otherwise.
OvertimeReason string When the time-pair is for overtime, then this is the reason e.g. 'Not Provided' Max-length: 40.
OvertimeReasonDetails string Represents additional information for why the overtime was worked, e.g. "Behind schedule". Max-length: 40.
PreviousOvertimeReason string When the time-pair is for overtime, then this is the previous reason e.g. 'Not Provided'. Max-length: 40.
PreviousOvertimeReasonDetails string Represents the previous additional information for why the overtime was worked, e.g. "Behind schedule". Max-length: 40.
TimeOffInLieu boolean Will be true if the time-pair is associated with Time Off In Lieu. False otherwise.
PreviousTimeOffInLieu boolean Will be true if the time-pair is associated with Time Off In Lieu. False otherwise.
TimeType string Time type associated with time-pair. Max-length: 255.
TimeCategory string Standard, Overtime or Special.
PayslipItemCode string Payslip item code associated with time-pair, can be used in payroll to pay employees. Max-length: 255.
RateOfPay decimal Rate of pay's value overriden by manager.
CurrencyIsoCode string Currency which is associated to provided rate of pay. Currency is in ISO format i.e. GBP.
WorkType string Work type field value describes the activity that was undertaken during the work period. Max-length: 255.
ExternalLocation string External location field value describes relevant external location where employees worked during their shift. Max-length: 255.
WorkReference string Field contains relevant work reference for the work they have done during their shift. Max-length: 255.
Customer string Customer field value describes relevant customer or project, which employee was working on. Max-length: 255.

Example of this event

{
  "EventData": {
    "PersonalReferenceNumber": "P100",
    "PersonFirstname": "Mark",
    "PersonLastname": "Hemingway",
    "TimePairType": "Standard",
    "StartTime": "2022-05-25T12:48:00Z",
    "StartTimeZone": "Europe/London",
    "StartLongitude": -1.1423692,
    "StartLatitude": 52.8842841,
    "StartAccuracy": 14.188,
    "StartTimeEntryType": "Automatic",
    "EndTime": "2022-05-25T13:57:00Z",
    "EndTimeZone": "Europe/London",
    "EndLongitude": -1.1423693,
    "EndLatitude": 52.8842857,,
    "EndAccuracy": 14.301,
    "EndTimeEntryType": "Automatic",
    "Duration": 5632,
    "PreviousDuration": null,
    "PreviousStartTime": null,
    "PreviousStartTimeZone": null,
    "PreviousEndTime": null,
    "PreviousEndTimeZone": null,
    "CurrentApprovalStatus": "AwaitingApproval",
    "PreviousApprovalStatus": "",
    "WorkingFromHome": false,
    "PreviousWorkingFromHome": null,
    "OvertimeReason": null,
    "OvertimeReasonDetails": "",
    "PreviousOvertimeReason": null,
    "PreviousOvertimeReasonDetails": null,
    "TimeType": "Normal hours",
    "TimeCategory": "Standard",
    "PayslipItemCode": "PI0021",
    "RateOfPay": 15.21,
    "CurrencyIsoCode": "GBP",
    "WorkType": "Engineering",
    "ExternalLocation": "",
    "WorkReference": "38959p8ncr498bv",
    "Customer": "Project One"
  },
  "EventType": "ClosedTimePairCreated",
  "TimeOfCreation": "2022-05-25T12:48:40.0660308Z"
}

TimePairApproved event

The payload for this event contains the details of the approved Time-pair.

A TimePairApproved event will be raised when:

  • a closed standard or overtime time-pair is manually approved
  • a closed standard time-pair is auto-approved when the system is configured appropriately

A TimePairApproved event will always contain both the start time details and the end time details, as well as the current & previous approval states.

Field definitions for this event

Field Name Data Type Additional information
PersonalReferenceNumber string The reference number of the person to whom the time-pair belongs. Max-length: 20
PersonFirstname string The first name of the person to whom the time-pair belongs. Max-length: 80
PersonLastname string The last name of the person to whom the time-pair belongs. Max-length: 80
TimePairType string Standard or Overtime
StartTime datetime The start date of the Time-pair. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
StartTimeZone string The starting Time Zone of the Time-pair. The Time Zone is in IANA format i.e. continent or ocean followed by the name of the largest city within the region e.g. Pacific/Honolulu.
StartLongitude decimal The starting Geolocation Longitude of the Time-pair. The value is in decimal degrees format and ranges from -180 to 180. For example, Washington DC has a longitude -77.0364.
StartLatitude decimal The starting Geolocation Latitude of the Time-pair. The value is in decimal degrees format and ranges from -90 to 90. For example, Washington DC has a latitude 38.8951.
StartAccuracy decimal The starting Geolocation Accuracy of the Time-pair. The value is in decimal format and represents the radius of a circle around the longitude and latitude co-ordinates. The location of the clock-in could be anywhere within that circle.
StartTimeEntryType string The starting Time Entry Type of the Time-pair. The value can only be Automatic or Manual. Automatic implies entered by clicking on a button or some other automatic process, whereas Manual means the time-pair was entered by manually editing values.
EndTime datetime the end date of the Time-Pair. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
EndTimeZone string The end Time Zone of the Time-pair. The Time Zone is in IANA format i.e. continent or ocean followed by the name of the largest city within the region e.g. Pacific/Honolulu.
EndLongitude decimal The end Geolocation Longitude of the Time-pair. The value is in decimal degrees format and ranges from -180 to 180. For example, Washington DC has a longitude -77.0364.
EndLatitude decimal The end Geolocation Latitude of the Time-pair. The value is in decimal degrees format and ranges from -90 to 90. For example, Washington DC has a latitude 38.8951.
EndAccuracy decimal The end Geolocation Accuracy of the Time-pair. The value is in decimal format and represents the radius of a circle around the longitude and latitude co-ordinates. The location of the clock-in could be anywhere within that circle.
EndTimeEntryType string The end Time Entry Type of the Time-pair. The value can only be Automatic or Manual. Automatic implies entered by clicking on a button or some other automatic process, whereas Manual means the time-pair was entered by manually editing values.
Duration integer The difference in seconds between the time-pair's StartTime and the EndTime. Will always be a positive non-zero whole number.
PreviousDuration integer The previous difference in seconds between the time-pair's StartTime and the EndTime. Will always be a positive non-zero whole number. Only applies to time-pairs which have been modified.
PreviousStartTime datetime The previous start date of the Time-pair. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
PreviousStartTimeZone string The previous starting Time Zone of the Time-pair. The Time Zone is in IANA format i.e. continent or ocean followed by the name of the largest city within the region e.g. Pacific/Honolulu.
PreviousEndTime datetime The previous end date of the Time-pair. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
PreviousEndTimeZone string The previous end Time Zone of the Time-pair. The Time Zone is in IANA format i.e. continent or ocean followed by the name of the largest city within the region e.g. Pacific/Honolulu.
CurrentApprovalStatus string The current approval status of the Time-pair. Values are AwaitingApproval, Approved, Rejected, or Deleted.
PreviousApprovalStatus string The previous approval status of the Time-pair. Values are null, AwaitingApproval, Approved, Rejected, or Deleted.
WorkingFromHome boolean Will be true if the time-pair represent time spent working at home, or at some other location away from the normal place of work. False otherwise.
PreviousWorkingFromHome boolean Will be true if the time-pair represent time spent working at home, or at some other location away from the normal place of work. False otherwise.
OvertimeReason string When the time-pair is for overtime, then this is the reason e.g. 'Not Provided' Max-length: 40.
OvertimeReasonDetails string Represents additional information for why the overtime was worked, e.g. "Behind schedule". Max-length: 40.
PreviousOvertimeReason string When the time-pair is for overtime, then this is the previous reason e.g. 'Not Provided'. Max-length: 40.
PreviousOvertimeReasonDetails string Represents the previous additional information for why the overtime was worked, e.g. "Behind schedule". Max-length: 40.
TimeOffInLieu boolean Will be true if the time-pair is associated with Time Off In Lieu. False otherwise.
PreviousTimeOffInLieu boolean Will be true if the time-pair is associated with Time Off In Lieu. False otherwise.
TimeType string Time type associated with time-pair. Max-length: 255.
TimeCategory string Standard, Overtime or Special.
PayslipItemCode string Payslip item code associated with time-pair, can be used in payroll to pay employees. Max-length: 255.
RateOfPay decimal Rate of pay's value overriden by manager.
CurrencyIsoCode string Currency which is associated to provided rate of pay. Currency is in ISO format i.e. GBP.
WorkType string Work type field value describes the activity that was undertaken during the work period. Max-length: 255.
ExternalLocation string External location field value describes relevant external location where employees worked during their shift. Max-length: 255.
WorkReference string Field contains relevant work reference for the work they have done during their shift. Max-length: 255.
Customer string Customer field value describes relevant customer or project, which employee was working on. Max-length: 255.

Example of this event

{
  "EventData": {
    "PersonalReferenceNumber": "P100",
    "PersonFirstname": "Mark",
    "PersonLastname": "Hemingway",
    "TimePairType": "Standard",
    "StartTime": "2022-05-25T12:48:00Z",
    "StartTimeZone": "Europe/London",
    "StartLongitude": -1.1423692,
    "StartLatitude": 52.8842841,
    "StartAccuracy": 14.188,
    "StartTimeEntryType": "Automatic",
    "EndTime": "2022-05-25T13:57:00Z",
    "EndTimeZone": "Europe/London",
    "EndLongitude": -1.1423693,
    "EndLatitude": 52.8842857,,
    "EndAccuracy": 14.301,
    "EndTimeEntryType": "Automatic",
    "Duration": 3552,
    "PreviousDuration": null,
    "PreviousStartTime": null,
    "PreviousStartTimeZone": null,
    "PreviousEndTime": null,
    "PreviousEndTimeZone": null,
    "CurrentApprovalStatus": "Approved",
    "PreviousApprovalStatus": "AwaitingApproval",
    "WorkingFromHome": false,
    "PreviousWorkingFromHome": null,
    "OvertimeReason": null,
    "OvertimeReasonDetails": "",
    "PreviousOvertimeReason": null,
    "PreviousOvertimeReasonDetails": null,
    "TimeType": "Normal hours",
    "TimeCategory": "Standard",
    "PayslipItemCode": "PI0021",
    "RateOfPay": 15.21,
    "CurrencyIsoCode": "GBP",
    "WorkType": "Engineering",
    "ExternalLocation": "",
    "WorkReference": "38959p8ncr498bv",
    "Customer": "Project One"
  },
  "EventType": "TimePairApproved",
  "TimeOfCreation": "2022-05-25T12:48:40.0660308Z"
}

TimePairRejected event

The payload for this event contains the details of the rejected Time-pair.

A TimePairApproved event will be raised when:

  • a closed time-pair is manually rejected

A TimePairRejected event will always contain both the start time details and the end time details, as well as the current & previous approval states.

Field definitions for this event

Field Name Data Type Additional information
PersonalReferenceNumber string The reference number of the person to whom the time-pair belongs. Max-length: 20
PersonFirstname string The first name of the person to whom the time-pair belongs. Max-length: 80
PersonLastname string The last name of the person to whom the time-pair belongs. Max-length: 80
TimePairType string Standard or Overtime
StartTime datetime The start date of the Time-pair. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
StartTimeZone string The starting Time Zone of the Time-pair. The Time Zone is in IANA format i.e. continent or ocean followed by the name of the largest city within the region e.g. Pacific/Honolulu.
StartLongitude decimal The starting Geolocation Longitude of the Time-pair. The value is in decimal degrees format and ranges from -180 to 180. For example, Washington DC has a longitude -77.0364.
StartLatitude decimal The starting Geolocation Latitude of the Time-pair. The value is in decimal degrees format and ranges from -90 to 90. For example, Washington DC has a latitude 38.8951.
StartAccuracy decimal The starting Geolocation Accuracy of the Time-pair. The value is in decimal format and represents the radius of a circle around the longitude and latitude co-ordinates. The location of the clock-in could be anywhere within that circle.
StartTimeEntryType string The starting Time Entry Type of the Time-pair. The value can only be Automatic or Manual. Automatic implies entered by clicking on a button or some other automatic process, whereas Manual means the time-pair was entered by manually editing values.
EndTime datetime the end date of the Time-Pair. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
EndTimeZone string The end Time Zone of the Time-pair. The Time Zone is in IANA format i.e. continent or ocean followed by the name of the largest city within the region e.g. Pacific/Honolulu.
EndLongitude decimal The end Geolocation Longitude of the Time-pair. The value is in decimal degrees format and ranges from -180 to 180. For example, Washington DC has a longitude -77.0364.
EndLatitude decimal The end Geolocation Latitude of the Time-pair. The value is in decimal degrees format and ranges from -90 to 90. For example, Washington DC has a latitude 38.8951.
EndAccuracy decimal The end Geolocation Accuracy of the Time-pair. The value is in decimal format and represents the radius of a circle around the longitude and latitude co-ordinates. The location of the clock-in could be anywhere within that circle.
EndTimeEntryType string The end Time Entry Type of the Time-pair. The value can only be Automatic or Manual. Automatic implies entered by clicking on a button or some other automatic process, whereas Manual means the time-pair was entered by manually editing values.
Duration integer The difference in seconds between the time-pair's StartTime and the EndTime. Will always be a positive non-zero whole number.
PreviousDuration integer The previous difference in seconds between the time-pair's StartTime and the EndTime. Will always be a positive non-zero whole number. Only applies to time-pairs which have been modified.
PreviousStartTime datetime The previous start date of the Time-pair. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
PreviousStartTimeZone string The previous starting Time Zone of the Time-pair. The Time Zone is in IANA format i.e. continent or ocean followed by the name of the largest city within the region e.g. Pacific/Honolulu.
PreviousEndTime datetime The previous end date of the Time-pair. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
PreviousEndTimeZone string The previous end Time Zone of the Time-pair. The Time Zone is in IANA format i.e. continent or ocean followed by the name of the largest city within the region e.g. Pacific/Honolulu.
CurrentApprovalStatus string The current approval status of the Time-pair. Values are AwaitingApproval, Approved, Rejected, or Deleted.
PreviousApprovalStatus string The previous approval status of the Time-pair. Values are null, AwaitingApproval, Approved, Rejected, or Deleted.
WorkingFromHome boolean Will be true if the time-pair represent time spent working at home, or at some other location away from the normal place of work. False otherwise.
PreviousWorkingFromHome boolean Will be true if the time-pair represent time spent working at home, or at some other location away from the normal place of work. False otherwise.
OvertimeReason string When the time-pair is for overtime, then this is the reason e.g. 'Not Provided' Max-length: 40.
OvertimeReasonDetails string Represents additional information for why the overtime was worked, e.g. "Behind schedule". Max-length: 40.
PreviousOvertimeReason string When the time-pair is for overtime, then this is the previous reason e.g. 'Not Provided'. Max-length: 40.
PreviousOvertimeReasonDetails string Represents the previous additional information for why the overtime was worked, e.g. "Behind schedule". Max-length: 40.
TimeOffInLieu boolean Will be true if the time-pair is associated with Time Off In Lieu. False otherwise.
PreviousTimeOffInLieu boolean Will be true if the time-pair is associated with Time Off In Lieu. False otherwise.
TimeType string Time type associated with time-pair. Max-length: 255.
TimeCategory string Standard, Overtime or Special.
PayslipItemCode string Payslip item code associated with time-pair, can be used in payroll to pay employees. Max-length: 255.
RateOfPay decimal Rate of pay's value overriden by manager.
CurrencyIsoCode string Currency which is associated to provided rate of pay. Currency is in ISO format i.e. GBP.
WorkType string Work type field value describes the activity that was undertaken during the work period. Max-length: 255.
ExternalLocation string External location field value describes relevant external location where employees worked during their shift. Max-length: 255.
WorkReference string Field contains relevant work reference for the work they have done during their shift. Max-length: 255.
Customer string Customer field value describes relevant customer or project, which employee was working on. Max-length: 255.

Example of this event

{
  "EventData": {
    "PersonalReferenceNumber": "P100",
    "PersonFirstname": "Mark",
    "PersonLastname": "Hemingway",
    "TimePairType": "Standard",
    "StartTime": "2022-05-25T12:48:00Z",
    "StartTimeZone": "Europe/London",
    "StartLongitude": -1.1423692,
    "StartLatitude": 52.8842841,
    "StartAccuracy": 14.188,
    "StartTimeEntryType": "Automatic",
    "EndTime": "2022-05-25T13:57:00Z",
    "EndTimeZone": "Europe/London",
    "EndLongitude": -1.1423693,
    "EndLatitude": 52.8842857,,
    "EndAccuracy": 14.301,
    "EndTimeEntryType": "Automatic",
    "Duration": 1342,
    "PreviousDuration": null,
    "PreviousStartTime": null,
    "PreviousStartTimeZone": null,
    "PreviousEndTime": null,
    "PreviousEndTimeZone": null,
    "CurrentApprovalStatus": "Rejected",
    "PreviousApprovalStatus": "AwaitingApproval",
    "WorkingFromHome": false,
    "PreviousWorkingFromHome": null,
    "OvertimeReason": null,
    "OvertimeReasonDetails": "",
    "PreviousOvertimeReason": null,
    "PreviousOvertimeReasonDetails": null,
    "TimeType": "Normal hours",
    "TimeCategory": "Standard",
    "PayslipItemCode": "PI0021",
    "RateOfPay": 15.21,
    "CurrencyIsoCode": "GBP",
    "WorkType": "Engineering",
    "ExternalLocation": "",
    "WorkReference": "38959p8ncr498bv",
    "Customer": "Project One"
  },
  "EventType": "TimePairRejected",
  "TimeOfCreation": "2022-05-25T12:48:40.0660308Z"
}

TimePairChanged event

The payload for this event contains the details of the changed Time-pair, and details of the previous values.

A TimePairChanged event will be raised when:

  • an open or closed time-pair is manually edited.
  • an open time-pair is clocked-out.

A TimePairChanged event will always contain the start time details, but will only contain the end time details if it is a closed time-pair.

Field definitions for this event

Field Name Data Type Additional information
PersonalReferenceNumber string The reference number of the person to whom the time-pair belongs. Max-length: 20
PersonFirstname string The first name of the person to whom the time-pair belongs. Max-length: 80
PersonLastname string The last name of the person to whom the time-pair belongs. Max-length: 80
TimePairType string Standard or Overtime
StartTime datetime The start date of the Time-pair. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
StartTimeZone string The starting Time Zone of the Time-pair. The Time Zone is in IANA format i.e. continent or ocean followed by the name of the largest city within the region e.g. Pacific/Honolulu.
StartLongitude decimal The starting Geolocation Longitude of the Time-pair. The value is in decimal degrees format and ranges from -180 to 180. For example, Washington DC has a longitude -77.0364.
StartLatitude decimal The starting Geolocation Latitude of the Time-pair. The value is in decimal degrees format and ranges from -90 to 90. For example, Washington DC has a latitude 38.8951.
StartAccuracy decimal The starting Geolocation Accuracy of the Time-pair. The value is in decimal format and represents the radius of a circle around the longitude and latitude co-ordinates. The location of the clock-in could be anywhere within that circle.
StartTimeEntryType string The starting Time Entry Type of the Time-pair. The value can only be Automatic or Manual. Automatic implies entered by clicking on a button or some other automatic process, whereas Manual means the time-pair was entered by manually editing values.
EndTime datetime the end date of the Time-Pair. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
EndTimeZone string The end Time Zone of the Time-pair. The Time Zone is in IANA format i.e. continent or ocean followed by the name of the largest city within the region e.g. Pacific/Honolulu.
EndLongitude decimal The end Geolocation Longitude of the Time-pair. The value is in decimal degrees format and ranges from -180 to 180. For example, Washington DC has a longitude -77.0364.
EndLatitude decimal The end Geolocation Latitude of the Time-pair. The value is in decimal degrees format and ranges from -90 to 90. For example, Washington DC has a latitude 38.8951.
EndAccuracy decimal The end Geolocation Accuracy of the Time-pair. The value is in decimal format and represents the radius of a circle around the longitude and latitude co-ordinates. The location of the clock-in could be anywhere within that circle.
EndTimeEntryType string The end Time Entry Type of the Time-pair. The value can only be Automatic or Manual. Automatic implies entered by clicking on a button or some other automatic process, whereas Manual means the time-pair was entered by manually editing values.
Duration integer The difference in seconds between the time-pair's StartTime and the EndTime. Will always be a positive non-zero whole number.
PreviousDuration integer The previous difference in seconds between the time-pair's StartTime and the EndTime. Will always be a positive non-zero whole number. Only applies to time-pairs which have been modified.
PreviousStartTime datetime The previous start date of the Time-pair. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
PreviousStartTimeZone string The previous starting Time Zone of the Time-pair. The Time Zone is in IANA format i.e. continent or ocean followed by the name of the largest city within the region e.g. Pacific/Honolulu.
PreviousEndTime datetime The previous end date of the Time-pair. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
PreviousEndTimeZone string The previous end Time Zone of the Time-pair. The Time Zone is in IANA format i.e. continent or ocean followed by the name of the largest city within the region e.g. Pacific/Honolulu.
CurrentApprovalStatus string The current approval status of the Time-pair. Values are AwaitingApproval, Approved, Rejected, or Deleted.
PreviousApprovalStatus string The previous approval status of the Time-pair. Values are null, AwaitingApproval, Approved, Rejected, or Deleted.
WorkingFromHome boolean Will be true if the time-pair represent time spent working at home, or at some other location away from the normal place of work. False otherwise.
PreviousWorkingFromHome boolean Will be true if the time-pair represent time spent working at home, or at some other location away from the normal place of work. False otherwise.
OvertimeReason string When the time-pair is for overtime, then this is the reason e.g. 'Not Provided' Max-length: 40.
OvertimeReasonDetails string Represents additional information for why the overtime was worked, e.g. "Behind schedule". Max-length: 40.
PreviousOvertimeReason string When the time-pair is for overtime, then this is the previous reason e.g. 'Not Provided'. Max-length: 40.
PreviousOvertimeReasonDetails string Represents the previous additional information for why the overtime was worked, e.g. "Behind schedule". Max-length: 40.
TimeOffInLieu boolean Will be true if the time-pair is associated with Time Off In Lieu. False otherwise.
PreviousTimeOffInLieu boolean Will be true if the time-pair is associated with Time Off In Lieu. False otherwise.
TimeType string Time type associated with time-pair. Max-length: 255.
TimeCategory string Standard, Overtime or Special.
PayslipItemCode string Payslip item code associated with time-pair, can be used in payroll to pay employees. Max-length: 255.
RateOfPay decimal Rate of pay's value overriden by manager.
CurrencyIsoCode string Currency which is associated to provided rate of pay. Currency is in ISO format i.e. GBP.
WorkType string Work type field value describes the activity that was undertaken during the work period. Max-length: 255.
ExternalLocation string External location field value describes relevant external location where employees worked during their shift. Max-length: 255.
WorkReference string Field contains relevant work reference for the work they have done during their shift. Max-length: 255.
Customer string Customer field value describes relevant customer or project, which employee was working on. Max-length: 255.

Example of this event

{
  "EventData": {
    "PersonalReferenceNumber": "P100",
    "PersonFirstname": "Mark",
    "PersonLastname": "Hemingway",
    "TimePairType": "Standard",
    "StartTime": "2022-05-25T12:41:00Z",
    "StartTimeZone": "Europe/London",
    "StartLongitude": -1.14239,
    "StartLatitude": 52.884293,
    "StartAccuracy": 17.13,
    "StartTimeEntryType": "Automatic",
    "EndTime": "2022-05-25T12:41:00Z",
    "EndTimeZone": "Europe/London",
    "EndLongitude": -1.1423902,
    "EndLatitude": 52.8842929,
    "EndAccuracy": 17.127,
    "EndTimeEntryType": "Automatic",
    "Duration": 0,
    "PreviousDuration": null,
    "PreviousStartTime": "2022-05-25T12:41:00Z",
    "PreviousStartTimeZone": "Europe/London",
    "PreviousEndTime": "",
    "PreviousEndTimeZone": null,
    "CurrentApprovalStatus": "AwaitingApproval",
    "PreviousApprovalStatus": "",
    "WorkingFromHome": false,
    "PreviousWorkingFromHome": false,
    "OvertimeReason": null,
    "OvertimeReasonDetails": "",
    "PreviousOvertimeReason": null,
    "PreviousOvertimeReasonDetails": "",
    "TimeType": "Normal hours",
    "TimeCategory": "Standard",
    "PayslipItemCode": "PI0021",
    "RateOfPay": 15.21,
    "CurrencyIsoCode": "GBP",
    "WorkType": "Engineering",
    "ExternalLocation": "",
    "WorkReference": "38959p8ncr498bv",
    "Customer": "Project One"
  },
  "EventType": "TimePairChanged",
  "TimeOfCreation": "2022-05-25T12:41:46.6038592Z"
}

TimePairDeleted event

The payload for this event contains the details of the deleted Time-pair.

A TimePairDeleted event will be raised when:

  • an open or closed time-pair is manually deleted.

A TimePairDeleted event will always contain the start time details, but will only contain the end time details if it is a closed time-pair.

Field definitions for this event

Field Name Data Type Additional information
PersonalReferenceNumber string The reference number of the person to whom the time-pair belongs. Max-length: 20
PersonFirstname string The first name of the person to whom the time-pair belongs. Max-length: 80
PersonLastname string The last name of the person to whom the time-pair belongs. Max-length: 80
TimePairType string Standard or Overtime
StartTime datetime The start date of the Time-pair. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
StartTimeZone string The starting Time Zone of the Time-pair. The Time Zone is in IANA format i.e. continent or ocean followed by the name of the largest city within the region e.g. Pacific/Honolulu.
StartLongitude decimal The starting Geolocation Longitude of the Time-pair. The value is in decimal degrees format and ranges from -180 to 180. For example, Washington DC has a longitude -77.0364.
StartLatitude decimal The starting Geolocation Latitude of the Time-pair. The value is in decimal degrees format and ranges from -90 to 90. For example, Washington DC has a latitude 38.8951.
StartAccuracy decimal The starting Geolocation Accuracy of the Time-pair. The value is in decimal format and represents the radius of a circle around the longitude and latitude co-ordinates. The location of the clock-in could be anywhere within that circle.
StartTimeEntryType string The starting Time Entry Type of the Time-pair. The value can only be Automatic or Manual. Automatic implies entered by clicking on a button or some other automatic process, whereas Manual means the time-pair was entered by manually editing values.
EndTime datetime the end date of the Time-Pair. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
EndTimeZone string The end Time Zone of the Time-pair. The Time Zone is in IANA format i.e. continent or ocean followed by the name of the largest city within the region e.g. Pacific/Honolulu.
EndLongitude decimal The end Geolocation Longitude of the Time-pair. The value is in decimal degrees format and ranges from -180 to 180. For example, Washington DC has a longitude -77.0364.
EndLatitude decimal The end Geolocation Latitude of the Time-pair. The value is in decimal degrees format and ranges from -90 to 90. For example, Washington DC has a latitude 38.8951.
EndAccuracy decimal The end Geolocation Accuracy of the Time-pair. The value is in decimal format and represents the radius of a circle around the longitude and latitude co-ordinates. The location of the clock-in could be anywhere within that circle.
EndTimeEntryType string The end Time Entry Type of the Time-pair. The value can only be Automatic or Manual. Automatic implies entered by clicking on a button or some other automatic process, whereas Manual means the time-pair was entered by manually editing values.
Duration integer The difference in seconds between the time-pair's StartTime and the EndTime. Will always be a positive non-zero whole number.
PreviousDuration integer The previous difference in seconds between the time-pair's StartTime and the EndTime. Will always be a positive non-zero whole number. Only applies to time-pairs which have been modified.
PreviousStartTime datetime The previous start date of the Time-pair. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
PreviousStartTimeZone string The previous starting Time Zone of the Time-pair. The Time Zone is in IANA format i.e. continent or ocean followed by the name of the largest city within the region e.g. Pacific/Honolulu.
PreviousEndTime datetime The previous end date of the Time-pair. The dateTime is in ISO format and should be in coordinated universal time (UTC) (e.g. 2019-05-02T15:17:00Z)
PreviousEndTimeZone string The previous end Time Zone of the Time-pair. The Time Zone is in IANA format i.e. continent or ocean followed by the name of the largest city within the region e.g. Pacific/Honolulu.
CurrentApprovalStatus string The current approval status of the Time-pair. Values are AwaitingApproval, Approved, Rejected, or Deleted.
PreviousApprovalStatus string The previous approval status of the Time-pair. Values are null, AwaitingApproval, Approved, Rejected, or Deleted.
WorkingFromHome boolean Will be true if the time-pair represent time spent working at home, or at some other location away from the normal place of work. False otherwise.
PreviousWorkingFromHome boolean Will be true if the time-pair represent time spent working at home, or at some other location away from the normal place of work. False otherwise.
OvertimeReason string When the time-pair is for overtime, then this is the reason e.g. 'Not Provided' Max-length: 40.
OvertimeReasonDetails string Represents additional information for why the overtime was worked, e.g. "Behind schedule". Max-length: 40.
PreviousOvertimeReason string When the time-pair is for overtime, then this is the previous reason e.g. 'Not Provided'. Max-length: 40.
PreviousOvertimeReasonDetails string Represents the previous additional information for why the overtime was worked, e.g. "Behind schedule". Max-length: 40.
TimeOffInLieu boolean Will be true if the time-pair is associated with Time Off In Lieu. False otherwise.
PreviousTimeOffInLieu boolean Will be true if the time-pair is associated with Time Off In Lieu. False otherwise.
TimeType string Time type associated with time-pair. Max-length: 255.
TimeCategory string Standard, Overtime or Special.
PayslipItemCode string Payslip item code associated with time-pair, can be used in payroll to pay employees. Max-length: 255.
RateOfPay decimal Rate of pay's value overriden by manager.
CurrencyIsoCode string Currency which is associated to provided rate of pay. Currency is in ISO format i.e. GBP.
WorkType string Work type field value describes the activity that was undertaken during the work period. Max-length: 255.
ExternalLocation string External location field value describes relevant external location where employees worked during their shift. Max-length: 255.
WorkReference string Field contains relevant work reference for the work they have done during their shift. Max-length: 255.
Customer string Customer field value describes relevant customer or project, which employee was working on. Max-length: 255.

Example of this event

{
  "EventData": {
    "PersonalReferenceNumber": "P100",
    "PersonFirstname": "Mark",
    "PersonLastname": "Hemingway",
    "TimePairType": "Standard",
    "StartTime": "2022-05-25T12:48:00Z",
    "StartTimeZone": "Europe/London",
    "StartLongitude": -1.1423692,
    "StartLatitude": 52.8842841,
    "StartAccuracy": 14.188,
    "StartTimeEntryType": "Automatic",
    "EndTime": null,
    "EndTimeZone": null,
    "EndLongitude": null,
    "EndLatitude": null,
    "EndAccuracy": null,
    "EndTimeEntryType": null,
    "Duration": null,
    "PreviousDuration": null,
    "PreviousStartTime": null,
    "PreviousStartTimeZone": null,
    "PreviousEndTime": null,
    "PreviousEndTimeZone": null,
    "CurrentApprovalStatus": "Deleted",
    "PreviousApprovalStatus": "AwaitingApproval",
    "WorkingFromHome": false,
    "PreviousWorkingFromHome": null,
    "OvertimeReason": null,
    "OvertimeReasonDetails": "",
    "PreviousOvertimeReason": null,
    "PreviousOvertimeReasonDetails": null,
    "TimeType": "Normal hours",
    "TimeCategory": "Standard",
    "PayslipItemCode": "PI0021",
    "RateOfPay": 15.21,
    "CurrencyIsoCode": "GBP",
    "WorkType": "Engineering",
    "ExternalLocation": "",
    "WorkReference": "38959p8ncr498bv",
    "Customer": "Project One"
  },
  "EventType": "TimePairDeleted",
  "TimeOfCreation": "2022-05-25T12:48:40.0660308Z"
}