Operation Definitions

The following topics define the endpoints and data models for the Staff API operations.

Endpoints

POST /External/General/Employee

Summary

This endpoint is used to create a single employee along with all related information, except employee jobs, in one request.

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The token created previously. For information on tokens, see Authentication.
header	`X-COMPANY-ID`	string	Yes	The unique identifier (UID) for the company provided by Genius
body	`body`	PostExternalGeneralEmployeeRequestBody	Yes	The request information

Sample Request Body

curl --location --request POST 'https://qa-backoffice-api.xenial.com
/External/General/Employee' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InhwcnQifQ...' \
--header 'X-Company-Id: 63da4601b5c13514ecaeac0a' \
--data-raw '{
    "Firstname": "Jack",
    "Lastname": "Doe",
    "Name": "Jack Doe",
    "Username": null,
    "EmployeeCorporateCode": "8796276",
    "ExternalEmployeeId": "80",
    "PrimarySiteId": "63da4653b5c13514ecaeac0f",
    "Source": "TestSource",
    "EmployeePhones": [
        {
            "PhoneNumber": "+2-312-312-3123",
            "PhoneTypeCode": "HOME"
        }
    ],
    "EmployeeAddresses": [
        {
            "AddressTypeCode": "HOME",
            "Address1": "Address 1",
            "City": "Pittsburgh",
            "StateCode": "PA",
            "PostalCode": "15106",
            "CountryCode": "US"
        }
    ],
    "EmployeeContacts": [
        {
            "Firstname": "Jenny",
            "Lastname": "Doe",
            "CountryCode": "US",
            "Phone1": "+0-232-123-1231"
        }
    ],
    "EmployeeEmails": [
        {
            "Email": "836@com.com",
            "EmailTypeCode": "PRSNL"
        },
        {
            "Email": "837@com.com",
            "EmailTypeCode": "WORK"
        }
    ],
    "EmployeeSiteStatuses": [
        {
            "EffectiveDate": "2025-07-01",
            "StatusCode": "ACTV",
            "SiteIds": [
                "63df82df32753797d3cfa2e1",
                "63df82df32753797d3cfa2e2",
                "63da4653b5c13514ecaeac0f"
            ]
        }
    ],
    "PosCredentials": [
        {
            "EmployeePosCode": "12",
            "Password": "12",
            "RoleId": "63da469cb5c13514ecaeac10"
        }
    ]
}'

Responses

Code	Description	Schema
200	Message: Success `Errors` - This array contains a list of errors encountered while processing the employee’s child entities. These errors did not block the creation of the employee but prevented the creation of the invalid records. `ProcessedData` - This object contains all employee data that was created successfully in the database based on the details provided in the request.	PostExternalGeneralEmployeeResponseBody
400	Appears when one or several parameters from headers / body failed in validation. Message: Bad Request
401	Appears when the token is absent or incorrect, or data in token is different than the one received in headers. Message: Unauthorized
403	Appears when the provided token does not have the required permissions to perform this action within this company. Message: Forbidden
500	Appears when an error was received during processing. Message: Internal Server Error

POST /External/General/Employee/[ID]/Jobs

Summary

This endpoint allows the creation of one or multiple employee job records for a single employee, identified by the unique identifier (UID) provided in the URL.

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The token created previously. For information on tokens, see Authentication.
header	`X-COMPANY-ID`	string	Yes	The UID for the company provided by Genius
path	`[ID]`	string	Yes	The 24 character hexadecimal UID of the target employee
body	`body`	PostExternalGeneralEmployeeIDJobsRequestBody	Yes	The request information

Sample Request Body

curl --location --request POST 'https://qa-backoffice-api.xenial.com
/External/General/Employee/62fa6c4e66507a2370954f50/Jobs' \
--header 'Authorization: Bearer 
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InhwcnQifQ...' \
--header 'X-Company-Id: 63da4601b5c13514ecaeac0a' \
--header 'Content-Type: application/json' \
--data '[
    {
        "JobCodeId": "58e63c06fbf17de5ced22064",
        "IsPrimaryJob": true,
        "CompensationTypeCode": "HOUR",  
        "SiteIds": ["63da4653b5c13514ecaeac0f","65fae456a881c84356c79d0a",
"64c228f421a5403fe5773bbf","67eb8df9f6ebe838aec61fd6"],
        "EmployeeJobPays": [
            {
                "EffectiveDate": "2025-01-01",
                "Rate": 15.56
            },
            {
                "EffectiveDate": "2024-01-01",
                "Rate": 14
            }
        ]
    },
    {
        "ExternalJobCodeId": "9087",
        "IsPrimaryJob": false,
        "CompensationTypeCode": "SLRY",  
        "SiteIds": ["63da4653b5c13514ecaeac0f",
"65fae456a881c84356c79d0a"],
        "EmployeeJobPays": [
            {
                "EffectiveDate": "2023-01-01",
                "Rate": 20000
            },
            {
                "EffectiveDate": "2026-01-01",
                "Rate": 20000
            }
        ]
    }
]'

Responses

Code	Description	Schema
200	Message: Success `Errors` - This array contains a list of errors encountered while processing the jobs or their child entities. `ProcessedData` - This array contains all employee jobs that was created successfully in the database based on the details provided in the request.	PostExternalGeneralEmployeeIDJobsResponseBody
400	Appears when one or several parameters from headers / body failed in validation. Message: Bad Request
401	Appears when the token is absent or incorrect, or data in token is different than the one received in headers. Message: Unauthorized
403	Appears when the provided token does not have the required permissions to perform this action within this company. Message: Forbidden
404	Appears when no employees records were found within the received company and with the received UID. Message: Not Found
410	Appears when an employee record with the received UID is no longer active/deleted. Message: Gone
500	Appears when an error was received during processing. Message: Internal Server Error

POST /External/General/Shift

Summary

Provides the ability to create one new shift at a time for non-deleted company, site, employee, and employee job.

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The token created previously. For information on tokens, see Authentication.
header	`X-COMPANY-ID`	string	Yes	The unique identifier (UID) for the company provided by Genius. Note This operation can only do one company at a time, cannot be null or empty, and the `company_id` in the token should match the value received in this header.
header	`X-SITE-IDs`	string	Yes	The unique site identifier for the employee's primary work location Note This operation can only do one site at a time and cannot be null or empty.
body	`body`	PostExternalGeneralShiftRequestBody	Yes	The request object with the shift information

Sample Request Body

curl --location --request POST 
'https://qa-backoffice-api.xenial.com/External/General/Shift' \
--header 'Content-Type: application/json' \
--header 'X-Company-Id: 63da4601b5c13514ecaeac0a' \
--header 'X-Site-Ids: 620c011778da1c0008db8bac' \
--header 'Authorization: Bearer 
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InhwcnQifQ...' \
--data-raw '{
    "EmployeeId": "62dc040174630b7536f71a96",
    "ExternalJobCodeId": "75",
    "StartDateTime": "2023-08-07T18:56:49Z",
    "EndDateTime": null,
    "Source": "TestSource",
    "ActualUpdateDate": "2023-08-08T07:16:57.000Z",
    "Breaks": [
        {
            "BreakStartDateTime": "2023-08-07T22:39:26Z",
            "BreakEndDateTime": "2023-08-08T00:16:38Z",
            "BreakTypeCode": "MEAL",
            "IsPaidBreak": true
        },
        {
            "BreakStartDateTime": "2023-08-08T02:30:00Z",
            "BreakEndDateTime": "2023-08-08T02:35:00Z",
            "BreakTypeCode": "REST",
            "IsPaidBreak": false
        }
    ],
    "Tips": [
        {
            "TenderCategoryCode": "DTIP",
            "TenderTypeCode": "CREDIT",
            "TenderCurrencyCode": "USD",
            "Amount": 9.00
        },
        {
            "TenderCategoryCode": "DTIP",
            "TenderTypeCode": "CUSTOM",
            "TenderCurrencyCode": "USD",
            "Amount": 0.70
        },
        {
            "TenderCategoryCode": "DTIP",
            "TenderTypeCode": "DEBIT",
            "TenderCurrencyCode": "USD",
            "Amount": 7.75
        }
    ],
    "Sales": [
        {
            "TenderTypeCode": "CASH",
            "TenderCurrencyCode": "USD",
            "Amount": 224.63
        }
    ]
}'

Responses

Code	Description	Schema
200	Message: Success. `Errors` - This array contains a list of errors encountered while processing the shift’s child entities. These errors did not block the creation of the shift but prevent the creation of the invalid records. `ProcessedData` - This array of objects contains all shift data that was created successfully in the database based on the details provided in the request.	PostExternalGeneralShiftResponseBody
400	Appears when: One or several parameters from a request failed in validation. An overlap with already existing shift is received. For closed and open shifts, it is not allowed to have several non-deleted shifts for the same employee and period of time. Also for a response body with the message “Processed shift overlapped with existing for this employee. Processed shift: StartDateTime={0}, EndDateTime={1}. Existing shift: StartDateTime={2} EndDateTime={3}“, where: {0} = value received in the request {1} = value received in the request or 'Still Clocked-In' if null was received in the request {2} = value of the existing shift {3} = value of the existing shift or 'Still Clocked-In' if the existing shift is open Related internal requests to other components fail. Message: Bad Request
401	The token is absent or incorrect. Message: Unauthorized
403	Appears when the received token has not enough permissions to perform this action or the data in the token and headers does not match. Message: Forbidden
500	An error was received during the processing. Message: Internal Server Error

POST /v2/schedules

Summary

Provides an ability to create only one active schedule and its child shifts at a time.

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The token created previously. For information on tokens, see Authentication.
header	`X-COMPANY-ID`	string	Yes	The unique identifier (UID) for the company provided by Genius. Note This operation can only do one company at a time, cannot be null or empty, and the `company_id` in the token should match the value received in this header.
header	`X-SITE-IDs`	string	Yes	The UID for the site provided by us Note This operation can only do one site at a time and cannot be null or empty. The received site ID should be non-deleted and belong to the company received in the `X-COMPANY-ID` header.
body	`body`	PostSchedulesRequestBody	Yes	The request object with the schedule information

Sample Request Body

curl --location --request POST 'https://qa-schedule.xenial.com/v2/schedules' \
--header 'x-company-id: 5ee35ad4653fed0009c8ff56' \
--header 'x-site-ids: 5ee35af39c0d910009207773' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [token]' \
--data-raw '{
    "StartDate": "2023-11-24T00:00:00.000Z",
    "EndDate": "2023-11-27T00:00:00.000Z",
    "Timezone": "US/Eastern",
    "Source": "New Schedule Test",
    "Shifts": [
        {
            "BusinessDate": "2023-11-24T",
            "StartTime": "2023-11-24T13:30:00.000Z",
            "EndTime": "2023-11-24T23:15:00.000Z",
            "EmployeeCorporateCode": "134489",
            "JobCodeId": "58e63c06fbf17de5ced22014"
        },
        {
            "BusinessDate": "2023-11-26",
            "StartTime": "2023-11-26T13:00:00.000Z",
            "EndTime": "2023-11-26T23:00:00.000Z",
            "EmployeeId": "607eab3dbffe7e00011adfd1",
            "ExternalJobCodeId": "80892",
            "ExternalShiftId": "920u93"
        }
    ]
}'

Responses

Code	Description	Schema
200	Successfully created schedule with its child shifts.	PostSchedulesResponseBody
400	One or several parameters from a request failed in validation. Message: Bad Request
401	The token is absent or incorrect. Message: Unauthorized
403	The provided token does not have the required permissions to perform this action within this company. Message: Forbidden
500	An error was received during the processing. Message: Internal Server Error

PATCH /External/General/Employee/[ID]

Summary

This endpoint provides an ability to update only selected fields of the specific employee, whose unique identifier (UID) is provided in the URL, as well as updates to the child entities, with the ability to create new records.

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The token created previously. For information on tokens, see Authentication.
header	`X-COMPANY-ID`	string	Yes	The UID for the company provided by Genius
path	`[ID]`	string	Yes	The 24 character hexadecimal UID of the target employee. The ID should belong to the existing, non-deleted employee that belongs to the company provided in the `X-COMPANY-ID` header.
body	`body`	PatchExternalGeneralEmployeeIDRequestBody	Yes	The request information

Sample Request Body

curl --location --request PATCH 'https://qa-backoffice-api.xenial.com
/External/General/Employee/6835ee484168f481249e8766' \
--header 'Authorization: Bearer 
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InhwcnQifQ...' \
--header 'Content-Type: application/json' \
--header 'x-company-id: 63da4601b5c13514ecaeac0a' \
--data-raw '{
    "Lastname": "Doe Jr.",
    "ExternalEmployeeId": "809",
    "EmployeeEmails": [
        {
            "Email": "837@email.com",
            "EmailTypeCode": "PRSNL"
        }
    ],
    "EmployeeSiteStatuses": [
        {
            "EffectiveDate": "2025-08-01",
            "StatusCode": "TERM",
            "SiteIds": [
                "63df82df32753797d3cfa2e1",
                "63df82df32753797d3cfa2e2",
                "63da4653b5c13514ecaeac0f"
            ]
        }
    ],
    "PosCredentials": [
        {
            "Password": "14"
        }
    ]
}'

Code	Description	Schema
200	Message: Success `Errors` - This array contains a list of errors encountered while processing the employee’s child entities. These errors did not block the creation of the employee but prevented the creation of the invalid records. `ProcessedData` - This object contains all employee data that was created successfully in the database based on the details provided in the request.	PostExternalGeneralEmployeeResponseBody The PATCH response has the same structure as the POST /External/General/Employee response.
400	Appears when one or several parameters from headers / body failed in validation. Message: Bad Request
401	Appears when the token is absent or incorrect, or data in token is different than the one received in headers. Message: Unauthorized
403	Appears when the provided token does not have the required permissions to perform this action within this company. Message: Forbidden
404	Appears when no employees records were found within the received company and with the received UID. Message: Not Found
410	Appears when an employee record with the received UID is no longer active/deleted. Message: Gone
500	Appears when an error was received during processing. Message: Internal Server Error

PATCH /External/General/Employee/[ID]/Job/[ID]

Summary

This endpoint provides an ability to deactivate any existing, non-deleted job, as well as update its rates. If any other job fields should be updated because they were previously provided with incorrect values, such jobs should be deleted through the DELETE /External/General/Employee/[ID]/Job/[ID] endpoint and recreated.

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The token created previously. For information on tokens, see Authentication.
header	`X-COMPANY-ID`	string	Yes	The unique identifier (UID) for the company provided by Genius
path	`[ID]`	string	Yes	The 24 character hexadecimal UID of the target non-deleted employee whose job should be updated
path	`[Job/ID]`	string	Yes	The 24 character hexadecimal UID of the target non-deleted job that should be updated
body	`body`	PatchExternalGeneralEmployeeIDJobIDRequestBody	Yes	The request information

Sample Request Body

curl --location --request PATCH 'https://qa-backoffice-api.xenial.com
/External/General/Employee/Job/63da4ba2614bb6862d37a761' \
--header 'Authorization: Bearer 
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InhwcnQifQ...' \
--header 'Content-Type: application/json' \
--header 'x-company-id: 63da4601b5c13514ecaeac0a' \
--data '{
    "Deactivated": true,
    "DeactivationDate": "2025-05-01",
    "EmployeeJobPays": [
        {
            "EffectiveDate": "2025-02-01",
            "Rate": 12.75
        },
        {
            "EffectiveDate": "2024-01-01",
            "Rate": 15
        }
    ]
}'

Responses

Code	Description	Schema
200	Message: Success	PostExternalGeneralEmployeeIDJobsResponseBody The PATCH response has the same structure as the POST /External/General/Employee/[ID]/Jobs response.
400	Appears when one or several parameters from headers / body failed in validation. Message: Bad Request
401	Appears when the token is absent or incorrect, or data in token is different than the one received in headers. Message: Unauthorized
403	Appears when the provided token does not have the required permissions to perform this action within this company. Message: Forbidden
404	Appears when no employees records were found within the received company and with the received UID. Message: Not Found
410	Appears when an employee record with the received UID is no longer active/deleted. Message: Gone
500	Appears when an error was received during processing. Message: Internal Server Error

PUT /External/General/Shift/[ID]

Summary

Provides the ability to update one new shift at a time for non-deleted company, site, employee, and employee job.

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The token created previously. For information on tokens, see Authentication.
header	`X-COMPANY-ID`	string	Yes	The unique identifier (UID) for the company provided by us Note This operation can only do one company at a time, cannot be null or empty, and the `company_id` in the token should match the value received in this header.
path	`ID`	string	Yes	The [ID] in the URL should contain a 24 character hexadecimal UID in our system of the shift that should be updated with new data.
body	`body`	PutExternalGeneralShiftRequestBody	Yes	The request object with the shift information

Sample Request Body

curl --location --request PUT 
'https://qa-backoffice-api.xenial.com/External/Generat/Shift/
5e46af81636dc9000ab1afc9' \
--header 'Content-Type: application/json' \
--header 'X-Company-Id: 63da4601b5c13514ecaeac0a' \
--header 'X-Site-Ids: 620c011778da1c0008db8bac' \
--header 'Authorization: Bearer 
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InhwcnQifQ....' \
--data-raw '{
    "StartDateTime": "2023-08-07T18:56:49Z",
    "EndDateTime": null,
    "Source": "TestSource",
    "ActualUpdateDate": "2023-08-08T07:16:57.000Z",
    "Breaks": [
        {
            "BreakStartDateTime": "2023-08-07T22:39:26Z",
            "BreakEndDateTime": "2023-08-08T00:16:38Z",
            "BreakTypeCode": "MEAL",
            "IsPaidBreak": true
        },
        {
            "BreakStartDateTime": "2023-08-08T02:30:00Z",
            "BreakEndDateTime": "2023-08-08T02:35:00Z",
            "BreakTypeCode": "REST",
            "IsPaidBreak": false
        }
    ],
    "Tips": [
        {
            "TenderCategoryCode": "DTIP",
            "TenderTypeCode": "CREDIT",
            "TenderCurrencyCode": "USD",
            "Amount": 9.00
        },
        {
            "TenderCategoryCode": "DTIP",
            "TenderTypeCode": "CUSTOM",
            "TenderCurrencyCode": "USD",
            "Amount": 0.70
        },
        {
            "TenderCategoryCode": "DTIP",
            "TenderTypeCode": "DEBIT",
            "TenderCurrencyCode": "USD",
            "Amount": 7.75
        }
    ],
    "Sales": [
        {
            "TenderTypeCode": "CASH",
            "TenderCurrencyCode": "USD",
            "Amount": 224.63
        }
    ]
}'

Responses

Code	Description	Schema
200	Message: Success. `Errors` - This array contains a list of errors encountered while processing the shift’s child entities. These errors did not block the creation of the shift but prevent the creation of the invalid records. `ProcessedData` - This array of objects contains all shift data that was created successfully in the database based on the details provided in the request.	PutExternalGeneralShiftResponseBody
400	Appears when: One or several parameters from a request failed in validation. An overlap with already existing shift is received. For closed and open shifts, it is not allowed to have several non-deleted shifts for the same employee and period of time. Also for a response body with the message “Processed shift overlapped with existing for this employee. Processed shift: StartDateTime={0}, EndDateTime={1}. Existing shift: StartDateTime={2} EndDateTime={3}“, where: {0} = value received in the request {1} = value received in the request or 'Still Clocked-In' if null was received in the request {2} = value of the existing shift {3} = value of the existing shift or 'Still Clocked-In' if the existing shift is open An outdated shift update is sent (when the received `ActualUpdateDate` value < = the one that a shift already has in the database) or non-existent shift ID is sent. Related internal requests to other components fail. If the update is performed for a shift that belongs to a deleted company or site, or the employee or employee’s job. Message: Bad Request
401	The token is absent or incorrect. Message: Unauthorized
403	Appears when the received token has not enough permissions to perform this action or the data in the token and headers does not match. Message: Forbidden
500	An error was received during the processing. Message: Internal Server Error

PUT /v2/schedules/[ID]

Summary

Provides an ability to update only one active schedule and its child shifts at a time.

Warning

This endpoint updates active schedules and shifts only, isActive: true.

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The token created previously. For information on tokens, see Authentication.
header	`X-COMPANY-ID`	string	Yes	The unique identifier (UID) for the company provided by Genius. Note This operation can only do one company at a time, cannot be null or empty, and the `company_id` in the token should match the value received in this header.
path	`id`	string	Yes	The [ID] in the URL should contain a 24 character hexadecimal UID in our system of the non-deleted schedule that should be updated with a new data.
body	`body`	PutSchedulesRequestBody	Yes	The request object with the schedule information

Sample Request Body

curl --location -g --request PUT 'https://qa-schedule.xenial.com/v2
/schedules/66d16bbafea8ff072f4181c6' \
--header 'x-company-id: 5ee35ad4653fed0009c8ff56' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [token]' \
--data-raw '{
    "StartDate": "2023-11-24T04:00:00.000Z",
    "EndDate": "2023-11-27T04:00:00.000Z",
    "ModifyTime": "2023-11-28T00:09:00.000Z",
    "Shifts": [
        {
            "ShiftId": "63da4601b5c13514ecaeac0a",
            "BusinessDate": "2023-11-24",
            "StartTime": "2023-11-24T13:00:00.000Z",
            "EndTime": "2023-11-24T23:00:00.000Z",
            "EmployeeCorporateCode": "134489",
            "JobCodeId": "58e63c06fbf17de5ced22014"
        },
        {
            "BusinessDate": "2023-11-26",
            "StartTime": "2023-11-26T13:00:00.000Z",
            "EndTime": "2023-11-26T23:00:00.000Z",
            "EmployeeId": "607eab3dbffe7e00011adfd1",
            "ExternalJobCodeId": "80892",
            "ExternalShiftId": "920u93"
        }
    ]
}'

Responses

Code	Description	Schema
200	Successfully updated the schedule with all its non-deleted child shifts	PutSchedulesResponseBody
400	One or several parameters from a request failed in validation. Message: Bad Request
401	The token is absent or incorrect. Message: Unauthorized
403	The provided token does not have the required permissions to perform this action within this company. Message: Forbidden
500	An error was received during the processing. Message: Internal Server Error

GET /External/General/Payroll/GetUpdates

Summary

This endpoint provides information about all payroll details created/updated/deleted in the database for a specified time frame received in the request and it provides information for both active and deleted payrolls.

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The token created previously. For information on tokens, see Authentication.
header	`X-COMPANY-ID`	string/HEX24	Yes	The unique identifier (UID) for the company provided by Genius. Only one company at a time. The parameter cannot be `null`, empty, `””`. The `company_id` in the token should match the value received in this header.
header	`X-SITE-IDs`	string/HEX24	No	The UID of the site provided by Genius. Only one site at a time or this header should be omitted. An absent value is considered as an absent parameter, which means if this header is received without a value, it is just ignored in the request.
query	`UpdateDateFrom`	string/datetime UTC with ms	Yes	This parameter is used to receive only those payroll details that were updated in the database after a particular date and time and received in this parameter. For example, the time since the last data pulling. Only one date at a time and should be sent in the YYYY-MM-DDTHH:MM:SS.SSSZ format. The `UpdateDateFrom` value cannot be older than one calendar month.
query	`UpdateDateTo`	string/datetime UTC with ms	No	This parameter is used to receive only those payroll details that were updated until a particular date and time received in this parameter. This field should be sent in a request only when there is a need to find payroll details updated in a defined time frame and not earlier or later. If received, this parameter cannot be `null`, empty, or `““`. Only one date at a time and should be sent in the YYYY-MM-DDTHH:MM:SS.SSSZ format. The received value should always be greater than the `UpdateDateFrom` value.

Sample Request Body

curl --location --request GET 'https://qa-backoffice-api.xenial.com
/External/General/Payroll/GetUpdates?UpdateDateFrom=2023-08-08T23:50:00.000Z' \
--header 'Content-Type: application/json' \
--header 'X-Company-id: 63da4601b5c13514ecaeac0a' \
--header 'X-Site-Ids: 620c011778da1c0008db8bac' \
--header 'Authorization: Bearer 
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InhwcnQifQ....'

Responses

For a successful response:

Both active and deleted payroll detail records are returned in response if they match the received filters.
The response size is limited to no more than 100 payroll detail records returned at a time. For pagination needs, the NextUpdateDateFrom field can be used in order to not miss data.
- In order to request another 100 batch, a value received in the response in the NextUpdateDateFrom field in the first request should be sent in the UpdateDateFrom query parameter in the next request. This approach should be repeated until Data array is returned empty as this is a marker that all updates have already been provided.
- If for any reason 100th element in response contains the same update_date value in the database as the 101th, all payroll detail records with this update_date value are not returned in response of the first request in order to not lose the values and allow the chance to return them in the next request with the NextUpdateDateFrom value returned in the response to the first request.
- If no payroll detail records were found based on the received time values, the NextUpdateDateFrom field will contain the same timestamp as sent in the request in the UpdateDateFrom parameter.
The data in received in the response is sorted by payroll detail records' update_date in ascending order.

Code	Description	Schema
200	Message: Success Where: The `Data` array contains information about all found payroll detail records. The `NextUpdateDateFrom` field contains maximum `update_date` value from the database for the payroll detail records found and sent in response with limitations of no more than 100 elements inside the `Data` array. If no payroll detail records were found according to the received query parameters: The `Data` array is returned as `"Data": []`. The `NextUpdateDateFrom` = received `UpdateDateFrom`. For example: { "Data": [], "NextUpdateDateFrom": "2025-03-21T05:25:18.000Z" }	GetExternalGeneralPayrollGetUpdatesResponseBody
400	Appears when: One or several parameters from headers / body failed in validation. Related requests to the Portal failed. Message: Bad Request
401	Appears when the token is absent or incorrect, or data in token is different than the one received in headers. Message: Unauthorized
403	Appears when the provided token does not have the required permissions to perform this action within this company or the data in the token and headers does not match. Message: Forbidden
500	Appears when an error was received during processing. Message: Internal Server Error

GET /Lookup/Ethnicity

Summary

This endpoint returns a list of available ethnicities from Data Management - Ethnicities section.

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The token created previously. For information on tokens, see Authentication.
header	`X-COMPANY-ID`	string	Yes	The unique identifier (UID) for the company provided by us Note This operation can only do one company at a time, cannot be null or empty, and the `company_id` in the token should match the value received in this header.

Sample Request Body

curl --location --request GET 'https://qa-backoffice-api.xenial.com
/Lookup/Ethnicity' \
--header 'Content-Type: application/json' \
--header 'X-Company-Id: 63da4601b5c13514ecaeac0a' \
--header 'Authorization: Bearer 
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InhwcnQifQ...'

Responses

Code	Description	Schema
200	Success Response. Message - OK	GetEthnicityResponseBody

Code

Description

Schema

200

Success Response.

Message - OK

GetEthnicityResponseBody

GET /auth/getCompanyRoles

Summary

The GET Company Roles endpoint returns a list of available roles within a given company, which are configurable by end users. These role values are referenced when creating point of sale (POS) credentials for a given employee.

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The token created previously. For information on tokens, see Authentication.
header	`X-COMPANY-ID`	string	Yes	The unique identifier (UID) for the company provided by us

Sample Request Body

curl --location --request GET 'https://qa-backoffice-api.xenial.com/Auth
/GetCompanyRoles' \
--header 'Content-Type: application/json' \
--header 'X-Company-Id: 63da4601b5c13514ecaeac0a' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtp
ZCI6InhwcnQifQ...'

Responses

Code	Description	Schema
200	Success Response. Message: OK	GetCompanyRolesResponseBody

Code

Description

Schema

200

Success Response.

Message: OK

GetCompanyRolesResponseBody

GET /Lookup/EmployeeStatus

Summary

The GET Employee Status endpoint returns a list of available Status records from Data Management -Employee Status Config section, which are assigned to Employees within Employee Site Status related requests.

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The token created previously. For information on tokens, see Authentication.
header	`X-COMPANY-ID`	string	Yes	The unique identifier (UID) for the company provided by us
header	`X-SITE-IDs`	string	Yes	The UID of the site, provided by us, for which a list of site statuses is provided

Sample Request Body

curl --location --request GET 'https://qa-backoffice-api.xenial.com/Lookup
/EmployeeStatus' \
--header 'Content-Type: application/json' \
--header 'X-Company-Id: 63da4601b5c13514ecaeac0a' \
--header 'X-Site-Ids: 63da4653b5c13514ecaeac0f' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtp
ZCI6InhwcnQifQ....'

Responses

Code	Description	Schema
200	Success Response. Message - OK	GetEmployeeStatusResponseBody

Code

Description

Schema

200

Success Response.

Message - OK

GetEmployeeStatusResponseBody

GET /Staff/JobCode

Summary

The Get All Jobs operation returns an array of all of the jobs that an employee can be assigned to.

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The token created previously. For information on tokens, see Authentication.
header	`X-COMPANY-ID`	string	Yes	The unique identifier (UID) for the company provided by us
header	`X-SITE-IDs`	string	Yes	An array of comma-separated `[SITE-IDs]` for which data is returned

Responses

Code	Description	Schema
200	Success Response	GetAllJobsResponseBody
404	Error Response. Message: Not Found
Default	Error Response. Message: Unexpected Error

Code

Description

Schema

200

Success Response

GetAllJobsResponseBody

404

Error Response.

Message: Not Found

Default

Error Response.

Message: Unexpected Error

GET /Lookup/Country

Summary

This endpoint returns a list of available countries from Data Management Countries' section. For the response schema, see GetLookupCountryResponseBody.

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The token created previously. For information on tokens, see Authentication.
header	`X-COMPANY-ID`	string	Yes	The unique identifier (UID) for the company provided by us Note This operation can only do one company at a time, cannot be null or empty, and the `company_id` in the token should match the value received in this header.

Sample Request Body

curl --location --request GET 'https://qa-backoffice-api.xenial.com/Lookup/
Country' \
--header 'Content-Type: application/json' \
--header 'X-Company-Id: 61939a5901181700091be07a' \
--header 'Authorization: Bearer 
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InhwcnQifQ….'

GET /Lookup/State

Summary

This endpoint returns a list of available states from Data Management from the Country States section. For the response schema, see GetLookupStateResponseBody.

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The token created previously. For information on tokens, see Authentication.
header	`X-COMPANY-ID`	string	Yes	The unique identifier (UID) for the company provided by us Note This operation can only do one company at a time, cannot be null or empty, and the `company_id` in the token should match the value received in this header.

Sample Request Body

curl --location --request GET 'https://qa-backoffice-api.xenial.com/Lookup/
State' \
--header 'Content-Type: application/json' \
--header 'X-Company-Id: 61939a5901181700091be07a' \
--header 'Authorization: Bearer 
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InhwcnQifQ….'

GET /Lookup/TenderType

Summary

This endpoint returns a list of available payment types from Data Management Payment Type section.

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The token created previously. For information on tokens, see Authentication.
header	`X-COMPANY-ID`	string	Yes	The unique identifier (UID) for the company provided by Genius.
header	`X-SITE-IDs`	string	Yes	The unique site identifier for the employee's primary work location Note Only one active site ID can be requested at one time. The site should belong to the company received in the X-Company-ID header.

Sample Request Body

curl --location --request GET 
'https://backoffice-api.xenial.com/Lookup/TenderType' \
--header 'Content-Type: application/json' \
--header 'X-Company-Id: 5ddab0e3d93109001df6a76c' \
--header 'Authorization: Bearer 
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InhwcnQifQ...'

Responses

Code	Description	Schema
200	Message: Success.	GetLookupTenderTypeResponseBody

GET /Lookup/TenderCurrency

Summary

This endpoint returns a list of available currencies configured in the Portal in the Data Management Tender Currency section.

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The token created previously. For information on tokens, see Authentication.
header	`X-COMPANY-ID`	string	Yes	The unique identifier (UID) for the company provided by Genius.
header	`X-SITE-IDs`	string	Yes	The unique site identifier for the employee's primary work location Note Only one active site ID can be requested at one time. The site should belong to the company received in the X-Company-ID header.

Sample Request Body

curl --location --request GET 
'https://backoffice-api.xenial.com/Lookup/TenderCurrency' \
--header 'Content-Type: application/json' \
--header 'X-Company-Id: 5ddab0e3d93109001df6a76c' \
--header 'Authorization: Bearer 
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InhwcnQifQ...'

Responses

Code	Description	Schema
200	Message: Success.	GetLookupTenderCurrencyResponseBody

GET /External/General/Shift/GetUpdates

Summary

