{ "swagger": "2.0", "info": { "version": "v1", "title": "Labor Productivity API", "description": "Use this API to access and update the employee and organisation data stored in Fourth. For employee records, this includes both static data — like their name or address — and temporary or transactional data such as time off (planned and unplanned). For more information about how this API works, see the [Labor Productivity API Guide](https://developer.fourth.com/en-gb/docs/labor-productivity-api/guide).

To use this API, you will need:
    •   A Labor Productivity API account
    •   The `externalCustomerCanonicalId` specific to the customer
    •   The root URL

Your mutual Fourth customer must request these details on your behalf. Please ensure they do this as soon as possible.

Testing: A test environment is available.

Availability: All customers using Workforce Management solutions.

Updates: See the [Release Notes page](https://developer.fourth.com/en-gb/docs/labor-productivity-api/release-notes) for this API.
" }, "host": "localhost:50000", "schemes": [ "http" ], "paths": { "/export/{externalCustomerCanonicalId}/Absences": { "get": { "tags": [ "AbsenceExport" ], "summary": "Get absences", "description": "Returns all employee absences across the business.
You can use the `If-Modified-Since` header to filter responses. This will return only records that were created or modified after the date specified in the header.", "operationId": "AbsenceExport_ExportAbsencesAsync", "consumes": [], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "externalCustomerCanonicalId", "in": "path", "description": "Customer identifier provided by Fourth.", "required": true, "type": "string" }, { "name": "If-Modified-Since", "in": "header", "description": "Used to retrieve only records that were modified after a certain date. Example: Sun, 10 May 2020 02:01:00 GMT", "required": false, "type": "string" } ], "responses": { "200": { "description": "List of Absences.", "schema": { "type": "array", "items": { "$ref": "#/definitions/AbsenceFlat" } }, "examples": { "application/json": [ { "reference": "R65432.1234", "employeeExternalId": "R65432", "payrollNo": "1122", "type": "Sick", "days": 2, "startDate": "2021-05-29T00:00:00Z", "endDate": "2021-05-30T00:00:00Z", "status": "active", "percentPaid": 100.0, "reason": "Got the flu", "jobCode": "PTO", "locationCode": "L123", "departmentCode": "D123" }, { "reference": "R65432.1234", "employeeExternalId": "R65432", "payrollNo": "1122", "type": "VACATION", "days": 2, "startDate": "2021-06-21T00:00:00Z", "endDate": "2021-06-28T00:00:00Z", "status": "active", "percentPaid": 100.0, "reason": "In Hawai", "jobCode": "PTO", "locationCode": "L123", "departmentCode": "D123" } ] } } } } }, "/import/{externalCustomerCanonicalId}/AdditionalPayments": { "post": { "tags": [ "AdditionalPayment" ], "summary": "Add or update one additional payment", "description": "Adds or updates one additional payment.", "operationId": "AdditionalPayment_ImportAdditionalPayments", "consumes": [ "application/json", "text/json", "application/xml", "text/xml" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "externalCustomerCanonicalId", "in": "path", "description": "Customer identifier provided by Fourth.", "required": true, "type": "string" }, { "name": "additionalPayments", "in": "body", "required": true, "schema": { "$ref": "#/definitions/AdditionalPayment" } } ], "responses": { "200": { "description": "OK", "schema": { "type": "object" } }, "202": { "description": "Accepted" } } } }, "/import/{externalCustomerCanonicalId}/AdditionalPayments:batchImport": { "post": { "tags": [ "AdditionalPayment" ], "summary": "Add or update additional payments", "description": "Adds or updates multiple additional payments.", "operationId": "AdditionalPayment_BatchImportAdditionalPayments", "consumes": [ "application/json", "text/json", "application/xml", "text/xml" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "externalCustomerCanonicalId", "in": "path", "description": "Customer identifier provided by Fourth.", "required": true, "type": "string" }, { "name": "additionalPayments", "in": "body", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/AdditionalPayment" } } } ], "responses": { "200": { "description": "OK", "schema": { "type": "object" } }, "202": { "description": "Accepted" } } } }, "/import/{externalCustomerCanonicalId}/Assignments": { "post": { "tags": [ "Assignment" ], "summary": "Add or update assignment for one employee", "description": "Adds or updates an assignment for one employee. Use this resource only after you have added the employee (using the `employees` resource) and their employment details (using the `employment` resource). The value of `assignment_Reference` identifies whether you are creating a new assignment or updating an existing one.
\r\nWe recommend integrating with the **batchimport** version of this resource for all requests.
\r\nFor more information on [Assignments, see our API Guide](https://developer.fourth.com/en-gb/docs/labor-productivity-api/guide#assignments-and-employment).", "operationId": "Assignment_ImportAssignmentAsync", "consumes": [ "application/json", "text/json", "application/xml", "text/xml" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "externalCustomerCanonicalId", "in": "path", "description": "Customer identifier provided by Fourth.", "required": true, "type": "string" }, { "name": "assignment", "in": "body", "required": true, "schema": { "$ref": "#/definitions/Assignment" } } ], "responses": { "200": { "description": "OK", "schema": { "type": "object" } }, "202": { "description": "Accepted" } } } }, "/import/{externalCustomerCanonicalId}/Assignments:batchImport": { "post": { "tags": [ "Assignment" ], "summary": "Add or update assignments for employees", "description": "Adds or updates assignments for one or more employees. Use this resource only after you have added employees (using the `employees` resource) and their employment details (using the `employment` resource). The value of `assignment_Reference` identifies whether you are creating a new assignment or updating an existing one.
\r\nFor more information on [Assignments, see our API Guide](https://developer.fourth.com/en-gb/docs/labor-productivity-api/guide#assignments-and-employment).", "operationId": "Assignment_ImportAssignmentsAsync", "consumes": [ "application/json", "text/json", "application/xml", "text/xml" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "externalCustomerCanonicalId", "in": "path", "description": "Customer identifier provided by Fourth.", "required": true, "type": "string" }, { "name": "assignments", "in": "body", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/Assignment" } } } ], "responses": { "200": { "description": "OK", "schema": { "type": "object" } }, "202": { "description": "Accepted" } } } }, "/import/{externalCustomerCanonicalId}/Assignments:delete": { "post": { "tags": [ "Assignment" ], "summary": "Delete assignment for one employee", "description": "Removes an assignment for an employee.
\r\nFourth expects assignments to be deleted only if the employee did not start the assignment. If you do delete an assignment in use, any associated tips and shifts are also removed.
\r\nWe recommend integrating with the **batchimport** version of this resource for all requests.
\r\nFor more information on [Assignments, see our API Guide](https://developer.fourth.com/en-gb/docs/labor-productivity-api/guide#assignments-and-employment).", "operationId": "Assignment_DeleteAssignmentsAsync", "consumes": [ "application/json", "text/json", "application/xml", "text/xml" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "externalCustomerCanonicalId", "in": "path", "description": "Customer identifier provided by Fourth.", "required": true, "type": "string" }, { "name": "removedAssignment", "in": "body", "required": true, "schema": { "$ref": "#/definitions/AssignmentRemoved" } } ], "responses": { "202": { "description": "Accepted" } } } }, "/import/{externalCustomerCanonicalId}/Assignments:batchDelete": { "post": { "tags": [ "Assignment" ], "summary": "Delete assignments for employees", "description": "Removes assignments for one or more employees.
\r\nFourth expects assignments to be deleted only if the employee did not start the assignment. If you do delete an assignment in use, any associated tips and shifts are also removed.
\r\nFor more information on [Assignments, see our API Guide](https://developer.fourth.com/en-gb/docs/labor-productivity-api/guide#assignments-and-employment).", "operationId": "Assignment_BatchDeleteAssignmentsAsync", "consumes": [ "application/json", "text/json", "application/xml", "text/xml" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "externalCustomerCanonicalId", "in": "path", "description": "Customer identifier provided by Fourth.", "required": true, "type": "string" }, { "name": "removedAssignment", "in": "body", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/AssignmentRemoved" }, "example": { "employee_ID": "123", "assigment_Reference": "00000000-0000-0000-0000-000000000000" } } } ], "responses": { "202": { "description": "Accepted" } } } }, "/import/{externalCustomerCanonicalId}/Employees": { "post": { "tags": [ "Employee" ], "summary": "Add or update one employee", "description": "Adds or updates employee details for one employee. The value of `employee_ID` identifies whether you are adding a new employee or updating an existing employee's details. After a new employee is added using this resource, Fourth Engage sends a \"Welcome\" email to them.
\r\nWe recommend integrating with the **batchimport** version of this resource for all requests.", "operationId": "Employee_ImportEmployeeAsync", "consumes": [ "application/json", "text/json", "application/xml", "text/xml" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "externalCustomerCanonicalId", "in": "path", "description": "Customer identifier provided by Fourth.", "required": true, "type": "string" }, { "name": "employee", "in": "body", "required": true, "schema": { "$ref": "#/definitions/Employee" } } ], "responses": { "201": { "description": "{account} created", "schema": { "type": "object" } }, "202": { "description": "Accepted" } } } }, "/import/{externalCustomerCanonicalId}/Employees:batchImport": { "post": { "tags": [ "Employee" ], "summary": "Add or update employees", "description": "Adds or updates employee details for one or more employees. The value of `employee_ID` identifies whether you are adding a new employee or updating an existing employee’s details. After a new employee is added using this resource, Fourth Engage sends a \"Welcome\" email to them.", "operationId": "Employee_BatchImportEmployeesAsync", "consumes": [ "application/json", "text/json", "application/xml", "text/xml" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "externalCustomerCanonicalId", "in": "path", "description": "Customer identifier provided by Fourth.", "required": true, "type": "string" }, { "name": "employees", "in": "body", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/Employee" } } } ], "responses": { "200": { "description": "OK", "schema": { "type": "object" } }, "202": { "description": "Accepted" } } } }, "/export/{externalCustomerCanonicalId}/employees": { "get": { "tags": [ "EmployeeExport" ], "summary": "Get employees (full)", "description": "This endpoint provides employees' assignments, employments, and personal data such as their email address and pay rate. Only data for current (active) employees are returned.
You can use the `If-Modified-Since` header to filter responses. This will return only employee records that were created or modified after the date specified in the header.
This endpoint is **restricted to approved API users only**. If you need access to this endpoint, please get your mutual customer to provide consent.", "operationId": "EmployeeExport_ExportEmployeesAsync", "consumes": [], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "externalCustomerCanonicalId", "in": "path", "description": "Customer identifier provided by Fourth.", "required": true, "type": "string" }, { "name": "employeesFilter.locationCode", "in": "query", "description": "Returns only employees for the location matching the **location code**.", "required": false, "type": "string" }, { "name": "employeesFilter.startDate", "in": "query", "description": "Use with `employeesFilter.endDate` to filter the employees by time range. You must use both parameters. The dates are inclusive, and must use the format: yyyy-MM-ddThh:mm:ssZ; for example, `2020-12-25T00:00:00Z`.", "required": false, "type": "string", "format": "date-time" }, { "name": "employeesFilter.endDate", "in": "query", "description": "Use with `employeesFilter.startDate` to specify a time range.", "required": false, "type": "string", "format": "date-time" }, { "name": "If-Modified-Since", "in": "header", "description": "Used to retrieve only records that were modified after a certain date. Example: Sun, 10 May 2020 02:01:00 GMT", "required": false, "type": "string" } ], "responses": { "200": { "description": "List of employees with their employments and assignments.", "schema": { "type": "array", "items": { "$ref": "#/definitions/EmployeeFlat" } }, "examples": { "application/json": [ { "employee_ID": "EMP_01", "user_ID": "0058F000206MboYQSS", "email_Home": "john.smith@fourth.com", "payroll_No": "40004", "first_Name": "John", "last_Name": "Smith", "date_Of_Birth": "1995-02-28T00:00:00Z", "employments": [ { "employment_Join_Date": "2019-01-20T00:00:00Z", "first_Working_Day": "2019-01-20T00:00:00Z", "original_Hire_Date": "2019-01-20T00:00:00Z", "contracted_Hours": 40.0, "pay_Group": "PG_1", "break_Waiver": true, "employment_Authorization": "COMPLETED", "onboarding_Status": "ONGOING", "assignments": [ { "assignment_Start_Date": "2019-01-21T00:00:00Z", "assignment_End_Date": "2019-06-21T00:00:00Z", "main_Assignment": true, "location_Code": "LOC_01", "department_Code": "DEP_01", "job_Code": "JC_01", "rate_Type": "WEEKLY", "rate_Currency": "USD", "rates": [ { "rate_Amount": 10.0, "rate_Unit": "HOUR" }, { "rate_Amount": 80.0, "rate_Unit": "DAY" } ] } ] } ] } ] } } } } }, "/export/{externalCustomerCanonicalId}/employees/restricted": { "get": { "tags": [ "EmployeeExport" ], "summary": "Get employees (limited)", "description": "Returns the employees' assignments and employments. Only data for current (active) employees are returned.
You can use the `If-Modified-Since` header to filter responses. This will return only employee records that were created or modified after the date specified in the header.
Fields for personal data such as an employee's email address and pay rate are left blank; if you need this data then you will need to use the **Get employees (full)** endpoint.", "operationId": "EmployeeExport_ExportEmployeesRestrictedAsync", "consumes": [], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "externalCustomerCanonicalId", "in": "path", "description": "Customer identifier provided by Fourth.", "required": true, "type": "string" }, { "name": "employeesFilter.locationCode", "in": "query", "description": "Returns only employees for the location matching the **location code**.", "required": false, "type": "string" }, { "name": "employeesFilter.startDate", "in": "query", "description": "Use with `employeesFilter.endDate` to filter the employees by time range. You must use both parameters. The dates are inclusive, and must use the format: yyyy-MM-ddThh:mm:ssZ; for example, `2020-12-25T00:00:00Z`.", "required": false, "type": "string", "format": "date-time" }, { "name": "employeesFilter.endDate", "in": "query", "description": "Use with `employeesFilter.startDate` to specify a time range.", "required": false, "type": "string", "format": "date-time" }, { "name": "If-Modified-Since", "in": "header", "description": "Used to retrieve only records that were modified after a certain date. Example: Sun, 10 May 2020 02:01:00 GMT", "required": false, "type": "string" } ], "responses": { "200": { "description": "List of employees with their employments and assignments.", "schema": { "type": "array", "items": { "$ref": "#/definitions/EmployeeFlat" } }, "examples": { "application/json": [ { "employee_ID": "EMP_01", "user_ID": "0058F000206MboYQSS", "payroll_No": "40004", "first_Name": "John", "last_Name": "Smith", "employments": [ { "employment_Join_Date": "2019-01-20T00:00:00Z", "first_Working_Day": "2019-01-20T00:00:00Z", "original_Hire_Date": "2019-01-20T00:00:00Z", "pay_Group": "PG_1", "break_Waiver": true, "employment_Authorization": "COMPLETED", "onboarding_Status": "ONGOING", "assignments": [ { "assignment_Start_Date": "2019-01-21T00:00:00Z", "assignment_End_Date": "2019-06-21T00:00:00Z", "main_Assignment": true, "location_Code": "LOC_01", "department_Code": "DEP_01", "job_Code": "JC_01", "rate_Type": "WEEKLY", "rate_Currency": "USD" } ] } ] } ] } } } } }, "/import/{externalCustomerCanonicalId}/Employments": { "post": { "tags": [ "Employment" ], "summary": "Add or update employment for one employee", "description": "Adds or updates the employment history for one employee. Use this resource only after you have added the employee (using the `employees` resource). The value of `employment_Reference` identifies whether you are creating a new employment or updating an existing one.
\r\n We recommend integrating with the **batchimport** version of this resource for all requests.
\r\n For more information on [Employment, see our API Guide](https://developer.fourth.com/en-gb/docs/labor-productivity-api/guide#assignments-and-employment).", "operationId": "Employment_ImportEmploymentAsync", "consumes": [ "application/json", "text/json", "application/xml", "text/xml" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "externalCustomerCanonicalId", "in": "path", "description": "Customer identifier provided by Fourth.", "required": true, "type": "string" }, { "name": "employment", "in": "body", "required": true, "schema": { "$ref": "#/definitions/Employment_Detail" } } ], "responses": { "202": { "description": "Accepted" } } } }, "/import/{externalCustomerCanonicalId}/Employments:batchImport": { "post": { "tags": [ "Employment" ], "summary": "Add or update employments for employees", "description": "Adds or updates the employment history for one or more employees. Use this resource only after you have added the employee (using the `employees` resource). The value of `employment_Reference` identifies whether you are creating a new employment or updating an existing one.
\r\n For more information on [Employment, see our API Guide](https://developer.fourth.com/en-gb/docs/labor-productivity-api/guide#assignments-and-employment).", "operationId": "Employment_BatchImportEmploymentsAsync", "consumes": [ "application/json", "text/json", "application/xml", "text/xml" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "externalCustomerCanonicalId", "in": "path", "description": "Customer identifier provided by Fourth.", "required": true, "type": "string" }, { "name": "employments", "in": "body", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/Employment_Detail" }, "example": [ { "employee_ID": "123", "employer_ID": "0001000", "employment_Reference": "0001000.123", "employment_Join_Date": "2017-01-20T00:00:00Z", "first_Working_Day": "2017-01-21T00:00:00Z", "employment_Leave_Date": "2020-06-21T00:00:00Z", "employment_Type": "EMPLOYEE", "employment_Status": "ACTIVE", "contract_Perm": true, "contract_Fulltime": true }, { "employee_ID": "222", "employer_ID": "0002000", "employment_Reference": "0002000.222", "employment_Join_Date": "2018-02-22T00:00:00Z", "first_Working_Day": "2018-02-02T00:00:00Z", "employment_Leave_Date": "2018-12-22T00:00:00Z", "termination_Reason": "Moving away", "employment_Type": "EMPLOYEE", "employment_Status": "INACTIVE", "contract_Perm": true, "contract_Fulltime": true } ] } } ], "responses": { "202": { "description": "Accepted" } } } }, "/import/{externalCustomerCanonicalId}/EmploymentsFullHistory": { "post": { "tags": [ "Employment" ], "summary": "Replace employment and assignments for one employee", "description": "Replaces an employee's full employment and assignments history.
\r\nWe recommend integrating with the **batchimport** version of this resource for all requests.
\r\nFor more information on [Employment, see our API Guide](https://developer.fourth.com/en-gb/docs/labor-productivity-api/guide#assignments-and-employment).", "operationId": "Employment_ImportEmploymentsAssignmentsFullHistoryAsync", "consumes": [ "application/json", "text/json", "application/xml", "text/xml" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "externalCustomerCanonicalId", "in": "path", "description": "Customer identifier provided by Fourth.", "required": true, "type": "string" }, { "name": "employment", "in": "body", "required": true, "schema": { "$ref": "#/definitions/Employment_Detail" } } ], "responses": { "202": { "description": "Accepted" } } } }, "/import/{externalCustomerCanonicalId}/EmploymentsFullHistory:batchImport": { "post": { "tags": [ "Employment" ], "summary": "Replace employments and assignments for employees", "description": "Replaces the full employments and assignments history for one or more employees.
\r\nFor more information on [Employment, see our API Guide](https://developer.fourth.com/en-gb/docs/labor-productivity-api/guide#assignments-and-employment).", "operationId": "Employment_BatchImportEmploymentsAssignmentsFullHistoryAsync", "consumes": [ "application/json", "text/json", "application/xml", "text/xml" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "externalCustomerCanonicalId", "in": "path", "description": "Customer identifier provided by Fourth.", "required": true, "type": "string" }, { "name": "employments", "in": "body", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/Employment_Detail" }, "example": { "employee_ID": "123", "employer_ID": "0001000", "employment_Reference": "0001000.123", "employment_Join_Date": "2017-01-20T00:00:00Z", "first_Working_Day": "2017-01-21T00:00:00Z", "employment_Leave_Date": "2020-06-21T00:00:00Z", "employment_Type": "EMPLOYEE", "employment_Status": "ACTIVE", "contract_Perm": true, "contract_Fulltime": true, "assignments": [ { "assigment_Reference": "0001000.123.A01", "employment_ID": "0001000.123", "assignment_Start_Date": "2017-01-21T00:00:00Z", "main_Assignment": true, "location_Code": "LOC_01", "department_Code": "DEP_01", "job_Code": "JOB_01", "rate_Type": "HOURLY", "attributes": [], "rates": [ { "rate_Unit": "HOUR", "rate_Amount": 15.5 } ] } ] } } } ], "responses": { "202": { "description": "Accepted" } } } }, "/import/{externalCustomerCanonicalId}/Employments:delete": { "post": { "tags": [ "Employment" ], "summary": "Delete employment for one employee", "description": "Removes an employment for one employee.
\r\nFourth expects employments to be deleted only if the employee did not start the employment. If you do delete an employment in use, any associated assignments, tips and shifts are also removed.
\r\nWe recommend integrating with the **batchimport** version of this resource for all requests.
\r\nFor more information on [Employment, see our API Guide](https://developer.fourth.com/en-gb/docs/labor-productivity-api/guide#assignments-and-employment).", "operationId": "Employment_DeleteEmploymentsAsync", "consumes": [ "application/json", "text/json", "application/xml", "text/xml" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "externalCustomerCanonicalId", "in": "path", "description": "Customer identifier provided by Fourth.", "required": true, "type": "string" }, { "name": "removedEmployment", "in": "body", "required": true, "schema": { "$ref": "#/definitions/EmploymentRemoved" } } ], "responses": { "202": { "description": "Accepted" } } } }, "/import/{externalCustomerCanonicalId}/Employments:batchDelete": { "post": { "tags": [ "Employment" ], "summary": "Delete employments for employees", "description": "Removes employments for one or more employees.
\r\nFourth expects employments to be deleted only if the employee did not start the employment. If you do delete an employment in use, any associated assignments, tips and shifts are also removed.
\r\nFor more information on [Employment, see our API Guide](https://developer.fourth.com/en-gb/docs/labor-productivity-api/guide#assignments-and-employment).", "operationId": "Employment_BatchDeleteEmploymentsAsync", "consumes": [ "application/json", "text/json", "application/xml", "text/xml" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "externalCustomerCanonicalId", "in": "path", "description": "Customer identifier provided by Fourth.", "required": true, "type": "string" }, { "name": "removedEmployments", "in": "body", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/EmploymentRemoved" }, "example": { "employee_ID": "123", "employment_Join_Date": "2017-01-20T00:00:00Z" } } } ], "responses": { "202": { "description": "Accepted" } } } }, "/import/{externalCustomerCanonicalId}/JobTitles": { "post": { "tags": [ "JobTitle" ], "summary": "Add or update one job title", "description": "Adds or updates one job title for your business. The value of `job_Code` identifies whether you are adding a new job title or updating an existing one. After sending a jobTitles request, you (or your customer) will need to use the Fourth UI to link the job title to a role.
\r\nWe recommend integrating with the **batchimport** version of this resource for all requests.", "operationId": "JobTitle_ImportJobTitleAsync", "consumes": [ "application/json", "text/json", "application/xml", "text/xml" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "externalCustomerCanonicalId", "in": "path", "description": "Customer identifier provided by Fourth.", "required": true, "type": "string" }, { "name": "jobTitle", "in": "body", "required": true, "schema": { "$ref": "#/definitions/JobTitle" } } ], "responses": { "202": { "description": "Accepted", "headers": { "Location": { "description": "Location of status URL", "type": "string" } } } } } }, "/import/{externalCustomerCanonicalId}/JobTitles:batchImport": { "post": { "tags": [ "JobTitle" ], "summary": "Add or update job titles", "description": "Adds or updates one or more job titles across your business. The value of `job_Code` identifies whether you are adding a new job title or updating an existing one. After sending a jobTitles request, you (or your customer) will need to use the Fourth UI to link the job titles to roles.", "operationId": "JobTitle_ImportJobTitlesAsync", "consumes": [ "application/json", "text/json", "application/xml", "text/xml" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "externalCustomerCanonicalId", "in": "path", "description": "Customer identifier provided by Fourth.", "required": true, "type": "string" }, { "name": "jobTitles", "in": "body", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/JobTitle" }, "example": [ { "job_Code": "BRT", "job_Name": "Bartender", "is_Tippable": true }, { "job_Code": "HST", "job_Name": "Hostess" } ] } } ], "responses": { "202": { "description": "Accepted", "headers": { "Location": { "description": "Location of status URL", "type": "string" } } } } } }, "/export/{externalCustomerCanonicalId}/JobTitles": { "get": { "tags": [ "JobTitleExport" ], "summary": "Get job titles", "description": "Returns the job titles for the business, including whether the job is tippable, and any attributes.
You can use the `If-Modified-Since` header to filter responses. This will return only records that were created or modified after the date specified in the header.", "operationId": "JobTitleExport_ExportJobTitlesAsync", "consumes": [], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "externalCustomerCanonicalId", "in": "path", "description": "Customer identifier provided by Fourth.", "required": true, "type": "string" }, { "name": "If-Modified-Since", "in": "header", "description": "Used to retrieve only records that were modified after a certain date. Example: Sun, 10 May 2020 02:01:00 GMT", "required": false, "type": "string" } ], "responses": { "200": { "description": "List of JobTitles and their attributes.", "schema": { "type": "array", "items": { "$ref": "#/definitions/JobTitleFlat" } }, "examples": { "application/json": [ { "job_Code": "BAR", "job_Name": "Bartender", "is_Tippable": true, "attributes": [ { "attribute_Name": "FLSA_EXEMPT", "attribute_Value": "false" } ], "created_Date": "2021-05-12T13:19:02.1245Z", "last_Modified_Date": "2021-05-11T13:19:02.1245Z" }, { "job_Code": "M", "job_Name": "Manager", "attributes": [ { "attribute_Name": "FLSA_EXEMPT", "attribute_Value": "true" } ], "created_Date": "2021-05-12T13:19:02.1256Z" } ] } } } } }, "/import/{externalCustomerCanonicalId}/Locations": { "post": { "tags": [ "Location" ], "summary": "Add or update one location", "description": "Adds or updates one location for your business. You must provide your locations before adding employees or assignments. The value of `location_Code` identifies whether you are adding a new location or updating an existing one.
\r\nWe recommend integrating with the **batchimport** version of this resource for all requests.", "operationId": "Location_ImportLocationAsync", "consumes": [ "application/json", "text/json", "application/xml", "text/xml" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "externalCustomerCanonicalId", "in": "path", "description": "Customer identifier provided by Fourth.", "required": true, "type": "string" }, { "name": "location", "in": "body", "required": true, "schema": { "$ref": "#/definitions/Location" } } ], "responses": { "202": { "description": "Accepted", "headers": { "Location": { "description": "Location of status URL", "type": "string" } } } } } }, "/import/{externalCustomerCanonicalId}/Locations:batchImport": { "post": { "tags": [ "Location" ], "summary": "Add or update locations", "description": "Adds or updates one or more locations across your business. You must provide your locations before adding employees or assignments. The value of `location_Code` identifies whether you are adding a new location or updating an existing one.", "operationId": "Location_ImportLocationsAsync", "consumes": [ "application/json", "text/json", "application/xml", "text/xml" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "externalCustomerCanonicalId", "in": "path", "description": "Customer identifier provided by Fourth.", "required": true, "type": "string" }, { "name": "locations", "in": "body", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/Location" }, "example": [ { "location_Code": "LOC1", "location_Name": "Example Restaurant", "location_StartDate": "2017-01-20T00:00:00Z", "location_Latitude": 42.352314, "location_Longitude": -71.046582, "location_Start_Of_Schedule_Week_Day": "MON", "location_Address": { "address_1": "123, Main Str.", "address_Town": "London", "address_Country": "UK" }, "departments": [ { "department_Code": "12", "department_Name": "Kitchen and cooking" }, { "department_Code": "22", "department_Name": "Dining and serving" } ] }, { "location_Code": "LOC2", "location_Name": "Another Restaurant", "location_StartDate": "2017-03-21T00:00:00Z", "location_Latitude": 51.510357, "location_Longitude": -0.116773, "location_Start_Of_Schedule_Week_Day": "WED", "location_Address": { "address_1": "456, Corner Str.", "address_Town": "London", "address_Country": "UK" }, "departments": [ { "department_Code": "445", "department_Name": "Drinks and cocktails" }, { "department_Code": "889", "department_Name": "Maintenance and cleaning" } ] } ] } } ], "responses": { "202": { "description": "Accepted", "headers": { "Location": { "description": "Location of status URL", "type": "string" } } } } } }, "/export/{externalCustomerCanonicalId}/Locations": { "get": { "tags": [ "LocationExport" ], "summary": "Get locations", "description": "Returns the customer’s location data, such as the address and departments.
You can use the `If-Modified-Since` header to filter responses. This will return only records that were created or modified after the date specified in the header.", "operationId": "LocationExport_ExportLocationsAsync", "consumes": [], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "externalCustomerCanonicalId", "in": "path", "description": "Customer identifier provided by Fourth.", "required": true, "type": "string" }, { "name": "If-Modified-Since", "in": "header", "description": "Used to retrieve only records that were modified after a certain date. Example: Sun, 10 May 2020 02:01:00 GMT", "required": false, "type": "string" } ], "responses": { "200": { "description": "List of Locations and their departments.", "schema": { "type": "array", "items": { "$ref": "#/definitions/LocationFlat" } }, "examples": { "application/json": [ { "location_Name": "Example Restaurant", "location_Code": "LOC1", "address": { "address_1": "123, Main Str.", "address_Town": "London", "address_Country": "UK" }, "departments": [ { "department_Code": "12", "department_Name": "Kitchen and cooking" }, { "department_Code": "22", "department_Name": "Dining and serving" } ] }, { "location_Name": "Another Restaurant", "location_Code": "LOC2", "address": { "address_1": "456, Corner Str.", "address_Town": "London", "address_Country": "UK" }, "departments": [ { "department_Code": "445", "department_Name": "Drinks and cocktails" }, { "department_Code": "889", "department_Name": "Maintenance and cleaning" } ] } ] } } } } }, "/import/{externalCustomerCanonicalId}/PaidAbsences": { "post": { "tags": [ "PaidAbsence" ], "summary": "Add or update paid absence for one employee", "description": "Adds or updates one paid absence for an employee. The value of `reference` identifies whether you are adding a new absence or updating an existing one.
\r\n We recommend integrating with the **batchimport** version of this resource for all requests.", "operationId": "PaidAbsence_ImportPaidAbsenceAsync", "consumes": [ "application/json", "text/json", "application/xml", "text/xml" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "externalCustomerCanonicalId", "in": "path", "description": "Customer identifier provided by Fourth.", "required": true, "type": "string" }, { "name": "paidAbsence", "in": "body", "required": true, "schema": { "$ref": "#/definitions/AbsenceRecord" } } ], "responses": { "200": { "description": "OK", "schema": { "type": "object" } }, "202": { "description": "Accepted" } } } }, "/import/{externalCustomerCanonicalId}/PaidAbsences:batchImport": { "post": { "tags": [ "PaidAbsence" ], "summary": "Add or update paid absences for employees", "description": "Adds or updates the paid absences for one or more employees. The value of `reference` identifies whether you are adding a new absence or updating an existing one.", "operationId": "PaidAbsence_ImportPaidAbsencesAsync", "consumes": [ "application/json", "text/json", "application/xml", "text/xml" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "externalCustomerCanonicalId", "in": "path", "description": "Customer identifier provided by Fourth.", "required": true, "type": "string" }, { "name": "paidAbsences", "in": "body", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/AbsenceRecord" } } } ], "responses": { "200": { "description": "OK", "schema": { "type": "object" } }, "202": { "description": "Accepted" } } } }, "/import/{externalCustomerCanonicalId}/PlannedAbsences": { "post": { "tags": [ "PlannedAbsence" ], "summary": "Add or update planned absence for one employee", "description": "Adds or updates one planned absence for an employee. The value of `absence_Reference` identifies whether you are adding a new absence or updating an existing one.
\r\n We recommend integrating with the **batchimport** version of this resource for all requests.", "operationId": "PlannedAbsence_ImportPlannedAbsenceAsync", "consumes": [ "application/json", "text/json", "application/xml", "text/xml" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "externalCustomerCanonicalId", "in": "path", "description": "Customer identifier provided by Fourth.", "required": true, "type": "string" }, { "name": "plannedAbsence", "in": "body", "required": true, "schema": { "$ref": "#/definitions/Absence" } } ], "responses": { "200": { "description": "OK", "schema": { "type": "object" } }, "202": { "description": "Accepted" } } } }, "/import/{externalCustomerCanonicalId}/PlannedAbsences:batchImport": { "post": { "tags": [ "PlannedAbsence" ], "summary": "Add or update planned absences for employees", "description": "Adds or updates the planned absences for one or more employees. The value of `absence_Reference` identifies whether you are adding a new absence or updating an existing one.", "operationId": "PlannedAbsence_ImportPlannedAbsencesAsync", "consumes": [ "application/json", "text/json", "application/xml", "text/xml" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "externalCustomerCanonicalId", "in": "path", "description": "Customer identifier provided by Fourth.", "required": true, "type": "string" }, { "name": "plannedAbsences", "in": "body", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/Absence" } } } ], "responses": { "200": { "description": "OK", "schema": { "type": "object" } }, "202": { "description": "Accepted" } } } }, "/delete/{externalCustomerCanonicalId}/PlannedAbsences": { "post": { "tags": [ "PlannedAbsence" ], "summary": "Delete one planned absence", "description": "Deletes a planned absence.", "operationId": "PlannedAbsence_DeletePlannedAbsenceAsync", "consumes": [ "application/json", "text/json", "application/xml", "text/xml" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "externalCustomerCanonicalId", "in": "path", "description": "Customer identifier provided by Fourth.", "required": true, "type": "string" }, { "name": "removedAbsence", "in": "body", "required": true, "schema": { "$ref": "#/definitions/AbsenceRemoved" } } ], "responses": { "200": { "description": "OK", "schema": { "type": "object" } }, "202": { "description": "Accepted" } } } }, "/delete/{externalCustomerCanonicalId}/PlannedAbsences:batchDelete": { "post": { "tags": [ "PlannedAbsence" ], "summary": "Delete planned absences", "description": "Deletes one or more planned absences.", "operationId": "PlannedAbsence_DeletePlannedAbsencesAsync", "consumes": [ "application/json", "text/json", "application/xml", "text/xml" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "externalCustomerCanonicalId", "in": "path", "description": "Customer identifier provided by Fourth.", "required": true, "type": "string" }, { "name": "removedAbsences", "in": "body", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/AbsenceRemoved" } } } ], "responses": { "200": { "description": "OK", "schema": { "type": "object" } }, "202": { "description": "Accepted" } } } }, "/": { "get": { "tags": [ "Root" ], "summary": "Get root resource for the API", "operationId": "Root_GetAsync", "consumes": [], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [], "responses": { "200": { "description": "OK" } } } }, "/import/{externalCustomerCanonicalId}/TnARecords": { "post": { "tags": [ "TnARecord" ], "summary": "Add or update one time and attendance record", "description": "**Integrations are not currently allowed to this endpoint.** Please get in contact with Fourth if you need to submit time and attendance data.", "operationId": "TnARecord_ImportTnARecordAsync", "consumes": [ "application/json", "text/json", "application/xml", "text/xml" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "externalCustomerCanonicalId", "in": "path", "description": "Customer identifier provided by Fourth.", "required": true, "type": "string" }, { "name": "tnaRecord", "in": "body", "description": "The Time and Attendance record.", "required": true, "schema": { "$ref": "#/definitions/TnAData" } } ], "responses": { "202": { "description": "Accepted", "headers": { "Location": { "description": "Location of status URL", "type": "string" } } } } } }, "/import/{externalCustomerCanonicalId}/TnARecords:batchImport": { "post": { "tags": [ "TnARecord" ], "summary": "Add or update time and attendance records", "description": "**Integrations are not currently allowed to this endpoint.** Please get in contact with Fourth if you need to submit time and attendance data.", "operationId": "TnARecord_BatchImportTnARecordsAsync", "consumes": [ "application/json", "text/json", "application/xml", "text/xml" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "externalCustomerCanonicalId", "in": "path", "description": "Customer identifier provided by Fourth.", "required": true, "type": "string" }, { "name": "tnaRecords", "in": "body", "description": "The collection of Time and Attendance records.", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/TnAData" }, "example": [ { "employee_ID": "EMP_1", "payroll_No": "", "employee_First_Name": "John", "employee_Last_Name": "Smith", "location_Code": "LOC1", "department_Code": "DEP1", "type": "CLOCKIN", "event_Date": "2019-01-20T00:00:00Z", "payments": [ { "reference": "XY123", "payment_Type": "Example payment text", "value": 10.0, "currency": "USD", "payment_Date": "2019-01-20T00:00:00Z", "location_Code": "LOC1", "record_Type": "PROCESSED_TIPS" } ], "notes": "Sonce notes", "submission_Date": "2019-01-21T00:00:00Z", "clock_In": "2019-01-20T09:00:00Z", "pay_Rate": 40.0, "rate_Type": "HOURLY", "job_Code": "J1" }, { "employee_ID": "", "payroll_No": "40005", "employee_First_Name": "Marry", "employee_Last_Name": "Adams", "location_Code": "LOC2", "department_Code": "DEP2", "type": "CLOCKOUT", "event_Date": "2019-01-20T00:00:00Z", "payments": [], "notes": "Some example attendance notes", "submission_Date": "2017-01-21T00:00:00Z", "clock_Out": "2017-01-20T18:00:00Z", "pay_Rate": 240.0, "rate_Type": "WEEKLY_SALARY", "job_Code": "J2" } ] } } ], "responses": { "202": { "description": "Accepted", "headers": { "Location": { "description": "Location of status URL", "type": "string" } } } } } } }, "definitions": { "AbsenceFlat": { "type": "object", "properties": { "reference": { "type": "string" }, "employeeExternalId": { "type": "string" }, "userCanonicalId": { "type": "string" }, "payrollNo": { "type": "string" }, "type": { "type": "string" }, "days": { "format": "int32", "type": "integer" }, "startDate": { "format": "date-time", "type": "string" }, "endDate": { "format": "date-time", "type": "string" }, "status": { "type": "string" }, "percentPaid": { "format": "float", "type": "number" }, "reason": { "type": "string" }, "expectedReturnDate": { "format": "date-time", "type": "string" }, "maternityDueDate": { "format": "date-time", "type": "string" }, "maternityDeliveryDate": { "format": "date-time", "type": "string" }, "jobCode": { "type": "string" }, "locationCode": { "type": "string" }, "locationCanonicalId": { "type": "string" }, "departmentCode": { "type": "string" } } }, "AdditionalPayment": { "required": [ "employee_First_Name", "employee_Last_Name", "payment_Type" ], "type": "object", "properties": { "reference": { "type": "string" }, "assignment_Reference": { "description": "The unique identifier for the assignment, from the external platform.
**Max length:** 45 characters", "type": "string" }, "employee_ID": { "description": "The unique identifier for the employee, from the external platform.
\r\n**Max length:** 68 characters", "type": "string" }, "payroll_No": { "type": "string" }, "employee_First_Name": { "type": "string" }, "employee_Last_Name": { "type": "string" }, "payment_Type": { "type": "string" }, "record_Type": { "type": "string" }, "location_Code": { "type": "string" }, "department_Code": { "description": "The external department ID.", "type": "string" }, "value": { "format": "double", "description": "The payment amount.", "maximum": 100000, "type": "number" }, "currency": { "description": "The currency code in ISO 4217.\r\nIf blank, then default to context.", "type": "string" }, "payment_Date": { "format": "date-time", "type": "string" } } }, "Assignment": { "required": [ "assigment_Reference", "location_Code", "job_Code", "rate_Type" ], "type": "object", "properties": { "assigment_Reference": { "description": "The unique identifier for the assignment, from the external platform.
**Max length:** 45 characters", "type": "string" }, "employment_ID": { "description": "Used to identify employment related to this assignment.", "type": "string" }, "employee_ID": { "description": "The unique identifier for the employee, from the external platform.
\r\n**Max length:** 68 characters", "type": "string" }, "assignment_Start_Date": { "format": "date-time", "description": "Required, in ISO-8601 format. Date and assignment starts.", "type": "string" }, "assignment_End_Date": { "format": "date-time", "description": "The date an assignment ends, in ISO-8601 format.", "type": "string" }, "main_Assignment": { "description": "Used to identify the Main Assignment in case there are multiple.", "type": "boolean" }, "location_Code": { "description": "Location to which this assignment is allocated. See Location resource for details.", "type": "string" }, "department_Code": { "description": "Identifier of the department within the location that the assignment is for.", "type": "string" }, "job_Code": { "description": "Required. Job code applicable to assignment record. See Job_Title resource for details.", "type": "string" }, "shift_Type": { "description": "The shift applicable to assignment record – this would not normally be used where the shift type was included in Pay Parts.", "type": "string" }, "working_Pattern": { "description": "Sequence of working pattern. Represented by a set of seven 1s and 0s indicating the days of the week the employee is available.\r\ne.g. 1111111 - means the employee is available to work on all seven days in the week.", "type": "string" }, "rate_Type": { "description": "Possible values are: `HOURLY`, `HOURLY_GUARANTEED_HOURS`, `WEEKLY_SALARY`, `WEEKLY_SALARY_PLUS`, `MONTHLY_SALARY`, `UNPAID` and `YEARLY_SALARY`.", "type": "string" }, "contracted_Hours": { "format": "double", "description": "Basic contracted hours.", "type": "number" }, "attributes": { "description": "Key value pair of strings (Attribute_Name, Attribute_Value) for additional Assignment attributes.", "type": "array", "items": { "$ref": "#/definitions/Attribute" } }, "rates": { "description": "Payment rates for the assignment.", "type": "array", "items": { "$ref": "#/definitions/Rate" } } } }, "Attribute": { "required": [ "attribute_Name", "attribute_Value" ], "type": "object", "properties": { "attribute_Name": { "type": "string" }, "attribute_Value": { "type": "string" } } }, "Rate": { "required": [ "rate_Unit", "rate_Amount" ], "type": "object", "properties": { "rate_Unit": { "description": "Required. One of: HOUR, DAY, WEEK, MONTH, YEAR, SHIFT.", "type": "string" }, "rate_Amount": { "format": "double", "description": "Required. Base pay rate.", "type": "number" } } }, "AssignmentRemoved": { "required": [ "employee_ID", "assigment_Reference" ], "type": "object", "properties": { "employee_ID": { "description": "The unique identifier for the employee, from the external platform.
\r\n**Max length:** 68 characters", "type": "string" }, "assigment_Reference": { "description": "The unique identifier for the assignment, from the external platform.
\r\n**Max length:** 45 characters", "type": "string" } }, "example": { "employee_ID": "123", "assigment_Reference": "00000000-0000-0000-0000-000000000000" } }, "Employee": { "required": [ "employee_ID", "personal_Details", "contact_Details" ], "type": "object", "properties": { "employee_ID": { "description": "The unique identifier for the employee, from the external platform.
\r\n**Max length:** 68 characters", "type": "string" }, "userCanonicalId": { "type": "string" }, "personal_Details": { "$ref": "#/definitions/Personal_Details" }, "contact_Details": { "$ref": "#/definitions/Contact_Details" }, "dependents": { "type": "array", "items": { "$ref": "#/definitions/Dependent" } }, "next_of_Kins": { "type": "array", "items": { "$ref": "#/definitions/Next_of_Kin" } }, "payment_Details": { "type": "array", "items": { "$ref": "#/definitions/Payment_Detail" } }, "employment_Details": { "type": "array", "items": { "$ref": "#/definitions/Employment" } }, "documents": { "type": "array", "items": { "$ref": "#/definitions/Documentation" } }, "absences": { "type": "array", "items": { "$ref": "#/definitions/Absence" } }, "pay_Parts": { "type": "array", "items": { "$ref": "#/definitions/Pay_Part" } }, "payslips": { "type": "array", "items": { "$ref": "#/definitions/Payslip" } }, "claims": { "type": "array", "items": { "$ref": "#/definitions/Claim" } } } }, "Personal_Details": { "required": [ "payroll_No", "first_Name", "last_Name" ], "type": "object", "properties": { "payroll_No": { "type": "string" }, "first_Name": { "description": "First name of the employee.
\r\nIf the employee's first, middle or last name contains any special characters, then these characters may be removed from the name when shown in our user interface and in some other Fourth API responses. For example, `Solange#` will show as `Solange` instead. The characters removed include: **~ , ; : ? # $ > < ^ %**", "type": "string" }, "middle_Name": { "description": "Middle name of the employee.", "type": "string" }, "last_Name": { "description": "Surname of the employee.", "type": "string" }, "preferred_Name": { "type": "string" }, "title": { "type": "string" }, "initials": { "type": "string" }, "gender": { "type": "string" }, "date_of_Birth": { "format": "date-time", "type": "string" }, "date_of_Death": { "format": "date-time", "type": "string" }, "ethnic_Origin": { "type": "string" }, "nationality": { "type": "string" }, "marital_Status": { "type": "string" }, "marital_Status_Date": { "format": "date-time", "type": "string" }, "education_Level": { "type": "string" }, "disabled": { "type": "boolean" }, "disability": { "type": "string" }, "passport": { "$ref": "#/definitions/Passport" } } }, "Contact_Details": { "required": [ "email", "telephone" ], "type": "object", "properties": { "addresses": { "type": "array", "items": { "$ref": "#/definitions/Address" } }, "email": { "$ref": "#/definitions/Employee_Email" }, "telephone": { "$ref": "#/definitions/Telephone" } } }, "Dependent": { "required": [ "dependent_Reference", "dependent_Name" ], "type": "object", "properties": { "dependent_Reference": { "type": "string" }, "dependent_Name": { "type": "string" }, "dependent_Type": { "type": "string" }, "dependent_DOB": { "format": "date-time", "type": "string" }, "dependent_ID": { "type": "string" }, "dependent_Nationality": { "type": "string" }, "dependent_Passport_No": { "type": "string" }, "dependent_Percent": { "type": "string" }, "dependent_Gender": { "type": "string" }, "dependent_Occupation": { "type": "string" }, "dependent_Income": { "format": "double", "type": "number" }, "dependent_Addresses": { "type": "array", "items": { "$ref": "#/definitions/Address" } }, "dependent_Telephone": { "$ref": "#/definitions/Telephone" }, "isObsolete": { "type": "boolean" } } }, "Next_of_Kin": { "required": [ "noK_Reference", "noK_Name" ], "type": "object", "properties": { "noK_Reference": { "type": "string" }, "noK_Name": { "type": "string" }, "noK_Relationship": { "type": "string" }, "noK_Addresses": { "type": "array", "items": { "$ref": "#/definitions/Address" } }, "noK_Telephone": { "$ref": "#/definitions/Telephone" }, "noK_Email": { "$ref": "#/definitions/External_Email" } } }, "Payment_Detail": { "type": "object", "properties": { "pay_Method": { "type": "string" }, "account_Details": { "$ref": "#/definitions/Account_Details" }, "split_Payment": { "$ref": "#/definitions/Split_Payment" } } }, "Employment": { "type": "object", "properties": { "employer_ID": { "description": "Id of corresponding employer.", "type": "string" }, "employment_Reference": { "description": "Used to identify record where employee has consecutive or concurrent periods of employment contract.", "type": "string" }, "employment_Join_Date": { "format": "date-time", "description": "The date that the employment contract begins, in ISO-8601 format.", "type": "string" }, "first_Working_Day": { "format": "date-time", "description": "The first working day of the employee under this employment. This is used when applying wage or employment rules. Format is ISO-8601.", "type": "string" }, "original_Hire_Date": { "format": "date-time", "description": "In ISO-8601 format. Date used where employee legal entitlement or continuity of employment precedes the current employment record.", "type": "string" }, "employment_Leave_Date": { "format": "date-time", "description": "End date for the employment, in ISO-8601 format.", "type": "string" }, "termination_Reason": { "description": "The reason why the employment was terminated, such as \"resigned\" or \"dismissed\". This is used for payment, tax and reporting purposes. For some customers, it may be superseded by a country specific element with fixed options.\r\n
If the termination reason is longer than the maximum length, then the string is truncated. \r\n
Max length: 512 characters", "type": "string" }, "rehire": { "description": "`True` — the employee has been rehired by this business.
\r\n`False` — the employee is working for this business for the first time.", "type": "boolean" }, "employment_Type": { "description": "One of: `contractor`, `employee`, `temp`, `agency`, `live_in` or `executive`.", "type": "string" }, "employment_Status": { "description": "One of: `active` or `inactive`.", "type": "string" }, "contract_Perm": { "description": "`True` — a permanent employee
\r\n`False` — a temporarily employee", "type": "boolean" }, "contract_Fulltime": { "description": "`True` — full time employment
\r\n`False` — part time employment", "type": "boolean" }, "contracted_Hours": { "format": "double", "description": "Basic contracted hours.", "type": "number" }, "fte": { "description": "Full time equivalent.", "type": "string" }, "foreign_Student": { "description": "Indicates if employee is a foreign student.", "type": "string" }, "pay_Group": { "description": "Used to group employees for processing or reporting, not necessarily the same as cost centre.", "type": "string" }, "live_In": { "description": "Employee resident on site or provided with accommodation.", "type": "boolean" }, "assignments": { "description": "Assignments for the current employment contract.", "type": "array", "items": { "$ref": "#/definitions/Assignment" } }, "break_Waiver": { "description": "True if the employee waived his/her break rights.", "type": "boolean" }, "employment_Authorization": { "description": "Status of the employment's authorization (e.g. I-9 case result).", "type": "string" }, "onboarding_Status": { "description": "Status of the employee's onboarding process.", "type": "string" } } }, "Documentation": { "type": "object", "properties": { "doc_Reference": { "type": "string" }, "doc_Type": { "type": "string" }, "doc_Number": { "type": "string" }, "doc_Country": { "type": "string" }, "doc_Issue_Date": { "format": "date-time", "type": "string" }, "doc_Arrival_Date": { "format": "date-time", "type": "string" }, "doc_Expiry_Date": { "format": "date-time", "type": "string" }, "doc_Holiday_Start": { "format": "date-time", "type": "string" }, "doc_Holiday_End": { "format": "date-time", "type": "string" }, "doc_Required": { "type": "boolean" }, "doc_Processed": { "type": "boolean" } } }, "Absence": { "required": [ "employee_ID", "job_Code", "absence_Reference", "absence_Type", "absence_Status" ], "type": "object", "properties": { "employee_ID": { "description": "The unique identifier for the employee, from the external platform.
\r\n**Max length:** 68 characters", "type": "string" }, "job_Code": { "description": "A unique identifier for the job, from the external platform.", "type": "string" }, "absence_Reference": { "description": "A unique identifier for the absence, from the external platform.", "type": "string" }, "absence_Type": { "description": "The absence type. Possible values are defined by the customer and partner.", "type": "string" }, "absence_Days": { "format": "int64", "description": "Number of days the employee will be unavailable for work, including the start date.", "type": "integer" }, "absence_Start_Date": { "format": "date-time", "description": "First day that the employee will not be available for work. Use the ISO-8601 format: `yyyy-mm-ddThh:mm:ss`.", "type": "string" }, "absence_End_Date": { "format": "date-time", "description": "Last day that the employee will not be available for work. This field is optional when `Absence_Days` has a value. Format: `yyyy-mm-ddThh:mm:ss`.", "type": "string" }, "absence_Status": { "description": "Available options are: `actual` and `forecast`.", "type": "string" }, "absence_Paid": { "format": "int64", "description": " This field is reserved for future use. Any value currently sent is stored but not used.\r\n
\r\n The proportion of pay the employee will receive during this planned absence. For example: `50` is 50%.", "type": "integer" }, "absence_Reason": { "description": "Provides a more detailed description of the leave. This is available in payroll processing and reporting, but not HR reporting.", "type": "string" }, "absence_Expected_Return": { "format": "date-time", "description": "First day that the employee is expected to be available for work. Format: `yyyy-mm-ddThh:mm:ss`.", "type": "string" }, "absence_Expected_Return_Date": { "format": "date-time", "description": "First day that the employee is expected to be available for work. This field is used for long term absences where payment to the employee is suspended. Format: `yyyy-mm-ddThh:mm:ss`.", "type": "string" }, "absence_Maternity_Due_Date": { "format": "date-time", "description": "For maternity leave only. This is the expected due date for the pregnancy. Format: `yyyy-mm-ddThh:mm:ss`.
\r\nWhether you need to send maternity data depends on the Fourth services your customer is using; for example, most payroll partners will need to send this to Fourth, while most HR partners will not.", "type": "string" }, "absence_Maternity_Delivery_Date": { "format": "date-time", "description": "For maternity leave only. This is the actual delivery date for the pregnancy. Format: `yyyy-mm-ddThh:mm:ss`.", "type": "string" }, "absence_Documents": { "description": "The details of any forms or documentation provided for the absence, such as a maternity certificate.", "type": "array", "items": { "$ref": "#/definitions/Documentation" } }, "half_Day": { "description": "Whether this is a half day absence. You must submit half day absences to Fourth separately from full days. Options are:
\r\n — `false`: the absence is for one or more full days.
\r\n — `true`: the absence is for a half day only. The `absence_Start_Date` and `absence_End_Date` (if included) must be for the same day, and `absence_Days` (if included) must be set to `1`.", "type": "boolean" } } }, "Pay_Part": { "type": "object", "properties": { "element_Name": { "type": "string" }, "element_Local_Ref": { "type": "string" }, "pay_Part_Values": { "type": "array", "items": { "$ref": "#/definitions/Pay_Part_Value" } } } }, "Payslip": { "type": "object", "properties": { "payslip_Reference": { "type": "string" }, "payslip_Date": { "format": "date-time", "type": "string" }, "payment_Date": { "format": "date-time", "type": "string" }, "tax_Category": { "type": "string" }, "tax_Rate": { "type": "string" }, "social_Security_Category": { "type": "string" }, "social_Security_Rate": { "type": "string" }, "pay_Group": { "type": "string" }, "transactions": { "type": "array", "items": { "$ref": "#/definitions/Transaction" } } } }, "Claim": { "required": [ "claim_Name", "claim_Value" ], "type": "object", "properties": { "claim_Name": { "type": "string" }, "claim_Value": { "type": "string" } } }, "Passport": { "required": [ "passport_No", "issuing_Country" ], "type": "object", "properties": { "passport_Reference": { "type": "string" }, "passport_No": { "type": "string" }, "issuing_Country": { "description": "The country whose name is on the cover of the passport, in ISO 3166-1 alpha-2 format. For example, `GB` for Great Britain.", "type": "string" }, "issue_Date": { "format": "date-time", "type": "string" }, "expiry_Date": { "format": "date-time", "type": "string" } } }, "Address": { "required": [ "address_1", "address_Town", "address_Country" ], "type": "object", "properties": { "address_Reference": { "type": "string" }, "address_Type": { "type": "string" }, "address_Effective_Date": { "format": "date-time", "type": "string" }, "address_1": { "type": "string" }, "address_2": { "type": "string" }, "address_3": { "type": "string" }, "address_4": { "type": "string" }, "address_Town": { "type": "string" }, "address_Municipality": { "type": "string" }, "address_District": { "type": "string" }, "address_Code": { "type": "string" }, "address_Zip": { "type": "string" }, "address_Zip_Addition": { "type": "string" }, "address_Province": { "type": "string" }, "address_Country": { "type": "string" }, "address_Is_Obsolete": { "type": "boolean" }, "address_Obsolete_Date": { "format": "date-time", "type": "string" } } }, "Employee_Email": { "required": [ "email_Home" ], "type": "object", "properties": { "email_Work": { "type": "string" }, "email_Home": { "type": "string" } } }, "Telephone": { "required": [ "tel_Mobile" ], "type": "object", "properties": { "tel_Work": { "type": "string" }, "tel_Home": { "type": "string" }, "tel_Mobile": { "type": "string" } } }, "External_Email": { "type": "object", "properties": { "email_Work": { "type": "string" }, "email_Home": { "type": "string" } } }, "Account_Details": { "required": [ "account_Number", "iban", "biC_Swift", "account_Currency", "reference" ], "type": "object", "properties": { "account_Name": { "type": "string" }, "account_Number": { "type": "string" }, "iban": { "type": "string" }, "branch_Code": { "type": "string" }, "biC_Swift": { "type": "string" }, "branch_Name": { "type": "string" }, "bank": { "type": "string" }, "account_Type": { "type": "string" }, "account_Currency": { "type": "string" }, "reference": { "type": "string" }, "isObsolete": { "type": "boolean" } } }, "Split_Payment": { "type": "object", "properties": { "split_Type": { "type": "string" }, "split_Value": { "type": "string" }, "split_Order": { "type": "string" } } }, "Pay_Part_Value": { "type": "object", "properties": { "start_Datetime": { "format": "date-time", "type": "string" }, "end_Datetime": { "format": "date-time", "type": "string" }, "units": { "type": "string" }, "unit_Type": { "type": "string" }, "rate": { "format": "double", "type": "number" }, "value": { "format": "double", "type": "number" }, "reference": { "type": "string" }, "assignment_Reference": { "description": "The unique identifier for the assignment, from the external platform.
**Max length:** 45 characters", "type": "string" }, "job_Code": { "type": "string" }, "site_Code": { "type": "string" }, "shift_Type": { "type": "string" }, "attributes": { "type": "array", "items": { "$ref": "#/definitions/Attribute" } } } }, "Transaction": { "type": "object", "properties": { "element_Name": { "type": "string" }, "element_Code": { "type": "string" }, "element_Category": { "type": "string" }, "units": { "type": "string" }, "unit_Type": { "type": "string" }, "rate": { "format": "double", "type": "number" }, "value": { "format": "double", "type": "number" }, "reference": { "type": "string" }, "job_Code": { "type": "string" }, "site_Code": { "type": "string" }, "department": { "type": "string" }, "cost_Centre": { "type": "string" } } }, "GetEmployeeFlat": { "description": "Model to map get employee uri parameters.", "type": "object", "properties": { "locationCode": { "description": "Returns only employees for the location matching the **location code**.", "type": "string" }, "startDate": { "format": "date-time", "description": "Use with `employeesFilter.endDate` to filter the employees by time range. You must use both parameters. The dates are inclusive, and must use the format: yyyy-MM-ddThh:mm:ssZ; for example, `2020-12-25T00:00:00Z`.", "type": "string" }, "endDate": { "format": "date-time", "description": "Use with `employeesFilter.startDate` to specify a time range.", "type": "string" } } }, "EmployeeFlat": { "type": "object", "properties": { "employee_ID": { "description": "The unique identifier for the employee, from the external platform.
\r\n**Max length:** 68 characters", "type": "string" }, "user_ID": { "description": "The user identifier within Fourth's system.", "type": "string" }, "email_Home": { "description": "The personal email of the employee.", "type": "string" }, "payroll_No": { "description": "The personal payroll number of the employee.", "type": "string" }, "first_Name": { "description": "The first name of the employee.", "type": "string" }, "last_Name": { "description": "The surname of the employee.", "type": "string" }, "date_Of_Birth": { "format": "date-time", "description": "The birth date of the employee.", "type": "string" }, "employments": { "type": "array", "items": { "$ref": "#/definitions/EmploymentFlat" } } } }, "EmploymentFlat": { "type": "object", "properties": { "employment_Join_Date": { "format": "date-time", "description": "The date that the employment contract begins, in ISO-8601 format.", "type": "string" }, "first_Working_Day": { "format": "date-time", "description": "The first working day of the employee under this employment. This is used when applying wage or employment rules. Format is ISO-8601.", "type": "string" }, "original_Hire_Date": { "format": "date-time", "description": "The date that the employee was originally hired.", "type": "string" }, "employment_Leave_Date": { "format": "date-time", "description": "The last working day of the employee, based on their contract.", "type": "string" }, "contracted_Hours": { "format": "double", "description": "The number of working hours that the employee is contracted to do a time period.", "type": "number" }, "pay_Group": { "description": "The employee's pay group, according to which payment rules will be applied.", "type": "string" }, "break_Waiver": { "description": "Whether the employee waived their right to a break.", "type": "boolean" }, "employment_Authorization": { "description": "The status of the employment's authorization (e.g. I-9 case result).\r\nPossible values: `NO_AUTHORIZATION_STATUS`, `NOT_COMPLETED`, `COMPLETED`, and `EXPIRED`.", "type": "string" }, "onboarding_Status": { "description": "The status of the employee's onboarding process.\r\nPossible values are: `NO_ONBOARDING_STATUS`, `ONGOING` and `COMPLETE`.", "type": "string" }, "assignments": { "type": "array", "items": { "$ref": "#/definitions/AssignmentFlat" } } } }, "AssignmentFlat": { "type": "object", "properties": { "assignment_Start_Date": { "format": "date-time", "description": "The first working day of an assignment within the employment contract of the employee.", "type": "string" }, "assignment_End_Date": { "format": "date-time", "description": "The last working day of an assignment within the employment contract of the employee.", "type": "string" }, "main_Assignment": { "description": "Whether this is a **main** or **secondary** assignment. See our [API Guide](https://developer.fourth.com/en-gb/docs/labor-productivity-api/guide) for information about main and secondary assignments.\r\n`true` — this is a main assignment
\r\n`false` — this is a secondary assignment", "type": "boolean" }, "location_Code": { "description": "The external system code of the location where the employee has been assigned to work.", "type": "string" }, "department_Code": { "description": "The external system code of the department where the employee has been assigned to work.", "type": "string" }, "job_Code": { "description": "The external system code of the job that the employees has been assigned to work.", "type": "string" }, "rate_Type": { "description": "The rate based on which the employee is paid.\r\nPossible values: `HOURLY`, `HOURLY_GUARANTEED_HOURS`, `WEEKLY_SALARY`, `WEEKLY_SALARY_PLUS`, `MONTHLY_SALARY` and `UNPAID`.", "type": "string" }, "rate_Currency": { "description": "The currency the employee is paid, in ISO 4217 format.", "type": "string" }, "is_Tippable": { "description": "Whether the employee assignment allows tips.", "type": "boolean" }, "is_Exempt": { "description": "Whether the employee assignment is exempt.", "type": "boolean" }, "rates": { "type": "array", "items": { "$ref": "#/definitions/AssignmentRateFlat" } } } }, "AssignmentRateFlat": { "type": "object", "properties": { "rate_Amount": { "format": "double", "description": "The amount the employee is paid based on their rate unit.", "type": "number" }, "rate_Unit": { "description": "The payment based on time period. Possible values are: `HOUR`, `DAY`, `WEEK`, `MONTH`, `YEAR` and `SHIFT`.", "type": "string" } } }, "EmployeeRestricted": { "type": "object", "properties": { "employee_ID": { "description": "The unique identifier for the employee, from the external platform.
\r\n**Max length:** 68 characters", "type": "string" }, "user_ID": { "description": "The user identifier within Fourth's system.", "type": "string" }, "payroll_No": { "description": "The personal payroll number of the employee.", "type": "string" }, "first_Name": { "description": "The first name of the employee.", "type": "string" }, "last_Name": { "description": "The surname of the employee.", "type": "string" }, "employments": { "type": "array", "items": { "$ref": "#/definitions/EmploymentRestricted" } } } }, "EmploymentRestricted": { "type": "object", "properties": { "employment_Join_Date": { "format": "date-time", "description": "The date that the employment contract begins, in ISO-8601 format.", "type": "string" }, "first_Working_Day": { "format": "date-time", "description": "The first working day of the employee under this employment. This is used when applying wage or employment rules. Format is ISO-8601.", "type": "string" }, "original_Hire_Date": { "format": "date-time", "description": "The date the employee was originally hired.", "type": "string" }, "employment_Leave_Date": { "format": "date-time", "description": "The date that the employee leaves the organization.\r\nDefined as the last working day of the employee based on his contract in the organization.", "type": "string" }, "pay_Group": { "description": "The employees pay group according to which payment rules will be applied.", "type": "string" }, "break_Waiver": { "description": "Whether the employee waived their right to breaks.", "type": "boolean" }, "employment_Authorization": { "description": "The status of the employment's authorization (e.g. I-9 case result).\r\nPossible values are: `NO_AUTHORIZATION_STATUS`, `NOT_COMPLETED`, `COMPLETED`, and `EXPIRED`.", "type": "string" }, "onboarding_Status": { "description": "The status of the employee's onboarding process.\r\nPossible values are: `NO_ONBOARDING_STATUS`, `ONGOING`, and `COMPLETE`.", "type": "string" }, "assignments": { "type": "array", "items": { "$ref": "#/definitions/AssignmentRestricted" } } } }, "AssignmentRestricted": { "type": "object", "properties": { "assignment_Start_Date": { "format": "date-time", "description": "The assignment start date.\r\nDefined as the first working day of an assignment within the employment contract of the employee.", "type": "string" }, "assignment_End_Date": { "format": "date-time", "description": "The assignment end date.\r\nDefined as the last working day of an assignment within the employment contract of the employee.", "type": "string" }, "main_Assignment": { "description": "Whether this is a **main** or **secondary** assignment. See our [API Guide](https://developer.fourth.com/en-gb/docs/labor-productivity-api/guide) for information about main and secondary assignments.
\r\n`true` — this is a main assignment
\r\n`false` — this is a secondary assignment", "type": "boolean" }, "location_Code": { "description": "The external platform's code for the location where the employee works.", "type": "string" }, "department_Code": { "description": "The external platform's code for the department where the employee works.", "type": "string" }, "job_Code": { "description": "The external platform's code for the employee's job title.", "type": "string" }, "rate_Type": { "description": "The rate based on which the employee is paid.\r\nPossible values are: `HOURLY`, `HOURLY_GUARANTEED_HOURS`, `WEEKLY_SALARY`, `WEEKLY_SALARY_PLUS`, `MONTHLY_SALARY` and `UNPAID`.", "type": "string" }, "rate_Currency": { "description": "The currency in which the employee is paid, in ISO 4217 format.", "type": "string" }, "is_Tippable": { "description": "Whether the employee assignment allows tips.", "type": "boolean" }, "is_Exempt": { "description": "Whether the employee assignment is exempt.", "type": "boolean" } } }, "Employment_Detail": { "required": [ "employee_ID" ], "type": "object", "properties": { "employee_ID": { "description": "The unique identifier for the employee, from the external platform.
\r\n**Max length:** 68 characters", "type": "string" }, "employer_ID": { "description": "Id of corresponding employer.", "type": "string" }, "employment_Reference": { "description": "Used to identify record where employee has consecutive or concurrent periods of employment contract.", "type": "string" }, "employment_Join_Date": { "format": "date-time", "description": "The date that the employment contract begins, in ISO-8601 format.", "type": "string" }, "first_Working_Day": { "format": "date-time", "description": "The first working day of the employee under this employment. This is used when applying wage or employment rules. Format is ISO-8601.", "type": "string" }, "original_Hire_Date": { "format": "date-time", "description": "In ISO-8601 format. Date used where employee legal entitlement or continuity of employment precedes the current employment record.", "type": "string" }, "employment_Leave_Date": { "format": "date-time", "description": "End date for the employment, in ISO-8601 format.", "type": "string" }, "termination_Reason": { "description": "The reason why the employment was terminated, such as \"resigned\" or \"dismissed\". This is used for payment, tax and reporting purposes. For some customers, it may be superseded by a country specific element with fixed options.\r\n
If the termination reason is longer than the maximum length, then the string is truncated. \r\n
Max length: 512 characters", "type": "string" }, "rehire": { "description": "`True` — the employee has been rehired by this business.
\r\n`False` — the employee is working for this business for the first time.", "type": "boolean" }, "employment_Type": { "description": "One of: `contractor`, `employee`, `temp`, `agency`, `live_in` or `executive`.", "type": "string" }, "employment_Status": { "description": "One of: `active` or `inactive`.", "type": "string" }, "contract_Perm": { "description": "`True` — a permanent employee
\r\n`False` — a temporarily employee", "type": "boolean" }, "contract_Fulltime": { "description": "`True` — full time employment
\r\n`False` — part time employment", "type": "boolean" }, "contracted_Hours": { "format": "double", "description": "Basic contracted hours.", "type": "number" }, "fte": { "description": "Full time equivalent.", "type": "string" }, "foreign_Student": { "description": "Indicates if employee is a foreign student.", "type": "string" }, "pay_Group": { "description": "Used to group employees for processing or reporting, not necessarily the same as cost centre.", "type": "string" }, "live_In": { "description": "Employee resident on site or provided with accommodation.", "type": "boolean" }, "assignments": { "description": "Assignments for the current employment contract.", "type": "array", "items": { "$ref": "#/definitions/Assignment" } }, "break_Waiver": { "description": "True if the employee waived his/her break rights.", "type": "boolean" }, "employment_Authorization": { "description": "Status of the employment's authorization (e.g. I-9 case result).", "type": "string" }, "onboarding_Status": { "description": "Status of the employee's onboarding process.", "type": "string" } }, "example": { "employee_ID": "123", "employer_ID": "0001000", "employment_Reference": "0001000.123", "employment_Join_Date": "2017-01-20T00:00:00Z", "first_Working_Day": "2017-01-21T00:00:00Z", "employment_Leave_Date": "2020-06-21T00:00:00Z", "employment_Type": "EMPLOYEE", "employment_Status": "ACTIVE", "contract_Perm": true, "contract_Fulltime": true, "assignments": [ { "assigment_Reference": "0001000.123.A01", "employment_ID": "0001000.123", "assignment_Start_Date": "2017-01-21T00:00:00Z", "main_Assignment": true, "location_Code": "LOC_01", "department_Code": "DEP_01", "job_Code": "JOB_01", "rate_Type": "HOURLY", "attributes": [], "rates": [ { "rate_Unit": "HOUR", "rate_Amount": 15.5 } ] } ] } }, "EmploymentRemoved": { "required": [ "employee_ID" ], "type": "object", "properties": { "employee_ID": { "description": "The unique identifier for the employee, from the external platform.
\r\n**Max length:** 68 characters", "type": "string" }, "employment_Join_Date": { "format": "date-time", "description": "The date that the employment contract begins, in ISO-8601 format.", "type": "string" } }, "example": { "employee_ID": "123", "employment_Join_Date": "2017-01-20T00:00:00Z" } }, "JobTitle": { "required": [ "job_Code", "job_Name" ], "type": "object", "properties": { "job_Code": { "description": "System job code.", "type": "string" }, "job_Name": { "description": "Job description.", "type": "string" }, "is_Tippable": { "description": "Whether employees can earn tips (cash or card) directly while working this job. Either `true` or `false`.
", "type": "boolean" }, "is_Indirectly_Tippable": { "description": "", "type": "boolean" }, "isObsolete": { "description": "Whether the job title has become obsolete (or inactive) at the business.
\r\n`true` — the job title is obsolete
\r\n`false` — the job title is current/active", "type": "boolean" }, "obsoleteDate": { "format": "date-time", "description": "The date the job title became obsolete, if applicable.", "type": "string" }, "attributes": { "type": "array", "items": { "$ref": "#/definitions/Attribute" } } }, "example": { "job_Code": "BRT", "job_Name": "Bartender", "is_Tippable": true } }, "JobTitleFlat": { "type": "object", "properties": { "job_Code": { "description": "The job code.", "type": "string" }, "job_Name": { "description": "The job name.", "type": "string" }, "is_Tippable": { "description": "Whether the job is tippable.", "type": "boolean" }, "is_Indirectly_Tippable": { "description": "Whether the job is indirectly tippable.", "type": "boolean" }, "is_Obsolete": { "description": "Whether the job is obsolete.", "type": "boolean" }, "obsolete_Date": { "format": "date-time", "description": "The date the job became obsolete.", "type": "string" }, "attributes": { "description": "List of attributes describing the job.", "type": "array", "items": { "$ref": "#/definitions/AttributeFlat" } }, "created_Date": { "format": "date-time", "description": "When the job was created.", "type": "string" }, "last_Modified_Date": { "format": "date-time", "description": "When the location was last modified.", "type": "string" } } }, "AttributeFlat": { "type": "object", "properties": { "attribute_Name": { "type": "string" }, "attribute_Value": { "type": "string" } } }, "Location": { "required": [ "location_Code", "location_Name" ], "type": "object", "properties": { "location_Code": { "description": "Internal code, used for identification of a location. Should be unique in context of one organization (client). An internal ID can be used for this field if there is no specific code field in external system.", "type": "string" }, "location_Name": { "description": "Location name.", "type": "string" }, "location_StartDate": { "format": "date-time", "description": "When this location becomes active.", "type": "string" }, "location_Latitude": { "format": "double", "description": "Geographical latitude.", "type": "number" }, "location_Longitude": { "format": "double", "description": "Geographical longitude.", "type": "number" }, "location_Start_Of_Schedule_Week_Day": { "description": "Start of scheduling. Possible values are: `MON`, `TUE`, `WED`, `THU`, `SAT` and `SUN`.", "type": "string" }, "location_IsObsolete": { "description": "Whether the location has become obsolete at the business.
\r\n`true` — the location is no longer in use
\r\n`false` — the location is in use", "type": "boolean" }, "location_ObsoleteDate": { "format": "date-time", "description": "The date the location became obsolete, if applicable.", "type": "string" }, "location_Address": { "$ref": "#/definitions/Address", "description": "The address of the location." }, "attributes": { "description": "Attributes for the location, such as the Fair Labor Standards Act (FLSA) ruleset.", "type": "array", "items": { "$ref": "#/definitions/Attribute" } }, "departments": { "description": "The departments that exist within this location.", "type": "array", "items": { "$ref": "#/definitions/Department" } } }, "example": { "location_Code": "LOC1", "location_Name": "Example Restaurant", "location_StartDate": "2017-01-20T00:00:00Z", "location_Latitude": 42.352314, "location_Longitude": -71.046582, "location_Start_Of_Schedule_Week_Day": "MON", "location_Address": { "address_1": "123, Main Str.", "address_Town": "London", "address_Country": "UK" }, "departments": [ { "department_Code": "445", "department_Name": "Drinks and cocktails" }, { "department_Code": "889", "department_Name": "Maintenance and cleaning" } ] } }, "Department": { "required": [ "department_Code" ], "type": "object", "properties": { "department_Code": { "description": "The department unique identifier code for the organization.", "type": "string" }, "department_Name": { "description": "The department's name.", "type": "string" } } }, "LocationFlat": { "type": "object", "properties": { "location_Name": { "description": "The location name.", "type": "string" }, "location_Code": { "description": "The location code.", "type": "string" }, "location_Canonical_Id": { "description": "The unique location identifier across Fourth systems.", "type": "string" }, "is_Obsolete": { "description": "Whether the location is obsolete (inactive).", "type": "boolean" }, "obsolete_Date": { "format": "date-time", "description": "The date the location became obsolete.", "type": "string" }, "address": { "$ref": "#/definitions/Address", "description": "The address lines of the location." }, "departments": { "description": "The departments that are located in this location.", "type": "array", "items": { "$ref": "#/definitions/Department" } }, "created_Date": { "format": "date-time", "description": "When the location was created.", "type": "string" }, "last_Modified_Date": { "format": "date-time", "description": "When the location was last modified.", "type": "string" } } }, "AbsenceRecord": { "type": "object", "properties": { "employee_ID": { "description": "The unique identifier for the employee, from the external platform.
\r\n**Max length:** 68 characters", "type": "string" }, "location_Code": { "type": "string" }, "department": { "type": "string" }, "job_Code": { "type": "string" }, "element_Name": { "type": "string" }, "element_Local_Ref": { "type": "string" }, "start_DateTime": { "format": "date-time", "type": "string" }, "end_DateTime": { "format": "date-time", "type": "string" }, "units": { "format": "int32", "type": "integer" }, "unit_Type": { "type": "string" }, "rate": { "format": "double", "type": "number" }, "reference": { "type": "string" } } }, "AbsenceRemoved": { "required": [ "employee_ID" ], "type": "object", "properties": { "employee_ID": { "description": "The unique identifier for the employee, from the external platform.
\r\n**Max length:** 68 characters", "type": "string" }, "absence_Start_Date": { "format": "date-time", "type": "string" } } }, "Root": { "description": "The root resource that provides the entry point for the API.", "type": "object", "properties": { "apiVersion": { "description": "The version of the API.", "type": "string" }, "machineName": { "description": "The current machine name.", "type": "string" }, "userCanonicalId": { "description": "The authenticated account identifier.", "type": "string" }, "externalSystemCanonicalId": { "description": "The authenticated organization identifier.", "type": "string" } } }, "TnAData": { "required": [ "type" ], "type": "object", "properties": { "event_Id": { "description": "The unique identifier if one is available.", "type": "string" }, "employee_ID": { "description": "The unique identifier for the employee, from the external platform.You must include this or `Payroll_No` to identify the employee.", "type": "string" }, "payroll_No": { "description": "The payroll number for the employee from the external platform. You must include this or `Employee_ID` to identify the employee.
\r\n**Max length:** 68 characters", "type": "string" }, "employee_First_Name": { "description": "The first name of the employee.", "type": "string" }, "employee_Last_Name": { "description": "The surname of the employee.", "type": "string" }, "location_Code": { "description": "The internal code used for identification of a location.", "type": "string" }, "department_Code": { "description": "The internal code used for identification of a department.", "type": "string" }, "type": { "description": "The type of the time and attendance entry. Possible values are: `CLOCKIN`, `CLOCKOUT` and `BREAK`.", "type": "string" }, "event_Date": { "format": "date-time", "description": "The date of the time and attendance record, in ISO 8601 format.", "type": "string" }, "payments": { "description": "A list of additional payments for this time and attendance record, normally tips.", "type": "array", "items": { "$ref": "#/definitions/Payment" } }, "notes": { "description": "Additional details or notes from the employee or employer.", "type": "string" }, "submission_Date": { "format": "date-time", "description": "The time and attendance recording.", "type": "string" }, "clock_In": { "format": "date-time", "description": "The time the employee clocked-in, in ISO 8601 format.", "type": "string" }, "clock_Out": { "format": "date-time", "description": "The time the employee clocked-out, in ISO 8601 format.", "type": "string" }, "pay_Rate": { "format": "double", "description": "The rate amount of the time and attendance record.", "type": "number" }, "rate_Type": { "description": "The rate type. Possible values are: `HOURLY`, `HOURLY_GUARANTEED_HOURS`, `WEEKLY_SALARY`, `WEEKLY_SALARY_PLUS`, `MONTHLY_SALARY` and `UNPAID`.", "type": "string" }, "job_Code": { "description": "The job code identifier of the employee's job definition.", "type": "string" }, "is_Deleted": { "description": "The flag that identifies if the record is deleted.", "type": "boolean" } }, "example": { "employee_ID": "EMP_1", "payroll_No": "", "employee_First_Name": "John", "employee_Last_Name": "Smith", "location_Code": "LOC1", "department_Code": "DEP1", "type": "CLOCKIN", "event_Date": "2019-01-20T00:00:00Z", "payments": [ { "reference": "XY123", "payment_Type": "Example payment text", "value": 10.0, "currency": "USD", "payment_Date": "2019-01-20T00:00:00Z", "location_Code": "LOC1", "record_Type": "PROCESSED_TIPS" } ], "notes": "Some example attendance notes", "submission_Date": "2019-01-21T00:00:00Z", "clock_In": "2019-01-20T09:00:00Z", "pay_Rate": 40.0, "rate_Type": "HOURLY", "job_Code": "J1" } }, "Payment": { "required": [ "payment_Type", "record_Type" ], "type": "object", "properties": { "reference": { "type": "string" }, "payment_Type": { "description": "Free text that describes the payment entry.", "type": "string" }, "value": { "format": "double", "description": "The payment amount.", "type": "number" }, "currency": { "description": "The currency in ISO 4217 format.", "type": "string" }, "payment_Date": { "format": "date-time", "description": "The date and time of payment, in ISO 8601 format.", "type": "string" }, "location_Code": { "description": "The external location ID.\r\nThis is required if Record_Type is `unprocessed_tips`, `processed_tips` or `service_charges`.", "type": "string" }, "record_Type": { "description": "Type of payment. Possible values are: \r\n`unprocessed_tips`, `processed_tips`, `service_charges` and `advance`.", "type": "string" } } } }, "securityDefinitions": { "basic": { "type": "basic", "description": "Basic HTTP Authentication" } } }