Integrations - External Payroll - Pulling Event Changes

Pulling event data changes

Once the integration goes live, we are into BAU (Business as usual) phase where only changes from People First will update the payroll application.

If webhooks are being used then the webhook will receive the People First events and push the contents to some other data store

Making calls to People First event stream APIs

The People First event stream API is:

GET PFBASEURI/api/v1/rtpi/eventstream?eventTypes=xxx&timeOfCreationFrom=YYYY-MM-DDTHH:MI:SSZ&timeOfCreationTo=YYYY-MM-DDTHH:MI:SSZ&page[Limit]=mmm&page[Offset]=nnn

Let’s go through the query parameters on this uri (the query parameters are the part of the uri after the first ?). The different parts of the query string are separated by &

All of these query parameters are mandatory.

eventTypes=xxx means get events with type xxx only

These 2 parameters restrict the events to those created between certain datetimes – the external application will need to know when the interface was last run and only get events after then and before the current time.

timeOfCreationFrom=YYYY-MM-DDTHH:MI:SSZ

timeOfCreationTo=YYYY-MM-DDTHH:MI:SSZ

This parameter is about managing the result set being returned

page[Limit]=mmm&page[Offset]=nnn

mmm is the maximum number of results the API call will return, and nnn is the number of records to skip because we have already retrieved those records. Recommended values are 100 for mmm and 0 for nnn initially. Subsequent calls, if there are more records, will increase nnn by the mmm value so as to not process the same records more than once – this will be explained in more detail below in the example.

List of Event Types

The People First event stream returns a list of event types which can be put into groups because of the structure of the data they return. An interface should process these events by the groups and make separate event stream API calls for each group. The list of event types and groups relevant to an external payroll are:

Event Type Group	Event Types
Person	PersonCreated, PersonNameChanged
PersonAddress	PersonAddressCreated, PersonAddressChanged
PersonContact	PersonContactDetailCreated, PersonContactDetailChanged
SocialSecurityNumber	SocialSecurityNumberChanged
EmploymentPeriod	EmploymentPeriodCreated, EmploymentPeriodEnded, EmploymentPeriodReinstated
EmploymentPeriodStartDate	EmploymentPeriodStartDateChanged
ReckonableService	ReckonableServiceDateCreated, ReckonableServiceDateChanged, ReckonableServiceDateDeleted
SensitiveInformation	SensitiveInformationChanged
Occupancy	OccupancyCreated, OccupancyEnded, OccupancyReinstated, OccupancyDeleted
OccupancyStartDate	OccupancyStartDateChanged
OccupancyHoursAndBasis	OccupancyHoursAndBasisCreated, OccupancyHoursAndBasisChanged
OccupancySalary	OccupancySalaryTimelineCreated, OccupancySalaryTimelineChanged
OccupancyWorkingPattern	WorkingPatternCreated, WorkingPatternChanged
BankAccount	BankAccountCreated, BankAccountChanged, BankAccountDeleted
CustomCards	CustomCardDataCreated, CustomCardDataChanged, CustomCardDataDeleted

There are other event types for Absence & Time & Attendance which will be included at a later stage.

Event Stream API Example (No Paging)

The following API call will return the Person group events within a timeframe, and we have used the default paging parameters to limit results to 100.

GET PFBASEURI/api/v1/rtpi/eventstream?eventTypes=PersonCreated&eventTypes=PersonNameChanged&timeOfCreationFrom=2024-03-22T15:17:00Z&timeOfCreationTo=2024-04-22T08:44:00Z&page[Limit]=100&page[Offset]=0

The response is:

{
    "meta": {
        "links": {
            "self": {
                "href": "/rtpi/eventstream?eventTypes=PersonCreated&eventTypes=PersonNameChanged&timeOfCreationFrom=2024-03-22T15:17:00Z&timeOfCreationTo=2024-04-22T08:44:00Z&page[Limit]=100&page[Offset]=0"
            },
            "first": {
                "href": "/rtpi/eventStream?page%5BLimit%5D=100&page%5BOffset%5D=0&timeOfCreationFrom=2024-03-22T15%3A17%3A00Z&timeOfCreationTo=2024-04-22T08%3A44%3A00Z"
            },
            "last": {
                "href": "/rtpi/eventStream?page%5BLimit%5D=100&page%5BOffset%5D=0&timeOfCreationFrom=2024-03-22T15%3A17%3A00Z&timeOfCreationTo=2024-04-22T08%3A44%3A00Z"
            }
        },
        "eventStream.results": {
            "items": 11,
            "total": 11
        }
    },
    "data": {
        "eventStream": [
            {
                "_links": {},
                "eventType": "PersonCreated",
                "timeOfReceipt": "2024-04-18T13:00:59.9118186Z",
                "timeOfCreation": "2024-04-18T13:00:58.7318535Z",
                "eventData": {
                    "personId": "64d85598-ae4c-4bf4-9a35-b15600d67fd0",
                    "personalReference": "V71001",
                    "firstName": "Kenny",
                    "lastName": "McCall",
                    "otherNames": "John William",
                    "knownAs": "Kenny",
                    "previousLastName": "",
                    "titleCode": "TITLE0001"
                }
            },

9 results removed to save space!

     {
                "_links": {},
                "eventType": "PersonCreated",
                "timeOfReceipt": "2024-04-02T18:28:51.670397Z",
                "timeOfCreation": "2024-04-02T18:28:50.7127437Z",
                "eventData": {
                    "personId": "ed8ee996-2d53-4925-bcab-b14601308cdc",
                    "personalReference": "J50001",
                    "firstName": "Olivia",
                    "lastName": "Jereme",
                    "otherNames": "Jane",
                    "knownAs": "Olivia",
                    "previousLastName": "",
                    "titleCode": "TITLE0001"
                }
            }
        ]
    }
}