Provides the ability to receive a list of all shifts, active and deleted, updated in a defined period of time.

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The token created previously. For information on tokens, see Authentication.
header	`X-COMPANY-ID`	string	Yes	The unique identifier (UID) for the company provided by Genius. Note This operation can only do one company at a time, cannot be null or empty, and the `company_id` in the token should match the value received in this header.
header	`X-SITE-IDs`	string	No	The unique site identifier for the employee's primary work location Note This operation can only do one site at a time and cannot be null or empty.
query	`UpdateDateFrom`	string	Yes	This parameter is used to receive only those shifts that were updated in the database after some particular date/time received in this parameter. For example, the time since the last data pulling until the current Coordinated Universal Time (UTC) timestamp or the time received in the `UpdateDateTo` parameter. Note The parameter can use only one date at a time in the 'YYYY-MM-DDTHH:MM:SS.SSSZ' format. The date/time should be provided in UTC.
query	`UpdateDateTo`	string	No	This parameter is used to receive only those shifts that were updated until some particular date/time received in this parameter. This field should be sent in a request only when there is a need to find shifts updated in a defined timeframe, and not earlier or later. Note The parameter can use only one date at a time in the 'YYYY-MM-DDTHH:MM:SS.SSSZ' format. The date/time should be provided in UTC. The received value should always be greater than the `UpdateDateFrom`.

Sample Request Body

curl --location --request GET 
'https://qa-backoffice-api.xenial.com/External/General/Shift/
GetUpdates?UpdateDateFrom=2023-08-08T23:50:00.000Z' \
--header 'Content-Type: application/json' \
--header 'X-Company-id: 63da4601b5c13514ecaeac0a' \
--header 'X-Site-Ids: 620c011778da1c0008db8bac' \
--header 'Authorization: Bearer 
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InhwcnQifQ....'

Responses

Code	Description	Schema
200	Message: Success.	GetExternalGeneralShiftUpdatesResponseBody
400	Appears when: One or several parameters from a request failed in validation. Related internal requests to other components fail. Message: Bad Request
401	The token is absent or incorrect. Message: Unauthorized
403	Appears when the received token has not enough permissions to perform this action or the data in the token and headers does not match. Message: Forbidden
500	An error was received during the processing. Message: Internal Server Error

GET /External/General/Shift/GetByBusinessDate

Summary

Provides the ability to receive a list of all shifts for a defined business date with additional filtering options.

Note

For this request, all query parameters work using the AND condition.

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The token created previously. For information on tokens, see Authentication.
header	`X-COMPANY-ID`	string	Yes	The unique identifier (UID) for the company provided by Genius. Note This operation can only do one company at a time, cannot be null or empty, and the `company_id` in the token should match the value received in this header.
header	`X-SITE-IDs`	string	Yes	The unique site identifier for the employee's primary work location Note This operation can only do one site at a time and cannot be null or empty.
query	`BusinessDate`	string	Yes	A business date for which all related shifts should be returned in response. If a valid date is received, all shifts that are crossing this business date are returned in response. Note The parameter can use only one date at a time in the YYYY-MM-DD format. The parameter cannot be null, empty, or ““.
query	`EmployeeIds`	array of strings	No	A list of employee identifiers (IDs) for which shifts should be returned in response for a certain business date. If a valid list of employee IDs is received, all shifts that have these employee IDs are returned in response if they match other received filter conditions: If this parameter is not received, it is ignored during the shifts search. If received, this parameter cannot be null, empty, or ““. Received values should have a 24 character hexadecimal string format. Only comma separators for values in this array can be used. 50 is the maximum number of records that can be received in this parameter.
query	`ShiftStatuses`	array of strings	No	Shifts received in this parameter's statuses are returned in the response only if they match other received filter conditions. The available shift statues: `CLOCKED_IN`: employee is not on a break and currently actively working. `ON_BREAK`: employee is currently on a break. `CLOCKED_OUT`: a shift is closed. If a valid list of statuses is received, all shifts that have these statuses are returned in the response if they match other received filter conditions: If this parameter is not received, it is ignored during the shifts search. If received, this parameter cannot be null, empty, or ““. The only supported values are `CLOCKED_OUT`, `CLOCKED_IN`, and `ON_BREAK`. Only comma separators for values in this array can be used.
query	`IncludeDeleted`	boolean	No	This parameter allows receiving `deleted` shifts in response if they match other received filter conditions. If a valid value is received, all shifts that have `is_active` value = the one received in this parameter are returned in response if they match other received filter conditions: If received, this parameter cannot be null, empty, ““, or with a non-boolean value. If this parameter is not received, it is ignored during the shifts search. Only active shifts are returned in response in this case.
query	`ItemsPerPage`	integer	No	This parameter is used for pagination needs and provides an ability to regulate the page size returned in response: If received, this parameter cannot be null, empty, ““, or with a non-integer value. If received, this parameter’s value cannot be greater than a default page size, which is 100 elements. If this parameter is not received, it is ignored. The default number of elements (100) is returned in response.
query	`PageNumber`	integer	No	This parameter is used for pagination needs and provides an ability to move to another data page skipping the previously processed one: If received, this parameter cannot be null, empty, ““, or with a non-integer value. If this parameter is not received, it is ignored. The first page of data (first elements in quantity = either default size or received in the `ItemsPerPage` parameter) are returned in response. Initial value = 0.

Sample Request Body

curl --location --request GET 
'https://qa-backoffice-api.xenial.com/External/General/Shift/
GetByBusinessDate?BusinessDate=2023-08-08&EmployeeIds=6690db6d636c0f9b657ce4cf,
6690db6d965c2ba2c74e471b&IncludeDeleted=true&ShiftStatuses=CLOCKED_OUT,
CLOCKED_IN&ItemsPerPage=50&PageNumber=2' \
--header 'Content-Type: application/json' \
--header 'X-Company-id: 63da4601b5c13514ecaeac0a' \
--header 'X-Site-Ids: 620c011778da1c0008db8bac' \
--header 'Authorization: Bearer 
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InhwcnQifQ....'

Responses

Code	Description	Schema
200	Message: Success. Where: `Data` array contains information about all found shifts. `TotalCount` field contains a total number of shifts found based on the received filters in query parameters and headers. This field is returned in response for every requested page with the same number unless some new shifts were added or removed during the period of data retrieval. This field’s value can be used to calculate how many pages should be requested to retrieve all existing shifts based on the received filters. For example, if the `TotalCount` = 147 and the `ItemsPerPage` parameter was not received, then, considering that a default page size = 100, 2 pages should be requested using the `PageNumber` parameter: The first request is made with `PageNumber` = 0 (100 shifts are returned), second - `PageNumber` = 1 (47 shifts are returned). If the `TotalCount` = 147 and the `ItemsPerPage` parameter was received with 50, then 3 pages should be requested using the `PageNumber` parameter: The first request is made with `PageNumber` = 0 (50 shifts are returned), second - `PageNumber` = 1 (50 shifts are returned), third - `PageNumber` = 2 (47 shifts are returned). If no shifts were found according to the received query parameters or there are no shifts for the received page: `Data` array is returned as `"Data": []`. // no data found { "Data": [], "Total": 0 } // no records for the received page { "Data": [], "Total": 190 }	GetExternalGeneralShiftByBusinessDateResponseBody
400	Appears when: One or several parameters from a request failed in validation. Related internal requests to other components fail. Message: Bad Request
401	The token is absent or incorrect. Message: Unauthorized
403	Appears when the received token has not enough permissions to perform this action or the data in the token and headers does not match. Message: Forbidden
500	An error was received during the processing. Message: Internal Server Error

GET /External/General/Shift/GetByShiftIds

Summary

Provides the ability to receive a list of shifts based on the received identifiers (IDs).

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The token created previously. For information on tokens, see Authentication.
header	`X-COMPANY-ID`	string	Yes	The unique identifier (UID) for the company provided by Genius. Note This operation can only do one company at a time, cannot be null or empty, and the `company_id` in the token should match the value received in this header.
query	`ShiftIds`	array of strings	Yes	A list of shift IDs that are returned in response for a certain business date. If a valid list of shift IDs is received, all shifts that have these IDs are returned in response. If for some IDs no shifts were found in the database, the shifts are not returned in the response, but they do not block other shifts processing. No errors or warnings are returned in response: If received, this parameter cannot be null, empty, or ““. Received values should have a 24 character hexadecimal string format. Only comma separators for values in this array can be used. 100 is the maximum number of records that can be received in this parameter.

Sample Request Body

curl --location --request GET 'https:
//qa-backoffice-api.xenial.com/External/General/Shift/
GetByShiftIds?ShiftIds=62a6b87bb4fd7c0008692cc5,
65a6d588adf7e83d16d43313,64d56a110745cc5992a0a1e0,
64d56a3421800bf5155221e1,62a3590cf118dc00098dfbc2,
62c2ed58dc684eeab137afa1,62a6ba9dde4ad10008787202,
6216c4a9300f510008713939,62bf0330c269a6b441b77410,
62c323603ec4efe48384366d,62a7688eec28df000852ca4e,
62c3247378d3983c50a26aaa,62efe194f24a76771990e9f7,
6303b0f116a947b559ad973b,630cdffcbada7f474bc32bc4,
62f167f2ac2319d201d3fea5,62bcb282c35cb31d0f3758b1,
6304223db5ce1b620f0c9d8a,62bb3a52bbba59d8728a30ec,
62bb3ad82f4d8129093e07d8,62fa91210b6d6caf565254b0,
62bf023724d1569abf8b65dd,630ce8816e9f5e8429b9e98a,
61e8540c61592400086ebe62,62bcb2f0c842bf57ad6d3e66,
62a769e990ec100009158ed3,63041f73d5c980d7a7188794,
632b5a73b3c158e7e98a99aa,653a8fcefc74f491eea4a785,
63ae19bc9bd59b8b2e074851,64dc427b31f797ced93bce37,
63222fe5b3c158e7e98a9986,63223091dda51a6ab003cd21,
640255a804d21164204471aa,63405118d977f30666a8e1ef,
634859cffd12eb7dc81647cc,638fd7bac4bc14f39d2b042d,
638fd8c509528134de27ba4a,638fd95288adf859c7bb43f8,
638fd8300cd618ba2208e7d9,63a61c5401e6f5aa67ad6fa2,
6401348cbf987c3ff11d3380,647e5ba17632754908569f8b,
64b2dd29a5819a837663636d,654a9e1c4d97db69ef8be611,
64d56ba45317fb67d6cfce2f,64c99dd8a490a4bf8d9927e5, \
--header 'Content-Type: application/json' \
--header 'X-Company-id: 63da4601b5c13514ecaeac0a' \
--header 'Authorization: Bearer 
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InhwcnQifQ....'

Responses

Code	Description	Schema
200	Message: Success. Where: `Data` array contains information about all found shifts. If no shifts were found according to the received query parameters or there are no shifts for the received page: `Data` array is returned as `"Data": []`.	GetExternalGeneralShiftByShiftIDsResponseBody
400	Appears when: One or several parameters from a request failed in validation. Related internal requests to other components fail. Message: Bad Request
401	The token is absent or incorrect. Message: Unauthorized
403	Appears when the received token has not enough permissions to perform this action or the data in the token and headers does not match. Message: Forbidden
500	An error was received during the processing. Message: Internal Server Error

GET /SchedulesService/schedules

Summary

Provides an ability to retrieve a list of all existing, non-deleted schedule records with a list of their non-deleted child shifts based on the received query filters.

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The token created previously. For information on tokens, see Authentication.
header	`X-COMPANY-ID`	string	Yes	The unique identifier (UID) for the company provided by Genius. Note This operation can only do one company at a time, cannot be null or empty, and the `company_id` in the token should match the value received in this header.
header	`X-SITE-IDs`	string	Yes	The UID for the site provided by us Note This operation can only do one site at a time and cannot be null or empty. The received site ID should be non-deleted and belong to the company received in the `X-COMPANY-ID` header.
query	`StartDate`	string	Yes	The start Date for the schedule in the YYYY-MM-DD format
query	`EndDate`	string	No	The end Date for the schedule in the YYYY-MM-DD format. If not received, all schedules with the received `StartDate` + 14 days value in the `EndDate` field in the databse are returned.
query	`$top`	integer	No	This parameter regulates the page size value, such as how many found records are displayed in the response. If this parameter is received, a successful response body contains a `page_size` field with the number equal to the one received in this parameter and the `"items":[]` array will contain the number of records equal to the quantity received in this parameter.
query	`$skip`	integer	No	This parameter can be used for pagination scrolling. It shows how many of the first found records can be ignored and not returned in the response. Example: The total quantity is 104 and the default page size is 100. In order to receive all records: Send a request without this parameter or $skip=0. Receive successful response. The first request also shows the total value that could help identify how many additional requests should be made in order to receive the whole list of found records. Send an additional request with `$skip=100` in the order to receive the four (4) remaining records.

Sample Request Body

curl --location --request GET 'https://qa-schedule.xenial.com/SchedulesService
/schedules?$top=50&$skip=0&StartDate=2025-02-20' \
--header 'x-company-id: 67c17d6db633aac8decd6dca' \
--header 'x-site-ids: 67c18218c2cda380bb670597' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InhwcnQifQ...'

Responses

Code	Description	Schema
200	All found documents that are not deleted are returned in response. Message: Success	GetSchedulesResponseBody
400	One or several parameters from a request failed in validation. Message: Bad Request
401	The token is absent or incorrect. Message: Unauthorized
403	The provided token does not have the required permissions to perform this action within this company. Message: Forbidden
500	An error was received during the processing. Message: Internal Server Error

GET /External/General/Employee/[ID]

Summary

This endpoint retrieves details of a single, active, non-deleted employee associated with the specified company. The response includes the complete employee information and, if requested, additional details such as addresses, site statuses, and other related data.

Note

It is recommended to request only those employee details that are required for the integration.

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The token created previously. For information on tokens, see Authentication.
header	`X-COMPANY-ID`	string	Yes	The 24-character hexadecimal unique identifier (UID) for the company provided by Genius
path	`id`	string	Yes	The 24-character hexadecimal UID for the employee
query	`selectNested`	array of strings	No	This parameter specifies which child entities should be included in the response. It can be used to exclude unnecessary data that is not required by integrators. If this parameter is not received, it is ignored. In this case employees are returned without described below child arrays and objects, only general employee data. If non-existent, or non-supported by this endpoint, employee child entities are requested by this parameter, they are ignored and not returned in response. If received, this parameter cannot be `null`, `empty`, or `““`.

Sample Request Body

curl --location --request GET 'https://qa-backoffice-api.xenial.com/External
/General/Employee/680f7ea1b11c2fd89f820877?selectNested=EmployeeSiteStatuses,
EmpoyeeJobs,PosCredentials' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--header 'x-company-id: 6486c8815de62f49cf344519'

Responses

Code	Description	Schema
200	Message: Success.	General Structure - GetExternalGeneralEmployeeResponseBody
400	Appears when: One or several parameters from a request failed in validation. Related internal requests to other components fail. Message: Bad Request
401	The token is absent or incorrect. Message: Unauthorized
403	Appears when the received token has not enough permissions to perform this action or the data in the token and headers does not match. Message: Forbidden
404	Appears when no employee records were found within the received company and with the received UID. Message: Not Found
410	Appears when an employee record with the received UID is no longer active and has been deleted. Message: Gone
500	An error was received during the processing. Message: Internal Server Error

An example of a fully successful request where all child arrays and objects were received in the query parameters.

{
    "EmployeeId": "63da49d6db78faa7f38988d3",
    "Firstname": "John",
    "Lastname": "Doe",
    "Middlename": null,
    "Name": "John Doe",
    "Username": null,
    "EmployeeCorporateCode": "8796276",
    "ExternalEmployeeId": null,
    "PrimarySiteId": "63da4653b5c13514ecaeac0f",
    "Source": "TestSource",
    "LastUpdateDate": "2023-02-01T11:18:34.253",
    "IsActive": true,  
    "AdditionalDetails": {
        "TaxIdentifier": null,
        "BadgeNumber": null,
        "EthnicityCode": null,
        "Nickname": null,
        "BirthDate": null,
        "Gender": null,
        "IsHandicapped": false,
        "IsRehireable": false,
        "IsVeteran": false,
        "IsMinor": false
    },
    "EmployeePhones": [
        {
            "PhoneNumber": "+2-312-312-3123",
            "PhoneTypeCode": "HOME"
        }
    ],
    "EmployeeAddresses": [
        {
            "AddressTypeCode": "HOME",
            "Address1": "Address 1",
            "Address2": "",
            "Address3": "",
            "City": "Pittsburgh",
            "StateCode": "PA",
            "PostalCode": "15106",
            "CountryCode": "US"
        }
    ],
    "EmployeeContacts": [
        {
            "ContactCode": "johnjackson",
            "Firstname": "John",
            "Lastname": "Jackson",
            "Middlename": "",
            "Address1": "Address1",
            "Address2": "",
            "Address3": "",
            "City": "Pittsburgh",
            "StateCode": "PA",
            "PostalCode": "15106",
            "CountryCode": "US",
            "Phone1": "+0-232-123-1231",
            "Phone2": ""
        }
    ],
    "EmployeeEmails": [
        {
            "Email": "jd+836@jd.com",
            "EmailTypeCode": "PRSNL"
        }
    ],
    "EmployeeJobs": [
        {
            "EmployeeJobId": "63da4ba2614bb6862d37a761",
            "EffectiveDate": "2023-01-01",
            "JobCodeId": "58e63c06fbf17de5ced22064",
            "ExternalJobCodeId": "80801",
            "IsPrimaryJob": true,
            "Deactivated": false,
            "DeactivationDate": null,
            "SiteId": "63da4653b5c13514ecaeac0f",
            "EmployeeJobPays": [
                {
                    "CompensationTypeCode": "HOUR",
                    "Rate": 15.56,
                    "EffectiveDate": "2023-01-01"
                },
                {
                    "CompensationTypeCode": "HOUR",
                    "Rate": 18.00,
                    "EffectiveDate": "2023-01-12"
                }
            ]
        },
        {
            "EmployeeJobId": "63da4e01db78faa7f38988da",
            "EffectiveDate": "2023-01-13",
            "JobCodeId": "58e63c06fbf17de5ced22074",
            "ExternalJobCodeId": null,
            "IsPrimaryJob": true,
            "Deactivated": false,
            "DeactivationDate": null,
            "SiteId": "63da4653b5c13514ecaeac0f",
            "EmployeeJobPays": [
                {
                    "CompensationTypeCode": "SLRY",
                    "Rate": 24.0,
                    "EffectiveDate": "2023-01-13"
                }
            ]
        }
    ],
    "EmployeeSiteStatuses": [
        {
            "EffectiveDate": "2024-01-01",
            "StatusCode": "ACTV",
            "SiteIds": [
                "63df82df32753797d3cfa2e1",
                "63df82df32753797d3cfa2e2",
                "63da4653b5c13514ecaeac0f"
            ]
        },
        {
            "EffectiveDate": "2024-01-01",
            "StatusCode": "IACTV",
            "SiteIds": [
                "63df82df32753797d3cfa2e3"
            ]
        },
        {
            "EffectiveDate": "2025-01-01",
            "StatusCode": "IACTV",
            "SiteIds": [
                "63df82df32753797d3cfa2e2",
                "63da4653b5c13514ecaeac0f"
            ]
        }
    ],
    "PosCredentials": [
        {
            "EmployeePOSCode": "68096",
            "Password": 
"DbFof1aDd4KgmPEFQ7fWzJFks9c/RZlB8rR4o7PTUBacahdBcEw1X48htzeOz2mL",
            "RoleId": "63da469cb5c13514ecaeac10"
        }
    ]
}

An example of a fully successful request where only EmployeeJobs, EmployeeSiteStatues, and PosCredentials were received in the selectNested query parameter.

{
    "EmployeeId": "63da49d6db78faa7f38988d3",
    "Firstname": "John",
    "Lastname": "Doe",
    "Middlename": null,
    "Name": "John Doe",
    "Username": null,
    "EmployeeCorporateCode": "8796276",
    "ExternalEmployeeId": null,
    "PrimarySiteId": "63da4653b5c13514ecaeac0f",
    "Source": "TestSource",
    "LastUpdateDate": "2023-02-01T11:18:34.253",
    "IsActive": true,
    "EmployeeJobs": [
        {
            "EmployeeJobId": "63da4ba2614bb6862d37a761",
            "EffectiveDate": "2023-01-01",
            "JobCodeId": "58e63c06fbf17de5ced22064",
            "ExternalJobCodeId": "80801",
            "IsPrimaryJob": true,
            "Deactivated": false,
            "DeactivationDate": null,
            "SiteId": "63da4653b5c13514ecaeac0f",
            "EmployeeJobPays": [
                {
                    "CompensationTypeCode": "HOUR",
                    "Rate": 15.56,
                    "EffectiveDate": "2023-01-01"
                },
                {
                    "CompensationTypeCode": "HOUR",
                    "Rate": 18.00,
                    "EffectiveDate": "2023-01-12"
                }
            ]
        },
        {
            "EmployeeJobId": "63da4e01db78faa7f38988da",
            "EffectiveDate": "2023-01-13",
            "JobCodeId": "58e63c06fbf17de5ced22074",
            "ExternalJobCodeId": null,
            "IsPrimaryJob": true,
            "Deactivated": false,
            "DeactivationDate": null,
            "SiteId": "63da4653b5c13514ecaeac0f",
            "EmployeeJobPays": [
                {
                    "CompensationTypeCode": "SLRY",
                    "Rate": 24.0,
                    "EffectiveDate": "2023-01-13"
                }
            ]
        }
    ],
    "EmployeeSiteStatuses": [
        {
            "EffectiveDate": "2024-01-01",
            "StatusCode": "ACTV",
            "SiteIds": [
                "63df82df32753797d3cfa2e1",
                "63df82df32753797d3cfa2e2",
                "63da4653b5c13514ecaeac0f"
            ]
        },
        {
            "EffectiveDate": "2024-01-01",
            "StatusCode": "IACTV",
            "SiteIds": [
                "63df82df32753797d3cfa2e3"
            ]
        },
        {
            "EffectiveDate": "2025-01-01",
            "StatusCode": "IACTV",
            "SiteIds": [
                "63df82df32753797d3cfa2e2",
                "63da4653b5c13514ecaeac0f"
            ]
        }
    ],
    "PosCredentials": [
        {
            "EmployeePOSCode": "68096",
            "Password": 
"DbFof1aDd4KgmPEFQ7fWzJFks9c/RZlB8rR4o7PTUBacahdBcEw1X48htzeOz2mL",
            "RoleId": "63da469cb5c13514ecaeac10"
        }
    ]
}

An example of a fully successful request where the selectNested query parameter was not received.

{
    "EmployeeId": "63da49d6db78faa7f38988d3",
    "Firstname": "John",
    "Lastname": "Doe",
    "Middlename": null,
    "Name": "John Doe",
    "Username": null,
    "EmployeeCorporateCode": "8796276",
    "ExternalEmployeeId": null,
    "PrimarySiteId": "63da4653b5c13514ecaeac0f",
    "Source": "TestSource",
    "LastUpdateDate": "2023-02-01T11:18:34.253",
    "IsActive": true
}

GET /External/General/Employee

Summary

This endpoint returns information about all non-deleted employees only associated with the requested company and, if specified, sites. The response includes complete employee information and, if requested, additional details such as addresses, site statuses, and other related data.

This endpoint is useful for initial imports or periodic data validations, when all employees for a company and, if requested, for a list of sites need to be retrieved. However, since this endpoint processes large amounts of data, it is strongly recommended to use the X-SITE-IDs header to limit results to specific sites whenever possible or to avoid sending requests too frequently. For example, every N minutes.

Note

It is recommended to request only those employee details that are required for the integration.

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The token created previously. For information on tokens, see Authentication.
header	`X-COMPANY-ID`	string	Yes	The 24-character hexadecimal unique identifier (UID) for the company provided by Genius
header	`X-SITE-IDs`	array of strings, separated by commas	No	The UID for the site(s) provided by Genius. Multiple site IDs can be provided, separated by commas. For example, 60ace72bacb1540007d34698,60ace72bacb1540007d34697.b If the parameter is provided without a value, it is treated as not provided. In this case, all employees within the specified company that match the query parameters will be returned. Note This parameter is useful to retrieve information related only to employees associated with the requested sites.
query	`selectNested`	array of strings	No	This parameter specifies which child entities should be included in the response. It can be used to exclude unnecessary data that is not required by integrators. If this parameter is not received, it is ignored. In this case employees are returned without described below child arrays and objects, only general employee data. If non-existent, or non-supported by this endpoint, employee child entities are requested by this parameter, they are ignored and not returned in response. If received, this parameter cannot be `null`, `empty`, or `““`.
query	`itemsPerPage`	number/integer	No	This parameter defines a page size returned in response, which is the number of employee records returned in response. If this parameter is not received, the default 100 items value is used.
query	`nextPageToken`	string	No	This parameter is used to receive the next portion of data based on the previous response. If received, this parameter cannot be null, empty, or ““. Warning Pagination in this endpoint supports only sequential data retrieval and does not allow parallelization. The next page can only be requested using the token returned in the response to the previous page in the `NextPageToken` parameter.

Sample Request Body

curl --location --request GET 'https://qa-backoffice-api.xenial.com/External
/General/Employee' \
--header 'Authorization: Bearer 
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InhwcnQifQ...' \
--header 'Content-Type: application/json' \
--header 'x-company-id: 63da4601b5c13514ecaeac0a' \
--header 'x-site-ids: 63da4653b5c13514ecaeac0f,
63da4653b5c13514ecaeac0d,63da4653b5c13514ecaeac0c'

Responses

For this response:

This endpoint supports caching based on the received filters in the header and query parameters. Due to this, the response time can vary if any changes to employees have been made since the last request.
The response includes non-deleted employee data only.
If the X-SITE-IDs header is received, the response includes all non-deleted employees found based on the received search filters:
- Have active, non-deleted is_active = true Site Status records with the site_id equals those received in this header.
- Or do not have active, non-deleted, is_active = true Site Status records with the site_id equals those received in this header but whose PrimarySiteId equals those received in this header.
The records in the response are sorted by the EmployeeId ascending (ASC) field.

Warning

Integrators using this endpoint should implement a default retry logic. Retries are required when the service responds with a 500 status code or when the connection is abruptly closed. The service may close the connection while sending a response in one of the following ways:

TCP connection is closed with Connection Reset Error (ECONNRESET)
HTTP2 stream is closed with INTERNAL_ERROR

The recommended retry strategy is to perform up to two (2) retries, with delays of five (5) seconds and 30 seconds between attempts. For example:

A request is made.
It fails.
Wait 5 seconds.
Retry once.
If it fails again, wait 30 seconds.
Retry once more.

Code	Description	Schema
200	Message: Success. TotalCount - Shows a total number of employees found based on the received filters in the request. RecordsReturned - Shows a total number of employees returned successfully in the response. A response may not contain the number of records, received in the `itemsPerPage` parameter, or all employees, or even default number, due to the: Exceeding of the processing timeout = 60 seconds. In this case, only those records that were prepared successfully for the response are returned. Exceeding the maximum payload size. The number of records on this page is less than the requested number such as the last portion of data is returned and there are no more employees. NextPageToken - An automatically generated value based on the predefined rules. This value is used in the following request to proceed with employee data retrieval, starting from the employee record, next to the last returned in the previous response. Warning The token has a lifetime of approximately 15 minutes. After that time, it is no longer possible to request the next portion of data using this token. Data retrieval must be started from the beginning. If no employees are found: { "Data": [], "TotalCount": 0, "RecordsReturned": 0, "NextPageToken": null } If no employees exist for the requested page: { "Data": [], "TotalCount": 3600, "RecordsReturned": 0, "NextPageToken": null }	General Structure - GetExternalGeneralEmployeeResponseBody
400	Appears when: One or several parameters from a request failed in validation. Related internal requests to other components fail. Message: Bad Request
401	The token is absent or incorrect. Message: Unauthorized
403	Appears when the received token has not enough permissions to perform this action or the data in the token and headers does not match. Message: Forbidden
500	An error was received during the processing. Message: Internal Server Error

An example of a fully successful request where all child arrays and objects were received in the query parameters.

{
    "Data": [
        {
            "EmployeeId": "63da49d6db78faa7f38988d3",
            "Firstname": "john",
            "Lastname": "doe",
            "Middlename": null,
            "Name": "john doe",
            "Username": null,
            "EmployeeCorporateCode": "8796276",
            "ExternalEmployeeId": null,
            "PrimarySiteId": "63da4653b5c13514ecaeac0f",
            "Source": "TestSource",
            "LastUpdateDate": "2023-02-01T11:18:34.253Z",
            "IsActive": true,
            "AdditionalDetails": {
                "TaxIdentifier": null,
                "BadgeNumber": null,
                "EthnicityCode": null,
                "Nickname": null,
                "BirthDate": null,
                "Gender": null,
                "IsHandicapped": false,
                "IsRehireable": false,
                "IsVeteran": false,
                "IsMinor": false
            },
            "EmployeePhones": [
                {
                    "PhoneNumber": "+2-312-312-3123",
                    "PhoneTypeCode": "HOME"
                }
            ],
            "EmployeeAddresses": [
                {
                    "AddressTypeCode": "HOME",
                    "Address1": "Address 1",
                    "Address2": "",
                    "Address3": "",
                    "City": "Pittsburgh",
                    "StateCode": "PA",
                    "PostalCode": "15106",
                    "CountryCode": "US"
                }
            ],
            "EmployeeContacts": [
                {
                    "ContactCode": "johndoe",
                    "Firstname": "Jack",
                    "Lastname": "doe",
                    "Middlename": "",
                    "Address1": "Address1",
                    "Address2": "",
                    "Address3": "",
                    "City": "Pittsburgh",
                    "StateCode": "PA",
                    "PostalCode": "15106",
                    "CountryCode": "US",
                    "Phone1": "+0-232-123-1231",
                    "Phone2": ""
                }
            ],
            "EmployeeEmails": [
                {
                    "Email": "jd@jd.com",
                    "EmailTypeCode": "PRSNL"
                }
            ],
            "EmployeeJobs": [
                {
                    "EmployeeJobId": "63da4ba2614bb6862d37a761",
                    "EffectiveDate": "2023-01-01",
                    "JobCodeId": "58e63c06fbf17de5ced22064",
                    "ExternalJobCodeId": "80801",
                    "IsPrimaryJob": true,
                    "Deactivated": false,
                    "DeactivationDate": null,
                    "SiteId": "63da4653b5c13514ecaeac0f",
                    "EmployeeJobPays": [
                        {
                            "CompensationTypeCode": "HOUR",
                            "Rate": 15.56,
                            "EffectiveDate": "2023-01-01"
                        },
                        {
                            "CompensationTypeCode": "HOUR",
                            "Rate": 18.00,
                            "EffectiveDate": "2023-01-12"
                        }
                    ]
                },
                {
                    "EmployeeJobId": "63da4e01db78faa7f38988da",
                    "EffectiveDate": "2023-01-13",
                    "JobCodeId": "58e63c06fbf17de5ced22074",
                    "ExternalJobCodeId": null,
                    "IsPrimaryJob": true,
                    "Deactivated": false,
                    "DeactivationDate": null,
                    "SiteId": "63da4653b5c13514ecaeac0f",
                    "EmployeeJobPays": [
                        {
                            "CompensationTypeCode": "SLRY",
                            "Rate": 24.0,
                            "EffectiveDate": "2023-01-13"
                        }
                    ]
                }
            ],
            "EmployeeSiteStatuses": [
                {
                    "EffectiveDate": "2021-01-01"
                    "StatusCode": "ACTV",
                    "SiteIds": [
                        "63df82df32753797d3cfa2e1",
                        "63df82df32753797d3cfa2e2",
                        "63da4653b5c13514ecaeac0f"
                    ]
                },
                {
                    "EffectiveDate": "2025-09-01"
                    "StatusCode": "IACTV",
                    "SiteIds": [
                        "63df82df32753797d3cfa2e3"
                    ]
                }
            ],
            "PosCredentials": []
        },
        {
            "EmployeeId": "63df82df32753797d3cfa2e0",
            "Firstname": "Patrick",
            "Lastname": "Doe",
            "Middlename": null,
            "Name": "Patrick Doe",
            "Username": null,
            "EmployeeCorporateCode": "8796277",
            "ExternalEmployeeId": null,
            "PrimarySiteId": "65fae456a881c84356c79d0a",
            "Source": "TestSource",
            "LastUpdateDate": "2024-07-01T11:01:15.910Z",
            "IsActive": true,
            "AdditionalDetails": {
                "TaxIdentifier": null,
                "BadgeNumber": null,
                "EthnicityCode": null,
                "Nickname": null,
                "BirthDate": null,
                "Gender": null,
                "IsHandicapped": false,
                "IsRehireable": false,
                "IsVeteran": false,
                "IsMinor": false
            },
            "EmployeePhones": [],
            "EmployeeAddresses": [],
            "EmployeeContacts": [],
            "EmployeeEmails": [],
            "EmployeeJobs": [
                {
                    "EmployeeJobId": "66828c6d89635e4fb9898023",
                    "EffectiveDate": "2024-05-27",
                    "JobCodeId": "656f79c4e9af7b2ebedb3f72",
                    "ExternalJobCodeId": "9012fn",
                    "IsPrimaryJob": true,
                    "Deactivated": false,
                    "DeactivationDate": null,
                    "SiteId": "63da4653b5c13514ecaeac0f",
                    "EmployeeJobPays": [
                        {
                            "CompensationTypeCode": "HOUR",
                            "Rate": 100.0,
                            "EffectiveDate": "2024-05-27"
                        }
                    ]
                },
                {
                    "EmployeeJobId": "6717a9bb9f3f963c2d6b8ec6",
                    "EffectiveDate": "2024-10-01",
                    "JobCodeId": "58e63c06fbf17de5ced22064",
                    "ExternalJobCodeId": "80801",
                    "IsPrimaryJob": false,
                    "Deactivated": false,
                    "DeactivationDate": null,
                    "SiteId": "65fae456a881c84356c79d0a",
                    "EmployeeJobPays": [
                        {
                            "CompensationTypeCode": "HOUR",
                            "Rate": 7.25,
                            "EffectiveDate": "2024-10-01"
                        }
                    ]
                }
            ],
            "EmployeeSiteStatuses": [
                {
                  "EffectiveDate": "2025-01-01",
                  "StatusCode": "ACTV",
                    "SiteIds": [
                        "63da4653b5c13514ecaeac0f",
                        "65fae456a881c84356c79d0a"
                    ]
                }
            ],
            "PosCredentials": [
                {
                    "EmployeePOSCode": "16982",
                    "Password": 
"mz+nM5eTpdQVj/+uFeHkkF+Qw1gIfbI+Kiyf1wrWVDbJUe++qPIxSrL7urj8XbYW",
                    "RoleId": "63da469cb5c13514ecaeac10"
                }
            ]
        },
        {
            "EmployeeId": "63df976132753797d3cfa2e7",
            "Firstname": "Mark",
            "Lastname": "Doe",
            "Middlename": "Jr",
            "Name": "Mark Doe",
            "Username": "mark@mark.mark",
            "EmployeeCorporateCode": "8796280",
            "ExternalEmployeeId": "908012",
            "PrimarySiteId": "63da4653b5c13514ecaeac0f",
            "Source": "Back office System 245",
            "LastUpdateDate": "2025-04-10T09:50:55.993Z",
            "IsActive": true,
            "AdditionalDetails": {
                "TaxIdentifier": null,
                "BadgeNumber": "900292",
                "EthnicityCode": null,
                "Nickname": "mark",
                "BirthDate": "2025-10-01",
                "Gender": "M",
                "IsHandicapped": false,
                "IsRehireable": false,
                "IsVeteran": false,
                "IsMinor": false
            },
            "EmployeePhones": [],
            "EmployeeAddresses": [],
            "EmployeeContacts": [],
            "EmployeeEmails": [],
            "EmployeeJobs": [],
            "EmployeeSiteStatuses": [
                {
                    "EffectiveDate": "2025-01-01"
                    "StatusCode": "ACTV",
                    "SiteIds": [
                        "63da4653b5c13514ecaeac0f"
                    ]
                }
            ],
            "PosCredentials": [
                {
                    "EmployeePOSCode": "68096",
                    "Password": 
"DbFof1aDd4KgmPEFQ7fWzJFks9c/RZlB8rR4o7PTUBacahdBcEw1X48htzeOz2mL",
                    "RoleId": "63da469cb5c13514ecaeac10"
                }
            ]
        }
    ],
    "TotalCount": 3616,
    "RecordsReturned": 3,
    "NextPageToken": 
"eyJFbXBsb3llZUlkIjoiNjNjNTI0N2ZmYjIzNzBlZWU1MGZkODg3IiwiRXhwaXJ5IjoxNzU2NDc
1OTY0OTA4MjE0MH0="
}

