Staff API | Getting Started

The process to get started with Staff API is outlined in the table. Note that each step is its own process.

Step	Topic	Description
1	Getting Started with APIs	Steps to obtain an integrator token and additional information about our APIs.
2	Confidentiality Statement	Information about our non-disclosure agreement (NDA) terms and conditions regarding endpoints.
3	API Prerequisites	A list of prerequisites to complete before starting the integration development process.

Staff API | Next Steps

After completing the initial steps for Staff API setup, review additional information in the topics below.

Step	Topic	Description
1	Create an Employee Record	Use this endpoint to create employee data for one employee, together with all required child entities, such as Site Statuses, POS Credentials, and other entities.
2	Create Employee Jobs	Use this endpoint to create employee job data together with a corresponding employee’s rate information for a single employee. And the PATCH /External/General/Employee/[ID]/Job/[ID] endpoint allows users to deactivate a single employee’s job, or create and update its rates.
3	Retrieve Employee Data	Use these endpoints for retrieving data by unique employee identifiers, employees by secondary identifiers, and employee updates. For the old implementations, see the GET /Staff/Employee/EmployeeDetail endpoint.
4	Update an Employee Record	Use this endpoint to update an employee or to create/update its child entities. The endpoint updates only the fields and entities included in the request. Do not send the entire employee object to update individual fields or child entities.
5	Operation Definitions	Use the operation definitions including the endpoints, data models, and sample code.
6	Get Calculated Payroll Details	Use the this endpoint to estimate wages per employee for a given business date.
7	Scheduled Shifts API	Use this endpoint to synchronize shift data between an employee-scheduling system and our system's backend.
8	Delete	Use these endpoints to remove erroneous data.

Create an Employee Record

The Create an Employee Record endpoint works with one employee record only together with all required child entities, such as Site Statuses, POS Credentials, Addresses, and other entities. Creating an employee record also creates an employee identifier, which the Genius system uses to link time card data and payroll data to the employee.

Follow these steps to create an Employee Detail Record:

Obtain an authentication token and set the request headers. See Authentication for a description and example of how an integrator token can be generated. For additional information, see Getting Started with APIs.
Send a POST request to the /External/General/Employee endpoint with the employee details in the body of the request.

Site Status Bulk Update

The Site Status Bulk Update endpoint is used to create, update, or delete employee site status information in bulk. It allows a payload to be posted that can include many objects, each of which describe an employee’s status for a referenced site. It is recommended to use this endpoint to create, update, or delete more than 50 site status records in one request.

Note

Employee Site Statuses that are not sent in this request are not affected in the result. This request does not delete statuses that are not received in the request.

Follow these steps to create, update, or delete employee site status information in bulk:

Obtain an authentication token and set the request headers. See Authentication for a description and example of how an integrator token can be generated. For additional information, see Getting Started with APIs.
Identify the Employee Status ID for the employee. Send a GET request to the /Lookup/EmployeeStatus endpoint to retrieve a list of available status records. See the Employee Statuses method definition for details, including a sample response.
Capture the EmployeeStatusId value associated with the employee. This value is required in the body of the request.
Send a PUT request to the /EmployeeSiteStatus/BulkUpdate endpoint with the employee site status details in the body of the request.

Create Employee Jobs

The Create Employee Jobs endpoint allows users to create employee job data together with a corresponding employee’s rate information for a single employee. And the PATCH /External/General/Employee/[ID]/Job/[ID] endpoint allows users to deactivate a single employee’s job, or create and update its rates.

Follow these steps to update employee job data:

Obtain an authentication token and set the request headers. See Authentication for a description and example of how an integrator token can be generated. For additional, see Getting Started with APIs.
Send a POST request to the /External/General/Employee/[ID]/Jobs endpoint to create one or multiple job records for a single employee.
Send a PATCH request to the /External/General/Employee/[ID]/Job/[ID] endpoint with the employee job details in the body of the request.

Update an Employee Record

The Update an Employee Record endpoint updates employee data. Use this endpoint to update an employee or to create/update its child entities. The endpoint updates only the fields and entities included in the request.

Important

Do not send the entire employee object to update individual fields or child entities. Use one of the GET endpoints to receive all previously created employee data, such as:

This is useful when updating employee data.

Within child arrays, like EmployeeSiteStatus, new records can be sent together with updates for existing records. Records that were received in the request but do not yet exist in the database will be created. Updates of child arrays differ from updates of the employee fields: objects in the child arrays that are not sent in the request are not affected by this update. This means that, for example, for employee status changes, it is possible to send only those statuses that should be updated or created in the EmployeeSiteStatus array - other already existing statuses will not be affected by this change.