Notice the following:

The items are returned in reverse created datetime order
The eventStream.results has items and total of 11 which as they are same value, there are no more results to return for this event type group.

Event Stream API Example (Paging)

The following API call will return the EmploymentPeriod group events within a timeframe, and we have used the default paging parameters to limit results to 100.

GET PFBASEURI/api/v1/rtpi/eventstream?eventTypes=EmploymentPeriodCreated&eventTypes=EmploymentPeriodEnded&eventTypes=EmploymentPeriodReinstated&timeOfCreationFrom=2023-03-22T15:17:00Z&timeOfCreationTo=2024-04-22T08:44:00Z&page[Limit]=100&page[Offset]=0

The response is:

{
    "meta": {
        "links": {
            "self": {
                "href": "/rtpi/eventstream?eventTypes=EmploymentPeriodCreated&eventTypes=EmploymentPeriodEnded&eventTypes=EmploymentPeriodReinstated&timeOfCreationFrom=2023-03-22T15:17:00Z&timeOfCreationTo=2024-04-22T08:44:00Z&page[Limit]=100&page[Offset]=0"
            },
            "first": {
                "href": "/rtpi/eventStream?page%5BLimit%5D=100&page%5BOffset%5D=0&timeOfCreationFrom=2023-03-22T15%3A17%3A00Z&timeOfCreationTo=2024-04-22T08%3A44%3A00Z"
            },
            "last": {
                "href": "/rtpi/eventStream?page%5BLimit%5D=100&page%5BOffset%5D=500&timeOfCreationFrom=2023-03-22T15%3A17%3A00Z&timeOfCreationTo=2024-04-22T08%3A44%3A00Z"
            },
            "next": {
                "href": "/rtpi/eventStream?page%5BLimit%5D=100&page%5BOffset%5D=100&timeOfCreationFrom=2023-03-22T15%3A17%3A00Z&timeOfCreationTo=2024-04-22T08%3A44%3A00Z"
            }
        },
        "eventStream.results": {
            "items": 100,
            "total": 546
        }
    },
    "data": {
        "eventStream": [
            {
                "_links": {},
                "eventType": "EmploymentPeriodCreated",
                "timeOfReceipt": "2024-04-18T13:00:59.7711933Z",
                "timeOfCreation": "2024-04-18T13:00:58.3412218Z",
                "eventData": {
                    "personId": "64d85598-ae4c-4bf4-9a35-b15600d67fd0",
                    "personalReference": "V71001",
                    "startDate": "2024-04-18"
                }
            },

98 records removed

            {
                "_links": {},
                "eventType": "EmploymentPeriodCreated",
                "timeOfReceipt": "2023-06-30T15:54:22.2937798Z",
                "timeOfCreation": "2023-06-30T15:53:42.3793183Z",
                "eventData": {
                    "personId": "5868c457-76cb-4fed-8f1b-b0310105f176",
                    "personalReference": "K00430",
                    "startDate": "2023-07-27"
                }
            }
        ]
    }
}

Notice from the response:

eventStream.results shows items 100 and total 546 which means only the first 100 have been returned.

In the response meta links there is a next link – this means that there are more records and we should keep making more requests until no data or no next link is returned to get the rest of the data.

The next link contains the next offset value for the paging

The next step is to get the next 100 records which would be using API call:

GET PFBASEURI/api/v1/rtpi/eventstream?eventTypes=EmploymentPeriodCreated&eventTypes=EmploymentPeriodEnded&eventTypes=EmploymentPeriodReinstated&timeOfCreationFrom=2023-03-22T15:17:00Z&timeOfCreationTo=2024-04-22T08:44:00Z&page[Limit]=100&page[Offset]=100

And so on until all the records are retrieved.

Integrations - External payroll

Pulling event data changes

Making calls to People First event stream APIs

List of Event Types

Event Stream API Example (No Paging)

Event Stream API Example (Paging)

Looking for something specific?