An example of a fully successful request where only EmployeeJobs, EmployeeSiteStatues, and PosCredentials were received in the selectNested query parameter.

{
    "Data": [
        {
            "EmployeeId": "63da49d6db78faa7f38988d3",
            "Firstname": "john",
            "Lastname": "doe",
            "Middlename": null,
            "Name": "john doe",
            "Username": null,
            "EmployeeCorporateCode": "8796276",
            "ExternalEmployeeId": null,
            "PrimarySiteId": "63da4653b5c13514ecaeac0f",
            "Source": "TestSource",
            "LastUpdateDate": "2023-02-01T11:18:34.253Z",
            "IsActive": true,
            "EmployeeJobs": [
                {
                    "EmployeeJobId": "63da4ba2614bb6862d37a761",
                    "EffectiveDate": "2023-01-01",
                    "JobCodeId": "58e63c06fbf17de5ced22064",
                    "ExternalJobCodeId": "80801",
                    "IsPrimaryJob": true,
                    "Deactivated": false,
                    "DeactivationDate": null,
                    "SiteId": "63da4653b5c13514ecaeac0f",
                    "EmployeeJobPays": [
                        {
                            "CompensationTypeCode": "HOUR",
                            "Rate": 15.56,
                            "EffectiveDate": "2023-01-01"
                        },
                        {
                            "CompensationTypeCode": "HOUR",
                            "Rate": 18.00,
                            "EffectiveDate": "2023-01-12"
                        }
                    ]
                },
                {
                    "EmployeeJobId": "63da4e01db78faa7f38988da",
                    "EffectiveDate": "2023-01-13",
                    "JobCodeId": "58e63c06fbf17de5ced22074",
                    "ExternalJobCodeId": null,
                    "IsPrimaryJob": true,
                    "Deactivated": false,
                    "DeactivationDate": null,
                    "SiteId": "63da4653b5c13514ecaeac0f",
                    "EmployeeJobPays": [
                        {
                            "CompensationTypeCode": "SLRY",
                            "Rate": 24.0,
                            "EffectiveDate": "2023-01-13"
                        }
                    ]
                }
            ],
            "EmployeeSiteStatuses": [
                {
                    "StatusCode": "ACTV",
                    "SiteIds": [
                        "63df82df32753797d3cfa2e1",
                        "63df82df32753797d3cfa2e2",
                        "63da4653b5c13514ecaeac0f"
                    ]
                },
                {
                    "StatusCode": "IACTV",
                    "SiteIds": [
                        "63df82df32753797d3cfa2e3"
                    ]
                }
            ],
            "PosCredentials": []
        },
        {
            "EmployeeId": "63df82df32753797d3cfa2e0",
            "Firstname": "Patrick",
            "Lastname": "doe",
            "Middlename": null,
            "Name": "Patrick doe",
            "Username": null,
            "EmployeeCorporateCode": "8796277",
            "ExternalEmployeeId": null,
            "PrimarySiteId": "65fae456a881c84356c79d0a",
            "Source": "TestSource",
            "LastUpdateDate": "2024-07-01T11:01:15.910Z",
            "IsActive": true,
            "EmployeeJobs": [
                {
                    "EmployeeJobId": "66828c6d89635e4fb9898023",
                    "EffectiveDate": "2024-05-27",
                    "JobCodeId": "656f79c4e9af7b2ebedb3f72",
                    "ExternalJobCodeId": "9012fn",
                    "IsPrimaryJob": true,
                    "Deactivated": false,
                    "DeactivationDate": null,
                    "SiteId": "63da4653b5c13514ecaeac0f",
                    "EmployeeJobPays": [
                        {
                            "CompensationTypeCode": "HOUR",
                            "Rate": 100.0,
                            "EffectiveDate": "2024-05-27"
                        }
                    ]
                },
                {
                    "EmployeeJobId": "6717a9bb9f3f963c2d6b8ec6",
                    "EffectiveDate": "2024-10-01",
                    "JobCodeId": "58e63c06fbf17de5ced22064",
                    "ExternalJobCodeId": "80801",
                    "IsPrimaryJob": false,
                    "Deactivated": false,
                    "DeactivationDate": null,
                    "SiteId": "65fae456a881c84356c79d0a",
                    "EmployeeJobPays": [
                        {
                            "CompensationTypeCode": "HOUR",
                            "Rate": 7.25,
                            "EffectiveDate": "2024-10-01"
                        }
                    ]
                }
            ],
            "EmployeeSiteStatuses": [
                {
                    "StatusCode": "ACTV",
                    "SiteIds": [
                        "63da4653b5c13514ecaeac0f",
                        "65fae456a881c84356c79d0a"
                    ]
                }
            ],
            "PosCredentials": [
                {
                    "EmployeePOSCode": "16982",
                    "Password": 
"mz+nM5eTpdQVj/+uFeHkkF+Qw1gIfbI+Kiyf1wrWVDbJUe++qPIxSrL7urj8XbYW",
                    "RoleId": "63da469cb5c13514ecaeac10"
                }
            ]
        },
        {
            "EmployeeId": "63df976132753797d3cfa2e7",
            "Firstname": "Mark",
            "Lastname": "doe",
            "Middlename": "Jr",
            "Name": "Mark doe",
            "Username": "mark@mark.mark",
            "EmployeeCorporateCode": "8796280",
            "ExternalEmployeeId": "908012",
            "PrimarySiteId": "63da4653b5c13514ecaeac0f",
            "Source": "Back office System 245",
            "LastUpdateDate": "2025-04-10T09:50:55.993Z",
            "IsActive": true,
            "EmployeeJobs": [],
            "EmployeeSiteStatuses": [
                {
                    "StatusCode": "ACTV",
                    "SiteIds": [
                        "63da4653b5c13514ecaeac0f"
                    ]
                }
            ],
            "PosCredentials": [
                {
                    "EmployeePOSCode": "68096",
                    "Password": 
"DbFof1aDd4KgmPEFQ7fWzJFks9c/RZlB8rR4o7PTUBacahdBcEw1X48htzeOz2mL",
                    "RoleId": "63da469cb5c13514ecaeac10"
                }
            ]
        }
    ],
    "TotalCount": 3616,
    "RecordsReturned": 3,
    "NextPageToken": 
"eyJFbXBsb3llZUlkIjoiNjNjNTI0N2ZmYjIzNzBlZWU1MGZkODg3IiwiRXhwaXJ5IjoxNzU2NDc
1OTY0OTA4MjE0MH0="
}

An example of a fully successful request where the selectNested query parameter was not received.

{
    "Data": [
        {
            "EmployeeId": "63da49d6db78faa7f38988d3",
            "Firstname": "john",
            "Lastname": "doe",
            "Middlename": null,
            "Name": "john doe",
            "Username": null,
            "EmployeeCorporateCode": "8796276",
            "ExternalEmployeeId": null,
            "PrimarySiteId": "63da4653b5c13514ecaeac0f",
            "Source": "TestSource",
            "LastUpdateDate": "2023-02-01T11:18:34.253Z",
            "IsActive": true
        },
        {
            "EmployeeId": "63df82df32753797d3cfa2e0",
            "Firstname": "Patrick",
            "Lastname": "doe",
            "Middlename": null,
            "Name": "Patrick doe",
            "Username": null,
            "EmployeeCorporateCode": "8796277",
            "ExternalEmployeeId": null,
            "PrimarySiteId": "65fae456a881c84356c79d0a",
            "Source": "TestSource",
            "LastUpdateDate": "2024-07-01T11:01:15.910Z",
            "IsActive": true
        },
        {
            "EmployeeId": "63df976132753797d3cfa2e7",
            "Firstname": "Mark",
            "Lastname": "doe",
            "Middlename": "Jr",
            "Name": "Mark doe",
            "Username": "mark@mark.mark",
            "EmployeeCorporateCode": "8796280",
            "ExternalEmployeeId": "908012",
            "PrimarySiteId": "63da4653b5c13514ecaeac0f",
            "Source": "Back office System 245",
            "LastUpdateDate": "2025-04-10T09:50:55.993Z",
            "IsActive": true
        }
    ],
    "TotalCount": 3616,
    "RecordsReturned": 3,
    "NextPageToken": 
"eyJFbXBsb3llZUlkIjoiNjNjNTI0N2ZmYjIzNzBlZWU1MGZkODg3IiwiRXhwaXJ5IjoxNzU2NDc
1OTY0OTA4MjE0MH0="
}

GET /External/General/Employee/GetBy

Summary

This endpoint provides information about all active, non-deleted employees associated with the requested company and, if specified, sites, and is retrieved based on the provided static query filters. The response includes complete employee information and, if requested, additional details such as addresses, site statuses, and other related data.

Note

Use this endpoint to retrieve employee information using secondary identifiers (IDs) that are not Genius unique IDs such as the External Employee ID. This is useful in cases where the system does not store the Genius UID.

However, note that the uniqueness of supported secondary identifiers may vary from client to client. For example, the EmployeeCorporateCode may be unique at the company level or at the site level. Keep this in mind when processing the response or consider using additional headers.

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The token created previously. For information on tokens, see Authentication.
header	`X-COMPANY-ID`	string	Yes	The 24-character hexadecimal unique identifier (UID) for the company provided by Genius
header	`X-SITE-IDs`	array of strings, separated by commas	No	The UID for the site(s) provided by Genius. Multiple site IDs can be provided, separated by commas. For example, 60ace72bacb1540007d34698,60ace72bacb1540007d34697.b If the parameter is provided without a value, it is treated as not provided. In this case, all employees within the specified company that match the query parameters will be returned. Note This parameter is useful when multiple employees share the same attribute such as `EmployeeCorporateCode`. It ensures that only employees belonging to the specified sites are retrieved. For example, if the `EmployeeCorporateCode` uniqueness level is configured at the site level for a client, send this header with the UID of the target site to return only the specific employee from that location, instead of all employees with the same `EmployeeCorporateCode`.
query	`selectNested`	array of strings	No	This parameter specifies which child entities should be included in the response. It can be used to exclude unnecessary data that is not required by integrators. If this parameter is not received, it is ignored. In this case employees are returned without described below child arrays and objects, only general employee data. If non-existent, or non-supported by this endpoint, employee child entities are requested by this parameter, they are ignored and not returned in response. If received, this parameter cannot be `null`, `empty`, or `““`.
query	`ExternalEmployeeId`	string	Yes*	The UID of the employee in an external system. This field is used to link or synchronize employee data across systems. *This parameter is required only if the `EmployeeCorporateCode` and `POSCode` are missing. If received, this parameter cannot be `null`, `empty`, or `““`.
query	`EmployeeCorporateCode`	string	Yes*	The unique, readable identifier assigned to the employee. This field is used for internal identification within the company. *This parameter is required only if the `ExternalEmployeeId` and `POSCode` are missing. If received, this parameter cannot be `null`, `empty`, or `““`.
query	`POSCode`	string	Yes*	The employee’s user ID used as a login on the point of sale (POS). *This parameter is required only if the `ExternalEmployeeId` and `EmployeeCorporateCode` are missing. If received, this parameter cannot be `null`, `empty`, or `““`.

Sample Request Body

curl --location --request GET 'https://qa-backoffice-api.xenial.com/External
/General/Employee/GetBy?ExternalEmployeeId=
90192&EmployeeCorporateCode=3785&selectNested=EmployeeSiteStatuses,EmployeeJobs' \
--header 'X-Company-Id: 63da4601b5c13514ecaeac0a' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InhwcnQifQ...'

Responses

For this response:

The response includes non-deleted employee data only.
If the X-SITE-IDs header is received, the response includes all non-deleted employees found based on the received search filters:
- Have active, non-deleted is_active = true Site Status records with the site_id equals those received in this header.
- Or do not have active, non-deleted, is_active = true Site Status records with the site_id equals those received in this header but whose PrimarySiteId equals those received in this header.
The records in the response are sorted by the EmployeeId ascending (ASC) field.

Code	Description	Schema
200	Message: Success. If no employees are found: { "Data": [], "TotalCount": 0 }	General Structure - GetExternalGeneralEmployeeResponseBody
400	Appears when: One or several parameters from a request failed in validation. Related internal requests to other components fail. Message: Bad Request
401	The token is absent or incorrect. Message: Unauthorized
403	Appears when the received token has not enough permissions to perform this action or the data in the token and headers does not match. Message: Forbidden
500	An error was received during the processing. Message: Internal Server Error

An example of a fully successful request where all child arrays and objects were received in the query parameters.

{
    "Data": [
        {
            "EmployeeId": "63da49d6db78faa7f38988d3",
            "Firstname": "John",
            "Lastname": "Doe",
            "Middlename": null,
            "Name": "John Doe",
            "Username": null,
            "EmployeeCorporateCode": "908972",
            "ExternalEmployeeId": "90",
            "PrimarySiteId": "63da4653b5c13514ecaeac0f",
            "Source": "TestSource",
            "LastUpdateDate": "2023-02-01T11:18:34.253Z",
            "IsActive": true,
            "AdditionalDetails": {
                "TaxIdentifier": null,
                "BadgeNumber": null,
                "EthnicityCode": null,
                "Nickname": null,
                "BirthDate": null,
                "Gender": null,
                "IsHandicapped": false,
                "IsRehireable": false,
                "IsVeteran": false,
                "IsMinor": false
            },
            "EmployeePhones": [
                {
                    "PhoneNumber": "+2-312-312-3123",
                    "PhoneTypeCode": "HOME"
                }
            ],
            "EmployeeAddresses": [
                {
                    "AddressTypeCode": "HOME",
                    "Address1": "Address 1",
                    "Address2": "",
                    "Address3": "",
                    "City": "Pittsburgh",
                    "StateCode": "PA",
                    "PostalCode": "15106",
                    "CountryCode": "US"
                }
            ],
            "EmployeeContacts": [
                {
                    "ContactCode": "johndoe",
                    "Firstname": "John",
                    "Lastname": "Doe",
                    "Middlename": "",
                    "Address1": "Address1",
                    "Address2": "",
                    "Address3": "",
                    "City": "Pittsburgh",
                    "StateCode": "PA",
                    "PostalCode": "15106",
                    "CountryCode": "US",
                    "Phone1": "+0-232-123-1231",
                    "Phone2": ""
                }
            ],
            "EmployeeEmails": [
                {
                    "Email": "jd@jd.com",
                    "EmailTypeCode": "PRSNL"
                }
            ],
            "EmployeeJobs": [
                {
                    "EmployeeJobId": "63da4ba2614bb6862d37a761",
                    "EffectiveDate": "2023-01-01",
                    "JobCodeId": "58e63c06fbf17de5ced22064",
                    "ExternalJobCodeId": "80801",
                    "IsPrimaryJob": true,
                    "Deactivated": false,
                    "DeactivationDate": null,
                    "SiteId": "63da4653b5c13514ecaeac0f",
                    "EmployeeJobPays": [
                        {
                            "CompensationTypeCode": "HOUR",
                            "Rate": 15.56,
                            "EffectiveDate": "2023-01-01"
                        },
                        {
                            "CompensationTypeCode": "HOUR",
                            "Rate": 18.00,
                            "EffectiveDate": "2023-01-12"
                        }
                    ]
                },
                {
                    "EmployeeJobId": "63da4e01db78faa7f38988da",
                    "EffectiveDate": "2023-01-13",
                    "JobCodeId": "58e63c06fbf17de5ced22074",
                    "ExternalJobCodeId": null,
                    "IsPrimaryJob": true,
                    "Deactivated": false,
                    "DeactivationDate": null,
                    "SiteId": "63da4653b5c13514ecaeac0f",
                    "EmployeeJobPays": [
                        {
                            "CompensationTypeCode": "SLRY",
                            "Rate": 24.0,
                            "EffectiveDate": "2023-01-13"
                        }
                    ]
                }
            ],
            "EmployeeSiteStatuses": [
                {
                    "EffectiveDate": "2024-01-01",
                    "StatusCode": "ACTV",
                    "SiteIds": [
                        "63df82df32753797d3cfa2e1",
                        "63df82df32753797d3cfa2e2",
                        "63da4653b5c13514ecaeac0f"
                    ]
                },
                {
                    "EffectiveDate": "2024-01-01",
                    "StatusCode": "IACTV",
                    "SiteIds": [
                        "63df82df32753797d3cfa2e3"
                    ]
                },
                {
                    "EffectiveDate": "2025-01-01",
                    "StatusCode": "IACTV",
                    "SiteIds": [
                        "63df82df32753797d3cfa2e2",
                        "63da4653b5c13514ecaeac0f"
                    ]
                }
            ],
            "PosCredentials": []
        },
        {
            "EmployeeId": "63df82df32753797d3cfa2e0",
            "Firstname": "Patrick",
            "Lastname": "Doe",
            "Middlename": null,
            "Name": "Patrick Doe",
            "Username": null,
            "EmployeeCorporateCode": "908972",
            "ExternalEmployeeId": "90",
            "PrimarySiteId": "65fae456a881c84356c79d0a",
            "Source": "TestSource",
            "LastUpdateDate": "2024-07-01T11:01:15.910",
            "IsActive": true,
            "AdditionalDetails": {
                "TaxIdentifier": null,
                "BadgeNumber": null,
                "EthnicityCode": null,
                "Nickname": null,
                "BirthDate": null,
                "Gender": null,
                "IsHandicapped": false,
                "IsRehireable": false,
                "IsVeteran": false,
                "IsMinor": false
            },
            "EmployeePhones": [],
            "EmployeeAddresses": [],
            "EmployeeContacts": [],
            "EmployeeEmails": [],
            "EmployeeJobs": [
                {
                    "EmployeeJobId": "66828c6d89635e4fb9898023",
                    "EffectiveDate": "2024-05-27",
                    "JobCodeId": "656f79c4e9af7b2ebedb3f72",
                    "ExternalJobCodeId": "9012fn",
                    "IsPrimaryJob": true,
                    "Deactivated": false,
                    "DeactivationDate": null,
                    "SiteId": "63da4653b5c13514ecaeac0f",
                    "EmployeeJobPays": [
                        {
                            "CompensationTypeCode": "HOUR",
                            "Rate": 100.0,
                            "EffectiveDate": "2024-05-27"
                        }
                    ]
                },
                {
                    "EmployeeJobId": "6717a9bb9f3f963c2d6b8ec6",
                    "EffectiveDate": "2024-10-01",
                    "JobCodeId": "58e63c06fbf17de5ced22064",
                    "ExternalJobCodeId": "80801",
                    "IsPrimaryJob": false,
                    "Deactivated": false,
                    "DeactivationDate": null,
                    "SiteId": "65fae456a881c84356c79d0a",
                    "EmployeeJobPays": [
                        {
                            "CompensationTypeCode": "HOUR",
                            "Rate": 7.25,
                            "EffectiveDate": "2024-10-01"
                        }
                    ]
                }
            ],
            "EmployeeSiteStatuses": [
                {
                    "EffectiveDate": "2016-07-14",
                    "StatusCode": "ACTV",
                    "SiteIds": [
                        "63da4653b5c13514ecaeac0f",
                        "65fae456a881c84356c79d0a"
                    ]
                }
            ],
            "PosCredentials": [
                {
                    "EmployeePOSCode": "16982",
                    "Password": 
"mz+nM5eTpdQVj/+uFeHkkF+Qw1gIfbI+Kiyf1wrWVDbJUe++qPIxSrL7urj8XbYW",
                    "RoleId": "63da469cb5c13514ecaeac10"
                }
            ]
        }
    ],
    "TotalCount": 2
}

An example of a fully successful request where only EmployeeJobs, EmployeeSiteStatues, and PosCredentials were received in the selectNested query parameters.

{
    "Data": [
        {
            "EmployeeId": "63da49d6db78faa7f38988d3",
            "Firstname": "John",
            "Lastname": "Doe",
            "Middlename": null,
            "Name": "John Doe",
            "Username": null,
            "EmployeeCorporateCode": "908972",
            "ExternalEmployeeId": "90",
            "PrimarySiteId": "63da4653b5c13514ecaeac0f",
            "Source": "TestSource",
            "LastUpdateDate": "2023-02-01T11:18:34.253Z",
            "IsActive": true,
            "EmployeeJobs": [
                {
                    "EmployeeJobId": "63da4ba2614bb6862d37a761",
                    "EffectiveDate": "2023-01-01",
                    "JobCodeId": "58e63c06fbf17de5ced22064",
                    "ExternalJobCodeId": "80801",
                    "IsPrimaryJob": true,
                    "Deactivated": false,
                    "DeactivationDate": null,
                    "SiteId": "63da4653b5c13514ecaeac0f",
                    "EmployeeJobPays": [
                        {
                            "CompensationTypeCode": "HOUR",
                            "Rate": 15.56,
                            "EffectiveDate": "2023-01-01"
                        },
                        {
                            "CompensationTypeCode": "HOUR",
                            "Rate": 18.00,
                            "EffectiveDate": "2023-01-12"
                        }
                    ]
                },
                {
                    "EmployeeJobId": "63da4e01db78faa7f38988da",
                    "EffectiveDate": "2023-01-13",
                    "JobCodeId": "58e63c06fbf17de5ced22074",
                    "ExternalJobCodeId": null,
                    "IsPrimaryJob": true,
                    "Deactivated": false,
                    "DeactivationDate": null,
                    "SiteId": "63da4653b5c13514ecaeac0f",
                    "EmployeeJobPays": [
                        {
                            "CompensationTypeCode": "SLRY",
                            "Rate": 24.0,
                            "EffectiveDate": "2023-01-13"
                        }
                    ]
                }
            ],
            "EmployeeSiteStatuses": [
                {
                    "EffectiveDate": "2024-01-01",
                    "StatusCode": "ACTV",
                    "SiteIds": [
                        "63df82df32753797d3cfa2e1",
                        "63df82df32753797d3cfa2e2",
                        "63da4653b5c13514ecaeac0f"
                    ]
                },
                {
                    "EffectiveDate": "2024-01-01",
                    "StatusCode": "IACTV",
                    "SiteIds": [
                        "63df82df32753797d3cfa2e3"
                    ]
                },
                {
                    "EffectiveDate": "2025-01-01",
                    "StatusCode": "IACTV",
                    "SiteIds": [
                        "63df82df32753797d3cfa2e2",
                        "63da4653b5c13514ecaeac0f"
                    ]
                }
            ],
            "PosCredentials": []
        },
        {
            "EmployeeId": "63df82df32753797d3cfa2e0",
            "Firstname": "Patrick",
            "Lastname": "Doe",
            "Middlename": null,
            "Name": "Patrick Doe",
            "Username": null,
            "EmployeeCorporateCode": "908972",
            "ExternalEmployeeId": "90",
            "PrimarySiteId": "65fae456a881c84356c79d0a",
            "Source": "TestSource",
            "LastUpdateDate": "2024-07-01T11:01:15.910",
            "IsActive": true,
            "EmployeeJobs": [
                {
                    "EmployeeJobId": "66828c6d89635e4fb9898023",
                    "EffectiveDate": "2024-05-27",
                    "JobCodeId": "656f79c4e9af7b2ebedb3f72",
                    "ExternalJobCodeId": "9012fn",
                    "IsPrimaryJob": true,
                    "Deactivated": false,
                    "DeactivationDate": null,
                    "SiteId": "63da4653b5c13514ecaeac0f",
                    "EmployeeJobPays": [
                        {
                            "CompensationTypeCode": "HOUR",
                            "Rate": 100.0,
                            "EffectiveDate": "2024-05-27"
                        }
                    ]
                },
                {
                    "EmployeeJobId": "6717a9bb9f3f963c2d6b8ec6",
                    "EffectiveDate": "2024-10-01",
                    "JobCodeId": "58e63c06fbf17de5ced22064",
                    "ExternalJobCodeId": "80801",
                    "IsPrimaryJob": false,
                    "Deactivated": false,
                    "DeactivationDate": null,
                    "SiteId": "65fae456a881c84356c79d0a",
                    "EmployeeJobPays": [
                        {
                            "CompensationTypeCode": "HOUR",
                            "Rate": 7.25,
                            "EffectiveDate": "2024-10-01"
                        }
                    ]
                }
            ],
            "EmployeeSiteStatuses": [
                {
                    "EffectiveDate": "2016-07-14",
                    "StatusCode": "ACTV",
                    "SiteIds": [
                        "63da4653b5c13514ecaeac0f",
                        "65fae456a881c84356c79d0a"
                    ]
                }
            ],
            "PosCredentials": [
                {
                    "EmployeePOSCode": "16982",
                    "Password": 
"mz+nM5eTpdQVj/+uFeHkkF+Qw1gIfbI+Kiyf1wrWVDbJUe++qPIxSrL7urj8XbYW",
                    "RoleId": "63da469cb5c13514ecaeac10"
                }
            ]
        }
    ],
    "TotalCount": 2
}

An example of a fully successful request where the selectNested parameter was not received.

{
    "Data": [
        {
            "EmployeeId": "63da49d6db78faa7f38988d3",
            "Firstname": "John",
            "Lastname": "Doe",
            "Middlename": null,
            "Name": "John Doe",
            "Username": null,
            "EmployeeCorporateCode": "908972",
            "ExternalEmployeeId": "90",
            "PrimarySiteId": "63da4653b5c13514ecaeac0f",
            "Source": "TestSource",
            "LastUpdateDate": "2023-02-01T11:18:34.253Z",
            "IsActive": true
        },
        {
            "EmployeeId": "63df82df32753797d3cfa2e0",
            "Firstname": "Patrick",
            "Lastname": "Doe",
            "Middlename": null,
            "Name": "Patrick Doe",
            "Username": null,
            "EmployeeCorporateCode": "908972",
            "ExternalEmployeeId": "90",
            "PrimarySiteId": "65fae456a881c84356c79d0a",
            "Source": "TestSource",
            "LastUpdateDate": "2024-07-01T11:01:15.910Z",
            "IsActive": true
        }
    ],
    "TotalCount": 2
}

GET /External/General/Employee/GetUpdates

Summary

This endpoint returns information about all active and deleted employees associated with the requested company and, if specified, sites. Employees are retrieved based on their last update time, returning all records updated since the provided timestamp. The response includes complete employee information and, if requested, additional details such as addresses, site statuses, and other related data.

This endpoint is particularly useful as it eliminates the need to run scheduled processes for importing all employees. Instead, it allows creating a scheduled process that tracks only the changes made since the last run: only employees updated since the provided timestamp are returned in the response.

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The token created previously. For information on tokens, see Authentication.
header	`X-COMPANY-ID`	string	Yes	The 24-character hexadecimal unique identifier (UID) for the company provided by Genius
header	`X-SITE-IDs`	array of strings, separated by commas	No	The UID for the site(s) provided by Genius. Multiple site IDs can be provided, separated by commas. For example, 60ace72bacb1540007d34698,60ace72bacb1540007d34697.b If the parameter is provided without a value, it is treated as not provided. In this case, all employees within the specified company that match the query parameters will be returned. Note This parameter is useful to retrieve updates related only to employees associated with the requested sites.
query	`selectNested`	array of strings	No	This parameter specifies which child entities should be included in the response. It can be used to exclude unnecessary data that is not required by integrators. If this parameter is not received, it is ignored. In this case employees are returned without described below child arrays and objects, only general employee data. If non-existent, or non-supported by this endpoint, employee child entities are requested by this parameter, they are ignored and not returned in response. If received, this parameter cannot be `null`, `empty`, or `““`.
query	`UpdateDateFrom`	string (UTC date/time with ms)	Yes	This parameter is used to retrieve only those employees that were updated in the database after the specified date/time such as since the last data pull. The comparison is performed across all employee-related entities. If at least one related entity has been created, updated, or deleted, the employee is included in the response, even if the employee record itself remains unchanged. Note Only one date is allowed at a time. `UpdateDateFrom` cannot be older than three (3) calendar months.
query	`UpdateDateTo`	string (UTC date/time with ms)	No	This parameter is used to retrieve only those employees that were updated in the database up to the specified date/time. Note Only one date is allowed at a time. If received, this parameter cannot be null, empty, or ““. The received value should always be greater than `UpdateDateFrom`.

Sample Request Body

curl --location --request GET 'https://qa-backoffice-api.xenial.com/External/General
/Employee/GetUpdates?UpdateDateFrom=2023-08-08T23:50:00.000Z' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsI' \
--header 'Content-Type: application/json' \
--header 'x-company-id: 61fd95804798c50009e08656'

Responses

For this response:

For deleted employees, IsActive: false child arrays and objects are not returned.
For active employees child arrays contain active, non-deleted data only.
The response size is limited. No more than 100 employees can be returned at a time. For pagination needs, the NextUpdateDateFrom field can be used in order not to miss data.
- To request another 100 batch, a value received in the response in the NextUpdateDateFrom field in the first request should be sent in the UpdateDateFrom query parameter in the next request. This approach should be repeated until the Data array is returned empty - this is a marker that all updates have already been provided.
- If for any reason 100th element in response contains the same LastUpdateDate value in the database as the 101th, all employees with this LastUpdateDate value will not be returned in the response of the first request in order not to lose them and allow time to return them in the next request with the NextUpdateDateFrom value returned in response to the first request.
- If no employees were found based on the received time values, the NextUpdateDateFrom field will contain the same timestamp as the one sent in the request in the UpdateDateFrom parameter.
If the X-SITE-IDs header is received, the response includes all non-deleted employees found based on the received search filters:
- Have active, non-deleted is_active = true Site Status records with the site_id equals those received in this header.
- Or do not have active, non-deleted, is_active = true Site Status records with the site_id equals those received in this header but whose PrimarySiteId equals those received in this header.
The records in the response are sorted by the LastUpdateDate ascending (ASC) field.

Code	Description	Schema
200	Message: Success. Where: The `Data` array contains information about all found employees. The `NextUpdateDateFrom` field contains maximum `LastUpdateDate` value from the database for the employees found and sent in response with limitations of no more than 100 elements inside the `Data` array. If no employees were found according to the received query parameters: The `Data` array is returned as `"Data": []`. `NextUpdateDateFrom` = received `UpdateDateFrom`. For example: { "Data": [], "NextUpdateDateFrom": "2023-08-08T23:50:00.000Z" }	General Structure - GetExternalGeneralEmployeeResponseBody
400	Appears when: One or several parameters from a request failed in validation. Related internal requests to other components fail. Message: Bad Request
401	The token is absent or incorrect. Message: Unauthorized
403	Appears when the received token has not enough permissions to perform this action or the data in the token and headers does not match. Message: Forbidden
500	An error was received during the processing. Message: Internal Server Error

An example of a fully successful request where deleted and non-deleted employees with all child arrays and objects were received in the selectNested query parameter.

{
    "Data": [
        {
            "EmployeeId": "63da49d6db78faa7f38988d3",
            "Firstname": "John",
            "Lastname": "Doe",
            "Middlename": null,
            "Name": "John Doe",
            "Username": null,
            "EmployeeCorporateCode": "908972",
            "ExternalEmployeeId": "90",
            "PrimarySiteId": "63da4653b5c13514ecaeac0f",
            "Source": "TestSource",
            "LastUpdateDate": "2023-02-01T11:18:34.253Z",
            "IsActive": true,
            "AdditionalDetails": {
                "TaxIdentifier": null,
                "BadgeNumber": null,
                "EthnicityCode": null,
                "Nickname": null,
                "BirthDate": null,
                "Gender": null,
                "IsHandicapped": false,
                "IsRehireable": false,
                "IsVeteran": false,
                "IsMinor": false
            },
            "EmployeePhones": [
                {
                    "PhoneNumber": "+2-312-312-3123",
                    "PhoneTypeCode": "HOME"
                }
            ],
            "EmployeeAddresses": [
                {
                    "AddressTypeCode": "HOME",
                    "Address1": "Address 1",
                    "Address2": "",
                    "Address3": "",
                    "City": "Pittsburgh",
                    "StateCode": "PA",
                    "PostalCode": "15106",
                    "CountryCode": "US"
                }
            ],
            "EmployeeContacts": [
                {
                    "ContactCode": "johndoe",
                    "Firstname": "John",
                    "Lastname": "Doe",
                    "Middlename": "",
                    "Address1": "Address1",
                    "Address2": "",
                    "Address3": "",
                    "City": "Pittsburgh",
                    "StateCode": "PA",
                    "PostalCode": "15106",
                    "CountryCode": "US",
                    "Phone1": "+0-232-123-1231",
                    "Phone2": ""
                }
            ],
            "EmployeeEmails": [
                {
                    "Email": "jd@jd.com",
                    "EmailTypeCode": "PRSNL"
                }
            ],
            "EmployeeJobs": [
                {
                    "EmployeeJobId": "63da4ba2614bb6862d37a761",
                    "EffectiveDate": "2023-01-01",
                    "JobCodeId": "58e63c06fbf17de5ced22064",
                    "ExternalJobCodeId": "80801",
                    "IsPrimaryJob": true,
                    "Deactivated": false,
                    "DeactivationDate": null,
                    "SiteId": "63da4653b5c13514ecaeac0f",
                    "EmployeeJobPays": [
                        {
                            "CompensationTypeCode": "HOUR",
                            "Rate": 15.56,
                            "EffectiveDate": "2023-01-01"
                        },
                        {
                            "CompensationTypeCode": "HOUR",
                            "Rate": 18.00,
                            "EffectiveDate": "2023-01-12"
                        }
                    ]
                },
                {
                    "EmployeeJobId": "63da4e01db78faa7f38988da",
                    "EffectiveDate": "2023-01-13",
                    "JobCodeId": "58e63c06fbf17de5ced22074",
                    "ExternalJobCodeId": null,
                    "IsPrimaryJob": true,
                    "Deactivated": false,
                    "DeactivationDate": null,
                    "SiteId": "63da4653b5c13514ecaeac0f",
                    "EmployeeJobPays": [
                        {
                            "CompensationTypeCode": "SLRY",
                            "Rate": 24.0,
                            "EffectiveDate": "2023-01-13"
                        }
                    ]
                }
            ],
            "EmployeeSiteStatuses": [
                {
                    "EffectiveDate": "2024-01-01",
                    "StatusCode": "ACTV",
                    "SiteIds": [
                        "63df82df32753797d3cfa2e1",
                        "63df82df32753797d3cfa2e2",
                        "63da4653b5c13514ecaeac0f"
                    ]
                },
                {
                    "EffectiveDate": "2024-01-01",
                    "StatusCode": "IACTV",
                    "SiteIds": [
                        "63df82df32753797d3cfa2e3"
                    ]
                },
                {
                    "EffectiveDate": "2025-01-01",
                    "StatusCode": "IACTV",
                    "SiteIds": [
                        "63df82df32753797d3cfa2e2",
                        "63da4653b5c13514ecaeac0f"
                    ]
                }
            ],
            "PosCredentials": []
        },
        {
            "EmployeeId": "63df82df32753797d3cfa2e0",
            "Firstname": "Patrick",
            "Lastname": "Doe",
            "Middlename": null,
            "Name": "Patrick Doe",
            "Username": null,
            "EmployeeCorporateCode": "8796277",
            "ExternalEmployeeId": null,
            "PrimarySiteId": "65fae456a881c84356c79d0a",
            "Source": "TestSource",
            "LastUpdateDate": "2024-07-01T11:01:15.910Z",
            "IsActive": false
        },
        {
            "EmployeeId": "63df976132753797d3cfa2e7",
            "Firstname": "Mark",
            "Lastname": "Doe",
            "Middlename": "Jr",
            "Name": "Mark Doe",
            "Username": "mark@mark.mark",
            "EmployeeCorporateCode": "8796280",
            "ExternalEmployeeId": "908012",
            "PrimarySiteId": "63da4653b5c13514ecaeac0f",
            "Source": "Back office System 2",
            "LastUpdateDate": "2025-04-10T09:50:55.993Z",
            "IsActive": true,
            "AdditionalDetails": {
                "TaxIdentifier": null,
                "BadgeNumber": "900292",
                "EthnicityCode": null,
                "Nickname": "mark",
                "BirthDate": "2025-10-01",
                "Gender": "M",
                "IsHandicapped": false,
                "IsRehireable": false,
                "IsVeteran": false,
                "IsMinor": false
            },
            "EmployeePhones": [],
            "EmployeeAddresses": [],
            "EmployeeContacts": [],
            "EmployeeEmails": [],
            "EmployeeJobs": [],
            "EmployeeSiteStatuses": [
                {
                    "EffectiveDate": "2016-07-14",
                    "StatusCode": "ACTV",
                    "SiteIds": [
                        "63da4653b5c13514ecaeac0f",
                        "65fae456a881c84356c79d0a"
                    ]
                }
            ],
            "PosCredentials": [
                {
                    "EmployeePOSCode": "68096",
                    "Password": 
"DbFof1aDd4KgmPEFQ7fWzJFks9c/RZlB8rR4o7PTUBacahdBcEw1X48htzeOz2mL",
                    "RoleId": "63da469cb5c13514ecaeac10"
                }
            ]
        }
    ],
    "NextUpdateDateFrom": "2025-04-10T09:50:55.993Z"
}

DELETE /External/General/Employee/[ID]/Address/[CODE]

Summary

This endpoint allows soft-deleting of an existing, non-deleted employee address record identified by the provided AddressTypeCode.

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The token created previously. For information on tokens, see Authentication.
header	`X-COMPANY-ID`	string	Yes	The UID for the company provided by Genius
path	`[ID]`	string	Yes	The `[ID]` is a 24 character hexadecimal UID of the target employee
path	`[CODE]`	string	Yes	The `[CODE]` parameter in the URL must contain one of the supported `AddressTypeCode` values.

Sample Request Body

curl --location --request DELETE 'https://qa-backoffice-api.xenial.com
/External/General/Employee/6835ee484168f481249e8766/Address/HOME' \
--header 'Authorization: Bearer 
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InhwcnQifQ...' \
--header 'Content-Type: application/json' \
--header 'x-company-id: 63da4601b5c13514ecaeac0a'

Responses

Code	Description	Schema
204	Address records with the received code were found for the received employee and successfully deleted. Message: No Content
400	Appears when one or several parameters from headers / URL failed in validation. Message: Bad Request
401	Appears when the token is absent or incorrect, or data in token is different than the one received in headers. Message: Unauthorized
403	Appears when the provided token does not have the required permissions to perform this action within this company. Message: Forbidden
404	Appears when no employees were found within the received company and with the received UID OR no non-deleted address records with the received code were found for the received employee. Message: Not Found
410	Appears when an employee record with the received UID is no longer active/deleted. Message: Gone
500	Appears when an error was received during processing. Message: Internal Server Error

DELETE /External/General/Employee/[ID]/Phone/[CODE]

Summary

This endpoint allows soft-deleting of an existing, non-deleted employee phone record identified by the provided PhoneTypeCode.

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The token created previously. For information on tokens, see Authentication.
header	`X-COMPANY-ID`	string	Yes	The UID for the company provided by Genius
path	`[ID]`	string	Yes	The `[ID]` is a 24 character hexadecimal UID of the target employee
path	`[CODE]`	string	Yes	The `[CODE]` parameter in the URL must contain one of the supported `PhoneTypeCode` values.

Sample Request Body

curl --location --request DELETE 'https://qa-backoffice-api.xenial.com
/External/General/Employee/6835ee484168f481249e8766/Phone/home' \
--header 'Authorization: Bearer 
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InhwcnQifQ...' \
--header 'Content-Type: application/json' \
--header 'x-company-id: 63da4601b5c13514ecaeac0a'

Responses

Code	Description	Schema
204	Phone records with the received code were found for the received employee and successfully deleted. Message: No Content
400	Appears when one or several parameters from headers / URL failed in validation. Message: Bad Request
401	Appears when the token is absent or incorrect, or data in token is different than the one received in headers. Message: Unauthorized
403	Appears when the provided token does not have the required permissions to perform this action within this company. Message: Forbidden
404	Appears when no employees were found within the received company and with the received UID OR no non-deleted phone records with the received code were found for the received employee. Message: Not Found
410	Appears when an employee record with the received UID is no longer active/deleted. Message: Gone
500	Appears when an error was received during processing. Message: Internal Server Error

DELETE /External/General/Employee/[ID]/Email/[CODE]

Summary

This endpoint allows soft-deleting of an existing, non-deleted employee email record identified by the provided EmailTypeCode.

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The token created previously. For information on tokens, see Authentication.
header	`X-COMPANY-ID`	string	Yes	The UID for the company provided by Genius
path	`[ID]`	string	Yes	The `[ID]` is a 24 character hexadecimal UID of the target employee
path	`[CODE]`	string	Yes	The `[CODE]` parameter in the URL must contain one of the supported `EmailTypeCode` values.

Sample Request Body

curl --location --request DELETE 'https://qa-backoffice-api.xenial.com
/External/General/Employee/6835ee484168f481249e8766/Email/PRSNL' \
--header 'Authorization: Bearer 
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InhwcnQifQ...' \
--header 'Content-Type: application/json' \
--header 'x-company-id: 63da4601b5c13514ecaeac0a'

Responses

Code	Description	Schema
204	Email records with the received code were found for the received employee and successfully deleted. Message: No Content
400	Appears when one or several parameters from headers / URL failed in validation. Message: Bad Request
401	Appears when the token is absent or incorrect, or data in token is different than the one received in headers. Message: Unauthorized
403	Appears when the provided token does not have the required permissions to perform this action within this company. Message: Forbidden
404	Appears when no employees were found within the received company and with the received UID OR no non-deleted email records with the received code were found for the received employee. Message: Not Found
410	Appears when an employee record with the received UID is no longer active/deleted. Message: Gone
500	Appears when an error was received during processing. Message: Internal Server Error

DELETE /External/General/Employee/[ID]/Contact/[CODE]

Summary

This endpoint allows soft-deleting of an existing, non-deleted employee contact record identified by the provided ContactCode.

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The token created previously. For information on tokens, see Authentication.
header	`X-COMPANY-ID`	string	Yes	The UID for the company provided by Genius
path	`[ID]`	string	Yes	The `[ID]` is a 24 character hexadecimal UID of the target employee
path	`[CODE]`	string	Yes	The `[CODE]` parameter in the URL must contain one of the supported `ContactCode` values.

Sample Request Body

curl --location --request DELETE 'https://qa-backoffice-api.xenial.com
/External/General/Employee/6835ee484168f481249e8766/Contact/johndoe' \
--header 'Authorization: Bearer 
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InhwcnQifQ...' \
--header 'Content-Type: application/json' \
--header 'x-company-id: 63da4601b5c13514ecaeac0a'

Responses

Code	Description	Schema
204	Contact records with the received code were found for the received employee and successfully deleted. Message: No Content
400	Appears when one or several parameters from headers / URL failed in validation. Message: Bad Request
401	Appears when the token is absent or incorrect, or data in token is different than the one received in headers. Message: Unauthorized
403	Appears when the provided token does not have the required permissions to perform this action within this company. Message: Forbidden
404	Appears when no employees were found within the received company and with the received UID OR no non-deleted contact records with the received code were found for the received employee. Message: Not Found
410	Appears when an employee record with the received UID is no longer active/deleted. Message: Gone
500	Appears when an error was received during processing. Message: Internal Server Error

DELETE /External/General/Employee/[ID]/Job/[ID]

Summary

This endpoint allows soft-deleting of an existing, non-deleted employee job record identified by the provided [ID], together with all its existing non-deleted rates.

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The token created previously. For information on tokens, see Authentication.
header	`X-COMPANY-ID`	string	Yes	The unique identifier (UID) for the company provided by Genius
path	`[ID]`	string	Yes	The `[ID]` is a 24 character hexadecimal UID of the target non-deleted employee whose job should be deleted
path	`[Job/ID]`	string	Yes	The 24 character hexadecimal UID of the target non-deleted job that should be deleted

Sample Request Body

curl --location --request DELETE 'https://qa-backoffice-api.xenial.com
/External/General/Employee/
63da4601b5c13514ecaeac0d/Job/6835ee484168f481249e8766' \
--header 'Authorization: Bearer 
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InhwcnQifQ...' \
--header 'Content-Type: application/json' \
--header 'x-company-id: 63da4601b5c13514ecaeac0a'

Responses

Code	Description	Schema
204	A job record with the received ID was found for the received company and successfully deleted. Message: No Content
400	Appears when one or several parameters from headers / URL failed in validation. Message: Bad Request
401	Appears when the token is absent or incorrect, or data in token is different than the one received in headers. Message: Unauthorized
403	Appears when the provided token does not have the required permissions to perform this action within this company. Message: Forbidden
404	Appears when no employees were found within the received company and with the received UID OR no non-deleted job records were found for the received employee. Message: Not Found
410	Appears when an employee job record or employee record with the received UID is no longer active/deleted. Message: Gone
500	Appears when an error was received during processing. Message: Internal Server Error

DELETE /v2/shifts/[ID]

Summary

This endpoint is used to soft-delete existing, non-deleted schedule’s shifts.

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The token created previously. For information on tokens, see Authentication.
header	`X-COMPANY-ID`	string	Yes	The unique identifier (UID) for the company provided by Genius. Note This operation can only do one company at a time, cannot be null or empty, and the `company_id` in the token should match the value received in this header.
path	`id`	string	Yes	The [ID] in the URL should contain a 24 character hexadecimal UID in our system of a schedule’s shift that should be soft-deleted.

Sample Request Body

curl --location --request DELETE 'https://qa-schedule.xenial.com/v2/shifts
/66d16bba4cacd4f3472174a4' \
--header 'x-company-id: 60ddef56f5b0920007046a72' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [token]'

Responses

Code	Description	Schema
200	The shift’s removal was successful. No content.
400	One or several parameters from a request failed in validation. Message: Bad Request
401	The token is absent or incorrect. Message: Unauthorized
403	The provided token does not have the required permissions to perform this action within this company. Message: Forbidden
404	Appears when received shift is not found or it is no longer active. Message: Not Found
500	An error was received during the processing. Message: Internal Server Error

DELETE /v2/schedules/[ID]

Summary

This endpoint is used to soft-delete existing, non-deleted schedules.

Warning

A schedule removal triggers all its child shifts removal. Deleted schedules are no longer returned in response to GET requests, and the schedules cannot be modified through PUT requests.

Request Parameters

In	Field Name	Type	Required	Description
header	`CONTENT-TYPE`	string	Yes	`application/json`
header	`AUTHORIZATION`	string	Yes	The token created previously. For information on tokens, see Authentication.
header	`X-COMPANY-ID`	string	Yes	The unique identifier (UID) for the company provided by Genius. Note This operation can only do one company at a time, cannot be null or empty, and the `company_id` in the token should match the value received in this header.
path	`id`	string	Yes	The [ID] in the URL should contain a 24 character hexadecimal UID in our system of a schedule that should be soft-deleted.

Sample Request Body

curl --location --request DELETE 'https://qa-schedule.xenial.com/v2/schedules
/66d16bba4cacd4f3472174a4' \
--header 'x-company-id: 60ddef56f5b0920007046a72' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [token]'

Responses

Code	Description	Schema
200	The schedule’s removal was successful. No content.
400	One or several parameters from a request failed in validation. Message: Bad Request
401	The token is absent or incorrect. Message: Unauthorized
403	The provided token does not have the required permissions to perform this action within this company. Message: Forbidden
404	Appears when received shift is not found or it is no longer active. Message: Not Found
500	An error was received during the processing. Message: Internal Server Error

Data Models

PostExternalGeneralEmployeeRequestBody

For this request:

Parameters cannot be received without a value.
All required string fields from the table below cannot be received as ““, null.
If any of the optional array fields from the table below are received, these arrays must contain only valid objects with the required child fields inside.

Field Name	Type	Required	Description
`Firstname`	string	Yes	The employee's first name
`Lastname`	string	Yes	The employee's last name or surname
`Middlename`	string	No	The employee’s middle name or patronymic, if applicable
`Username`	string	No	The employee’s primary email. Using this email, the employee's link to the portal user is performed. Note Several non-deleted employees with the same value in this field within the same company are not allowed.
`EmployeeCorporateCode`	string	No	The unique readable identifier assigned to the employee. Used for internal identification within the company. Letters and numbers are allowed in this field. Multiple employees cannot share the same value in this field. Uniqueness is enforced at two possible levels (the applicable uniqueness level is defined individually for each client): Company level - The value must be unique across the entire company. Site level - The value must be unique within the employee’s primary site and site statuses. If omitted in the request or received as `null`, `““`, it will be generated automatically.
`ExternalEmployeeId`	string	Yes	The unique identifier (UID) of the employee from external system. No restrictions are applied to the value format. Note It is recommended to use unique values for each employee across the entire company.
`PrimarySiteId`	string/HEX24	Yes	The UID of the location at which the employee performs most of their work. It is a Genius generated value that can be found in Genius Portal - Sites section. Note The received site ID should belong to the non-deleted site that belongs to the company, received in the `X-COMPANY-ID` header.
`Source`	string	No	This information is used to determine where the employee record was imported from. No restrictions are applied to the value format.
`AdditionalDetails`	AdditionalDetails Object	No	A list of additional details about an employee that could be useful or important for any need
`EmployeePhones`	EmployeePhones Array	No	This array stores one or more phone numbers associated with the employee. Each item includes the actual phone number and its type, such as mobile, work, and home.
`EmployeeAddresses`	EmployeeAddresses Array	No	This array contains one or more postal addresses associated with the employee. Each item includes the full address details and the address type, such as home and work.
`EmployeeContacts`	EmployeeContacts Array	No	This array contains one or more emergency contacts for the employee. Each item includes personal details and contact information.
`EmployeeEmails`	EmployeeEmails Array	No	This array stores one or more email addresses associated with the employee. Each item includes the actual email address and its type, such as work and home.
`EmployeeSiteStatuses`	EmployeeSiteStatuses Array	No	This array tracks the employee’s status at one or more sites. Each item reflects the employee’s actual activity status starting from the specified date.
`PosCredentials`	PosCredentials Array	No	This array contains login credentials and the assigned role for an employee to access the Genius POS system. Although this field is an array, only a single set of credentials can exist per employee. If multiple records are provided, only the first one will be processed.

AdditionalDetails Object

Field Name	Type	Required	Description
`TaxIdentifier`	string	No	The employee’s tax identification number. Note If this value is received, it should be unique within a company.
`BadgeNumber`	string	No	The unique number assigned to the employee’s access badge. Note If this value is received, it should be unique within a company.
`EthnicityCode`	string	No	The code representing the employee’s ethnicity, configured in Data Management - Ethnicities section. All available codes could be found using the GET /Lookup/Ethnicity endpoint. The `Code` field from the response is the value that should be sent here.
`Nickname`	string	No	The employee’s preferred informal name
`BirthDate`	string/date	No	The employee’s date of birth. Note If this field is received, it should be provided in the YYYY-MM-DD format only.
`Gender`	string	No	The employee’s gender. Note If this field is received, its supported values are: `O` - Declined to answer `F` - Female `M` - Male
`IsHandicapped`	boolean	No	A flag that indicates whether the employee has a disability
`IsRehireable`	boolean	No	A flag that indicates whether the employee is eligible for rehire by the company after the termination of their previous employment
`IsVeteran`	boolean	No	A flag that indicates whether the employee has served in the military
`IsMinor`	boolean	No	A flag that indicates whether the employee is legally considered a minor based on their age

EmployeePhones Array

All required fields listed in the table below cannot be sent as empty ("") or null when this array is included in the request.

Field Name

Type

Required

Description

PhoneNumber

string

Yes

The employee's phone number

PhoneTypeCode

string

Yes

The phone type code for the employee's phone number. Supported values:

Code	Name
`BIZ`	Business phone number
`CELL`	Mobile phone number
`FAX`	Fax phone number
`HOME`	Home phone number

Note

Several phone records with the same PhoneTypeCode for one employee are not allowed.

EmployeeAddresses Array

All required fields listed in the table below cannot be sent as empty ("") or null when this array is included in the request.

Field Name

Type

Required

Description

AddressTypeCode

string

Yes

The address type code for the employee's address. Supported values:

Code	Name
`HOME`	The employee's home address
`MAIL`	The employee's mailing address

Address1

string

Yes

The primary line of the employee’s address, such as street and number

Address2

string

The secondary line of the employee’s address, such as apartment, suite, or unit

Address3

string

An additional line for the employee’s address, such as building, or complex

City

string

The employee's city name

StateCode

string

The code representing the state, province, or region of the employee’s address.

The list of all configured states, including their names and codes, can be retrieved using the GET /Lookup/State endpoint. The Code field from response is the one that should be sent here.

PostalCode

string

The employee's postal code

CountryCode

string

Yes

The code representing the country of the employee’s address.

The list of all configured countries, including their names and codes, can always be retrieved using the GET /Lookup/Country endpoint. The Code field from response is the one that should be sent here.

EmployeeContacts Array

All required fields listed in the table below cannot be sent as empty ("") or null when this array is included in the request.

Field Name	Type	Required	Description
`Firstname`	string	Yes	The first name of the employee's emergency contact. Note Several contact records with the same combination of lowercase concatenation of the contact’s `FirstName` and `LastName` values for one employee are not allowed.
`Lastname`	string	Yes	The last name of the employee’s emergency contact. Note Several contact records with the same combination of lowercase concatenation of the contact’s `FirstName` and `LastName` values for one employee are not allowed.
`Middlename`	string	No	The middle name of the employee’s emergency contact
`Address1`	string	No	The primary line of the employee contact’s address
`Address2`	string	No	The secondary line of the employee contact’s address
`Address3`	string	No	An additional line of the employee contact’s address
`City`	string	No	The city name of the employee contact's address
`StateCode`	string	No	The code representing the state, province, or region of the employee contact’s address. The list of all configured states, including their names and codes, can be retrieved using the GET /Lookup/State endpoint. The `Code` field from response is the one that should be sent here.
`PostalCode`	string	No	The postal code of the employee contact's address
`CountryCode`	string	No	The code representing the country of the employee contact’s address. The list of all configured countries, including their names and codes, can always be retrieved using the GET /Lookup/Country endpoint. The `Code` field from response is the one that should be sent here.
`Phone1`	string	No	The primary phone number of the employee’s emergency contact
`Phone2`	string	No	The secondary phone number of the employee’s emergency contact

EmployeeEmails Array

All required fields listed in the table below cannot be sent as empty ("") or null when this array is included in the request.

Field Name

Type

Required

Description

Email

string

Yes

The employee's email address

EmailTypeCode

string

Yes

The email type code for the employee's email address. Supported values:

Code	Name
`PRSNL`	Personal email
`WORK`	Work email

EmployeeSiteStatuses Array

This array must contain a list of sites where the employee should have a corresponding status code starting from the specified effective date. Each object in the array represents one employee status and its related list of site identifiers (IDs).

All required fields listed in the table below cannot be sent as empty ("") or null when this array is included in the request.
If for any reason several records are received in this array in the request with the same StatusCode AND EffectiveDate, only the first record is processed. Other records are ignored.
If for any reason several records are received in this array in the request with the same StatusCode but different EffectiveDate, only the earliest record is processed. Other records are ignored.

Field Name

Type

Required

Description

EffectiveDate

string/date

Yes

The date when the site status becomes effective.

Note

The received values should be in the YYYY-MM-DD format.

StatusCode

string

Yes

The code representing the employee’s status at a site.

The list of all configured statuses, including their names and codes, can always be retrieved using the GET /Lookup/EmployeeStatus endpoint. The Code field from response is the one that should be sent here.

SiteIds

array of strings [HEX24, …, HEX24]

Yes

A list of site IDs to which this status applies since the EffectiveDate.

All site IDs should belong to the non-deleted sites that belong to the company, which are received in the X-COMPANY-ID header.

PosCredentials Array

All required fields listed in the table below cannot be sent as empty ("") or null when this array is included in the request.

If for any reason several records are received in this array in the request, only the first record is processed. Other records are ignored.

Field Name

Type

Required

Description

EmployeePOSCode

string

Yes

The employee’s log in value, or user identifier (ID), on the point of sale (POS).

Multiple employees cannot share the same value in this field. The applicable uniqueness level is defined individually for each client. Uniqueness is enforced at two possible levels:

Company level - The value must be unique across the entire company.
Site level – The value must be unique within the employee’s primary site and site statuses.

Password

string

Yes

A non-hashed value should be sent here

RoleId

string/HEX24

Yes

The user's role ID.

The received value should have a 24 character hexadecimal string format.

A list of all available roles in Genius Portal can be received using the GET /auth/getCompanyRoles endpoint, The Id field from response is the one that should be sent here.

PostExternalGeneralEmployeeResponseBody

Each child array is returned with all its fields described in the table below if at least one active, non-deleted child record was created successfully for the employee. For example, at least one non-deleted phone record exists in the database for the EmployeePhones array. Otherwise, the corresponding arrays are returned as empty ([]).

Field Name	Type	Required	Description
`EmployeeId`	string/HEX24	Yes	The 24 character hexadecimal string uniquely identifying the employee in the Staff database
`Firstname`	string	Yes	The employee's first name
`Lastname`	string	Yes	The employee's last name or surname
`Middlename`	string	Yes	The employee’s middle name or patronymic, if applicable
`Name`	string	Yes	The concatenated value of `Firstname` and `Lastname`
`Username`	string	Yes	The employee’s primary email.
`EmployeeCorporateCode`	string	Yes	The unique readable identifier assigned to the employee. Used for internal identification within the company.
`ExternalEmployeeId`	string	Yes	The unique identifier (UID) of the employee from external system. Used to link or synchronize employee data across systems.
`PrimarySiteId`	string/HEX24	Yes	The Genius Portal ID of the employee’s main work site
`Source`	string	Yes	Indicates the origin of the employee record
`LastUpdateDate`	string/datetime UTC	Yes	The Coordinated Universal Time (UTC) timestamp when this employee record was last time updated in the database in the YYYY-MM-DDTHH:MM:SS.SSSZ format
`IsActive`	boolean	Yes	A flag indicating whether the employee is deleted. For this endpoint, the value is always `true`.
`AdditionalDetails`	AdditionalDetails Object	No	An optional field for extra information about the employee, such as birth date or tax identifier.
`EmployeePhones`	EmployeePhones Array	No	A list of the employee’s phone numbers
`EmployeeAddresses`	EmployeeAddresses Array	No	A list of the employee’s addresses
`EmployeeContacts`	EmployeeContacts Array	No	A list of the employee’s emergency contacts
`EmployeeEmails`	EmployeeEmails Array	No	A list of the employee’s emails
`EmployeeSiteStatuses`	EmployeeSiteStatuses Array	No	A list of the employee’s statuses at different sites, such as active, inactive, or on leave. Used to track availability and work location assignments.
`PosCredentials`	PosCredentials Array	No	The employee’s access details for the point of sale (POS) system

Sample of the General Structure

{
    "Errors": [
        {
            "Reason": string,
            "Message": string
        }
    ],
    "ProcessedData": {
        "EmployeeId": string,
        "Firstname": string,
        "Lastname": string,
        "Middlename": string,
        "Name": string,
        "Username": string,
        "EmployeeCorporateCode": string,
        "ExternalEmployeeId": string,
        "PrimarySiteId": string,
        "Source": string,
        "LastUpdateDate": string,
        "IsActive": boolean,
        "AdditionalDetails": {
            "TaxIdentifier": string,
            "BadgeNumber": string,
            "EthnicityCode": string,
            "Nickname": string,
            "BirthDate": string,
            "Gender": string,
            "IsHandicapped": boolean,
            "IsRehireable": boolean,
            "IsVeteran": boolean,
            "IsMinor": boolean,
        },
        "EmployeePhones": [
            {
                "PhoneNumber": string,
                "PhoneTypeCode": string,
            }
        ],
        "EmployeeAddresses": [
            {
                "AddressTypeCode": string,
                "Address1": string,
                "Address2": string,
                "Address3": string,
                "City": string,
                "StateCode": string,
                "PostalCode": string,
                "CountryCode": string,
            }
        ],
        "EmployeeContacts": [
            {
                "ContactCode": string,
                "Firstname": string,
                "Lastname": string,
                "Middlename": string,
                "Address1": string,
                "Address2": string,
                "Address3": string,
                "City": string,
                "StateCode": string,
                "PostalCode": string,
                "CountryCode": string,
                "Phone1": string,
                "Phone2": string,
            }
        ],
        "EmployeeEmails": [
            {
                "Email": string,
                "EmailTypeCode": string,
            }
        ],
        "EmployeeSiteStatuses": [
            {
                "EffectiveDate": string,
                "StatusCode": string,
                "SiteIds": []// array of strings
            }
        ],
        "PosCredentials": [
            {
                "EmployeePosCode": string,
                "Password": string,
                "RoleId": string
            }
        ]
    }
}

Sample of a Successful Request

{
    "Errors": [],
    "ProcessedData": {
        "EmployeeId": "63da49d6db78faa7f38988d3",
        "Firstname": "Jack",
        "Lastname": "Doe",
        "Middlename": null,
        "Name": "Jack Doe",
        "Username": null,
        "EmployeeCorporateCode": "8796276",
        "ExternalEmployeeId": "80",
        "PrimarySiteId": "63da4653b5c13514ecaeac0f",
        "Source": "TestSource",
        "LastUpdateDate": "2025-05-01T11:18:34.253",
        "IsActive": true,
        "AdditionalDetails": {
            "TaxIdentifier": null,
            "BadgeNumber": null,
            "EthnicityCode": null,
            "Nickname": null,
            "BirthDate": null,
            "Gender": null,
            "IsHandicapped": false,
            "IsRehireable": false,
            "IsVeteran": false,
            "IsMinor": false
        },
        "EmployeePhones": [
            {
                "PhoneNumber": "+2-312-312-3123",
                "PhoneTypeCode": "HOME"
            }
        ],
        "EmployeeAddresses": [
            {
                "AddressTypeCode": "HOME",
                "Address1": "Address 1",
                "Address2": null,
                "Address3": null,
                "City": "Pittsburgh",
                "StateCode": "PA",
                "PostalCode": "15106",
                "CountryCode": "US"
            }
        ],
        "EmployeeContacts": [
            {
                "ContactCode": "jennydoe",
                "Firstname": "Jenny",
                "Lastname": "Doe",
                "Middlename": null,
                "Address1": "Address1",
                "Address2": null,
                "Address3": null,
                "City": null,
                "StateCode": null,
                "PostalCode": null,
                "CountryCode": "US",
                "Phone1": "+0-232-123-1231",
                "Phone2": null
            }
        ],
        "EmployeeEmails": [
            {
                "Email": "836@com.com",
                "EmailTypeCode": "PRSNL"
            },
            {
                "Email": "837@com.com",
                "EmailTypeCode": "WORK"
            }
        ],
        "EmployeeSiteStatuses": [
            {
                "EffectiveDate": "2025-07-01",
                "StatusCode": "ACTV",
                "SiteIds": [
                    "63df82df32753797d3cfa2e1",
                    "63df82df32753797d3cfa2e2",
                    "63da4653b5c13514ecaeac0f"
                ]
            }
        ],
        "PosCredentials": [
            {
                "EmployeePosCode": "12",
                "Password": 
"1nxYRTFQ50JnHT3qJOM9G9LJaGpnkfO8dmKNAJ4D+Rw4Lgio8E13H3MV/KjNmgcZ",
                "RoleId": "63da469cb5c13514ecaeac10"
            }
        ]
    }
}

Sample of a Response with Errors in Child Arrays

{
    "Errors": [
        {
            "Reason": "InvalidPhoneData.1",
            "Message": "No PhoneType records were found for the 
provided code PERSON. Please check and try again."
        },
        {
            "Reason": "InvalidSiteStatusData.0",
            "Message": "Invalid input data passed to endpoint:  
SiteIds: Unsupported format is received. Supported formats: 
24 digit hexadecimal strings separated by commas"
        }
    ],
    "ProcessedData": {
        "EmployeeId": "63da49d6db78faa7f38988d3",
        "Firstname": "Jack",
        "Lastname": "Doe",
        "Middlename": null,
        "Name": "Jack Doe",
        "Username": null,
        "EmployeeCorporateCode": "8796276",
        "ExternalEmployeeId": "80",
        "PrimarySiteId": "63da4653b5c13514ecaeac0f",
        "Source": "TestSource",
        "LastUpdateDate": "2025-05-01T11:18:34.253",
        "IsActive": true,
        "AdditionalDetails": {
            "TaxIdentifier": null,
            "BadgeNumber": null,
            "EthnicityCode": null,
            "Nickname": null,
            "BirthDate": null,
            "Gender": null,
            "IsHandicapped": false,
            "IsRehireable": false,
            "IsVeteran": false,
            "IsMinor": false
        },
        "EmployeePhones": [],
        "EmployeeAddresses": [
            {
                "AddressTypeCode": "HOME",
                "Address1": "Address 1",
                "Address2": null,
                "Address3": null,
                "City": "Pittsburgh",
                "StateCode": "PA",
                "PostalCode": "15106",
                "CountryCode": "US"
            }
        ],
        "EmployeeContacts": [
            {
                "ContactCode": "jennydoe",
                "Firstname": "Jenny",
                "Lastname": "Doe",
                "Middlename": null,
                "Address1": "Address1",
                "Address2": null,
                "Address3": null,
                "City": null,
                "StateCode": null,
                "PostalCode": null,
                "CountryCode": "US",
                "Phone1": "+0-232-123-1231",
                "Phone2": null
            }
        ],
        "EmployeeEmails": [
            {
                "Email": "836@com.com",
                "EmailTypeCode": "PRSNL"
            }
        ],
        "EmployeeSiteStatuses": [
            {
                "EffectiveDate": "2025-07-01",
                "StatusCode": "ACTV",
                "SiteIds": [
                    "63da4653b5c13514ecaeac0f"
                ]
            }
        ],
        "PosCredentials": [
            {
                "EmployeePosCode": "12",
                "Password": 
"1nxYRTFQ50JnHT3qJOM9G9LJaGpnkfO8dmKNAJ4D+Rw4Lgio8E13H3MV/KjNmgcZ",
                "RoleId": "63da469cb5c13514ecaeac10"
            }
        ]
    }
}

AdditionalDetails Object Response

Field Name	Type	Required	Description
`TaxIdentifier`	string	No	The employee’s tax identification number.
`BadgeNumber`	string	No	The unique number assigned to the employee’s access badge.
`EthnicityCode`	string	No	The code representing the employee’s ethnicity
`Nickname`	string	No	The employee’s preferred informal name
`BirthDate`	string/date	No	The employee’s date of birth in the YYYY-MM-DD format
`Gender`	string	No	The employee’s gender.
`IsHandicapped`	boolean	No	A flag that indicates whether the employee has a disability
`IsRehireable`	boolean	No	A flag that indicates whether the employee is eligible for rehire by the company after the termination of their previous employment
`IsVeteran`	boolean	No	A flag that indicates whether the employee has served in the military
`IsMinor`	boolean	No	A flag that indicates whether the employee is legally considered a minor based on their age

EmployeePhones Array Response

Field Name	Type	Required	Description
`PhoneNumber`	string	No	The employee's phone number
`PhoneTypeCode`	string	No	The phone type code for the employee's phone number

EmployeeAddresses Array Response

Field Name	Type	Required	Description
`AddressTypeCode`	string	No	The address type code for the employee's address
`Address1`	string	No	The primary line of the employee’s address, such as street and number
`Address2`	string	No	The secondary line of the employee’s address, such as apartment, suite, or unit
`Address3`	string	No	An additional line for the employee’s address, such as building, or complex
`City`	string	No	The employee's city name
`StateCode`	string	No	The code representing the state, province, or region of the employee’s address
`PostalCode`	string	No	The employee's postal code
`CountryCode`	string	No	The code representing the country of the employee’s address

EmployeeContacts Array Response

Field Name	Type	Required	Description
`Firstname`	string	No	The first name of the employee's emergency contact
`Lastname`	string	No	The last name of the employee’s emergency contact
`Middlename`	string	No	The middle name of the employee’s emergency contact
`Address1`	string	No	The primary line of the employee contact’s address
`Address2`	string	No	The secondary line of the employee contact’s address
`Address3`	string	No	An additional line of the employee contact’s address
`City`	string	No	The city name of the employee contact's address
`StateCode`	string	No	The code representing the state, province, or region of the employee contact’s address
`PostalCode`	string	No	The postal code of the employee contact's address
`CountryCode`	string	No	The code representing the country of the employee contact’s address
`Phone1`	string	No	The primary phone number of the employee’s emergency contact
`Phone2`	string	No	The secondary phone number of the employee’s emergency contact

EmployeeEmails Array Response

Field Name	Type	Required	Description
`Email`	string	No	The employee's email address
`EmailTypeCode`	string	No	The email type code for the employee's email address

EmployeeSiteStatuses Array Response

Field Name	Type	Required	Description
`EffectiveDate`	string/date	No	The date when the site status becomes effective in the YYYY-MM-DD format
`StatusCode`	string	No	The code representing the employee’s status at a site
`SiteIds`	array of strings [HEX24, …, HEX24]	No	A list of site IDs to which this status applies since the `EffectiveDate`

PosCredentials Array Response

Field Name	Type	Required	Description
`EmployeePOSCode`	string	No	The employee’s log in value, or user identifier (ID), on the point of sale (POS)
`Password`	string	No	The password for the employee’s POS account, returned as hash
`RoleId`	string/HEX24	No	The Genius Portal unique identifier (UID) for the role assigned to the employee. A role defines a set of functions available to the employee during their work with POS

PostExternalGeneralEmployeeIDJobsRequestBody

For this request:

Parameters cannot be received without a value.
All non-arrays fields from the table below cannot be received as ““, null, except in the cases described in the table below.
All array fields from the table below cannot be received as null, [], or “", and these arrays must contain only valid objects with the required child fields inside.
Invalid jobs do not block valid records from creation.

Field Name

Type

Required

Description

JobCodeId

string/HEX24

Yes*

The Data Management entity_id of the job code to be associated with this employee’s job. Used to link the employee’s job to the corresponding job definition.

Send a GET request to the /Staff/JobCode endpoint to retrieve a list of available Job Code records from Data Management.

*This parameter is required if the ExternalJobCodeId parameter is not received. Only one parameter must be sent at a time, either JobCodeId or ExternalJobCodeId.

The null value is considered is absent field.

If received, the value should have a 24 character hexadecimal string format.

Several active, non-deleted jobs with the same combination of JobCodeId + SiteId are not allowed.

ExternalJobCodeId

string

Yes*

The Data Management external_id of the job code to associate with this employee’s job. This field is typically used for mapping with external systems.

*This parameter is required if the JobCodeId parameter is not received. Only one parameter must be sent at a time, either JobCodeId or ExternalJobCodeId.

The null value is considered is absent field.

Several active, non-deleted jobs with the same combination of JobCodeId (identified based on the provided ExternalJobCodeId) + SiteId are not allowed.

IsPrimaryJob

boolean

Yes

A flag that indicates whether this job is the employee’s primary position.

Several job records with the IsPrimaryJob = true flag for the same SiteId are not allowed.

CompensationTypeCode

string

Yes

The code indicating the type of compensation applied for this job.

Code	Name
`SLRY`	Salary
`HOUR`	Hourly

Note

Having job pay records with different Compensation Type Codes for the same job record is not allowed.

SiteIds

array of strings

[HEX24, ..., HEX24]

Yes

The Genius Portal unique identifier (UID) of the sites where the job is assigned.

For every valid site from this array, a single job record is created with the corresponding job pay records received.

Received values should have a 24 character hexadecimal string format and only comma separator can be used.

Creating employee jobs for sites where their parent employees do not have non-deleted Site Status records, regardless of the status itself, is not allowed.

Warning

Even if the array contains site records that pass validation individually, no job records will be created unless all received site IDs pass the validation successfully. The job creation process is initiated only after full validation of the entire array.

EmployeeJobPays

EmployeeJobPays Array

Yes

A list of pay details associated with this job position, such as salary or hourly rate

EmployeeJobPays Array

For this array:

Parameters cannot be received without a value, “", or null.
Errors in one job pay record block other job pay records AND the whole job record from processing.

Field Name	Type	Required	Description
`EffectiveDate`	string/date	Yes	The date when this compensation rate becomes effective in YYYY-MM-DD format. Note Several job pay records with the same `EffectiveDate` are not allowed.
`Rate`	number/decimal (2)	Yes	The amount or rate of pay associated with the compensation type. Note Negative values are not allowed.

PostExternalGeneralEmployeeIDJobsResponseBody

Field Name	Type	Required	Description
`EmployeeJobId`	string/HEX24	Yes	The 24 character hexadecimal string uniquely identifying the employee job in the Staff database. Used for further updates, if required.
`EffectiveDate`	string/date	Yes	The date when the job assignment at the specified site becomes effective. It correlates with the Business Date on point of sale (POS) in the YYYY-MM-DD format. The earliest Effective Date from the list of provided Job Pay records.
`JobCodeId`	string/HEX24	Yes	The 24 character hexadecimal string uniquely identifying the job position, configured in Data Management. The field received in the request or identified based on the provided `ExternalJobCodeId`.
`ExternalJobCodeId`	string	Yes	The unique identifier (UID) of the job position, used for integration and data synchronization. The field received in the request or identified based on the provided `JobCodeId` or `null` if not configured for the provided `JobCodeId`.
`IsPrimaryJob`	boolean	Yes	A flag that indicates whether this job is the employee’s primary position
`Deactivated`	boolean	Yes	The value is always `false` for this endpoint. A flag that indicates whether the job position is no longer available for an employee.
`DeactivationDate`	string/date	Yes	The date when the job position was deactivated in YYYY-MM-DD format. The value is always `null` for this endpoint.
`SiteId`	string/HEX24	Yes	The Genius Portal UID of the site where the job is assigned
`LastUpdateDate`	string/datetime UTC	Yes	The Coordinated Universal Time (UTC) timestamp when this employee job record was created in the database in YYYY-MM-DDTHH:MM:SS.SSSZ format
`IsActive`	boolean	Yes	A flag that indicates whether a job record is deleted. The value is always `true` for this endpoint.
`EmployeeJobPays`	EmployeeJobPays Array	Yes	A list of pay details associated with this job position, such as salary or hourly rate

Sample of General Structure

{
    "Errors": [
        {
            "Reason": string,
            "Message": string
        }
    ],
    "ProcessedData": [
        {
            "EmployeeJobId": string,
            "EffectiveDate": string,
            "JobCodeId": string,
            "ExternalJobCodeId": string,
            "IsPrimaryJob": boolean,
            "Deactivated": boolean,
            "DeactivationDate": string,
            "SiteId": string,
            "LastUpdateDate": string,
            "IsActive": boolean,
            "EmployeeJobPays": [
                {
                    "CompensationTypeCode": string,
                    "EffectiveDate": string,
                    "Rate": decimal
                }
            ]
        }
    ]
}

Sample of Fully Successful Request

{
    "Errors": [],
    "ProcessedData": [
        {
            "EmployeeJobId": "63da4ba2614bb6862d37a761",
            "EffectiveDate": "2024-01-01",
            "JobCodeId": "58e63c06fbf17de5ced22064",
            "ExternalJobCodeId": "80801",
            "IsPrimaryJob": true,
            "Deactivated": false,
            "DeactivationDate": null,
            "SiteId": "63da4653b5c13514ecaeac0f",
            "LastUpdateDate": "2025-05-01T11:18:34.253",
            "IsActive": true,
            "EmployeeJobPays": [
                {
                    "EffectiveDate": "2025-01-01",
                    "CompensationTypeCode": "HOUR",
                    "Rate": 15.56
                },
                {
                    "EffectiveDate": "2024-01-01",
                    "CompensationTypeCode": "HOUR",
                    "Rate": 14
                }
            ]
        },
        {
            "EmployeeJobId": "63da4ba2614bb6862d37a762",
            "EffectiveDate": "2024-01-01",
            "JobCodeId": "58e63c06fbf17de5ced22064",
            "ExternalJobCodeId": "80801",
            "IsPrimaryJob": true,
            "Deactivated": false,
            "DeactivationDate": null,
            "SiteId": "65fae456a881c84356c79d0a",
            "LastUpdateDate": "2025-05-01T11:18:34.253",
            "IsActive": true,
            "EmployeeJobPays": [
                {
                    "EffectiveDate": "2025-01-01",
                    "CompensationTypeCode": "HOUR",
                    "Rate": 15.56
                },
                {
                    "EffectiveDate": "2024-01-01",
                    "CompensationTypeCode": "HOUR",
                    "Rate": 14
                }
            ]
        },
        {
            "EmployeeJobId": "63da4ba2614bb6862d37a763",
            "EffectiveDate": "2024-01-01",
            "JobCodeId": "58e63c06fbf17de5ced22064",
            "ExternalJobCodeId": "80801",
            "IsPrimaryJob": true,
            "Deactivated": false,
            "DeactivationDate": null,
            "SiteId": "64c228f421a5403fe5773bbf",
            "LastUpdateDate": "2025-05-01T11:18:34.253",
            "IsActive": true,
            "EmployeeJobPays": [
                {
                    "EffectiveDate": "2025-01-01",
                    "CompensationTypeCode": "HOUR",
                    "Rate": 15.56
                },
                {
                    "EffectiveDate": "2024-01-01",
                    "CompensationTypeCode": "HOUR",
                    "Rate": 14
                }
            ]
        },
        {
            "EmployeeJobId": "63da4ba2614bb6862d37a764",
            "EffectiveDate": "2024-01-01",
            "JobCodeId": "58e63c06fbf17de5ced22064",
            "ExternalJobCodeId": "80801",
            "IsPrimaryJob": true,
            "Deactivated": false,
            "DeactivationDate": null,
            "SiteId": "67eb8df9f6ebe838aec61fd6",
            "LastUpdateDate": "2025-05-01T11:18:34.253",
            "IsActive": true,
            "EmployeeJobPays": [
                {
                    "EffectiveDate": "2025-01-01",
                    "CompensationTypeCode": "HOUR",
                    "Rate": 15.56
                },
                {
                    "EffectiveDate": "2024-01-01",
                    "CompensationTypeCode": "HOUR",
                    "Rate": 14
                }
            ]
        },
        {
            "EmployeeJobId": "63da4ba2614bb6862d37a765",
            "EffectiveDate": "2023-01-01",
            "JobCodeId": "58e63c06fbf17de5ced22074",
            "ExternalJobCodeId": "9087",
            "IsPrimaryJob": false,
            "Deactivated": false,
            "DeactivationDate": null,
            "SiteId": "63da4653b5c13514ecaeac0f",
            "LastUpdateDate": "2025-05-01T11:18:34.253",
            "IsActive": true,
            "EmployeeJobPays": [
                {
                    "EffectiveDate": "2026-01-01",
                    "CompensationTypeCode": "SLRY",
                    "Rate": 20000
                }
            ]
        },
        {
            "EmployeeJobId": "63da4ba2614bb6862d37a766",
            "EffectiveDate": "2023-01-01",
            "JobCodeId": "58e63c06fbf17de5ced22074",
            "ExternalJobCodeId": "9087",
            "IsPrimaryJob": false,
            "Deactivated": false,
            "DeactivationDate": null,
            "SiteId": "65fae456a881c84356c79d0a",
            "LastUpdateDate": "2025-05-01T11:18:34.253",
            "IsActive": true,
            "EmployeeJobPays": [
                {
                    "EffectiveDate": "2026-01-01",
                    "CompensationTypeCode": "SLRY",
                    "Rate": 20000
                }
            ]
        }
    ]
}

Sample of a Response with Errors in Child Arrays

{
    "Errors": [
        {
            "Reason": "InvalidJobData.0",
            "Message": "No active employee site status records found 
for the following site(s): 
67eb8df9f6ebe838aec61fd7,65fae456a881c84356c79d0a. A job cannot be 
created for these site(s)."
        },
        {
            "Reason": "InvalidJobData.2",
            "Message": "No CompensationTypeCode records were found 
for the provided code SALARY. Please check and try again."
        }
    ],
    "ProcessedData": [
        {
            "EmployeeJobId": "63da4ba2614bb6862d37a765",
            "EffectiveDate": "2023-01-01",
            "JobCodeId": "58e63c06fbf17de5ced22074",
            "ExternalJobCodeId": "9087",
            "IsPrimaryJob": false,
            "Deactivated": false,
            "DeactivationDate": null,
            "SiteId": "63da4653b5c13514ecaeac0f",
            "LastUpdateDate": "2025-05-01T12:18:34.253",
            "IsActive": true,
            "EmployeeJobPays": [
                {
                    "EffectiveDate": "2023-01-01",
                    "CompensationTypeCode": "SLRY",
                    "Rate": 20000
                },
                {
                    "EffectiveDate": "2026-01-01",
                    "CompensationTypeCode": "SLRY",
                    "Rate": 20000
                }
            ]
        }
    ]
}

EmployeeJobPays Array Response

Field Name	Type	Required	Description
`CompensationTypeCode`	string	No	The code indicating the type of compensation applied for this job
`EffectiveDate`	string/date	No	The date when this compensation rate becomes effective in YYYY-MM-DD format
`Rate`	number/decimal (2)	No	The amount or rate of pay associated with the compensation type

PostExternalGeneralShiftRequestBody

For this request body:

Only one shift can be created at a time.
A shift can be created only for non-deleted employees and employee jobs.
All other parameters sent outside of the list provided below are ignored during the shift processing without errors.
All datetime values should be provided in Coordinated Universal Time (UTC).

Field Name	Type	Required	Description
`EmployeeId`	string	Yes*	The Staff API employee unique identifier (UID) in our system. Only one of these parameters can be sent at a time: `EmployeeId`, `EmployeeCorporateCode`, or `ExternalEmployeeId`. If this parameter is received, the received value should have a 24 character hexadecimal string format. *This parameter is required if neither `EmployeeCorporateCode` nor `ExternalEmployeeId` parameters are received.
`EmployeeCorporateCode`	string	Yes*	The Staff API readable identifier of the employee that should be associated with this shift. This value can be either automatically generated by Staff API or received from external systems. Only one of these parameters can be sent at a time: `EmployeeId`, `EmployeeCorporateCode`, or `ExternalEmployeeId`. If this parameter is received, it cannot be null, empty, or ““ . *This parameter is required if neither `EmployeeId` nor `ExternalEmployeeId` parameters are received.
`ExternalEmployeeId`	string	Yes*	The external identifier of the employee, which is not generated by our system. An identifier from external systems that can be used as a link and that should be associated with this shift. Only one of these parameters can be sent at a time: `EmployeeId`, `EmployeeCorporateCode`, or `ExternalEmployeeId`. If this parameter is received, it cannot be null, empty, or ““ . *This parameter is required if neither `EmployeeCorporateCode` nor `EmployeeId` parameters are received.
`JobCodeId`	string	Yes*	The Data Management `entity_id` of the job code that should be associated with this shift. A list of all Job Codes can be received using the GET /Staff/JobCode endpoint. The `JobCodeId` field is the one that stores UIDs that should be sent in this field. Only one of these parameters can be sent at a time: `JobCodeId` or `ExternalJobCodeId`. If this parameter is received, the received value should have a 24 character hexadecimal string format. *This parameter is required if the `ExternalJobCodeId` parameter is not received.
`ExternalJobCodeId`	string	Yes*	The Data Management `external_id` of the job code that should be associated with this shift. This parameter is taken from either the Job Code Rate record, or if missing, from the Job Code. To verify that job codes with the target external ID exist in our system, the GET /Staff/JobCode endpoint can be used. Only one of these parameters can be sent at a time: `JobCodeId` or `ExternalJobCodeId`. If this parameter is received, it cannot be null, empty, or ““ . *This parameter is required if the `JobCodeId` parameter is not received.
`StartDateTime`	string	Yes	The shift’s start date and time. This parameter cannot be null, empty, or ““, and must be in the YYYY-MM-DDTHH:MM:SSZ format.
`EndDateTime`	string	No	The shift's end date and time. This parameter can be null for open shifts, but cannot be empty or ““, and must be in the YYYY-MM-DDTHH:MM:SSZ format.
`Source`	string	Yes	The name of the source system from which this shift is sent. This parameter can be null, empty, or ““.
`ActualUpdateDate`	string	Yes	The timestamp of when the shift is sent from the external system. This parameter cannot be null, empty, or ““, and must be in the YYYY-MM-DDTHH:MM:SS.SSSZ format.
`Breaks`	array of objects	Yes	This array can be empty when a shift has no breaks - `Breaks: []`, but this array should always be present in a request and cannot be null, empty, or ““. Several open breaks with `"BreakEndDateTime": null` are not allowed. Break overlaps are not allowed. Breaks cannot overlap or stay outside of the shift's boundaries.
`Breaks.BreakStartDateTime`	string	Yes*	The break’s start date and time. If received, this parameter cannot be null, empty, or ““, and must be in the YYYY-MM-DDTHH:MM:SSZ format. *This parameter can be absent in the request if there are no breaks for the shift. Otherwise, this field is required.
`Breaks.BreakEndDateTime`	string	No	The break’s end date and time. This parameter can be absent in the request if there are no breaks for the shift or for open breaks. If received, this parameter cannot be null, empty, or ““, and must be in the YYYY-MM-DDTHH:MM:SSZ format.
`Breaks.BreakTypeCode`	string	Yes*	The code of the break’s type based on the Break Time section configuration in Data Management. If received, this parameter cannot be null, empty, or ““, and its only supported values are `MEAL` , `REST`, and `UNKNOWN`. `UNKNOWN` is for those cases when break type is not required for external system. *This parameter can be absent in the request if there are no breaks for the shift. Otherwise, this field is required.
`Breaks.IsPaidBreak`	boolean	Yes*	A flag that shows whether a break is a paid one or not based on the Break Time section configuration in Data Management. If received, this parameter cannot be null, empty, or ““, and its only supported values are `true` and `false`. This parameter can be absent in the request if there are no breaks for the shift. Otherwise, this field is required. Note If for any reason the Break Time* section in Data Management contains no records with the received Break Type and `IsPaidBreak` value, a shift is created and in response such break is returned with the `UNKNOWN` break type. A shift can be updated using the PUT /External/General/Shift/[ID] endpoint with the same break information after a valid Break Time configuration is created in Data Management.
`Tips`	array	Yes	This array can be sent as `Tips: []` when a shift has no tips received by an employee, but this array must always be present in the request and cannot be null, empty string, or empty. Several records with the same combination of received values are combined into one during the processing. Their amounts are summed up. Note If no configuration is found in Data Management for the received combinations of `TenderCategoryCode` , `TenderTypeCode`, and `TenderCurrencyCode values`, or invalid values are received in this array, such tip records are not created in the database, but they do not block a shift from creation and a result response, if no other errors are received, will be 200 OK, but with the `Errors` array containing information about those tips records for which processing failed and they were not created in the database. If tips are not created due to the missing Tender Mapping configuration in Data Management, after the configuration is created, then such shifts can be updated with the same set of transactions using the PUT /External/General/Shift/[ID] endpoint, and the transactions are created if a valid Tender Mapping record is found.
`Tips.TenderCategoryCode`	string	Yes*	The code of the tips transaction type, `Indirect` or `Direct` tips, based on the Tender Mapping section configuration in Data Management. If received, this parameter cannot be null, empty, or ““, and its only supported values are `DTIP` and `IDTIP`. *This parameter can be absent in the request if there are no tips for the shift. Otherwise, this field is required.
`Tips.TenderTypeCode`	string	Yes*	The code of the tips payment type configured in the Pay Type section in Data Management. The codes of the related payment classes should be sent here. A list of all payment types, configured in our system, can be received using the GET /Lookup/TenderType endpoint. The `Code` field stores the values that should be sent in this field. If received, this parameter cannot be null, empty, or ““. *This parameter can be absent in the request if there are no tips for the shift. Otherwise, this field is required.
`Tips.TenderCurrencyCode`	string	Yes*	The code of the tips currency configured in the Tender Currency section in Data Management. The codes should be sent here. The list of all tender currencies, configured in our system, can be received using the GET /Lookup/TenderCurrency endpoint. The `Code` field stores the values that should be sent in this field. If received, this parameter cannot be null, empty, or ““. *This parameter can be absent in the request if there are no tips for the shift. Otherwise, this field is required.
`Tips.Amount`	number/decimal	Yes*	The tips amount. If received, this parameter cannot be null, empty, or ““, and negative values are not allowed. *This parameter can be absent in the request if there are no tips for the shift. Otherwise, this field is required.
`Sales`	array of objects	Yes	This array can be sent as `Sales: []` when a shift has no sales data received for an employee, but this array must always be present in the request and cannot be null, empty string, or empty. Several records with the same combination of received values are combined into one during the processing. Their amounts are summed up. Note If no configuration is found in Data Management for the received combinations of `TenderTypeCode`, and `TenderCurrencyCode values`, or invalid values are received in this array, such sales records are not created in the database, but they do not block a shift from creation and a result response, if no other errors are received, will be 200 OK, but with the `Errors` array containing information about those sales records for which processing failed and they were not created in the database. If sales records are not created due to the missing Tender Mapping configuration in Data Management, after the configuration is created, then such shifts can be updated with the same set of transactions using the PUT /External/General/Shift/[ID] endpoint, and the transactions are created if a valid Tender Mapping record is found.
`Sales.TenderTypeCode`	string	Yes*	The code of the sales payment type configured in the Pay Type section in Data Management. Codes of the related payment classes should be sent here. The value logic is the same as described in the Tips.TenderTypeCode. If received, this parameter cannot be null, empty, or ““. *This parameter can be absent in the request if there is no sales data for the shift.
`Sales.TenderCurrencyCode`	string	Yes*	The code of the sales currency configured in the Tender Currency section in Data Management. The codes should be sent here. The value logic is the same as described in the Tips.TenderCurrencyCode. If received, this parameter cannot be null, empty, or ““. *This parameter can be absent in the request if there is no sales data for the shift.
`Sales.Amount`	number/decimal	Yes*	The sales amount. If received, this parameter cannot be null, empty, or ““. *This parameter can be absent in the request if there is no sales data for the shift.

PostExternalGeneralShiftResponseBody

Since source sites can have the Automatic Punches Split preference enabled, in the result of a POST request, not one but several shifts can be created if a received shift crosses several business dates. All these shifts are returned in the response.

Field Name	Type	Required	Description
`Errors`	array	Yes	This array contains a list of errors encountered while processing the shift’s child entities. These errors did not block the creation of the shift but prevent the creation of the invalid records.
`Errors.Reason`	string	Yes	The reason the error occurred
`Errors.Message`	string	Yes	The error message
`ProcessedData`	array	Yes	This array of objects contains all shift data that was created successfully in the database based on the details provided in the request
`ProcessedData.ShiftId`	string	Yes	The Staff API unique identifier (UID) for the shift that is being created
`ProcessedData.EmployeeId`	string	Yes	The Staff API UID for the employee related to the created shift
`ProcessedData.EmployeeCorporateCode`	string	Yes	The readable identifier for the employee related to the returned shift. This is the value stored in the Employee Corporate Code field in the employee profile in Staff API.
`ProcessedData.ExternalEmployeeId`	string	Yes	The external identifier for the employee related to the created shift, received from external systems or null
`ProcessedData.JobName`	string	Yes	The name of the job code from Data Management from the active employee job related to the created shift
`ProcessedData.JobCodeId`	string	Yes	The `entity_id` of the job code record from Data Management from the active employee job related to the created shift
`ProcessedData.ExternalJobCodeId`	string	Yes	The Data Management `external_id` of the job code rate or job code from the employee job associated with this shift
`ProcessedData.StartDateTime`	string	Yes	The shift’s start date time returned in the YYYY-MM-DDTHH:MM:SSZ Coordinated Universal Time (UTC) format
`ProcessedData.EndDateTime`	string	Yes	The shift’s end date time returned in the YYYY-MM-DDTHH:MM:SSZ UTC format or null if this shift is open
`ProcessedData.Status`	string	Yes	The shift's status in the database: `CLOCKED_IN`: The employee is not on a break and currently actively working. `ON_BREAK`: The employee is currently on a break. `CLOCKED_OUT`: A shift is closed.
`ProcessedData.IsActive`	boolean	Yes	A flag that shows that this shift is non-deleted. Always = `true`.
`ProcessedData.SiteId`	string	Yes	The UID in our system of a site associated with the currently created shift
`ProcessedData.Source`	string	Yes	The name of the source system from which this shift was imported or null if a shift was created in Staff API or was imported without external system specified
`ProcessedData.ActualUpdateDate`	string	Yes	The last time the current shift was created or updated through the API call in the YYYY-MM-DDTHH:MM:SS.SSSZ UTC format
`ProcessedData.Breaks`	array of objects	Yes	Each break is displayed as a separate object inside this array. If there are no breaks within the currently created shift, this array is returned as `Breaks:[]`.
`ProcessedData.Breaks.BreakStartDateTime`	string	Yes*	The break’s start date time returned in the YYYY-MM-DDTHH:MM:SSZ UTC format. *Absent only when there are no breaks for a shift.
`ProcessedData.Breaks.BreakEndDateTime`	string	Yes*	The break’s end date time returned in the YYYY-MM-DDTHH:MM:SSZ UTC format or null if this break is open. *Absent only when there are no breaks for a shift.
`ProcessedData.Breaks.BreakTypeCode`	string	Yes*	Break Type Code from the Break Time configuration in Data Management. `MEAL`, `REST`, `UNKNOWN`. `UNKNOWN` for cases when no configuration for the received `BreakTypeCode` and `IsPaidBreak` was found. *Absent only when there are no breaks for a shift.
`ProcessedData.Breaks.IsPaidBreak`	boolean	Yes*	A flag showing whether the received break is paid or not. Taken from the found Break Time configuration in Data Management or taken from a default record for cases when no configuration for the received `BreakTypeCode` and `IsPaidBreak` was found. *Absent only when there are no breaks for a shift.
`ProcessedData.Tips`	array of objects	Yes	A list of unique tip records received for the currently created shift that was successfully created in the database, aggregated by `TenderCategoryCode`, `TenderTypeCode`, and `TenderCurrencyCode`. If a result shift has no tip transactions created, this array is returned as `"Tips": [].`
`ProcessedData.Tips.TenderCategoryCode`	string	Yes*	The identifier of the tip type - Direct (`DTIP`) or Indirect (`IDTIP`). *Absent only when there are no tips for a shift.
`ProcessedData.Tips.TenderTypeCode`	string	Yes*	The code of the payment class associated with a tip record that was created. *Absent only when there are no tips for a shift.
`ProcessedData.Tips.TenderCurrencyCode`	string	Yes*	The code of the tender currency associated with a tip record that was created. *Absent only when there are no tips for a shift.
`ProcessedData.Tips.Amount`	number/decimal	Yes*	The total tips amount for this particular tender type. *Absent only when there are no tips for a shift.
`ProcessedData.Sales`	array of objects	Yes	A list of unique sales records received for the currently created shift that was successfully created in the database, aggregated by `TenderTypeCode` and `TenderCurrencyCode`. If a result shift has no sales transactions created, this array is returned as `"Sales": []`.
`ProcessedData.Sales.TenderTypeCode`	string	Yes*	The code of the payment class associated with a sales record that was created. *Absent only when there are no sales for a shift.
`ProcessedData.Sales.TenderCurrencyCode`	string	Yes*	The code of the tender currency associated with a sales record that was created. *Absent only when there are no sales for a shift.
`ProcessedData.Sales.Amount`	number/decimal	Yes*	The total sales amount for this particular tender type. *Absent only when there are no sales for a shift.

General Structure Sample Body

{
    "Errors": [
        {
            "Reason": string,
            "Message": string
        }
    ],
    "ProcessedData": [
        {
            "ShiftId": string,
            "EmployeeId": string,
            "EmployeeCorporateCode": string,
            "ExternalEmployeeId": string,
            "JobName": string,
            "JobCodeId": string,
            "ExternalJobCodeId": string,
            "StartDateTime": string,
            "EndDateTime": string,
            "Status": string,
            "IsActive": boolean,
            "SiteId": string,
            "Source": string,
            "ActualUpdateDate": string,
            "Breaks": [
                {
                    "BreakStartDateTime": string,
                    "BreakEndDateTime": string,
                    "BreakTypeCode": string,
                    "IsPaidBreak": boolean
                }
            ],
            "Tips": [
                {
                    "TenderCategoryCode": string,
                    "TenderTypeCode": string,
                    "TenderCurrencyCode": string,
                    "Amount": decimal
                }
            ],
            "Sales": [
                {
                    "TenderTypeCode": string,
                    "TenderCurrencyCode": string,
                    "Amount": decimal
                }
            ]
        }
    ]
}

Fully Successful Sample Response Body

{
    "Errors": [],
    "ProcessedData": [
        {
            "ShiftId": "69d63c8ce87f10de90daf63d",
            "EmployeeId": "69d51fece87f10de90daedce",
            "EmployeeCorporateCode": "3655",
            "ExternalEmployeeId": null,
            "JobName": "Cashier",
            "JobCodeId": "58e63c06fbf17de5ced22064",
            "ExternalJobCodeId": "8792",
            "StartDateTime": "2026-03-07T18:56:01Z",
            "EndDateTime": "2026-03-08T05:00:00Z",
            "Status": "CLOCKED_OUT",
            "IsActive": true,
            "SiteId": "63da4653b5c13514ecaeac0f",
            "Source": "TestSource",
            "ActualUpdateDate": "2026-04-07T00:00:00.000Z",
            "Breaks": [
                {
                    "BreakStartDateTime": "2026-03-07T19:00:00Z",
                    "BreakEndDateTime": "2026-03-07T19:15:00Z",
                    "BreakTypeCode": "MEAL",
                    "IsPaidBreak": true
                }
            ],
            "Tips": [],
            "Sales": []
        },
        {
            "ShiftId": "69d63c8ce87f10de90daf640",
            "EmployeeId": "69d51fece87f10de90daedce",
            "EmployeeCorporateCode": "3655",
            "ExternalEmployeeId": null,
            "JobName": "Cashier",
            "JobCodeId": "58e63c06fbf17de5ced22064",
            "ExternalJobCodeId": "8792",
            "StartDateTime": "2026-03-08T05:00:01Z",
            "EndDateTime": "2026-03-08T23:49:00Z",
            "Status": "CLOCKED_OUT",
            "IsActive": true,
            "SiteId": "63da4653b5c13514ecaeac0f",
            "Source": "TestSource",
            "ActualUpdateDate": "2026-04-07T00:00:00.000Z",
            "Breaks": [
                {
                    "BreakStartDateTime": "2026-03-08T10:00:00Z",
                    "BreakEndDateTime": "2026-03-08T13:35:00Z",
                    "BreakTypeCode": "REST",
                    "IsPaidBreak": false
                }
            ],
            "Tips": [
                {
                    "TenderCategoryCode": "DTIP",
                    "TenderTypeCode": "CREDIT",
                    "TenderCurrencyCode": "USD",
                    "Amount": 9.00
                },
                {
                    "TenderCategoryCode": "DTIP",
                    "TenderTypeCode": "CUSTOM",
                    "TenderCurrencyCode": "USD",
                    "Amount": 0.70
                },
                {
                    "TenderCategoryCode": "DTIP",
                    "TenderTypeCode": "DEBIT",
                    "TenderCurrencyCode": "USD",
                    "Amount": 7.75
                }
            ],
            "Sales": [
                {
                    "TenderTypeCode": "CASH",
                    "TenderCurrencyCode": "USD",
                    "Amount": 224.63
                }
            ]
        }
    ]
}

Successful Sample Response with Not All Tips Created

{
    "Errors": [
        {
            "Reason": "InvalidBreakData",
            "Message": 
"No break configuration was found for the received combination of 
BreakTypeCode and IsPaidBreak"
        },
        {
            "Reason": "InvalidTipsData",
            "Message": 
"Unsupported TenderCategoryCode=DGTLW value is received. Supported values: 
DTIP, IDTIP"
        }
    ],
    "ProcessedData": [
        {
            "ShiftId": "6439b0e15b6b7639fe2dd4f8",
            "EmployeeId": "62dc040174630b7536f71a96",
            "EmployeeCorporateCode": "9092i2",
            "ExternalEmployeeId": "636894",
            "JobName": "Expediter",
            "JobCodeId": "6092a69a2cedea0034aceddd",
            "ExternalJobCodeId": "75",
            "StartDateTime": "2023-08-07T18:56:49Z",
            "EndDateTime": "2023-08-08T18:56:49Z",
            "Status": "CLOCKED_OUT",
            "IsActive": true,
            "SiteId": "6439b0e15b6b7639fe2dd4f1",
            "Source": "TestSource",
            "ActualUpdateDate": "2023-08-08T19:16:57.000Z",
            "Breaks": [
                {
                    "BreakStartDateTime": "2023-08-07T22:39:26Z",
                    "BreakEndDateTime": "2023-08-08T00:16:38Z",
                    "BreakTypeCode": "MEAL",
                    "IsPaidBreak": true
                },
                {
                    "BreakStartDateTime": "2023-08-08T02:30:00Z",
                    "BreakEndDateTime": "2023-08-08T02:35:00Z",
                    "BreakTypeCode": "UNKNOWN",
                    "IsPaidBreak": false
                }
            ],
            "Tips": [
                {
                    "TenderCategoryCode": "DTIP",
                    "TenderTypeCode": "CREDIT",
                    "TenderCurrencyCode": "USD",
                    "Amount": 9.00
                },
                {
                    "TenderCategoryCode": "DTIP",
                    "TenderTypeCode": "CUSTOM",
                    "TenderCurrencyCode": "USD",
                    "Amount": 0.70
                },
                {
                    "TenderCategoryCode": "DTIP",
                    "TenderTypeCode": "DEBIT",
                    "TenderCurrencyCode": "USD",
                    "Amount": 7.75
                }
            ],
            "Sales": [
                {
                    "TenderTypeCode": "CASH",
                    "TenderCurrencyCode": "USD",
                    "Amount": 224.63
                }
            ]
        }
    ]
}

PostSchedulesRequestBody

For this request body:

Only one schedule record can be created at a time.
All other parameters sent outside of the list provided below are ignored during the schedule processing without errors.
Several schedules for the same company + site + timeframe are not allowed. Overlaps are identified using both StartDate and EndDate fields.

Field Name	Type	Required	Description
`StartDate`	string	Yes	The schedule’s start date and time, if needed. The date/time should be provided in the UTC - YYYY-MM-DDTHH:MM:SS.SSSZ format.
`EndDate`	string	Yes	The schedule's end date and time, if needed. The date/time should be provided in the UTC - YYYY-MM-DDTHH:MM:SS.SSSZ format.
`Timezone`	string	Yes	The store’s timezone name. Use the format described in the TZ identifier column in this list of timezones.
`Source`	string	No	The source system name from where a schedule record is being imported
`Shifts`	ShiftsRequestBody Array	Yes	A list of employees' shifts within this schedule. The child fields are described below: This array cannot be null, empty, or received in another format. For all shifts inside the array: Shift overlaps are not allowed for the same combination of `SiteId` + `EmployeeId`/`EmployeeCorporateCode` + `EndTime` + `StartTime`. Shifts cannot be outside of their parent’s schedule boundaries. For example, before the schedule’s start time or after the schedule’s end time.

PostShiftsRequestBody Array

Field Name	Type	Required	Description
`ExternalShiftId`	string	No	The shift's identifier (ID) provided by external publisher. If provided, the ID should be unique within a company.
`BusinessDate`	string	Yes	The business date to which a received shift should belong. This parameter should consider the site’s business date start date and time.
`EmployeeCorporateCode`	string	No*	The employee internal, readable ID in our system. *This parameter is required if if the `EmployeeId` parameter is not received. If both the `EmployeeId` and `EmployeeCorporateCode` parameters are received, then the `EmployeeId` parameter has higher priority and `EmployeeCorporateCode` value will be ignored. If `EmployeeCorporateCode` is received, it should belong to the existing, non-deleted employee.
`EmployeeId`	string	No*	The employee unique database ID in our system. *This parameter is required if the `EmployeeCorporateCode` parameter is not received. If both the `EmployeeId` and `EmployeeCorporateCode` parameters are received, then the `EmployeeId` parameter has higher priority and `EmployeeCorporateCode` value will be ignored. If this parameter is received, received value should have a 24 character hexadecimal string format. If `EmployeeId` is received, it should belong to the existing, non-deleted employee.
`JobCodeId`	string	No*	The Data Management UID of the job code that should be associated with this shift record. An employee must have a non-deleted job record within the received site and with this job code for this schedule to be successfully saved. A list of available job codes in our system can be requested using the GET /Staff/JobCode endpoint. *This parameter is required if the `ExternalJobCodeId` parameter is not received. If both `JobCodeId` and `ExternalJobCodeId` parameters are received, then the `JobCodeId` parameter has higher priority and `ExternalJobCodeId` value will be ignored. If the `JobCodeId` parameter is received, received value should have a 24 character hexadecimal string format.
`ExternalJobCodeId`	string	No*	The Data Management `external_id` of the job code that should be associated with this shift record. Using this code, the received site ID in the `X-SITE-IDs` header, and the identified employee, a non-deleted employee’s job code could be identified by our system to verify that such a job code exists in Data Management. *This parameter is required if the `JobCodeId` parameter is not received.
`StartTime`	string	Yes	The shift’s start date and time, if needed. The date/time should be provided in the UTC - YYYY-MM-DDTHH:MM:SS.SSSZ format and cannot be null or "".
`EndTime`	string	Yes	The shift’s end date and time, if needed. The date/time should be provided in the UTC - YYYY-MM-DDTHH:MM:SS.SSSZ format and cannot be null or "".

PostSchedulesResponseBody

Field Name	Type	Required	Description
`ScheduleId`	string	Yes	The internal unique identifier (UID) in our system of the created schedule
`StartDate`	string	Yes	The start date of the created schedule. The date/time is returned in the UTC - YYYY-MM-DDTHH:MM:SS.SSSZ format.
`EndDate`	string	Yes	The end date of the created schedule. The date/time is returned in the UTC - YYYY-MM-DDTHH:MM:SS.SSSZ format.
`Source`	string	Yes	The source-system name where the schedule has been created initially. The value is `null` if it was not received in the request.
`Timezone`	string	Yes	The received value as is without transformations
`ModifyTime`	string	Yes	The Coordinated Universal Time (UTC) timestamp of the record being created in the database. The date/time is returned in the UTC - YYYY-MM-DDTHH:MM:SS.SSSZ format.
`Shifts`	ShiftsResponseBody Array	Yes	A list of successfully created child shifts

PostShiftsResponseBody Array

Field Name	Type	Required	Description
`ExternalShiftId`	string	No	The shift's identifier (ID) provided by external publisher. The field is present in a response if it was received in a request.
`BusinessDate`	string	Yes	The received business date. The date is returned in the YYYY-MM-DDTHH:MM:SS.SSSZ format without additional time zone conversions.
`StartTime`	string	Yes	The shift's start time. The date is returned in the YYYY-MM-DDTHH:MM:SS.SSSZ format.
`EndTime`	string	Yes	The shift’s end date and time, if needed. The date is returned in the YYYY-MM-DDTHH:MM:SS.SSSZ format.
`EmployeeCorporateCode`	string	No	The employee internal, readable ID in our system.
`EmployeeId`	string	No	The employee unique database ID in our system.
`JobCodeId`	string	No	The Data Management unique identifier (UID) of the job code
`ExternalJobCodeId`	string	No	The Data Management `external_id` of the job code that should be associated with this shift record. The field is present in a response if it was received in a request.
`ModifyTime`	string	Yes	The Coordinated Universal Time (UTC) timestamp of the record being created in the database. The date is returned in the YYYY-MM-DDTHH:MM:SS.SSSZ format.

PatchExternalGeneralEmployeeIDRequestBody

For this request:

General validations:
- Parameters cannot be received without a value.
- For all string fields with the Nullable column listed as No: These parameters cannot be received as null or ““.
- For all string fields with the Nullable column listed as Yes: These parameters can be null, but cannot be received as ““.
- For all array fields: If received, these parameters cannot be [],““,or null, and these arrays must contain only valid, not empty, objects with the required child fields inside.
- For object fields: These parameters cannot be received as null or ““.
Structure:
- Only the fields and objects that need to be updated should be included in the request. There is no need to send the entire employee record.
- This also applies when only child arrays require updates. In such cases, parent employee fields can be omitted, and only the necessary child entities should be sent.

Field Name	Type	Required	Nullable	Description
`Firstname`	string	No	No	The employee's first name
`Lastname`	string	No	No	The employee's last name or surname
`Middlename`	string	No	Yes	The employee’s middle name or patronymic, if applicable
`Username`	string	No	Yes	The employee’s primary email. Using this email, the employee's link to the portal user is performed. Note Several non-deleted employees with the same value in this field within the same company are not allowed.
`EmployeeCorporateCode`	string	No	No	The unique readable identifier assigned to the employee. Used for internal identification within the company. Letters and numbers are allowed in this field. Multiple employees cannot share the same value in this field. Uniqueness is enforced at two possible levels (the applicable uniqueness level is defined individually for each client): Company level - The value must be unique across the entire company. Site level - The value must be unique within the employee’s primary site and site statuses.
`ExternalEmployeeId`	string	No	No	The unique identifier (UID) of the employee from external system. No restrictions are applied to the value format. Note It is recommended to use unique values for each employee across the entire company.
`PrimarySiteId`	string/HEX24	No	No	The UID of the location at which the employee performs most of their work. It is a Genius generated value that can be found in Genius Portal - Sites section. Note The received site ID should belong to the non-deleted site that belongs to the company, received in the `X-COMPANY-ID` header.
`Source`	string	No	Yes	This information is used to determine where the employee record was imported from. No restrictions are applied to the value format.
`AdditionalDetails`	AdditionalDetails Object	No	No	A list of additional details about an employee that could be useful or important for any need
`EmployeePhones`	EmployeePhones Array	No	No	This array stores one or more phone numbers associated with the employee. Each item includes the actual phone number and its type, such as mobile, work, and home.
`EmployeeAddresses`	EmployeeAddresses Array	No	No	This array contains one or more postal addresses associated with the employee. Each item includes the full address details and the address type, such as home and work.
`EmployeeContacts`	EmployeeContacts Array	No	No	This array contains one or more emergency contacts for the employee. Each item includes personal details and contact information.
`EmployeeEmails`	EmployeeEmails Array	No	No	This array stores one or more email addresses associated with the employee. Each item includes the actual email address and its type, such as work and home.
`EmployeeSiteStatuses`	EmployeeSiteStatuses Array	No	No	This array tracks the employee’s status at one or more sites. Each item reflects the employee’s actual activity status starting from the specified date.
`PosCredentials`	PosCredentials Array	No	No	This array contains login credentials and the assigned role for an employee to access the Genius POS system. Although this field is an array, only a single set of credentials can exist per employee. If multiple records are provided, only the first one will be processed.

AdditionalDetails Object - PATCH

Field Name	Type	Required	Nullable	Description
`TaxIdentifier`	string	No	Yes	The employee’s tax identification number. Note If this value is received, it should be unique within a company.
`BadgeNumber`	string	No	Yes	The unique number assigned to the employee’s access badge. Note If this value is received, it should be unique within a company.
`EthnicityCode`	string	No	Yes	The code representing the employee’s ethnicity, configured in Data Management - Ethnicities section. All available codes could be found using the GET /Lookup/Ethnicity endpoint. The `Code` field from the response is the value that should be sent here.
`Nickname`	string	No	Yes	The employee’s preferred informal name
`BirthDate`	string/date	No	Yes	The employee’s date of birth. Note If this field is received, it should be provided in the YYYY-MM-DD format only.
`Gender`	string	No	Yes	The employee’s gender. Note If this field is received, its supported values are: `O` - Declined to answer `F` - Female `M` - Male
`IsHandicapped`	boolean	No	Yes	A flag that indicates whether the employee has a disability
`IsRehireable`	boolean	No	Yes	A flag that indicates whether the employee is eligible for rehire by the company after the termination of their previous employment
`IsVeteran`	boolean	No	Yes	A flag that indicates whether the employee has served in the military
`IsMinor`	boolean	No	Yes	A flag that indicates whether the employee is legally considered a minor based on their age

EmployeePhones Array - PATCH

For this array:

All required fields listed in the table below cannot be sent as empty ("") or null when this array is included in the request.
The provided PhoneTypeCode value is used to determine whether the existing record should be updated by this request or a new one should be created.

Field Name

Type

Required

Description

PhoneNumber

string

Yes

The employee's phone number

PhoneTypeCode

string

Yes

The phone type code for the employee's phone number. Supported values:

Code	Name
`BIZ`	Business phone number
`CELL`	Mobile phone number
`FAX`	Fax phone number
`HOME`	Home phone number

Note

Several phone records with the same PhoneTypeCode for one employee are not allowed.

EmployeeAddresses Array - PATCH

For this array:

All required fields listed in the table below cannot be sent as empty ("") or null when this array is included in the request.
All optional fields can be received as null or ““. In such cases, they overwrite the existing values with the received value.
The provided AddressTypeCode value is used to determine whether the existing record should be updated by this request or a new one should be created.

Field Name

Type

Required

Description

AddressTypeCode

string

Yes

The address type code for the employee's address. Supported values:

Code	Name
`HOME`	The employee's home address
`MAIL`	The employee's mailing address

Address1

string

Yes*

The primary line of the employee’s address, such as street and number.

*This parameter can be omitted from the request only when a record with the same AddressTypeCode already exists in the database, as this is an update request and not a new record creation, AND at least one another field was received for this address record, except AddressTypeCode. In all other cases, this field is required.

Address2

string

The secondary line of the employee’s address, such as apartment, suite, or unit

Address3

string

An additional line for the employee’s address, such as building, or complex

City

string

The employee's city name

StateCode

string

The code representing the state, province, or region of the employee’s address.

The list of all configured states, including their names and codes, can be retrieved using the GET /Lookup/State endpoint. The Code field from response is the one that should be sent here.

PostalCode

string

The employee's postal code

CountryCode

string

Yes*

The code representing the country of the employee’s address.

EmployeeContacts Array - PATCH

For this array:

All required fields listed in the table below cannot be sent as empty ("") or null when this array is included in the request.
All optional fields can be received as null or ““. In such cases, they overwrite the existing values with the received value.
The provided Firstname and Lastname values are used to determine whether the existing record should be updated by this request or a new one should be created.

Field Name	Type	Required	Description
`Firstname`	string	Yes	The first name of the employee's emergency contact. Note Several contact records with the same combination of lowercase concatenation of the contact’s `FirstName` and `LastName` values for one employee are not allowed.
`Lastname`	string	Yes	The last name of the employee’s emergency contact. Note Several contact records with the same combination of lowercase concatenation of the contact’s `FirstName` and `LastName` values for one employee are not allowed.
`Middlename`	string	No	The middle name of the employee’s emergency contact
`Address1`	string	No	The primary line of the employee contact’s address
`Address2`	string	No	The secondary line of the employee contact’s address
`Address3`	string	No	An additional line of the employee contact’s address
`City`	string	No	The city name of the employee contact's address
`StateCode`	string	No	The code representing the state, province, or region of the employee contact’s address. The list of all configured states, including their names and codes, can be retrieved using the GET /Lookup/State endpoint. The `Code` field from response is the one that should be sent here.
`PostalCode`	string	No	The postal code of the employee contact's address
`CountryCode`	string	No	The code representing the country of the employee contact’s address. The list of all configured countries, including their names and codes, can always be retrieved using the GET /Lookup/Country endpoint. The `Code` field from response is the one that should be sent here.
`Phone1`	string	No	The primary phone number of the employee’s emergency contact
`Phone2`	string	No	The secondary phone number of the employee’s emergency contact

EmployeeEmails Array - PATCH

For this array:

All required fields listed in the table below cannot be sent as empty ("") or null when this array is included in the request.
The provided EmailTypeCode value is used to determine whether the existing record should be updated by this request or a new one should be created.

Field Name

Type

Required

Description

Email

string

Yes

The employee's email address

EmailTypeCode

string

Yes

The email type code for the employee's email address. Supported values:

Code	Name
`PRSNL`	Personal email
`WORK`	Work email

Note

Several email records with the same EmailTypeCode for one employee are not allowed.

EmployeeSiteStatuses Array - PATCH

All required fields listed in the table below cannot be sent as empty ("") or null when this array is included in the request.
If for any reason several records are received in this array in the request with the same StatusCode AND EffectiveDate, only the first record is processed. Other records are ignored.
If for any reason several records are received in this array in the request with the same StatusCode but different EffectiveDate, only the earliest record is processed. Other records are ignored.

Processing notes to better understand the result of the request:

If the employee has no non-deleted site statuses for the received site(s): New site status records for this employee and the specified sites are created using the Status and Effective Date provided in the request.
If the employee has at least one non-deleted site status record for the received site(s):
- If the existing status record with the maximum effective date less than the one received in the request in the EffectiveDate parameter has the same Status value, no site status records are created or updated.
- If the existing status record with the maximum effective date equal to the one received in the request in the EffectiveDate parameter:
  - If the existing Status value equals the one received in the request, no site status records are created or updated.
  - If the existing Status value is not equal to the one received in the request, the existing record is updated with a new status.
- Otherwise, new site status records for this employee and the specified sites are created using the Status and Effective Date provided in the request.

Additionally, after processing all received site status records, the chronological sequence of statuses is validated to ensure that no consecutive records have the same Status value. For this purpose:

All non-deleted site status records, aggregated by site, are sorted by EffectiveDate.
If, within the sorted list for a site, an employee has two or more site status records with the same Status value:
- The record with the earliest EffectiveDate is kept.
- All other records with the same Status value, up until the next record that has a different Status value, are removed.

Field Name

Type

Required

Description

EffectiveDate

string/date

Yes

The date when the site status becomes effective.

Note

The received values should be in the YYYY-MM-DD format.

StatusCode

string

Yes

The code representing the employee’s status at a site.

SiteIds

array of strings [HEX24, …, HEX24]

Yes

A list of site IDs to which this status applies since the EffectiveDate.

All site IDs should belong to the non-deleted sites that belong to the company, which are received in the X-COMPANY-ID header.

PosCredentials Array - PATCH

For this array:

All required fields listed in the table below cannot be sent as empty ("") or null when this array is included in the request.
If for any reason several records are received in this array in the request, only the first record is processed. Other records are ignored.

Field Name	Type	Required	Description
`EmployeePOSCode`	string	Yes*	The employee’s log in value, or user identifier (ID), on the point of sale (POS). This field is required if a new POS Credentials record is created for an employee. Multiple employees cannot share the same value in this field. The applicable uniqueness level is defined individually for each client. Uniqueness is enforced at two possible levels: Company level* - The value must be unique across the entire company. Site level – The value must be unique within the employee’s primary site and site statuses. Only positive numbers are allowed.
`Password`	string	Yes*	*This field is required if a new POS Credentials record is created for an employee. If a new password needs to be sent for an employee, this field must contain the non-hashed value. Otherwise, the hashed value, previously received in responses of other External/Employee GET/POST endpoints, should be provided together with the field `IsHashedPassword = true`.
`IsHashedPassword`	boolean	No	This flag ensures that the system correctly interprets whether additional hashing is required. If the provided password was pre-hashed by Genius, this parameter should be sent as `true`. If the password was provided in plain text, not hashed, this parameter should be sent as `false`.
`RoleId`	string/HEX24	Yes*	The user's role ID. *This field is required if a new POS Credentials record is created for an employee. The received value should have a 24 character hexadecimal string format. A list of all available roles in Genius Portal can be received using the GET /auth/getCompanyRoles endpoint, The `Id` field from response is the one that should be sent here.

PatchExternalGeneralEmployeeIDJobIDRequestBody

For this request:

Only the fields explicitly provided in the request are updated for the job. Valid values received overwrite existing ones in the database. Fields that are not included in the request remain unchanged.
It is allowed to send this request only with rates, without parent job fields, but it cannot be received as an empty object.
Parameters cannot be received without a value, null except as described below, [] for arrays, or ““.

Field Name	Type	Required	Description
`Deactivated`	boolean	No	A flag that indicates whether the the employee’s job record is no longer active. This field is typically used to exclude inactive job records from processing, calculations, or synchronization flows.
`DeactivationDate`	string/date	Yes*	The date when the employee's job was deactivated. This field is typically used together with the `Deactivated` flag to determine job status over time. *This field is required when the valid `Deactivated` field is received. This parameter can be `null` only if the `Deactivated` field is received as `false`. In all other cases, it cannot be received as `null`, `““`, or without a value.
`IsPrimaryJob`	boolean	No	A flag that indicates whether this job is the employee’s primary position. Several job records with the I`sPrimaryJob = true` flag for the same `SiteId` are not allowed.
`EmployeeJobPays`	EmployeeJobPays Array	No	A list of pay details associated with this job position, such as salary or hourly rate This array should be sent only if a new job rate record should be created or the existing updated. Otherwise, this field should be omitted. It is allowed to receive this array as an empty array. No errors will be returned in response, and this array will be ignored.

EmployeeJobPays Array - Patch

For this array:

Parameters cannot be received without a value, “", or null.
Errors in one job pay record block other job pay records AND the whole job record from processing.
The earliest EffectiveDate value from all successfully created/updated rates in addition to the already existing in the database is used as the Effective Date of the parent job record.
The required fields from the table below are mandatory only when the EmployeeJobPays array is included in the request and contains at least one valid, non-empty object.

Processing notes to better understand the result of the request:

If the employee job has no non-deleted rates: New job pay records for this job with all details received in the request and job’s compensation type are created.
Otherwise:
- If the existing job pay record with the maximum effective date is less than the one received in the request in the EffectiveDate parameter has the same Rate, no job pay records either created or updated.
- If the existing job pay record with the maximum effective date equals the one received in the request in the EffectiveDate parameter:
  - If the existing Rate value equals the one received in the request, no job pay records are created or updated.
  - If the existing Rate values are not equal to the one received in the request, the existing record is updated with the new data.
- Otherwise, new job pay records are created for this employee job.

Field Name	Type	Required	Description
`EffectiveDate`	string/date	Yes	The date when this compensation rate becomes effective in YYYY-MM-DD format. Note Several job pay records with the same `EffectiveDate` are not allowed.
`Rate`	number/decimal (2)	Yes	The amount or rate of pay associated with the compensation type. Note Negative values are not allowed.

PutExternalGeneralShiftRequestBody

For this request body:

Only one shift can be updated at a time.
All other parameters sent outside of the list provided below are ignored during the shift processing without errors.
Received data always fully overwrites the already existing one if a valid request is received.
Nested Tips and Sales arrays errors do not affect the shift’s update process.
Updates are allowed only for non-deleted shifts and shifts that belong to non-deleted employees and employee jobs.
All datetime values should be provided in Coordinated Universal Time (UTC).

Field Name	Type	Required	Description
`StartDateTime`	string	Yes	The shift’s start date and time. This parameter cannot be null, empty, or ““, and must be in the YYYY-MM-DDTHH:MM:SSZ format.
`EndDateTime`	string	No	The shift's end date and time. This parameter can be null for open shifts, but cannot be empty or ““, and must be in the YYYY-MM-DDTHH:MM:SSZ format.
`Source`	string	Yes	The name of the source system from which this shift is sent. This parameter can be null, empty, or ““.
`ActualUpdateDate`	string	Yes	The timestamp of when the shift is sent from the external system. This parameter cannot be null, empty, or ““, and must be in the YYYY-MM-DDTHH:MM:SS.SSSZ format. The received `ActualUpdateDate` should always be more recent than the date a shift already has in the database.
`Breaks`	array of objects	Yes	This array can be empty when a shift has no breaks - `Breaks: []`, but this array should always be present in a request and cannot be null, empty, or ““. Several open breaks with `"BreakEndDateTime": null` are not allowed. Break overlaps are not allowed. Breaks cannot overlap or stay outside of the shift's boundaries.
`Breaks.BreakStartDateTime`	string	Yes*	The break’s start date and time. If received, this parameter cannot be null, empty, or ““, and must be in the YYYY-MM-DDTHH:MM:SSZ format. *This parameter can be absent in the request if there are no breaks for the shift. Otherwise, this field is required.
`Breaks.BreakEndDateTime`	string	No	The break’s end date and time. This parameter can be absent in the request if there are no breaks for the shift or for open breaks. If received, this parameter cannot be null, empty, or ““, and must be in the YYYY-MM-DDTHH:MM:SSZ format.
`Breaks.BreakTypeCode`	string	Yes*	The code of the break’s type based on the Break Time section configuration in Data Management. If received, this parameter cannot be null, empty, or ““, and its only supported values are `MEAL` , `REST`, and `UNKNOWN`. `UNKNOWN` is for those cases when break type is not required for external system. *This parameter can be absent in the request if there are no breaks for the shift. Otherwise, this field is required.
`Breaks.IsPaidBreak`	boolean	Yes*	A flag that shows whether a break is a paid one or not based on the Break Time section configuration in Data Management. If received, this parameter cannot be null, empty, or ““, and its only supported values are `true` and `false`. This parameter can be absent in the request if there are no breaks for the shift. Otherwise, this field is required. Note If for any reason the Break Time* section in Data Management contains no records with the received Break Type and `IsPaidBreak` value, a shift is created and in response such break is returned with the `UNKNOWN` break type. A shift can be updated using the PUT /External/General/Shift/[ID] endpoint with the same break information after a valid Break Time configuration is created in Data Management.
`Tips`	array	Yes	This array can be sent as `Tips: []` when a shift has no tips received by an employee, but this array must always be present in the request and cannot be null, empty string, or empty. Several records with the same combination of received values are combined into one during the processing. Their amounts are summed up. Note If no configuration is found in Data Management for the received combinations of `TenderCategoryCode` , `TenderTypeCode`, and `TenderCurrencyCode values`, or invalid values are received in this array, such tip records are not created in the database, but they do not block a shift from creation and a result response, if no other errors are received, will be 200 OK, but with the `Errors` array containing information about those tips records for which processing failed and they were not created in the database. If tips are not created due to the missing Tender Mapping configuration in Data Management, after the configuration is created, then such shifts can be updated with the same set of transactions using the PUT /External/General/Shift/[ID] endpoint, and the transactions are created if a valid Tender Mapping record is found.
`Tips.TenderCategoryCode`	string	Yes*	The code of the tips transaction type, `Indirect` or `Direct` tips, based on the Tender Mapping section configuration in Data Management. If received, this parameter cannot be null, empty, or ““, and its only supported values are `DTIP` and `IDTIP`. *This parameter can be absent in the request if there are no tips for the shift. Otherwise, this field is required.
`Tips.TenderTypeCode`	string	Yes*	The code of the tips payment type configured in the Pay Type section in Data Management. The codes of the related payment classes should be sent here. A list of all payment types, configured in our system, can be received using the GET /Lookup/TenderType endpoint. The `Code` field stores the values that should be sent in this field. If received, this parameter cannot be null, empty, or ““. *This parameter can be absent in the request if there are no tips for the shift. Otherwise, this field is required.
`Tips.TenderCurrencyCode`	string	Yes*	The code of the tips currency configured in the Tender Currency section in Data Management. The codes should be sent here. The list of all tender currencies, configured in our system, can be received using the GET /Lookup/TenderCurrency endpoint. The `Code` field stores the values that should be sent in this field. If received, this parameter cannot be null, empty, or ““. *This parameter can be absent in the request if there are no tips for the shift. Otherwise, this field is required.
`Tips.Amount`	number/decimal	Yes*	The tips amount. If received, this parameter cannot be null, empty, or ““, and negative values are not allowed. *This parameter can be absent in the request if there are no tips for the shift. Otherwise, this field is required.
`Sales`	array of objects	Yes	This array can be sent as `Sales: []` when a shift has no sales data received for an employee, but this array must always be present in the request and cannot be null, empty string, or empty. Several records with the same combination of received values are combined into one during the processing. Their amounts are summed up. Note If no configuration is found in Data Management for the received combinations of `TenderTypeCode`, and `TenderCurrencyCode values`, or invalid values are received in this array, such sales records are not created in the database, but they do not block a shift from creation and a result response, if no other errors are received, will be 200 OK, but with the `Errors` array containing information about those sales records for which processing failed and they were not created in the database. If sales records are not created due to the missing Tender Mapping configuration in Data Management, after the configuration is created, then such shifts can be updated with the same set of transactions using the PUT /External/General/Shift/[ID] endpoint, and the transactions are created if a valid Tender Mapping record is found.
`Sales.TenderTypeCode`	string	Yes*	The code of the sales payment type configured in the Pay Type section in Data Management. Codes of the related payment classes should be sent here. The value logic is the same as described in the Tips.TenderTypeCode. If received, this parameter cannot be null, empty, or ““. *This parameter can be absent in the request if there is no sales data for the shift.
`Sales.TenderCurrencyCode`	string	Yes*	The code of the sales currency configured in the Tender Currency section in Data Management. The codes should be sent here. The value logic is the same as described in the Tips.TenderCurrencyCode. If received, this parameter cannot be null, empty, or ““. *This parameter can be absent in the request if there is no sales data for the shift.
`Sales.Amount`	number/decimal	Yes*	The sales amount. If received, this parameter cannot be null, empty, or ““. *This parameter can be absent in the request if there is no sales data for the shift.

PutExternalGeneralShiftResponseBody

Field Name	Type	Required	Description
`Errors`	array	Yes	This array contains a list of errors encountered while processing the shift’s child entities. These errors did not block the creation of the shift but prevent the creation of the invalid records.
`Errors.Reason`	string	Yes	The reason for the error
`Errors.Message`	string	Yes	The error message
`ProcessedData`	array	Yes	This array of objects contains all shift data that was created successfully in the database based on the details provided in the request
`ProcessedData.ShiftId`	string	Yes	The Staff API unique identifier (UID) for the shift that is being created
`ProcessedData.EmployeeId`	string	Yes	The Staff API UID for the employee related to the created shift
`ProcessedData.EmployeeCorporateCode`	string	Yes	The readable identifier for the employee related to the returned shift. This is the value stored in the Employee Corporate Code field in the employee profile in Staff API.
`ProcessedData.ExternalEmployeeId`	string	Yes	The external identifier for the employee related to the created shift, received from external systems or null
`ProcessedData.JobName`	string	Yes	The name of the job code from Data Management from the active employee job related to the created shift
`ProcessedData.JobCodeId`	string	Yes	The `entity_id` of the job code record from Data Management from the active employee job related to the created shift
`ProcessedData.ExternalJobCodeId`	string	Yes	The Data Management `external_id` of the job code rate or job code from the employee job associated with this shift
`ProcessedData.StartDateTime`	string	Yes	The shift’s start date time returned in the YYYY-MM-DDTHH:MM:SSZ Coordinated Universal Time (UTC) format
`ProcessedData.EndDateTime`	string	Yes	The shift’s end date time returned in the YYYY-MM-DDTHH:MM:SSZ UTC format or null if this shift is open
`ProcessedData.Status`	string	Yes	The shift's status in the database: `CLOCKED_IN`: The employee is not on a break and currently actively working. `ON_BREAK`: The employee is currently on a break. `CLOCKED_OUT`: A shift is closed.
`ProcessedData.IsActive`	boolean	Yes	A flag that shows that this shift is non-deleted. Always = `true`.
`ProcessedData.SiteId`	string	Yes	The UID in our system of a site associated with the currently created shift
`ProcessedData.Source`	string	Yes	The name of the source system from which this shift was imported or "" if a shift was created in Staff API or was imported without external system specified
`ProcessedData.ActualUpdateDate`	string	Yes	The last time the current shift was created or updated through the API call in the YYYY-MM-DDTHH:MM:SS.SSSZ UTC format
`ProcessedData.Breaks`	array of objects	Yes	Each break is displayed as a separate object inside this array. If there are no breaks within the currently created shift, this array is returned as `Breaks:[]`.
`ProcessedData.Breaks.BreakStartDateTime`	string	Yes*	The break’s start date time returned in the YYYY-MM-DDTHH:MM:SSZ UTC format. *Absent only when there are no breaks for a shift. Otherwise, this parameter must be present with a corresponding value.
`ProcessedData.Breaks.BreakEndDateTime`	string	Yes*	The break’s end date time returned in the YYYY-MM-DDTHH:MM:SSZ UTC format or null if this break is open. *Absent only when there are no breaks for a shift. Otherwise, this parameter must be present with a corresponding value or null if a break is still open.
`ProcessedData.Breaks.BreakTypeCode`	string	Yes*	Break Type Code from the Break Time configuration in Data Management. `MEAL`, `REST`, `UNKNOWN`. `UNKNOWN` for cases when no configuration for the received `BreakTypeCode` and `IsPaidBreak` was found. *Absent only when there are no breaks for a shift. Otherwise, this parameter must be present with a corresponding value.
`ProcessedData.Breaks.IsPaidBreak`	boolean	Yes*	A flag showing whether the received break is paid or not. Taken from the found Break Time configuration in Data Management or taken from a default record for cases when no configuration for the received `BreakTypeCode` and `IsPaidBreak` was found. *Absent only when there are no breaks for a shift. Otherwise, this parameter must be present with a corresponding value.
`ProcessedData.Tips`	array of objects	Yes	A list of unique tip records received for the currently created shift that was successfully created in the database, aggregated by `TenderCategoryCode`, `TenderTypeCode`, and `TenderCurrencyCode`. If a result shift has no tip transactions created, this array is returned as `"Tips": [].`
`ProcessedData.Tips.TenderCategoryCode`	string	Yes*	The identifier of the tip type - Direct (`DTIP`) or Indirect (`IDTIP`). *Absent only when there are no tips for a shift.
`ProcessedData.Tips.TenderTypeCode`	string	Yes*	The code of the payment class associated with a tip record that was created. *Absent only when there are no tips for a shift.
`ProcessedData.Tips.TenderCurrencyCode`	string	Yes*	The code of the tender currency associated with a tip record that was created. *Absent only when there are no tips for a shift.
`ProcessedData.Tips.Amount`	number/decimal	Yes*	The total tips amount for this particular tender type. *Absent only when there are no tips for a shift.
`ProcessedData.Sales`	array of objects	Yes	A list of unique sales records received for the currently created shift that was successfully created in the database, aggregated by `TenderTypeCode` and `TenderCurrencyCode`. If a result shift has no sales transactions created, this array is returned as `"Sales": []`.
`ProcessedData.Sales.TenderTypeCode`	string	Yes*	The code of the payment class associated with a sales record that was created. *Absent only when there are no sales for a shift.
`ProcessedData.Sales.TenderCurrencyCode`	string	Yes*	The code of the tender currency associated with a sales record that was created. *Absent only when there are no sales for a shift.
`ProcessedData.Sales.Amount`	number/decimal	Yes*	The total sales amount for this particular tender type. *Absent only when there are no sales for a shift.

General Structure Sample Body

{
    "Errors": [
        {
            "Reason": string,
            "Message": string
        }
    ],
    "ProcessedData": [
        {
            "ShiftId": string,
            "EmployeeId": string,
            "EmployeeCorporateCode": string,
            "ExternalEmployeeId": string,
            "JobName": string,
            "JobCodeId": string,
            "ExternalJobCodeId": string,
            "StartDateTime": string,
            "EndDateTime": string,
            "Status": string,
            "IsActive": boolean,
            "SiteId": string,
            "Source": string,
            "ActualUpdateDate": string,
            "Breaks": [
                {
                    "BreakStartDateTime": string,
                    "BreakEndDateTime": string,
                    "BreakTypeCode": string,
                    "IsPaidBreak": boolean
                }
            ],
            "Tips": [
                {
                    "TenderCategoryCode": string,
                    "TenderTypeCode": string,
                    "TenderCurrencyCode": string,
                    "Amount": decimal
                }
            ],
            "Sales": [
                {
                    "TenderTypeCode": string,
                    "TenderCurrencyCode": string,
                    "Amount": decimal
                }
            ]
        }
    ]
}

Fully Successful Sample Response Body

{
    "Errors": [],
    "ProcessedData": [
        {
            "ShiftId": "69d63c8ce87f10de90daf63d",
            "EmployeeId": "69d51fece87f10de90daedce",
            "EmployeeCorporateCode": "3655",
            "ExternalEmployeeId": null,
            "JobName": "Cashier",
            "JobCodeId": "58e63c06fbf17de5ced22064",
            "ExternalJobCodeId": "8792",
            "StartDateTime": "2026-03-07T18:56:01Z",
            "EndDateTime": "2026-03-08T05:00:00Z",
            "Status": "CLOCKED_OUT",
            "IsActive": true,
            "SiteId": "63da4653b5c13514ecaeac0f",
            "Source": "TestSource",
            "ActualUpdateDate": "2026-04-07T00:00:00.000Z",
            "Breaks": [
                {
                    "BreakStartDateTime": "2026-03-07T19:00:00Z",
                    "BreakEndDateTime": "2026-03-07T19:15:00Z",
                    "BreakTypeCode": "MEAL",
                    "IsPaidBreak": true
                }
            ],
            "Tips": [],
            "Sales": []
        },
        {
            "ShiftId": "69d63c8ce87f10de90daf640",
            "EmployeeId": "69d51fece87f10de90daedce",
            "EmployeeCorporateCode": "3655",
            "ExternalEmployeeId": null,
            "JobName": "Cashier",
            "JobCodeId": "58e63c06fbf17de5ced22064",
            "ExternalJobCodeId": "8792",
            "StartDateTime": "2026-03-08T05:00:01Z",
            "EndDateTime": "2026-03-08T23:49:00Z",
            "Status": "CLOCKED_OUT",
            "IsActive": true,
            "SiteId": "63da4653b5c13514ecaeac0f",
            "Source": "TestSource",
            "ActualUpdateDate": "2026-04-07T00:00:00.000Z",
            "Breaks": [
                {
                    "BreakStartDateTime": "2026-03-08T10:00:00Z",
                    "BreakEndDateTime": "2026-03-08T13:35:00Z",
                    "BreakTypeCode": "REST",
                    "IsPaidBreak": false
                }
            ],
            "Tips": [
                {
                    "TenderCategoryCode": "DTIP",
                    "TenderTypeCode": "CREDIT",
                    "TenderCurrencyCode": "USD",
                    "Amount": 9.00
                },
                {
                    "TenderCategoryCode": "DTIP",
                    "TenderTypeCode": "CUSTOM",
                    "TenderCurrencyCode": "USD",
                    "Amount": 0.70
                },
                {
                    "TenderCategoryCode": "DTIP",
                    "TenderTypeCode": "DEBIT",
                    "TenderCurrencyCode": "USD",
                    "Amount": 7.75
                }
            ],
            "Sales": [
                {
                    "TenderTypeCode": "CASH",
                    "TenderCurrencyCode": "USD",
                    "Amount": 224.63
                }
            ]
        }
    ]
}

Successful Sample Response with Not All Tips Created

{
    "Errors": [
        {
            "Reason": "InvalidBreakData",
            "Message": 
"No break configuration was found for the received combination of 
BreakTypeCode and IsPaidBreak"
        },
        {
            "Reason": "InvalidTipsData",
            "Message": 
"Unsupported TenderCategoryCode=DGTLW value is received. Supported values: 
DTIP, IDTIP"
        }
    ],
    "ProcessedData": [
        {
            "ShiftId": "6439b0e15b6b7639fe2dd4f8",
            "EmployeeId": "62dc040174630b7536f71a96",
            "EmployeeCorporateCode": "9092i2",
            "ExternalEmployeeId": "636894",
            "JobName": "Expediter",
            "JobCodeId": "6092a69a2cedea0034aceddd",
            "ExternalJobCodeId": "75",
            "StartDateTime": "2023-08-07T18:56:49Z",
            "EndDateTime": "2023-08-08T18:56:49Z",
            "Status": "CLOCKED_OUT",
            "IsActive": true,
            "SiteId": "6439b0e15b6b7639fe2dd4f1",
            "Source": "TestSource",
            "ActualUpdateDate": "2023-08-08T19:16:57.000Z",
            "Breaks": [
                {
                    "BreakStartDateTime": "2023-08-07T22:39:26Z",
                    "BreakEndDateTime": "2023-08-08T00:16:38Z",
                    "BreakTypeCode": "MEAL",
                    "IsPaidBreak": true
                },
                {
                    "BreakStartDateTime": "2023-08-08T02:30:00Z",
                    "BreakEndDateTime": "2023-08-08T02:35:00Z",
                    "BreakTypeCode": "UNKNOWN",
                    "IsPaidBreak": false
                }
            ],
            "Tips": [
                {
                    "TenderCategoryCode": "DTIP",
                    "TenderTypeCode": "CREDIT",
                    "TenderCurrencyCode": "USD",
                    "Amount": 9.00
                },
                {
                    "TenderCategoryCode": "DTIP",
                    "TenderTypeCode": "CUSTOM",
                    "TenderCurrencyCode": "USD",
                    "Amount": 0.70
                },
                {
                    "TenderCategoryCode": "DTIP",
                    "TenderTypeCode": "DEBIT",
                    "TenderCurrencyCode": "USD",
                    "Amount": 7.75
                }
            ],
            "Sales": [
                {
                    "TenderTypeCode": "CASH",
                    "TenderCurrencyCode": "USD",
                    "Amount": 224.63
                }
            ]
        }
    ]
}

PutSchedulesRequestBody

For this request body:

All other parameters sent outside of the list provided below are ignored during the schedule processing without errors.
If at least one child shift is invalid, such as invalid data is received, or a shift overlaps with another shift, or is outside the schedule ranges, the whole schedule update is not performed.
Several schedules for the same company + site + timeframe are not allowed. Overlaps are identified using both StartDate and EndDate fields.
If a request is received with the empty Shifts: [] array, any already existing shifts for the received schedule are not affected by this update request.
All already existing, active, non-deleted shifts that are not sent in the request, are not affected by this update request.
If a shift that is sent in the request is found in the database and it is received with a valid set of parameters, then the update request always overwrites the already existing record with newer data. There is no merging. Missing required parameters are not allowed and this update request results in the shift overwritten.

Field Name	Type	Required	Description
`StartDate`	string	Yes	The schedule’s start date and time, if needed. The date/time should be provided in the UTC - YYYY-MM-DDTHH:MM:SS.SSSZ format.
`EndDate`	string	Yes	The schedule's end date and time, if needed. The date/time should be provided in the UTC - YYYY-MM-DDTHH:MM:SS.SSSZ format.
`Timezone`	string	Yes	The store’s timezone name. Use the format described in the TZ identifier column in this list of timezones.
`Source`	string	No	The source system name from where a schedule record is being imported
`ModifyTime`	string	Yes	The schedule’s update time received from the external system. This parameter is used to prevent outdated schedule updates. The date/time should be provided in the UTC - YYYY-MM-DDTHH:MM:SS.SSSZ format and cannot be null or "". The received value cannot be less than or equal to the already existing database value of a schedule that is being updated.
`Shifts`	PutShiftsRequestBody Array	Yes	A list of employees' shifts within this schedule. The child fields are described below: This array can be empty when no shifts should be updated - `Shifts: []`, but it still should be present in the payload. For all shifts inside the array: Shift overlaps are not allowed for the same combination of `SiteId` + `EmployeeId/EmployeeCorporateCode` + `EndTime` + `StartTime`. Shifts cannot be outside of their parent’s schedule boundaries. For example, before the schedule’s start time or after the schedule’s end time.

PutShiftsRequestBody Array

Field Name	Type	Required	Description
`ShiftId`	string	No	The unique identifier (UID) in our system of a shift that should be updated with a new data. If received, the value should have a 24 character hexadecimal string format and belong to the existing, non-deleted shift. If a shift is received in this array with this request but without this field, a new shift is created if it does not violate the logic described in the `Shifts` description and all its parameters are valid and based on the logic described below in each of the parameters.
`ExternalShiftId`	string	No	The shift's ID provided by external publisher. If provided, the ID should be unique within a company.
`BusinessDate`	string	Yes	The business date to which a received shift should belong. This parameter should consider the site’s business date start date and time.
`EmployeeCorporateCode`	string	No*	The employee internal, readable ID in our system. *This parameter is required if if the `EmployeeId` parameter is not received. If both the `EmployeeId` and `EmployeeCorporateCode` parameters are received, then the `EmployeeId` parameter has higher priority and `EmployeeCorporateCode` value will be ignored. If `EmployeeCorporateCode` is received, it should belong to the existing, non-deleted employee.
`EmployeeId`	string	No*	The employee unique database ID in our system. *This parameter is required if the `EmployeeCorporateCode` parameter is not received. If both the `EmployeeId` and `EmployeeCorporateCode` parameters are received, then the `EmployeeId` parameter has higher priority and `EmployeeCorporateCode` value will be ignored. If this parameter is received, received value should have a 24 character hexadecimal string format. If `EmployeeId` is received, it should belong to the existing, non-deleted employee.
`JobCodeId`	string	No*	The Data Management UID of the job code that should be associated with this shift record. An employee must have a non-deleted job record within the received site and with this job code for this schedule to be successfully saved. A list of available job codes in our system can be requested using the GET /Staff/JobCode endpoint. *This parameter is required if the `ExternalJobCodeId` parameter is not received. If both `JobCodeId` and `ExternalJobCodeId` parameters are received, then the `JobCodeId` parameter has higher priority and `ExternalJobCodeId` value will be ignored. If the `JobCodeId` parameter is received, received value should have a 24 character hexadecimal string format.
`ExternalJobCodeId`	string	No*	The Data Management `external_id` of the job code that should be associated with this shift record. Using this code, the received site ID in the `X-SITE-IDs` header, and the identified employee, a non-deleted employee’s job code could be identified by our system to verify that such a job code exists in Data Management. *This parameter is required if the `JobCodeId` parameter is not received.
`StartTime`	string	Yes	The shift’s start date and time. The date/time should be provided in the UTC - YYYY-MM-DDTHH:MM:SS.SSSZ format and cannot be null or "".
`EndTime`	string	Yes	The shift’s end date and time. The date/time should be provided in the UTC - YYYY-MM-DDTHH:MM:SS.SSSZ format and cannot be null or "".

PutSchedulesResponseBody

Field Name	Type	Required	Description
`ScheduleId`	string	Yes	The internal unique identifier (UID) in our system of the updated schedule
`StartDate`	string	Yes	The start date of the updated schedule. The date/time is returned in the UTC - YYYY-MM-DDTHH:MM:SS.SSSZ format.
`EndDate`	string	Yes	The end date of the updated schedule. The date/time is returned in the UTC - YYYY-MM-DDTHH:MM:SS.SSSZ format.
`Source`	string	Yes	The source-system name. The value is `null` if it was not received in the request.
`Timezone`	string	Yes	The value received in the initial schedule create request.
`ModifyTime`	string	Yes	The Coordinated Universal Time (UTC) timestamp of the record was updated in the database. The date/time is returned in the UTC - YYYY-MM-DDTHH:MM:SS.SSSZ format.
`Shifts`	PutShiftsResponseBody Array	Yes	A list of successfully updated child shifts and shifts that have already existed for this schedule before. Only non-deleted shifts are returned in the response.

PutShiftsResponseBody Array

Field Name	Type	Required	Description
`ShiftId`	string	Yes	The unique identifier (UID) in our system of the schedule’s shift
`ExternalShiftId`	string	No	The shift's ID provided by external publisher. The field is present in a response if it was received in the current or a previous request.
`BusinessDate`	string	Yes	The received business date. The date is returned in the YYYY-MM-DD format without additional timezone conversions
`StartTime`	string	Yes	The shift's start time. The date is returned in the YYYY-MM-DDTHH:MM:SS.SSSZ format.
`EndTime`	string	Yes	The shift’s end time. The date is returned in the YYYY-MM-DDTHH:MM:SS.SSSZ format.
`EmployeeCorporateCode`	string	No	The employee internal, readable ID in our system.
`EmployeeId`	string	No	The employee unique database ID in our system.
`JobCodeId`	string	No	The Data Management unique identifier (UID) of the job code
`ExternalJobCodeId`	string	No	The Data Management `external_id` of the job code that should be associated with this shift record. The field is present in a response if it was received in a request.
`ModifyTime`	string	Yes	The Coordinated Universal Time (UTC) timestamp of the shift's create time or the last update to the shift's record. The date is returned in the YYYY-MM-DDTHH:MM:SS.SSSZ format.

GetExternalGeneralPayrollGetUpdatesResponseBody

Field Name

Type

Required

Description

PayrolDetailId

string/HEX24

Yes

The Genius Staff unique identifier (UID) of the payroll record

EmployeeId

string/HEX24

Yes

The Genius Staff UID of the employee related to the returned payroll record

ShiftId

string/HEX24

Yes

The Genius Staff UID of the shift related to the returned payroll record

TenderTypeCode

string

Yes

Only for not null values. The payment type code associated with the tips payroll record null for non-tips payroll details.

BusinessDate

string/date

Yes

The date representing the business day associated with the payroll record in YYYY-MM-DD format

ClockIn

string/datetime UTC

Yes

The timestamp start for the returned payroll record in YYYY-MM-DDTHH:MM:SSZ format

ClockOut

string/datetime UTC

Yes

The timestamp end for the returned payroll record in YYYY-MM-DDTHH:MM:SSZ format

JobCodeId

string/HEX24

Yes

The entity_id of the Job Code record from Genius Data Management from the active employee job related to the returned payroll record

ExternalJobCodeId

string

Yes

The Genius Data Management external_id associated with the returned JobCodeId. The value can be null if not configured

Rate

number/decimal (2)

Yes

The monetary rate of pay for an employee for a payroll record

CompensationTypeCode

string

Yes

A code representing the type of compensation assigned to the employee. Supported values:

Code	Name
`SLRY`	Salary
`HOUR`	Hourly

Multiplier

number/decimal (2)

Yes

A numeric factor used to adjust the employee’s base rate of pay associated with the payroll record

Hours

number/decimal (2)

Yes

The total number of hours associated with the payroll record

TotalPay

number/decimal (2)

Yes

The total monetary amount earned by the employee associated with the payroll record. It is usually the result of multiplying Rate × Multiplier × Hours, with exceptions for certain payroll rules.

PayRuleId

string/HEX24

Yes

The UID of the pay rule applied to the employee’s payroll record.

The value is null for payroll details generated not based on a specific pay rule, such as regular hours and tips.

RateTypeCode

string

Yes

A code representing the type of pay rate applied to the payroll record. Supported values:

Code	Name
`CNSDA`	Consecutive Days
`CNSHR`	Consecutive Hours
`MWADJ`	Minimum Wage Adjustment
`OTD`	Daily Overtime
`OTW`	Weekly Overtime
`REG`	Regular Rate
`SHDIF`	Shift Differential
`TIP`	Tip
`UNPDBRK`	Unpaid break
`FLCTHR`	Fluctuating Hours
`PDBRK`	Paid Break
`MBP`	Missed Breaks Penalty

WorkTypeCode

string

Yes

A code representing the type of work performed by the employee associated with this payroll record. Supported values:

Code	Name
`PAYR`	Payroll Generated Time
`WORK`	Work Time
`SICK`	Sick
`VACA`	Vacation
`HOLI`	Holiday
`BREAK`	Break

SiteId

string/HEX24

Yes

The UID of the site or location where the employee performed the work

IsStillClockedIn

boolean

Yes

A flag indicating whether the employee is clocked in currently that is illustrated as the current automatically generated payroll record

IsActive

boolean

Yes

A flag indicating whether the current payroll record is active currently

DeleteDate

string/datetime UTC with ms

Yes

The date and time when the record was deleted in YYYY-MM-DDTHH:MM:SS.SSSZ format.

The value is null for non-deleted payroll details.

UpdateDate

string/datetime UTC with ms

Yes

The date and time when the record was last updated in YYYY-MM-DDTHH:MM:SS.SSSZ format

Sample Response Body - General Structure with Non-deleted and Deleted Shifts

{
    "Data": [
        {
            "PayrollDetailId": string,
            "EmployeeId": string,
            "ShiftId": string,
            "TenderTypeCode": string,
            "BusinessDate": string,
            "ClockIn": string,
            "ClockOut": string,
            "JobCodeId": string,
            "ExternalJobCodeId": string,
            "Rate": number,
            "CompensationTypeCode": string,
            "Multiplier": number,
            "Hours": number,
            "TotalPay": number,
            "PayRuleId": string,
            "RateTypeCode": string,
            "WorkTypeCode": string,
            "SiteId": string,
            "IsStillClockedIn": boolean,
            "IsActive": boolean,
            "DeleteDate": string,
            "UpdateDate": string
        }
    ],
    "NextUpdateDateFrom": string
}

Sample Response Body - An Example of a Fully Successful Request

{
    "Data": [
        {
            "PayrollDetailId": "67dc38a68b5444a9945bd884",
            "EmployeeId": "67c8e75bbf2e4917b7a4bd1e",
            "ShiftId": "5ba8a738b51fed0001c4f3aa",
            "TenderTypeCode": "CREDIT",
            "BusinessDate": "2025-03-20",
            "ClockIn": "2025-03-20T14:44:04Z",
            "ClockOut": "2025-03-20T15:47:48Z",
            "JobCodeId": "6001e52c0d0d87003fbbab34",
            "ExternalJobCodeId": "22",
            "Rate": 4.76,
            "CompensationTypeCode": "HOURLY",
            "Multiplier": 1.0,
            "Hours": 1.0,
            "TotalPay": 4.76,
            "PayRuleId": null,
            "RateTypeCode": "TIP",
            "WorkTypeCode": "WORK",
            "SiteId": "66f5a8c257fc474b68d34c65",
            "IsStillClockedIn": false,
            "IsActive": true,
            "DeleteDate": null,
            "UpdateDate": "2025-03-20T15:47:50.000Z"
        },
        {
            "PayrollDetailId": "67dcf7483b72d6b77f5a6df4",
            "EmployeeId": "62a8c68df86994d976ccd456",
            "ShiftId": "5ca7450592e8d60011dc0d21",
            "TenderTypeCode": null,
            "BusinessDate": "2025-03-20",
            "ClockIn": "2025-03-21T05:19:48Z",
            "ClockOut": "2025-03-21T05:19:48Z",
            "JobCodeId": "6001e52c0d0d87003fbbab34",
            "ExternalJobCodeId": "22",
            "Rate": 17,
            "CompensationTypeCode": "HOURLY",
            "Multiplier": 1.5,
            "Hours": 0.02,
            "TotalPay": 0.51,
            "PayRuleId": "60a4fe6d91e8dd003f7d658b",
            "RateTypeCode": "OTD",
            "WorkTypeCode": "WORK",
            "SiteId": "620a91dfd2d8f300082bf8c8",
            "IsStillClockedIn": true,
            "IsActive": false,
            "DeleteDate": "2025-03-21T05:25:18.265Z",
            "UpdateDate": "2025-03-21T05:25:18.000Z"
        }
    ],
    "NextUpdateDateFrom": "2025-03-21T05:25:18.000Z"
}

GetEthnicityResponseBody

Field Name	Type	Description
`EthnicityId`	string	The employee's ethnicity identifier (ID)
`Description`	string	The description of the employee's ethnicity
`IsActive`	boolean	Sending the `false` value in this field for a specific ethnicity deletes this ethnicity record in the Back Office database (soft-deleted - still present but no longer available). The valid values are true and false.
`Name`	string	The ethnicity name
`Code`	string	The ethnicity code
`Source`	string	The name of the source system from which employee ethnicity record is being imported
`ActualUpdateDate`	string/date	The actual date of the update to the records

GetEmployeeStatusResponseBody

Field Name	Type	Description
`Data`	Data Array	A list of the employee status information
`TotalCount`	number	The number of data items in the response

GetEmployeeStatus Data Array

Field Name	Type	Description
`EmployeeStatusId`	string	The employee status identifier
`Description`	string	The employee status description. For example, "Active".
`IsActive`	boolean	Sending the `false` value in this field for a specific employee status deletes this employee status record in the Back Office database (soft-deleted - still present but no longer available). The valid values are true and false.
`SiteId`	string	The employee's worksite identifier
`Name`	string	The employee status name
`Code`	string	The employee status code

GetCompanyRolesResponseBody

Field Name	Type	Description
`Id`	string	The company role identifier
`Name`	string	The company role name

Get Company Roles Sample Code

Sample Response Body

[
    {
        "Id": "63da469cb5c13514ecaeac10",
        "Name": "Cashier"
    },
    {
        "Id": "63da4601b5c13514ecaeac0c",
        "Name": "Company Administrator"
    },
    {
        "Id": "63da46a9b5c13514ecaeac11",
        "Name": "Manager"
    }
]

GetAllJobsResponseBody

Field Name	Type	Description
`JobCodeId`	string	The job code unique identifier (UID)
`JobCodeUsageTypeIds`	array	A list of UIDs for the job code usage types, such as `Punch`, `Schedules`
`Name`	string	The job code name
`JobCodeCategoryId`	string	The job code category identifier
`IsManagerialPosition`	boolean	The flag that indicates if the job code is managerial
`AllowPrimaryPosition`	boolean	The flag that indicates whether to all the primary position
`IsActive`	boolean	The flag that indicates if the job code is active
`StandardShiftLengthHours`	number	The standard shift length by hours
`JobTipCategoryId`	string	The job tip category identifier
`DefaultPosSecurityLevelId`	string	The default point of sale (POS) security-level identifier
`JobColor`	string	The job color. For example, "#999999".
`ParentJobCodeId`	string	The parent job code identifier
`SiteId`	string	The job code site identifier

Get All Jobs Sample Code

Sample Response Body

{
            "JobCodeUsageTypeIds": [
                "9999999999999999"
            ],
            "JobCodeId": "9999999999999999",
            "Name": "Manager",
            "JobCodeCategoryId": "9999999999999999",
            "IsManagerialPosition": true,
            "AllowPrimaryPosition": true,
            "IsActive": true,
            "StandardShiftLengthHours": 8,
            "JobTipCategoryId": "9999999999999999",
            "DefaultPosSecurityLevelId": "9999999999999999",
            "JobColor": "#999999",
            "ParentJobCodeId": null,
            "SiteId": "9999999999999999"
        },
        {
            "JobCodeUsageTypeIds": [
                "9999999999999999",
                "9999999999999999"
            ],
            "JobCodeId": "9999999999999999",
            "Name": "Crew Member",
            "JobCodeCategoryId": "9999999999999999",
            "IsManagerialPosition": false,
            "AllowPrimaryPosition": true,
            "IsActive": true,
            "StandardShiftLengthHours": 7,
            "JobTipCategoryId": "9999999999999999",
            "DefaultPosSecurityLevelId": null,
            "JobColor": "#999999",
            "ParentJobCodeId": null,
            "SiteId": "9999999999999999"
        },

GetLookupStateResponseBody

Field Name	Type	Description
`Data`	array	The list of state items
`StateId`	string	The state identifier
`CountryId`	string	The state's country identifier
`SiteId`	string	The site identifier for the state, if applicable
`Name`	string	The state name
`Code`	string	The state code
`Source`	string	The name of the source system from which compensation type records are being imported
`ActualUpdateDate`	string	The date the record was updated
`TotalCount`	number	The number of data lists in the response

Sample Response Body

{
    "Data": [
        {
            "StateId": "58f515ff736c128b640d5852",
            "CountryId": "58f4f1ff736c128b640d584b",
            "SiteId": null,
            "Name": "Alaska",
            "Code": "AK",
            "Source": null,
            "ActualUpdateDate": "0001-01-01T00:00:00.000"
        },
        {
            "StateId": "58f5171b736c128b640d5885",
            "CountryId": "58f4f1ff736c128b640d584b",
            "SiteId": null,
            "Name": "Washington",
            "Code": "WA",
            "Source": null,
            "ActualUpdateDate": "0001-01-01T00:00:00.000"
        },
    ],
    "TotalCount": 2
}

GetLookupCountryResponseBody

Field Name	Type	Description
`Data`	array	The list of country items
`CountryId`	string	The country identifier
`SiteId`	string	The site identifier for the country, if applicable
`Name`	string	The country name
`Code`	string	The country code
`Source`	string	The name of the source system from which compensation type records are being imported
`ActualUpdateDate`	string	The data the record was updated
`TotalCount`	number	The number of data lists in the response

Sample Response Body

{
    "Data": [
        {
            "CountryId": "58f4f1ff736c128b640d584b",
            "SiteId": null,
            "Name": "United States",
            "Code": "US",
            "Source": null,
            "ActualUpdateDate": "0001-01-01T00:00:00.000"
        }
    ],
    "TotalCount": 1
}

GetLookupTenderTypeResponseBody

Field Name	Type	Description
`Data`	array	The tender type information
`TenderTypeId`	string	The tender type unique identifier (UID)
`Description`	string	The tender type description
`IsActive`	boolean	A flag that shows if the tender type is active
`SiteId`	string	The site UID
`Name`	string	The tender type name
`Code`	string	The tender type code
`ActualUpdateDate`	string	The actual date of the update to the records

Sample Response Body

{
    "Data": [
        {
            "TenderTypeId": "58ad7fdf7e6ae011068ff492",
            "Description": null,
            "IsActive": true,
            "SiteId": null,
            "Name": "Cash",
            "Code": "CASH",
            "Source": null,
            "ActualUpdateDate": "0001-01-01T00:00:00.000"
        },
        {
            "TenderTypeId": "58ad800d7e6ae011068ff494",
            "Description": null,
            "IsActive": true,
            "SiteId": null,
            "Name": "Credit*",
            "Code": "CREDIT",
            "Source": null,
            "ActualUpdateDate": "0001-01-01T00:00:00.000"
        }
    ],
    "TotalCount": 2
}

GetLookupTenderCurrencyResponseBody

Field Name	Type	Description
`Data`	array	The currency information
`TenderCurrencyId`	string	The unique identifier (UID) for the currency
`Description`	string	The description for the currency
`IsDefault`	boolean	A flag that shows if the currency in the response is the default currency for the company identified
`IsActive`	boolean	A flag that shows if the currency is active
`SiteId`	string	The site UID
`Name`	string	The name of the currency
`Code`	string	The code for the currency
`Source`	string	The source for the record
`ActualUpdateDate`	string	The actual date of the update to the records
`TotalCount`	number	The number of data items in the response

Sample Response Body

{
    "Data": [
        {
            "TenderCurrencyId": "56f7712eb8e30b8e5bbbc9af",
            "Description": "United States Dollars",
            "IsDefault": true,
            "IsActive": true,
            "SiteId": null,
            "Name": "USD",
            "Code": "USD",
            "Source": null,
            "ActualUpdateDate": "0001-01-01T00:00:00.000"
        }
    ],
    "TotalCount": 1
}

GetExternalGeneralShiftUpdatesResponseBody

For this response body:

The response size is limited to no more than 100 shifts returned at a time. For pagination needs, the NextUpdateDateFrom field can be used in order not to miss data.
- In order to request another 100 batch, a value received in the response in the NextUpdateDateFrom field in the first request should be sent in the UpdateDateFrom query parameter in the next request. This approach should be repeated until Data array is returned empty, which is a marker that all updates have already been provided.
- If no shifts were found based on the received time values, NextUpdateDateFrom field will contain the same timestamp as sent in the request in the UpdateDateFrom parameter.
Data in response is sorted by shifts' update_date earliest entries.

Field Name	Type	Required	Description
`ShiftId`	string	Yes	The Staff API unique identifier (UID) for the shift that is being created
`EmployeeId`	string	Yes	The Staff API UID for the employee related to the created shift
`EmployeeCorporateCode`	string	Yes	The readable identifier for the employee related to the returned shift. This is the value stored in the Employee Corporate Code field in the employee profile in Staff API.
`ExternalEmployeeId`	string	Yes	The external identifier for the employee related to the created shift, received from external systems or null
`JobName`	string	Yes	The name of the job code from Data Management from the active employee job related to the created shift
`JobCodeId`	string	Yes	The `entity_id` of the job code record from Data Management from the active employee job related to the created shift
`ExternalJobCodeId`	string	Yes	The Data Management `external_id` of the job code rate or job code from the employee job associated with this shift
`StartDateTime`	string	Yes	The shift’s start date time returned in the YYYY-MM-DDTHH:MM:SSZ Coordinated Universal Time (UTC) format
`EndDateTime`	string	Yes	The shift’s end date time returned in the YYYY-MM-DDTHH:MM:SSZ UTC format or null if this shift is open
`Status`	string	Yes	The shift's status in the database: `CLOCKED_IN`: The employee is not on a break and currently actively working. `ON_BREAK`: The employee is currently on a break. `CLOCKED_OUT`: A shift is closed.
`IsActive`	boolean	Yes	A flag that shows that this shift is non-deleted. Always = `true`.
`SiteId`	string	Yes	The UID in our system of a site associated with the currently created shift
`Source`	string	Yes	The name of the source system from which this shift was imported or "" if a shift was created in Staff API or was imported without external system specified
`ActualUpdateDate`	string	Yes	The last time the current shift was created or updated through the API call in the YYYY-MM-DDTHH:MM:SS.SSSZ UTC format
`Breaks`	array of objects	Yes	Each break is displayed as a separate object inside this array. If there are no breaks within the currently created shift, this array is returned as `Breaks:[]`.
`Breaks.BreakStartDateTime`	string	Yes*	The break’s start date time returned in the YYYY-MM-DDTHH:MM:SSZ UTC format. *Absent only when there are no breaks for a shift. Otherwise, this parameter must be present with a corresponding value.
`Breaks.BreakEndDateTime`	string	Yes*	The break’s end date time returned in the YYYY-MM-DDTHH:MM:SSZ UTC format or null if this break is open. *Absent only when there are no breaks for a shift. Otherwise, this parameter must be present with a corresponding value or null if a break is still open.
`Breaks.BreakTypeCode`	string	Yes*	Break Type Code from the Break Time configuration in Data Management. `MEAL`, `REST`, `UNKNOWN`. `UNKNOWN` for cases when no configuration for the received `BreakTypeCode` and `IsPaidBreak` was found. *Absent only when there are no breaks for a shift. Otherwise, this parameter must be present with a corresponding value.
`Breaks.IsPaidBreak`	boolean	Yes*	A flag showing whether the received break is paid or not. Taken from the found Break Time configuration in Data Management or taken from a default record for cases when no configuration for the received `BreakTypeCode` and `IsPaidBreak` was found. *Absent only when there are no breaks for a shift. Otherwise, this parameter must be present with a corresponding value.
`Tips`	array of objects	Yes	A list of unique tip records received for the currently created shift that was successfully created in the database, aggregated by `TenderCategoryCode`, `TenderTypeCode`, and `TenderCurrencyCode`. If a result shift has no tip transactions created, this array is returned as `"Tips": [].`
`Tips.TenderCategoryCode`	string	Yes*	The identifier of the tip type - Direct (`DTIP`) or Indirect (`IDTIP`). *Absent only when there are no tips for a shift.
`Tips.TenderTypeCode`	string	Yes*	The code of the payment class associated with a tip record that was created. *Absent only when there are no tips for a shift.
`Tips.TenderCurrencyCode`	string	Yes*	The code of the tender currency associated with a tip record that was created. *Absent only when there are no tips for a shift.
`Tips.Amount`	number/decimal	Yes*	The total tips amount for this particular tender type. *Absent only when there are no tips for a shift.
`Sales`	array of objects	Yes	A list of unique sales records received for the currently created shift that was successfully created in the database, aggregated by `TenderTypeCode` and `TenderCurrencyCode`. If a result shift has no sales transactions created, this array is returned as `"Sales": []`.
`Sales.TenderTypeCode`	string	Yes*	The code of the payment class associated with a sales record that was created. *Absent only when there are no sales for a shift.
`Sales.TenderCurrencyCode`	string	Yes*	The code of the tender currency associated with a sales record that was created. *Absent only when there are no sales for a shift.
`Sales.Amount`	number/decimal	Yes*	The total sales amount for this particular tender type. *Absent only when there are no sales for a shift.

GetExternalGeneralShiftByBusinessDateResponseBody

For this response body:

The endpoint supports pagination using the PageNumber query parameter and a TotalCount field from a response.
Data in response is sorted by shifts' create_date earliest entries.

Field Name	Type	Required	Description
`ShiftId`	string	Yes	The Staff API unique identifier (UID) for the shift that is being created
`EmployeeId`	string	Yes	The Staff API UID for the employee related to the created shift
`EmployeeCorporateCode`	string	Yes	The readable identifier for the employee related to the returned shift. This is the value stored in the Employee Corporate Code field in the employee profile in Staff API.
`ExternalEmployeeId`	string	Yes	The external identifier for the employee related to the created shift, received from external systems or null
`JobName`	string	Yes	The name of the job code from Data Management from the active employee job related to the created shift
`JobCodeId`	string	Yes	The `entity_id` of the job code record from Data Management from the active employee job related to the created shift
`ExternalJobCodeId`	string	Yes	The Data Management `external_id` of the job code rate or job code from the employee job associated with this shift
`StartDateTime`	string	Yes	The shift’s start date time returned in the YYYY-MM-DDTHH:MM:SSZ Coordinated Universal Time (UTC) format
`EndDateTime`	string	Yes	The shift’s end date time returned in the YYYY-MM-DDTHH:MM:SSZ UTC format or null if this shift is open
`Status`	string	Yes	The shift's status in the database: `CLOCKED_IN`: The employee is not on a break and currently actively working. `ON_BREAK`: The employee is currently on a break. `CLOCKED_OUT`: A shift is closed.
`IsActive`	boolean	Yes	A flag that shows that this shift is non-deleted. Always = `true`.
`SiteId`	string	Yes	The UID in our system of a site associated with the currently created shift
`Source`	string	Yes	The name of the source system from which this shift was imported or "" if a shift was created in Staff API or was imported without external system specified
`ActualUpdateDate`	string	Yes	The last time the current shift was created or updated through the API call in the YYYY-MM-DDTHH:MM:SS.SSSZ UTC format
`Breaks`	array of objects	Yes	Each break is displayed as a separate object inside this array. If there are no breaks within the currently created shift, this array is returned as `Breaks:[]`.
`Breaks.BreakStartDateTime`	string	Yes*	The break’s start date time returned in the YYYY-MM-DDTHH:MM:SSZ UTC format. *Absent only when there are no breaks for a shift. Otherwise, this parameter must be present with a corresponding value.
`Breaks.BreakEndDateTime`	string	Yes*	The break’s end date time returned in the YYYY-MM-DDTHH:MM:SSZ UTC format or null if this break is open. *Absent only when there are no breaks for a shift. Otherwise, this parameter must be present with a corresponding value or null if a break is still open.
`Breaks.BreakTypeCode`	string	Yes*	Break Type Code from the Break Time configuration in Data Management. `MEAL`, `REST`, `UNKNOWN`. `UNKNOWN` for cases when no configuration for the received `BreakTypeCode` and `IsPaidBreak` was found. *Absent only when there are no breaks for a shift. Otherwise, this parameter must be present with a corresponding value.
`Breaks.IsPaidBreak`	boolean	Yes*	A flag showing whether the received break is paid or not. Taken from the found Break Time configuration in Data Management or taken from a default record for cases when no configuration for the received `BreakTypeCode` and `IsPaidBreak` was found. *Absent only when there are no breaks for a shift. Otherwise, this parameter must be present with a corresponding value.
`Tips`	array of objects	Yes	A list of unique tip records received for the currently created shift that was successfully created in the database, aggregated by `TenderCategoryCode`, `TenderTypeCode`, and `TenderCurrencyCode`. If a result shift has no tip transactions created, this array is returned as `"Tips": [].`
`Tips.TenderCategoryCode`	string	Yes*	The identifier of the tip type - Direct (`DTIP`) or Indirect (`IDTIP`). *Absent only when there are no tips for a shift.
`Tips.TenderTypeCode`	string	Yes*	The code of the payment class associated with a tip record that was created. *Absent only when there are no tips for a shift.
`Tips.TenderCurrencyCode`	string	Yes*	The code of the tender currency associated with a tip record that was created. *Absent only when there are no tips for a shift.
`Tips.Amount`	number/decimal	Yes*	The total tips amount for this particular tender type. *Absent only when there are no tips for a shift.
`Sales`	array of objects	Yes	A list of unique sales records received for the currently created shift that was successfully created in the database, aggregated by `TenderTypeCode` and `TenderCurrencyCode`. If a result shift has no sales transactions created, this array is returned as `"Sales": []`.
`Sales.TenderTypeCode`	string	Yes*	The code of the payment class associated with a sales record that was created. *Absent only when there are no sales for a shift.
`Sales.TenderCurrencyCode`	string	Yes*	The code of the tender currency associated with a sales record that was created. *Absent only when there are no sales for a shift.
`Sales.Amount`	number/decimal	Yes*	The total sales amount for this particular tender type. *Absent only when there are no sales for a shift.

GetExternalGeneralShiftByShiftIDsResponseBody

For this response body:

The endpoint always returns information about deleted and active shifts without additional query parameters.
Data in response is sorted by shifts' create_date earliest entries.

Field Name	Type	Required	Description
`ShiftId`	string	Yes	The Staff API unique identifier (UID) for the shift that is being created
`EmployeeId`	string	Yes	The Staff API UID for the employee related to the created shift
`EmployeeCorporateCode`	string	Yes	The readable identifier for the employee related to the returned shift. This is the value stored in the Employee Corporate Code field in the employee profile in Staff API.
`ExternalEmployeeId`	string	Yes	The external identifier for the employee related to the created shift, received from external systems or null
`JobName`	string	Yes	The name of the job code from Data Management from the active employee job related to the created shift
`JobCodeId`	string	Yes	The `entity_id` of the job code record from Data Management from the active employee job related to the created shift
`ExternalJobCodeId`	string	Yes	The Data Management `external_id` of the job code rate or job code from the employee job associated with this shift
`StartDateTime`	string	Yes	The shift’s start date time returned in the YYYY-MM-DDTHH:MM:SSZ Coordinated Universal Time (UTC) format
`EndDateTime`	string	Yes	The shift’s end date time returned in the YYYY-MM-DDTHH:MM:SSZ UTC format or null if this shift is open
`Status`	string	Yes	The shift's status in the database: `CLOCKED_IN`: The employee is not on a break and currently actively working. `ON_BREAK`: The employee is currently on a break. `CLOCKED_OUT`: A shift is closed.
`IsActive`	boolean	Yes	A flag that shows that this shift is non-deleted. Always = `true`.
`SiteId`	string	Yes	The UID in our system of a site associated with the currently created shift
`Source`	string	Yes	The name of the source system from which this shift was imported or "" if a shift was created in Staff API or was imported without external system specified
`ActualUpdateDate`	string	Yes	The last time the current shift was created or updated through the API call in the YYYY-MM-DDTHH:MM:SS.SSSZ UTC format
`Breaks`	array of objects	Yes	Each break is displayed as a separate object inside this array. If there are no breaks within the currently created shift, this array is returned as `Breaks:[]`.
`Breaks.BreakStartDateTime`	string	Yes*	The break’s start date time returned in the YYYY-MM-DDTHH:MM:SSZ UTC format. *Absent only when there are no breaks for a shift. Otherwise, this parameter must be present with a corresponding value.
`Breaks.BreakEndDateTime`	string	Yes*	The break’s end date time returned in the YYYY-MM-DDTHH:MM:SSZ UTC format or null if this break is open. *Absent only when there are no breaks for a shift. Otherwise, this parameter must be present with a corresponding value or null if a break is still open.
`Breaks.BreakTypeCode`	string	Yes*	Break Type Code from the Break Time configuration in Data Management. `MEAL`, `REST`, `UNKNOWN`. `UNKNOWN` for cases when no configuration for the received `BreakTypeCode` and `IsPaidBreak` was found. *Absent only when there are no breaks for a shift. Otherwise, this parameter must be present with a corresponding value.
`Breaks.IsPaidBreak`	boolean	Yes*	A flag showing whether the received break is paid or not. Taken from the found Break Time configuration in Data Management or taken from a default record for cases when no configuration for the received `BreakTypeCode` and `IsPaidBreak` was found. *Absent only when there are no breaks for a shift. Otherwise, this parameter must be present with a corresponding value.
`Tips`	array of objects	Yes	A list of unique tip records received for the currently created shift that was successfully created in the database, aggregated by `TenderCategoryCode`, `TenderTypeCode`, and `TenderCurrencyCode`. If a result shift has no tip transactions created, this array is returned as `"Tips": [].`
`Tips.TenderCategoryCode`	string	Yes*	The identifier of the tip type - Direct (`DTIP`) or Indirect (`IDTIP`). *Absent only when there are no tips for a shift.
`Tips.TenderTypeCode`	string	Yes*	The code of the payment class associated with a tip record that was created. *Absent only when there are no tips for a shift.
`Tips.TenderCurrencyCode`	string	Yes*	The code of the tender currency associated with a tip record that was created. *Absent only when there are no tips for a shift.
`Tips.Amount`	number/decimal	Yes*	The total tips amount for this particular tender type. *Absent only when there are no tips for a shift.
`Sales`	array of objects	Yes	A list of unique sales records received for the currently created shift that was successfully created in the database, aggregated by `TenderTypeCode` and `TenderCurrencyCode`. If a result shift has no sales transactions created, this array is returned as `"Sales": []`.
`Sales.TenderTypeCode`	string	Yes*	The code of the payment class associated with a sales record that was created. *Absent only when there are no sales for a shift.
`Sales.TenderCurrencyCode`	string	Yes*	The code of the tender currency associated with a sales record that was created. *Absent only when there are no sales for a shift.
`Sales.Amount`	number/decimal	Yes*	The total sales amount for this particular tender type. *Absent only when there are no sales for a shift.

GetSchedulesResponseBody

Field Name	Type	Required	Description
`items`	items Array	Yes	An array that contains information about all found schedules together with their child shifts
`$top`	integer	No	The maximum number of items
`$skip`	integer	No	The number of first items skipped from the query
`$page_size`	integer	Yes	The total number of items inside the `items` array

items Array

Field Name	Type	Required	Description
`ScheduleId`	string	Yes	The internal unique identifier (UID) in our system of the schedule
`CompanyId`	string	Yes	The UID in our system of a source company for which a schedule a created
`SiteId`	string	Yes	The UID in our system of the source site
`StartDate`	string	Yes	The start date of the schedule. The date/time is returned in the UTC - YYYY-MM-DDTHH:MM:SS.SSSZ format.
`EndDate`	string	Yes	The end date of the schedule. The date/time is returned in the UTC - YYYY-MM-DDTHH:MM:SS.SSSZ format.
`IsActive`	boolean	Yes	A flag that indicates that the schedule is active. The value is always `true`.
`Source`	string	No	The source-system name from where this schedule was imported. The field is present in a response if it was received in the initial creation or update request.
`ModifyTime`	string	Yes	The Coordinated Universal Time (UTC) timestamp of the record was last updated in the database. The date/time is returned in the UTC - YYYY-MM-DDTHH:MM:SS.SSSZ format.
`Shifts`	GetShiftsResponseBody Array	Yes	This array contains a list of child shifts, non-deleted only

GetShiftsResponseBody Array

Field Name	Type	Required	Description
`ShiftId`	string	Yes	The unique identifier (UID) in our system of the schedule’s shift
`ScheduleId`	string	Yes	The parent schedule ID
`ExternalShiftId`	string	No	The shift's ID provided by external publisher. The field is present in a response if it was received in the initial creation or update request.
`BusinessDate`	string	Yes	The store's business date in local time. The date is returned in the YYYY-MM-DD format without additional timezone conversions
`StartTime`	string	Yes	The shift's start time in local time. The date is returned in the YYYY-MM-DDTHH:MM:SS.SSSZ format.
`EndTime`	string	Yes	The shift’s end time in local time. The date is returned in the YYYY-MM-DDTHH:MM:SS.SSSZ format.
`EmployeeCorporateCode`	string	No	The employee internal, readable ID in our system.
`EmployeeId`	string	No	The employee unique database ID in our system.
`JobCodeId`	string	No	The Data Management unique identifier (UID) of the job code
`ExternalJobCodeId`	string	No	The Data Management `external_id` of the job code that should be associated with this shift record. The field is present in a response if it was received in a request.
`ModifyTime`	string	Yes	The Coordinated Universal Time (UTC) timestamp of the shift's create time or the last update to the shift's record. The date is returned in the YYYY-MM-DDTHH:MM:SS.SSSZ format.
`CompanyId`	string	Yes	The UID in our system of a source company for which a schedule a created

General Structure | GetExternalGeneralEmployeeResponseBody

For this response body:

All child arrays including EmployeePhones, EmployeeAddresses, EmployeeEmails, EmployeeContacts, EmployeeJobs, EmployeeSiteStatuses, and PosCredentials plus the AdditionalDetails object are returned in the response body only if these parameters are included in the selectNested query parameter list.
Each child array is returned with all its fields described below if at least one active, non-deleted child record exists for the employee. For example, for the EmployeePhones array at least one non-deleted phone record. If no child records exist, the corresponding arrays are returned as empty [].

Field Name	Type	Required	Description
`EmployeeId`	string	Yes	The 24-character hexadecimal string uniquely identifying the employee in the Staff database
`Firstname`	string	Yes	The employee’s first name
`Lastname`	string	Yes	The employee's last name
`Middlename`	string	Yes	The employee’s middle name or patronymic, if applicable
`Name`	string	Yes	The concatenated value of `Firstname` and `Lastname`
`Username`	string	Yes	The employee’s email address
`EmployeeCorporateCode`	string	Yes	The unique, readable identifier assigned to the employee. This field is used for internal identification within the company.
`ExternalEmployeeId`	string	Yes	The unique identifier (UID) of the employee in an external system. This field is used to link or synchronize employee data across systems.
`PrimarySiteId`	string	Yes	The Genius Portal identifier of the employee’s main work site
`Source`	string	Yes	Indicates the origin of the employee record
`LastUpdateDate`	string/date and time with ms	Yes	The Coordinated Universal Time (UTC) timestamp when this employee record was last time updated in the database For example, YYYY-MM-DD-THH:MM:SS.SSSZ.
`IsActive`	boolean	Yes	A flag showing if employee is deleted.
`AdditionalDetails`	AdditionalDetails Object	No	An optional field for extra information about the employee such as birth date and tax identifier
`EmployeePhones`	EmployeePhones Array	No	A list of the employee’s phone numbers
`EmployeeAddresses`	EmployeeAddresses Array	No	A list of the employee’s addresses
`EmployeeContacts`	EmployeeContacts Array	No	A list of the employee’s emergency contacts
`EmployeeEmails`	EmployeeEmails Array	No	A list of the employee’s email addresses
`EmployeeJobs`	EmployeeJobs Array	No	A list of the employee’s job positions within the company. For the endpoints using the `X-SITE-IDs` header, all non-deleted employee jobs are returned in the response, if requested, regardless of the sites provided in the `X-SITE-IDs` header.
`EmployeeSiteStatuses`	EmployeeSiteStatues Array	No	A list of the employee’s statuses at different sites, such as `active`, `inactive`, and `on leave`. These fields are used to track availability and work location assignments. For the endpoints using the `X-SITE-IDs` header, all non-deleted employee site statuses are returned in the response, if requested, regardless of the sites provided in the `X-SITE-IDs` header.
`PosCredentials`	PosCredentials Array	No	The employee’s access details for the point of sale (POS) system

Sample General Structure Response Body

{
    "Data": [
        {
            "EmployeeId": string,
            "Firstname": string,
            "Lastname": string,
            "Middlename": string,
            "Name": string,
            "Username": string,
            "EmployeeCorporateCode": string,
            "ExternalEmployeeId": string,
            "PrimarySiteId": string,
            "Source": string,
            "LastUpdateDate": string,
            "IsActive": boolean,
            "AdditionalDetails": {
                "TaxIdentifier": string,
                "BadgeNumber": string,
                "EthnicityCode": string,
                "Nickname": string,
                "BirthDate": string,
                "Gender": string,
                "IsHandicapped": boolean,
                "IsRehireable": boolean,
                "IsVeteran": boolean,
                "IsMinor": boolean
            },
            "EmployeePhones": [
                {
                    "PhoneNumber": string,
                    "PhoneTypeCode": string,
                }
            ],
            "EmployeeAddresses": [
                {
                    "AddressTypeCode": string,
                    "Address1": string,
                    "Address2": string,
                    "Address3": string,
                    "City": string,
                    "StateCode": string,
                    "PostalCode": string,
                    "CountryCode": string,
                }
            ],
            "EmployeeContacts": [
                {
                    "ContactСode": string,
                    "Firstname": string,
                    "Lastname": string,
                    "Middlename": string,
                    "Address1": string,
                    "Address2": string,
                    "Address3": string,
                    "City": string,
                    "StateCode": string,
                    "PostalCode": string,
                    "CountryCode": string,
                    "Phone1": string,
                    "Phone2": string,
                }
            ],
            "EmployeeEmails": [
                {
                    "Email": string,
                    "EmailTypeCode": string,
                }
            ],
            "EmployeeJobs": [
                {
                    "EmployeeJobId": string,
                    "EffectiveDate": string,
                    "JobCodeId": string,
                    "ExternalJobCodeId": string,
                    "IsPrimaryJob": boolean,
                    "Deactivated": boolean,
                    "DeactivationDate": string,
                    "SiteId": string,
                    "EmployeeJobPays": [
                        {
                            "CompensationTypeCode": string,
                            "Rate": decimal,
                            "EffectiveDate": string,
                        }
                    ]
                }
            ],
            "EmployeeSiteStatuses": [
                {
                    "EffectiveDate": string,
                    "StatusCode": string,
                    "SiteIds": [] //array of strings
                },
            ],
            "PosCredentials": [
                {
                    "EmployeePOSCode": string,
                    "Password": string,
                    "RoleId": string,
                }
            ]
        }
    ],
    "TotalCount": integer,
    "RecordsReturned": integer,
    "NextPageToken": string
}

AdditionalDetails Object

Field Name	Type	Description
`TaxIdentifier`	string	The employee’s tax identification number
`BadgeNumber`	string	The unique number assigned to the employee’s access badge
`EthnicityCode`	string	The code representing the employee’s ethnicity
`Nickname`	string	The employee’s preferred informal name
`BirthDate`	string/date	The employee’s date of birth
`Gender`	string	The employee’s gender
`IsHandicapped`	boolean	A flag that indicates whether the employee has a disability
`IsRehireable`	boolean	A flag that indicates whether the employee is eligible for rehire
`IsVeteran`	boolean	A flag that indicates whether the employee has military service experience
`IsMinor`	boolean	A flag that indicates whether the employee is under the legal adult age

EmployeePhones Array

Field Name

Type

Description

PhoneNumber

string

The employee phone number

PhoneTypeCode

string

The code indicating the type of phone number. Supported static values:

Name	Code
Business	BIZ
Mobile	CELL
Fax	FAX
Home	HOME

EmployeeAddresses Array

Field Name

Type

Description

AddressTypeCode

string

The code indicating the type of address. Supported static values:

Name	Code
Home Address	HOME
Mailing Address	MAIL

Address1

string

The primary line of the employee’s address. For example, street name and number.

Address2

string

The secondary line of the employee’s address. For example, apartment, suite, or unit.

Address3

string

The additional line for the employee’s address. For example, building or complex.

City

string

The city name for the address

StateCode

string

The code representing the state, province, or region of the employee’s address. The list of all configured states, including their names and codes, can always be retrieved using the GET /Lookup/State endpoint.

PostalCode

string

The postal code for the address

CountryCode

string

The code representing the country of the employee’s address. The list of all configured countries, including their names and codes, can always be retrieved using the GET /Lookup/Country endpoint.

EmployeeContacts Array

Field Name	Type	Description
`ContactCode`	string	Concatenation of the contact’s `FirstName` and `LastName` values
`Firstname`	string	The first name of the employee’s emergency contact
`Lastname`	string	The last name of the employee’s emergency contact
`Middlename`	string	The middle name of the employee’s emergency contact
`Address1`	string	The primary line of the employee contact’s address
`Address2`	string	The secondary line of the employee contact’s address
`Address3`	string	The additional line of the employee contact’s address
`City`	string	The city name of the employee contact's address
`StateCode`	string	The code representing the state, province, or region of the employee contact’s address
`PostalCode`	string	The postal code of the employee contact's address
`CountryCode`	string	The code representing the country of the employee contact’s address
`Phone1`	string	The primary phone number of the employee’s emergency contact
`Phone2`	string	The secondary phone number of the employee’s emergency contact

EmployeeEmails Array

Field Name

Type

Description

Email

string

The employee email address

EmailTypeCode

string

The code indicating the type of email address. Supported static values:

Name	Code
Personal	PRSNL
Work	WORK

EmployeeJobs Array

Field Name	Type	Description
`EmployeeJobId`	string	The 24-character hexadecimal string uniquely identifying the employee’s job record in the Staff database
`EffectiveDate`	string/date	The date when the job assignment at the specified site becomes effective. This field correlates with the Business Date on the point of sale (POS).
`JobCodeId`	string	The 24-character hexadecimal string uniquely identifying the job position, configured in Data Management
`ExternalJobCodeId`	string	The unique identifier (UID) of the job position, mainly used for integration and data synchronization
`IsPrimaryJob`	boolean	A flag that indicates whether this job position is the employee’s primary job
`Deactivated`	boolean	A flag that indicates whether the job position is no longer available for an employee
`DeactivationDate`	string/date	The date when the job position was deactivated
`SiteId`	string	The Genius Portal UID of the site where the job is assigned
`EmployeeJobPays`	EmployeeJobPays Array	A list of pay details associated with this job position, such as salary and hourly rate. Note If for any reason no non-deleted employee job pay records exist for this job, this array is returned as `"EmployeeJobsPays": []`. Such job records should be considered invalid and must be fixed by the next PUT/PATCH request.

EmployeeJobPays Array

All history of rate changes is returned in this array.

Field Name

Type

Description

CompensationTypeCode

string

The code indicating the type of compensation. Supported static values:

Name	Code
Salary	SLRY
Hourly	HOUR

Rate

number/decimal (2)

The amount or rate of pay associated with the compensation type

EffectiveDate

string/date

The date when this compensation rate becomes effective

EmployeeSiteStatues Array

This array returns the full history of status changes for all sites to which the employee is assigned.

Field Name

Type

Description

EffectiveDate

string/date

The date when the site status becomes effective

StatusCode

string

The code representing the employee’s status at a site.

The list of all configured statuses, including their names and codes, can always be retrieved using the GET /Lookup/EmployeeStatus endpoint.

SiteIds

array of strings

A list of site identifiers (IDs) to which this status applies since the EffectiveDate.

PosCredentials Array

Field Name	Type	Description
`EmployeePOSCode`	string	The employee’s login value, or user identifier (ID), on the point of sale (POS) device
`Password`	string	The password for the employee’s POS account, returned as a hash
`RoleId`	string	A 24-character hexadecimal string Genius Portal unique identifier (UID) of the role assigned to the employee. A role defines a set of functions available for the employee during their work with POS. A list of all available roles within a source company can always be found using the GET /auth/getCompanyRoles endpoint.