{ "openapi": "3.1.0", "info": { "title": "Default module", "description": "Webhook events emitted when a company's KYB status is created or changes.\n\nRollfi sends these requests to the webhook URL configured for the client.\nConsumers should return a successful 2xx response after accepting the event.\n", "version": "1.0.0" }, "tags": [ { "name": "Admin Portal" }, { "name": "TimeOff Admin" }, { "name": "TimeTracking Admin" }, { "name": "TimeOff User" }, { "name": "TimeTracking User" }, { "name": "TimeTracking Reports" }, { "name": "TimeOff Reports" }, { "name": "Pay Schedule Webhooks" }, { "name": "Pay Period Webhooks" }, { "name": "Employee Bank Account Webhooks" }, { "name": "Employee KYC Webhooks" }, { "name": "Company Bank Account Webhooks" }, { "name": "Company Webhooks" }, { "name": "Employee Status Webhooks" } ], "paths": { "/companyOnboarding/createBusiness": { "post": { "summary": "createBusiness", "deprecated": false, "description": "The `createBusiness` API offers a holistic solution for seamlessly integrating a new company into the system. This API is designed to streamline the onboarding process by consolidating multiple steps into a single, efficient call. This approach is ideal for businesses seeking a quick and straightforward onboarding experience.\n\n### Features of `createBusiness` API:\n\n1. **Company Registration**\n\n2. **KYB Information**\n\n3. **Location Setup**\n\n4. **Admin User Addition**\n \n5. **KYB Process Initiation**\n\n## Notes:\n\n- For beneficial owners all fields in the **businessUser** object are mandatory, since we are required to collect address and personal information for compliance\n- **companyLocation** should be a filing address for the first location edded here", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "registration": { "type": "object", "properties": { "company": { "type": "string" }, "businessWebsite": { "type": "string" }, "doingBusinessAs": { "type": "string" }, "isTermsAccepted": { "type": "boolean" } }, "required": [ "company", "isTermsAccepted" ] }, "kybInformation": { "type": "object", "properties": { "ein": { "type": "string", "title": "Must be 9 Digits" }, "entityType": { "type": "string", "title": "Enum", "enum": [ "C Corp", "S Corp", "LLC", "Single Member LLC", "LLP", "Partnership", "Sole Proprietor", "Non-Profit" ] }, "incorporationState": { "type": "string" }, "dateOfIncorporation": { "type": "string" }, "irsAssisgnedFederalFilingForm": { "type": "string", "title": "Enum", "enum": [ "941", "944" ] }, "payrollRunThisYear": { "type": "string" }, "formerPaidThisYear": { "type": "string" } }, "required": [ "ein", "entityType", "incorporationState", "dateOfIncorporation", "irsAssisgnedFederalFilingForm", "payrollRunThisYear", "formerPaidThisYear" ] }, "companyLocation": { "type": "object", "properties": { "companyLocation": { "type": "string", "title": "Enum" }, "address1": { "type": "string" }, "address2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string", "title": "Enum" }, "zipcode": { "type": "string", "title": "Must be Five or Nine Digits" }, "phoneNumber": { "type": "string", "title": "Must be 10 digits" }, "isWorkLocation": { "type": "boolean" }, "isMailingAddress": { "type": "boolean" }, "isFilingAddress": { "type": "boolean" } }, "required": [ "companyLocation", "address1", "city", "state", "zipcode", "isFilingAddress" ] }, "businessUser": { "type": "object", "properties": { "firstName": { "type": "string" }, "middleName": { "type": "string" }, "lastName": { "type": "string" }, "phoneNumber": { "type": "string", "title": "Must be 10 digits" }, "email": { "type": "string" }, "address1": { "type": "string" }, "address2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string", "title": "Enum" }, "zipcode": { "type": "string" }, "ssn": { "type": "string", "title": "Must be 9 Digits" }, "dateOfBirth": { "type": "string" }, "payrollAdmin": { "type": "boolean" }, "bookkeeper": { "type": "boolean" }, "beneficialOwner": { "type": "boolean" }, "ownershipPercentage": { "type": "integer", "title": "Must be specified for Beneficial Owner " }, "bookKeeper": { "type": "boolean" } }, "required": [ "firstName", "lastName", "email", "phoneNumber" ] } }, "required": [ "method", "registration", "kybInformation", "companyLocation", "businessUser" ] }, "example": { "method": "createBusiness", "registration": { "company": "Best LLC", "businessWebsite": "www.schumm.com", "doingBusinessAs": "Best", "isTermsAccepted": true }, "kybInformation": { "ein": "109709569", "entityType": "LLP", "incorporationState": "Alabama", "dateOfIncorporation": "2015-02-25", "irsAssisgnedFederalFilingForm": "941", "payrollRunThisYear": "Yes", "formerPaidThisYear": "No" }, "companyLocation": { "companyLocation": "Main", "address1": "8745 Colard Ln", "address2": "", "city": "Lyons", "state": "CO", "zipcode": "80540", "phoneNumber": "9889890989", "isWorkLocation": true, "isMailingAddress": true, "isFilingAddress": true }, "businessUser": { "firstName": "Manoj", "middleName": "", "lastName": "Deshmukh", "phoneNumber": "9974574177", "email": "manoje901@mailsac.com", "address1": "8745 Colard Ln", "address2": "", "city": "Lyons", "state": "CO", "zipcode": "80540", "ssn": "458756985", "dateOfBirth": "2000-09-09", "payrollAdmin": true, "bookkeeper": true, "beneficialOwner": true, "ownershipPercentage": 25 } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "registration": { "type": "object", "properties": { "companyId": { "type": "string" }, "kybInformationId": { "type": "string" }, "businessUserId": { "type": "string" }, "companyLocationId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "companyId", "kybInformationId", "businessUserId", "companyLocationId" ] } }, "required": [ "registration" ] }, "examples": { "1": { "summary": "", "value": { "registration": { "companyId": "98016CB2-FAA4-47E5-8173-DD6F29C7C397", "kybInformationId": "32E9AE44-529A-4B4E-9C40-56DFCE99E712", "businessUserId": "4B47C1DA-F279-40E8-ABF6-ADD82E7C2582", "companyLocationId": "FB3B168C-62C2-43D0-A1EF-B3C6C5C6FAE3", "status": "Registered", "message": "A company with name Wise Wonders co is registered successfully and KYB verification is in progress." } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "First Name is mandatory and cannot be empty." } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } } }, "required": [ "error" ] } } }, "headers": {} } }, "security": [] } }, "/companyOnboarding/companyRegistration": { "post": { "summary": "companyRegistration", "deprecated": false, "description": "\nThe `companyRegistration` API is used to register a company, collect key company details like business name and website, and create an admin user. This is the first step in the multi-step company onboarding process.\n\n### What it does:\n\n- Initializes a new company in the system\n- Creates a default admin user with the details provided\n- returns a unique `companyId` to be used in subsequent onboarding steps", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "default": "companyRegistration" }, "registration": { "type": "object", "properties": { "company": { "type": "string" }, "firstName": { "type": "string" }, "middleName": { "type": "string" }, "lastName": { "type": "string" }, "phoneNumber": { "type": "string" }, "email": { "type": "string" }, "businessWebsite": { "type": "string" }, "doingBusinessAs": { "type": "string" }, "isTermsAccepted": { "type": "boolean" } }, "required": [ "company", "firstName", "lastName", "phoneNumber", "email", "isTermsAccepted" ] } }, "required": [ "method", "registration" ] }, "example": { "method": "companyRegistration", "registration": { "company": "BBR LLC", "firstName": "Titus", "middleName": "", "lastName": "Davenport", "phoneNumber": "2652227589", "email": "titus067@mailsac.com", "businessWebsite": "max.in", "doingBusinessAs": "BBR", "isTermsAccepted": true } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "registration": { "type": "object", "properties": { "companyId": { "type": "string" }, "businessUserId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "companyId", "businessUserId", "status", "message" ] } }, "required": [ "registration" ] }, "examples": { "1": { "summary": "Success", "value": { "registration": { "companyId": "EC1F7FD4-8CBD-4A0A-8517-EF88DA80EB2B", "businessUserId": "AEAD072B-D659-4195-816D-CBA835F5E580", "status": "Registered", "message": "A company with name Prism is registered successfully." } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "First Name is mandatory and cannot be empty." } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] } } }, "headers": {} } }, "security": [] } }, "/companyOnboarding/addKybInformation": { "post": { "summary": "addKybInformation", "deprecated": false, "description": "The `addKybInformation` API is used to submit KYB (Know Your Business) data for regulatory compliance. Here you add the information required for the KYB process, which verifies business information with official records.\n\n### What it does:\n\n- Collects essential business verification information including EIN, entity type, and incorporation date\n- Begins KYB verification process for regulatory compliance\n- Ensures taxation and payroll compliance depending on business type\n\n### Supported Entity Types:\n\n- C Corp\n- S Corp \n- LLC\n- Single Member LLC\n- LLP\n- Partnership\n- Sole Proprietor\n- Non-Profit\n\n### Supported Federal Filing Forms:\n\n- **941**: Quarterly Federal Tax Return (**most common**)\n- **944**: Annual Federal Tax Return (for small businesses with an annual employment tax liability of $1,000 or less)", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "addKybInformation" }, "kybInformation": { "type": "object", "properties": { "companyId": { "type": "string" }, "ein": { "type": "string", "title": "Must be 9 Digits" }, "entityType": { "type": "string", "title": "Enum", "enum": [ "C Corp", "S Corp", "LLC", "Single Member LLC", "LLP", "Partnership", "Sole Proprietor", "Non-Profit" ] }, "dateOfIncorporation": { "type": "string" }, "incorporationState": { "type": "string" }, "irsAssisgnedFederalFilingForm": { "type": "string", "enum": [ "941", "944" ] } }, "required": [ "companyId", "ein", "entityType", "dateOfIncorporation", "incorporationState", "irsAssisgnedFederalFilingForm" ] } }, "required": [ "method", "kybInformation" ] }, "example": { "method": "addKybInformation", "kybInformation": { "companyId": "8131D8A7-78F3-4DFC-A309-9010C95F2816", "ein": "899991002", "entityType": "LLP", "dateOfIncorporation": "2023-02-25", "incorporationState": "Maryland", "irsAssisgnedFederalFilingForm": "941" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "kybInformation": { "type": "object", "properties": { "kybInformationId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "kybInformationId", "status" ], "x--orders": [ "kybInformationId", "status", "message" ] } }, "required": [ "kybInformation" ], "x--orders": [ "kybInformation" ] }, "examples": { "1": { "summary": "Success", "value": { "kybInformation": { "kybInformationId": "44BF4454-FFCB-42BA-8918-E7A820E6497E", "status": "KYB Verification Pending", "message": "The KYB information for wil food has been saved successfully." } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "Ein is mandatory and cannot be empty." } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Entity type is not valid" } } } }, "headers": {} } }, "security": [] } }, "/companyOnboarding/addCompanyLocation": { "post": { "summary": "addCompanyLocation", "deprecated": false, "description": "\nThe `addCompanyLocation` API is used to add a company location. This step sets up the company's primary physical location and is essential for regional compliance, tax jurisdiction, and audit readiness.\n\n### What it does:\n\n- Establishes the company's physical presence and operational address\n- Enables proper tax jurisdiction for payroll processing and ensures regional compliance\n\n## Location Options:\n\n| Location | Description |\n|----------|-------------|\n|**WorkLocation**|Physical addresses where the company has employees working in the United States|\n|**MailingAddress**|Address where company correspondence and official mail is sent|\n|**FilingAddress**|Address used for tax filings and regulatory submissions with government agencies|\n\n### Notes:\n- This step must be completed before beginning the KYB verification process and is required for accurate payroll processing across different jurisdictions.\n- Companies must maintain **at least one** filing address at all times", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "addCompanyLocation", "examples": [ "addCompanyLocation" ] }, "companyLocation": { "type": "object", "properties": { "companyId": { "type": "string", "format": "uuid" }, "companyLocation": { "type": "string", "title": "Enum", "maxLength": 20, "examples": [ "Suggested Values : Main, Branch, Corporate" ] }, "address1": { "type": "string", "maxLength": 40 }, "address2": { "type": "string", "maxLength": 40, "title": "mandatory" }, "city": { "type": "string", "maxLength": 40 }, "state": { "type": "string", "title": "Enum", "maxLength": 2, "enum": [ "TX", "AK", "ND", "IL", "MA", "KS", "AS", "AL", "UT", "SD", "MI", "DC", "GA", "SC", "TN", "OK", "CO", "CA", "ME", "MO", "WY", "MD", "VT", "NM", "CT", "AZ", "WI", "VA", "WV", "NJ", "DE", "NC", "PR", "IN", "MT", "NH", "HI", "IA", "KY", "WA", "OH", "FL", "OR", "MP", "GU", "MN", "MS", "PA", "NE", "RI", "ID", "LA", "NY", "NV", "AR" ] }, "zipcode": { "type": "string", "title": "Must be Five or Nine Digits" }, "phoneNumber": { "type": "string", "title": "Must be 10 digits", "examples": [ "9874563210" ] }, "isWorkLocation": { "type": "boolean", "title": "mandatory" }, "isMailingAddress": { "type": "boolean", "title": "mandatory" }, "isFilingAddress": { "type": "boolean", "title": "mandatory" } }, "required": [ "companyId", "companyLocation", "address1", "city", "state", "zipcode", "isWorkLocation", "isMailingAddress", "isFilingAddress" ], "x--orders": [ "companyLocation", "address1", "city", "state", "zipcode", "country", "phoneNumber", "isWorkLocation", "isMailingAddress", "isFilingAddress", "companyId", "address2" ] } }, "required": [ "method", "companyLocation" ], "x--orders": [ "method", "companyLocation" ] }, "example": { "method": "addCompanyLocation", "companyLocation": { "companyId": "33A04AFB-4317-464A-B1E0-BAB610086174", "companyLocation": "Main", "address1": "8745 Colard Ln", "address2": "", "city": "Lyons", "state": "CO", "zipcode": "80540", "phoneNumber": "9889890989", "isWorkLocation": true, "isMailingAddress": true, "isFilingAddress": true } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "companyLocation": { "type": "object", "properties": { "companyLocationId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "status", "companyLocationId" ], "x--orders": [ "companyLocationId", "status", "message" ] } }, "required": [ "companyLocation" ], "x--orders": [ "companyLocation" ] }, "examples": { "1": { "summary": "Success", "value": { "companyLocation": { "companyLocationId": "EAE2367A-F86E-4495-B403-627FCCFD8184", "status": "Verification pending", "message": "Company Location has been saved successfully." } } }, "2": { "summary": "Exception", "value": { "error": [ { "code": 400, "message": "Company Location is mandatory and cannot be empty." } ] } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] } } }, "headers": {} } }, "security": [] } }, "/companyOnboarding/updateAdminUser": { "put": { "summary": "updateAdminUser", "deprecated": false, "description": "The `updateAdminUser` API is used to update the details of the admin user added during onboarding.\n\n### What it does:\n\n- Updates the admin Business User account\n- Complete the record for the businessUser that is created when calling the `companyRegistration` endpoint \n\n### Note:\n\n- For beneficialOwners we are required to collect address and personal information\n- Required fields for **beneficial owners**: ssn, address1, city, state, zipcode, dateOfBirth,\n\n- A list of businessUsers registered to the company and their associated businessUserIds can be retrieved using `getBusinessUsers`\n- Beneficial Owner share cannot be reduced below 25% to maintain compliance", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "updateAdminUser" ], "title": "updateAdminUser" }, "businessUser": { "type": "object", "properties": { "businessUserId": { "type": "string" }, "firstName": { "type": "string", "maxLength": 40 }, "middleName": { "type": "string", "maxLength": 40 }, "lastName": { "type": "string", "maxLength": 40 }, "phoneNumber": { "type": "string", "title": "Must be 10 Digits", "examples": [ "9874563210" ] }, "email": { "type": "string", "maxLength": 35 }, "dateOfBirth": { "type": "string", "examples": [ "YYYY-MM-DD" ] }, "address1": { "type": "string", "maxLength": 40 }, "address2": { "type": "string", "maxLength": 40 }, "city": { "type": "string", "maxLength": 40 }, "state": { "type": "string", "title": "Enum", "maxLength": 2, "enum": [ "TX", "AK", "ND", "IL", "MA", "KS", "AS", "AL", "UT", "SD", "MI", "DC", "GA", "SC", "TN", "OK", "CO", "CA", "ME", "MO", "WY", "MD", "VT", "NM", "CT", "AZ", "WI", "VA", "WV", "NJ", "DE", "NC", "PR", "IN", "MT", "NH", "HI", "IA", "KY", "WA", "OH", "FL", "OR", "MP", "GU", "MN", "MS", "PA", "NE", "RI", "ID", "LA", "NY", "NV", "AR" ] }, "zipcode": { "type": "string", "title": "Must be Five or Nine Digits" }, "ssn": { "type": "string", "examples": [ "987-65-1243" ] }, "payrollAdmin": { "type": "boolean" }, "bookKeeper": { "type": "boolean" }, "beneficialOwner": { "type": "boolean" }, "ownershipPercentage": { "type": "number", "title": "Must be specified for Beneficial Owner " } }, "required": [ "businessUserId" ], "x--orders": [ "businessUserId", "firstName", "lastName", "phoneNumber", "email", "address1", "city", "state", "zipcode", "country", "isPayrollAdmin", "isController", "isBeneficialOwner", "isEmployee", "middleName", "address2", "ssn" ] } }, "required": [ "method", "businessUser" ], "x--orders": [ "method", "businessUser" ] }, "example": { "method": "updateAdminUser", "businessUser": { "businessUserId": "EDC3BD9C-3B2F-4EE3-BC5C-720768044", "firstName": "Titus", "middleName": "", "lastName": "Davenport", "phoneNumber": "2106384100", "email": "titus048@mailsac.com", "address1": "102 Fallsgrove Blvd", "address2": "", "city": "Rockville", "state": "MD", "zipcode": "20850", "ssn": "452006520", "dateOfBirth": "2000-09-09", "payrollAdmin": true, "bookkeeper": true, "beneficialOwner": true, "ownershipPercentage": 25 } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "businessUser": { "type": "object", "properties": { "businessUserId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "businessUserId", "status" ], "x--orders": [ "businessUserId", "status", "message" ] } }, "required": [ "businessUser" ], "x--orders": [ "businessUser" ] }, "examples": { "1": { "summary": "Success", "value": { "businessUser": { "businessUserId": "3819B535-F3AA-4E5E-A055-16D33CE68315", "status": "Ready", "message": "The Business User has been updated successfully." } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "First Name should not exceed 40 characters." } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] } } }, "headers": {} } }, "security": [] } }, "/companyOnboarding/initiateCompanyKyb": { "post": { "summary": "initiateCompanyKyb", "deprecated": false, "description": "The `initiateCompanyKyb` API is used to begin the required business verification for regulatory compliance. This triggers the KYB (Know Your Business) process to verify business information with official records.\n\n### What it does:\n\n- Initiates the formal KYB verification process for the company\n- Validates submitted company information against official records\n\n### Prerequisites:\n\nBefore initiating KYB, the following steps must be completed:\n\n1. **Company Registration**: Basic company profile must be established\n\n2. **Company Location**: Primary physical location must be added\n\n3. **Business User**: Admin user details must be updated with required information. At least one admin user must be a Beneficial Owner with at least 25% share of the company\n\n4. **KYB Information**: Essential business data (EIN, entity type, incorporation date) must be submitted\n\n### Note:\n\n- This step is mandatory for regulatory compliance and must be completed before the company can access full payroll functionality and process payments.\n- If Kyb fails please correct the record using the `updateKybInformation` API and re-initiate", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "initiateCompanyKyb", "examples": [ "initiateCompanyKyb" ] }, "companyId": { "type": "string", "format": "uuid" } }, "required": [ "method", "companyId" ] }, "example": { "method": "initiateCompanyKyb", "companyId": "8A9B7683-8E02-494D-8422-963FD05EE785" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "initiateKyb": { "type": "object", "properties": { "companyId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "companyId", "status" ] } }, "required": [ "initiateKyb" ] }, "example": { "initiateKyb": { "companyId": "0A455F56-8B75-4834-B6A7-13A0F86315DE", "status": "KYB Verification Initiated", "message": "The KYB Initiated for KYB test successfully." } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid Company ID. Company not found." } } } }, "headers": {} } }, "security": [] } }, "/companyOnboarding/addBusinessUser": { "post": { "summary": "addBusinessUser", "deprecated": false, "description": "The `addBusinessUser` API is used to create a Business User and define their permissions and responsibilities within the system.\n\n### What it does:\n\n- Creates a Business User with defined roles and permissions\n- Establishes user access levels based on assigned roles providing role-based functionality\n- Supports multiple role assignments for flexible user management\n\n### Business User Roles:\n\nA Business User can have one or more of these roles:\n\n| Role | Description |\n|------|-------------|\n|**Payroll Admin**| Full access to payroll processing and management functions |\n|**Beneficial Owner**| Legal ownership stake in the company (*At least 25% share must be stated*) |\n|**Book Keeper**| Usually limited access to read-only for company accounting purposes and reporting |\n\n\n### Notes:\n\n- At least one beneficial owner with at least 25% share of the company must be registered to the system for compliance. A sole beneficial owner cannot be deleted before another is added.\n- For beneficial owners **dateOfBirth**, **address1**, **address2**, **city**, **state**, **zipcode**, ssn and ownershipPercentage are mandatory for compliance purposes.", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "addBusinessUser", "examples": [ "addBusinessUser" ] }, "businessUser": { "type": "object", "properties": { "companyId": { "type": "string", "format": "uuid" }, "firstName": { "type": "string", "maxLength": 40 }, "middleName": { "type": "string", "maxLength": 40 }, "lastName": { "type": "string", "maxLength": 40 }, "phoneNumber": { "type": "string", "title": "Must be 10 digits", "examples": [ "9874563210" ] }, "email": { "type": "string", "maxLength": 35 }, "address1": { "type": "string", "maxLength": 40 }, "address2": { "type": "string", "maxLength": 40 }, "city": { "type": "string", "maxLength": 40 }, "state": { "type": "string", "title": "Enum", "maxLength": 2, "enum": [ "TX", "AK", "ND", "IL", "MA", "KS", "AS", "AL", "UT", "SD", "MI", "DC", "GA", "SC", "TN", "OK", "CO", "CA", "ME", "MO", "WY", "MD", "VT", "NM", "CT", "AZ", "WI", "VA", "WV", "NJ", "DE", "NC", "PR", "IN", "MT", "NH", "HI", "IA", "KY", "WA", "OH", "FL", "OR", "MP", "GU", "MN", "MS", "PA", "NE", "RI", "ID", "LA", "NY", "NV", "AR" ] }, "zipcode": { "type": "string", "title": "Must be Five or Nine Digits" }, "ssn": { "type": "string", "title": "Must be 9 Digits", "examples": [ "659-56-4561" ] }, "dateOfBirth": { "type": "string", "examples": [ "YYYY-MM-DD" ] }, "payrollAdmin": { "type": "boolean" }, "bookKeeper": { "type": "boolean" }, "beneficialOwner": { "type": "boolean" }, "ownershipPercentage": { "type": "number", "title": "Must be specified for Beneficial Owner " } }, "required": [ "companyId", "firstName", "lastName", "phoneNumber", "email" ], "x--orders": [ "firstName", "lastName", "phoneNumber", "email", "address1", "city", "state", "zipcode", "country", "isPayrollAdmin", "isController", "isBeneficialOwner", "companyId", "middleName", "address2", "ssn", "ownershipPercentage", "isEmployee" ] } }, "required": [ "method", "businessUser" ], "x--orders": [ "method", "businessUser" ] }, "example": { "method": "addBusinessUser", "businessUser": { "companyId": "8A9B7683-8E02-494D-8422-963FD05EE785", "firstName": "Tim", "middleName": "", "lastName": "David", "phoneNumber": "9889890989", "email": "tim@david.xyz", "address1": "8745 Colard Ln", "address2": "", "city": "Lyons", "state": "CO", "zipcode": "80540", "ssn": "123098989", "dateOfBirth": "2000-09-09", "payrollAdmin": true, "bookKeeper": true, "beneficialOwner": true, "ownershipPercentage": 25 } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "businessUser": { "type": "object", "properties": { "businessUserId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "businessUserId", "status" ], "x--orders": [ "businessUserId", "status", "message" ] } }, "required": [ "businessUser" ], "x--orders": [ "businessUser" ] }, "examples": { "1": { "summary": "Success", "value": { "businessUser": { "businessUserId": "5370FF7F-9FFF-401A-A949-AFB393B50F09", "status": "KYC Pending", "message": "Tim David has been successfully added as BusinessUser." } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "Phone Number should not exceed 10 digits." } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid companyId" } } } }, "headers": {} } }, "security": [] } }, "/companyOnboarding/updateKybInformation": { "put": { "summary": "updateKybInformation", "deprecated": false, "description": "The `updateKybInformation` API is used to update KYB (Know Your Business) information that was previously provided during company onboarding.\n\n### What it does:\n\n- Updates existing KYB information for company onboarding\n- Allows corrections to KYB data when the business is not currently in a pending KYB review state\n\n### Updatable Fields:\n\n| Field | Description |\n|-------|-------------|\n| **EIN (Employer Identification Number)** | Federal Tax Identification Number |\n| **Entity Type** | Business structure (C Corp, S Corp, LLC, etc.) |\n| **Date of Incorporation** | When the business was legally established |\n\n### ⚠️ Important:\n- KYB information cannot be updated when KYB status is `pending`. If KYB is currently under review, please contact support for assistance before making changes.\n- If KYB fails, the KYB information becomes editable so it can be corrected and resubmitted using the initiateCompanyKyb API.", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "updateKybInformation" }, "kybInformation": { "type": "object", "properties": { "kybInformationId": { "type": "string" }, "ein": { "type": "string" }, "entityType": { "type": "string" }, "dateOfIncorporation": { "type": "string" } }, "required": [ "kybInformationId" ] } }, "required": [ "method", "kybInformation" ] }, "example": { "method": "updateKybInformation", "kybInformation": { "kybInformationId": "BEA64543-E6D3-4C0C-8B24-88F22B49E0FB", "ein": "258903006", "entityType": "LLC", "dateOfIncorporation": "2016-01-25" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "kybInformation": { "type": "object", "properties": { "kybInformationId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "kybInformationId", "status" ] } }, "required": [ "kybInformation" ] }, "examples": { "1": { "summary": "Success", "value": { "kybInformation": { "kybInformationId": "BEA64543-E6D3-4C0C-8B24-88F22B49E0FB", "status": "KYB Pending", "message": "kybInformation has been updated successfully." } } }, "2": { "summary": "Exception", "value": { "error": { "code": 403, "message": "Invalid kybInformationId. KybInformationId does not exist." } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 403, "message": "Invalid kybInformationId. KybInformationId does not exist." } } } }, "headers": {} } }, "security": [] } }, "/companyOnboarding/updateCompany": { "put": { "summary": "updateCompany", "deprecated": false, "description": "\nThe `updateCompany` API is used to update the company's website information after onboarding.", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "updateCompany" ], "title": "updateCompany" }, "company": { "type": "object", "properties": { "companyId": { "type": "string", "format": "uuid" }, "businessWebsite": { "type": "string", "maxLength": 40 } }, "required": [ "companyId" ] } }, "required": [ "method", "company" ] }, "example": { "method": "updateCompany", "company": { "companyId": "33A04AFB-4317-464A-B1E0-BAB610086174", "businessWebsite": "prism.com" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "company": { "type": "object", "properties": { "companyId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "companyId", "status" ] } }, "required": [ "company" ] }, "example": { "company": { "companyId": "2ed03719-f013-4178-bbfe-4ad80916ca7b", "status": "Ready", "message": "The Company's data has been updated successfully." } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Website format is not valid" } } } }, "headers": {} } }, "security": [] } }, "/companyOnboarding/deleteBusinessUser": { "delete": { "summary": "deleteBusinessUser", "deprecated": false, "description": "The `deleteBusiness` API is used to remove a Business User from the system and can be accessed throughout and after the onboarding process.\n\n### Note:\n\nAt least one Business User and/or one Beneficial Owner must be registered to a company. A sole Business User or Beneficial Owner cannot be deleted to maintain compliance so should be updated using `updateAdminUser` instead.", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "deleteBusinessUser" ], "title": "deleteBusinessUser" }, "businessUser": { "type": "object", "properties": { "businessUserId": { "type": "string" } }, "required": [ "businessUserId" ] } }, "required": [ "method", "businessUser" ] }, "example": { "method": "deleteBusinessUser", "businessUser": { "businessUserId": "33A04AFB-4317-464A-B1E0-BAB610086174" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "businessUser": { "type": "object", "properties": { "businessUserId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "businessUserId", "status" ] } }, "required": [ "businessUser" ] }, "examples": { "1": { "summary": "Success", "value": { "businessUser": { "businessUserId": "77158402-ba31-496d-b0bb-02e2998b15f4", "status": "Inactive", "message": "The Business User has been deleted successfully." } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "businessUserId is mandatory and cannot be empty." } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid business user ID" } } } }, "headers": {} } }, "security": [] } }, "/companyOnboarding/addBookKeeper": { "post": { "summary": "addBookKeeper", "deprecated": false, "description": "The `addBookKeeper` API is a streamlined method for adding a book keeper to a company\n\n### Note:\n\n- To add other admin roles such as beneficialOwner and payrollAdmin please use the addBusinessUser API", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "businessUser": { "type": "object", "properties": { "companyId": { "type": "string" }, "firstName": { "type": "string" }, "middleName": { "type": "string" }, "lastName": { "type": "string" }, "phoneNumber": { "type": "string" }, "email": { "type": "string" }, "bookkeeper": { "type": "boolean" } }, "required": [ "companyId", "firstName", "lastName", "phoneNumber", "email", "bookkeeper" ] } }, "required": [ "method", "businessUser" ] }, "example": { "method": "addBookKeeper", "businessUser": { "companyId": "65F6898F-8EC1-4541-9D61-03E50ADB04DA", "firstName": "Regi", "middleName": "", "lastName": "Wisdom", "phoneNumber": "2511630147", "email": "Wisdom02@mailsac.com", "bookkeeper": true } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "bookKeeper": { "type": "object", "properties": { "bookKeeperId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "bookKeeperId", "status", "message" ] } }, "required": [ "bookKeeper" ] }, "examples": { "1": { "summary": "Success", "value": { "bookKeeper": { "bookKeeperId": "22213C37-A0F2-439B-9D27-47ADAA24B6D9", "status": "KYC Pending", "message": "Regi Wisdom has been successfully added as Book Keeper." } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "Phone Number should not exceed 10 digits." } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Email already in use" } } } }, "headers": {} } }, "security": [] } }, "/adminPortal/updateStateRegistrationInfo": { "put": { "summary": "updateStateRegistrationInfo", "deprecated": false, "description": "\nThe `updateStateRegistrationInfo` API updates state registration information for a company to maintain payroll tax compliance.\n\n### What it does:\n- Updates state-specific registration fields\n\n### Note:\n- To retrieve the required fields for a given state use the `getStateRegistrationFields` API", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "updateStateRegistration" }, "companyId": { "type": "string" }, "code": { "type": "string" }, "companyStateRegistration": { "type": "object", "properties": { "UI Account Number": { "type": "string" }, "Unemployment Rate": { "type": "string" } } } }, "required": [ "method", "companyId", "code", "companyStateRegistration" ] }, "example": { "method": "updateStateRegistrationInfo", "companyId": "962D5035-6F51-41D3-94E8-1BF7A00955CF", "code": "AK", "companyStateRegistration": { "UI Account Number": "741258052", "Unemployment Rate": "3.0" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "status", "message" ] }, "examples": { "1": { "summary": "Success", "value": { "status": "Success", "message": "The Company State Registrations have been updated successfully." } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "State Code is not valid" } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] } } }, "headers": {} } }, "security": [] } }, "/adminPortal/deleteStateRegistrationInfo": { "delete": { "summary": "deleteStateRegistrationInfo", "deprecated": false, "description": "\nThe `deleteStateRegistrationInfo` API removes a company's state registration based on the State ID.\n\n### What it does:\n\n- Deletes existing state registration records for the company", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "updateStateRegistration" }, "companyId": { "type": "string" }, "stateCode": { "type": "string" } }, "required": [ "method", "companyId", "stateCode" ] }, "example": { "method": "deleteStateRegistrationInfo", "companyId": "CF41E979-90AE-4A8D-8FC7-08E7224FF960", "stateCode": "AK" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "status", "message" ] }, "examples": { "1": { "summary": "Success", "value": { "status": "Success", "message": "State 'WA' registration deleted successfully for the company." } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "State Code is not valid" } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] } } }, "headers": {} } }, "security": [] } }, "/adminPortal/addStateRegistrationInfo": { "post": { "summary": "addStateRegistrationInfo", "deprecated": false, "description": "\nThe `addStateRegistrationInfo` API adds state registration information for a company to enable payroll tax compliance.\n\n### What it does:\n\n- Adds state-specific registration details including account numbers and unemployment rates\n- Sets up state tax compliance for companies operating in specific states\n\n### Note:\n- To retrieve the required fields for a given state use the `getStateRegistrationFields` API", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "addStateRegistration" }, "companyId": { "type": "string" }, "code": { "type": "string" }, "companyStateRegistration": { "type": "object", "properties": { "UI Account Number": { "type": "string" }, "Unemployment Rate": { "type": "string" } }, "required": [ "UI Account Number", "Unemployment Rate" ] } }, "required": [ "method", "companyId", "code", "companyStateRegistration" ] }, "example": { "method": "addStateRegistrationInfo", "companyId": "962D5035-6F51-41D3-94E8-1BF7A00955CF", "code": "AK", "companyStateRegistration": { "UI Account Number": "741258023", "Unemployment Rate": "2.5" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "status", "message" ] }, "examples": { "1": { "summary": "Success", "value": { "status": "Success", "message": "The company state registrations for Lakin LLC have been saved successfully." } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "Invalid companyId" } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] } } }, "headers": {} } }, "security": [] } }, "/adminPortal/updateBusinessUser": { "put": { "summary": "updateBusinessUser", "deprecated": false, "description": "\nThe `updateBusinessUser` API updates Business User details in the system.\n\n### What it does:\n\n- Supports multiple roles: Payroll Admin, Controller, Beneficial Owner, Employee\n- Preserves existing user data while updating only specified fields\n\n### Notes:\n\n- Run `getBusinessUserDetails` endpoint first to get current information before updating\n- Requires ownership percentage specification for Beneficial Owner role", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "updateBusinessUser" ], "title": "updateBusinessUser" }, "businessUser": { "type": "object", "properties": { "businessUserId": { "type": "string" }, "firstName": { "type": "string", "maxLength": 40 }, "middleName": { "type": "string", "maxLength": 40 }, "lastName": { "type": "string", "maxLength": 40 }, "phoneNumber": { "type": "string", "title": "Must be 10 Digits", "examples": [ "9874563210" ] }, "email": { "type": "string", "maxLength": 35 }, "address1": { "type": "string", "maxLength": 40 }, "address2": { "type": "string", "maxLength": 40 }, "city": { "type": "string", "maxLength": 40 }, "state": { "type": "string", "title": "Enum", "maxLength": 2, "enum": [ "TX", "AK", "ND", "IL", "MA", "KS", "AS", "AL", "UT", "SD", "MI", "DC", "GA", "SC", "TN", "OK", "CO", "CA", "ME", "MO", "WY", "MD", "VT", "NM", "CT", "AZ", "WI", "VA", "WV", "NJ", "DE", "NC", "PR", "IN", "MT", "NH", "HI", "IA", "KY", "WA", "OH", "FL", "OR", "MP", "GU", "MN", "MS", "PA", "NE", "RI", "ID", "LA", "NY", "NV", "AR" ] }, "zipcode": { "type": "string", "title": "Must be Five or Nine Digits" }, "country": { "type": "string", "enum": [ "US" ] }, "ssn": { "type": "string", "examples": [ "987-65-1243" ] }, "payrollAdmin": { "type": "boolean" }, "bookKeeper": { "type": "boolean" }, "beneficialOwner": { "type": "boolean" } }, "required": [ "businessUserId" ], "x--orders": [ "businessUserId", "firstName", "lastName", "phoneNumber", "email", "address1", "city", "state", "zipcode", "country", "isPayrollAdmin", "isController", "isBeneficialOwner", "isEmployee", "middleName", "address2", "ssn" ] } }, "required": [ "method", "businessUser" ], "x--orders": [ "method", "businessUser" ] }, "example": "{\r\n \"method\": \"updateBusinessUser\",\r\n \"businessUser\": {\r\n \"businessUserId\": \"67DEFFE5-ADC9-4B21-A3B4-194C468290F4\",\r\n \"firstName\": \"Marcus\",\r\n \"middleName\": \"\",\r\n \"lastName\": \"Steve\",\r\n \"email\": \"marcus020@sto.com\",\r\n \"phoneNumber\": \"9988884377\",\r\n \"address1\": \"8745 Colard Ln\",\r\n \"address2\": \"\",\r\n \"city\": \"Lyons\",\r\n \"state\": \"CO\",\r\n \"zipcode\": \"80540\",\r\n \"country\": \"US\",\r\n \"ssn\": \"745896325\",\r\n \"dateOfBirth\": \"2000-09-09\",\r\n \"payrollAdmin\": true,\r\n \"bookkeeper\": true,\r\n \"beneficialOwner\": true,\r\n \"ownershipPercentage\": 25,\r\n }\r\n}" } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "businessUser": { "type": "object", "properties": { "businessUserId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "businessUserId", "status" ], "x--orders": [ "businessUserId", "status", "message" ] } }, "required": [ "businessUser" ], "x--orders": [ "businessUser" ] }, "example": { "businessUser": { "businessUserId": "3819B535-F3AA-4E5E-A055-16D33CE68315", "status": "Ready", "message": "The Business User has been updated successfully." } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "First Name should not exceed 40 characters." } } } }, "headers": {} } }, "security": [] } }, "/adminPortal/updateCompanyLocation": { "put": { "summary": "updateCompanyLocation", "deprecated": false, "description": "\nThe `updateCompanyLocation` API updates the company's location information.\n\n### What it does:\n\n- Updates company's mailing address, filing address, and employee work locations and allows re-designation of a location as any of these types.\n- Modifies existing location details for payroll tax compliance purposes\n\n### Notes:\n\n- Locations that have employees registered to them must be designated as a WorkLocation\n- The company must retain at least one Filing address and Mailing address for tax compliance", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "updateCompanyLocation" ], "title": "updateCompanyLocation" }, "companyLocation": { "type": "object", "properties": { "companyLocationId": { "type": "string", "format": "uuid" }, "companyLocation": { "type": "string", "title": "Enum", "examples": [ "Suggested Values : Main, Branch, Corporate" ] }, "address1": { "type": "string", "maxLength": 40 }, "address2": { "type": "string", "maxLength": 40 }, "city": { "type": "string", "maxLength": 40 }, "state": { "type": "string", "title": "Enum", "maxLength": 2, "enum": [ "TX", "AK", "ND", "IL", "MA", "KS", "AS", "AL", "UT", "SD", "MI", "DC", "GA", "SC", "TN", "OK", "CO", "CA", "ME", "MO", "WY", "MD", "VT", "NM", "CT", "AZ", "WI", "VA", "WV", "NJ", "DE", "NC", "PR", "IN", "MT", "NH", "HI", "IA", "KY", "WA", "OH", "FL", "OR", "MP", "GU", "MN", "MS", "PA", "NE", "RI", "ID", "LA", "NY", "NV", "AR" ] }, "zipcode": { "type": "string", "title": "Must be Five or Nine Digits" }, "country": { "type": "string", "enum": [ "US" ], "title": "Currently only US is supported" }, "phoneNumber": { "type": "string", "title": "Must be 10 Digits", "examples": [ "9874563210" ] }, "isWorkLocation": { "type": "boolean" }, "isMailingAddress": { "type": "boolean" }, "isFilingAddress": { "type": "boolean" } }, "required": [ "companyLocationId" ], "x--orders": [ "companyLocationId", "companyLocation", "address1", "city", "state", "zipcode", "country", "phoneNumber", "isWorkLocation", "isMailingAddress", "isFilingAddress" ] } }, "required": [ "method", "companyLocation" ], "x--orders": [ "method", "companyLocation" ] }, "example": { "method": "updateCompanyLocation", "companyLocation": { "companyLocationId": "A4EA3BD6-2821-4F94-83A6-5C126991AB28", "companyLocation": "Main", "address1": "8435 Colard Ln", "address2": "", "city": "Lyons", "state": "CO", "zipcode": "80540", "country": "US", "phoneNumber": "9889890987", "isWorkLocation": true, "isMailingAddress": true, "isFilingAddress": true } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "companyLocation": { "type": "object", "properties": { "companyLocationId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "companyLocationId", "status" ], "x--orders": [ "CompanyLocationID", "Status", "Message" ] } }, "required": [ "companyLocation" ], "x--orders": [ "CompanyLocation" ] }, "example": { "companyLocation": { "companyLocationId": "A4EA3BD6-2821-4F94-83A6-5C126991AB28", "status": "Verified", "message": "Company Location has been update successfully." } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Company Location should not exceed 20 characters." } } } }, "headers": {} } }, "security": [] } }, "/adminPortal/addUser": { "post": { "summary": "addUser", "deprecated": false, "description": "\nCreates a new employee or contractor in the system.\n\n### When to Use\n- Onboarding new hires\n- Adding contractors to payroll\n- Setting up remote workers\n### Worker Types\n- \"W2\" - Traditional employees\n- \"1099\" - Independent contractors\n\n### Key Requirements\n- For Remote workers: Must include `code` (state code)\n- For Office workers: Must include `companyLocationId`", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "addUser" }, "user": { "type": "object", "properties": { "companyId": { "type": "string" }, "firstName": { "type": "string" }, "middleName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "phoneNumber": { "type": "string", "title": "Must be 10 digits" }, "dateOfJoin": { "type": "string" }, "workerType": { "type": "string", "title": "Enum", "enum": [ "W2", "1099-NEC" ] }, "jobTitle": { "type": "string" }, "companyLocationCategory": { "type": "string" }, "stateCode": { "type": "string" }, "companyLocationId": { "type": "string", "title": "Need to be added when CompanyLocationCategory is Office" } }, "required": [ "companyId", "firstName", "lastName", "email", "phoneNumber", "dateOfJoin", "workerType", "jobTitle", "companyLocationCategory" ] } }, "required": [ "method", "user" ] }, "example": { "method": "addUser", "user": { "companyId": "33A04AFB-4317-464A-B1E0-BAB610086174", "firstName": "Marcus", "middleName": "Austin", "lastName": "Steve", "email": "mar@sto.com", "phoneNumber": "9889890989", "dateOfJoin": "2000-01-01", "workerType": "W2", "jobTitle": "Manager", "companyLocationCategory": "Remote", "stateCode": "FL", "companyLocationId": "" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "userId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "userId", "status" ], "x--orders": [ "EmployeeID", "Status", "Message" ] } }, "required": [ "user" ], "x--orders": [ "Employee" ] }, "examples": { "1": { "summary": "Success", "value": { "user": { "userId": "E7B3731C-20F4-4432-A3BE-DDD83D877EAD", "status": "KYC Pending", "message": "Marcus Steve has been successfully added as Employee in Test Ltd." } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "First Name is mandatory and cannot be empty." } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] } } }, "headers": {} } }, "security": [] } }, "/adminPortal/updateUser": { "put": { "summary": "updateUser", "deprecated": false, "description": "\nThe `updateUser` API updates required employee information in the system.\n\n### What it does:\n\n- Updates existing employee personal details and contact information\n- Allows partial changes to user data\n- StateCode can only be added for **Remote** workers, and companylocationId can only be added for \"Office\" workers\n\n### Note:\n\n- We are not currently allowing changes to a user's name for kyc (know your customer) purposes. Please contact support if a name change is required", "tags": [], "parameters": [], "requestBody": { "content": { "application/x-msgpack": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "updateUser" }, "user": { "type": "object", "properties": { "userId": { "type": "string" }, "middleName": { "type": "string" }, "phoneNumber": { "type": "string", "title": "Must be 10 Digits" }, "dateOfJoin": { "type": "string" }, "workerType": { "type": "string", "title": "Enum" }, "jobTitle": { "type": "string" }, "companyLocationCategory": { "type": "string", "title": "Enum" }, "stateCode": { "type": "string" }, "companyLocationId": { "type": "string" } }, "required": [ "userId" ] } }, "required": [ "method", "user" ] }, "example": { "method": "updateUser", "user": { "userId": "5F45CFBA-4AED-41AF-B334-E02D23BA17AE", "firstName": "Joe", "lastName": "Bloggs", "phoneNumber": "9889890989", "email": "joeBloggs@mailsac.com", "dateOfJoin": "2000-01-01", "workerType": "W2", "jobTitle": "Manager", "companyLocationCategory": "Office", "stateCode": "AL", "companyLocationId": "9721384B-0367-41DD-BD64-EF8047E8FD71" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "userId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "userId", "status" ], "x--orders": [ "EmployeeID", "Status", "Message" ] } }, "required": [ "user" ], "x--orders": [ "Employee" ] }, "examples": { "1": { "summary": "Success", "value": { "user": { "userId": "673F4A1C-ABD9-4E20-A235-66ED7CA71E8D", "status": "Ready", "message": "The User's data has been updated successfully." } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "Date of join format is not valid" } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] } } }, "headers": {} } }, "security": [] } }, "/adminPortal/deleteUser": { "delete": { "summary": "deleteUser", "deprecated": false, "description": "Deletes employee/user data for the provided companyId and userId.\n\n### When to use:\n- Whan an employee was added by mistake and is still in `Hiring and Onboarding`\n- When an employee is incorrectly added as W2 or 1099-NEC and needs to be re-onboarded with the correct userType\n\n### Notes:\n- Deletion is only supported when the employee status is `Invite Sent` or `Add Wage`.\n- To remove an employee who is active they must be dectivated or terminated", "operationId": "deleteUser", "tags": [ "Admin Portal" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "userId": { "type": "string" } }, "required": [ "method", "companyId", "userId" ] }, "examples": { "deleteUserRequest": { "value": { "method": "deleteUser", "companyId": "ECF1B47E-108F-45C0-A520-6A128A727B04", "userId": "33820169-85C2-482A-BCCF-B2281419E96E" }, "summary": "Delete terminated/deactivated employee" } } } }, "required": true }, "responses": { "200": { "description": "User delete completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ] }, "examples": { "success": { "summary": "success", "value": { "success": true, "message": "User deleted successfully" } } } } }, "headers": {} }, "400": { "description": "Validation or business rule failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "examples": { "missingCompanyId": { "summary": "Missing companyId", "value": { "error": { "code": 400, "message": "companyId is required" } } }, "missingUserId": { "summary": "Missing userId", "value": { "error": { "code": 400, "message": "userId is required" } } }, "wrongCompanyForUser": { "summary": "Employee not in company", "value": { "error": { "code": 400, "message": "Employee does not belong to the specified company" } } }, "activeStatusBlocked": { "summary": "Active employee cannot be deleted", "value": { "error": { "code": 400, "message": "Cannot delete user with active employee status" } } }, "invalidCompanyId": { "summary": "Invalid companyId format", "value": { "error": { "code": 400, "message": "Invalid companyId." } } }, "invalidUserId": { "summary": "Invalid userId format", "value": { "error": { "code": 400, "message": "Invalid userId." } } } } } }, "headers": {} } }, "security": [] } }, "/adminPortal/addFormerUser": { "post": { "summary": "addFormerUser", "deprecated": false, "description": "The `addFormerUser` API adds a terminated user to the system.\n\n### Use when:\n- `formerPaidThisYear` = true during onboarding\n- You have an employee that has been paid this year but is no longer at the company at the point of onboarding\n\n### Notes:\n- Used to maintain compliance for payroll and to calculate accurate employer taxes\n", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "employee": { "type": "object", "properties": { "companyId": { "type": "string" }, "firstName": { "type": "string" }, "middleName": { "type": "string" }, "lastName": { "type": "string" }, "workerType": { "type": "string", "enum": [ "W2", "1099-NEC" ] }, "ssn": { "type": "string" }, "dateOfBirth": { "type": "string" }, "address1": { "type": "string" }, "address2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zipcode": { "type": "string" }, "startDate": { "type": "string" }, "endDate": { "type": "string" }, "companyLocationCategory": { "type": "string" }, "stateCode": { "type": "string", "description": "Required if companyLocationCategory = Remote" }, "companyLocationId": { "type": "string", "description": "Required if companyLocationCategory = Office" } }, "required": [ "companyId", "firstName", "lastName", "workerType", "ssn", "dateOfBirth", "address1", "city", "state", "zipcode", "startDate", "endDate", "companyLocationCategory" ] } }, "required": [ "method", "employee" ] }, "example": { "method": "addFormerUser", "employee": { "companyId": "33B0F117-6C2B-4DEB-AB3C-6AF54182A748", "firstName": "John", "middleName": "", "lastName": "Doe", "workerType": "W2", "ssn": "123000630", "dateOfBirth": "1990-05-15", "address1": "123 Main Street", "address2": "Apt 4B", "city": "New York", "state": "NY", "zipcode": "10001", "startDate": "2020-01-15", "endDate": "2026-03-29", "companyLocationCategory": "Remote", "stateCode": "NY" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "userId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "userId", "status" ], "x--orders": [ "EmployeeID", "Status", "Message" ] } }, "required": [ "user" ], "x--orders": [ "Employee" ] }, "examples": { "1": { "summary": "Success", "value": { "formerUser": { "userId": "16684041-4DA6-4525-AAE3-39EEB684E4D3", "status": "Success", "message": "Former user Jimmy Do has been added successfully." } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "FirstName is required" } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid company ID. Company does not exist." } } } }, "headers": {} } }, "security": [] } }, "/adminPortal/addBusinessContractor": { "post": { "summary": "addBusinessContractor", "deprecated": false, "description": "\nThe `addBusinessContractor` API creates a new business contractor who interacts with the company payroll.\n\n### What it does:\n\n- Creates a business contractor user with address, KYB (Know Your Business) data, wage and company location\n- Records the ownership share of the business user in their respective company\n\n### Notes:\n\n- Different from regular contractors created with `addUser` - this is specifically for business contractors\n- Business contractors are separate from business users who have administrative roles", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "companyId": { "type": "string", "format": "uuid" }, "firstName": { "type": "string", "maxLength": 40 }, "middleName": { "type": "string", "maxLength": 40 }, "lastName": { "type": "string", "maxLength": 40 }, "email": { "type": "string", "maxLength": 35 }, "phoneNumber": { "type": "string", "title": "Must be 10 digits", "examples": [ "9874563210" ] }, "dateOfJoin": { "type": "string", "maxLength": 10 }, "workerType": { "type": "string", "title": "Enum", "maxLength": 8, "enum": [ "W2", "1099-NEC" ] }, "jobTitle": { "type": "string", "maxLength": 20 }, "companyLocationCategory": { "type": "string", "enum": [ "Office", "Remote" ], "examples": [ "When Remote is Selected State Code Should be mentioned", "When Office is Selected companyLocationId Should be mentioned" ] }, "code": { "type": "string", "title": "Enum", "maxLength": 2, "enum": [ "TX", "AK", "ND", "IL", "MA", "KS", "AS", "AL", "UT", "SD", "MI", "DC", "GA", "SC", "TN", "OK", "CO", "CA", "ME", "MO", "WY", "MD", "VT", "NM", "CT", "AZ", "WI", "VA", "WV", "NJ", "DE", "NC", "PR", "IN", "MT", "NH", "HI", "IA", "KY", "WA", "OH", "FL", "OR", "MP", "GU", "MN", "MS", "PA", "NE", "RI", "ID", "LA", "NY", "NV", "AR" ] }, "companyLocationId": { "type": "string", "title": "Need to be added when CompanyLocationCategory is Office", "format": "uuid" } }, "required": [ "companyId", "firstName", "lastName", "email", "phoneNumber", "dateOfJoin", "workerType", "jobTitle", "companyLocationCategory" ], "x--orders": [ "companyId", "firstName", "lastName", "email", "phoneNumber", "dateOfJoin", "workerType", "jobTitle", "employeeStatus", "companyLocationCategory", "state", "middleName" ] }, "kybInformation": { "type": "object", "properties": { "ein": { "type": "string" }, "dateOfIncorporation": { "type": "string" } }, "required": [ "ein", "dateOfIncorporation" ] }, "companyLocation": { "type": "object", "properties": { "address1": { "type": "string" }, "address2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zipcode": { "type": "string" }, "country": { "type": "string" }, "phoneNumber": { "type": "string" } }, "required": [ "address1", "city", "state", "zipcode", "country", "phoneNumber" ] }, "businessUser": { "type": "object", "properties": { "address1": { "type": "string" }, "address2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zipcode": { "type": "string" }, "country": { "type": "string" }, "dateOfBirth": { "type": "string" }, "ownershipPercentage": { "type": "number" } }, "required": [ "address1", "city", "state", "zipcode", "country", "dateOfBirth", "ownershipPercentage" ] } }, "required": [ "user", "kybInformation", "companyLocation", "businessUser" ], "x--orders": [ "method", "employee" ] }, "example": { "method": "addBusinessContractor", "user": { "companyId": "A141A4B1-C742-4C43-9A45-E8CCC2FD87F7", "legalName": "Pear Inc", "firstName": "Meery", "middleName": "Austin", "lastName": "Steve", "email": "pear001@sto.com", "phoneNumber": "9889890989", "dateOfJoin": "2000-01-01", "jobTitle": "Manager", "companyLocationCategory": "Remote", "code": "FL" }, "userWage": { "differentialPay": "No", "wageRate": 1110, "workerType": "W2", "wageBasis": "Per Week", "userType": "Salary/Eligible for overtime", "employmentStatus": "Full Time (30+ Hours per week)", "userRefTaxExempt": "Yes, as an owner/corporate officer", "startDate": "2023-02-25", "paymentMethod": "Check" }, "kybInformation": { "ein": "785698565", "dateOfIncorporation": "2023-02-25" }, "companyLocation": { "address1": "8745 Colard Ln", "address2": "", "city": "Lyons", "state": "CO", "zipcode": "80540", "country": "US", "phoneNumber": "9889890989" }, "businessUser": { "address1": "8745 Colard Ln", "address2": "", "city": "Lyons", "state": "CO", "zipcode": "80540", "country": "US", "dateOfBirth": "2000-09-09", "ownershipPercentage": 28 } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "businessContractor": { "type": "object", "properties": { "companyId": { "type": "string" }, "kybInformationId": { "type": "string" }, "userId": { "type": "string" }, "userWageId": { "type": "string" }, "businessUserId": { "type": "string" }, "companyLocationId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "companyId", "kybInformationId", "userId", "userWageId", "businessUserId", "companyLocationId", "status", "message" ] } }, "required": [ "businessContractor" ] }, "example": { "businessContractor": { "companyId": "B06FF5C9-D654-4B6F-ABF0-072AF5A7D1CF", "kybInformationId": "51A02CD2-745A-4C77-B7C6-6711ABBD9EEE", "userId": "088B3C3C-F7C2-4F42-999A-CC1FA135CE82", "userWageId": "C62AD35C-5BDF-4B9F-9E0A-6C97A44730BF", "businessUserId": "088B3C3C-F7C2-4F42-999A-CC1FA135CE82", "companyLocationId": "401AB38E-5C90-48F1-BBEA-F7449B41DB80", "status": "Registered", "message": "A business contractor has been registered successfully and KYB verification is in progress." } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "First Name is mandatory and cannot be empty." } } } }, "headers": {} } }, "security": [] } }, "/adminPortal/addUsers": { "post": { "summary": "addUsers", "deprecated": false, "description": "## Bulk Create Employees/Contractors\n\nCreates multiple employees or contractors in a single API call.\n\n### When to Use\n- Mass onboarding (new company setup)\n- Seasonal hiring\n- Bulk contractor additions", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string", "format": "uuid" }, "user": { "type": "array", "items": { "type": "object", "properties": { "firstName": { "type": "string" }, "middleName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "phoneNumber": { "type": "string", "title": "Must be 10 digits", "examples": [ "9874563210" ] }, "dateOfJoin": { "type": "string" }, "workerType": { "type": "string", "title": "Enum", "maxLength": 8, "enum": [ "W2", "1099-NEC" ] }, "jobTitle": { "type": "string" }, "companyLocationCategory": { "type": "string", "enum": [ "Office", "Remote" ], "examples": [ "When Remote is Selected State Code Should be mentioned", "When Office is Selected companyLocationId Should be mentioned" ] }, "code": { "type": "string", "title": "Enum", "maxLength": 2, "enum": [ "TX", "AK", "ND", "IL", "MA", "KS", "AS", "AL", "UT", "SD", "MI", "DC", "GA", "SC", "TN", "OK", "CO", "CA", "ME", "MO", "WY", "MD", "VT", "NM", "CT", "AZ", "WI", "VA", "WV", "NJ", "DE", "NC", "PR", "IN", "MT", "NH", "HI", "IA", "KY", "WA", "OH", "FL", "OR", "MP", "GU", "MN", "MS", "PA", "NE", "RI", "ID", "LA", "NY", "NV", "AR" ] }, "companyLocationId": { "type": "string", "title": "Need to be added when CompanyLocationCategory is Office", "format": "uuid" } }, "required": [ "firstName", "lastName", "email", "phoneNumber", "dateOfJoin", "workerType", "jobTitle", "companyLocationCategory" ] } } }, "required": [ "method", "companyId", "user" ] }, "example": { "method": "addUsers", "companyId": "33A04AFB-4317-464A-B1E0-BAB610086174", "users": [ { "firstName": "Marcus", "middleName": "Austin", "lastName": "Steve", "email": "marcus@steve.in", "phoneNumber": "9889890989", "dateOfJoin": "2000-01-01", "workerType": "W2", "jobTitle": "Manager", "companyLocationCategory": "Remote", "stateCode": "FL", "companyLocationId": "" }, { "firstName": "Laura", "middleName": "Beth", "lastName": "Johnson", "email": "laurajohnson@company.com", "phoneNumber": "9988776655", "dateOfJoin": "2001-02-02", "workerType": "W2", "jobTitle": "Developer", "companyLocationCategory": "Remote", "stateCode": "CA", "companyLocationId": "" }, { "firstName": "Aaron", "middleName": "", "lastName": "Ruth", "email": "aaronruth@company.com", "phoneNumber": "9988776655", "dateOfJoin": "2001-02-02", "workerType": "W2", "jobTitle": "Developer", "companyLocationCategory": "Remote", "stateCode": "CA", "companyLocationId": "" } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "userId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "userId", "status", "message" ] } }, "required": [ "user" ] } }, "example": [ { "user": { "userId": "BAF0E9A0-0468-4936-A18A-B764772EBD6D", "status": "KYC Pending", "message": "Marcus Steve has been successfully added as Employee in Company146933." } }, { "user": { "userId": "4D6E227F-48E4-4808-A95C-61D09863A5D2", "status": "KYC Pending", "message": "Laura Johnson has been successfully added as Employee in Company146933." } }, { "user": { "userId": "EF7B8546-D333-4FED-8D08-F0720857F9A4", "status": "KYC Pending", "message": "Aaron Ruth has been successfully added as Employee in Company146933." } } ] } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "userId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "userId", "status", "message" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "user", "error" ] } }, "example": [ { "user": { "userId": "", "status": "Error", "message": "Failed to add User." }, "error": { "code": "400", "message": "Email already in use" } }, { "user": { "userId": "", "status": "Error", "message": "Failed to add User." }, "error": { "code": "400", "message": "Email already in use" } }, { "user": { "userId": "", "status": "Error", "message": "Failed to add User." }, "error": { "code": "400", "message": "Email already in use" } } ] } }, "headers": {} } }, "security": [] } }, "/adminPortal/addRecurringPayItem": { "post": { "summary": "addRecurringPayItem", "deprecated": false, "description": "The `addRecurringPayItem` API is used to add a recurring item that will appear on an employee's payroll.\n\n### What it does:\n- Adds an employee-specific recurring pay item\n- Used to add recurring deductions, additional compensations, and reimbursements without having to add them to pay periods\n\n### Notes:\n- Either `allocatedPercentage` or `amountPerPayPeriod` is required\n- Recurring items will be added to open pay periods until they are removed with `removeRecurringPayItem`\n- `type` is restricted to the list of deductions and additional compensations available with `getDeductionDescription` and `getAdditionalCompensationDescription`\n- `type` allows free-string entry for reimbursements\n- Only one recurring item per `type` can be added\n\n---\n\n| PayItem options | Restrictions |\n| - | - |\n| Deduction | `getDeductionDescription` |\n| AdditionalCompensation | `getAdditionalCompensationDescription` |\n| Reimbursement | No restriction. Free entry |", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "userId": { "type": "string" }, "payItem": { "type": "string", "enum": [ "Deduction", "AdditionalCompensation", "Reimbursement" ] }, "type": { "type": "string" }, "amountPerPayPeriod": { "type": "number" }, "allocatedPercentage": { "type": "number" } }, "required": [ "method", "companyId", "userId", "payItem", "type" ] }, "example": { "method": "addRecurringPayItem", "companyId": "336CB829-543B-451D-AAA2-18A1B03454F2", "userId": "C8E5F6AB-4CB5-406C-B756-208B742F4281", "payItem": "Garnishments", "type": "CN RPP", "amountPerPayPeriod": 450 } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "status", "message" ] }, "example": { "Status": "Success", "Message": "Recurring pay item added successfully." } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid companyId" } } } }, "headers": {} } }, "security": [] } }, "/adminPortal/updateRecurringPayItem": { "put": { "summary": "updateRecurringPayItem", "deprecated": false, "description": "The `updateRecurringPayItem` API is used to make amount updates to an employee's existing recurring payroll item.\n\n### What it does:\n- Updates the `allocatedPercentage` or `amountPerPayPeriod` for an existing item\n- Can be used to switch between percentage and set dollar amount\n\n### Notes:\n- A recurring pay item must already exist with the specified `type`\n- Updates will reflect immediately in open pay periods but will not affect processing or processed pay periods", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "userId": { "type": "string" }, "type": { "type": "string" }, "allocatedPercentage": { "type": "number" }, "amountPerPayPeriod": { "type": "number" } }, "required": [ "method", "companyId", "userId", "type" ] }, "example": { "method": "updateRecurringPayItem", "companyId": "336CB829-543B-451D-AAA2-18A1B03454F2", "userId": "C8E5F6AB-4CB5-406C-B756-208B742F4281", "type": "CN RPP", "allocatedPercentage": 5 } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "status", "message" ] }, "example": { "Status": "Success", "Message": "Recurring pay item updated successfully." } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid companyId" } } } }, "headers": {} } }, "security": [] } }, "/adminPortal/deleteRecurringPayItem": { "delete": { "summary": "deleteRecurringPayItem", "deprecated": false, "description": "The `deleteRecurringPayItem` API is used to completely remove a recurring pay item for an employee.\n\n### What it does:\n- Removes an existing recurring pay item for an employee\n- Removes the pay item from open pay periods\n\n### Notes:\n- If you do not need to remove the pay item completely, please use the `updateRecurringPayItem` API\n- Once deleted, a recurring pay item of the same `type` can be re-added to an employee", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "userId": { "type": "string" }, "type": { "type": "string" } }, "required": [ "method", "companyId", "userId", "type" ] }, "example": { "method": "deleteRecurringPayItem", "companyId": "336CB829-543B-451D-AAA2-18A1B03454F2", "userId": "80FBE5FA-3BE3-4CDA-A396-17CA4DF4B965", "type": "125Adoption Assistance Sup" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "status", "message" ] }, "example": { "Status": "Success", "Message": "Recurring pay item deleted successfully." } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid companyId" } } } }, "headers": {} } }, "security": [] } }, "/adminPortal/updateBusinessUserAsEmployee": { "put": { "summary": "updateBusinessUserAsEmployee", "deprecated": false, "description": "## Convert Business User to Employee\n\nConverts an existing business user into a company employee.\n\n### Location Requirements\n| Location Type | Required Field | Example |\n|---------------|----------------|---------|\n| Office | `companyLocationId` | \"FDF3DC4C-78F1-4D2A-AAFE-39E9D41456AF\" |\n| Remote | `code` (state code) | \"CA\", \"NY\", \"TX\" |\n\n### Common Use Cases\n- Business owner becoming employee\n- Admin taking on employee role\n- Dual role assignments", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "updateBusinessUserAsEmployee" ], "title": "updateBusinessUserAsEmployee" }, "businessUser": { "type": "object", "properties": { "businessUserId": { "type": "string" }, "workerType": { "type": "string", "title": "Enum", "maxLength": 8, "enum": [ "W2", "1099-NEC" ] }, "companyLocationCategory": { "type": "string" }, "code": { "type": "string", "title": "Need to be mentioned when \"companyLocationCategory\" is Office", "maxLength": 2, "enum": [ "TX", "AK", "ND", "IL", "MA", "KS", "AS", "AL", "UT", "SD", "MI", "DC", "GA", "SC", "TN", "OK", "CO", "CA", "ME", "MO", "WY", "MD", "VT", "NM", "CT", "AZ", "WI", "VA", "WV", "NJ", "DE", "NC", "PR", "IN", "MT", "NH", "HI", "IA", "KY", "WA", "OH", "FL", "OR", "MP", "GU", "MN", "MS", "PA", "NE", "RI", "ID", "LA", "NY", "NV", "AR" ] }, "companyLocationId": { "type": "string", "title": "Need to be mentioned when \"companyLocationCategory\" is Office" }, "jobTitle": { "type": "string" }, "startDate": { "type": "string" } }, "required": [ "businessUserId", "workerType", "companyLocationCategory", "code", "companyLocationId", "jobTitle", "startDate" ] } }, "required": [ "method", "businessUser" ] }, "example": { "method": "updateBusinessUserAsEmployee", "businessUser": { "businessUserId": "FDF3DC4C-78F1-4D2A-AAFE-39E9D41456AF", "workerType": "W2", "companyLocationCategory": "Remote", "companyLocationId": "", "code": "FL", "jobTitle": "HR", "startDate": "2020-09-09" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "businessUser": { "type": "object", "properties": { "businessUserId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "businessUserId", "status" ], "x--orders": [ "BusinessUserID", "Status", "Message" ] } }, "required": [ "businessUser" ], "x--orders": [ "BusinessUser" ] }, "example": { "businessUser": { "businessUserId": "FDF3DC4C-78F1-4D2A-AAFE-39E9D41456AF", "status": "Ready", "message": "The Business User has been updated successfully." } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid businessUserId" } } } }, "headers": {} } }, "security": [] } }, "/adminPortal/updateEmployeeAsBusinessUser": { "put": { "summary": "updateEmployeeAsBusinessUser", "deprecated": false, "description": "\nThe `updateEmployeeAsBusinessUser` API adds an existing employee as a Business User of the company.\n\n### What it does:\n\n- Converts existing employees into Business Users with administrative roles\n- Assigns roles like Payroll Admin, Controller, or Beneficial Owner to employees\n\n### Note:\n\n- Requires ownership percentage specification for Beneficial Owner role", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "updateEmployeeAsBusinessUser" ], "title": "updateEmployeeAsBusinessUser" }, "user": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "payrollAdmin": { "type": "boolean" }, "bookKeeper": { "type": "boolean" }, "beneficialOwner": { "type": "boolean" }, "ownershipPercentage": { "type": "integer", "title": "Need to be mentioned when isBeneficialOwner is True" } }, "required": [ "userId", "payrollAdmin", "bookKeeper", "beneficialOwner" ] } }, "required": [ "method", "user" ] }, "example": { "method": "updateEmployeeAsBusinessUser", "user": { "userId": "8155F978-4A06-4BC7-937E-3AF761FC5F32", "payrollAdmin": true, "bookKeeper": true, "beneficialOwner": true, "ownershipPercentage": 30 } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "userId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "userId", "status", "message" ] } }, "required": [ "user" ] }, "example": { "user": { "userId": "5A2390E1-0F83-46BD-AE1C-81B30FE364E1", "status": "Ready", "message": "The details of user William Henry were successfully updated." } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid UserId" } } } }, "headers": {} } }, "security": [] } }, "/adminPortal/addUserWage": { "post": { "summary": "addUserWage", "deprecated": false, "description": "\nSets up wage information for an employee or contractor.\n\n### Required After\n- Must call `addUser` first\n- Employee must exist in system\n\n### Wage Basis Options\n- \"Per Hour\" - Hourly employees\n- \"Per Week\" - Weekly salary\n- \"Per Month\" - Monthly salary\n- \"Per Year\" - Annual salary\n\n### Worker Types\n- \"W2\" - Traditional employees\n- \"1099\" - Independent contractors", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "addUserWage" ], "title": "addUserWage" }, "addUserWage": { "type": "object", "properties": { "companyId": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid" }, "differentialPay": { "type": "string", "examples": [ "Yes/No" ], "enum": [ "Yes", "No" ] }, "wageRate": { "type": "number", "maximum": 40 }, "workerType": { "type": "string", "title": "Enum", "maxLength": 8, "enum": [ "W2", "1099-NEC" ] }, "wageBasis": { "type": "string", "title": "Enum - For 1099 only PerHour, PerDay, PerWeek values are allowed ", "enum": [ "Per Week", "Per Year", "Per Day", "Per Hour", "Per Month" ], "maxLength": 20 }, "userType": { "type": "string", "title": "Enum", "enum": [ "Commission only/Eliglble for overtime", "Commission only/No overtime", "Paid by the hour", "Salary/Eligible for overtime", "Salary/No overtime" ], "maxLength": 40 }, "employmentStatus": { "type": "string", "title": "Enum", "maxLength": 50, "enum": [ "Part Time (0-19 Hours per week)", "Seasonal (0-6 months per year)", "Full Time (30+ Hours per week)", "Part Time (20-29 Hours per week)", "Variable (Hours vary every week)" ] }, "userRefTaxExempt": { "type": "string", "title": "Enum", "enum": [ "No, this employee is not tax exempt", "Yes, for another reason", "Yes, as an owner/corporate officer", "Yes, as a newspaper vendor", "Yes, as a member of the clergy or a religious order", "Yes, as a family employee", "Yes, as a non-resident alien" ], "maxLength": 50 }, "startDate": { "type": "string", "maxLength": 10 }, "paymentMethod": { "type": "string", "enum": [ "Direct Deposit", "Check" ], "maxLength": 20 } }, "required": [ "companyId", "userId", "wageRate", "workerType", "wageBasis", "userType", "employmentStatus", "userRefTaxExempt", "paymentMethod" ], "x--orders": [ "companyId", "employeeId", "wageRate", "workerType", "wageBasis", "employeeType", "employmentStatus", "employeeRefTaxExempt", "startDate" ] } }, "required": [ "method", "addUserWage" ], "x--orders": [ "method", "employeeWage" ] }, "example": { "method": "addUserWage", "userWage": { "companyId": "AE36FED3-0FDE-41F7-8312-C29FACD0E9EC", "userId": "7DF6034A-F5A9-43F3-B5A2-42DC61A4EE12", "differentialPay": "No", "wageRate": 111, "workerType": "W2", "wageBasis": "Per Week", "userType": "Salary/Eligible for overtime", "employmentStatus": "Full Time (30+ Hours per week)", "userRefTaxExempt": "Yes, as an owner/corporate officer", "startDate": "2023-02-25", "paymentMethod": "Direct Deposit" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "userWage": { "type": "object", "properties": { "userWageId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "userWageId", "status" ], "x--orders": [ "EmployeeWageID", "Status", "Message" ] } }, "required": [ "userWage" ], "x--orders": [ "EmployeeWage" ] }, "example": { "userWage": { "userWageId": "739BC4C4-2D79-431A-B0FF-489BADB70D9C", "status": "Verification Pending", "message": "User Wage for jacob king has been saved successfully." } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid date format" } } } }, "headers": {} } }, "security": [] } }, "/adminPortal/verifyMicroDeposits": { "post": { "summary": "verifyMicroDeposits", "deprecated": false, "description": "\nThe `verifyMicroDeposits` API verifies micro deposit amounts to confirm company bank account ownership.\n\n### What it does:\n\n- Verifies two small debit amounts sent to the company's bank account to ensure the company has legitimate access to the funding source\n- Completes the bank account verification process for payroll funding\n\n### Note:\n\n- Requires exact debit amounts (**debitAmount1** and **debitAmount2**) from bank statement", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "addUserWage" }, "companyId": { "type": "string" }, "debitAmount1": { "type": "number" }, "debitAmount2": { "type": "number" } }, "required": [ "method", "companyId", "debitAmount1", "debitAmount2" ] }, "example": { "method": "verifyMicroDeposits", "companyId": "7F8DBF11-3551-426C-8820-434C8CC33664", "debitAmount1": 0.12, "debitAmount2": 0.15 } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "status", "message" ] }, "example": { "status": "failed", "message": "Verification Failed." } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "example": { "code": 400, "message": "Bank account dosen't not exists for this companyId" } } }, "headers": {} } }, "security": [] } }, "/adminPortal/updateUserWage": { "put": { "summary": "updateUserWage", "deprecated": false, "description": "The `updateUserWage` API updates wage details for an employee or contractor.\n\n### What it does:\n\n- Can be used to update wage, payment methods, employment status, tax exemptions for existing users", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "updateUserWage" }, "userWage": { "type": "object", "properties": { "userWageId": { "type": "string" }, "wageRate": { "type": "integer" }, "workerType": { "type": "string", "title": "Enum" }, "wageBasis": { "type": "string", "title": "Enum" }, "userType": { "type": "string" }, "employmentStatus": { "type": "string" }, "userRefTaxExempt": { "type": "string" }, "startDate": { "type": "string" } }, "required": [ "userWageId" ] } }, "required": [ "method", "userWage" ] }, "example": { "method": "updateUserWage", "userWage": { "userWageId": "97EFDBF6-A979-4593-9393-204EB3471C3B", "wageRate": 3560, "workerType": "W2", "wageBasis": "Per Week", "userType": "Salary/Eligible for overtime", "employmentStatus": "Full Time (30+ Hours per week)", "userRefTaxExempt": "Yes, as an owner/corporate officer", "startDate": "2023-02-25" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "userWage": { "type": "object", "properties": { "userWageId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "userWageId", "status" ], "x--orders": [ "EmployeeWageID", "Status", "Message" ] } }, "required": [ "userWage" ], "x--orders": [ "EmployeeWage" ] }, "example": { "userWage": { "userWageId": "057B2704-02FB-489D-B01B-731A225DAF68", "status": "Ready", "message": "The User's wage data has been updated successfully." } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid date format" } } } }, "headers": {} } }, "security": [] } }, "/adminPortal/addEmployeeMiscellaneousStateTax": { "post": { "summary": "addEmployeeMiscellaneousStateTax", "deprecated": false, "description": "The `addEmployeeMiscellaneousStateTax ` API is used to collect state-specific tax withholding information for employees in states that require profession/job specific taxes\n\n### What it does:\n\n- Used when a state tax does not apply to all employees within the state, but to a select few professions/jobs\n\n### Notes:\n\n- This step is only required for employees subjest to state taxes not covered in the standard W4 import. Skip this step if the employee is not subject to miscellaneous taxes.\n- \"CompositeRate\" cannot be less than \"PayrollDeductionRate\".\n- A user's MiscellaneousStateTaxes can be seen in `getUsers` and `getUser` APIs.\n- After adding MiscellaneousStateTaxes, use `getEmployeeMiscellaneousStateTaxforPayroll` to retrieve the exact object to add the taxes to payroll.", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "userId": { "type": "string" }, "employeeMiscellaneousStateTax": { "type": "object", "properties": { "CompositeRate": { "type": "string" }, "RiskClassName": { "type": "string" }, "RiskClassCode": { "type": "string" }, "PayrollDeductionRate": { "type": "string" } }, "required": [ "CompositeRate", "RiskClassName", "RiskClassCode", "PayrollDeductionRate" ] } }, "required": [ "method", "companyId", "userId", "employeeMiscellaneousStateTax" ] }, "example": { "method": "addEmployeeMiscellaneousStateTax", "companyId": "7440E812-C699-4A94-AE14-A4B788D83299", "userId": "98CCB6CF-08DD-4C17-A367-B339CD5526CD", "employeeMiscellaneousStateTax": { "CompositeRate": "5", "RiskClassName": "Painter", "RiskClassCode": "121212", "PayrollDeductionRate": "4" } } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": { "employeeMiscellaneousStateTax": { "status": "Ready", "message": "The Employee Miscellaneous State Tax Information has been saved successfully." } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "CompositeRate (5.0) cannot be less than PayrollDeductionRate (7.0)" } } } }, "headers": {} } }, "security": [] } }, "/adminPortal/updateEmployeeMiscellaneousStateTax": { "put": { "summary": "updateEmployeeMiscellaneousStateTax", "deprecated": false, "description": "The `updateEmployeeMiscellaneousStateTax` API is used to update miscellaneous state taxes added to individual employees\n\n### What it does:\n\n- Used when a state tax does not apply to all employees within the state, but to a select few professions/jobs\n\n### Notes:\n\n- This step is only required for employees subjest to state taxes not covered in the standard W4 import. Skip this step if the employee is not subject to miscellaneous taxes.\n- \"CompositeRate\" cannot be less than \"PayrollDeductionRate\".\n- A user's MiscellaneousStateTaxes can be seen in `getUsers` and `getUser` APIs.\n- After adding MiscellaneousStateTaxes, use `getEmployeeMiscellaneousStateTaxforPayroll` to retrieve the exact object to add the taxes to payroll.", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "examples": {} } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } }, "headers": {} } }, "security": [] } }, "/adminPortal/removeEmployeeMiscellaneousStateTax": { "delete": { "summary": "removeEmployeeMiscellaneousStateTax", "deprecated": false, "description": "", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "examples": {} } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } }, "headers": {} } }, "security": [] } }, "/adminPortal/deactivateUser": { "post": { "summary": "deactivateUser", "deprecated": false, "description": "\nThe `deactivateUser` API temporarily deactivates an employee or contractor.\n\n### What it does:\n\n- Deactivates users while preserving their records for potential reactivation\n- Sets exit date and final paycheck details for the deactivated user\n- Triggers an automated email explaining the deactivation to the employee\n- Allows additional notes to be recorded - circumstances or employee specific details on deactivation\n\n### Notes:\n\n- Different from `terminateUser` - deactivated users can be reactivated with `activateUser`\n- Used for temporary separations like leave of absence or seasonal layoffs", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "deactivateUser" ], "title": "deactivateUser" }, "user": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "exitDate": { "type": "string", "maxLength": 10 }, "personalEmail": { "type": "string", "maxLength": 40 }, "finalPayCheckType": { "type": "string", "title": "Enum", "enum": [ "They will be paid by cash or check", "They will be paid by supplemental payroll", "They will be paid by a different way", "They will be paid during a regular payroll cycle", "They have already been paid" ] }, "additionalNotes": { "type": "string", "maxLength": 40 } }, "required": [ "userId", "exitDate", "finalPayCheckType", "personalEmail" ] } }, "required": [ "method", "user" ] }, "example": { "method": "deactivateUser", "user": { "userId": "f9b2507d-c757-4c9a-9e96-0002299fa2f7", "exitDate": "2023-09-09", "personalEmail": "mm@aa.ll", "finalPayCheckType": "They have already been paid", "additionalNotes": "deactivating temporarily" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "userId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "userId", "status" ] } }, "required": [ "user" ] }, "example": { "user": { "userId": "f9b2507d-c757-4c9a-9e96-0002299fa2f7", "status": "Inactive", "message": "The User has been deactivated successfully." } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "EmployeeId is mandatory and cannot be empty." } } } }, "headers": {} } }, "security": [] } }, "/adminPortal/terminateUser": { "put": { "summary": "terminateUser", "deprecated": false, "description": "\nThe `terminateUser` API permanently terminates an employee or contractor. The termination is permanent and users cannot be reactivated, but employee data is retained for compliance reasons.\n\n### What it does:\n\n- Sets exit date, final paycheck details and termination reason\n- Option to add a severance package \n- Allows more complex severance packets to be applied to termination, including \n- Includes additional notes \n\n### Options\n\n#### terminationChoice\n\n- Yes - This employee is leaving voluntarily\n- No - This user did not choose to leave\n\n#### Final Payment Details\n\n- They will be paid by cash or check\n- They will be paid by supplemental payroll\n- They will be paid by a different way\n- They will be paid during a regular payroll cycle\n- They have already been paid\n\n### Notes:\n\n- Different from `deactivateUser` - terminated users cannot be reactivated\n- Includes severance payment options including payment over time and lump sum, and dismissal type tracking", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "terminateUser" ], "title": "terminateUser" }, "user": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "companyId": { "type": "string", "format": "uuid" }, "exitDate": { "type": "string" }, "personalEmail": { "type": "string" }, "finalPayCheckType": { "type": "string", "title": "Enum", "enum": [ "They will be paid by cash or check", "They will be paid by supplemental payroll", "They will be paid by a different way", "They will be paid during a regular payroll cycle", "They have already been paid" ] }, "terminationChoice": { "type": "string", "title": "Enum", "enum": [ "Yes - This employee is leaving voluntarily", "No - This employee did not choose to leave" ] }, "dismissalType": { "type": "string", "title": "Only used If employeeRefTerminationChoice is No", "enum": [ "Performance", "Attendance", "Other", "Layoff", "Location", "Seasonal", "Position Eliminated" ] }, "severance": { "type": "boolean" }, "severancePaymentType": { "type": "string", "enum": [ "No, the severance payments will be made over time", "Yes, it will be a one time severance payment" ] }, "severancePaymentFrequency": { "type": "string", "enum": [ "Weekly, every Friday", "Bi-Weekly, Every other Friday", "Monthly, Last Day of the month", "Semi-Monthly, 15th and last day of month" ] }, "firstSeverancePayDate": { "type": "string", "maxLength": 10 }, "lastSeverancePayDate": { "type": "string", "maxLength": 10 }, "severanceAmount": { "type": "integer" }, "additionalNotes": { "type": "string" } }, "required": [ "userId", "companyId", "exitDate", "personalEmail", "finalPayCheckType", "terminationChoice", "dismissalType", "severance", "severancePaymentType", "severancePaymentFrequency", "firstSeverancePayDate", "lastSeverancePayDate", "severanceAmount" ] } }, "required": [ "method", "user" ] }, "example": { "method": "terminateUser", "user": { "userId": "f9b2507d-c757-4c9a-9e96-0002299fa2f7", "companyId": "eb869cf0-af11-4bdb-853c-fd2616bc91f2", "exitDate": "2023-09-09", "personalEmail": "mm@aa.ll", "finalPayCheckType": "They have already been paid", "terminationChoice": "No - This user did not choose to leave", "dismissalType": "Layoff", "severance": true, "severancePaymentType": "Yes, it will be a one time severance payment", "severancePaymentFrequency": "Weekly, every Friday", "firstSeverancePayDate": "2023-09-09", "lastSeverancePayDate": "2023-12-12", "severanceAmount": 2333, "additionalNotes": "terminated due to recession" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "userId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "userId", "status" ] } }, "required": [ "user" ] }, "examples": { "1": { "summary": "Success", "value": { "user": { "userId": "f9b2507d-c757-4c9a-9e96-0002299fa2f7", "status": "Inactive", "message": "The User has been terminated successfully." } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "UserId is mandatory and cannot be empty." } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } }, "required": [ "error" ] } } }, "headers": {} } }, "security": [] } }, "/adminPortal/activateUser": { "post": { "summary": "activateUser", "deprecated": false, "description": "## Reactivate Employee/Contractor\n\nReactivates a previously deactivated employee or contractor.\n\n### When to Use\n- Rehiring former employees\n- Reactivating seasonal workers\n- Correcting accidental deactivations\n\n### Prerequisites\n- User must be in \"Deactivated\" status\n- Cannot reactivate deleted users", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "activateUser" ], "title": "activateUser" }, "user": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" } }, "required": [ "userId" ] } }, "required": [ "method", "user" ] }, "example": { "method": "activateUser", "user": { "userId": "f9b2507d-c757-4c9a-9e96-0002299fa2f7" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "userId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "userId", "status" ] } }, "required": [ "user" ] }, "example": { "user": { "userId": "f9b2507d-c757-4c9a-9e96-0002299fa2f7", "status": "Active", "message": "The User has been activated successfully." } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "UserId is mandatory and cannot be empty." } } } }, "headers": {} } }, "security": [] } }, "/adminPortal/addCompanyBankAccount": { "post": { "summary": "addCompanyBankAccount", "deprecated": false, "description": "The `addCompanyBankAccount` API adds bank account details for a company to process payroll.\n\n### What it does:\n- Adds company bank account information including account number, routing number, and bank name\n- Sets up the funding source for payroll processing and payments\n\n### Note:\n- Account type is limited to **savings** or **checking**\n- This endpoint can also be used to update a company's linked account after using `deactivateCompanyBankAccount` on the existing entity.\n\n### Account Linking with Plaid\n- Use the `linkType` field to determine the linking method for the account. Supported options are **Manual**, **Plaid** and **CustomProvider**. If not included, linkType defaults to Manual\n- If `linkType` is **Plaid**, you must choose between sending the link via email or returning the link via API to surface in your UI using the `plaidOptions` field. Account details are not required.\n- The invite email will be sent to the payrollAdmin. If you wish to send the invite to a different email address, please specify with 'email'\n- The intiital valid link will be re-used for subsequent 'addCompanyBankAccount' calls\n\n⚠️ Warning: Plaid links have an expiry and should be completed as soon as possible. Default expiry is 72 hours. ", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "addCompanyBankAccount" ], "title": "addCompanyBankAccount" }, "linkType": { "type": "string", "enum": [ "Plaid", "CustomProvider", "Manual" ], "description": "Default: Manual" }, "plaidOptions": { "type": "string", "description": "Required if linkType: plaid", "enum": [ "generateURL", "sendInviteByEmail" ] }, "companyFundingSourceEntity": { "type": "object", "properties": { "companyId": { "type": "string", "format": "uuid" }, "accountNumber": { "type": "string", "maxLength": 40, "description": "Not required for Plaid" }, "routingNumber": { "type": "string", "maxLength": 40, "description": "Not required for Plaid" }, "bankName": { "type": "string", "maxLength": 40, "description": "Not required for Plaid" }, "accountType": { "type": "string", "maxLength": 40, "enum": [ "savings", "checking" ], "description": "Not required for Plaid" }, "accountName": { "type": "string", "description": "Not required for Plaid" } }, "required": [ "companyId" ] } }, "required": [ "method", "companyFundingSourceEntity" ] }, "examples": { "1": { "value": { "method": "addCompanyBankAccount", "companyFundingSourceEntity": { "companyId": "8A9B7683-8E02-494D-8422-963FD05EE785", "accountNumber": "9889890989", "routingNumber": "221982389", "bankName": "Chase Bank", "accountType": "savings", "accountName": "default" } }, "summary": "Manual" }, "2": { "value": { "method": "addCompanyBankAccount", "linkType": "Plaid", "plaidOptions": "sendInviteByEmail", "email": "test@mailsac.com", "companyFundingSourceEntity": { "companyId": "03B5FD90-4A91-46D8-A892-CFB8F52A8E67" } }, "summary": "Plaid Email Example" }, "3": { "value": { "method": "addCompanyBankAccount", "linkType": "Plaid", "plaidOptions": "generateURL", "companyFundingSourceEntity": { "companyId": "03B5FD90-4A91-46D8-A892-CFB8F52A8E67" } }, "summary": "Plaid URL Link Example" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "companyFundingSourceEntity": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "status", "message" ] }, "message": { "type": "string" }, "invitesentto": { "type": "string" }, "plaidLinkURL": { "type": "string" }, "expirationDate": { "type": "string" } } }, "examples": { "1": { "summary": "Success", "value": { "companyFundingSourceEntity": { "status": "pending", "message": "The Company's bank account has been added successfully." } } }, "2": { "summary": "Plaid - URL Link", "value": { "message": "Bank Linking is in progress. The company will be updated once the linking is completed.", "plaidLinkURL": "https://secure.plaid.com/hl/lsqr1nnr54r9so9751n0rn0o625q7p5r10", "expirationDate": "2026-06-15T15:06:27.902391Z" } }, "3": { "summary": "Plaid - Email", "value": { "message": "Bank Linking is in progress , payPercentage will be updated , once the linking is completed.", "invitesentto": "testPlaid@mailsac.com", "plaidLinkURL": "https://secure.plaid.com/hl/lsqr1nnr54r9so9751n0rn0o625q7p5r10", "expirationDate": "2026-06-15T15:06:27.807Z" } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid CompanyId" } } } }, "headers": {} } }, "security": [] } }, "/adminPortal/uploadDocument": { "post": { "summary": "uploadDocument", "deprecated": false, "description": "This API is used to upload compliance and miscellaneous documents to a company for retriveal using the `downloadDocument` API\n\n### When to use:\n- When adding documents at a company level\n- When adding employee or pay period specific documents\n\n---\nOnly IDs that pertain to the specific documentType are required to ensure they are routed correctly. \n|Example Document|Requried IDs|\n|-|-|\n|Paystubs|companyId, employeeId, payPeriodId|\n|Payroll journals|companyId, payPeriodId|\n|Company handbook|companyId|\n\n### 8655 and W4 forms:\nRollfi supports uploading employee W4s and 8655 forms through the API. These are specified using the documentType\n\n|Document|documentType|Required IDs|\n|-|-|-|\n|Employee W4|W4Form|companyId, employeeId|\n|Company 8655|8655Form|companyId|\n\n\n### Note:\n- Documents should be uploaded in base64 encoding for safe storage and retrieval\n- Uploaded documents can be viewed using `getUploadedDocuments` and retrieved from storage using `downloadDocument`", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "employeeId": { "type": "string" }, "payPeriodId": { "type": "string" }, "fileName": { "type": "string" }, "documentType": { "type": "string" }, "fileBase64": { "type": "string" } }, "required": [ "method", "companyId", "fileName", "fileBase64" ] }, "example": { "method": "uploadDocument", "companyId": "6FFBAEFF-020F-4F63-A140-0348BD0F0FCB", "employeeId": "161978BD-C696-495A-87DC-226B9D0D5A3B", "payPeriodId": "D9108BF3-5FFB-433D-89E2-7A4C79972153", "fileName": "sample-document.pdf", "documentType": "PayStub", "fileBase64": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMiAwIFIKPj4KZW5kb2JqCjIgMCBvYmoKPDwKL1R5cGUgL1BhZ2VzCi9LaWRzIFszIDAgUl0KL0NvdW50IDEKPD4KZW5kb2JqCjMgMCBvYmoKPDwKL1R5cGUgL1BhZ2UKL1BhcmVudCAyIDAgUgovTWVkaWFCb3ggWzAgMCA2MTIgNzkyXQovUmVzb3VyY2VzIDw8Ci9Qcm9jU2V0IFsvUERGIC9UZXh0IC9JbWFnZUIgL0ltYWdlQyAvSW1hZ2VJXQo+PgovQ29udGVudHMgNCAwIFIKPj4KZW5kb2JqCjQgMCBvYmoKPDwKL0xlbmd0aCA0NAo+PgpzdHJlYW0KQlQKL0YxIDEyIFRmCjcyIDcyMCBUZAooSGVsbG8gV29ybGQpIFRqCkVUCmVuZHN0cmVhbQplbmRvYmoKeHJlZgowIDUKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQ1IDAwMDAwIG4gCnRyYWlsZXIKPDwKL1NpemUgNQovUm9vdCAxIDAgUgo+PgpzdGFydHhyZWYKMzM4CiUlRU9G" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "documentId": { "type": "string" }, "fileName": { "type": "string" }, "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "documentId", "fileName", "success", "message" ] }, "example": { "documentId": "181D4FCA-CBDB-49F6-93BE-95B78AD3045E", "fileName": "sample-document.pdf", "success": true, "message": "Document uploaded successfully" } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid PayPeriodId" } } } }, "headers": {} } }, "security": [] } }, "/adminPortal/downloadDocument": { "get": { "summary": "downloadDocument", "deprecated": false, "description": "The `downloadDocument` API is used to download a Base64 encoded PDF document\n\n### When to use:\n- When retrieving a pre filled W4 or 8655 to be signed and uploaded\n- When retrieving a document that was already uploaded to Rollfi\n\n### Required fields:\n|Document Description|Required Fields|\n|-|-|\n|Document uploaded to Rollfi using the uploadDocument API|documentId|\n|Pre filled 8655 without signature|companyId, documentType|\n|Pre filled W4 without signature|companyId, employeeId, documentType|\n|Pre filled State W4 without signature|documentId|\n\n### State W4 retrieval\n- State W4s are generated for each employee during onboarding after `initateUserKyc`\n- documentIds can be retrieved for state W4 forms using getUploadedDocuments\n- complete State W4 forms can be uploaded using the uploadDocument API\n- current state support: NJ, OH, NC, KY, KS", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "documentId": { "type": "string" }, "companyId": { "type": "string" }, "employeeId": { "type": "string" }, "documentType": { "type": "string", "enum": [ "8655Form", "W4Form" ] } }, "required": [ "method" ] }, "examples": { "1": { "value": { "method": "downloadDocument", "companyId": "82CCB239-764C-49BA-A3A8-00B9C37A59D4", "documentType": "8655Form" }, "summary": "Pre-fill 8655" }, "2": { "value": { "method": "downloadDocument", "documentId": "179F3EE8-8CF4-4C4F-8430-5C25C9E190F9" }, "summary": "by documentId" }, "3": { "value": { "method": "getUploadedDocuments", "companyId": "28FCB32E-29FE-4269-8AA3-011E7276EF5E", "employeeId": "FA937C14-5DFE-40B3-B2C2-19BA2E988DCF" }, "summary": "Pre-fill W4" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "documentId": { "type": "string" }, "companyId": { "type": "string" }, "employeeId": { "type": [ "string", "null" ] }, "payPeriodId": { "type": [ "string", "null" ] }, "fileName": { "type": "string" }, "documentType": { "type": "string" }, "fileBase64": { "type": "string" }, "downloadCount": { "type": "integer" } }, "required": [ "documentId", "companyId", "fileName", "documentType", "fileBase64", "downloadCount" ] }, "example": { "documentId": "24A9F639-689C-4E7D-80CB-14AD3A608B21", "companyId": "6FFBAEFF-020F-4F63-A140-0348BD0F0FCB", "employeeId": "161978BD-C696-495A-87DC-226B9D0D5A3B", "payPeriodId": null, "fileName": "sample-document.pdf", "documentType": "Team Documents", "fileBase64": "JVeLjz9MKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMiAwIFIKPj4KZW5kb2JqCjIgMCBvYmoKPDwKL1R5cGUgL1BhZ2sssVzCi9LaWRzIFszIDAgUl0KL0NvdW50IDEKPD4KZW5kb2JqCjMgMCBvYmoKPDwKL1R5cGUgL1BhZ2UKL1BhcmVudCAyIDAgUgovTWVkaWFCb3ggWzAgMCA2MTIgNzkyXQovUmVzb3VyY2VzIDw8ChegHl80UERGIC9UZXh0IC9JbWFnZUIgL0ltYWdlQyAvSW1hZ2VJXQo+PgovQ29udGVudHMgNCAwIFIKPj4KZW5kb2JqCjQgMCBvYmoKPDwKL0xlbmd0aCA0NAo+PgpzdHJlYW0KQlQKL0YxIDEyIFRmCjcyIDcyMCBUZAooSGVsbG8gV29ybGQpIFRqCkVUCmVuZHN0cmVhbQplbmRvYmoKeHJlZHwgHllLMha6Gh9DAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMAowMDAwMDAwMjQ1IDAwMDAwIG4gCnRyYWlsZXIKPDwKL1NpemUgNQovUm9vdCAxIDAgUgo+PgpzdGFydHhyZWYKMzM4CiUlRU9G", "downloadCount": 1 } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "documentId is required" } } } }, "headers": {} } }, "security": [] } }, "/adminPortal/deactivateCompanyBankAccount": { "put": { "summary": "deactivateCompanyBankAccount", "deprecated": false, "description": "\nThe `deactivateCompanyBankAccount` API deactivates a company's bank account in the system.\n\n### What it does:\n\n- Deactivates the company's funding source while preserving account records\n- Prevents future payroll transactions from using the deactivated account\n\n### Notes:\n\n- At least one active bank account must be linked to a company at all times\n- Historical banking history is maintained for compliance\n- Deactivated bank accounts cannot be re-activated they must be manually added again using `addCompanyBankAccount`", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "deactivateCompanyBankAccount" ], "title": "deactivateCompanyBankAccount" }, "companyId": { "type": "string", "format": "uuid" } }, "required": [ "method", "companyId" ] }, "example": { "method": "deactivateCompanyFundingSourceEntity", "companyId": "5DB0A2B8-5346-41E5-9CE7-444482475C" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "companyFundingSourceEntity": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "companyId": { "type": "string" } }, "required": [ "status", "message", "companyId" ] } }, "required": [ "companyFundingSourceEntity" ] }, "example": { "companyFundingSourceEntity": { "status": "Inactive", "message": "The Company's Bank Account has been deactivated successfully.", "companyId": "914CB6A7-11D4-463F-8C25-C07F615CEF11" } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid CompanyId" } } } }, "headers": {} } }, "security": [] } }, "/adminPortal/addGarnishments": { "post": { "summary": "addGarnishments", "deprecated": false, "description": "The `addGarnishments` API is used to set up recurring wage garnishments for an employee\n\n---\nGarnishment form fields are type and agency specific.\n- To retrieve the form fields for a garnishment or agency use the `getGarnishmentFormFields` API\n- To retrieve garnishment agencies for a garnishment type use the `getGarnishmentAgencies` API. Currently only child support agencies are supported\n- The amount withheld per pay period is automatically calculated from the total amount and frequency since the garnishment schedule may differ from the paySchedule\n---\n\n### Notes:\n- Currently only child support payments can be made by Rollfi (in all states except SC)\n- For garnishments outside of child support, Rollfi will calculate garnishment deductions from the employee's pay check but will not make the payment.\n- Garnishments added to an employee show up in their `getUser` request", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "userId": { "type": "string" }, "companyId": { "type": "string" }, "employeeGarnishments": { "type": "array", "items": { "type": "object", "properties": { "garnishmentType": { "type": "string" }, "garnishmentAgency": { "type": "string" }, "garnishmentFields": { "type": "object", "properties": {} } }, "required": [ "garnishmentType", "garnishmentFields" ] } } }, "required": [ "method", "userId", "companyId", "employeeGarnishments" ] }, "example": { "method": "addGarnishments", "userId": "1755E872-9092-4ECE-8386-860531D492D3", "companyId": "21DA3F1A-E593-42EE-95F5-A22EDF6382F0", "employeeGarnishments": [ { "garnishmentType": "Child Support", "garnishmentAgency": "Florida Child Support Enforcement", "garnishmentFields": { "County": "Polk", "Case Number": "9218729", "Start Date": "2026-03-03", "End Date": "2026-09-09", "Total Withholding Amount": 1000, "Frequency (Per)": "Weekly", "Maximum Withholding Percentage": 0.1, "Choose who will be paying the agency": "I want my payroll provider to make the payments" } }, { "garnishmentType": "Student Loan", "garnishmentFields": { "End Date": "2026-06-06", "Amount needed to be withheld per pay period": 500, "Total amount to be garnished": 5000 } } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": { "garnishmentIds": [ "52F6249E-F4ED-40C2-B25F-39BB99BCF98D", "883826B8-1191-4553-A17F-9422162AF33D" ], "success": true, "message": "Processed 2 garnishments." } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "employeeGarnishments[0].garnishmentFields[Choose who will be paying the agency] value I dont want my payroll provider to make the payments is not valid for Choose who will be paying the agency." } } } }, "headers": {} } }, "security": [] } }, "/adminPortal/updateGarnishment": { "put": { "summary": "updateGarnishment", "deprecated": false, "description": "The `updateGarnishment` API is used to make changes to an existing garnishment entry for an employee\n\n---\n- An employee's active garnishments and garnishmentIds can be viewed using the `getUser` API\n- Garnishment form fields can be retrieved using `getGarnishmentFormFields`\n- The amount withheld per pay period is automatically calculated from the total amount and frequency since the garnishment schedule may differ from the paySchedule\n---\n\n### When to use:\n- When the garnishment details entered initially were incorrect, but the garnishment does apply to the employee\n- When payments have been made outside of payroll to reduce the employee's liability for the added garnishment\n- When a garnishment is no longer applicable to the employee, or the total amount of liability has changed", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "userId": { "type": "string" }, "companyId": { "type": "string" }, "garnishmentId": { "type": "string" }, "garnishmentFields": { "type": "object", "properties": {}, "description": "Dynamic object containing fields retrieved with getGarnishmentFormFields" } }, "required": [ "method", "userId", "companyId", "garnishmentId", "garnishmentFields" ] }, "example": { "method": "updateUserGarnishment", "userId": "1755E872-9092-4ECE-8386-860531D492D3", "companyId": "21DA3F1A-E593-42EE-95F5-A22EDF6382F0", "garnishmentId": "52F6249E-F4ED-40C2-B25F-39BB99BCF98D", "garnishmentFields": { "County": "Polk", "Case Number": "9218729", "Start Date": "2026-03-03", "End Date": "2026-09-09", "Total Withholding Amount": 1000, "Frequency (Per)": "Weekly", "Maximum Withholding Percentage": 0.1, "Choose who will be paying the agency": "I want my payroll provider to make the payments" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": { "success": true, "garnishmentId": "52F6249E-F4ED-40C2-B25F-39BB99BCF98D", "message": "Update successful" } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid CompanyId" } } } }, "headers": {} } }, "security": [] } }, "/adminPortal/removeGarnishment": { "post": { "summary": "removeGarnishment", "deprecated": false, "description": "The `removeGarnishment` API is used to remove a garnishment from an employee\n\n### When to use:\n- When the garnishment is paid in full outside of payroll\n- When a garnishment is no longer applicable to the employee\n\n### Notes: \n- An employee's active garnishments and garnishmentIds can be viewed using the `getUser` API\n- Once removed, the garnishment will no longer show in `getUser`, and will not be applied to future pay periods", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "userId": { "type": "string" }, "companyId": { "type": "string" }, "garnishmentId": { "type": "string" } }, "required": [ "method", "userId", "companyId", "garnishmentId" ] }, "example": { "method": "removeUserGarnishment", "userId": "1755E872-9092-4ECE-8386-860531D492D3", "companyId": "21DA3F1A-E593-42EcE-95F5-A22EDF6382F0", "garnishmentId": "52F6249E-F4ED-40C2-B25F-39BB99BCF98D" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ] }, "example": { "success": true, "message": "Garnishment removed successfully" } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 404, "message": "garnishment not found" } } } }, "headers": {} } }, "security": [] } }, "/adminPortal/addTimeOffPolicy": { "post": { "summary": "addTimeOffPolicy", "deprecated": false, "description": "The `addTimeOffPolicy` API creates a new PTO policy for a company.\n\n### What it does:\n\n- Creates a time off policy with accrual or lump-sum earning rules.\n- Stores policy-level carryover, waiting period, and payout settings.\n\n### Notes:\n\n- `earningMethod` controls conditional required fields.\n- For `Lump Sum`, include `lumpSumHoursEarned`.\n- For `Accrual`, include `accrualRatePerHour` and `proratedByStartDate`.\n- If `canCarryoverHours` is `true`, include `maximumCarryoverHours`.", "operationId": "addTimeOffPolicy", "tags": [ "TimeOff Admin" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "method": { "type": "string", "const": "addTimeOffPolicy" }, "timeOffPolicy": { "type": "object", "additionalProperties": true, "properties": { "companyId": { "type": "string" }, "policyType": { "type": "string", "description": "Policy type label (for example: Paid Time Off, Sick Leave, Unpaid Leave)." }, "policyName": { "type": "string" }, "earningMethod": { "type": "string", "description": "How hours are earned (for example: Lump Sum or Accrual)." }, "lumpSumHoursEarned": { "type": "number", "description": "Required when earningMethod is Lump Sum." }, "accrualRatePerHour": { "type": "number", "description": "Required when earningMethod is Accrual." }, "canCarryoverHours": { "type": "boolean", "description": "Required for policy creation." }, "maximumCarryoverHours": { "type": "number", "description": "Required when canCarryoverHours is true." }, "maxAccumulatedHours": { "type": "number", "description": "Required for policy creation." }, "waitingPeriod": { "type": "string", "description": "Required. Format like \"2 Weeks\", \"3 Days\", \"1 Month\"." }, "proratedByStartDate": { "type": "boolean", "description": "Required when earningMethod is Accrual." }, "whenTimeOffReceived": { "type": "string", "description": "When time off is granted. Required for non-Unpaid Leave policies." }, "payoutOnTerminations": { "type": "boolean" }, "maxPayoutHours": { "type": "number" } } } }, "required": [ "method", "timeOffPolicy" ] }, "example": { "method": "addTimeOffPolicy", "timeOffPolicy": { "companyId": "5221FFCF-E84B-4690-B7DC-DE29D549096B", "policyType": "Paid Time Off", "policyName": "PTO Full Time", "earningMethod": "Lump Sum", "lumpSumHoursEarned": 80, "canCarryoverHours": true, "maximumCarryoverHours": 40, "maxAccumulatedHours": 120, "waitingPeriod": "0 Days", "proratedByStartDate": false, "whenTimeOffReceived": "Start of Year", "payoutOnTerminations": true, "maxPayoutHours": 80 } } } }, "required": true }, "responses": { "200": { "description": "Policy created", "content": { "application/json": { "schema": { "type": "object", "properties": { "timeOffPolicy": { "type": "object", "properties": { "timeOffPolicyId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "timeOffPolicyId", "status", "message" ] } }, "required": [ "timeOffPolicy" ] }, "example": { "timeOffPolicy": { "timeOffPolicyId": "EBA8563B-A2EA-46D6-A68A-5CEA5341575F", "status": "active", "message": "Time off policy has been added successfully" } } } }, "headers": {} }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "accrualRatePerHour is required when earningMethod is \"Accrual\"." } } } }, "headers": {} } }, "security": [] } }, "/adminPortal/addTimeOffPolicyAssignment": { "post": { "summary": "addTimeOffPolicyAssignment", "deprecated": false, "description": "The `addTimeOffPolicyAssignment` API assigns a PTO policy to an employee.\n\n### What it does:\n\n- Links a user to a specific PTO policy.\n- Establishes the assignment used for requests and balance tracking.", "operationId": "addTimeOffPolicyAssignment", "tags": [ "TimeOff Admin" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "method": { "type": "string", "const": "addTimeOffPolicyAssignment" }, "timeOffPolicyAssignment": { "type": "object", "additionalProperties": true, "properties": { "companyId": { "type": "string" }, "timeOffPolicyId": { "type": "string" }, "userId": { "type": "string", "description": "Employee user identifier." } } } }, "required": [ "method", "timeOffPolicyAssignment" ] }, "example": { "method": "addTimeOffPolicyAssignment", "timeOffPolicyAssignment": { "companyId": "5221FFCF-E84B-4690-B7DC-DE29D549096B", "timeOffPolicyId": "1BD5AB2B-AEEC-46CD-A93B-D1A68FB90C3A", "userId": "C4CA148F-F2C6-4E70-8349-57CC6DFC1C2B" } } } }, "required": true }, "responses": { "200": { "description": "Assignment created", "content": { "application/json": { "schema": { "type": "object", "properties": { "timeOffPolicyAssignment": { "type": "object", "properties": { "timeOffPolicyAssignmentId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "timeOffPolicyAssignmentId", "status", "message" ] } }, "required": [ "timeOffPolicyAssignment" ] }, "example": { "timeOffPolicyAssignment": { "timeOffPolicyAssignmentId": "6A2CE7AE-3D25-4E2D-A4A0-D71CB1A1F8FA", "status": "active", "message": "Time off policy assignment has been added successfully" } } } }, "headers": {} }, "400": { "description": "Validation or duplicate assignment error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "A time off policy assignment already exists for this user and policy." } } } }, "headers": {} } }, "security": [] } }, "/adminPortal/updateTimeOffPolicyAssignment": { "put": { "summary": "updateTimeOffPolicyAssignment", "deprecated": false, "description": "The `updateTimeOffPolicyAssignment` API updates an employee's PTO policy assignment balance.\n\n### What it does:\n\n- Adjusts assignment-level PTO balance values for an existing assignment.\n- Persists updated balance totals for downstream reporting.", "operationId": "updateTimeOffPolicyAssignment", "tags": [ "TimeOff Admin" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "method": { "type": "string", "const": "updateTimeOffPolicyAssignment" }, "timeOffPolicyAssignment": { "type": "object", "additionalProperties": true, "properties": { "companyId": { "type": "string" }, "userId": { "type": "string" }, "timeOffPolicyId": { "type": "string" }, "balance": { "type": "number", "description": "Desired resulting balance." } } } }, "required": [ "method", "timeOffPolicyAssignment" ] }, "example": { "method": "updateTimeOffPolicyAssignment", "timeOffPolicyAssignment": { "companyId": "5221FFCF-E84B-4690-B7DC-DE29D549096B", "userId": "C4CA148F-F2C6-4E70-8349-57CC6DFC1C2B", "timeOffPolicyId": "1BD5AB2B-AEEC-46CD-A93B-D1A68FB90C3A", "balance": 32 } } } }, "required": true }, "responses": { "200": { "description": "Balance updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "timeOffPolicyAssignment": { "type": "object", "properties": { "timeOffPolicyAssignmentId": { "type": "string" }, "previousBalance": { "type": "number" }, "newBalance": { "type": "number" }, "adjustmentHours": { "type": "integer" }, "timeOffRequestId": { "type": "string" }, "message": { "type": "string" } }, "required": [ "timeOffPolicyAssignmentId", "previousBalance", "newBalance", "adjustmentHours", "message" ] } }, "required": [ "timeOffPolicyAssignment" ] }, "example": { "timeOffPolicyAssignment": { "timeOffPolicyAssignmentId": "6A2CE7AE-3D25-4E2D-A4A0-D71CB1A1F8FA", "previousBalance": 24, "newBalance": 32, "adjustmentHours": 8, "timeOffRequestId": "F7D25F37-1B8B-4ED4-9BC2-2E4E8C3909E1", "message": "Time off policy assignment balance updated successfully" } } } }, "headers": {} }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "balance is required." } } } }, "headers": {} } }, "security": [] } }, "/adminPortal/approveTimeOffRequest": { "post": { "summary": "approveTimeOffRequest", "deprecated": false, "description": "The `approveTimeOffRequest` API approves or denies a pending PTO request.\n\n### What it does:\n\n- Moves a pending request to `Approved` or `Denied`.\n- Optionally overrides request breakout hours before finalizing status.\n\n### Notes:\n\n- Input uses `isApproved` (`true` approve, `false` deny).\n- Only requests currently in `Pending` status can be processed.", "operationId": "approveTimeOffRequest", "tags": [ "TimeOff Admin" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "method": { "type": "string", "const": "updateTimeOffStatus" }, "timeOffRequestId": { "type": "string" }, "isApproved": { "type": "boolean" } }, "required": [ "method", "timeOffRequestId", "isApproved" ] }, "example": { "method": "updateTimeOffStatus", "timeOffRequestId": "5E11A5FA-83C1-4F83-91D2-46931D0B9C58", "isApproved": true } } }, "required": true }, "responses": { "200": { "description": "Status updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "timeOffRequest": { "type": "object", "properties": { "timeOffRequestId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "timeOffRequestId", "status", "message" ] } }, "required": [ "timeOffRequest" ] }, "example": { "timeOffRequest": { "timeOffRequestId": "F7D25F37-1B8B-4ED4-9BC2-2E4E8C3909E1", "status": "Approved", "message": "Time off request approved successfully" } } } }, "headers": {} }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "isApproved is required (true to approve, false to reject)." } } } }, "headers": {} } }, "security": [] } }, "/adminPortal/addTimeTrackingPolicy": { "post": { "summary": "addTimeTrackingPolicy", "deprecated": false, "description": "The `addTimeTrackingPolicy` API creates a company time tracking policy.\n\n### What it does:\n- Creates the policy used to enable time tracking for the company.\n- Defines overtime thresholds for calculations.\n\n### Notes:\n- This policy currently defines `dailyOvertimeThreshold` and `weeklyOvertimeThreshold`.", "operationId": "addTimeTrackingPolicy", "tags": [ "TimeTracking Admin" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "dailyOvertimeThreshold": { "type": "integer" }, "weeklyOvertimeThreshold": { "type": "integer" } }, "required": [ "method", "companyId" ] }, "example": { "method": "addTimeTrackingPolicy", "companyId": "5221FFCF-E84B-4690-B7DC-DE29D549096B", "dailyOvertimeThreshold": 8, "weeklyOvertimeThreshold": 40 } } } }, "responses": { "200": { "description": "Policy created", "content": { "application/json": { "schema": { "type": "object", "properties": { "timeTrackingPolicy": { "type": "object", "properties": { "timeTrackingPolicyId": { "type": "string" }, "status": { "type": "string" } }, "required": [ "timeTrackingPolicyId", "status" ] } }, "required": [ "timeTrackingPolicy" ] }, "example": { "timeTrackingPolicy": { "timeTrackingPolicyId": "1DB2594A-7CC6-4310-B5F9-830604C66F6F", "status": "Active" } } } }, "headers": {} }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "An active time tracking policy already exists for this company." } } } }, "headers": {} } }, "security": [] } }, "/adminPortal/updateTimeTrackingPolicy": { "put": { "summary": "updateTimeTrackingPolicy", "deprecated": false, "description": "The `updateTimeTrackingPolicy` API updates an existing time tracking policy.\n\n### What it does:\n- Updates overtime threshold values for the active company policy.\n\n### Notes:\n- The policy fields are currently `dailyOvertimeThreshold` and `weeklyOvertimeThreshold`.", "operationId": "updateTimeTrackingPolicy", "tags": [ "TimeTracking Admin" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "dailyOvertimeThreshold": { "type": "integer" }, "weeklyOvertimeThreshold": { "type": "integer" } }, "required": [ "method", "companyId" ] }, "example": { "method": "updateTimeTrackingPolicy", "companyId": "5221FFCF-E84B-4690-B7DC-DE29D549096B", "timeTrackingPolicyId": "80CB5B4B-F6CB-4BB9-BBF9-30289014F1E8", "dailyOvertimeThreshold": 7, "weeklyOvertimeThreshold": 45 } } } }, "responses": { "200": { "description": "Policy updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "timeTrackingPolicy": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ] } }, "required": [ "timeTrackingPolicy" ] }, "example": { "timeTrackingPolicy": { "success": true, "message": "Time tracking policy updated successfully." } } } }, "headers": {} }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 404, "message": "Invalid time tracking policy ID." } } } }, "headers": {} } }, "security": [] } }, "/adminPortal/deleteTimeTrackingPolicy": { "delete": { "summary": "deleteTimeTrackingPolicy", "deprecated": false, "description": "The `deleteTimeTrackingPolicy` API is used when timetracking is no longer needed for a company, or when it makes sense to start over at the policy level\n\n### What it does:\n- Deletes the company's time tracking policy\n- Deactivates all open timecards and active assignments\n- Preserves time card history for deleted policies\n\n### Note:\n- This is a permenant deletion. You may be able to achieve a similar result by updating assignments and updating the policy\n- A new time tracking policy can be added after the delete with the `addTimeTrackingPolicy` API", "operationId": "deleteTimeTrackingPolicy", "tags": [ "TimeTracking Admin" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "timeTrackingPolicyId": { "type": "string" } }, "required": [ "method", "companyId", "timeTrackingPolicyId" ] }, "example": { "method": "deleteTimeTrackingPolicy", "companyId": "5221FFCF-E84B-4690-B7DC-DE29D549096B", "timeTrackingPolicyId": "1DB2594A-7CC6-4310-B5F9-830604C66F6F" } } } }, "responses": { "200": { "description": "Policy deactivated", "content": { "application/json": { "schema": { "type": "object", "properties": { "timeTrackingPolicy": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ] } }, "required": [ "timeTrackingPolicy" ] }, "example": { "timeTrackingPolicy": { "success": true, "message": "Time tracking policy deactivated successfully." } } } }, "headers": {} }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 404, "message": "Invalid time tracking policy ID." } } } }, "headers": {} } }, "security": [] } }, "/adminPortal/addTimeTrackingPolicyAssignments": { "post": { "summary": "addTimeTrackingPolicyAssignments", "deprecated": false, "description": "The `addTimeTrackingPolicyAssignments` API adds a batch of employees to an active time tracking policy for a company\n\n### What it does:\n- Creates an assignment record for each employee assigned to time tracking\n- Generates a timecard for each employee in their respective open pay period (for both W2 and 1099 users)\n\n### Note:\n- Employees must have an active policy assignment to participate in time tracking\n- Employees cannot be already assigned to the timeTracking Policy\n- Only Active employees can be added to the company's policy. Employees may be added before their **dateOfJoin** but will be ineligble to insert entries or clock in until the date lapses\n", "operationId": "addTimeTrackingPolicyAssignments", "tags": [ "TimeTracking Admin" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "timeTrackingPolicyId": { "type": "string" }, "userIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "method", "companyId", "timeTrackingPolicyId", "userIds" ] }, "example": { "method": "addTimeTrackingPolicyAssignments", "companyId": "5221FFCF-E84B-4690-B7DC-DE29D549096B", "timeTrackingPolicyId": "45C67A2B-4D64-47D2-B473-B7B5FD1CB80E", "userIds": [ "C4CA148F-F2C6-4E70-8349-57CC6DFC1C2B" ] } } } }, "responses": { "200": { "description": "Assignments updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "assignments": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "success": { "type": "boolean" }, "message": { "type": "string" } } } } }, "required": [ "assignments" ] }, "example": { "assignments": [ { "userId": "C4CA148F-F2C6-4E70-8349-57CC6DFC1C2B", "success": true, "message": "Employee assigned successfully." } ] } } }, "headers": {} }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "assignments": [ { "userId": "C4CA148F-F2C6-4E70-8349-57CC6DFC1C2B", "success": false, "error": { "code": 400, "message": "Employee already has an active assignment." } } ] } } }, "headers": {} } }, "security": [] } }, "/adminPortal/removeTimeTrackingPolicyAssignments": { "post": { "summary": "removeTimeTrackingPolicyAssignments", "deprecated": false, "description": "The `removeTimeTrackingPolicyAssignments` API bulk deactivates active policy assignments.\n\n### What it does:\n- Removes the employee's active assignment.\n- Deactivates related active time tracking records tied to that assignment.\n\n### Notes:\n- Employees can be re-added later by creating a new assignment while the company has an active policy.", "operationId": "removeTimeTrackingPolicyAssignments", "tags": [ "TimeTracking Admin" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "timeTrackingPolicyId": { "type": "string" }, "userIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "method", "companyId", "timeTrackingPolicyId", "userIds" ] }, "example": { "method": "removeTimeTrackingPolicyAssignments", "companyId": "5221FFCF-E84B-4690-B7DC-DE29D549096B", "timeTrackingPolicyId": "45C67A2B-4D64-47D2-B473-B7B5FD1CB80E", "userIds": [ "F64EFF29-6516-4C1E-B14D-82F00B7EADF9" ] } } } }, "responses": { "200": { "description": "Assignments updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "assignments": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "success": { "type": "boolean" }, "message": { "type": "string" } } } } }, "required": [ "assignments" ] }, "example": { "assignments": [ { "userId": "F64EFF29-6516-4C1E-B14D-82F00B7EADF9", "success": true, "message": "Assignment deactivated successfully." } ] } } }, "headers": {} }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "assignments": [ { "userId": "F64EFF29-6516-4C1E-B14D-82F00B7EADF9", "success": false, "error": { "code": 404, "message": "No active assignment found for this employee." } }, { "userId": "BCC67A2B-4D64-47D2-B473-B7B5FD1CB80E", "success": false, "error": { "code": 404, "message": "No active assignment found for this employee." } } ] } } }, "headers": {} } }, "security": [] } }, "/adminPortal/upsertTimeEntry": { "post": { "summary": "upsertTimeEntry", "deprecated": false, "description": "Use `upsertTimeEntry` to update an existing time entry or to insert a new time entry for an employee\n\n### When to use:\n- When an employee forgets to clock in or clock out for a shift\n- When an employee forgets to add a break in a shift\n- When the clock in or clock out time for a shift needs amending\n\n### What it does:\n- Inserts a time entry if no existing timeEntryId is provided\n- Updates an exiting time entry if a timeEntryId is provided\n- Ensures there is no overlap between inserted and updated time entries and any other shifts on the same day\n- Triggers time card recalculation in accordance with the overtime rules for the policy\n\n### Note:\n- To remove a shift entirely use the `deleteTimeEntry` API\n- Use workDate when inserting a timeEntry, and timeEntryId when updating an existing time entry", "operationId": "upsertTimeEntry", "tags": [ "TimeTracking Admin" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "userId": { "type": "string" }, "companyId": { "type": "string" }, "timeEntry": { "type": "object", "properties": { "timeEntryId": { "type": "string" }, "workDate": { "type": "string" }, "clockInTime": { "type": "string" }, "clockOutTime": { "type": "string" }, "breaks": { "type": "array", "items": { "type": "object", "properties": { "breakStart": { "type": "string" }, "breakEnd": { "type": "string" } }, "required": [ "breakStart", "breakEnd" ] } } }, "required": [ "clockInTime", "clockOutTime" ] } }, "required": [ "method", "userId", "companyId", "timeEntry" ] }, "examples": { "1": { "value": { "method": "upsertTimeEntry", "userId": "C4CA148F-F2C6-4E70-8349-57CC6DFC1C2B", "companyId": "5221FFCF-E84B-4690-B7DC-DE29D549096B", "timeEntry": { "timeEntryId": "D70A1260-A592-4A5D-B0E5-36E02AF1BC4C", "clockInTime": "9:00:00", "clockOutTime": "20:30:00", "breaks": [ { "breakStart": "12:00:00", "breakEnd": "12:45:00" }, { "breakStart": "16:00:00", "breakEnd": "16:30:00" } ] } }, "summary": "Update" }, "2": { "value": { "method": "upsertTimeEntry", "userId": "C4CA148F-F2C6-4E70-8349-57CC6DFC1C2B", "companyId": "5221FFCF-E84B-4690-B7DC-DE29D549096B", "timeEntry": { "workDate": "2026-03-22", "clockInTime": "9:00:00", "clockOutTime": "20:30:00", "breaks": [ { "breakStart": "12:00:00", "breakEnd": "12:45:00" }, { "breakStart": "16:00:00", "breakEnd": "16:30:00" } ] } }, "summary": "Insert" } } } } }, "responses": { "200": { "description": "Time entry upserted", "content": { "application/json": { "schema": { "type": "object", "properties": { "timeEntry": { "type": "object", "properties": { "timeEntryId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "timeEntryId", "status", "message" ] } }, "required": [ "timeEntry" ] }, "examples": { "1": { "summary": "Update", "value": { "timeEntry": { "timeEntryId": "D70A1260-A592-4A5D-B0E5-36E02AF1BC4C", "status": "Ready", "message": "Time entry updated successfully." } } }, "2": { "summary": "Insert", "value": { "timeEntry": { "timeEntryId": "4081DFA4-17CA-42EE-89C4-C76AA8F2BC2E", "status": "Ready", "message": "Time entry inserted successfully." } } } } } }, "headers": {} }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Time entry overlaps with existing entry: 09:00:00 - 20:30:00" } } } }, "headers": {} } }, "security": [] } }, "/adminPortal/deleteTimeEntry": { "delete": { "summary": "deleteTimeEntry", "deprecated": false, "description": "Use the `deleteTimeEntry` API when a time entry was added accidentally by an admin or employee\n\n### What it does:\n- Completely removes a time entry by its ID\n- Triggers a recalculation of the timecard in accordance with the overtime rules\n\n### Notes:\n- The time card must not be approved or synced to remove a time entry. If this is the case you must unapprove the card before continuing\n- If a time entry can be fixed rather than deleted use the `upsertTimeEntry` API", "operationId": "deleteTimeEntry", "tags": [ "TimeTracking Admin" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "timeEntryId": { "type": "string" } }, "required": [ "method", "timeEntryId" ] }, "example": { "method": "deleteTimeEntry", "timeEntryId": "8B57BE5E-D6F3-49C4-9A7A-CFBE74019C00" } } } }, "responses": { "200": { "description": "Time entry deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "timeEntry": { "type": "object", "properties": { "timeEntryId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "timeEntryId", "status", "message" ] } }, "required": [ "timeEntry" ] }, "example": { "timeEntry": { "timeEntryId": "8B57BE5E-D6F3-49C4-9A7A-CFBE74019C00", "status": "Ready", "message": "Time entry deleted successfully." } } } }, "headers": {} }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "timeEntryId is required." } } } }, "headers": {} } }, "security": [] } }, "/adminPortal/updateTimeCardApprovals": { "put": { "summary": "updateTimeCardApprovals", "deprecated": false, "description": "The `updateTimeCardApprovals` API moves timecards between the editable **new** status and **approved** so they can be synced to payroll\n\n### What it does:\n- Locks the complete time card when **isApproved: true** so the administrator or employee cannot add or update time entries\n- Unlocks the time card when **isApproved: false** so last minyte edits can be made\n- Blocks clock in and out for the employee if the timecard includes the current date\n\n### Notes:\n- Once time cards are approved they can be synced to payroll using the `syncTimeCardsToPayroll` API\n- Time cards can be unapproved from both **synced** and **approved** status so they are once again editable and corrections can be made\n- Approval status is determined by the`isApproved: true/false` fields", "operationId": "updateTimeCardApprovals", "tags": [ "TimeTracking Admin" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "payPeriodId": { "type": "string" }, "timeCardIds": { "type": "array", "items": { "type": "string" } }, "isApproved": { "type": "boolean" } }, "required": [ "method", "companyId", "payPeriodId", "timeCardIds", "isApproved" ] }, "example": { "method": "updateTimeCardApprovals", "companyId": "5221FFCF-E84B-4690-B7DC-DE29D549096B", "payPeriodId": "3EAEC271-6C06-4E17-8C3B-1C6649D534D5", "timeCardIds": [ "4DDB60ED-BC33-49FA-A589-E29FB6C4FD5C" ], "isApproved": true } } } }, "responses": { "200": { "description": "Time card approval statuses updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "timeCards": { "type": "array", "items": { "type": "object", "properties": { "timeCardId": { "type": "string" }, "userId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "timeCardId", "userId", "status", "message" ] } } }, "required": [ "timeCards" ] }, "example": { "timeCards": [ { "timeCardId": "4DDB60ED-BC33-49FA-A589-E29FB6C4FD5C", "userId": "C4CA148F-F2C6-4E70-8349-57CC6DFC1C2B", "status": "Approved", "message": "Time card approved successfully." } ] } } }, "headers": {} }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "timeCards": [ { "error": 400, "message": "Time card not approved. There are open time entries on the time card" }, { "error": 400, "message": "Invalid timeCardId" } ] } } }, "headers": {} } }, "security": [] } }, "/adminPortal/syncTimeCardsToPayroll": { "post": { "summary": "syncTimeCardsToPayroll", "deprecated": false, "description": "The `syncTimeCardsToPayroll` API imports eligible time cards into payroll.\n\n### What it does:\n- Imports standard and overtime hours for payroll processing.\n\n### Notes:\n- Time cards in `Approved` or `Synced` status are eligible for sync.", "operationId": "syncTimeCardsToPayroll", "tags": [ "TimeTracking Admin" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "payPeriodId": { "type": "string" }, "timeCardIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "method", "companyId", "payPeriodId", "timeCardIds" ] }, "example": { "method": "syncTimeCardsToPayroll", "companyId": "5221FFCF-E84B-4690-B7DC-DE29D549096B", "payPeriodId": "3EAEC271-6C06-4E17-8C3B-1C6649D534D5", "timeCardIds": [ "4DDB60ED-BC33-49FA-A589-E29FB6C4FD5C" ] } } } }, "responses": { "200": { "description": "Time cards sync processed", "content": { "application/json": { "schema": { "type": "object", "properties": { "timeCards": { "type": "array", "items": { "type": "object", "properties": { "timeCardId": { "type": "string" }, "userId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "timeCardId", "userId", "status", "message" ] } } }, "required": [ "timeCards" ] }, "example": { "timeCards": [ { "timeCardId": "4DDB60ED-BC33-49FA-A589-E29FB6C4FD5C", "userId": "C4CA148F-F2C6-4E70-8349-57CC6DFC1C2B", "status": "Synced", "message": "Synced successfully." } ] } } }, "headers": {} }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "timeCards": [ { "error": 400, "message": "Only Approved or Synced time cards can be synced to payroll" }, { "error": 400, "message": "Invalid timeCardId" } ] } } }, "headers": {} } }, "security": [] } }, "/userOnboarding/acceptTermsAndCondition": { "put": { "summary": "acceptTermsAndCondition", "deprecated": false, "description": "The `acceptTermsAndCondition` API is used to record a user's acceptance of the Terms and Conditions, which is mandatory for regulatory compliance before proceeding with any onboarding steps.\n\n### What it does:\n\n- Records user's acceptance of current Terms and Conditions\n- Enables progression to subsequent onboarding steps\n\n### Note:\n\nThis a **mandatory step** in the user onboarding flow. Users must complete this step before progressing any further.", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "acceptTermsAndCondition", "examples": [ "acceptTermsAndCondition" ], "default": "acceptTermsAndCondition", "enum": [ "acceptTermsAndCondition" ] }, "userId": { "type": "string" } }, "required": [ "method", "userId" ] }, "example": { "method": "acceptTermsAndCondition", "userId": "D34A5E5B-F8D3-4486-AF41-BE281C7E9B5B" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "userId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "userId", "status", "message" ] } }, "required": [ "user" ] }, "examples": { "1": { "summary": "Success", "value": { "user": { "userId": "D34A5E5B-F8D3-4486-AF41-BE281C7E9B5B", "status": "Ready", "message": "Terms and conditions accepted successfully." } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "Failed to accept terms and conditions." } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] } } }, "headers": {} } }, "security": [] } }, "/userOnboarding/addKycInformation": { "post": { "summary": "addKycInformation", "deprecated": false, "description": "\nThe `addKycInformation` API is used to collect essential identity information from employees as part of the KYC (Know Your Customer) process for regulatory compliance and identity validation.\n\n### What it does:\n\n- Collects essential identity data (name, DOB, SSN, address)\n- Requires all data needed for the KYC verification process\n\n### Note:\n\nThis a **mandatory step** in the user onboarding flow. Users must complete this step before proceeding with tax information (W-4) or bank account setup.", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "addKycInformation" ], "title": "addKycInformation" }, "kycInformation": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "ssn": { "type": "string", "title": "Must be 9 Digits", "examples": [ "659-89-9874" ] }, "dateOfBirth": { "type": "string", "maxLength": 10 }, "address1": { "type": "string", "maxLength": 40 }, "address2": { "type": "string", "maxLength": 40 }, "city": { "type": "string", "maxLength": 40 }, "state": { "type": "string", "title": "Enum", "maxLength": 2, "enum": [ "TX", "AK", "ND", "IL", "MA", "KS", "AS", "AL", "UT", "SD", "MI", "DC", "GA", "SC", "TN", "OK", "CO", "CA", "ME", "MO", "WY", "MD", "VT", "NM", "CT", "AZ", "WI", "VA", "WV", "NJ", "DE", "NC", "PR", "IN", "MT", "NH", "HI", "IA", "KY", "WA", "OH", "FL", "OR", "MP", "GU", "MN", "MS", "PA", "NE", "RI", "ID", "LA", "NY", "NV", "AR" ] }, "zipcode": { "type": "string", "title": "Must be Five or Nine Digits" } }, "required": [ "userId", "ssn", "dateOfBirth", "address1", "city", "state", "zipcode" ] }, "employeeRemoteLocation": { "type": "object", "properties": { "address1": { "type": "string", "maxLength": 40 }, "address2": { "type": "string", "maxLength": 40 }, "city": { "type": "string", "maxLength": 40 }, "state": { "type": "string", "title": "Enum", "maxLength": 2, "enum": [ "TX", "AK", "ND", "IL", "MA", "KS", "AS", "AL", "UT", "SD", "MI", "DC", "GA", "SC", "TN", "OK", "CO", "CA", "ME", "MO", "WY", "MD", "VT", "NM", "CT", "AZ", "WI", "VA", "WV", "NJ", "DE", "NC", "PR", "IN", "MT", "NH", "HI", "IA", "KY", "WA", "OH", "FL", "OR", "MP", "GU", "MN", "MS", "PA", "NE", "RI", "ID", "LA", "NY", "NV", "AR" ] }, "zipcode": { "type": "string", "title": "Must be Five or Nine Digits" } }, "title": "Used when work location is different", "required": [ "address1", "city", "state", "zipcode" ] } }, "required": [ "method", "kycInformation" ] }, "example": { "method": "addKycInformation", "kycInformation": { "userId": "5a2390e1-0f83-46bd-ae1c-81b30fe364e1", "ssn": "789898953", "dateOfBirth": "2000-01-01", "address1": "777 West Convention Way", "address2": "", "city": "Anaheim", "state": "CA", "zipcode": "92802" }, "userRemoteLocation": { "address1": "e", "address2": "e", "city": "e", "state": "AZ", "zipcode": "50023" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "kycInformation": { "type": "object", "properties": { "userId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "userId", "status" ], "x--orders": [ "kycInformationId", "status", "message" ] } }, "required": [ "kycInformation" ], "x--orders": [ "kycInformation" ] }, "example": { "kycInformation": { "userId": "5a2390e1-0f83-46bd-ae1c-81b30fe364e1", "status": "KYC Pending", "message": "The KYC Information for jacob king has been added successfully." } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "EmployeeId is mandatory and cannot be empty." } } } }, "headers": {} } }, "security": [] } }, "/userOnboarding/addW4Information": { "post": { "summary": "addW4Information", "deprecated": false, "description": "\nThe `addW4Information` API is used to collect federal tax withholding information from employees for accurate payroll tax calculation.\n\n### What it does:\n\n- Collects federal tax withholding data (filing status, dependents, additional withholdings)\n- Enables accurate payroll tax calculations\n\n### Note:\n\nThis is a **mandatory step** in the user onboarding flow. Federal tax information is required for all employees to ensure proper tax withholding and compliance with IRS regulations.", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "addW4Information" ], "title": "addW4Information" }, "w4Information": { "type": "object", "properties": { "userId": { "type": "string", "title": "", "format": "uuid" }, "w4FilingStatus": { "type": "string", "title": "Enum", "maxLength": 40, "enum": [ "Single", "Married filing jointly", "Head of household", "Married Qualifying widow(er)", "Married Filing Separately" ] }, "haveMultipleJob": { "type": "boolean" }, "dependents": { "type": "integer" }, "dependentsAbove18": { "type": "integer" }, "otherIncome": { "type": "integer" }, "otherDeduction": { "type": "integer" }, "extraWithholding": { "type": "integer" }, "hasMiltarySpouseExemption": { "type": "boolean" }, "stateAdditionalDeduction": { "type": "integer" }, "isNonResident": { "type": "boolean" }, "azDeductionPercent": { "type": "integer", "title": "Only added when Employee address state is Arizona" } }, "required": [ "userId", "w4FilingStatus" ], "x--orders": [ "employeeId", "w4FilingStatus", "haveMultipleJob", "dependents", "dependentsAbove18", "otherIncome", "otherDeduction", "ExtraWithholding", "HasMiltarySpouseExemption", "StateAdditionalDeduction", "IsNonResident", "AZDeductionPercent" ] } }, "required": [ "method", "w4Information" ], "x--orders": [ "method", "w4Information" ] }, "example": { "method": "addW4Information", "w4Information": { "userId": "D9363C3E-91D4-4B04-ACE4-41509B306844", "w4FilingStatus": "Head of household", "haveMultipleJob": true, "dependents": 3, "dependentsAbove18": 2, "otherIncome": 1500, "otherDeduction": 150, "extraWithholding": 10 } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "w4Information": { "type": "object", "properties": { "userId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "userId", "status" ], "x--orders": [ "w4InformationId", "status", "message" ] } }, "x--orders": [ "w4Information" ], "required": [ "w4Information" ] }, "example": { "w4Information": { "userId": "D9363C3E-91D4-4B04-ACE4-41509B306844", "status": "Ready", "message": "The W4Information for jacob king has been saved successfully." } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "EmployeeId is mandatory and cannot be empty." } } } }, "headers": {} } }, "security": [] } }, "/userOnboarding/initiateUserKyc": { "post": { "summary": "initiateUserKyc", "deprecated": false, "description": "\nThe `initiateUserKyc` API is used to start the KYC verification process to validate the employee's identity information.\n\n### What it does:\n\n- Initiates identity verification using previously submitted KYC information\n\n### Note:\n\nKyc may only be initiated after using `addKycInformation` to submit the required information for verification.", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "initiateUserKyc" ], "title": "initiateUserKyc" }, "userId": { "type": "string", "format": "uuid" } }, "required": [ "method", "userId" ] }, "example": { "method": "initiateUserKyc", "userId": "e066e305-3816-4b06-8576-50d2502be436" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "initiateKyc": { "type": "object", "properties": { "userId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "userId", "status" ] } }, "required": [ "initiateKyc" ] }, "example": { "initiateKyc": { "userId": "e066e305-3816-4b06-8576-50d2502be436", "status": "KYC Verification Initiated", "message": "The KYC Information for jacob king has been added successfully." } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid User ID: No user found with the provided ID" } } } }, "headers": {} } }, "security": [] } }, "/userOnboarding/updateKycInformation": { "put": { "summary": "updateKycInformation", "deprecated": false, "description": "\nThe `updateKycInformation` API is used to modify previously submitted identity information for employees when changes are needed.\n\n### What it does:\n\n- Updates existing KYC data (address, phone number, personal details)\n- Can update the remote work location for employees to ensure they receive the correct state tax filing\n- Requires kyc to already have been added using the `addKycInformation` API\n\n### ⚠️ Warnings:\n\n- ssn cannot be changed when the employee is `Active` since they have passed KYB. To change an employee's ssn please contact support\n- `userRemoteLocation` should only be provided if the employee is remote and works from a location which is not their home address", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "updateKycInformation" ], "title": "updateKycInformation" }, "kycInformation": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "ssn": { "type": "string", "title": "Must be 9 Digits", "examples": [ "987-89-4510" ] }, "dateOfBirth": { "type": "string", "maxLength": 10 }, "address1": { "type": "string", "maxLength": 40 }, "address2": { "type": "string", "maxLength": 40 }, "city": { "type": "string" }, "state": { "type": "string", "title": "Enum", "maxLength": 2, "enum": [ "TX", "AK", "ND", "IL", "MA", "KS", "AS", "AL", "UT", "SD", "MI", "DC", "GA", "SC", "TN", "OK", "CO", "CA", "ME", "MO", "WY", "MD", "VT", "NM", "CT", "AZ", "WI", "VA", "WV", "NJ", "DE", "NC", "PR", "IN", "MT", "NH", "HI", "IA", "KY", "WA", "OH", "FL", "OR", "MP", "GU", "MN", "MS", "PA", "NE", "RI", "ID", "LA", "NY", "NV", "AR" ] }, "zipcode": { "type": "string", "title": "Must be FIve or Nine Digits" } }, "required": [ "userId" ] }, "employeeRemoteLocation": { "type": "object", "properties": { "address1": { "type": "string", "maxLength": 40 }, "address2": { "type": "string", "maxLength": 40 }, "city": { "type": "string", "maxLength": 40 }, "state": { "type": "string", "title": "Enum", "maxLength": 2, "enum": [ "TX", "AK", "ND", "IL", "MA", "KS", "AS", "AL", "UT", "SD", "MI", "DC", "GA", "SC", "TN", "OK", "CO", "CA", "ME", "MO", "WY", "MD", "VT", "NM", "CT", "AZ", "WI", "VA", "WV", "NJ", "DE", "NC", "PR", "IN", "MT", "NH", "HI", "IA", "KY", "WA", "OH", "FL", "OR", "MP", "GU", "MN", "MS", "PA", "NE", "RI", "ID", "LA", "NY", "NV", "AR" ] }, "zipcode": { "type": "string", "title": "Must be Five or NIne Digits" } } } }, "required": [ "method", "kycInformation" ] }, "example": { "method": "updateKycInformation", "kycInformation": { "userId": "e066e305-3816-4b06-8576-50d2502be436", "ssn": "789895512", "dateOfBirth": "2000-01-01", "address1": "650 Capitol Mall", "address2": "", "city": "e", "state": "Sacramento", "zipcode": "95814" }, "userRemoteLocation": { "address1": "e", "address2": "e", "city": "e", "state": "AZ", "zipcode": "50023" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "kycInformation": { "type": "object", "properties": { "userId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "userId", "status" ], "x--orders": [ "kycInformationId", "status", "message" ] } }, "x--orders": [ "kycInformation" ] }, "examples": { "1": { "summary": "Success", "value": { "kycInformation": { "userIdId": "e066e305-3816-4b06-8576-50d2502be436", "status": "Ready", "message": "The KYCInformation has been updated successfully." } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "SSN format is not valid" } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] } } }, "headers": {} } }, "security": [] } }, "/userOnboarding/updateW4Information": { "put": { "summary": "updateW4Information", "deprecated": false, "description": "\nThe `updateW4Information` API is used to modify previously submitted federal tax withholding information for employees.", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "updateW4Information" ], "title": "updateW4Information" }, "w4Information": { "type": "object", "properties": { "userId": { "type": "string", "title": "", "format": "uuid" }, "w4FilingStatus": { "type": "string", "maxLength": 25, "enum": [ "Single", "Married filing jointly", "Head of household", "Married Qualifying widow(er)", "Married Filing Separately" ] }, "haveMultipleJob": { "type": "boolean" }, "dependents": { "type": "integer" }, "dependentsAbove18": { "type": "integer" }, "otherIncome": { "type": "integer" }, "otherDeduction": { "type": "integer" }, "extraWithholding": { "type": "integer" }, "hasMilitarySpouseExemption": { "type": "boolean" }, "stateAdditionalDeduction": { "type": "integer" }, "isNonResident": { "type": "boolean" }, "azDeductionPercent": { "type": "integer" } }, "required": [ "userId" ], "x--orders": [ "w4InformationId", "w4FilingStatus", "haveMultipleJob", "dependents", "dependentsAbove18", "otherIncome", "otherDeduction", "ExtraWithholding", "HasMiltarySpouseExemption", "StateAdditionalDeduction", "IsNonResident", "AZDeductionPercent" ] } }, "required": [ "method", "w4Information" ], "x--orders": [ "method", "w4Information" ] }, "example": { "method": "updateW4Information", "w4Information": { "userId": "e066e305-3816-4b06-8576-50d2502be436", "w4FilingStatus": "Head of household", "haveMultipleJob": true, "dependents": 3, "dependentsAbove18": 2, "otherIncome": 1500, "otherDeduction": 150, "extraWithholding": 10 } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "w4Information": { "type": "object", "properties": { "userId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "userId", "status", "message" ], "x--orders": [ "w4InformationId", "status", "message" ] } }, "required": [ "w4Information" ], "x--orders": [ "w4Information" ] }, "example": { "w4Information": { "userId": "e066e305-3816-4b06-8576-50d2502be436", "status": "Ready", "message": "The W4Information has been updated successfully." } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "EmployeeId is mandatory and cannot be empty." } } } }, "headers": {} } }, "security": [] } }, "/userOnboarding/addStateW4Information": { "post": { "summary": "addStateW4Information", "deprecated": false, "description": "\nThe `addStateW4Information` API is used to collect state-specific tax withholding information for employees in states that require additional withholding forms.\n\nTo retreive the **state specific W4 fields** use 'getStateW4FormFields` with the userId\n\n### What it does:\n\n- Collects state-specific withholding data\n- Ensures compliance with state tax regulations\n\n### Note:\n\n- This step is only required for employees in states with their own W-4 forms. Skip this step if the employee's state doesn't require additional withholding information.", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "addStateW4Information", "examples": [ "addStateW4Information" ] }, "userId": { "type": "string" }, "stateW4Information": { "type": "object", "properties": { "Additional Withholding": { "type": "string" } }, "required": [ "Additional Withholding" ] } }, "required": [ "method", "userId", "stateW4Information" ] }, "example": { "method": "addStateW4Information", "userId": "A31A0E84-3643-405A-B0E4-D229D0A194FB", "stateW4Information": { "Filing Status": "Married", "Withholding Allowance": "10", "Additional Withholding": "10.10", "NYC Withholding Allowance": "20", "NYC Additional Withholding": "14.00" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "stateW4Information": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "status", "message" ] } }, "required": [ "stateW4Information" ] }, "examples": { "1": { "summary": "Success", "value": { "stateW4Information": { "status": "Ready", "message": "The StateW4Information for Steve Jobs has been saved successfully." } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "EmployeeId is mandatory and cannot be empty." } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] } } }, "headers": {} } }, "security": [] } }, "/userOnboarding/updateStateW4Information": { "put": { "summary": "updateStateW4Information", "deprecated": false, "description": "The `updateStateW4Information` API is used to modify previously submitted state-specific tax withholding information for employees.", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "updateStateW4Information" }, "userId": { "type": "string" }, "stateW4Information": { "type": "object", "properties": { "Filing Status": { "type": "string" }, "Withholding Allowance": { "type": "string" }, "Additional Withholding": { "type": "string" }, "NYC Withholding Allowance": { "type": "string" }, "NYC Additional Withholding": { "type": "string" } } } }, "required": [ "method", "userId", "stateW4Information" ] }, "example": { "method": "updateStateW4Information", "userId": "A31A0E84-3643-405A-B0E4-D229D0A194FB", "stateW4Information": { "Filing Status": "Married", "Withholding Allowance": "11", "Additional Withholding": "10.10", "NYC Withholding Allowance": "20", "NYC Additional Withholding": "14.00" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "stateW4Information": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "status", "message" ] } }, "required": [ "stateW4Information" ] }, "examples": { "1": { "summary": "Success", "value": { "stateW4Information": { "status": "Ready", "message": "The StateW4Information for Steve Jobs has been saved successfully." } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "EmployeeId is mandatory and cannot be empty." } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] } } }, "headers": {} } }, "security": [] } }, "/userPortal/addUserBankAccount": { "post": { "summary": "addUserBankAccount", "deprecated": false, "description": "The `addUserBankAccount` API allows you to add a bank account for an employee.\n\nFor more information on employee bank account linking, refer to the [Employee Bank Account Linking guide](https://developer.rollfi.xyz/docs/EmployeeBankAccountLinking).\n\n### Account linking with Plaid\n\nUse the `linkType` field to specify the account linking method. Supported values are:\n\n- `Manual`\n- `Plaid`\n- `CustomProvider`\n\nIf `linkType` is set to `Plaid`, use the `plaidOptions` field to either:\n\n- Send the Plaid invitation via email\n- Return the Plaid link in the API response to surface within your UI\n\nThe employee must have an email address on file to receive a Plaid invitation. If the employee was onboarded without an email address, use the `updateUser` endpoint to add one.\n\n> ⚠️ **Warning:** Only one Plaid linking request can be active at a time. The employee must complete account linking using the original Plaid link before additional bank accounts can be added.\n\n### Notes\n\n- A bank account is required before employees using **Direct Deposit** can become active.\n- The first bank account is automatically assigned `payPercentage: 100`.\n- Multiple accounts may be added. After adding additional bank accounts, update allocation percentages using the `updateUserPayPercentage` API.\n- If `linkType` is omitted from the request, it currently defaults to `Manual`.\n\n---\n\n## Changing an employee's bank account\n\n- `payPercentage` is used to deactivate an existing bank account for payment purposes so a new one can be used instead.\n- To change `payPercentage`, add a secondary bank account using `addUserBankAccount`.\n- The secondary bank account can then be set to `payPercentage: 100` using the `updateUserPayPercentage` API.\n- This update pattern retains an audit record of which bank accounts have been added or paid out to.\n", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "linkType": { "type": "string", "enum": [ "Manual", "Plaid", "CustomProvider" ] }, "plaidOptions": { "type": "string" }, "userPayAccountEntity": { "type": "object", "properties": { "companyId": { "type": "string" }, "userId": { "type": "string" }, "accountNumber": { "type": "string", "maxLength": 40 }, "routingNumber": { "type": "string", "maxLength": 25 }, "bankName": { "type": "string", "maxLength": 40 }, "accountType": { "type": "string", "maxLength": 40 }, "accountName": { "type": "string", "maxLength": 40 } }, "required": [ "companyId", "userId" ] } }, "required": [ "method", "userPayAccountEntity" ] }, "examples": { "1": { "value": { "method": "addUserBankAccount", "linkType": "Manual", "userPayAccountEntity": { "companyId": "8A9B7683-8E02-494D-8422-963FD05EE785", "userId": "e066e305-3816-4b06-8576-50d2502be436", "accountNumber": "9889890989", "routingNumber": "122238242", "bankName": "Chase Bank", "accountType": "savings", "accountName": "default" } }, "summary": "Manual" }, "2": { "value": { "method": "addUserBankAccount", "linkType": "Plaid", "plaidOptions": "sendInviteByEmail", "userPayAccountEntity": { "companyId": "8A9B7683-8E02-494D-8422-963FD05EE785", "userId": "e066e305-3816-4b06-8576-50d2502be436" } }, "summary": "Plaid - Email" }, "3": { "value": { "method": "addUserBankAccount", "linkType": "Plaid", "plaidOptions": "generateURL", "userPayAccountEntity": { "companyId": "8A9B7683-8E02-494D-8422-963FD05EE785", "userId": "e066e305-3816-4b06-8576-50d2502be436" } }, "summary": "Plaid - URL link" }, "4": { "value": { "method": "addUserBankAccount", "linkType": "CustomProvider", "userPayAccountEntity": { "companyId": "8A9B7683-8E02-494D-8422-963FD05EE785", "userId": "e066e305-3816-4b06-8576-50d2502be436", "accountNumber": "9889890989", "routingNumber": "122238242", "bankName": "Chase Bank", "accountType": "savings", "accountName": "default" } }, "summary": "Custom Provider" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "userPayAccountEntity": { "type": "object", "properties": { "userPayAccountEntityId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "userPayAccountEntityId", "status", "message" ] }, "message": { "type": "string" }, "inviteSentTo": { "type": "string" }, "plaidLinkURL": { "type": "string" }, "expirationDate": { "type": "string" } } }, "examples": { "1": { "summary": "Manual", "value": { "userPayAccountEntity": { "userPayAccountEntityId": "8BE7466C-37B5-4437-8FEE-7D0B582784BD", "status": "Ready", "message": "The User PayAccount Entity has been added successfully." } } }, "2": { "summary": "Plaid - Email", "value": { "message": "Bank Linking is in progress , payPercentage will be updated , once the linking is completed.", "inviteSentTo": "testPlaidUser@mailsac.com", "expirationDate": "2023-08-18T02:08:03Z" } }, "3": { "summary": "Plaid - URL link", "value": { "message": "Bank Linking is in progress , payPercentage will be updated , once the linking is completed.", "plaidLinkURL": "https://secure.plaid.com/link/lp9o97618r1r6p93oon62nr025950ro4s3", "expirationDate": "2023-08-18T02:08:03Z" } }, "4": { "summary": "Custom Provider", "value": { "userPayAccountEntity": { "userPayAccountEntityId": "8BE7466C-37B5-4437-8FEE-7D0B582784BD", "status": "Ready", "message": "The User PayAccount Entity has been added successfully." } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "This employee does not have a saved email address" } } } }, "headers": {} } }, "security": [] } }, "/userPortal/updateUserPayPercentage": { "put": { "summary": "updateUserPayPercentage", "deprecated": false, "description": "The `updateUserPayPercentage` API is used to modify the payPercentage for an employee's bank account\n\n### What it does:\n- Changes the pay allocation if the employee has more than one bank account set up\n\n### Notes: \n- PayPercentage can only be updated for non-primary accounts\n- The payPercentage that is added/removed from the account will be balanced out by recalculating the payPercentage in the **Primary bank account**\n- A bank account with 0% allocation is considered deactivated for payroll purposes but is maintaned for audit. This account will not recieve funds when the employee is paid", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "userPayAccountEntity": { "type": "object", "properties": { "userPayAccountEntityId": { "type": "string" }, "payPercentage": { "type": "number" } }, "required": [ "userPayAccountEntityId", "payPercentage" ] } }, "required": [ "method", "userPayAccountEntity" ] }, "example": { "method": "updateUserPayPercentage", "userPayAccountEntity": { "userPayAccountEntityId": "7CB1745C-28E6-4E2F-9028-FF34F4E6A3A0", "payPercentage": 50 } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "userPayAccountEntity": { "type": "object", "properties": { "userPayAccountEntityId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "userPayAccountEntityId", "status", "message" ] } }, "required": [ "userPayAccountEntity" ] }, "example": { "userPayAccountEntity": { "userPayAccountEntityId": "00779759-E315-45A6-B30C-2EBDFA97FC4A", "status": "pending", "message": "The User pay account Entity has been updated successfully." } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid userPayAccountEntityId" } } } }, "headers": {} } }, "security": [] } }, "/userPortal/updateKycInformation": { "put": { "summary": "updateKycInformation", "deprecated": false, "description": "\nThe `updateKycInformation` API is used to modify previously submitted identity information for employees when changes are needed.\n\n### What it does:\n\n- Updates existing address and phone number KYC data", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "updateKycInformation", "examples": [ "updateKycInformation" ], "enum": [ "updateKycInformation" ] }, "kycInformation": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "address1": { "type": "string", "maxLength": 40 }, "address2": { "type": "string", "maxLength": 40 }, "city": { "type": "string", "maxLength": 40 }, "state": { "type": "string", "title": "Enum", "maxLength": 2, "enum": [ "TX", "AK", "ND", "IL", "MA", "KS", "AS", "AL", "UT", "SD", "MI", "DC", "GA", "SC", "TN", "OK", "CO", "CA", "ME", "MO", "WY", "MD", "VT", "NM", "CT", "AZ", "WI", "VA", "WV", "NJ", "DE", "NC", "PR", "IN", "MT", "NH", "HI", "IA", "KY", "WA", "OH", "FL", "OR", "MP", "GU", "MN", "MS", "PA", "NE", "RI", "ID", "LA", "NY", "NV", "AR" ] }, "zipcode": { "type": "string", "title": "Must be FIve or Nine Digits" }, "phoneNumber": { "type": "string", "title": "Must be 10 Digits", "examples": [ "9874563210" ] } }, "required": [ "userId" ], "maxProperties": 9, "x--orders": [ "employeeId", "address1", "address2", "city", "state", "zipcode", "phoneNumber" ] } }, "required": [ "method", "kycInformation" ], "x--orders": [ "method", "kycInformation" ] }, "example": { "method": "updateKycInformation", "kycInformation": { "userId": "e066e305-3816-4b06-8576-50d2502be436", "address1": "2710 English Ivy Court", "address2": "", "city": "Longwood", "state": "FL", "zipcode": "32779", "phoneNumber": "8978784102" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "kycInformation": { "type": "object", "properties": { "userId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "userId", "status" ], "x--orders": [ "employeeId", "status", "message" ] } }, "x--orders": [ "kycInformation" ], "required": [ "kycInformation" ] }, "examples": { "1": { "summary": "Success", "value": { "kycInformation": { "userId": "E066E305-3816-4B06-8576-50D2502BE436", "status": "Ready", "message": "The KYC information for Jacob King has been updated successfully." } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "EmployeeId is mandatory and cannot be empty." } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] } } }, "headers": {} } }, "security": [] } }, "/userPortal/addTimeOffRequest": { "post": { "summary": "addTimeOffRequest", "deprecated": false, "description": "The `addTimeOffRequest` API creates a PTO request for an employee.\n\n### What it does:\n\n- Creates a new request tied to a policy or assignment context.\n- Records requested date range and reason details.", "operationId": "addTimeOffRequest", "tags": [ "TimeOff User" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "method": { "type": "string", "const": "addTimeOffRequest" }, "timeOffRequest": { "type": "object", "additionalProperties": true, "properties": { "companyId": { "type": "string" }, "userId": { "type": "string", "description": "Employee user identifier." }, "policyType": { "type": "string", "description": "Optional policy type label." }, "requestDate": { "type": "string", "format": "date", "description": "Request creation date." }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "hours": { "type": "number" }, "timeOffLineItems": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "date": { "type": "string", "format": "date" }, "requestHours": { "type": "number" } }, "required": [ "date", "requestHours" ] } } } } }, "required": [ "method", "timeOffRequest" ] }, "example": { "method": "addTimeOffRequest", "timeOffRequest": { "companyId": "5221FFCF-E84B-4690-B7DC-DE29D549096B", "userId": "C4CA148F-F2C6-4E70-8349-57CC6DFC1C2B", "policyType": "Paid Time Off", "startDate": "2026-09-01", "endDate": "2026-09-03", "hours": 8, "timeOffLineItems": [ { "date": "2026-09-01", "requestHours": 8 }, { "date": "2026-09-02", "requestHours": 8 }, { "date": "2026-09-03", "requestHours": 8 } ] } } } }, "required": true }, "responses": { "200": { "description": "Request created", "content": { "application/json": { "schema": { "type": "object", "properties": { "timeOffRequest": { "type": "object", "properties": { "timeOffRequestId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "timeOffRequestId", "status", "message" ] } }, "required": [ "timeOffRequest" ] }, "example": { "timeOffRequest": { "timeOffRequestId": "F7D25F37-1B8B-4ED4-9BC2-2E4E8C3909E1", "status": "Pending", "message": "Time off request has been created successfully" } } } }, "headers": {} }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "timeOffPolicyId is required." } } } }, "headers": {} } }, "security": [] } }, "/userPortal/cancelTimeOffRequest": { "post": { "summary": "cancelTimeOffRequest", "deprecated": false, "description": "The `cancelTimeOffRequest` API cancels an existing PTO request.\n\n### What it does:\n\n- Marks an eligible request as cancelled.\n- Preserves request history while changing current lifecycle state.\n\n### Notes:\n\n- Cancellation rules depend on the request's current status.", "operationId": "cancelTimeOffRequest", "tags": [ "TimeOff User" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "method": { "type": "string", "const": "cancelTimeOffRequest" }, "timeOffRequestId": { "type": "string", "description": "Cancellation reason." }, "timeOffRequest": { "type": "object", "additionalProperties": true, "properties": { "timeOffRequestId": { "type": "string" }, "companyId": { "type": "string" }, "userId": { "type": "string" } } } } }, "example": { "method": "cancelTimeOffRequest", "timeOffRequest": { "timeOffRequestId": "A7F26D7A-FAF9-49C6-A623-C14ED3055262", "companyId": "5221FFCF-E84B-4690-B7DC-DE29D549096B", "userId": "C4CA148F-F2C6-4E70-8349-57CC6DFC1C2B" } } } }, "required": true }, "responses": { "200": { "description": "Request cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "timeOffRequest": { "type": "object", "properties": { "timeOffRequestId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" }, "hoursConsumed": { "type": "integer" }, "hoursRestored": { "type": "integer" } }, "required": [ "timeOffRequestId", "status", "message" ] } }, "required": [ "timeOffRequest" ] }, "example": { "timeOffRequest": { "timeOffRequestId": "F7D25F37-1B8B-4ED4-9BC2-2E4E8C3909E1", "status": "Cancelled", "message": "Time off request cancelled successfully", "hoursConsumed": 8, "hoursRestored": 8 } } } }, "headers": {} }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "timeOffRequestId is required." } } } }, "headers": {} }, "409": { "description": "Conflict (not approved/already cancelled)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 409, "message": "Only approved time-off requests can be cancelled." } } } }, "headers": {} } }, "security": [] } }, "/userPortal/deleteTimeOffRequest": { "delete": { "summary": "deleteTimeOffRequest", "deprecated": false, "description": "The `deleteTimeOffRequest` API soft-deletes an eligible PTO request.\n\n### What it does:\n\n- Deactivates the request record without hard deletion.\n- Prevents deleted requests from appearing in active request flows.\n\n### Notes:\n\n- Requests in protected statuses may not be deletable.", "operationId": "deleteTimeOffRequest", "tags": [ "TimeOff User" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "method": { "type": "string", "const": "deleteTimeOffRequest" }, "timeOffRequestId": { "type": "string", "description": "Cancellation reason." }, "timeOffRequest": { "type": "object", "additionalProperties": true, "properties": { "timeOffRequestId": { "type": "string" }, "companyId": { "type": "string" }, "userId": { "type": "string" } } } } }, "example": { "method": "deleteTimeOffRequest", "timeOffRequest": { "timeOffRequestId": "F7D25F37-1B8B-4ED4-9BC2-2E4E8C3909E1", "companyId": "5221FFCF-E84B-4690-B7DC-DE29D549096B", "userId": "C4CA148F-F2C6-4E70-8349-57CC6DFC1C2B" } } } }, "required": true }, "responses": { "200": { "description": "Request soft-deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "timeOffRequest": { "type": "object", "properties": { "timeOffRequestId": { "type": "string" }, "message": { "type": "string" } }, "required": [ "timeOffRequestId", "message" ] } }, "required": [ "timeOffRequest" ] }, "example": { "timeOffRequest": { "timeOffRequestId": "F7D25F37-1B8B-4ED4-9BC2-2E4E8C3909E1", "message": "Time off request deleted successfully" } } } }, "headers": {} }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid timeOffRequestId: Time-off request not found." } } } }, "headers": {} } }, "security": [] } }, "/userPortal/clockIn": { "post": { "summary": "clockIn", "deprecated": false, "description": "The `clockIn` API starts a shift for an employee.\n\n### What it does:\n- Creates an active time entry for the employee on the current local work date.\n\n### Notes:\n- Use `getEmployeeTimeTrackingStatus` to check eligibility before clock in.", "operationId": "clockIn", "tags": [ "TimeTracking User" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "userId": { "type": "string" } }, "required": [ "method", "companyId", "userId" ] }, "example": { "method": "clockIn", "companyId": "737A232C-33C3-4D15-9A76-FC99826F1B33", "userId": "F64EFF29-6516-4C1E-B14D-82F00B7EADF9" } } } }, "responses": { "200": { "description": "Clock-in recorded", "content": { "application/json": { "schema": { "title": "", "type": "object", "properties": {} }, "example": { "timeEntry": { "timeEntryId": "B17DCF4B-CE3B-45AC-8535-B132F05B6F5B", "status": "Ready", "message": "The employee is successfully clocked in." } } } }, "headers": {} }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Employee is already clocked in." } } } }, "headers": {} } }, "security": [] } }, "/userPortal/clockOut": { "put": { "summary": "clockOut", "deprecated": false, "description": "The `clockOut` API is used to start a shift for an employee\n\n### What it does:\n- Ends a time entry for the employee on the current date at their local time\n- Ends the employee's break if they are also on break when the clock out action occurs\n\n### Notes:\n- Use the `getEmployeeTimeTrackingStatus` API to determine the employee's eligibility to clock out\n- Rollfi does not currently support shifts spanning multiple days (past midnight). ClockOut should be used on the same day as clockIn", "operationId": "clockOut", "tags": [ "TimeTracking User" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "userId": { "type": "string" } }, "required": [ "method", "companyId", "userId" ] }, "example": { "method": "clockOut", "companyId": "737A232C-33C3-4D15-9A76-FC99826F1B33", "userId": "F64EFF29-6516-4C1E-B14D-82F00B7EADF9" } } } }, "responses": { "200": { "description": "Clock-out recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "timeEntry": { "type": "object", "properties": { "timeEntryId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "timeEntryId", "status", "message" ] } }, "required": [ "timeEntry" ] }, "example": { "timeEntry": { "timeEntryId": "B17DCF4B-CE3B-45AC-8535-B132F05B6F5B", "status": "Ready", "message": "The employee is successfully clocked out." } } } }, "headers": {} }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Employee is not currently clocked in." } } } }, "headers": {} } }, "security": [] } }, "/userPortal/startBreak": { "post": { "summary": "startBreak", "deprecated": false, "description": "The `startBreak` API starts a break for an employee who is currently clocked in.\n\n### What it does:\n- Opens a break segment that is excluded from worked-hour totals.\n\n### Notes:\n- Use `getEmployeeTimeTrackingStatus` to verify break eligibility.", "operationId": "startBreak", "tags": [ "TimeTracking User" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "userId": { "type": "string" }, "companyId": { "type": "string" } }, "required": [ "method", "userId", "companyId" ] }, "example": { "method": "startBreak", "userId": "C4CA148F-F2C6-4E70-8349-57CC6DFC1C2B", "companyId": "5221FFCF-E84B-4690-B7DC-DE29D549096B" } } } }, "responses": { "200": { "description": "Break started", "content": { "application/json": { "schema": { "type": "object", "properties": { "timeEntryBreak": { "type": "object", "properties": { "breakId": { "type": "string" }, "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "breakId", "success", "message" ] } }, "required": [ "timeEntryBreak" ] }, "example": { "timeEntryBreak": { "breakId": "3B6F5367-9AB1-4BCB-997D-CBCE29DC6EBE", "success": true, "message": "Break started successfully." } } } }, "headers": {} }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Employee is already on a break." } } } }, "headers": {} } }, "security": [] } }, "/userPortal/endBreak": { "put": { "summary": "endBreak", "deprecated": false, "description": "The `endBreak` API is used to end a break for an employee\n\n### What it does:\n- Ends a break for an employee so they can continue to track shift hours towards their time card totals\n\n### Notes:\n- Use the `getEmployeeTimeTrackingStatus` API to determine if the employee is currently on a break\n- Open breaks are automatically ended when a clockOut action occurs", "operationId": "endBreak", "tags": [ "TimeTracking User" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "userId": { "type": "string" }, "companyId": { "type": "string" } }, "required": [ "method", "userId", "companyId" ] }, "example": { "method": "endBreak", "userId": "C4CA148F-F2C6-4E70-8349-57CC6DFC1C2B", "companyId": "5221FFCF-E84B-4690-B7DC-DE29D549096B" } } } }, "responses": { "200": { "description": "Break ended", "content": { "application/json": { "schema": { "type": "object", "properties": { "timeEntryBreak": { "type": "object", "properties": { "breakId": { "type": "string" }, "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "breakId", "success", "message" ] } }, "required": [ "timeEntryBreak" ] }, "example": { "timeEntryBreak": { "breakId": "3B6F5367-9AB1-4BCB-997D-CBCE29DC6EBE", "success": true, "message": "Break ended successfully." } } } }, "headers": {} }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Employee is not currently on a break." } } } }, "headers": {} } }, "security": [] } }, "/benefits/addCompanyBenefits": { "post": { "summary": "addCompanyBenefits", "deprecated": false, "description": "\nThe `addCompanyBenefits` API adds benefit plans at the company level for employee enrollment.\n\n### What it does:\n\n- Creates company-wide benefit plans that employees can enroll in\n- Sets up benefit types and effective dates for the company\n- Establishes the foundation for employee benefit enrollment\n\n### Supported Benefits:\n\n- Medical\n- Dental\n- Vision\n\n### Notes:\n\n- Company benefits must be added before employees can enroll using `addEmployeeBenefits`", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "addUserBankAccount" }, "benefitCompanyElection": { "type": "object", "properties": { "companyId": { "type": "string" }, "benefitType": { "type": "string" }, "effectiveMonth": { "type": "string" } }, "required": [ "companyId", "benefitType", "effectiveMonth" ] } }, "required": [ "method", "benefitCompanyElection" ] }, "example": { "method": "addCompanyBenefits", "benefitCompanyElection": { "companyId": "0BD1DCDE-64CF-440F-A552-9C4AA356BAAF", "benefitType": "Medical", "effectiveMonth": "March 2025" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "Benefits": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "benefitType": { "type": "string" } }, "required": [ "status", "benefitType" ], "x--orders": [ "CompanyFundingSourceEntityID", "Status", "Message" ] } }, "required": [ "Benefits" ], "x--orders": [ "CompanyFundingSourceEntity" ] }, "example": { "Benefits": { "status": "Ready", "message": "The Benefits for Medical has been saved successfully.", "benefitType": "Medical" } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid companyId" } } } }, "headers": {} } }, "security": [] } }, "/benefits/addEmployeeBenefits": { "post": { "summary": "addEmployeeBenefits", "deprecated": false, "description": "\nThe `addEmployeeBenefits` API enrolls an employee in company benefit plans.\n\n### What it does:\n\n- Enrolls employees in existing company benefit plans\n- Sets employee deduction amounts and company contribution amounts per pay period\n- Establishes benefit enrollment with effective dates\n\n### Supported Benefits:\n\n- Medical\n- Dental\n- Vision\n\n### Note:\n\n- Benefits must be added using `addCompanyBenefits` before employees can enroll", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "addUserBankAccount", "examples": [ "addUserBankAccount" ], "default": "addUserBankAccount" }, "benefitEmployeeElection": { "type": "object", "properties": { "companyId": { "type": "string", "format": "uuid" }, "benefitType": { "type": "string", "maxLength": 40 }, "effectiveMonth": { "type": "string", "maxLength": 25 }, "companyContributionAmountPerPayPeriod": { "type": "number", "title": "Max allowed is 100 %" }, "employeeDeductionAmountPerPayPeriod": { "type": "number" } }, "required": [ "companyId", "benefitType", "effectiveMonth", "companyContributionAmountPerPayPeriod", "employeeDeductionAmountPerPayPeriod" ] } }, "required": [ "method", "benefitEmployeeElection" ] }, "example": { "method": "addEmployeeBenefits", "benefitEmployeeElection": { "userId": "C0378C3F-0B62-491D-9CD9-1B4CE347D8F1", "benefitType": "Medical", "effectiveMonth": "December 2024", "companyContributionAmountPerPayPeriod": 55, "employeeDeductionAmountPerPayPeriod": 25 } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "Benefits": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "benefitType": { "type": "string" } }, "required": [ "status", "benefitType" ], "x--orders": [ "CompanyFundingSourceEntityID", "Status", "Message" ] } }, "required": [ "Benefits" ], "x--orders": [ "CompanyFundingSourceEntity" ] }, "examples": { "1": { "summary": "Success", "value": { "Benefits": { "status": "Ready", "message": "The Benefits for Medical has been saved successfully.", "benefitType": "Medical" } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "Invalid userId" } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid userId" } } } }, "headers": {} } }, "security": [] } }, "/benefits/addCompanyEmployeeBenefits": { "post": { "summary": "addCompanyEmployeeBenefits", "deprecated": false, "description": "\nThe `addCompanyEmployeeBenefits` API adds company benefits with employees enrolled in a single operation. Combines `addCompanyBenefits` and `addEmployeeBenefits` into a single, efficient API call.\n\n### What it does:\n\n- Creates company-wide benefit plans and enrolls selected employees simultaneously\n- Sets up benefit types, effective dates, and employee participation together\n\n### Note:\n\n- Streamlines the process of setting up benefits and enrolling employees at the same time", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "" }, "benefitCompanyElection": { "type": "object", "properties": { "companyId": { "type": "string", "format": "uuid" }, "benefitType": { "type": "string", "maxLength": 40 }, "effectiveMonth": { "type": "string", "maxLength": 40 }, "benefitEmployeeElections": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "companyContributionAmountPerPayPeriod": { "type": "string" }, "employeeDeductionAmountPerPayPeriod": { "type": "string" } }, "required": [ "userId", "companyContributionAmountPerPayPeriod", "employeeDeductionAmountPerPayPeriod" ] } }, "required": [ "companyId", "benefitEmployeeElections" ], "maxProperties": 9, "x--orders": [ "employeeId", "address1", "address2", "city", "state", "zipcode", "phoneNumber" ] } }, "required": [ "method", "benefitCompanyElection" ], "x--orders": [ "method", "kycInformation" ] }, "example": { "method": "addCompanyEmployeeBenefits", "benefitCompanyElection": { "companyId": "9C952CC4-7652-4E2A-9303-912D876057AE", "benefitType": "Dental", "effectiveMonth": "December 2024" }, "benefitEmployeeElections": [ { "userId": "C0378C3F-0B62-491D-9CD9-1B4CE347D8F1", "companyContributionAmountPerPayPeriod": 55, "employeeDeductionAmountPerPayPeriod": 25 } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "Benefits": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "benefitType": { "type": "string" } }, "required": [ "status", "benefitType" ], "x--orders": [ "employeeId", "status", "message" ] } }, "x--orders": [ "kycInformation" ], "required": [ "Benefits" ] }, "examples": { "1": { "summary": "Success", "value": { "Benefits": { "status": "Ready", "message": "The Benefits for Dental has been saved successfully.", "benefitType": "Dental" } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "Invalid CompanyId" } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid CompanyId" } } } }, "headers": {} } }, "security": [] } }, "/benefits/updateEmployeeBenefits": { "put": { "summary": "updateEmployeeBenefits", "deprecated": false, "description": "\nThe `updateEmployeeBenefits` API modifies an employee's enrollment in specific benefit plans.\n\n### What it does:\n\n- Updates employee enrollment details for a specified company benefit plan\n- Modifies deduction amounts, company contributions, or coverage levels\n\n### Supported Benefits:\n\n- Medical\n- Dental\n- Vision\n\n### Note:\n\n- Can only update benefits for an employee who is already enrolled in the benefit plan", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "addUserBankAccount", "examples": [ "addUserBankAccount" ], "default": "addUserBankAccount" }, "benefitEmployeeElection": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "benefitType": { "type": "string", "maxLength": 40 }, "effectiveMonth": { "type": "string", "maxLength": 25 }, "companyContributionAmountPerPayPeriod": { "type": "number", "title": "Max allowed is 100 %" }, "employeeDeductionAmountPerPayPeriod": { "type": "number" } }, "required": [ "userId" ] } }, "required": [ "method", "benefitEmployeeElection" ] }, "example": { "method": "updateEmployeeBenefits", "benefitEmployeeElection": { "userId": "1C58E147-2F3F-46C1-B6B7-098B6EA94993", "benefitType": "Dental", "effectiveMonth": "January 2025", "companyContributionAmountPerPayPeriod": 75, "employeeDeductionAmountPerPayPeriod": 25 } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "Benefits": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "benefitType": { "type": "string" } }, "required": [ "status", "benefitType" ], "x--orders": [ "CompanyFundingSourceEntityID", "Status", "Message" ] } }, "required": [ "Benefits" ], "x--orders": [ "CompanyFundingSourceEntity" ] }, "examples": { "1": { "summary": "Success", "value": { "Benefits": { "status": "Ready", "message": "The Benefits for Dental has been updated successfully.", "benefitType": "Dental" } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "Invalid userId" } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid userId" } } } }, "headers": {} } }, "security": [] } }, "/benefits/removeEmployeeBenefits": { "post": { "summary": "removeEmployeeBenefits", "deprecated": false, "description": "\nThe `removeEmployeeBenefits` API removes an employee's enrollment from specific benefit plans.\n\n### What it does:\n\n- Removes employee enrollment from a specified company benefit plan\n\n### Supported Benefits:\n\n- Medical\n- Dental\n- Vision\n\n### Note:\n\n- Can only remove an employee from a benefit they have already been added to", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "addUserBankAccount", "examples": [ "addUserBankAccount" ], "default": "addUserBankAccount" }, "benefitEmployeeElection": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "benefitType": { "type": "string", "maxLength": 40 }, "effectiveMonth": { "type": "string", "maxLength": 25 } }, "required": [ "userId", "benefitType", "effectiveMonth" ] } }, "required": [ "method", "benefitEmployeeElection" ] }, "example": { "method": "removeEmployeeBenefits", "benefitEmployeeElection": { "userId": "7B0AAA79-FDC5-4630-A10E-F9A87A35C780", "benefitType": "Medical", "effectiveMonth": "December 2024" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "Benefits": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "benefitType": { "type": "string" } }, "required": [ "status", "benefitType" ], "x--orders": [ "CompanyFundingSourceEntityID", "Status", "Message" ] } }, "required": [ "Benefits" ], "x--orders": [ "CompanyFundingSourceEntity" ] }, "examples": { "1": { "summary": "Success", "value": { "Benefits": { "status": "Ready", "message": "The Benefits for Medical has been removed successfully.", "benefitType": "Medical" } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "Invalid userId" } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] } } }, "headers": {} } }, "security": [] } }, "/benefits/removeCompanyBenefits": { "post": { "summary": "removeCompanyBenefits", "deprecated": false, "description": "\nThe `removeCompanyBenefits` API removes company-wide benefit plans.\n\n### What it does:\n\n- Terminates company-level benefit offerings for specified benefit types\n- Removes the option for employee enrollment in the terminated benefit\n\n### Notes:\n\n- Removing company benefits may affect employees currently enrolled in those benefits", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "updateUserBankAccount", "examples": [ "updateUserBankAccount" ], "enum": [ "updateUserBankAccount" ] }, "benefitCompanyElection": { "type": "object", "properties": { "companyId": { "type": "string", "format": "uuid" }, "benefitType": { "type": "string", "maxLength": 40 }, "effectiveMonth": { "type": "string", "maxLength": 25 } }, "required": [ "companyId", "benefitType", "effectiveMonth" ] } }, "required": [ "method", "benefitCompanyElection" ] }, "example": { "method": "removeCompanyBenefits", "benefitCompanyElection": { "companyId": "9C952CC4-7652-4E2A-9303-912D876057AE", "benefitType": "Dental", "effectiveMonth": "March 2025" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "Benefits": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "benefitType": { "type": "string" } }, "required": [ "status", "benefitType" ], "x--orders": [ "CompanyFundingSourceEntityID", "Status", "Message" ] } }, "required": [ "Benefits" ], "x--orders": [ "CompanyFundingSourceEntity" ] }, "examples": { "1": { "summary": "Success", "value": { "Benefits": { "status": "Ready", "message": "The Benefits for Dental has been removed successfully.", "benefitType": "Dental" } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "Invalid CompanyId" } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid CompanyId" } } } }, "headers": {} } }, "security": [] } }, "/benefits/getBenefitValidEffectiveMonths": { "get": { "summary": "getBenefitValidEffectiveMonths", "deprecated": false, "description": "\nThe `getBenefitValidEffectiveMonths` API retrieves valid effective months for benefit enrollment.\n\n### What it does:\n\n- Returns available effective months when benefits can be enrolled or modified\n- Provides valid timing options for benefit enrollment periods\n\n### Notes:\n\n- Used before enrolling employees in benefits to ensure proper effective month selection\n- Helps determine when benefit changes can take effect based on company policies", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "addUserBankAccount" }, "getBenefitValidEffectiveMonths": { "type": "string" } }, "required": [ "method", "getBenefitValidEffectiveMonths" ] }, "example": { "method": "getBenefitValidEffectiveMonths" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "x--orders": [ "CompanyFundingSourceEntity" ] }, "example": [ "November 2024", "December 2024", "January 2025", "February 2025", "March 2025", "April 2025" ] } }, "headers": {} } }, "security": [] } }, "/payroll/deactivatePaySchedule": { "post": { "summary": "deactivatePaySchedule", "deprecated": false, "description": "The `deactivatePaySchedule` API Deactivates an existing pay schedule (cannot be undone).\n\n### When to Use\n- Changing pay frequency\n- Company restructuring \n- Ending contractor arrangements\n\n### Prerequisites\n- All pending payrolls must be processed\n- Cannot deactivate if active pay periods exist\n\n### Warning\n⚠️ This action is permanent. Create new pay schedule if needed.", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "paySchedule": { "type": "object", "properties": { "payScheduleId": { "type": "string", "format": "uuid" } }, "required": [ "payScheduleId" ] } }, "required": [ "method", "paySchedule" ] }, "example": { "method": "deactivatePaySchedule", "payScheduleId": "141D6357-CB56-42C9-951D-E80E10C5853A" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "PaySchedule": { "type": "object", "properties": { "PayScheduleID": { "type": "string" }, "Status": { "type": "string" }, "Message": { "type": "string" } }, "required": [ "PayScheduleID" ] } }, "required": [ "PaySchedule" ] }, "examples": { "1": { "summary": "Success", "value": { "PaySchedule": { "PayScheduleID": "1F67BE13-4E3E-4578-AC25-5660DFDE9E39", "Status": "InActive", "Message": "The PaySchedule has been deactivated successfully." } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "PayScheduleId is mandatory" } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } } }, "required": [ "error" ] } } }, "headers": {} } }, "security": [] } }, "/payroll/addPaySchedule": { "post": { "summary": "addPaySchedule", "deprecated": false, "description": "Sets up payment frequency and schedule for company employees.\n\n🔹For more in depth details on how to set up a paySchedule, take a look at the [Payroll Guide](https://rollfi-monthly-semi-monthly.mintlify.app/docs/PayrollGuide)\n\n### Compensation Frequencies\n| Frequency | Use Case |\n|-----------|----------|\n| Weekly | Hourly workers, high turnover |\n| BiWeekly | Most common for salaried |\n| SemiMonthly | 15th and last day of month |\n| Monthly | Executive/contractor payments |\n| Quarterly | Sole proprietors/Small business owners |\n\n----\n\n### Monthly and Semi-Monthly Schedules\n- To retrieve pay period startDates and endDates, use the `getMonthlySemitMonthlyPaySchedulDates` API\n- The day employees are paid in Monthly and SemiMonthly pay schedules is flexible\n- For SemiMonthly pay schedules use `payDateOptions` to set a pay day based on the distance from the payEndDate\n- For Monthly pay schedules use `payDay`\n\n### Quarterly Schedules\n- The start and end date of each payPeriod are determined by the `payDate` in the request\n- To begin a schedule including the current quarter, the payDate but be on or before Quarter end\n\n### ⚠️ Warning:\n\n- The **option** field, previously used to determine the payDay for Monthly and SemitMonthly paySchedules will be deprecated soon \n\n### Note:\n- **payDate, payDay or payDateOptions** are **required** based on the pay schedule", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "addPaySchedule" }, "paySchedule": { "type": "object", "properties": { "companyId": { "type": "string" }, "workerType": { "type": "string", "title": "Enum" }, "standardWorkingHours": { "type": "integer" }, "compensationFrequency": { "type": "string", "title": "Enum", "enum": [ "Weekly", "BiWeekly", "SemiMonthly", "Monthly" ] }, "payBeginDate": { "type": "string" }, "payDateOptions": { "type": "string", "enum": [ "7 days From payEndDate", "6 days From payEndDate", "5 days From payEndDate", "4 days From payEndDate", "3 days From payEndDate", "2 days From payEndDate", "1 days From payEndDate" ], "description": "Used for SemiMonthly payPeriods" }, "payDate": { "type": "string", "title": "", "description": "Used for Weekly, BiWeekly, Quarterly payPeriods" }, "payDay": { "type": "string", "description": "Used for Monthly payPeriods", "enum": [ "15th and last day of the month" ] }, "paymentMode": { "type": "string", "title": "Enum" } }, "required": [ "companyId", "workerType", "standardWorkingHours", "compensationFrequency", "paymentMode", "payBeginDate" ] } }, "required": [ "method", "paySchedule" ] }, "examples": { "1": { "value": { "method": "addPaySchedule", "paySchedule": { "companyId": "AFB94AFD-D9EE-4018-A718-304D43702C9C", "workerType": "1099-NEC", "standardWorkingHours": 8, "compensationFrequency": "BiWeekly", "payBeginDate": "2025-07-31", "payDate": "2025-08-04", "paymentMode": "Self-Initiated" } }, "summary": "Weekly, BiWeekly" }, "2": { "value": { "method": "addPaySchedule", "paySchedule": { "companyId": "ECF1B47E-108F-45C0-A520-6A128A727B04", "workerType": "W2", "standardWorkingHours": 8, "compensationFrequency": "SemiMonthly", "payBeginDate": "2026-02-16", "payDateOptions": "5 days From payEndDate", "paymentMode": "Automatic" } }, "summary": "SemiMonthly" }, "3": { "value": { "method": "addPaySchedule", "paySchedule": { "companyId": "ECF1B47E-108F-45C0-A520-6A128A727B04", "workerType": "W2", "standardWorkingHours": 8, "compensationFrequency": "Monthly", "payBeginDate": "2026-02-16", "payDay": "Last day of the month", "paymentMode": "Automatic" } }, "summary": "Monthly" }, "4": { "value": { "method": "addPaySchedule", "paySchedule": { "companyId": "A26B85B1-7203-4316-B087-006D0D17140C", "workerType": "1099-NEC", "compensationFrequency": "Quarterly", "paymentMode": "Automatic", "standardWorkingHours": 8, "payDate": "2026-03-17" } }, "summary": "Quarterly" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "paySchedule": { "type": "object", "properties": { "payScheduleId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "payScheduleId", "status", "message" ] } }, "required": [ "paySchedule" ] }, "examples": { "1": { "summary": "Success", "value": { "paySchedule": { "payScheduleId": "8457D59C-20B9-4B01-8B2F-7BD60C700DEB", "status": "Active", "message": "The PaySchedule for Blanda's LLC has been added successfully" } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "PayDate format is not valid" } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } } } }, "required": [ "error" ] } } }, "headers": {} } }, "security": [] } }, "/payroll/updatePaySchedule": { "put": { "summary": "updatePaySchedule", "deprecated": false, "description": "The `updatePaySchedule` endpoint allows updates to the payment mode for an active pay schedule, without having to deactivate and add a new one.\n\n### Notes:\n- `paymentMode` is required\n- Updates only the payment mode (`Automatic` or `Self-Initiated`)", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "updatePaySchedule" }, "paySchedule": { "type": "object", "properties": { "payScheduleId": { "type": "string", "format": "uuid", "description": "Preferred lookup key" }, "paymentMode": { "type": "string", "title": "Enum", "enum": [ "Automatic", "Self-Initiated" ] } }, "required": [ "paymentMode" ] } }, "required": [ "method", "paySchedule" ] }, "examples": { "1": { "value": { "method": "updatePaySchedule", "paySchedule": { "payScheduleId": "8457D59C-20B9-4B01-8B2F-7BD60C700DEB", "paymentMode": "Automatic" } }, "summary": "Update by payScheduleId" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "status", "message" ] }, "examples": { "1": { "summary": "Success", "value": { "status": "Success", "message": "The payment mode has been updated successfully." } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "examples": { "1": { "summary": "Invalid payment mode", "value": { "error": { "code": 400, "message": "Invalid payment mode" } } }, "2": { "summary": "No active schedule for company + workerType", "value": { "error": { "code": 400, "message": "No active pay schedule found for the given company and worker type" } } }, "3": { "summary": "Invalid company", "value": { "error": { "code": 400, "message": "Invalid company ID. Company does not exist." } } } } } }, "headers": {} } }, "security": [] } }, "/payroll/initiatePayroll": { "post": { "summary": "initiatePayroll", "deprecated": false, "description": "Starts payroll calculation and processing for a specific pay period.\n\n### Pre-Execution Checklist\n✅ All payroll data successfully imported, including hours, deductions, additional compensations etc.\n\n✅ Bank account verified.\n\n✅ The funding source has the required funds.\n\n✅ All employee information (addresses, tax details) up to date.\n\n### Process Flow:\n1. **Validation:** Checks all requirements\n2. **Recalculation:** Computes wages, taxes, deductions to ensure up to date numbers before payroll runs\n3. **Processing:** Executes payments, payroll is `inProcess`\n4. **Confirmation:** Sends notifications\n\n### Notes:\n- If payroll is initated before the `deadlineToRunPayroll` the payPeriod becomes `submitted` and will automatically process on the deadline.\n- If `runNow: true` is included in the request, or the date is past the `deadlineToRunPayroll` the payroll processes immediately, skipping the `submitted` status, and the payDate is brought forward. \n- If the company bank account is linked with plaid (includes balance checks) and does not have the required funds to cover payroll, the submission will be unsuccessful.\n- For more information regarding the payroll process please refer to the [Payroll Processing](https://developer.rollfi.xyz/docs/PayrollProcessing) guide.", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string", "format": "uuid" }, "payPeriodId": { "type": "string", "format": "uuid" }, "runNow": { "type": "boolean" } }, "required": [ "method", "companyId", "payPeriodId" ] }, "example": { "method": "initiatePayroll", "companyId": "8D728FCE-2993-42E0-8797-832C930506E1", "payPeriodId": "F4C96CCA-24D4-4DF4-B624-1544989F7D21", "runNow": false } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "payPeriod": { "type": "object", "properties": { "payPeriodId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "payPeriodId", "status" ], "x--orders": [ "PayPeriodId", "Status", "Message" ] } }, "required": [ "payPeriod" ], "x--orders": [ "PayPeriod" ] }, "examples": { "1": { "summary": "Success", "value": { "payPeriod": { "payPeriodId": "3b51b98b-2915-4854-b87c-f7952ef086ec", "status": "inProcess", "message": "The PayPeriod has been initiated successfully." } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "payPeriodId is mandatory and cannot be empty." } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid PayPeriodId" } } } }, "headers": {} } }, "security": [] } }, "/payroll/addSupplementalPayPeriod": { "post": { "summary": "addSupplementalPayPeriod", "deprecated": false, "description": "\nThe `addSupplementalPayPeriod` API creates a supplemental pay period for processing additional payroll outside of the regular pay schedules.\n\n### What it does:\n\n- Creates a special pay period for supplemental payroll processing (bonuses, commissions, off-cycle payments)\n- Sets up pay period dates and worker type for the supplemental payroll\n\n### Notes:\n\n- Requires pay period dates (**payBeginDate**, **payEndDate**, **payDate**)\n- Returns a **payPeriodId** for use with supplemental payroll line items", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "addSupplementalPayPeriod" ], "title": "addSupplementalPayPeriod" }, "payPeriod": { "type": "object", "properties": { "companyId": { "type": "string", "format": "uuid" }, "payPeriodType": { "type": "string", "title": "Enum", "enum": [ "Missing", "Severance", "Off-Cycle" ] }, "workerType": { "type": "string", "title": "Enum", "enum": [ "W2", "1099 -NEC" ], "maxLength": 8 }, "payBeginDate": { "type": "string", "maxLength": 10 }, "payEndDate": { "type": "string", "maxLength": 10 }, "payDate": { "type": "string", "maxLength": 10 } }, "required": [ "payPeriodType", "workerType", "payBeginDate", "payEndDate", "payDate", "companyId" ], "x--orders": [ "companyId", "payScheduleId", "payPeriodType", "workerType", "payBeginDate", "payEndDate", "payDate", "total", "readyForProcessing" ] } }, "required": [ "method", "payPeriod" ], "x--orders": [ "method", "payPeriod" ] }, "example": { "method": "addSupplementalPayPeriod", "payPeriod": { "companyId": "3c62037a-2bac-4910-839d-5c803f0d4f0a", "payPeriodType": "Missing", "workerType": "W2", "payBeginDate": "2023-11-12", "payEndDate": "2023-12-10", "payDate": "2023-12-10" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "payPeriod": { "type": "object", "properties": { "payPeriodId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "payPeriodId", "status" ], "x--orders": [ "payPeriodId", "status", "message" ] } }, "required": [ "payPeriod" ], "x--orders": [ "payPeriod" ] }, "examples": { "1": { "summary": "Success", "value": { "payPeriod": { "payPeriodId": "91384C53-089C-42E9-8CB0-59978AF46DEA", "status": "New", "message": "Supplemental PayPeriod for Prism Ltd has been saved successfully." } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "PayBeginDate should be greater than future date" } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } } }, "required": [ "error" ] } } }, "headers": {} } }, "security": [] } }, "/payroll/addSupplementalPayrollLineItem": { "post": { "summary": "addSupplementalPayrollLineItem", "deprecated": false, "description": "# addSupplementalPayrollLineItem\n\nThe `addSupplementalPayrollLineItem` API adds supplemental pay for an employee within a company.\n\n### What it does:\n\n- Adds specific payment amounts to employees outside of regular payroll processing\n- Allows one time additions for non-regular pay such as bonuses, rebates, corrections etc.\n\n### Notes:\n\n- Requires a **payPeriodId** for a supplemental or regular pay period\n- Used for processing payments outside of regular pay schedules like bonuses or corrections", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "addSupplementalPayrollLineItem" ], "title": "addSupplementalPayrollLineItem" }, "payrollLineItem": { "type": "object", "properties": { "payPeriodId": { "type": "string", "format": "uuid" }, "companyId": { "type": "string" }, "userId": { "type": "string", "format": "uuid" }, "amount": { "type": "number" } }, "required": [ "payPeriodId", "userId", "amount", "companyId" ] } }, "required": [ "method", "payrollLineItem" ] }, "example": { "method": "addSupplementalPayrollLineItem", "payrollLineItem": { "payPeriodId": "00b8b220-f329-4554-bd7b-d0ef53fc0542", "companyId": "8D728FCE-2993-42E0-8797-832C930506E1", "userId": "30da3ca7-8b39-4a3c-8ab9-050f17fbcb3b", "amount": 10 } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "payrollLineItem": { "type": "object", "properties": { "employeeId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "employeeId", "status" ] } }, "required": [ "payrollLineItem" ] }, "examples": { "1": { "summary": "Success", "value": { "payrollLineItem": { "employeeId": "30da3ca7-8b39-4a3c-8ab9-050f17fbcb3b", "status": "Ready", "message": "The PayrollLineItem for Nelson John has been saved successfully." } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "EmployeeId is mandatory and cannot be empty." } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } }, "required": [ "error" ] } } }, "headers": {} } }, "security": [] } }, "/payroll/addPayrollTaxExemption": { "post": { "summary": "addPayrollTaxExemption", "deprecated": false, "description": "Used to add a tax exemption to prevent tax withholding for particular employer and employee taxes\n\n### What it does\n\n- Prevents employee or employer taxes being calculated and withheld when the employee or employer is exempt from a specific tax\n- Allows file upload with supporting evidence for the tax exemption\n- Can be used to add exemptions to companies or to employees by adding **userId**\n\n### Notes:\n- Use the `getTaxExemptionNames` to retrieve the taxExemptions that can be applied to an employee or company\n- ExemptConfirmation is a legal confirmation that the details provided regarding the employee or employers tax exemption are correct and accurate\n- The taxName must be applicable to the employee or the employer (federal and state) to be added as an exemption\n- **exemptionEffectiveStartDate** must be today or a future date", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "userId": { "type": "string" }, "taxName": { "type": "string" }, "exemptionEffectiveStartDate": { "type": "string" }, "exemptionEffectiveEndDate": { "type": "string" }, "exemptReason": { "type": "string" }, "exemptConfirmation": { "type": "boolean" }, "fileName": { "type": "string" }, "fileBase64": { "type": "string" } }, "required": [ "method", "companyId", "taxName", "exemptionEffectiveStartDate", "exemptReason", "exemptConfirmation" ] }, "example": { "method": "addPayrollTaxExemption", "companyId": "ECF1B47E-108F-45C0-A520-6A128A727B04", "userId": "33820169-85C2-482A-BCCF-B2281419E96E", "taxName": "WA - State paid family medical leave ER", "exemptionEffectiveStartDate": "2026-02-30", "exemptionEffectiveEndDate": "2025-12-31", "exemptReason": "Employer claimed exempt on W-4", "exemptConfirmation": true, "fileName": "tax.pdf", "fileBase64": "JVBERi0xLjcNCiW1tbW1DQoxIDAgb2JqDQo8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFIvTGFuZyhlbikgL1N0cnVjdFRyZWVSb290IDIyIDAgUi9NYXJrSW5mbzw8L01hcmtlZCB0cnVlPj4vTWV0YWRhdGEgMTk3IDAgUi9WaWV3ZXJQcmVmZXJlbmNlcyAxOTggMCBSPj4NCmVuZG9iag0KMiAwIG9iag0KPDwvVHlwZS9QYWdlcy9Db3VudCAxL0tpZHNbIDMgMCBSXSA+Pg0KZW5kb2JqDQozIDAgb2JqDQo8PC9UeXBlL1BhZ2UvUGFyZW50IDIgMCBSL1Jlc291cmNlczw8L0V4dEdTdGF0ZTw8L0dTNSA1IDAgUi9HUzggOCAwIFI+Pi9YT2JqZWN0PDwvSW1hZ2U2IDYgMCBSPj4vRm9udDw8L0YxIDkgMCBSL0YyIDExIDAgUi9GMyAxMyAwIFIvRjQgMTUgMCBSPj4vUHJvY1NldFsvUERGL1RleHQvSW1hZ2VCL0ltYWdlQy9JbWFnZUldID4+L0Fubm90c1sgMjAgMCBSXSAvTWVkaWFCb3hbIDAgMCA2MTIgNzkyXSAvQ29udGVudHMgNCAwIFIvR3JvdXA8PC9UeXBlL0dyb3VwL1MvVHJhbnNwYXJlbmN5L0NTL0RldmljZVJHQj4+L1RhYnMvUy9TdHJ1Y3RQYXJlbnRzIDA+Pg0KZW5kb2JqDQo0IDAgb2JqDQo8PC9GaWx0ZXIvRmxhdGVEZWNvZGUvTGVuZ3RoIDc3Mjc+Pg0Kc3RyZWFtDQp4nL09a48bN5LfDfg/6D4cIC1u2s138xAEcGzH8V7ieGMne7jdxUHxTOxJ7JEzHucB3I+/Kj5arSar2epuycZoNBKb9SDrRRaLqwcvVp999uCbR88er+rPP1998fjRqq6MtJavfr9/78HTl2r15uP9e3XFV0/v31ux1c" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ] }, "example": { "success": true, "message": "Payroll tax exemption for company added successfully." } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid taxName 'Regular Tax'. This tax code does not belong to company 'ECF1B47E-108F-45C0-A520-6A128A727B04'. Please provide a valid tax name that exists for this company." } } } }, "headers": {} } }, "security": [] } }, "/payroll/updatePayrollTaxExemption": { "put": { "summary": "updatePayrollTaxExemption", "deprecated": false, "description": "Used to update the effectiveEndDate of a payroll tax exemption\n\n### What it does\n\n- Removes a payroll tax exemption on a specific date\n- Allows the **effectiveEndDate** to be set in the future in case the exemption expires \n- Allows both removal and extension of an exemption with changes to **effectiveEndDate**\n\n### Notes:\n- Tax exemptions are applied at/on **payDate**. If the effectiveEndDate is before the payDate the exemption is not applied to the payPeriod and vice versa\n- **exemptionEffectiveEndDate** must be today or a future date\n- Once the **exemptionEffectiveEndDate** lapses, the exemption (and any required supporting documentation) must be resubmitted with `addPayrollTaxExemption` to be reactivated\n- UserId is required when the taxName is an employee tax", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "userId": { "type": "string" }, "taxName": { "type": "string" }, "exemptionEffectiveEndDate": { "type": "string" } }, "required": [ "method", "companyId", "taxName", "exemptionEffectiveEndDate" ] }, "example": { "method": "updatePayrollTaxExemption", "companyId": "ECF1B47E-108F-45C0-A520-6A128A727B04", "userId": "33820169-85C2-482A-BCCF-B2281419E96E", "taxName": "WA - State paid family medical leave ER", "exemptionEffectiveEndDate": "2026-02-23" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ] }, "examples": { "1": { "summary": "Success", "value": { "success": true, "message": "Payroll tax exemption end date for company updated successfully." } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "exemptionEffectiveEndDate cannot be a past date. It must be current date or a future date." } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "exemptionEffectiveEndDate cannot be a past date. It must be current date or a future date." } } } }, "headers": {} } }, "security": [] } }, "/payroll/importPayrollHistory": { "post": { "summary": "importPayrollHistory", "deprecated": false, "description": "The `importPayrollHistory` API loads a completed pay period into Rollfi so legacy payroll appears in reports and year-to-date calculations.\n\n### When to use:\n- When a company onboards in the middle of the year with payroll history from another payroll provider\n- When backfilling prior pay information so employees see accurate YTD totals\n\n### Notes:\n- Either companyId or companyName is required to import data, you do not need to include both\n- Accurate reporting is required to calculate YTD totals and tax withholding information for employers and employees", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyName": { "type": "string" }, "companyId": { "type": "string" }, "payPeriod": { "type": "object", "properties": { "payPeriodType": { "type": "string" }, "workerType": { "type": "string" }, "payBeginDate": { "type": "string" }, "payEndDate": { "type": "string" }, "deadLineToRunPayroll": { "type": "string" }, "payDate": { "type": "string" }, "payrollData": { "type": "array", "items": { "type": "object", "properties": { "firstName": { "type": "string" }, "middleName": { "type": "string" }, "lastName": { "type": "string" }, "payDetails": { "type": "object", "properties": { "baseTotal": { "type": [ "number", "integer" ] }, "grossTotal": { "type": [ "number", "integer" ] }, "netTotal": { "type": [ "number", "integer" ] }, "payRate": { "type": "integer" } }, "required": [ "baseTotal", "grossTotal", "netTotal", "payRate" ] }, "additionalCompensation": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "amount": { "type": "number" } }, "required": [ "description", "amount" ] } }, "overTime": { "type": "object", "properties": { "type": { "type": "string" }, "noOfHours": { "type": "string" }, "multiplier": { "type": "string" } }, "required": [ "type", "noOfHours", "multiplier" ] }, "deductions": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "amount": { "type": "integer" } }, "required": [ "description", "amount" ] } }, "reimbursements": { "type": "array", "items": { "type": "object", "properties": { "reimbursementType": { "type": "string" }, "amount": { "type": "string" } }, "required": [ "reimbursementType", "amount" ] } }, "taxCalculationResponses": { "type": "array", "items": { "type": "object", "properties": { "taxState": { "type": "string" }, "taxName": { "type": "string" }, "taxType": { "type": "string" }, "taxAmount": { "type": [ "number", "integer" ] } }, "required": [ "taxState", "taxName", "taxType", "taxAmount" ] } } }, "required": [ "firstName", "lastName", "payDetails" ] } } }, "required": [ "payPeriodType", "workerType", "payBeginDate", "payEndDate", "deadLineToRunPayroll", "payDate", "payrollData" ] } }, "required": [ "method", "payPeriod", "companyName", "companyId" ] }, "example": { "method": "importPayrollHistory", "companyName": "paystub ytd test inc", "payPeriod": { "payPeriodType": "Regular", "workerType": "W2", "payBeginDate": "2025-04-01", "payEndDate": "2025-06-30", "deadLineToRunPayroll": "2025-06-26", "payDate": "2025-06-30", "payrollData": [ { "firstName": "Jeromy", "middleName": "", "lastName": "Asp", "payDetails": { "baseTotal": 7324.42, "grossTotal": 9284.8, "netTotal": 7529.69, "payRate": 0 }, "additionalCompensation": [ { "description": "Bonus", "amount": 1024.92 }, { "description": "Qualified Parking", "amount": 157.68 }, { "description": "Severance Pay", "amount": 777.78 } ], "overTime": [ { "type": "Comp off OT", "noOfHours": 10, "multiplier": 1 } ], "deductions": [ { "description": "403B CU 15 year Reg", "amount": 10 }, { "description": "125DC Reg", "amount": 50 } ], "reimbursements": [ { "reimbursementType": "GYM", "amount": 120 } ], "taxCalculationResponses": [ { "taxState": "FED", "taxName": "Federal Income Tax", "taxType": "Employee", "taxAmount": 604.55 }, { "taxState": "FED", "taxName": "Social Security", "taxType": "Employee", "taxAmount": 575.66 }, { "taxState": "FED", "taxName": "Medicare", "taxType": "Employee", "taxAmount": 134.63 }, { "taxState": "MN", "taxName": "Income Tax", "taxType": "Employee", "taxAmount": 440.27 }, { "taxState": "FED", "taxName": "FUTA Employer", "taxType": "Employer", "taxAmount": 10.36 }, { "taxState": "FED", "taxName": "Social Security Employer", "taxType": "Employer", "taxAmount": 575.66 }, { "taxState": "FED", "taxName": "Medicare Employer", "taxType": "Employer", "taxAmount": 134.63 }, { "taxState": "MN", "taxName": "SUI Employer", "taxType": "Employer", "taxAmount": 89.13 }, { "taxState": "MN", "taxName": "Workforce Development Fee", "taxType": "Employer", "taxAmount": 9.28 }, { "taxState": "MN", "taxName": "Additional Assessment", "taxType": "Employer", "taxAmount": 4.46 } ] }, { "firstName": "Carrie", "middleName": "", "lastName": "Fricke", "payDetails": { "baseTotal": 9000, "grossTotal": 9000, "netTotal": 7590, "payRate": 0 }, "additionalCompensation": [ { "description": "Bonus", "amount": 1024.92 }, { "description": "Qualified Parking", "amount": 157.68 } ], "overTime": [ { "type": "Comp off OT", "noOfHours": 20, "multiplier": 1 } ], "deductions": [ { "description": "403B CU 15 year Reg", "amount": 10 }, { "description": "125DC Reg", "amount": 50 } ], "reimbursements": [ { "reimbursementType": "GYM", "amount": 120 } ], "taxCalculationResponses": [ { "taxState": "FED", "taxName": "Federal Income Tax", "taxType": "Employee", "taxAmount": 570.36 }, { "taxState": "FED", "taxName": "Social Security", "taxType": "Employee", "taxAmount": 558 }, { "taxState": "FED", "taxName": "Medicare", "taxType": "Employee", "taxAmount": 130.5 }, { "taxState": "MN", "taxName": "Income Tax", "taxType": "Employee", "taxAmount": 151.14 }, { "taxState": "FED", "taxName": "FUTA Employer", "taxType": "Employer", "taxAmount": 6 }, { "taxState": "FED", "taxName": "Social Security Employer", "taxType": "Employer", "taxAmount": 558 }, { "taxState": "FED", "taxName": "Medicare Employer", "taxType": "Employer", "taxAmount": 130.5 }, { "taxState": "MN", "taxName": "SUI Employer", "taxType": "Employer", "taxAmount": 86.4 }, { "taxState": "MN", "taxName": "Workforce Development Fee", "taxType": "Employer", "taxAmount": 9 }, { "taxState": "MN", "taxName": "Additional Assessment", "taxType": "Employer", "taxAmount": 4.32 } ] } ] } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "importPayrollHistory": { "type": "object", "properties": { "payPeriodId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "payPeriodId", "status", "message" ] } }, "required": [ "importPayrollHistory" ] }, "example": { "importPayrollHistory": { "payPeriodId": "E80A9618-6046-4A5C-BC9F-44A2A0E9B9A0", "status": "Ready", "message": "Payroll history imported successfully" } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid payPeriodType: Normal" } } } }, "headers": {} } }, "security": [] } }, "/payroll/importPayrollDetailsFile": { "post": { "summary": "importPayrollDetailsFile", "deprecated": false, "description": "", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "importPayrollDetails" ], "title": "importPayrollDetails" }, "payrollDetails": { "type": "object", "properties": { "companyId": { "type": "string" }, "payPeriodId": { "type": "string" }, "fileLocation": { "type": "string" } }, "required": [ "companyId", "payPeriodId", "fileLocation" ] } }, "required": [ "method", "payrollDetails" ] }, "example": { "method": "importPayrollDetails", "payrollDetails": { "companyId": "8A9B7683-8E02-494D-8422-963FD05EE785", "payPeriodId": "3b51b98b-2915-4854-b87c-f7952ef086ec", "fileLocation": "../documents/test.csv" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "payrollDataDocument": { "type": "object", "properties": { "payrollDataDocumentId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "payrollDataDocumentId", "status" ] } }, "required": [ "payrollDataDocument" ] }, "example": { "payrollDataDocument": { "payrollDataDocumentId": "BB14339E2-7AA6-4431-9BE7-73FCFBB4EC82", "status": "Ready", "message": "Imported Payroll Data Successfully, Tax Calcualtion is in Progress " } } } }, "headers": {} } }, "security": [] } }, "/payroll/importRegularPayrollData": { "post": { "summary": "importRegularPayrollData", "deprecated": false, "description": "The `importRegularPayrollData` API imports regular payroll data for processing.\n\n### What it does:\n\n- Handles standard payroll data import for companies with consistent pay structures\n- Links users to their regular compensation package, deductions, additional compensation, and reimbursements\n- Processes regular payroll information for multiple employees at once\n- Used to import regular payroll data without differential pay rates on a user-by-user basis\n\n### Notes:\n\n- To allow `miscellaneousStateTaxes` to be imported to payroll, please refer to the `addEmployeeMiscellaneousStateTax` API\n- An employee's available miscellaneousStateTax items can be retrieved using 'getEmployeeMiscellaneousStateTaxforPayroll`\n---\n\n### Specifying Payment Method:\n- PaymentMethod can be specified for each employee in the request.\n- Defaults to the method in the user's wage details.\n- Employees can only be set to Direct Deposit if the employee has a connected bank account\n- Employees will be switched only for the pay period you are currently importing for. Subsequent pay periods will default back to the user wage\n\n---\n### Async Import:\n- This method will return before the import fully completes to prevent unecessary blocking.\n- Once the import completes a `payperiod.payperiodstatus.update` webhook is fired to indicate ther import was successful.\n- The payload is validated before returning, and while the import is ongoing. An error in the response or webhook body indicates some employee's data needs correcting and re-importing\n- For more details please see the [Payroll Processing Guide](https://developer.rollfi.xyz/docs/PayrollProcessing)", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "payPeriodId": { "type": "string" }, "payrollData": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "paymentMethod": { "type": "string", "enum": [ "Check", "Direct Deposit" ], "description": "Defaults to the method in the user's wage details. Can only be set to Direct Deposit if the employee has a connected bank account" }, "basicPay": { "type": "object", "properties": { "payHours": { "type": "integer" } }, "required": [ "payHours" ] }, "unPaidLeave": { "type": "object", "properties": { "noOfHours": { "type": "integer" } }, "required": [ "noOfHours" ] }, "retro": { "type": "object", "properties": { "amount": { "type": "integer" }, "description": { "type": "string" } }, "required": [ "amount", "description" ] }, "overTime": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "noOfHours": { "type": "number" }, "multiplier": { "type": "number" } }, "required": [ "type", "noOfHours", "multiplier" ] } }, "additionalCompensation": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "amount": { "type": "integer" } }, "required": [ "description", "amount" ] } }, "deductions": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "amount": { "type": "integer" } }, "required": [ "description", "amount" ] } }, "reimbursements": { "type": "array", "items": { "type": "object", "properties": { "reimbursementType": { "type": "string" }, "amount": { "type": "integer" } }, "required": [ "reimbursementType", "amount" ] } }, "timeOffs": { "type": "array", "items": { "type": "object", "properties": { "leaveType": { "type": "string" }, "policyType": { "type": "string" }, "hours": { "type": "number" } } } }, "miscellaneousStateTaxes": { "type": "array", "items": { "type": "object", "properties": { "stateCode": { "type": "string" }, "taxName": { "type": "string" }, "taxDetails": { "type": "array", "items": { "type": "object", "properties": { "riskClassName": { "type": "string" }, "noOfHours": { "type": "number" } } } } } } } }, "required": [ "userId", "basicPay" ] } } }, "required": [ "method", "companyId", "payPeriodId", "payrollData" ] }, "example": { "method": "importRegularPayrollData", "companyId": "3FD08599-7CBB-44C5-9243-CAD72BE36BDF", "payPeriodId": "EDD9F5D2-BED4-4337-A80C-4DDD33EDFF91", "payrollData": [ { "userId": "4DF5A79A-3735-4588-95A6-B80D15CB5A5E", "paymentMethod": "Check", "basicPay": { "payHours": 173 }, "unPaidLeave": { "noOfHours": 10 }, "retro": { "amount": 4, "description": "JK" }, "overTime": [ { "type": "Comp off OT", "noOfHours": 10, "multiplier": 1 } ], "additionalCompensation": [ { "description": "Stock Options", "amount": 500 }, { "description": "Van Pool & Transit Passes", "amount": 500 } ], "deductions": [ { "description": "403B CU 15 year Reg", "amount": 10 }, { "description": "125DC Reg", "amount": 5000 } ], "reimbursements": [ { "reimbursementType": "GYM", "amount": 120 } ], "timeOffs": [ { "leaveType": "Paid", "policyType": "Sick Leave", "hours": 20 }, { "leaveType": "Paid", "policyType": "Vacation", "hours": 10 }, { "leaveType": "Unpaid", "hours": 5 } ], "miscellaneousStateTaxes": [ { "stateCode": "WA", "taxName": "Washington L&I", "taxDetails": [ { "riskClassName": "Electrician", "noOfHours": 5 } ] } ] } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "importRegularPayrollLData": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "status", "message" ] } }, "required": [ "importRegularPayrollLData" ] }, "examples": { "1": { "summary": "Success", "value": { "importRegularPayrollLData": { "status": "Ready", "message": "Imported Payroll Data Successfully" } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "Invalid Payroll Details" } } }, "3": { "summary": "Partial Success", "value": { "status": "Ready", "message": "Payroll data imported successfully", "validationWarning": { "message": "Payroll changes not processed for 1 user(s) due to negative net pay or invalid payment method", "userIds": [ "4DF5A79A-3735-4588-95A6-B80D15CB5A5E" ] } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } }, "required": [ "error" ] } } }, "headers": {} } }, "security": [] } }, "/payroll/importRegularDifferentialPayrollData": { "post": { "summary": "importRegularDifferentialPayrollData", "deprecated": false, "description": "\nThe `importRegularDifferentialPayrollData` API adds regular differential payroll data for processing.\n\n### What it does:\n\n- Adds payroll data with differential pay rates for employees\n- Allows varying pay rate using a **payCode** for employees who operate in different roles with different pay scales\n\n### Notes:\n- To allow `miscellaneousStateTaxes` to be imported to payroll, please refer to the `addEmployeeMiscellaneousStateTax` API\n- An employee's available miscellaneousStateTax items can be retrieved using 'getEmployeeMiscellaneousStateTaxforPayroll`\n---\n\n### Specifying Payment Method:\n- PaymentMethod can be specified for each employee in the request.\n- Defaults to the method in the user's wage details.\n- Employees can only be set to Direct Deposit if the employee has a connected bank account\n- Employees will be switched only for the pay period you are currently importing for. Subsequent pay periods will default back to the user wage\n\n---\n### Async Import:\n- This method will return before the import fully completes to prevent unecessary blocking.\n- Once the import completes a `payperiod.payperiodstatus.update` webhook is fired to indicate ther import was successful.\n- The payload is validated before returning, and while the import is ongoing. An error in the response or webhook body indicates one or more employees' data needs correcting and re-importing\n- For more details please see the [Payroll Processing Guide](https://developer.rollfi.xyz/docs/PayrollProcessing)", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "payPeriodId": { "type": "string" }, "payrollData": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "paymentMethod": { "type": "string", "enum": [ "Check", "Direct Deposit" ], "description": "Defaults to the method in the user's wage details. Can only be set to Direct Deposit if the employee has a connected bank account" }, "basePay": { "type": "array", "items": { "type": "object", "properties": { "payCode": { "type": "string" }, "payRate": { "type": "integer" }, "payHours": { "type": "integer" }, "multiplier": { "type": "integer" }, "amount": { "type": "integer" } }, "required": [ "payCode", "payRate", "payHours", "amount" ] } }, "additionalCompensations": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "amount": { "type": "integer" } } } }, "deductions": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "amount": { "type": "integer" } }, "required": [ "description", "amount" ] } }, "reimbursements": { "type": "array", "items": { "type": "object", "properties": { "reimbursementType": { "type": "string" }, "amount": { "type": "integer" } }, "required": [ "reimbursementType", "amount" ] } }, "miscellaneousStateTaxes": { "type": "array", "items": { "type": "object", "properties": { "stateCode": { "type": "string" }, "taxName": { "type": "string" }, "taxDetails": { "type": "array", "items": { "type": "object", "properties": { "riskClassName": { "type": "string" }, "noOfHours": { "type": "number" } } } } } } } }, "required": [ "userId", "firstName", "lastName", "basePay" ] } } }, "required": [ "method", "companyId", "payPeriodId", "payrollData" ] }, "example": { "method": "importRegularDifferentialPayrollData", "companyId": "68D29B82-86FA-4B51-B16E-01346BD3F43B", "payPeriodId": "2412217E-E92A-46D5-A359-DF715FBF28CD", "payrollData": [ { "userId": "CE934E2C-00A5-46A1-B925-CBD97BF07AF8", "firstName": "Emmanuel", "lastName": "Golden", "paymentMethod": "Direct Deposit", "basePay": [ { "payHours": 8.75, "payRate": 0, "payCode": "BASE_PAY", "multiplier": 1, "amount": 0 }, { "payHours": 0.75, "payRate": 20, "payCode": "1151", "multiplier": 1, "amount": 15 } ], "additionalCompensations": [ { "amount": 310, "description": "Van Pool & Transit Passes" } ], "deductions": [ { "description": "Qualified Parking Sup", "amount": 120 } ], "reimbursements": [ { "reimbursementType": "GYM", "amount": 120 } ], "miscellaneousStateTaxes": [ { "stateCode": "WA", "taxName": "Washington L&I", "taxDetails": [ { "riskClassName": "Shop - Intra State Trucking", "noOfHours": 6 } ] } ] } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "importDifferntiaPayrollData": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "status", "message" ] } }, "required": [ "importDifferntiaPayrollData" ] }, "examples": { "1": { "summary": "Success", "value": { "importDifferntiaPayrollData": { "status": "Ready", "message": "Imported Differential Payroll Data Successfully" } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "Invalid Payroll Details" } } }, "3": { "summary": "Partial Success", "value": { "status": "Ready", "message": "Payroll data imported successfully", "validationWarning": { "message": "Payroll changes not processed for 1 user(s) due to negative net pay or invalid payment method", "userIds": [ "4DF5A79A-3735-4588-95A6-B80D15CB5A5E" ] } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code" ] } }, "required": [ "error" ] } } }, "headers": {} } }, "security": [] } }, "/payroll/importSupplementalPayrollData": { "post": { "summary": "importSupplementalPayrollData", "deprecated": false, "description": "", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "payPeriodId": { "type": "string" }, "payrollData": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "amount": { "type": "integer" }, "retro": { "type": "object", "properties": { "amount": { "type": "integer" }, "description": { "type": "string" } }, "required": [ "amount", "description" ] }, "overTime": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "noOfHours": { "type": "integer" }, "multiplier": { "type": "integer" } }, "required": [ "type", "noOfHours", "multiplier" ] } }, "additionalCompensation": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "amount": { "type": "integer" } }, "required": [ "description", "amount" ] } }, "deductions": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "amount": { "type": "integer" } }, "required": [ "description", "amount" ] } }, "reimbursements": { "type": "array", "items": { "type": "object", "properties": { "reimbursementType": { "type": "string" }, "amount": { "type": "integer" } }, "required": [ "reimbursementType", "amount" ] } }, "timeOffs": { "type": "array", "items": { "type": "object", "properties": { "leaveType": { "type": "string" }, "hours": { "type": "integer" } }, "required": [ "leaveType", "hours" ] } }, "miscellaneousStateTaxes": { "type": "array", "items": { "type": "object", "properties": { "stateCode": { "type": "string" }, "taxName": { "type": "string" }, "taxDetails": { "type": "array", "items": { "type": "object", "properties": { "riskClassName": { "type": "string" }, "noOfHours": { "type": "integer" } }, "required": [ "riskClassName", "noOfHours" ] } } }, "required": [ "stateCode", "taxName", "taxDetails" ] } } }, "required": [ "userId" ] } } }, "required": [ "method", "companyId", "payPeriodId", "payrollData" ] }, "example": { "method": "importSupplementalPayrollData", "companyId": "EB45E206-5E50-4079-8B41-04C05E4C5338", "payPeriodId": "769088C2-2A5A-4846-8C66-5AB88D0795BA", "payrollData": [ { "userId": "49720D41-693D-435B-982F-7D0C47ECAF61", "amount": 10000, "retro": { "amount": 1, "description": "JK" }, "overTime": [ { "type": "Comp off OT", "noOfHours": 10, "multiplier": 1 } ], "additionalCompensation": [ { "description": "Stock Options", "amount": 2 }, { "description": "Van Pool & Transit Passes", "amount": 3 } ], "deductions": [ { "description": "403B CU 15 year Reg", "amount": 4 }, { "description": "125DC Reg", "amount": 5 } ], "reimbursements": [ { "reimbursementType": "GYM", "amount": 6 } ], "timeOffs": [ { "leaveType": "Unpaid", "hours": 8 } ], "miscellaneousStateTaxes": [ { "stateCode": "WA", "taxName": "Washington L&I", "taxDetails": [ { "riskClassName": "Electrician", "noOfHours": 5 } ] } ] } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "importSupplementalPayrollData": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "status", "message" ] } }, "required": [ "importSupplementalPayrollData" ] }, "example": { "importSupplementalPayrollData": { "status": "Ready", "message": "Payroll data imported successfully" } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "importSupplementalPayrollData": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "validationWarning": { "type": "object", "properties": { "message": { "type": "string" }, "userIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "userIds" ] } }, "required": [ "status", "message", "validationWarning" ] } }, "required": [ "importSupplementalPayrollData" ] }, "example": { "importSupplementalPayrollData": { "status": "Error", "message": "Payroll data import failed - all employees have negative net pay", "validationWarning": { "message": "Payroll changes not processed for 1 user(s) due to negative net pay", "userIds": [ "49720D41-693D-435B-982F-7D0C47ECAF61" ] } } } } }, "headers": {} } }, "security": [] } }, "/payroll/removeMiscellaneousStateTaxes": { "post": { "summary": "removeMiscellaneousStateTaxes", "deprecated": false, "description": "", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "payPeriodId": { "type": "string" }, "payrollData": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "amount": { "type": "integer" }, "retro": { "type": "object", "properties": { "amount": { "type": "integer" }, "description": { "type": "string" } }, "required": [ "amount", "description" ] }, "overTime": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "noOfHours": { "type": "integer" }, "multiplier": { "type": "integer" } }, "required": [ "type", "noOfHours", "multiplier" ] } }, "additionalCompensation": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "amount": { "type": "integer" } }, "required": [ "description", "amount" ] } }, "deductions": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "amount": { "type": "integer" } }, "required": [ "description", "amount" ] } }, "reimbursements": { "type": "array", "items": { "type": "object", "properties": { "reimbursementType": { "type": "string" }, "amount": { "type": "integer" } }, "required": [ "reimbursementType", "amount" ] } }, "timeOffs": { "type": "array", "items": { "type": "object", "properties": { "leaveType": { "type": "string" }, "hours": { "type": "integer" } }, "required": [ "leaveType", "hours" ] } }, "miscellaneousStateTaxes": { "type": "array", "items": { "type": "object", "properties": { "stateCode": { "type": "string" }, "taxName": { "type": "string" }, "taxDetails": { "type": "array", "items": { "type": "object", "properties": { "riskClassName": { "type": "string" }, "noOfHours": { "type": "integer" } }, "required": [ "riskClassName", "noOfHours" ] } } }, "required": [ "stateCode", "taxName", "taxDetails" ] } } }, "required": [ "userId" ] } } }, "required": [ "method", "companyId", "payPeriodId", "payrollData" ] }, "example": { "method": "importSupplementalPayrollData", "companyId": "EB45E206-5E50-4079-8B41-04C05E4C5338", "payPeriodId": "769088C2-2A5A-4846-8C66-5AB88D0795BA", "payrollData": [ { "userId": "49720D41-693D-435B-982F-7D0C47ECAF61", "amount": 10000, "retro": { "amount": 1, "description": "JK" }, "overTime": [ { "type": "Comp off OT", "noOfHours": 10, "multiplier": 1 } ], "additionalCompensation": [ { "description": "Stock Options", "amount": 2 }, { "description": "Van Pool & Transit Passes", "amount": 3 } ], "deductions": [ { "description": "403B CU 15 year Reg", "amount": 4 }, { "description": "125DC Reg", "amount": 5 } ], "reimbursements": [ { "reimbursementType": "GYM", "amount": 6 } ], "timeOffs": [ { "leaveType": "Unpaid", "hours": 8 } ], "miscellaneousStateTaxes": [ { "stateCode": "WA", "taxName": "Washington L&I", "taxDetails": [ { "riskClassName": "Electrician", "noOfHours": 5 } ] } ] } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "importSupplementalPayrollData": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "status", "message" ] } }, "required": [ "importSupplementalPayrollData" ] }, "example": { "importSupplementalPayrollData": { "status": "Ready", "message": "Payroll data imported successfully" } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "importSupplementalPayrollData": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "validationWarning": { "type": "object", "properties": { "message": { "type": "string" }, "userIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "userIds" ] } }, "required": [ "status", "message", "validationWarning" ] } }, "required": [ "importSupplementalPayrollData" ] }, "example": { "importSupplementalPayrollData": { "status": "Error", "message": "Payroll data import failed - all employees have negative net pay", "validationWarning": { "message": "Payroll changes not processed for 1 user(s) due to negative net pay", "userIds": [ "49720D41-693D-435B-982F-7D0C47ECAF61" ] } } } } }, "headers": {} } }, "security": [] } }, "/payroll/removeOvertime": { "post": { "summary": "removeOvertime", "deprecated": false, "description": "The `removeOvertime` API is used to remove overtime entries for an employee in a pay period.\n\n### When to use:\n- When correcting overtime mistakes before payroll submission\n\n### Notes:\n- Pay period must be in an editable state (see the `PayrollProcessing` guide)\n- overtimeType can be used to remove specific overtimes for a user\n- Automatically updates earnings calculations after removal", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "payPeriodId": { "type": "string" }, "userId": { "type": "string" }, "overtimeType": { "type": "string" } }, "required": [ "method", "companyId", "payPeriodId", "userId" ] }, "example": { "method": "removeOvertime", "companyId": "F59AE5EA-BE39-4120-A11E-DA2610D866CA", "payPeriodId": "382005A7-7B3E-4787-9B2B-2A3BE1767D7B", "userId": "A34C2BA9-900D-46B8-A297-644F82D68E29", "overtimeType": "Comp off OT" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "overtimeRemoval": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "status", "message" ] } }, "required": [ "overtimeRemoval" ] }, "examples": { "1": { "summary": "Success", "value": { "overtimeRemoval": { "status": "Success", "message": "Comp off OT have been removed successfully." } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "PayScheduleId is mandatory" } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } } }, "required": [ "error" ] } } }, "headers": {} } }, "security": [] } }, "/payroll/removeDeductions": { "post": { "summary": "removeDeductions", "deprecated": false, "description": "The `removeDeductions` API is used to remove deduction entries for an employee in a pay period.\n\n### When to use:\n- When correcting deduction mistakes before payroll submission\n- When removing specific deduction types (401k, health insurance, etc.)\n\n### Notes:\n- Pay period must be in an editable state (see the 'Payroll Processing` guide)\n- deductionDescription can be included to remove specific deductions for a user\n- Automatically updates earnings calculations after removal", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "payPeriodId": { "type": "string" }, "userId": { "type": "string" }, "deductionDescription": { "type": "string" } }, "required": [ "method", "companyId", "payPeriodId", "userId" ] }, "example": { "method": "removeDeductions", "companyId": "3A08507F-E78B-4ABF-98D8-87D382E7CE14", "payPeriodId": "43CCBBDF-8CF3-472E-874D-888E7911BB1F", "userId": "5F45CFBA-4AED-41AF-B334-E02D23BA17AE", "deductionDescription": "125DC Reg" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "removeDeductionOnly": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "status", "message" ] } }, "required": [ "removeDeductionOnly" ] }, "examples": { "1": { "summary": "Success", "value": { "removeDeductionOnly": { "status": "Success", "message": "125DC Reg deduction has been removed successfully." } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "userId is mandatory" } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "UserId is mandatory" } } } }, "headers": {} } }, "security": [] } }, "/payroll/removeAdditionalCompensations": { "post": { "summary": "removeAdditionalCompensations", "deprecated": false, "description": "The `removeAdditionalCompensations` API is used to remove additional compensation entries for an employee in a pay period.\n\n### When to use:\n- When correcting additional compensation mistakes before payroll submission\n- When removing specific compensation types (bonuses, commissions, etc.)\n\n### Notes:\n- Pay period must be in an editable state (see the 'Payroll Processing` guide)\n- All additionalCompensations are removed if compensationDescription is not included in the request\n- Automatically updates earnings calculations after removal", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "payPeriodId": { "type": "string" }, "userId": { "type": "string" }, "compensationDescription": { "type": "string" } }, "required": [ "method", "companyId", "payPeriodId", "userId" ] }, "example": { "method": "removeAdditionalCompensations", "companyId": "3A08507F-E78B-4ABF-98D8-87D382E7CE14", "payPeriodId": "43CCBBDF-8CF3-472E-874D-888E7911BB1F", "userId": "5F45CFBA-4AED-41AF-B334-E02D23BA17AE", "compensationDescription": "Bonus" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "removeAdditionalCompensationOnly": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "status", "message" ] } }, "required": [ "removeAdditionalCompensationOnly" ] }, "examples": { "1": { "summary": "Example 1", "value": { "removeAdditionalCompensationOnly": { "status": "Success", "message": "Bonus additional compensation has been removed successfully." } } }, "2": { "summary": "Example 1", "value": { "error": { "code": 400, "message": "UserId is mandatory" } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "UserId is mandatory" } } } }, "headers": {} } }, "security": [] } }, "/payroll/removeReimbursements": { "post": { "summary": "removeReimbursements", "deprecated": false, "description": "The `removeReimbursements` API is used to remove reimbursement entries from an employee in a payPeriod.\n\n### When to use:\n- When correcting reimbursement mistakes before payroll submission\n- When removing specific reimbursement types (travel, meals, etc.)\n\n### Notes:\n- Pay period must be in an editable state (see the 'Payroll Processing` guide)\n- ReimbursementType can be used to remove a specific reimbursement\n- Automatically updates earnings calculations after removal", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "payPeriodId": { "type": "string" }, "userId": { "type": "string" }, "reimbursementType": { "type": "string" } }, "required": [ "method", "companyId", "payPeriodId", "userId" ] }, "example": { "method": "removeReimbursements", "companyId": "3A08507F-E78B-4ABF-98D8-87D382E7CE14", "payPeriodId": "505529F2-9AAF-43EB-8D2A-04852B1E4687", "userId": "5F45CFBA-4AED-41AF-B334-E02D23BA17AE", "reimbursementType": "Gym" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "removeReimbursementOnly": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "status", "message" ] } }, "required": [ "removeReimbursementOnly" ] }, "example": { "removeReimbursementOnly": { "status": "Success", "message": "GYM reimbursement has been removed successfully." } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "UserId is mandatory" } } } }, "headers": {} } }, "security": [] } }, "/payroll/addPayrollLineItemTaxAdjustments": { "post": { "summary": "addPayrollLineItemTaxAdjustments", "deprecated": false, "description": "The `addPayrollLineItemTaxAdjustments ` API is used to add tax adjustments when the calculated taxes are incorrect. \n\n### What it does:\n- Overwrites the existing tax with the specified amount\n\n### When to use:\n- For complex cases where the generic tax calculations do not produce an an accurate withholding amount\n- When the employee has previosuly over or under-withheld specific taxes\n\n### Notes:\n- Use the `getAllowedTaxAdjustmentsList` API to retrieve the allowed taxNames\n- Employees must be active within the pay period sent in the request to have tax adjustments added\n- Allowed tax adjustments vary from employee to employee", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "payPeriodId": { "type": "string" }, "employeeId": { "type": "string" }, "taxAdjustments": { "type": "array", "items": { "type": "object", "properties": { "taxName": { "type": "string" }, "amount": { "type": "integer" } }, "required": [ "taxName", "amount" ] } } }, "required": [ "method", "companyId", "payPeriodId", "employeeId", "taxAdjustments" ] }, "example": { "method": "addPayrollLineItemTaxAdjustments", "companyId": "3A08507F-E78B-4ABF-98D8-87D382E7CE14", "payPeriodId": "3C068DE4-038F-4874-B99B-4AFD7CB39351", "employeeId": "BA445FB2-A3CA-43B7-BB8A-399BDE85486C", "taxAdjustments": [ { "taxName": "Federal Withholding Tax", "amount": 45 } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ] }, "example": { "success": true, "message": "Tax adjustment added successfully" } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "companyId is mandatory" } } } }, "headers": {} } }, "security": [] } }, "/payroll/updatePayrollLineItemTaxAdjustment": { "put": { "summary": "updatePayrollLineItemTaxAdjustment", "deprecated": false, "description": "The `updatePayrollLineItemTaxAdjustment ` API is used to correct a tax adjustment that has been added to an employee for a pay period\n\n### When to use:\n- When correcting tax adjustment mistakes before payroll submission\n\n### Notes:\n- The employee must have a tax adjustment applied in the specified pay period with the given `taxName`\n- **Amount** overwrites the existing calculated tax value entirely, it does not subtract", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "payPeriodId": { "type": "string" }, "employeeId": { "type": "string" }, "taxName": { "type": "string" }, "amount": { "type": "integer" } }, "required": [ "method", "companyId", "payPeriodId", "employeeId", "taxName", "amount" ] }, "example": { "method": "updatePayrollLineItemTaxAdjustment", "companyId": "C2019899-9EEF-49F7-9B51-70744AFAFE61", "payPeriodId": "9BF440AF-9BE8-49B7-8F5E-0673E35CB5B3", "employeeId": "91B2952B-664E-42D2-B3AA-CCAFC9CE00A6", "taxName": "Federal Withholding Tax", "amount": 55 } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ] }, "example": { "success": true, "message": "Tax adjustment updated successfully" } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } } }, "required": [ "error" ] }, "example": { "error": { "code": 404, "message": "Tax adjustment not found for the specified parameters. Please ensure the tax adjustment exists before attempting to update." } } } }, "headers": {} } }, "security": [] } }, "/payroll/removePayrollLineItemTaxAdjustment": { "post": { "summary": "removePayrollLineItemTaxAdjustment", "deprecated": false, "description": "The `removePayrollLineItemTaxAdjustment` API is used to remove tax adjustments that have been applied to an employee for a pay period.\n\n### When to use:\n- When a tax adjustment is no longer necessary\n- When a tax adjustment has been incorrectly added to an employee or the wrong type `(taxName)` has been added ", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "payPeriodId": { "type": "string" }, "employeeId": { "type": "string" }, "taxName": { "type": "string" } }, "required": [ "method", "companyId", "payPeriodId", "employeeId", "taxName" ] }, "example": { "method": "removePayrollLineItemTaxAdjustment", "companyId": "3A08507F-E78B-4ABF-98D8-87D382E7CE14", "payPeriodId": "3C068DE4-038F-4874-B99B-4AFD7CB39351", "employeeId": "BA445FB2-A3CA-43B7-BB8A-399BDE85486C", "taxName": "Federal Withholding Tax" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ] }, "example": { "success": true, "message": "Tax adjustment removed successfully" } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "companyId is mandatory" } } } }, "headers": {} } }, "security": [] } }, "/payroll/removeUsersFromSupplementalPayPeriod": { "post": { "summary": "removeUsersFromSupplementalPayPeriod", "deprecated": false, "description": "The `removeUsersFromSupplementalPayPeriod` API is used to remove employees from a supplemental pay period after they have been added.\n\n### When to use:\n- When correcting supplemental payroll mistakes before submission\n- When removing accidental bonus or adjustment entries\n\n### Notes:\n- Cannot remove all employees - at least one must remain\n- If you wish to remove all employees, instead use the `skipPayPeriod` API.", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "payPeriodId": { "type": "string" }, "payrollLineItems": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "reason": { "description": "optional", "type": "string" } }, "required": [ "userId" ] } } }, "required": [ "method", "companyId", "payPeriodId", "payrollLineItems" ] }, "example": { "method": "removeUsersFromSupplementalPayPeriod", "companyId": "C8D57032-BF6F-4510-AA41-08A358365531", "payPeriodId": "4083B766-8F3A-4A23-ABB7-FB67FA1F97D3", "payrollLineItems": [ { "userId": "7DDB8A83-29D5-4454-9467-53CC80307139", "reason": "" } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "payrollLineItems": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "userId", "message" ] } } }, "required": [ "payrollLineItems" ] }, "example": { "payrollLineItems": [ { "userId": "7DDB8A83-29D5-4454-9467-53CC80307139", "status": "Removed", "message": "The PayrollLineItem for Const Jonas has been removed successfully." } ] } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "UserId is mandatory" } } } }, "headers": {} } }, "security": [] } }, "/payroll/addUsersToSupplementalPayPeriod": { "post": { "summary": "addUsersToSupplementalPayPeriod", "deprecated": false, "description": "The `addUsersToSupplementalPayPeriod` API is used to add employees to a supplemental pay period for bonuses, commissions, or adjustments.\n\n### When to use:\n- When issuing bonuses, commissions, or one-time payments\n- When processing termination payouts outside regular payroll\n\n### Note:\n- To create a supplemental pay period use the `addSupplementalPayPeriod` API", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "payPeriodId": { "type": "string" }, "payrollLineItems": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "amount": { "type": "integer" }, "paymentMethod": { "type": "string" } }, "required": [ "userId", "amount", "paymentMethod" ] } } }, "required": [ "method", "companyId", "payPeriodId", "payrollLineItems" ] }, "example": { "method": "addUsersToSupplementalPayPeriod", "companyId": "C8D57032-BF6F-4510-AA41-08A358365531", "payPeriodId": "4083B766-8F3A-4A23-ABB7-FB67FA1F97D3", "payrollLineItems": [ { "userId": "7DDB8A83-29D5-4454-9467-53CC80307139", "amount": 1000, "paymentMethod": "Check" }, { "userId": "123DA511-5970-4C2F-AF7E-5C0FB11D23A3", "amount": 1500, "paymentMethod": "Direct Deposit" } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "payrollLineItems": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "userId", "status", "message" ] } } }, "required": [ "payrollLineItems" ] }, "examples": { "1": { "summary": "Success", "value": { "payrollLineItems": [ { "userId": "7DDB8A83-29D5-4454-9467-53CC80307139", "status": "Ready", "message": "The PayrollLineItem for Const Jonas has been saved successfully." }, { "userId": "123DA511-5970-4C2F-AF7E-5C0FB11D23A3", "status": "Ready", "message": "The PayrollLineItem for Celina Gos has been saved successfully." } ] } }, "2": { "summary": "Example 1", "value": { "error": { "code": 400, "message": "Invalid userId" } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "invalid UserId" } } } }, "headers": {} } }, "security": [] } }, "/payroll/editUsersOfSupplementalPayPeriod": { "put": { "summary": "editUsersOfSupplementalPayPeriod", "deprecated": false, "description": "The `editUsersOfSupplementalPayPeriod` API is used to modify high level payroll details for employees\n\n### When to use:\n- When correcting payment amounts before payroll submission\n- When changing payment methods for existing supplemental payroll entries\n\n### Notes:\n- Automatically recalculates taxes and net totals\n- Payment method can only be changed to `Direct Deposit` if the user in the payroll is set up with a bank account", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "payPeriodId": { "type": "string" }, "payrollLineItems": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "amount": { "type": "integer" }, "paymentMethod": { "type": "string" } }, "required": [ "userId", "amount", "paymentMethod" ] } } }, "required": [ "method", "companyId", "payPeriodId", "payrollLineItems" ] }, "example": { "method": "editUsersOfSupplementalPayPeriod", "companyId": "C8D57032-BF6F-4510-AA41-08A358365531", "payPeriodId": "4083B766-8F3A-4A23-ABB7-FB67FA1F97D3", "payrollLineItems": [ { "userId": "123DA511-5970-4C2F-AF7E-5C0FB11D23A3", "amount": 2000, "paymentMethod": "Check" } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "payrollLineItems": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "userId", "status", "message" ] } } }, "required": [ "payrollLineItems" ] }, "examples": { "1": { "summary": "Success", "value": { "payrollLineItems": [ { "userId": "123DA511-5970-4C2F-AF7E-5C0FB11D23A3", "status": "Updated", "message": "The PayrollLineItem for Celina Gos has been updated successfully." } ] } }, "2": { "summary": "Example 1", "value": { "error": { "code": 400, "message": "PayPeriodId is mandatory" } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "PayPeriodId is mandatory" } } } }, "headers": {} } }, "security": [] } }, "/payroll/removeUsersFromRegularPayPeriod": { "post": { "summary": "removeUsersFromRegularPayPeriod", "deprecated": false, "description": "The `removeUsersFromRegularPayPeriod` API is used to remove employees from a regular pay period due to many different circumstances\n\n### When to use:\n- When there are employee terminations mid-pay period that need to be reflected in payroll\n- When payroll corrections are needed to fix accidental additions before payroll processing\n\n### Notes:\n- Cannot remove all employees - at least one must remain in the pay period\n- In the event that all employees need to be removed from a payroll use the `skipPayPeriod` API", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "payPeriodId": { "type": "string" }, "payrollLineItems": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "reason": { "description": "optional", "type": "string" } }, "required": [ "userId" ] } } }, "required": [ "method", "companyId", "payPeriodId", "payrollLineItems" ] }, "example": { "method": "removeUsersFromRegularPayPeriod", "companyId": "C8D57032-BF6F-4510-AA41-08A358365531", "payPeriodId": "81A0AE81-F817-4012-B058-46B2C0B9B72C", "payrollLineItems": [ { "userId": "BEC0E358-C9F5-4FEA-AED3-6A25C205F599", "reason": "sabatical vacation" } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "payrollLineItems": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "userId", "status", "message" ] } } }, "required": [ "payrollLineItems" ] }, "examples": { "1": { "summary": "Success", "value": { "payrollLineItems": [ { "userId": "BEC0E358-C9F5-4FEA-AED3-6A25C205F599", "status": "Removed", "message": "The PayrollLineItem for Brendon Mcln has been removed successfully." } ] } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "PayPeriodId is mandatory" } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "PayPeriodId is mandatory" } } } }, "headers": {} } }, "security": [] } }, "/payroll/addUsersToRegularPayPeriod": { "post": { "summary": "addUsersToRegularPayPeriod", "deprecated": false, "description": "The `addUsersToRegularPayPeriod` API is used to add employees to an existing regular pay period in the rollfi system\n\n### Notes:\n- This API can be used when an employee was removed and needs re-adding to a pay period\n- Only works with 'Regular' pay period types, not supplemental pay periods", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "payPeriodId": { "type": "string" }, "payrollLineItems": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "paymentMethod": { "type": "string" } }, "required": [ "userId", "paymentMethod" ] } } }, "required": [ "method", "companyId", "payPeriodId", "payrollLineItems" ] }, "example": { "method": "addUsersToRegularPayPeriod", "companyId": "C8D57032-BF6F-4510-AA41-08A358365531", "payPeriodId": "81A0AE81-F817-4012-B058-46B2C0B9B72C", "payrollLineItems": [ { "userId": "BEC0E358-C9F5-4FEA-AED3-6A25C205F599", "paymentMethod": "Check" } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "payrollLineItems": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "userId", "status", "message" ] } } }, "required": [ "payrollLineItems" ] }, "examples": { "1": { "summary": "Success", "value": { "payrollLineItems": [ { "userId": "BEC0E358-C9F5-4FEA-AED3-6A25C205F599", "status": "Ready", "message": "The PayrollLineItem for Brendon Mcln has been saved successfully." } ] } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "PayPeriodId is mandatory" } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "PayPeriodId is mandatory" } } } }, "headers": {} } }, "security": [] } }, "/payroll/addSupplementalPayPeriodWithLineItems": { "post": { "summary": "addSupplementalPayPeriodWithLineItems", "deprecated": false, "description": "The `addSupplementalPayPeriodWithLineItems ` API is used to fully import a supplemental payPeriod to the rollfi system\n\n### Notes:\n- This API is used when all the data for a supplemental payPeriod, including individual pay items, is readily available\n- If you do not have access to the lineItem data at the time of import use `addSupplementalPayPeriod` and `addSupplementalPayrollLineItem` to achieve the same results", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "payPeriod": { "type": "object", "properties": { "companyId": { "type": "string", "format": "uuid" }, "payPeriodType": { "type": "string", "enum": [ "Missing", "Severance", "Off-Cycle" ] }, "workerType": { "type": "string", "enum": [ "W2", "1099-NEC" ] }, "payBeginDate": { "type": "string", "maxLength": 10 }, "payEndDate": { "type": "string", "maxLength": 10 }, "payDate": { "type": "string", "maxLength": 10 }, "payrollLineItem": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "amount": { "type": "number" }, "paymentMethod": { "type": "string" } }, "required": [ "userId", "amount" ] } } }, "required": [ "companyId", "payPeriodType", "workerType", "payBeginDate", "payEndDate", "payDate", "payrollLineItem" ] } }, "required": [ "method", "payPeriod" ] }, "example": { "method": "addSupplementalPayPeriodWithLineItems", "payPeriod": { "companyId": "C8D57032-BF6F-4510-AA41-08A358365531", "payPeriodType": "Off-Cycle", "workerType": "W2", "payBeginDate": "2024-01-15", "payEndDate": "2024-01-15", "payDate": "2025-10-15", "payrollLineItem": [ { "userId": "123DA511-5970-4C2F-AF7E-5C0FB11D23A3", "amount": 500, "paymentMethod": "Direct Deposit" }, { "userId": "3D971CE4-3DA9-4031-AB0E-D0E1A364444B", "amount": 300 } ] } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "payPeriod": { "type": "object", "properties": { "payPeriodId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "payPeriodId", "status", "message" ] } }, "required": [ "payPeriod" ] }, "examples": { "1": { "summary": "Success", "value": { "payPeriod": { "payPeriodId": "80B0DE7E-BB68-4EDE-B418-36FC21B90914", "status": "Ready", "message": "Supplemental PayPeriod for Payroll MonthlyBiweekly has been saved successfully." } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "WorkerType is invalid" } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "WorkerType is invalid" } } } }, "headers": {} } }, "security": [] } }, "/payroll/skipPayPeriod": { "post": { "summary": "skipPayPeriod", "deprecated": false, "description": "The `skipPayPeriod` API is used to skip a pay period \n\n### When to use:\n- If payroll for a payperiod is handled outside of the rollfi system\n- When a payPeriod is no longer required, such as during a furlough period\n\n### Notes:\n- payPeriodStatus becomes `Skipped` after using this API\n- This is a finalized state. To recreate a skipped payroll, use a supplemental payPeriod", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "payPeriodId": { "type": "string" } }, "required": [ "method", "companyId", "payPeriodId" ] }, "example": { "method": "skipPayPeriod", "companyId": "C8D57032-BF6F-4510-AA41-08A358365531", "payPeriodId": "81A0AE81-F817-4012-B058-46B2C0B9B72C" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "skipPayPeriod": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "status", "message" ] } }, "required": [ "skipPayPeriod" ] }, "examples": { "1": { "summary": "Success", "value": { "skipPayPeriod": { "status": "Skipped", "message": "PayPeriod skipped Successfully" } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "invalid payPeriodId" } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "invalid payPeriodId" } } } }, "headers": {} } }, "security": [] } }, "/payroll/cancelPayrollSubmission": { "post": { "summary": "cancelPayrollSubmission", "deprecated": false, "description": "The `cancelPayrollSubmission` API is used to cancel a previously submitted payroll and return it to an editable state.\n\n### When to use:\n- When there are last minute changes to a payroll that has already been submitted\n- When a payroll has been submitted but needs to be moved to another day\n\n### Notes:\n- payPeriodStatus becomes `Cancelled` after using this API\n- Edits can be made before 12:00 PM EST (noon) on the deadlineToRunPayroll to ensure payroll is still disbursed on time\n- If edits are made after this time the payroll will be delayed. For more information see the `Payroll Processing` guide.", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "payPeriodId": { "type": "string" } }, "required": [ "method", "companyId", "payPeriodId" ] }, "example": { "method": "cancelPayrollSubmission", "companyId": "3A08507F-E78B-4ABF-98D8-87D382E7CE14", "payPeriodId": "3C068DE4-038F-4874-B99B-4AFD7CB39351" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "payPeriod": { "type": "object", "properties": { "payPeriodId": { "type": "string" }, "message": { "type": "string" } }, "required": [ "payPeriodId", "message" ] } }, "required": [ "payPeriod" ] }, "example": { "payPeriod": { "payPeriodId": "DEE97E29-BF4A-40D1-9324-11D70BE38582", "message": "Payroll submission has been cancelled successfully. You can now make changes and resubmit before the deadline." } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "invalid payPeriodId" } } } }, "headers": {} } }, "security": [] } }, "/reports/getEmployeeTimeTrackingStatus": { "get": { "summary": "getEmployeeTimeTrackingStatus", "deprecated": false, "description": "The `getEmployeeTimeTrackingStatus` API retrieves an employee's current status within time tracking to determine their eligibility for clock in/out and break actions.\n\n### What it does:\n\n- Returns wether the employee is currently clocked in or on a break\n- Provides the clockIn time and break start time (if applicable) so their current shift duration can be calculated\n\n### Note:\n- The shift and break start times are returned in the employee's local timezone", "operationId": "getEmployeeTimeTrackingStatus", "tags": [ "TimeTracking Reports" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "userId": { "type": "string" }, "companyId": { "type": "string" } }, "required": [ "method", "userId", "companyId" ] }, "example": { "method": "getEmployeeTimeTrackingStatus", "userId": "C4CA148F-F2C6-4E70-8349-5d7CC6DFC1C2B", "companyId": "5221FFCF-E84B-4690-B7DC-DE29D549096B" } } } }, "responses": { "200": { "description": "Employee time tracking status", "content": { "application/json": { "schema": { "type": "object", "properties": { "employeeTimeStatus": { "type": "object", "properties": { "clockedIn": { "type": "boolean" }, "timeEntryId": { "type": "string" }, "clockInTime": { "type": "string" }, "onBreak": { "type": "boolean" }, "breakStartTime": { "type": "string" } }, "required": [ "clockedIn", "onBreak" ] } }, "required": [ "employeeTimeStatus" ] }, "example": { "employeeTimeStatus": { "clockedIn": true, "timeEntryId": "4942446B-5B19-4FC2-9559-9B74DE58D29B", "clockInTime": "23:32:28", "onBreak": true, "breakStartTime": "23:32:37" } } } }, "headers": {} }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Employee not found" } } } }, "headers": {} } }, "security": [] } }, "/reports/getTimeTrackingPolicy": { "get": { "summary": "getTimeTrackingPolicy", "deprecated": false, "description": "The `getTimeTrackingPolicy` API retrieves the active time tracking policy for a company and its assignments\n\n### What it does:\n\n- Returns the current overtime thresholds so they can be easily updated with `updateTimeTrackingPolicy`\n- Returns the current policy's assignments so they can be updated with `addTimeTrackingPolicyAssignments` and `removeTimeTrackingPolicyAssignments`", "operationId": "getTimeTrackingPolicy", "tags": [ "TimeTracking Reports" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" } }, "required": [ "method", "companyId" ] }, "example": { "method": "getTimeTrackingPolicy", "companyId": "5221FFCF-E84B-4690-B7DC-DE29D549096B" } } } }, "responses": { "200": { "description": "Active time tracking policy", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "policy": { "type": "object", "properties": { "timeTrackingPolicyId": { "type": "string" }, "companyId": { "type": "string" }, "dailyOvertimeThreshold": { "type": "integer" }, "weeklyOvertimeThreshold": { "type": "integer" } }, "required": [ "timeTrackingPolicyId", "companyId", "dailyOvertimeThreshold", "weeklyOvertimeThreshold" ] }, "assignedUserIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "success", "policy", "assignedUserIds" ] }, "example": { "success": true, "policy": { "timeTrackingPolicyId": "45C67A2B-4D64-47D2-B473-B7B5FD1CB80E", "companyId": "5221FFCF-E84B-4690-B7DC-DE29D549096B", "dailyOvertimeThreshold": 8, "weeklyOvertimeThreshold": 40 }, "assignedUserIds": [ "C4CA148F-F2C6-4E70-8349-57CC6DFC1C2B" ] } } }, "headers": {} }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "companyId is required." } } } }, "headers": {} } }, "security": [] } }, "/reports/getEmployeePayPeriodTimeCard": { "get": { "summary": "getEmployeePayPeriodTimeCard", "deprecated": false, "description": "The `getEmployeePayPeriodTimeCard` API retrieves an employee's timecard for a given payPeriod\n\n### When to use:\n- To display timecards on employee facing screens\n- For a more detailed view of time entries so individual days can be edited, and the timecard can be approved using `updateTimeCardApprovals`\n\n### What it does:\n- Fetches in depth time entry information for an employee in a given payPeriod\n- Displays time entries and breaks for each day in the payPeriod\n- Displays top level totals for the employee's timecard and their overtime eligibility\n\n### Notes:\n- All times are displayed in the employee's local time\n- For more information about timeCard statuses please see our [Time Tracking Guide](developer.rollfi.xyz/docs/TimeTrackingGuide).\n", "operationId": "getEmployeePayPeriodTimeCard", "tags": [ "TimeTracking Reports" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "userId": { "type": "string" }, "companyId": { "type": "string" }, "payPeriodId": { "type": "string" } }, "required": [ "method", "userId", "companyId", "payPeriodId" ] }, "example": { "method": "getEmployeePayPeriodTimeCard", "userId": "C4CA148F-F2C6-4E70-8349-57CC6DFC1C2B", "companyId": "5221FFCF-E84B-4690-B7DC-DE29D549096B", "payPeriodId": "3EAEC271-6C06-4E17-8C3B-1C6649D534D5" } } } }, "responses": { "200": { "description": "Employee pay period time card", "content": { "application/json": { "schema": { "type": "object", "properties": { "payPeriodTimeCard": { "type": "object", "properties": { "timeCardId": { "type": "string" }, "approvalStatus": { "type": "string" }, "lastSynced": { "type": "string" }, "isOvertimeEligible": { "type": "boolean" }, "regularHours": { "type": "number" }, "overtimeHours": { "type": "number" }, "workDates": { "type": "array", "items": { "type": "object", "properties": { "workDate": { "type": "string" }, "regularHours": { "type": [ "integer", "number" ] }, "overtimeHours": { "type": [ "number", "integer" ] }, "timeEntries": { "type": "array", "items": { "type": "object", "properties": { "timeEntryId": { "type": "string" }, "clockInTime": { "type": "string" }, "clockOutTime": { "type": "string" }, "breaks": { "type": "array", "items": { "type": "object", "properties": { "breakStart": { "type": "string" }, "breakEnd": { "type": "string" } }, "required": [ "breakStart", "breakEnd" ] } } }, "required": [ "timeEntryId", "clockInTime", "clockOutTime", "breaks" ] } } }, "required": [ "workDate", "regularHours", "overtimeHours", "timeEntries" ] } } }, "required": [ "timeCardId", "approvalStatus", "isOvertimeEligible", "regularHours", "workDates" ] } }, "required": [ "payPeriodTimeCard" ] }, "example": { "payPeriodTimeCard": { "timeCardId": "4DDB60ED-BC33-49FA-A589-E29FB6C4FD5C", "approvalStatus": "New", "lastSynced": null, "isOvertimeEligible": true, "regularHours": 71.76, "overtimeHours": 10.46, "workDates": [ { "workDate": "2026-03-01", "regularHours": 8, "overtimeHours": 3.67, "timeEntries": [ { "timeEntryId": "8B57BE5E-D6F3-49C4-9A7A-CFBE74019C00", "clockInTime": "07:30:00", "clockOutTime": "19:40:00", "breaks": [ { "breakStart": "12:00:00", "breakEnd": "12:30:00" } ] } ] }, { "workDate": "2026-03-02", "regularHours": 8, "overtimeHours": 1.75, "timeEntries": [ { "timeEntryId": "D70A1260-A592-4A5D-B0E5-36E02AF1BC4C", "clockInTime": "09:30:00", "clockOutTime": "19:45:00", "breaks": [ { "breakStart": "12:00:00", "breakEnd": "12:30:00" } ] } ] }, { "workDate": "2026-03-03", "regularHours": 0, "overtimeHours": 0, "timeEntries": [] }, { "workDate": "2026-03-04", "regularHours": 8, "overtimeHours": 0.27, "timeEntries": [ { "timeEntryId": "6CF7C88B-F0A0-4870-B8D3-8C90D533F152", "clockInTime": "08:59:00", "clockOutTime": "17:45:00", "breaks": [ { "breakStart": "12:00:00", "breakEnd": "12:30:00" } ] } ] }, { "workDate": "2026-03-05", "regularHours": 8, "overtimeHours": 0.27, "timeEntries": [ { "timeEntryId": "AA441B88-9B18-4864-AE7E-8CDD033D8349", "clockInTime": "08:59:00", "clockOutTime": "17:45:00", "breaks": [ { "breakStart": "12:00:00", "breakEnd": "12:30:00" } ] } ] }, { "workDate": "2026-03-06", "regularHours": 0, "overtimeHours": 0, "timeEntries": [] }, { "workDate": "2026-03-07", "regularHours": 7.75, "overtimeHours": 0, "timeEntries": [ { "timeEntryId": "3F62FCBA-5218-4655-A607-4896C586CE2F", "clockInTime": "10:00:00", "clockOutTime": "18:30:00", "breaks": [ { "breakStart": "12:00:00", "breakEnd": "12:45:00" } ] } ] }, { "workDate": "2026-03-08", "regularHours": 8, "overtimeHours": 0.75, "timeEntries": [ { "timeEntryId": "FD706B06-0633-40DD-BB20-D38E10153BDF", "clockInTime": "09:00:00", "clockOutTime": "18:30:00", "breaks": [ { "breakStart": "12:00:00", "breakEnd": "12:45:00" } ] } ] }, { "workDate": "2026-03-09", "regularHours": 0, "overtimeHours": 0, "timeEntries": [] }, { "workDate": "2026-03-10", "regularHours": 0, "overtimeHours": 0, "timeEntries": [] }, { "workDate": "2026-03-11", "regularHours": 0, "overtimeHours": 0, "timeEntries": [] }, { "workDate": "2026-03-12", "regularHours": 0, "overtimeHours": 0, "timeEntries": [] }, { "workDate": "2026-03-13", "regularHours": 0, "overtimeHours": 0, "timeEntries": [] }, { "workDate": "2026-03-14", "regularHours": 8, "overtimeHours": 0.75, "timeEntries": [ { "timeEntryId": "C94195E5-EA1D-4A0E-B49F-5AEB69A384FC", "clockInTime": "09:00:00", "clockOutTime": "18:30:00", "breaks": [ { "breakStart": "12:00:00", "breakEnd": "12:45:00" } ] } ] }, { "workDate": "2026-03-15", "regularHours": 8, "overtimeHours": 0.75, "timeEntries": [ { "timeEntryId": "936F5117-63CA-4011-98CB-C8ED4D891BCB", "clockInTime": "09:00:00", "clockOutTime": "18:30:00", "breaks": [ { "breakStart": "12:00:00", "breakEnd": "12:45:00" } ] } ] }, { "workDate": "2026-03-16", "regularHours": 0, "overtimeHours": 0, "timeEntries": [] }, { "workDate": "2026-03-17", "regularHours": 8, "overtimeHours": 2.25, "timeEntries": [ { "timeEntryId": "17A2DF13-EB87-4F5C-AD53-70F4B0E213AE", "clockInTime": "09:00:00", "clockOutTime": "20:30:00", "breaks": [ { "breakStart": "12:00:00", "breakEnd": "12:45:00" }, { "breakStart": "16:00:00", "breakEnd": "16:30:00" } ] } ] }, { "workDate": "2026-03-18", "regularHours": 0, "overtimeHours": 0, "timeEntries": [] }, { "workDate": "2026-03-19", "regularHours": 0, "overtimeHours": 0, "timeEntries": [] }, { "workDate": "2026-03-20", "regularHours": 0, "overtimeHours": 0, "timeEntries": [] }, { "workDate": "2026-03-21", "regularHours": 0, "overtimeHours": 0, "timeEntries": [] }, { "workDate": "2026-03-22", "regularHours": 0, "overtimeHours": 0, "timeEntries": [] }, { "workDate": "2026-03-23", "regularHours": 0.01, "overtimeHours": 0, "timeEntries": [ { "timeEntryId": "4942446B-5B19-4FC2-9559-9B74DE58D29B", "clockInTime": "23:32:28", "clockOutTime": "23:39:06", "breaks": [ { "breakStart": "23:32:37", "breakEnd": "23:39:06" } ] } ] }, { "workDate": "2026-03-24", "regularHours": 0, "overtimeHours": 0, "timeEntries": [] }, { "workDate": "2026-03-25", "regularHours": 0, "overtimeHours": 0, "timeEntries": [] }, { "workDate": "2026-03-26", "regularHours": 0, "overtimeHours": 0, "timeEntries": [] }, { "workDate": "2026-03-27", "regularHours": 0, "overtimeHours": 0, "timeEntries": [] }, { "workDate": "2026-03-28", "regularHours": 0, "overtimeHours": 0, "timeEntries": [] }, { "workDate": "2026-03-29", "regularHours": 0, "overtimeHours": 0, "timeEntries": [] }, { "workDate": "2026-03-30", "regularHours": 0, "overtimeHours": 0, "timeEntries": [] }, { "workDate": "2026-03-31", "regularHours": 0, "overtimeHours": 0, "timeEntries": [] } ] } } } }, "headers": {} }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "companyId is required." } } } }, "headers": {} } }, "security": [] } }, "/reports/getPayPeriodTimeCards": { "get": { "summary": "getPayPeriodTimeCards", "deprecated": false, "description": "The `getPayPeriodTimeCards` API retrieves active timecards given a payPeriodId\n\n### What it does:\n- Fetches top level information for all time cards in a pay period\n- Displays totals for regular hours, overtime hours and the employee's overtime eligibility for easy top level timecard display screens\n- Can be used to display time cards history given a `processed` payPeriodId, or the current timecard given a `new` payPeriodId\n\n### Notes:\n- For more in depth information you can retrieve an individual employee's time cards using the `getEmployeePayPeriodTimeCard` API\n- overtimeHours is only retirned when `isOvertimeEligible = true`", "operationId": "getPayPeriodTimeCards", "tags": [ "TimeTracking Reports" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "payPeriodId": { "type": "string" } }, "required": [ "method", "companyId", "payPeriodId" ] }, "example": { "method": "getPayPeriodTimeCards", "companyId": "5221FFCF-E84B-4690-B7DC-DE29D549096B", "payPeriodId": "3EAEC271-6C06-4E17-8C3B-1C6649D534D5" } } } }, "responses": { "200": { "description": "Pay period time cards", "content": { "application/json": { "schema": { "type": "object", "properties": { "timeCards": { "type": "array", "items": { "type": "object", "properties": { "timeCardId": { "type": "string" }, "companyId": { "type": "string" }, "userId": { "type": "string" }, "payPeriodId": { "type": "string" }, "approvalStatus": { "type": "string" }, "lastSynced": { "type": "string" }, "isOvertimeEligible": { "type": "boolean" }, "regularHours": { "type": "number" }, "overtimeHours": { "type": "integer" } }, "required": [ "timeCardId", "companyId", "userId", "payPeriodId", "approvalStatus", "isOvertimeEligible", "regularHours", "lastSynced" ] } } }, "required": [ "timeCards" ] }, "example": { "timeCards": [ { "timeCardId": "4DDB60ED-BC33-49FA-A589-E29FB6C4FD5C", "companyId": "5221FFCF-E84B-4690-B7DC-DE29D549096B", "userId": "C4CA148F-F2C6-4E70-8349-57CC6DFC1C2B", "payPeriodId": "3EAEC271-6C06-4E17-8C3B-1C6649D534D5", "approvalStatus": "New", "lastSynced": null, "isOvertimeEligible": true, "regularHours": 24.5, "overtimeHours": 12 } ] } } }, "headers": {} }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "payPeriodId is required." } } } }, "headers": {} } }, "security": [] } }, "/reports/getGarnishmentFormFields": { "get": { "summary": "getGarnishmentFormFields", "deprecated": false, "description": "The `getGarnishmentFormFields ` API retrieves the form fields for a particular garnishment and agency\n\n### When to use:\n- To determine the necessary fields to add an employee garnishment \n\n### Note:\n- Agency specific fields are currently only supported for child support\n\n### Direct Agency Payment Scope:\n- Rollfi can only pay agencies directly for `Child Support` garnishments.\n- Direct agency payment for child support is available in 49 states (all except South Carolina (SC)).", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "garnishmentType": { "type": "string" }, "garnishmentAgency": { "type": "string" } }, "required": [ "method", "garnishmentType", "garnishmentAgency" ] }, "example": { "method": "getGarnishmentFormFields", "garnishmentType": "Child Support", "garnishmentAgency": "Florida Child Support Enforcement" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "garnishmentType": { "type": "string" }, "garnishmentAgency": { "type": "string" }, "garnishmentFieldList": { "type": "array", "items": { "type": "string" } }, "fieldDescription": { "type": "array", "items": { "type": "object", "properties": { "fieldName": { "type": "string" }, "isMandatory": { "type": "boolean" }, "dataType": { "type": "string" }, "options": { "type": "array", "items": { "type": "string" } } }, "required": [ "fieldName", "isMandatory", "dataType", "options" ] } } }, "required": [ "garnishmentType", "garnishmentFieldList", "fieldDescription" ] }, "example": { "garnishmentType": "Child Support", "garnishmentAgency": "Florida CSE", "garnishmentFieldList": [ "County", "Choose who will be paying the agency", "Case Number", "Start Date", "End Date", "Total Withholding Amount", "Frequency (Per)", "Expected Amount Per Pay Period", "Maximum Withholding Percentage" ], "fieldDescription": [ { "fieldName": "County", "isMandatory": false, "dataType": "String", "options": [ "Alachua", "Baker", "Bay", "Bradford", "Brevard", "Broward", "Calhoun", "Charlotte", "Citrus", "Clay", "Collier", "Columbia", "DeSoto", "Dixie", "Duval", "Escambia", "Flagler", "Florida Statewide", "Franklin", "Gadsden", "Gilchrist", "Glades", "Gulf", "Hamilton", "Hardee", "Hendry", "Hernando", "Highlands", "Hillsborough", "Holmes", "Indian River", "Jackson", "Jefferson", "Lafayette", "Lake", "Lee", "Leon", "Levy", "Liberty", "Madison", "Manatee", "Marion", "Martin", "Miami-Dade", "Monroe", "Nassau", "Okaloosa", "Okeechobee", "Orange", "Osceola", "Palm Beach", "Pasco", "Pinellas", "Polk", "Putnam", "Santa Rosa", "Sarasota", "Seminole", "St. Johns", "St. Lucie", "Sumter", "Suwannee", "Taylor", "Union", "Volusia", "Wakulla", "Walton", "Washington" ] }, { "fieldName": "Choose who will be paying the agency", "isMandatory": false, "dataType": "String", "options": [ "I want my payroll provider to make the payments", "I will make the payments myself" ] }, { "fieldName": "Case Number", "isMandatory": false, "dataType": "String" }, { "fieldName": "Start Date", "isMandatory": false, "dataType": "Date" }, { "fieldName": "End Date", "isMandatory": false, "dataType": "Date" }, { "fieldName": "Total Withholding Amount", "isMandatory": false, "dataType": "Decimal" }, { "fieldName": "Frequency (Per)", "isMandatory": false, "dataType": "String", "options": [ "Weekly" ] }, { "fieldName": "Expected Amount Per Pay Period", "isMandatory": false, "dataType": "Decimal" }, { "fieldName": "Maximum Withholding Percentage", "isMandatory": false, "dataType": "Decimal" } ] } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": { "error": { "code": 404, "message": "No garnishment agency found matching Bankruptcy Agency." } } } }, "headers": {} } }, "security": [] } }, "/reports/getGarnishmentAgencies": { "get": { "summary": "getGarnishmentAgencies", "deprecated": false, "description": "The `getGarnishmentAgencies` API retrieves the available agencies given a garnishment type\n\n### When to use:\n- To determine the agency to send in the `addGarnishments` request\n- Agencies are state specific and will be stated on any garnishment communications you recieve via mail\n\n### Note:\n- Currently only `Child Support` is supported for garnishmentType since this is the only garnishment Rollfi pays directly to an agency\n\n### Direct Agency Payment Scope:\n- Rollfi can only pay agencies directly for `Child Support` garnishments.\n- Direct agency payment for child support is available in 49 states (all except South Carolina (SC)).", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "garnishmentType": { "type": "string" } }, "required": [ "method", "garnishmentType" ] }, "example": { "method": "getGarnishmentAgencies", "garnishmentType": "Child Support" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "garnishmentAgencies": { "type": "array", "items": { "type": "string" } } }, "required": [ "garnishmentAgencies" ] }, "example": { "garnishmentAgencies": [ "Alabama Child Support Agency", "Alaska Child Support Agency", "Arizona Child Support Agency", "Arkansas Child Support Agency", "California Child Support Agency", "Colorado Child Support Agency", "Connecticut Child Support Agency", "Delaware Child Support Agency", "District of Columbia Child Support Agency", "Florida Child Support Enforcement", "Georgia Child Support Agency", "Hawaii Child Support Agency", "Idaho Child Support Agency", "Illinois Child Support State Agency", "Indiana Child Support Agency", "Iowa Child Support Agency", "Kansas Child Support Agency", "Kentucky Child Support Agency", "Louisiana Child Support Agency", "Maine Child Support Agency", "Maryland Child Support Agency", "Massachusetts Child Support Agency", "Michigan Child Support Agency", "Minnesota Child Support Agency", "Mississippi Child Support Agency", "Missouri Child Support Agency", "Montana Child Support Agency", "Nebraska Child Support Agency", "Nevada Child Support Agency", "New Hampshire Child Support Agency", "New Jersey Child Support Agency", "New Mexico Child Support Agency", "New York Child Support Enforcement", "North Carolina Child Support Agency", "North Dakota Child Support Division", "Ohio Child Support Program", "Oklahoma Child Support Agency", "Oregon Child Support Agency", "Pennsylvania Child Support Agency", "Rhode Island Child Support Agency", "South Carolina Child Support Agency", "South Dakota Child Support Agency", "Tennessee Child Support Agency", "Texas Attorney General Child Support", "Utah Child Support Agency", "Vermont Child Support Agency", "Virginia Child Support Agency", "Washington Child Support Agency", "West Virginia Child Support Agency", "Wisconsin Child Support Agency", "Wyoming Child Support Agency" ] } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": { "error": { "code": 404, "message": "No garnishment type found matching Test Agency." } } } }, "headers": {} } }, "security": [] } }, "/reports/getGarnishmentTypes": { "get": { "summary": "getGarnishmentTypes", "deprecated": false, "description": "The `getGarnishmentTypes` API retrieves the available garnishments you can add to an employee\n\n### When to use:\n- When a garnishment is necessary for an employee\n- Used to populate a dropdown of garnishment types to use in `addGarnishments`\n\n### Note:\n- Type can be used to retrieve available agencies if applicable using `getGarnishmentAgencies`\n- Use these garnishmentTypes to retrieve the fields using `getGarnishmentFormFields`", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" } }, "required": [ "method" ] }, "example": { "method": "getGarnishmentTypes" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "garnishmentTypes": { "type": "array", "items": { "type": "string" } } }, "required": [ "garnishmentTypes" ] }, "example": { "garnishmentTypes": [ "Administrative", "Bankruptcy", "Child Support", "Federal Tax Lien", "Other Garnishment", "State Tax Lien", "Student Loan", "Voluntary Wage" ] } } }, "headers": {} } }, "security": [] } }, "/reports/getTimeOffPolicyTypes": { "get": { "summary": "getTimeOffPolicyTypes", "deprecated": false, "description": "The `getTimeOffPolicyTypes` API returns supported PTO policy types.\n\n### What it does:\n\n- Provides available policy type labels used when creating or updating policies.\n- Helps clients present valid selection options in UI.", "operationId": "getTimeOffPolicyTypes", "tags": [ "TimeOff Reports" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "method": { "type": "string", "const": "getTimeOffPolicyTypes" } } }, "example": { "method": "getTimeOffPolicyTypes" } } } }, "responses": { "200": { "description": "Supported types", "content": { "application/json": { "schema": { "type": "object", "properties": { "timeOffPolicyTypes": { "type": "array", "items": { "type": "string" } } }, "required": [ "timeOffPolicyTypes" ] }, "example": { "timeOffPolicyTypes": [ "Paid Time Off", "Sick Leave", "Unpaid Leave" ] } } }, "headers": {} }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "companyId is required." } } } }, "headers": {} } }, "security": [] } }, "/reports/getTimeOffRequest": { "get": { "summary": "getTimeOffRequest", "deprecated": false, "description": "The `getTimeOffRequest` API returns PTO request report rows.\n\n### What it does:\n\n- Returns request-level reporting data for company users.\n- Includes status and date details for reconciliation workflows.", "operationId": "getTimeOffRequest", "tags": [ "TimeOff Reports" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "const": "getTimeOffRequest" }, "companyId": { "type": "string" } }, "required": [ "method", "companyId" ] }, "example": { "method": "getTimeOffRequest", "companyId": "5221FFCF-E84B-4690-B7DC-DE29D549096B" } } }, "required": true }, "responses": { "200": { "description": "Request dashboard rows", "content": { "application/json": { "schema": { "type": "object", "properties": { "timeOffRequests": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "date": { "type": "string", "description": "MM/DD/YYYY" }, "length": { "type": "string", "description": "e.g.", "2 days": null }, "type": { "type": "string" }, "status": { "type": "string" }, "approver": { "type": "string" } } } } }, "required": [ "timeOffRequests" ] }, "example": { "timeOffRequests": [ { "name": "JANE DOE", "date": "08/01/2026", "length": "2 days", "type": "Paid Time Off", "status": "Approved", "approver": "PAYROLL ADMIN" }, { "name": "JOHN SMITH", "date": "08/04/2026", "length": "1 day", "type": "Sick Leave", "status": "Pending", "approver": "" } ] } } }, "headers": {} }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "companyId is required." } } } }, "headers": {} } }, "security": [] } }, "/reports/getTimeOffPolicyAssignments": { "get": { "summary": "getTimeOffPolicyAssignments", "deprecated": false, "description": "The `getTimeOffPolicyAssignments` API returns PTO policy assignment summaries.\n\n### What it does:\n\n- Lists employee-to-policy assignment records.\n- Surfaces assignment-level values used for PTO reporting and review.", "operationId": "getTimeOffPolicyAssignments", "tags": [ "TimeOff Reports" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "const": "getTimeOffPolicyAssignments" }, "companyId": { "type": "string" }, "policyName": { "type": "string" } }, "required": [ "method", "companyId" ] }, "example": { "method": "getTimeOffPolicyAssignments", "companyId": "5221FFCF-E84B-4690-B7DC-DE29D549096B" } } }, "required": true }, "responses": { "200": { "description": "Assignment summary list", "content": { "application/json": { "schema": { "type": "object", "properties": { "employeeCount": { "type": "integer" }, "timeOffPolicyAssignments": { "type": "array", "items": { "type": "object", "properties": { "employeeName": { "type": "string" }, "policyName": { "type": "string" }, "balance": { "type": "number" }, "requests": { "type": "integer" } } } } }, "required": [ "employeeCount", "timeOffPolicyAssignments" ] }, "example": { "employeeCount": 2, "timeOffPolicyAssignments": [ { "employeeName": "JANE DOE", "policyName": "PTO FULL TIME", "balance": 32, "requests": 1 }, { "employeeName": "JOHN SMITH", "policyName": "SICK LEAVE STANDARD", "balance": 16, "requests": 2 } ] } } }, "headers": {} }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "companyId is required." } } } }, "headers": {} } }, "security": [] } }, "/reports/getUserTask": { "get": { "summary": "getUserTask", "deprecated": false, "description": "\nThe `getUserTask` API retrieves pending tasks and setup requirements for a specific user.\n\n### What it does:\n\n- Returns pending tasks with descriptions for user onboarding and setup\n- Provides actionable task information to guide completion of user requirements\n\n### Notes:\n\n- Used to track individual user onboarding progress and identify incomplete steps\n- Incomplete steps (verification and missing direct deposit account) prevent an employee from moving on from the onboarding process", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "userId": { "type": "string" } }, "required": [ "method", "userId" ] }, "example": { "method": "getUserTask", "userId": "D32D7451-FE6C-44D3-8DDB-E6442A15884E" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "description": { "type": "string" } }, "required": [ "type", "description" ] } } }, "required": [ "task" ] }, "examples": { "1": { "summary": "Success", "value": { "task": [ { "type": "KYC Verification", "description": "Your KYC status is pending. Please wait for the process to complete or contact support for more information." }, { "type": "Link Direct Deposit Account", "description": "Connect your direct deposit account" } ] } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "Invalid userId" } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid userId" } } } }, "headers": {} } }, "security": [] } }, "/reports/getCompanyBenefits": { "get": { "summary": "getCompanyBenefits", "deprecated": false, "description": "\nThe `getCompanyBenefits` API retrieves the details for a company's benefit elections\n\n### What it does:\n- Shows benefit elections on an employee-by-employee basis\n- Provides employee and company contributions per payPeriod\n", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" } }, "required": [ "method", "companyId" ] }, "example": { "method": "getCompanyBenefits", "companyId": "9598E98F-A4DC-419E-96DC-26AC71F08111" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "Benefits": { "type": "array", "items": { "type": "object", "properties": { "BenefitType": { "type": "string" }, "Premium per pay period": { "type": "integer" }, "Employer contribution per pay period": { "type": "integer" }, "Employee covered": { "type": "integer" } }, "required": [ "BenefitType", "Premium per pay period" ] } }, "EmployeeBenefitDetails": { "type": "array", "items": { "type": "object", "properties": { "Employee": { "type": "string" }, "EmployeeID": { "type": "string" }, "BenefitType": { "type": "string" }, "EffectiveStartMonthYear": { "type": "string" }, "Status": { "type": "string" }, "Employee contribution": { "type": "integer" }, "Employer contribution": { "type": "integer" }, "Pay Frequency": { "type": "string" } } } } }, "required": [ "Benefits", "EmployeeBenefitDetails" ] }, "example": { "Benefits": [ { "BenefitType": "Dental", "Premium per pay period": 0 }, { "BenefitType": "Medical", "Employer contribution per pay period": 0, "Employee covered": 1, "Premium per pay period": 250 }, { "BenefitType": "Vision", "Premium per pay period": 0 } ], "EmployeeBenefitDetails": [ { "Employee": "Nia Stewart", "EmployeeID": "2F3F1D5E-DB45-4268-89DB-E926C631B475", "BenefitType": "Medical", "EffectiveStartMonthYear": "October 2025", "Status": "Active", "Employee contribution": 250, "Employer contribution": 0, "Pay Frequency": "BiWeekly" } ] } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid CompanyId" } } } }, "headers": {} } }, "security": [] } }, "/reports/getUser": { "get": { "summary": "getUser", "deprecated": false, "description": "\nThe `getUser` API retrieves detailed information for a specific user.\n\n### What it does:\n\n- Returns comprehensive user details including personal information, employment status, wage, and contact data\n- Provides individual user profile information for employees or contractors", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "getUser" }, "companyId": { "type": "string" }, "userId": { "type": "string" } }, "required": [ "method", "companyId", "userId" ] }, "example": { "method": "getUser", "companyId": "2DFCA586-C2D4-4FD7-B823-063F2575A5E7", "userId": "AD5BBA6F-B0F3-41E7-B98E-63603F5E115F" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "string" }, "userId": { "type": "string" }, "userReferenceId": { "type": "string" }, "companyId": { "type": "string" }, "status": { "type": "object", "properties": { "userStatus": { "type": "string" } }, "required": [ "userStatus" ] }, "WorkerType": { "type": "object", "properties": { "WorkerType": { "type": "string" } }, "required": [ "WorkerType" ] }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "middleName": { "type": "string" }, "phoneNumber": { "type": "string" }, "kycStatus": { "type": "string" }, "jobTitle": { "type": "string" }, "dateOfJoin": { "type": "string" }, "email": { "type": "string" }, "userWages": { "type": "array", "items": { "type": "object", "properties": { "userWageId": { "type": "string" }, "standardWorkingHours": { "type": "integer" }, "WageRate": { "type": "integer" }, "WageBasis": { "type": "object", "properties": { "WageBasis": { "type": "string" } }, "required": [ "WageBasis" ] }, "paymentMethod": { "type": "object", "properties": { "PaymentMethod": { "type": "string" } }, "required": [ "PaymentMethod" ] }, "employeeRefTaxExempt": { "type": "string" }, "employeeType": { "type": "string" }, "differentialPay": { "type": "string" }, "employmentStatus": { "type": "string" } } } }, "userAddress": { "type": "object", "properties": { "address1": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zipcode": { "type": "string" }, "country": { "type": "string" } }, "required": [ "address1", "city", "state", "zipcode", "country" ] }, "userRemoteLocations": { "type": "array", "items": { "type": "string" } }, "companyLocationCategory": { "type": "object", "properties": { "companyLocationCategory": { "type": "string" } }, "required": [ "companyLocationCategory" ] }, "companyLocation": { "type": "object", "properties": {} }, "stateCode": { "type": "string" }, "W4Informations": { "type": "array", "items": { "type": "object", "properties": { "W4FilingStatus": { "type": "object", "properties": { "W4FilingStatus": { "type": "string" } }, "required": [ "W4FilingStatus" ] }, "HaveMultipleJob": { "type": "boolean" }, "Dependents": { "type": "integer" }, "DependentsAbove18": { "type": "integer" }, "OtherIncome": { "type": "integer" }, "OtherDeduction": { "type": "integer" }, "ExtraWithholding": { "type": "integer" }, "HasMilitarySpouseExemption": { "type": "boolean" }, "StateAdditionalDeduction": { "type": "integer" }, "IsNonResident": { "type": "boolean" }, "AZDeductionPercent": { "type": "integer" } } } }, "ssn": { "type": "string" }, "dateOfBirth": { "type": "string" }, "userRemoteLocation": { "type": "object", "properties": {} }, "stateW4Informations": { "type": "array", "items": { "type": "string" } }, "employeeMiscellaneousStateTax": { "type": "array", "items": { "type": "object", "properties": { "instanceId": { "type": "string" }, "RiskClassNameEmployee": { "type": "string" }, "RiskClassCode": { "type": "string" }, "PayrollDeductionRate": { "type": "string" }, "CompositeRate": { "type": "string" } }, "required": [ "instanceId", "RiskClassNameEmployee", "RiskClassCode", "PayrollDeductionRate", "CompositeRate" ] } }, "bankAccounts": { "type": "array", "items": { "type": "object", "properties": { "userPayAccountEntityId": { "type": "string" }, "bankName": { "type": "string" }, "accountName": { "type": "string" }, "accountNumber": { "type": "string" }, "payPercentage": { "type": "integer" }, "accountType": { "type": "string" }, "status": { "type": "string" }, "accountPriority": { "type": "string" } } } }, "timeOffRequests": { "type": "array", "items": { "type": "string" } }, "employeeGarnishments": { "type": "array", "items": { "type": "object", "properties": { "garnishmentId": { "type": "string" }, "garnishmentType": { "type": "string" }, "garnishmentFields": { "type": "object", "properties": { "garnishmentId": { "type": "string" }, "garnishmentType": { "type": "string" }, "garnishmentAgency": { "type": "string" }, "garnishmentFields": { "type": "object", "properties": {} } }, "required": [ "garnishmentId", "garnishmentType", "garnishmentFields" ] } }, "required": [ "garnishmentId", "garnishmentType", "garnishmentFields" ] } } }, "required": [ "user", "userId", "userReferenceId", "companyId", "status", "WorkerType", "firstName", "lastName", "middleName", "phoneNumber", "kycStatus", "jobTitle", "dateOfJoin", "email", "userWages", "userAddress", "userRemoteLocations", "companyLocationCategory", "ssn", "dateOfBirth", "W4Informations", "stateCode" ] } } }, "required": [ "user" ] }, "examples": { "1": { "summary": "Success", "value": { "user": [ { "user": "Molly Phelps", "userId": "A9A61FBE-7C7F-48E6-9CA8-1AD8A8CB3980", "userReferenceId": "12370808", "companyId": "C2019899-9EEF-49F7-9B51-70744AFAFE61", "status": { "userStatus": "Active" }, "WorkerType": { "WorkerType": "W2" }, "firstName": "Molly", "lastName": "Phelps", "middleName": "", "phoneNumber": "9988776655", "kycStatus": "passed", "jobTitle": "Developer", "dateOfJoin": "2023-02-02", "email": "phelps6600@mailsac.com", "userWages": [ { "userWageId": "9C86DE50-1EFF-4982-B174-CB1BE05977E1", "standardWorkingHours": 8, "WageRate": 4000, "WageBasis": { "WageBasis": "Per Month" }, "paymentMethod": { "PaymentMethod": "Direct Deposit" }, "employeeRefTaxExempt": "Yes, as an owner/corporate officer", "employeeType": "Commission only/Eliglble for overtime", "differentialPay": "No", "employmentStatus": "Full Time (30+ Hours per week)" } ], "userAddress": { "address1": "102 Fallsgrove Blvd", "city": "Seattle", "state": "WA", "zipcode": "98101", "country": "US" }, "userRemoteLocations": [], "companyLocationCategory": { "companyLocationCategory": "Remote" }, "companyLocation": null, "stateCode": "WA", "W4Informations": [ { "W4FilingStatus": { "W4FilingStatus": "Head of household" }, "HaveMultipleJob": true, "Dependents": 3, "DependentsAbove18": 2, "OtherIncome": 1500, "OtherDeduction": 150, "ExtraWithholding": 10, "HasMilitarySpouseExemption": false, "StateAdditionalDeduction": 0, "IsNonResident": false, "AZDeductionPercent": 0 } ], "ssn": "523656325", "dateOfBirth": "2006-01-01", "userRemoteLocation": null, "stateW4Informations": [], "employeeMiscellaneousStateTax": [ { "instanceId": "A310861D-384B-4B2A-9D11-DDD9BE5C6109", "RiskClassNameEmployee": "DupTest2", "RiskClassCode": "123451", "PayrollDeductionRate": "1", "CompositeRate": "2" } ], "bankAccounts": [ { "userPayAccountEntityId": "D48DA316-ED8C-4815-B0EC-14057D344951", "bankName": "THE UNION BK OF MENA", "accountName": "LEGACY BANK", "accountNumber": "XXXXXXXXX2500", "payPercentage": 100, "accountType": "savings", "status": "ready", "accountPriority": "Primary" } ], "timeOffRequests": [], "employeeGarnishments": [ { "garnishmentId": "1BBB5668-49A7-44DA-81DC-7462ACCB5B1F", "garnishmentType": "Student Loan", "garnishmentFields": { "Amount needed to be withheld per pay period": "500", "End Date": "2026-06-06", "Total amount to be garnished": "5000" } }, { "garnishmentId": "767A5AB2-990E-498D-A527-0DB16365498A", "garnishmentType": "Child Support", "garnishmentAgency": "Florida Child Support Enforcement", "garnishmentFields": { "County": "Polk", "Expected Amount Per Pay Period": "25", "Frequency (Per)": "Monthly", "Total Withholding Amount": "20", "Start Date": "2026-01-10", "End Date": "2026-10-10", "Max % of Net Pay": "10", "Who Makes Payment": "I will make the payments myself" } } ] } ] } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "EmployeeId is Mandatory." } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } }, "headers": {} } }, "security": [] } }, "/reports/getUsers": { "get": { "summary": "getUsers", "deprecated": false, "description": "\nThe `getUsers` API retrieves detailed information for all users within a company.\n\n### What it does:\n\n- Returns comprehensive user details for all employees (W2) and contractors (1099) including personal information, employment status, wage, and contact data\n- Provides complete user profile information for all active users in the company\n\n### Note:\n- Sensitive data, such as bank details, are ommitted from the blanket `getUsers` and must be retrieved individually", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "getUser" }, "companyId": { "type": "string" } }, "required": [ "method", "companyId" ] }, "example": { "method": "getUsers", "companyId": "CFC4D743-4869-4799-B1AF-B615D6CF21E5" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "users": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "string" }, "userId": { "type": "string" }, "companyId": { "type": "string" }, "status": { "type": "object", "properties": { "userStatus": { "type": "string" } }, "required": [ "userStatus" ] }, "WorkerType": { "type": "object", "properties": { "WorkerType": { "type": "string" } }, "required": [ "WorkerType" ] }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "middleName": { "type": "string" }, "phoneNumber": { "type": "string" }, "kycStatus": { "type": "string" }, "jobTitle": { "type": "string" }, "dateOfJoin": { "type": "string" }, "email": { "type": "string" }, "userWages": { "type": "array", "items": { "type": "object", "properties": { "WageRate": { "type": "integer" }, "WageBasis": { "type": "object", "properties": { "WageBasis": { "type": "string" } }, "required": [ "WageBasis" ] }, "paymentMethod": { "type": "object", "properties": { "PaymentMethod": { "type": "string" } }, "required": [ "PaymentMethod" ] } }, "required": [ "WageRate", "WageBasis", "paymentMethod" ] } }, "userAddress": { "type": "object", "properties": { "address1": { "type": "string" }, "address2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zipcode": { "type": "string" }, "country": { "type": "string" } }, "required": [ "address1", "address2", "city", "state", "zipcode", "country" ] }, "employeeMiscellaneousStateTax": { "type": "object", "properties": { "RiskClassCode": { "type": "string" }, "CompositeRate": { "type": "string" }, "RiskClassNameEmployee": { "type": "string" }, "PayrollDeductionRate": { "type": "string" } } } }, "required": [ "user", "userId", "companyId", "status", "WorkerType", "firstName", "lastName", "middleName", "phoneNumber", "kycStatus", "jobTitle", "dateOfJoin", "email", "userWages", "userAddress", "employeeMiscellaneousStateTax" ] } } }, "required": [ "users" ] }, "example": { "users": [ { "user": "Molly Phelps", "userId": "A9A61FBE-7C7F-48E6-9CA8-1AD8A8CB3980", "companyId": "C2019899-9EEF-49F7-9B51-70744AFAFE61", "status": { "userStatus": "Active" }, "WorkerType": { "WorkerType": "W2" }, "firstName": "Molly", "lastName": "Phelps", "middleName": "", "phoneNumber": "9988776655", "kycStatus": "passed", "jobTitle": "Developer", "dateOfJoin": "2023-02-02", "email": "phelps6600@mailsac.com", "userWages": [ { "WageRate": 4000, "WageBasis": { "WageBasis": "Per Month" }, "paymentMethod": { "PaymentMethod": "Direct Deposit" } } ], "userAddress": { "address1": "102 Fallsgrove Blvd", "address2": "", "city": "Seattle", "state": "WA", "zipcode": "98101", "country": "US" }, "employeeMiscellaneousStateTax": { "RiskClassCode": "643609", "CompositeRate": "9", "RiskClassNameEmployee": "Plumber", "PayrollDeductionRate": "4.5" } } ] } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid CompanyId" } } } }, "headers": {} } }, "security": [] } }, "/reports/getPaySchedule": { "get": { "summary": "getPaySchedule", "deprecated": false, "description": "\nThe `getPaySchedule` API retrieves the pay schedules for W2 and/or 1099 workers for a company.\n\n### What it does:\n\n- Returns pay schedule details including payroll beginning and end dates, deadline for payroll submission, and pay date", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "getPaySchedule" ], "title": "getPaySchedule" }, "companyId": { "type": "string", "format": "uuid" } }, "required": [ "method", "companyId" ] }, "example": { "method": "getPaySchedule", "companyId": "27FE3598-D47E-49B7-A328-F61802228735" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "paySchedule": { "type": "array", "items": { "type": "object", "properties": { "payScheduleId": { "type": "string" }, "payBeginDate": { "type": "string" }, "payDate": { "type": "string" }, "payEndDate": { "type": "string" }, "deadlineToRunPayroll": { "type": "string" }, "workerType": { "type": "object", "properties": { "workerType": { "type": "string" } }, "required": [ "workerType" ] }, "compensationFrequency": { "type": "object", "properties": { "compensationFrequency": { "type": "string" } }, "required": [ "compensationFrequency" ] } } } } }, "required": [ "paySchedule" ] }, "example": { "paySchedule": [ { "payScheduleId": "146C42D1-EC46-4F1C-B308-251676DC3942", "payBeginDate": "2025-01-10", "payDate": "2025-01-17", "payEndDate": "2025-01-16", "deadlineToRunPayroll": "2025-01-14", "workerType": { "workerType": "W2" }, "compensationFrequency": { "compensationFrequency": "Weekly" } } ] } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid CompanyId" } } } }, "headers": {} } }, "security": [] } }, "/reports/getPayPeriod": { "get": { "summary": "getPayPeriod", "deprecated": false, "description": "\nThe `getPayPeriod` API retrieves pay period information for a company based on worker type.\n\n### What it does:\n\n- Returns pay period details including dates, deadlines, and payroll amounts\n\n### Notes:\n\n- Requires `companyId` and `workerType` (W2 or 1099) parameters\n- Used before initiating payroll processing with `initiatePayroll`", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string", "format": "uuid" }, "workerType": { "type": "string", "enum": [ "W2", "1099-NEC" ] } }, "required": [ "method", "companyId", "workerType" ] }, "example": { "method": "getPayPeriod", "companyId": "C2019899-9EEF-49F7-9B51-70744AFAFE61", "workerType": "W2" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "payPeriodId": { "type": "string" }, "payPeriod": { "type": "string" }, "payBeginDate": { "type": "string" }, "payEndDate": { "type": "string" }, "payDate": { "type": "string" }, "deadLineToRunPayroll": { "type": "string" }, "payPeriodStatus": { "type": "string", "enum": [ "new", "submitted", "cancelled", "inProcess", "processed", "failed", "returned", "skipped" ] }, "payrollAmount": { "type": "number" } }, "required": [ "payPeriodId", "payPeriod", "payBeginDate", "payEndDate", "payDate", "deadLineToRunPayroll", "payPeriodStatus", "payrollAmount" ] }, "example": { "payPeriodId": "9BF440AF-9BE8-49B7-8F5E-0673E35CB5B3", "payPeriod": "10/01/2025 - 10/31/2025", "payBeginDate": "2025-10-01", "payEndDate": "2025-10-31", "payDate": "2025-10-31", "deadLineToRunPayroll": "2025-10-29", "payPeriodStatus": "submitted", "payrollAmount": 2763663.09 } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid WorkerType" } } } }, "headers": {} } }, "security": [] } }, "/reports/getPayPeriodDetails": { "get": { "summary": "getPayPeriodDetails", "deprecated": false, "description": "The `getPayPeriodDetails` API retrieves detailed information about a specific pay period using a payPeriodId.\n\n### What it does:\n\n- Returns comprehensive pay period details for a specific pay period ID\n- Provides pay period dates, deadlines, and associated payroll information\n- Provides each employee's payroll details including: gross and net pay amounts, taxes, banking, overtime and additional compensation\n\n### Notes:\n- includeTransactions can be used to view the company debit and employee credits on each payPeriod\n- includeTransactions defaults to false when not included in the request", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "getPayPeriodDetails" ], "title": "getPayPeriodDetails" }, "payPeriodId": { "type": "string", "format": "uuid" }, "includeTransactions": { "type": "boolean" } }, "required": [ "method", "payPeriodId", "includeTransactions" ] }, "example": { "method": "getPayPeriodDetails", "payPeriodId": "7BF6D637-9E8C-4AF6-A8B0-A24F36CA2F53", "includeTransactions": false } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "payPeriod": { "type": "array", "items": { "type": "object", "properties": { "payPeriodId": { "type": "string" }, "payPeriod": { "type": "string" }, "deadLineToRunPayroll": { "type": "string" }, "PayPeriodStatus": { "type": "string" }, "total": { "type": "number" }, "employeeTaxSum": { "type": "number" }, "employerTaxSum": { "type": "number" }, "isProcessed": { "type": "boolean" }, "payDate": { "type": "string" }, "payEndDate": { "type": "string" }, "payBeginDate": { "type": "string" }, "workerType": { "type": "object", "properties": { "workerType": { "type": "string" } }, "required": [ "workerType" ] }, "payPeriodType": { "type": "object", "properties": { "payPeriodType": { "type": "string" } }, "required": [ "payPeriodType" ] }, "payrollLineItems": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "userName": { "type": "string" }, "baseTotal": { "type": "integer" }, "numberOfLeaveDays": { "type": "integer" }, "lop": { "type": "integer" }, "retroAmount": { "type": "integer" }, "grossTotal": { "type": [ "number", "integer" ] }, "netTotal": { "type": "number" }, "payHours": { "type": "integer" }, "payRate": { "type": "integer" }, "standardWorkingHours": { "type": "integer" }, "employeeTax": { "type": "object", "properties": { "employeeTax": { "type": "number" } }, "required": [ "employeeTax" ] }, "employeePayrollTransactions": { "type": "array", "items": { "type": "object", "properties": { "transactionName": { "type": "string" }, "transferAmount": { "type": "number" }, "status": { "type": "string", "enum": [ "failed", "pending", "returned", "complete", "cancelled" ] } }, "required": [ "transactionName", "transferAmount", "status" ] } }, "employeeTaxDetails": { "type": "array", "items": { "type": "object", "properties": { "taxName": { "type": "string" }, "taxAmount": { "type": [ "integer", "number" ] }, "taxAmountYtd": { "type": "integer" }, "isEmployerTax": { "type": "boolean" } }, "required": [ "taxName", "taxAmount", "taxAmountYtd", "isEmployerTax" ] } }, "employerTaxDetails": { "type": "array", "items": { "type": "object", "properties": { "taxName": { "type": "string" }, "taxAmount": { "type": [ "integer", "number" ] }, "taxAmountYtd": { "type": "integer" }, "isEmployerTax": { "type": "boolean" } }, "required": [ "taxName", "taxAmount", "taxAmountYtd", "isEmployerTax" ] } }, "miscellaneousStateTaxes": { "type": "array", "items": { "type": "string" } }, "overTimes": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "amount": { "type": "number" }, "numberOfHours": { "type": "integer" } } } }, "additionalCompensations": { "type": "array", "items": { "type": "object", "properties": { "payrollLineItemAdditionalCompensationVertexCompensationIdentifier": { "type": "object", "properties": { "compensationDescription": { "type": "string" } }, "required": [ "compensationDescription" ] }, "amount": { "type": "integer" } }, "required": [ "payrollLineItemAdditionalCompensationVertexCompensationIdentifier", "amount" ] } }, "deductions": { "type": "array", "items": { "type": "object", "properties": { "vertexDeductionIdentifier": { "type": "object", "properties": { "deductionDescription": { "type": "string" } }, "required": [ "deductionDescription" ] }, "amount": { "type": "integer" } }, "required": [ "vertexDeductionIdentifier", "amount" ] } }, "reimbursements": { "type": "array", "items": { "type": "object", "properties": { "reimbursementType": { "type": "string" }, "amount": { "type": "integer" } }, "required": [ "reimbursementType", "amount" ] } }, "timeOffs": { "type": "array", "items": { "type": "string" } }, "payDetails": { "type": "array", "items": { "type": "object", "properties": { "payPercentage": { "type": "integer" }, "amount": { "type": "number" }, "employeePayAccount": { "type": [ "object", "null" ], "properties": { "accountName": { "type": "string" } }, "required": [ "accountName" ] } }, "required": [ "payPercentage", "amount", "employeePayAccount" ] } }, "basePay": { "type": "array", "items": { "type": "object", "properties": { "payCode": { "type": "string" }, "payHours": { "type": "integer" }, "payRate": { "type": "integer" }, "multiplier": { "type": "integer" }, "amount": { "type": "integer" } }, "required": [ "payCode", "payHours", "payRate", "multiplier", "amount" ] } }, "employee": { "type": "object", "properties": { "employee": { "type": "string" } }, "required": [ "employee" ] } }, "required": [ "userId", "userName", "baseTotal", "numberOfLeaveDays", "lop", "retroAmount", "grossTotal", "netTotal", "payHours", "payRate", "standardWorkingHours", "employeeTax", "employeeTaxDetails", "employerTaxDetails", "miscellaneousStateTaxes", "overTimes", "additionalCompensations", "deductions", "reimbursements", "timeOffs", "payDetails", "employee" ] } }, "companyPayrollTransactions": { "type": "array", "items": { "type": "object", "properties": { "transactionName": { "type": "string" }, "transferAmount": { "type": "number" }, "status": { "type": "string", "enum": [ "failed", "pending", "returned", "complete", "cancelled" ] } }, "required": [ "transferAmount", "status", "transactionName" ] } } } } } }, "required": [ "payPeriod" ] }, "examples": { "1": { "summary": "IncludeTransactions: true", "value": { "payPeriod": [ { "payPeriodId": "EDD9F5D2-BED4-4337-A80C-4DDD33EDFF91", "payPeriod": "11/01/2025 - 11/30/2025", "deadLineToRunPayroll": "2025-11-25", "PayPeriodStatus": "processed", "total": 10426.56, "employeeTaxSum": 879.35, "employerTaxSum": 898.9, "isProcessed": true, "payDate": "2025-11-28", "payEndDate": "2025-11-30", "payBeginDate": "2025-11-01", "workerType": { "workerType": "W2" }, "payPeriodType": { "payPeriodType": "Regular" }, "payrollLineItems": [ { "userId": "4DF5A79A-3735-4588-95A6-B80D15CB5A5E", "userName": "Dalary Beil", "baseTotal": 4000, "numberOfLeaveDays": 0, "lop": 0, "retroAmount": 4, "grossTotal": 5236.56, "netTotal": 4879.39, "payHours": 173, "payRate": 4000, "standardWorkingHours": 8, "employeeTax": { "employeeTax": 417.17 }, "employeePayrollTransactions": [ { "transactionName": "AchCredit", "transferAmount": 4879.39, "status": "complete" } ], "employeeTaxDetails": [ { "taxName": "Federal Withholding Tax", "taxAmount": 0, "taxAmountYtd": 0, "isEmployerTax": false }, { "taxName": "Medicare", "taxAmount": 67.96, "taxAmountYtd": 0, "isEmployerTax": false }, { "taxName": "Social Security", "taxAmount": 290.57, "taxAmountYtd": 0, "isEmployerTax": false }, { "taxName": "Cares Fund EE", "taxAmount": 27.47, "taxAmountYtd": 0, "isEmployerTax": false }, { "taxName": "WA - State paid family medical leave EE", "taxAmount": 31.17, "taxAmountYtd": 0, "isEmployerTax": false } ], "employerTaxDetails": [ { "taxName": "FUTA", "taxAmount": 18, "taxAmountYtd": 0, "isEmployerTax": true }, { "taxName": "Medicare", "taxAmount": 67.96, "taxAmountYtd": 0, "isEmployerTax": true }, { "taxName": "Social Security", "taxAmount": 290.57, "taxAmountYtd": 0, "isEmployerTax": true }, { "taxName": "WA - State Unemployment Insurance", "taxAmount": 47.37, "taxAmountYtd": 0, "isEmployerTax": true }, { "taxName": "WA - State employment admin fund", "taxAmount": 0, "taxAmountYtd": 0, "isEmployerTax": true }, { "taxName": "WA - State paid family medical leave ER", "taxAmount": 0, "taxAmountYtd": 0, "isEmployerTax": true } ], "miscellaneousStateTaxes": [], "overTimes": [ { "type": "Compensatory Time Off", "amount": 232.56, "numberOfHours": 10 } ], "additionalCompensations": [ { "payrollLineItemAdditionalCompensationVertexCompensationIdentifier": { "compensationDescription": "Group Term Life Over $50000" }, "amount": 500 }, { "payrollLineItemAdditionalCompensationVertexCompensationIdentifier": { "compensationDescription": "Van Pool & Transit Passes" }, "amount": 500 } ], "deductions": [ { "vertexDeductionIdentifier": { "deductionDescription": "125DC Reg" }, "amount": 50 }, { "vertexDeductionIdentifier": { "deductionDescription": "403B CU 15 year Reg" }, "amount": 10 } ], "reimbursements": [ { "reimbursementType": "GYM", "amount": 120 } ], "timeOffs": [], "payDetails": [ { "payPercentage": 100, "amount": 4879.39, "employeePayAccount": { "accountName": "savings ... 2500" } } ] }, { "userId": "37C3B7D0-0B5B-4B48-BB76-B18DECE19994", "userName": "Yahir Greene", "baseTotal": 1200, "numberOfLeaveDays": 0, "lop": 0, "retroAmount": 0, "grossTotal": 1250, "netTotal": 1303.34, "payHours": 0, "basePay": [ { "payCode": "Deductions", "payHours": 0, "payRate": 10, "multiplier": 0, "amount": 10 }, { "payCode": "Training Hours", "payHours": 6, "payRate": 200, "multiplier": 1, "amount": 1200 }, { "payCode": "AdditionalCompensation", "payHours": 0, "payRate": 50, "multiplier": 0, "amount": 50 }, { "payCode": "Reimbursements", "payHours": 0, "payRate": 160, "multiplier": 0, "amount": 160 } ], "payRate": 0, "standardWorkingHours": 0, "employeeTax": { "employeeTax": 106.66 }, "employeePayrollTransactions": [ { "transactionName": "AchCredit", "transferAmount": 1303.34, "status": "complete" } ], "employeeTaxDetails": [ { "taxName": "Federal Withholding Tax", "taxAmount": 0, "taxAmountYtd": 0, "isEmployerTax": false }, { "taxName": "Medicare", "taxAmount": 17.4, "taxAmountYtd": 0, "isEmployerTax": false }, { "taxName": "Social Security", "taxAmount": 74.4, "taxAmountYtd": 0, "isEmployerTax": false }, { "taxName": "Cares Fund EE", "taxAmount": 6.96, "taxAmountYtd": 0, "isEmployerTax": false }, { "taxName": "WA - State paid family medical leave EE", "taxAmount": 7.9, "taxAmountYtd": 0, "isEmployerTax": false } ], "employerTaxDetails": [ { "taxName": "FUTA", "taxAmount": 7.2, "taxAmountYtd": 0, "isEmployerTax": true }, { "taxName": "Medicare", "taxAmount": 17.4, "taxAmountYtd": 0, "isEmployerTax": true }, { "taxName": "Social Security", "taxAmount": 74.4, "taxAmountYtd": 0, "isEmployerTax": true }, { "taxName": "WA - State Unemployment Insurance", "taxAmount": 12, "taxAmountYtd": 0, "isEmployerTax": true }, { "taxName": "WA - State employment admin fund", "taxAmount": 0, "taxAmountYtd": 0, "isEmployerTax": true }, { "taxName": "WA - State paid family medical leave ER", "taxAmount": 0, "taxAmountYtd": 0, "isEmployerTax": true } ], "miscellaneousStateTaxes": [], "overTimes": [], "additionalCompensations": [ { "payrollLineItemAdditionalCompensationVertexCompensationIdentifier": { "compensationDescription": "Van Pool & Transit Passes" }, "amount": 50 } ], "deductions": [], "reimbursements": [ { "reimbursementType": "GYM", "amount": 160 } ], "timeOffs": [], "payDetails": [ { "payPercentage": 100, "amount": 1303.34, "employeePayAccount": null } ] }, { "userId": "4BF5464F-0C20-465C-974D-9490770EC374", "userName": "Eve Bravo", "baseTotal": 4000, "numberOfLeaveDays": 0, "lop": 0, "retroAmount": 0, "grossTotal": 4000, "netTotal": 3644.48, "payHours": 172, "payRate": 4000, "standardWorkingHours": 8, "employeeTax": { "employeeTax": 355.52 }, "employeePayrollTransactions": [ { "transactionName": "AchCredit", "transferAmount": 3644.48, "status": "complete" } ], "employeeTaxDetails": [ { "taxName": "Federal Withholding Tax", "taxAmount": 0, "taxAmountYtd": 0, "isEmployerTax": false }, { "taxName": "Medicare", "taxAmount": 58, "taxAmountYtd": 0, "isEmployerTax": false }, { "taxName": "Social Security", "taxAmount": 248, "taxAmountYtd": 0, "isEmployerTax": false }, { "taxName": "Cares Fund EE", "taxAmount": 23.2, "taxAmountYtd": 0, "isEmployerTax": false }, { "taxName": "WA - State paid family medical leave EE", "taxAmount": 26.32, "taxAmountYtd": 0, "isEmployerTax": false } ], "employerTaxDetails": [ { "taxName": "FUTA", "taxAmount": 18, "taxAmountYtd": 0, "isEmployerTax": true }, { "taxName": "Medicare", "taxAmount": 58, "taxAmountYtd": 0, "isEmployerTax": true }, { "taxName": "Social Security", "taxAmount": 248, "taxAmountYtd": 0, "isEmployerTax": true }, { "taxName": "WA - State Unemployment Insurance", "taxAmount": 40, "taxAmountYtd": 0, "isEmployerTax": true }, { "taxName": "WA - State employment admin fund", "taxAmount": 0, "taxAmountYtd": 0, "isEmployerTax": true }, { "taxName": "WA - State paid family medical leave ER", "taxAmount": 0, "taxAmountYtd": 0, "isEmployerTax": true } ], "miscellaneousStateTaxes": [], "overTimes": [], "additionalCompensations": [], "deductions": [], "reimbursements": [], "timeOffs": [], "payDetails": [ { "payPercentage": 100, "amount": 3644.48, "employeePayAccount": null } ] } ], "companyPayrollTransactions": [ { "transactionName": "AchDebit", "transferAmount": 10426.56, "status": "complete" } ] } ] } }, "2": { "summary": "IncludeTransactions: false", "value": { "payPeriod": [ { "payPeriodId": "EDD9F5D2-BED4-4337-A80C-4DDD33EDFF91", "payPeriod": "11/01/2025 - 11/30/2025", "deadLineToRunPayroll": "2025-11-25", "PayPeriodStatus": "processed", "total": 10426.56, "employeeTaxSum": 879.35, "employerTaxSum": 898.9, "isProcessed": true, "payDate": "2025-11-28", "payEndDate": "2025-11-30", "payBeginDate": "2025-11-01", "workerType": { "workerType": "W2" }, "payPeriodType": { "payPeriodType": "Regular" }, "payrollLineItems": [ { "userId": "4DF5A79A-3735-4588-95A6-B80D15CB5A5E", "userName": "Dalary Beil", "baseTotal": 4000, "numberOfLeaveDays": 0, "lop": 0, "retroAmount": 4, "grossTotal": 5236.56, "netTotal": 4879.39, "payHours": 173, "payRate": 4000, "standardWorkingHours": 8, "employeeTax": { "employeeTax": 417.17 }, "employeeTaxDetails": [ { "taxName": "Federal Withholding Tax", "taxAmount": 0, "taxAmountYtd": 0, "isEmployerTax": false }, { "taxName": "Medicare", "taxAmount": 67.96, "taxAmountYtd": 0, "isEmployerTax": false }, { "taxName": "Social Security", "taxAmount": 290.57, "taxAmountYtd": 0, "isEmployerTax": false }, { "taxName": "Cares Fund EE", "taxAmount": 27.47, "taxAmountYtd": 0, "isEmployerTax": false }, { "taxName": "WA - State paid family medical leave EE", "taxAmount": 31.17, "taxAmountYtd": 0, "isEmployerTax": false } ], "employerTaxDetails": [ { "taxName": "FUTA", "taxAmount": 18, "taxAmountYtd": 0, "isEmployerTax": true }, { "taxName": "Medicare", "taxAmount": 67.96, "taxAmountYtd": 0, "isEmployerTax": true }, { "taxName": "Social Security", "taxAmount": 290.57, "taxAmountYtd": 0, "isEmployerTax": true }, { "taxName": "WA - State Unemployment Insurance", "taxAmount": 47.37, "taxAmountYtd": 0, "isEmployerTax": true }, { "taxName": "WA - State employment admin fund", "taxAmount": 0, "taxAmountYtd": 0, "isEmployerTax": true }, { "taxName": "WA - State paid family medical leave ER", "taxAmount": 0, "taxAmountYtd": 0, "isEmployerTax": true } ], "miscellaneousStateTaxes": [], "overTimes": [ { "type": "Compensatory Time Off", "amount": 232.56, "numberOfHours": 10 } ], "additionalCompensations": [ { "payrollLineItemAdditionalCompensationVertexCompensationIdentifier": { "compensationDescription": "Group Term Life Over $50000" }, "amount": 500 }, { "payrollLineItemAdditionalCompensationVertexCompensationIdentifier": { "compensationDescription": "Van Pool & Transit Passes" }, "amount": 500 } ], "deductions": [ { "vertexDeductionIdentifier": { "deductionDescription": "125DC Reg" }, "amount": 50 }, { "vertexDeductionIdentifier": { "deductionDescription": "403B CU 15 year Reg" }, "amount": 10 } ], "reimbursements": [ { "reimbursementType": "GYM", "amount": 120 } ], "timeOffs": [], "payDetails": [ { "payPercentage": 100, "amount": 4879.39, "employeePayAccount": { "accountName": "savings ... 2500" } } ] }, { "userId": "37C3B7D0-0B5B-4B48-BB76-B18DECE19994", "userName": "Yahir Greene", "baseTotal": 1200, "numberOfLeaveDays": 0, "lop": 0, "retroAmount": 0, "grossTotal": 1250, "netTotal": 1303.34, "payHours": 0, "basePay": [ { "payCode": "Deductions", "payHours": 0, "payRate": 10, "multiplier": 0, "amount": 10 }, { "payCode": "Training Hours", "payHours": 6, "payRate": 200, "multiplier": 1, "amount": 1200 }, { "payCode": "AdditionalCompensation", "payHours": 0, "payRate": 50, "multiplier": 0, "amount": 50 }, { "payCode": "Reimbursements", "payHours": 0, "payRate": 160, "multiplier": 0, "amount": 160 } ], "payRate": 0, "standardWorkingHours": 0, "employeeTax": { "employeeTax": 106.66 }, "employeeTaxDetails": [ { "taxName": "Federal Withholding Tax", "taxAmount": 0, "taxAmountYtd": 0, "isEmployerTax": false }, { "taxName": "Medicare", "taxAmount": 17.4, "taxAmountYtd": 0, "isEmployerTax": false }, { "taxName": "Social Security", "taxAmount": 74.4, "taxAmountYtd": 0, "isEmployerTax": false }, { "taxName": "Cares Fund EE", "taxAmount": 6.96, "taxAmountYtd": 0, "isEmployerTax": false }, { "taxName": "WA - State paid family medical leave EE", "taxAmount": 7.9, "taxAmountYtd": 0, "isEmployerTax": false } ], "employerTaxDetails": [ { "taxName": "FUTA", "taxAmount": 7.2, "taxAmountYtd": 0, "isEmployerTax": true }, { "taxName": "Medicare", "taxAmount": 17.4, "taxAmountYtd": 0, "isEmployerTax": true }, { "taxName": "Social Security", "taxAmount": 74.4, "taxAmountYtd": 0, "isEmployerTax": true }, { "taxName": "WA - State Unemployment Insurance", "taxAmount": 12, "taxAmountYtd": 0, "isEmployerTax": true }, { "taxName": "WA - State employment admin fund", "taxAmount": 0, "taxAmountYtd": 0, "isEmployerTax": true }, { "taxName": "WA - State paid family medical leave ER", "taxAmount": 0, "taxAmountYtd": 0, "isEmployerTax": true } ], "miscellaneousStateTaxes": [], "overTimes": [], "additionalCompensations": [ { "payrollLineItemAdditionalCompensationVertexCompensationIdentifier": { "compensationDescription": "Van Pool & Transit Passes" }, "amount": 50 } ], "deductions": [], "reimbursements": [ { "reimbursementType": "GYM", "amount": 160 } ], "timeOffs": [], "payDetails": [ { "payPercentage": 100, "amount": 1303.34, "employeePayAccount": null } ] }, { "userId": "4BF5464F-0C20-465C-974D-9490770EC374", "userName": "Eve Bravo", "baseTotal": 4000, "numberOfLeaveDays": 0, "lop": 0, "retroAmount": 0, "grossTotal": 4000, "netTotal": 3644.48, "payHours": 172, "payRate": 4000, "standardWorkingHours": 8, "employeeTax": { "employeeTax": 355.52 }, "employeeTaxDetails": [ { "taxName": "Federal Withholding Tax", "taxAmount": 0, "taxAmountYtd": 0, "isEmployerTax": false }, { "taxName": "Medicare", "taxAmount": 58, "taxAmountYtd": 0, "isEmployerTax": false }, { "taxName": "Social Security", "taxAmount": 248, "taxAmountYtd": 0, "isEmployerTax": false }, { "taxName": "Cares Fund EE", "taxAmount": 23.2, "taxAmountYtd": 0, "isEmployerTax": false }, { "taxName": "WA - State paid family medical leave EE", "taxAmount": 26.32, "taxAmountYtd": 0, "isEmployerTax": false } ], "employerTaxDetails": [ { "taxName": "FUTA", "taxAmount": 18, "taxAmountYtd": 0, "isEmployerTax": true }, { "taxName": "Medicare", "taxAmount": 58, "taxAmountYtd": 0, "isEmployerTax": true }, { "taxName": "Social Security", "taxAmount": 248, "taxAmountYtd": 0, "isEmployerTax": true }, { "taxName": "WA - State Unemployment Insurance", "taxAmount": 40, "taxAmountYtd": 0, "isEmployerTax": true }, { "taxName": "WA - State employment admin fund", "taxAmount": 0, "taxAmountYtd": 0, "isEmployerTax": true }, { "taxName": "WA - State paid family medical leave ER", "taxAmount": 0, "taxAmountYtd": 0, "isEmployerTax": true } ], "miscellaneousStateTaxes": [], "overTimes": [], "additionalCompensations": [], "deductions": [], "reimbursements": [], "timeOffs": [], "payDetails": [ { "payPercentage": 100, "amount": 3644.48, "employeePayAccount": null } ] } ] } ] } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 204, "message": "Invalid PayPeriod" } } } }, "headers": {} } }, "security": [] } }, "/reports/getPayRun": { "get": { "summary": "getPayRun", "deprecated": false, "description": "\nThe `getPayRun` API retrieves payroll line item information for a specific pay period.\n\n### What it does:\n\n- Returns payroll line items including user ID, total hours, wages and taxes\n- Provides at-a-glance payroll data for all employees within a specific pay period\n- Provides cash requirements after all withholdings, deductions, taxes and credits for each employee to be paid successfully", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "getPayRun" ], "title": "getPayRun" }, "payPeriodId": { "type": "string", "format": "uuid" } }, "required": [ "method", "payPeriodId" ] }, "example": { "method": "getPayRun", "payPeriodId": "1701499A-1F6A-4D96-9A45-2021A19777E6" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "payrollLineItems": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "totalHours": { "type": "integer" }, "wages": { "type": "integer" }, "taxes": { "type": "number" }, "cash requirements": { "type": "integer" } }, "required": [ "userId", "totalHours", "wages", "taxes", "cash requirements" ] } } }, "required": [ "payrollLineItems" ] }, "example": { "payrollLineItems": [ { "userId": "50070F09-2923-499A-850B-F12ED4C2FD69", "totalHours": 40, "wages": 960, "taxes": 129.99, "cash requirements": 960 }, { "userId": "9E3CBA77-9035-471F-AA1E-F77A13AFE5C2", "totalHours": 40, "wages": 2000, "taxes": 429.74, "cash requirements": 2000 } ] } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid Payperiod" } } } }, "headers": {} } }, "security": [] } }, "/reports/getPayrollHistoryBasedOnPayPeriod": { "get": { "summary": "getPayrollHistoryBasedOnPayPeriod", "deprecated": false, "description": "\nThe `getPayrollHistoryBasedOnPayPeriod` API retrieves complete payroll history for a specific pay period.\n\n### What it does:\n\n- Returns detailed payroll information for all employees within a specific pay period\n- Provides payroll line items including wages, taxes, deductions, and net pay for the specified pay period\n\n### Note:\n\n- For requests encompassing a single pay period (duration defined when payroll was set up)", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "getPayrollHistoryBasedOnPayPeriod" ], "title": "getPayrollHistoryBasedOnPayPeriod" }, "payPeriodId": { "type": "string", "format": "uuid" } }, "required": [ "method", "payPeriodId" ] }, "example": { "method": "getPayrollHistoryBasedOnPayPeriod", "payPeriodId": "FD8B55C3-FB80-4DF3-89DF-D48E65750BF2" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "payPeriod": { "type": "array", "items": { "type": "object", "properties": { "payPeriodId": { "type": "string" }, "payPeriod": { "type": "string" }, "deadLineToRunPayroll": { "type": "string" }, "total": { "type": "number" }, "employeeTaxSum": { "type": "number" }, "employerTaxSum": { "type": "number" }, "isProcessed": { "type": "boolean" }, "payDate": { "type": "string" }, "payEndDate": { "type": "string" }, "payBeginDate": { "type": "string" }, "workerType": { "type": "string" }, "payrollLineItems": { "type": "array", "items": { "type": "object", "properties": { "baseTotal": { "type": "number" }, "numberOfLeaveDays": { "type": "integer" }, "lop": { "type": "integer" }, "retroAmount": { "type": "integer" }, "grossTotal": { "type": "number" }, "netTotal": { "type": "number" }, "userId": { "type": "string" }, "employee": { "type": "string" }, "employeeTax": { "type": "number" }, "payrollLineItemDeductions": { "type": "array", "items": { "type": "string" } }, "payDetails": { "type": "array", "items": { "type": "object", "properties": { "payPercentage": { "type": "integer" }, "amount": { "type": "number" }, "employeePayAccount": { "type": "string" } } } }, "payrollLineItemOverTimes": { "type": "array", "items": { "type": "string" } }, "payrollLineItemAdditionalCompensations": { "type": "array", "items": { "type": "string" } } } } } } } } }, "required": [ "payPeriod" ] }, "example": { "payPeriod": [ { "payPeriodId": "FD8B55C3-FB80-4DF3-89DF-D48E65750BF2", "payPeriod": "06/15/2025 - 06/28/2025", "deadLineToRunPayroll": "2025-06-27", "total": 4.62, "employeeTaxSum": 0.36, "employerTaxSum": 0.48, "isProcessed": true, "payDate": "2025-07-01", "payEndDate": "2025-06-28", "payBeginDate": "2025-06-15", "workerType": "W2", "payrollLineItems": [ { "baseTotal": 4.62, "numberOfLeaveDays": 0, "lop": 0, "retroAmount": 0, "grossTotal": 4.62, "netTotal": 4.26, "userId": "C88011F6-954A-445B-B5B5-EAFCCBA95D98", "employee": "Jad Abisaleh", "employeeTax": 0.36, "payrollLineItemDeductions": [], "payDetails": [ { "payPercentage": 100, "amount": 4.26, "employeePayAccount": "savings ... 1111" } ], "payrollLineItemOverTimes": [], "payrollLineItemAdditionalCompensations": [] } ] } ] } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid WorkerType" } } } }, "headers": {} } }, "security": [] } }, "/reports/getPayrollHistoryBasedOnDateRange": { "get": { "summary": "getPayrollHistoryBasedOnDateRange", "deprecated": false, "description": "\nThe `getPayrollHistoryBasedOnDateRange` API retrieves payroll history for all pay periods within a specified date range.\n\n### What it does:\n\n- Returns pay period details and payroll line items for all employees within the specified date range\n- Provides comprehensive payroll data including wages, taxes, deductions, and net pay across multiple pay periods\n- Requests can encompass multiple pay periods and partial pay periods - start dates and end dates for requests are not limited", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "getPayrollHistoryBasedOnDateRange" ], "title": "getPayrollHistoryBasedOnDateRange" }, "companyId": { "type": "string", "format": "uuid" }, "startDate": { "type": "string", "maxLength": 10 }, "endDate": { "type": "string", "maxLength": 10 } }, "required": [ "method", "companyId", "startDate", "endDate" ] }, "example": { "method": "getPayrollHistoryBasedOnDateRange", "companyId": "32cef965-3a70-4ee0-b943-ad2fb876a839", "startDate": "2023-01-01", "endDate": "2023-12-31" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "payPeriod": { "type": "array", "items": { "type": "object", "properties": { "payPeriodId": { "type": "string" }, "payPeriod": { "type": "string" }, "deadLineToRunPayroll": { "type": "string" }, "total": { "type": "integer" }, "employeeTaxSum": { "type": "number" }, "employerTaxSum": { "type": "number" }, "isProcessed": { "type": "boolean" }, "payDate": { "type": "string" }, "payEndDate": { "type": "string" }, "payBeginDate": { "type": "string" }, "workerType": { "type": "object", "properties": { "workerType": { "type": "string" } }, "required": [ "workerType" ] }, "payrollLineItems": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "baseTotal": { "type": "integer" }, "numberOfLeaveDays": { "type": "integer" }, "lop": { "type": "integer" }, "retroAmount": { "type": "integer" }, "grossTotal": { "type": "integer" }, "netTotal": { "type": "number" }, "userName": { "type": "object", "properties": { "employee": { "type": "string" } }, "required": [ "employee" ] }, "employeeTax": { "type": "object", "properties": { "employeeTax": { "type": "number" } }, "required": [ "employeeTax" ] }, "Deductions": { "type": "array", "items": { "type": "object", "properties": { "vertexDeductionIdentifier": { "type": "object", "properties": { "deductionDescription": { "type": "string" } }, "required": [ "deductionDescription" ] }, "amount": { "type": "integer" } }, "required": [ "vertexDeductionIdentifier", "amount" ] } }, "payDetails": { "type": "array", "items": { "type": "object", "properties": { "payPercentage": { "type": "integer" }, "amount": { "type": [ "integer", "number" ] }, "employeePayAccount": { "type": "object", "properties": { "accountName": { "type": [ "string", "null" ] } }, "required": [ "accountName" ] } }, "required": [ "payPercentage", "amount", "employeePayAccount" ] } }, "OverTimes": { "type": "array", "items": { "type": "string" } }, "AdditionalCompensations": { "type": "array", "items": { "type": "object", "properties": { "payrollLineItemAdditionalCompensation_VertexCompensationIdentifier": { "type": "object", "properties": { "compensationDescription": { "type": "string" } }, "required": [ "compensationDescription" ] }, "amount": { "type": "integer" } }, "required": [ "payrollLineItemAdditionalCompensation_VertexCompensationIdentifier", "amount" ] } } }, "required": [ "userId", "baseTotal", "numberOfLeaveDays", "lop", "retroAmount", "grossTotal", "netTotal", "userName", "employeeTax", "Deductions", "payDetails", "OverTimes", "AdditionalCompensations" ] } } } } } }, "required": [ "payPeriod" ] }, "example": { "payPeriod": [ { "payPeriodId": "EFAB1DAB-5646-4DF5-8EA2-C4D42C37811E", "payPeriod": "11/16/2023 - 11/30/2023", "deadLineToRunPayroll": "2023-11-28", "total": 2910, "employeeTaxSum": 574.18, "employerTaxSum": 493.73, "isProcessed": true, "payDate": "2023-11-30", "payEndDate": "2023-11-30", "payBeginDate": "2023-11-16", "workerType": { "workerType": "W2" }, "payrollLineItems": [ { "userId": "50070F09-2923-499A-850B-F12ED4C2FD69", "baseTotal": 960, "numberOfLeaveDays": 0, "lop": 0, "retroAmount": 0, "grossTotal": 940, "netTotal": 810.01, "userName": { "employee": "Ron Wood" }, "employeeTax": { "employeeTax": 129.99 }, "Deductions": [ { "vertexDeductionIdentifier": { "deductionDescription": "Qualified Parking Sup" }, "amount": 120 } ], "payDetails": [ { "payPercentage": 0, "amount": 0, "employeePayAccount": { "accountName": "savings ... 1111" } }, { "payPercentage": 100, "amount": 810.01, "employeePayAccount": { "accountName": null } } ], "OverTimes": [], "AdditionalCompensations": [ { "payrollLineItemAdditionalCompensation_VertexCompensationIdentifier": { "compensationDescription": "Cash" }, "amount": 100 } ] }, { "userId": "9E3CBA77-9035-471F-AA1E-F77A13AFE5C2", "baseTotal": 2000, "numberOfLeaveDays": 0, "lop": 0, "retroAmount": 0, "grossTotal": 1970, "netTotal": 1540.26, "userName": { "employee": "Mark sazav Steve" }, "employeeTax": { "employeeTax": 429.74 }, "Deductions": [ { "vertexDeductionIdentifier": { "deductionDescription": "Qualified Parking Sup" }, "amount": 150 } ], "payDetails": [ { "payPercentage": 100, "amount": 1540.26, "employeePayAccount": { "accountName": "checking ... 0000" } } ], "OverTimes": [], "AdditionalCompensations": [ { "payrollLineItemAdditionalCompensation_VertexCompensationIdentifier": { "compensationDescription": "Cash" }, "amount": 120 } ] } ] } ] } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid CompanyId" } } } }, "headers": {} } }, "security": [] } }, "/reports/getUnProcessedPayPeriod": { "get": { "summary": "getUnProcessedPayPeriod", "deprecated": false, "description": "\nThe `getUnProcessedPayPeriod` API retrieves pay periods that have not yet been processed for payroll.\n\n### What it does:\n\n- Returns pay periods that have not completed processing\n- Provides pay period details for periods awaiting payroll processing including key dates and deadline to run payroll\n\n### Notes:\n- Used to identify pay periods that are available for processing with `initiatePayroll`\n- Returns payPeriods that are **submitted** but not yet paid out, and payPeriods that are editable\n- Uses optional **workerType** to filter by W2 or 1099-NEC or can be used to return both", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "workerType": { "type": "string" } }, "required": [ "method", "companyId" ] }, "example": { "method": "getUnProcessedPayPeriod", "companyId": "2DFCA586-C2D4-4FD7-B823-063F2575A5E7", "workerType": "W2" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "unprocessedPayPeriods": { "type": "array", "items": { "type": "object", "properties": { "payPeriodId": { "type": "string" }, "payPeriod": { "type": "string" }, "payPeriodType": { "type": "string" }, "payBeginDate": { "type": "string" }, "payEndDate": { "type": "string" }, "payDate": { "type": "string" }, "deadLineToRunPayroll": { "type": "string" }, "payPeriodStatus": { "type": "string" }, "workerType": { "type": "string" } }, "required": [ "payPeriodId", "payPeriod", "payPeriodType", "payBeginDate", "payEndDate", "payDate", "deadLineToRunPayroll", "payPeriodStatus", "workerType" ] } } }, "required": [ "unprocessedPayPeriods" ] }, "example": { "unprocessedPayPeriods": [ { "payPeriodId": "080EA408-D041-4C43-A745-9337AAEB9EAF", "payPeriod": "09/17/2025 - 09/23/2025", "payPeriodType": "Regular", "payBeginDate": "2025-09-17", "payEndDate": "2025-09-23", "payDate": "2026-03-11", "deadLineToRunPayroll": "2025-09-19", "payPeriodStatus": "new", "workerType": "1099-NEC" }, { "payPeriodId": "EDCDB86C-337A-4CA9-88AB-48750BE757D4", "payPeriod": "03/16/2026 - 03/31/2026", "payPeriodType": "Regular", "payBeginDate": "2026-03-16", "payEndDate": "2026-03-31", "payDate": "2026-03-31", "deadLineToRunPayroll": "2026-03-27", "payPeriodStatus": "new", "workerType": "W2" }, { "payPeriodId": "8EF7603A-8ECF-40E4-82E8-2C5FC5528D5F", "payPeriod": "02/02/2026 - 02/09/2026", "payPeriodType": "Off-Cycle", "payBeginDate": "2026-02-02", "payEndDate": "2026-02-09", "payDate": "2026-04-01", "deadLineToRunPayroll": "2026-03-30", "payPeriodStatus": "new", "workerType": "W2" }, { "payPeriodId": "CC4D8605-1FA4-4EB9-9E57-9EBEF1AFD703", "payPeriod": "03/09/2026 - 03/23/2026", "payPeriodType": "Off-Cycle", "payBeginDate": "2026-03-09", "payEndDate": "2026-03-23", "payDate": "2026-04-01", "deadLineToRunPayroll": "2026-03-30", "payPeriodStatus": "new", "workerType": "W2" }, { "payPeriodId": "7F52523F-EBF0-40BD-87D4-20E82AF5AD95", "payPeriod": "02/02/2026 - 03/24/2026", "payPeriodType": "Off-Cycle", "payBeginDate": "2026-02-02", "payEndDate": "2026-03-24", "payDate": "2026-04-02", "deadLineToRunPayroll": "2026-03-31", "payPeriodStatus": "new", "workerType": "W2" }, { "payPeriodId": "3BBB82F7-FDF0-4CAE-BF39-5611D8D6E304", "payPeriod": "03/31/2026 - 03/31/2026", "payPeriodType": "Missing", "payBeginDate": "2026-03-31", "payEndDate": "2026-03-31", "payDate": "2026-04-03", "deadLineToRunPayroll": "2026-04-01", "payPeriodStatus": "new", "workerType": "W2" }, { "payPeriodId": "329ED801-CE87-42F3-87AE-59AA65E007C6", "payPeriod": "03/30/2026 - 03/30/2026", "payPeriodType": "Missing", "payBeginDate": "2026-03-30", "payEndDate": "2026-03-30", "payDate": "2026-04-03", "deadLineToRunPayroll": "2026-04-01", "payPeriodStatus": "new", "workerType": "W2" }, { "payPeriodId": "DC815FD5-B8BA-4021-A51D-2DD2FF2971B4", "payPeriod": "05/19/2026 - 05/25/2026", "payPeriodType": "Missing", "payBeginDate": "2026-05-19", "payEndDate": "2026-05-25", "payDate": "2026-05-20", "deadLineToRunPayroll": "2026-05-18", "payPeriodStatus": "new", "workerType": "W2" } ] } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid WorkerType" } } } }, "headers": {} } }, "security": [] } }, "/reports/getProcessedPayperiodsDetails": { "get": { "summary": "getProcessedPayperiodsDetails", "deprecated": false, "description": "\nThe `getProcessedPayPeriods` API retrieves all pay periods that have been processed for a company.\n\n### What it does:\n\n- Returns a list of completed pay periods with their associated IDs\n- Provides date range, start date, end date, payroll deadline and workerType for each completed pay period\n\n### Note:\n\n- `getPayPeriodDetails` can be used to retrieve more in-depth information for a completed pay period using the **payPeriodIDs** returned by this API", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "workerType": { "type": "string" } }, "required": [ "method", "companyId" ] }, "example": { "method": "getProcessedPayperiodsDetails", "companyId": "4934E42A-F448-4AF5-8273-850ECF17647C", "workerType": "W2" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "processedPayPeriods": { "type": "array", "items": { "type": "object", "properties": { "payPeriodId": { "type": "string" }, "payPeriod": { "type": "string" }, "payPeriodType": { "type": "string" }, "payBeginDate": { "type": "string" }, "payEndDate": { "type": "string" }, "payDate": { "type": "string" }, "deadLineToRunPayroll": { "type": "string" }, "workerType": { "type": "string" } } } } }, "required": [ "processedPayPeriods" ] }, "example": { "processedPayPeriods": [ { "payPeriodId": "5D23FFB1-A33D-453C-BBBA-15D3320B9D70", "payPeriod": "06/11/2024 - 06/24/2024", "payPeriodType": "Regular", "payBeginDate": "2024-06-11", "payEndDate": "2024-06-24", "payDate": "2024-06-25", "deadLineToRunPayroll": "2024-06-21", "workerType": "W2" } ] } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid WorkerType" } } } }, "headers": {} } }, "security": [] } }, "/reports/getTransactions": { "get": { "summary": "getTransactions", "deprecated": false, "description": "\nThe `getTransactions` API retrieves all payroll transaction records for a specific pay period.\n\n### What it does:\n\n- Returns all payment transactions related to a pay period within a payroll\n- Provides transaction details including source, destination, amounts, and status for all payments processed\n- Shows complete transaction history for direct deposits, tax payments, and other payroll-related transfers", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "getTransactions" ], "title": "getTransactions" }, "payPeriodId": { "type": "string", "minLength": 2, "format": "uuid" } }, "required": [ "method", "payPeriodId" ], "x--orders": [ "method", " PayrollTransaction " ] }, "example": { "method": "getTransactionsBasedOnName", "payPeriodId": "2AF56831-2841-438D-9722-E097AC1CCCAC" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "payrollTransaction": { "type": "array", "items": { "type": "object", "properties": { "requestReferenceId": { "type": "string" }, "companyId": { "type": "string" }, "payPeriodId": { "type": "string" }, "source": { "type": "string" }, "sourceAccount": { "type": "string" }, "destination": { "type": "string" }, "destinationAccount": { "type": "string" }, "transactionName": { "type": "string" }, "transferAmount": { "type": "number" }, "status": { "type": "string" } }, "required": [ "requestReferenceId", "companyId", "payPeriodId", "source", "sourceAccount", "destination", "destinationAccount", "transactionName", "transferAmount", "status" ] } } }, "required": [ "payrollTransaction" ] }, "example": { "payrollTransaction": [ { "requestReferenceId": "5244157", "companyId": "C2019899-9EEF-49F7-9B51-70744AFAFE61", "payPeriodId": "2AF56831-2841-438D-9722-E097AC1CCCAC", "source": "Ledger", "sourceAccount": "A4567F07-CB88-4973-8A60-0AF2F9512C41", "destination": "EmployeeBankAccount", "destinationAccount": "ADAB2624-0DC9-4151-A4D5-00C83851F8BA", "transactionName": "AchCredit", "transferAmount": 3624.48, "status": "complete" }, { "requestReferenceId": "5244151", "companyId": "C2019899-9EEF-49F7-9B51-70744AFAFE61", "payPeriodId": "2AF56831-2841-438D-9722-E097AC1CCCAC", "source": "Ledger", "sourceAccount": "A4567F07-CB88-4973-8A60-0AF2F9512C41", "destination": "EmployeeBankAccount", "destinationAccount": "132F5B54-D23B-458B-8F69-1F08F0FA7A23", "transactionName": "AchCredit", "transferAmount": 14988.62, "status": "complete" }, { "requestReferenceId": "5244154", "companyId": "C2019899-9EEF-49F7-9B51-70744AFAFE61", "payPeriodId": "2AF56831-2841-438D-9722-E097AC1CCCAC", "source": "Ledger", "sourceAccount": "A4567F07-CB88-4973-8A60-0AF2F9512C41", "destination": "EmployeeBankAccount", "destinationAccount": "4391AD1B-51D2-42F3-B815-D5F3D68A5DC7", "transactionName": "AchCredit", "transferAmount": 10244.69, "status": "complete" }, { "requestReferenceId": "5244153", "companyId": "C2019899-9EEF-49F7-9B51-70744AFAFE61", "payPeriodId": "2AF56831-2841-438D-9722-E097AC1CCCAC", "source": "Ledger", "sourceAccount": "A4567F07-CB88-4973-8A60-0AF2F9512C41", "destination": "EmployeeBankAccount", "destinationAccount": "4EFC8423-667B-4389-9DE2-8D56ACCD7BF8", "transactionName": "AchCredit", "transferAmount": 14151.46, "status": "complete" }, { "requestReferenceId": "5244155", "companyId": "C2019899-9EEF-49F7-9B51-70744AFAFE61", "payPeriodId": "2AF56831-2841-438D-9722-E097AC1CCCAC", "source": "Ledger", "sourceAccount": "A4567F07-CB88-4973-8A60-0AF2F9512C41", "destination": "EmployeeBankAccount", "destinationAccount": "98A73017-2B14-4C17-A986-320DA48C0C5B", "transactionName": "AchCredit", "transferAmount": 9975.36, "status": "complete" }, { "requestReferenceId": "5244158", "companyId": "C2019899-9EEF-49F7-9B51-70744AFAFE61", "payPeriodId": "2AF56831-2841-438D-9722-E097AC1CCCAC", "source": "Ledger", "sourceAccount": "A4567F07-CB88-4973-8A60-0AF2F9512C41", "destination": "EmployeeBankAccount", "destinationAccount": "04FE795D-76EB-438C-9CC7-7BA7BD98D6CA", "transactionName": "AchCredit", "transferAmount": 9958.75, "status": "pending" }, { "requestReferenceId": "5244156", "companyId": "C2019899-9EEF-49F7-9B51-70744AFAFE61", "payPeriodId": "2AF56831-2841-438D-9722-E097AC1CCCAC", "source": "Ledger", "sourceAccount": "A4567F07-CB88-4973-8A60-0AF2F9512C41", "destination": "EmployeeBankAccount", "destinationAccount": "F1830475-EFCF-4A6E-A6FB-682F61898537", "transactionName": "AchCredit", "transferAmount": 14246.53, "status": "complete" }, { "requestReferenceId": "5244150", "companyId": "C2019899-9EEF-49F7-9B51-70744AFAFE61", "payPeriodId": "2AF56831-2841-438D-9722-E097AC1CCCAC", "source": "Ledger", "sourceAccount": "A4567F07-CB88-4973-8A60-0AF2F9512C41", "destination": "EmployeeBankAccount", "destinationAccount": "D48DA316-ED8C-4815-B0EC-14057D344951", "transactionName": "AchCredit", "transferAmount": 3644.48, "status": "complete" }, { "requestReferenceId": "5243486", "companyId": "C2019899-9EEF-49F7-9B51-70744AFAFE61", "payPeriodId": "2AF56831-2841-438D-9722-E097AC1CCCAC", "source": "EmployerBankAccount", "sourceAccount": "1111222233331111", "destination": "Ledger", "destinationAccount": "76650000049771", "transactionName": "AchDebit", "transferAmount": 101741.64, "status": "complete" }, { "requestReferenceId": "5244152", "companyId": "C2019899-9EEF-49F7-9B51-70744AFAFE61", "payPeriodId": "2AF56831-2841-438D-9722-E097AC1CCCAC", "source": "Ledger", "sourceAccount": "A4567F07-CB88-4973-8A60-0AF2F9512C41", "destination": "EmployeeBankAccount", "destinationAccount": "90A22A2C-5DB3-4BBE-A2CA-31E0D37D6356", "transactionName": "AchCredit", "transferAmount": 3897.82, "status": "complete" } ] } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid PayPeriodId" } } } }, "headers": {} } }, "security": [] } }, "/reports/getTransactionsBasedOnName": { "get": { "summary": "getTransactionsBasedOnName", "deprecated": false, "description": "\nThe `getTransactionsBasedOnName` API retrieves payroll transaction details based on a specific transaction name within a pay period.\n\n### What it does:\n\n- Returns transaction details including source, destination, amounts, and status for transactions matching the specified name\n- Provides filtered payroll transaction information for specific transaction types within a pay period", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "getTransactionsBasedOnName" ], "title": "getTransactionsBasedOnName" }, "payPeriodId": { "type": "string", "format": "uuid" }, "transactionName": { "type": "string", "maxLength": 15 } }, "required": [ "method", "payPeriodId", "transactionName" ] }, "example": { "method": "getTransactionsBasedOnName", "payPeriodId": "2AF56831-2841-438D-9722-E097AC1CCCAC", "transactionName": "AchCredit" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "payrollTransaction": { "type": "array", "items": { "type": "object", "properties": { "requestReferenceId": { "type": "string" }, "companyId": { "type": "string" }, "payPeriodId": { "type": "string" }, "source": { "type": "string" }, "sourceAccount": { "type": "string" }, "destination": { "type": "string" }, "destinationAccount": { "type": "string" }, "transactionName": { "type": "string" }, "transferAmount": { "type": "number" }, "status": { "type": "string" } }, "required": [ "requestReferenceId", "companyId", "payPeriodId", "source", "sourceAccount", "destination", "destinationAccount", "transactionName", "transferAmount", "status" ] } } }, "required": [ "payrollTransaction" ] }, "example": { "payrollTransaction": [ { "requestReferenceId": "5244157", "companyId": "C2019899-9EEF-49F7-9B51-70744AFAFE61", "payPeriodId": "2AF56831-2841-438D-9722-E097AC1CCCAC", "source": "Ledger", "sourceAccount": "A4567F07-CB88-4973-8A60-0AF2F9512C41", "destination": "EmployeeBankAccount", "destinationAccount": "ADAB2624-0DC9-4151-A4D5-00C83851F8BA", "transactionName": "AchCredit", "transferAmount": 3624.48, "status": "complete" }, { "requestReferenceId": "5244151", "companyId": "C2019899-9EEF-49F7-9B51-70744AFAFE61", "payPeriodId": "2AF56831-2841-438D-9722-E097AC1CCCAC", "source": "Ledger", "sourceAccount": "A4567F07-CB88-4973-8A60-0AF2F9512C41", "destination": "EmployeeBankAccount", "destinationAccount": "132F5B54-D23B-458B-8F69-1F08F0FA7A23", "transactionName": "AchCredit", "transferAmount": 14988.62, "status": "complete" }, { "requestReferenceId": "5244154", "companyId": "C2019899-9EEF-49F7-9B51-70744AFAFE61", "payPeriodId": "2AF56831-2841-438D-9722-E097AC1CCCAC", "source": "Ledger", "sourceAccount": "A4567F07-CB88-4973-8A60-0AF2F9512C41", "destination": "EmployeeBankAccount", "destinationAccount": "4391AD1B-51D2-42F3-B815-D5F3D68A5DC7", "transactionName": "AchCredit", "transferAmount": 10244.69, "status": "complete" }, { "requestReferenceId": "5244153", "companyId": "C2019899-9EEF-49F7-9B51-70744AFAFE61", "payPeriodId": "2AF56831-2841-438D-9722-E097AC1CCCAC", "source": "Ledger", "sourceAccount": "A4567F07-CB88-4973-8A60-0AF2F9512C41", "destination": "EmployeeBankAccount", "destinationAccount": "4EFC8423-667B-4389-9DE2-8D56ACCD7BF8", "transactionName": "AchCredit", "transferAmount": 14151.46, "status": "complete" }, { "requestReferenceId": "5244155", "companyId": "C2019899-9EEF-49F7-9B51-70744AFAFE61", "payPeriodId": "2AF56831-2841-438D-9722-E097AC1CCCAC", "source": "Ledger", "sourceAccount": "A4567F07-CB88-4973-8A60-0AF2F9512C41", "destination": "EmployeeBankAccount", "destinationAccount": "98A73017-2B14-4C17-A986-320DA48C0C5B", "transactionName": "AchCredit", "transferAmount": 9975.36, "status": "complete" }, { "requestReferenceId": "5244158", "companyId": "C2019899-9EEF-49F7-9B51-70744AFAFE61", "payPeriodId": "2AF56831-2841-438D-9722-E097AC1CCCAC", "source": "Ledger", "sourceAccount": "A4567F07-CB88-4973-8A60-0AF2F9512C41", "destination": "EmployeeBankAccount", "destinationAccount": "04FE795D-76EB-438C-9CC7-7BA7BD98D6CA", "transactionName": "AchCredit", "transferAmount": 9958.75, "status": "pending" }, { "requestReferenceId": "5244156", "companyId": "C2019899-9EEF-49F7-9B51-70744AFAFE61", "payPeriodId": "2AF56831-2841-438D-9722-E097AC1CCCAC", "source": "Ledger", "sourceAccount": "A4567F07-CB88-4973-8A60-0AF2F9512C41", "destination": "EmployeeBankAccount", "destinationAccount": "F1830475-EFCF-4A6E-A6FB-682F61898537", "transactionName": "AchCredit", "transferAmount": 14246.53, "status": "complete" }, { "requestReferenceId": "5244150", "companyId": "C2019899-9EEF-49F7-9B51-70744AFAFE61", "payPeriodId": "2AF56831-2841-438D-9722-E097AC1CCCAC", "source": "Ledger", "sourceAccount": "A4567F07-CB88-4973-8A60-0AF2F9512C41", "destination": "EmployeeBankAccount", "destinationAccount": "D48DA316-ED8C-4815-B0EC-14057D344951", "transactionName": "AchCredit", "transferAmount": 3644.48, "status": "complete" }, { "requestReferenceId": "5244152", "companyId": "C2019899-9EEF-49F7-9B51-70744AFAFE61", "payPeriodId": "2AF56831-2841-438D-9722-E097AC1CCCAC", "source": "Ledger", "sourceAccount": "A4567F07-CB88-4973-8A60-0AF2F9512C41", "destination": "EmployeeBankAccount", "destinationAccount": "90A22A2C-5DB3-4BBE-A2CA-31E0D37D6356", "transactionName": "AchCredit", "transferAmount": 3897.82, "status": "complete" } ] } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid PayPeriodId" } } } }, "headers": {} } }, "security": [] } }, "/reports/getTransactionBasedOnReference": { "get": { "summary": "getTransactionBasedOnReference", "deprecated": false, "description": "\nThe `getTransactionBasedOnReference` API retrieves payroll transaction details based on a specific request reference ID.\n\n### What it does:\n\n- Returns transaction details including source, destination, amounts, and status for a specific reference ID\n- Provides payroll transaction information filtered by request reference ID", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "getTransactionBasedOnReference" ], "title": "getTransactionBasedOnReference" }, "requestReferenceId": { "type": "string" } }, "required": [ "method", "requestReferenceId" ] }, "example": { "method": "getTransactionsBasedOnReference", "requestReferenceId": "5244157" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "payrollTransaction": { "type": "array", "items": { "type": "object", "properties": { "requestReferenceId": { "type": "string" }, "companyId": { "type": "string" }, "payPeriodId": { "type": "string" }, "source": { "type": "string" }, "sourceAccount": { "type": "string" }, "destination": { "type": "string" }, "destinationAccount": { "type": "string" }, "transactionName": { "type": "string" }, "transferAmount": { "type": "number" }, "status": { "type": "string" } }, "required": [ "requestReferenceId", "companyId", "payPeriodId", "source", "sourceAccount", "destination", "destinationAccount", "transactionName", "transferAmount", "status" ] } } }, "required": [ "payrollTransaction" ] }, "example": { "payrollTransaction": [ { "requestReferenceId": "5244157", "companyId": "C2019899-9EEF-49F7-9B51-70744AFAFE61", "payPeriodId": "2AF56831-2841-438D-9722-E097AC1CCCAC", "source": "Ledger", "sourceAccount": "A4567F07-CB88-4973-8A60-0AF2F9512C41", "destination": "EmployeeBankAccount", "destinationAccount": "ADAB2624-0DC9-4151-A4D5-00C83851F8BA", "transactionName": "AchCredit", "transferAmount": 3624.48, "status": "complete" } ] } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "RequestReferenceId is invalid" } } } }, "headers": {} } }, "security": [] } }, "/reports/getPayStub": { "get": { "summary": "getPayStub", "deprecated": false, "description": "\nThe `getPayStub` API retrieves detailed pay stub information for a specific employee and pay period.\n\n### What it does:\n\n- Retrieves a comprehensive pay stub for an employee across a single pay period\n- Includes gross pay, net pay, state & federal taxes, and deductions based on the employees details", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "getPayStub" }, "payPeriodId": { "type": "string" }, "userId": { "type": "string" } }, "required": [ "method", "payPeriodId", "userId" ] }, "example": { "method": "getPayStub", "payPeriodId": "F240E800-B95E-41E0-A5D3-0C84E22FFA82", "userId": "18C949DF-7D8C-4752-B7BE-8C2364BE55C5" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "payrollLineItem": { "type": "array", "items": { "type": "object", "properties": { "payPeriodId": { "type": "string" }, "payPeriod": { "type": "object", "properties": { "payPeriod": { "type": "string" }, "payDate": { "type": "string" } }, "required": [ "payPeriod", "payDate" ] }, "baseTotal": { "type": "number" }, "grossTotal": { "type": "number" }, "netTotal": { "type": "number" }, "ytdBaseTotal": { "type": "number" }, "ytdGrossTotal": { "type": "number" }, "ytdNetTotal": { "type": "number" }, "taxDetails": { "type": "array", "items": { "type": "object", "properties": { "TaxName": { "type": "string" }, "TaxAmount": { "type": [ "integer", "number" ] }, "TaxAmountYTD": { "type": [ "integer", "number" ] } }, "required": [ "TaxName", "TaxAmount", "TaxAmountYTD" ] } }, "deductions": { "type": "array", "items": { "type": "object", "properties": { "vertexDeductionIdentifier": { "type": "object", "properties": { "deductionDescription": { "type": "string" } }, "required": [ "deductionDescription" ] }, "amount": { "type": "integer" }, "amountYtd": { "type": "integer" } } } }, "additionalCompensations": { "type": "array", "items": { "type": "object", "properties": { "payrollLineItemAdditionalCompensation_VertexCompensationIdentifier": { "type": "object", "properties": { "compensationDescription": { "type": "string" } }, "required": [ "compensationDescription" ] }, "amount": { "type": "integer" }, "amountYtd": { "type": "integer" } } } }, "overTimes": { "type": "array", "items": { "type": "object", "properties": { "overTimeType": { "type": "object", "properties": { "overTimeType": { "type": "string" } }, "required": [ "overTimeType" ] }, "amount": { "type": "number" }, "numberOfHours": { "type": "integer" }, "multiplier": { "type": "integer" }, "overtimeYTD": { "type": "number" } } } }, "reimbursements": { "type": "array", "items": { "type": "object", "properties": { "reimbursementType": { "type": "string" }, "amount": { "type": "integer" }, "reimbursementYTD": { "type": "integer" } } } }, "timeOffs": { "type": "array", "items": { "type": "string" } } } } } }, "required": [ "payrollLineItem" ] }, "example": { "payrollLineItem": [ { "payPeriodId": "F240E800-B95E-41E0-A5D3-0C84E22FFA82", "payPeriod": { "payPeriod": "10/01/2025 - 10/31/2025", "payDate": "2025-11-03" }, "baseTotal": 3953.49, "grossTotal": 4099.77, "netTotal": 3725.61, "ytdBaseTotal": 7953.49, "ytdGrossTotal": 8332.33, "ytdNetTotal": 7581.98, "taxDetails": [ { "TaxName": "Federal Withholding Tax", "TaxAmount": 0, "TaxAmountYTD": 0 }, { "TaxName": "Medicare", "TaxAmount": 58.5, "TaxAmountYTD": 119.87 }, { "TaxName": "Social Security", "TaxAmount": 250.16, "TaxAmountYTD": 512.58 }, { "TaxName": "Cares Fund EE", "TaxAmount": 23.66, "TaxAmountYTD": 48.21 }, { "TaxName": "WA - State paid family medical leave EE", "TaxAmount": 26.84, "TaxAmountYTD": 54.69 } ], "deductions": [ { "vertexDeductionIdentifier": { "deductionDescription": "125Adoption Assistance Reg" }, "amount": 25, "amountYtd": 25 } ], "additionalCompensations": [ { "payrollLineItemAdditionalCompensation_VertexCompensationIdentifier": { "compensationDescription": "3rd Party LTD 125 plan" }, "amount": 20, "amountYtd": 20 } ], "overTimes": [ { "overTimeType": { "overTimeType": "Comp off OT" }, "amount": 116.28, "numberOfHours": 5, "multiplier": 1, "overtimeYTD": 348.84 } ], "reimbursements": [ { "reimbursementType": "Gym", "amount": 10, "reimbursementYTD": 10 } ], "timeOffs": [] } ] } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "Invalid userId" } } } }, "headers": {} } }, "security": [] } }, "/reports/getBusinessUsers": { "get": { "summary": "getBusinessUsers", "deprecated": false, "description": "\nThe `getBusinessUsers` API is used to retrieve comprehensive information about **all** business users within a company.\n\n### What it does:\n\n- Returns the business user IDs for every business user in the payroll system\n- Returns detailed information for each of the business users including their role, address, SSN and more\n\n### Notes:\n\n- Requires only a companyID since all business users are retrieved\n- Returns the same fields as `getBusinessUserInfo` which can be used to retrieve data for a single business user", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "getBusinessUsers", "examples": [ "getBusinessUserDetails" ] }, "companyId": { "type": "string", "format": "uuid" } }, "required": [ "method", "companyId" ] }, "example": { "method": "getBusinessUsers", "companyId": "B62B4EB2-4198-42FE-95E3-00959BEF1B8F" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "BusinessUser": { "type": "array", "items": { "type": "object", "properties": { "businessUserId": { "type": "string" }, "businessUser": { "type": "string" }, "firstName": { "type": "string" }, "middleName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "phoneNumber": { "type": "string" }, "payrollAdmin": { "type": "boolean" }, "bookKeeper": { "type": "boolean" }, "beneficialOwner": { "type": "boolean" }, "employee": { "type": "boolean" }, "ownershipPercentage": { "type": "number" }, "companyLocationID": { "type": "string" }, "address1": { "type": "string" }, "address2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zipcode": { "type": "string" }, "country": { "type": "string" }, "ssn": { "type": "string" }, "startDate": { "type": "number" }, "dateOfBirth": { "type": "string" }, "isPayrollAdmin": { "type": "boolean" }, "isController": { "type": "boolean" }, "isBeneficialOwner": { "type": "boolean" }, "isEmployee": { "type": "boolean" }, "dateOfJoin": { "type": "string" } } } } }, "required": [ "BusinessUser" ] }, "example": { "BusinessUser": [ { "businessUserId": "F7F09EAD-2FA8-458F-B3E6-750F42B15857", "businessUser": "Tyler Hm", "firstName": "Tyler", "middleName": "", "lastName": "Hm", "email": "tylerhm@mailsac.com", "phoneNumber": "8473625628", "payrollAdmin": true, "bookKeeper": true, "beneficialOwner": true, "employee": false, "ownershipPercentage": 0.1, "companyLocationID": "F7F09EAD-2FA8-458F-B3E6-750F42B15857", "address1": "919 2nd Ave", "address2": "", "city": "New York", "state": "NY", "zipcode": "10017-1582", "country": "US", "ssn": "857476277", "startDate": "2023-12-10", "dateOfBirth": "2000-12-10" } ] } } }, "headers": {} } }, "security": [] } }, "/reports/getBusinessUserDetails": { "get": { "summary": "getBusinessUserDetails", "deprecated": false, "description": "\nThe `getBusinessUserDetails` API is used to retrieve comprehensive information about a specific business user within the system.\n\n### What it does:\n\n- Returns detailed information for the business user including their role, address, SSN and more\n- Allows business users to view their stored data before making changes using other API calls\n\n### Note:\n\n- Use `getBusinessUserDetails` if you do not have access to the business user ID or wish to retrieve data for all business users", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "getBusinessUserDetails" }, "businessUserId": { "type": "string" } }, "required": [ "method", "businessUserId" ] }, "example": { "method": "getBusinessUserDetails", "businessUserId": "D8934854-20F7-4607-8007-A4B78254007F" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "businessUser": { "type": "array", "items": { "type": "object", "properties": { "businessUserId": { "type": "string" }, "businessUser": { "type": "string" }, "firstName": { "type": "string" }, "middleName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "phoneNumber": { "type": "string" }, "payrollAdmin": { "type": "boolean" }, "bookKeeper": { "type": "boolean" }, "beneficialOwner": { "type": "boolean" }, "employee": { "type": "boolean" }, "ownershipPercentage": { "type": "integer" }, "companyLocationID": { "type": "string" }, "address1": { "type": "string" }, "address2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zipcode": { "type": "string" }, "country": { "type": "string" }, "ssn": { "type": "string" }, "startDate": { "type": "string" }, "dateOfBirth": { "type": "string" } } } } }, "required": [ "businessUser" ] }, "example": { "businessUser": [ { "businessUserId": "D8934854-20F7-4607-8007-A4B78254007F", "businessUser": "Regina Wise", "firstName": "Regina", "middleName": "", "lastName": "Wise", "email": "wise021@mailsac.com", "phoneNumber": "2511630007", "payrollAdmin": true, "bookKeeper": true, "beneficialOwner": false, "employee": true, "ownershipPercentage": 0, "companyLocationID": "889F5A0D-CBC5-4495-A09B-D98B63490C1C", "address1": "102 Fallsgrove Blvd", "address2": "", "city": "Rockville", "state": "MD", "zipcode": "20850", "country": "US", "ssn": "587400936", "startDate": "2020-09-09", "dateOfBirth": "2006-09-09" } ] } } }, "headers": {} } }, "security": [] } }, "/reports/getIndividualPayrollHistory": { "get": { "summary": "getIndividualPayrollHistory", "deprecated": false, "description": "\nThe `getIndividualPayrollHistory` API retrieves comprehensive payroll history details for a specific employee.\n\n### What it does:\n\n- Returns complete payroll history for a specific employee based on their Employee ID\n- Provides detailed payroll line items including gross pay, net pay, taxes, and deductions for each pay period\n- Includes year-to-date aggregates for gross, base, and net totals plus employer tax calculations", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "getIndividualPayrollHistory" ], "title": "getIndividualPayrollHistory" }, "userId": { "type": "string", "format": "uuid" } }, "required": [ "method", "userId" ] }, "example": { "method": "getIndividualPayrollHistory", "userId": "30da3ca7-8b39-4a3c-8ab9-050f17fbcb3b" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "array", "items": { "type": "object", "properties": { "userName": { "type": "string" }, "payrollLineItems": { "type": "array", "items": { "type": "object", "properties": { "payPeriod": { "type": "object", "properties": { "payPeriodId": { "type": "string" }, "payPeriod": { "type": "string" }, "payEndDate": { "type": "string" }, "payBeginDate": { "type": "string" }, "payPeriodType": { "type": "object", "properties": { "payPeriodType": { "type": "string" } }, "required": [ "payPeriodType" ] } }, "required": [ "payPeriodId", "payPeriod", "payEndDate", "payBeginDate", "payPeriodType" ] }, "grossTotal": { "type": "number" }, "netTotal": { "type": "number" }, "payrollLineItemTaxAggregation": { "type": "object", "properties": { "employerTax": { "type": "number" } }, "required": [ "employerTax" ] } }, "required": [ "payPeriod", "grossTotal", "netTotal", "payrollLineItemTaxAggregation" ] } }, "employeePayrollLineItemsAggregate": { "type": "object", "properties": { "aggregate": { "type": "object", "properties": { "sum": { "type": "object", "properties": { "netTotal": { "type": "number" }, "ytdGrossTotal": { "type": "integer" }, "ytdBaseTotal": { "type": "integer" }, "ytdNetTotal": { "type": "integer" } }, "required": [ "netTotal", "ytdGrossTotal", "ytdBaseTotal", "ytdNetTotal" ] } }, "required": [ "sum" ] } }, "required": [ "aggregate" ] }, "employerTaxCalculationResponsesAggregate": { "type": "object", "properties": { "aggregate": { "type": "object", "properties": { "sum": { "type": "object", "properties": { "taxAmount": { "type": "number" } }, "required": [ "taxAmount" ] } }, "required": [ "sum" ] } }, "required": [ "aggregate" ] } } } } }, "required": [ "user" ] }, "example": { "user": [ { "userName": "Benjamin Harris", "payrollLineItems": [ { "payPeriod": { "payPeriodId": "D549C3D1-A9B1-4073-828B-0008743D8875", "payPeriod": "11/01/2025 - 11/30/2025", "payEndDate": "2025-11-30", "payBeginDate": "2025-11-01", "payPeriodType": { "payPeriodType": "Regular" } }, "grossTotal": 1952.2, "netTotal": 1795.13, "payrollLineItemTaxAggregation": { "employerTax": 200.1 } }, { "payPeriod": { "payPeriodId": "3C068DE4-038F-4874-B99B-4AFD7CB39351", "payPeriod": "09/01/2025 - 09/30/2025", "payEndDate": "2025-09-30", "payBeginDate": "2025-09-01", "payPeriodType": { "payPeriodType": "Regular" } }, "grossTotal": 2060.85, "netTotal": 1795.13, "payrollLineItemTaxAggregation": { "employerTax": 238.42 } }, { "payPeriod": { "payPeriodId": "43CCBBDF-8CF3-472E-874D-888E7911BB1F", "payPeriod": "10/01/2025 - 10/31/2025", "payEndDate": "2025-10-31", "payBeginDate": "2025-10-01", "payPeriodType": { "payPeriodType": "Regular" } }, "grossTotal": 2363.73, "netTotal": 2142.86, "payrollLineItemTaxAggregation": { "employerTax": 248.72 } } ], "employeePayrollLineItemsAggregate": { "aggregate": { "sum": { "netTotal": 5733.12, "ytdGrossTotal": 0, "ytdBaseTotal": 0, "ytdNetTotal": 0 } } }, "employerTaxCalculationResponsesAggregate": { "aggregate": { "sum": { "taxAmount": 448.82 } } } } ] } } }, "headers": {} } }, "security": [] } }, "/reports/getCompanyInfo": { "get": { "summary": "getCompanyInfo", "deprecated": false, "description": "\nThe `getCompanyInfo` API retrieves detailed information about a specific company.\n\n### What it does:\n\n- Returns complete company profile including business details, contact information, locations, and banking", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "getCompanyInfo" ], "title": "getCompanyInfo" }, "companyId": { "type": "string", "format": "uuid" } }, "required": [ "method", "companyId" ] }, "example": { "method": "getCompanyInfo", "companyId": "B62B4EB2-4198-42FE-95E3-00959BEF1B8F" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "Company": { "type": "array", "items": { "type": "object", "properties": { "company": { "type": "string" }, "companyID": { "type": "string" }, "businessWebsite": { "type": "string" }, "registration": { "type": "object", "properties": { "isTermsAccepted": { "type": "boolean" }, "isEsign": { "type": "boolean" } }, "required": [ "isTermsAccepted", "isEsign" ] }, "CompanyLocations": { "type": "array", "items": { "type": "object", "properties": { "address1": { "type": "string" }, "address2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zipcode": { "type": "string" }, "country": { "type": "string" }, "companyLocation": { "type": "string" } } } }, "KYBInformations": { "type": "array", "items": { "type": "object", "properties": { "ein": { "type": "string" }, "email": { "type": "string" }, "EntityType": { "type": "object", "properties": { "entityType": { "type": "string" } }, "required": [ "entityType" ] }, "phoneNumber": { "type": "string" }, "dateOfIncorporation": { "type": "string" } } } }, "kycStatus": { "type": "string" }, "BankAccounts": { "type": "array", "items": { "type": "object", "properties": { "companyFundingSourceEntityId": { "type": "string" }, "bankName": { "type": "string" }, "accountName": { "type": "string" }, "accountNumber": { "type": "string" }, "accountType": { "type": "string" } } } } } } } }, "required": [ "Company" ] }, "example": { "Company": [ { "company": "Diferential Pay", "companyID": "B62B4EB2-4198-42FE-95E3-00959BEF1B8F", "businessWebsite": "", "registration": { "isTermsAccepted": true, "isEsign": true }, "CompanyLocations": [ { "address1": "8642 Yule St", "address2": "", "city": "Arvada", "state": "CO", "zipcode": "80007-7241", "country": "US", "companyLocation": "Main" } ], "KYBInformations": [ { "ein": "389723826", "email": "tylerhm@mailsac.com", "EntityType": { "entityType": "LLC" }, "phoneNumber": "8473625628", "dateOfIncorporation": "2024-11-21" } ], "kycStatus": "passed", "BankAccounts": [ { "companyFundingSourceEntityId": "141C7B75-1044-4D18-A64B-64895BAF8090", "bankName": "First Platypus Bank", "accountName": "Plaid Saving", "accountNumber": "XXXXXXXXX1111", "accountType": "savings" } ] } ] } } }, "headers": {} } }, "security": [] } }, "/reports/getCompanyLocationInfo": { "get": { "summary": "getCompanyLocationInfo", "deprecated": false, "description": "\nThe `getCompanyLocationInfo` API retrieves all location information for a specific company including address and location type designation.\n\n### What it does:\n\n- Returns all company locations including addresses, phone numbers, and location type\n\n### Notes:\n\n- Location types include **WorkLocation**, **MailingAddress**, and **FilingAddress**", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "getCompanyLocationInfo" ], "title": "getCompanyLocationInfo" }, "companyId": { "type": "string", "format": "uuid" } }, "required": [ "method", "companyId" ] }, "example": { "method": "getCompanyLocationInfo", "companyId": "0944def5-7c6e-4f6b-a7ed-10d28b11b9b9" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "CompanyLocation": { "type": "array", "items": { "type": "object", "properties": { "companyLocation": { "type": "string" }, "companyLocationID": { "type": "string" }, "address1": { "type": "string" }, "address2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zipcode": { "type": "string" }, "country": { "type": "string" }, "phoneNumber": { "type": "string" }, "isWorkLocation": { "type": "boolean" }, "isMailingAddress": { "type": "boolean" }, "isFilingAddress": { "type": "boolean" } } } } }, "required": [ "CompanyLocation" ] }, "example": { "CompanyLocation": [ { "companyLocation": "22 Main", "companyLocationID": "1BD3184B-76B2-45A4-98D5-3552DB5684A2", "address1": "8435 Colard Ln", "address2": "", "city": "Lyons", "state": "CO", "zipcode": "80540", "country": "US", "phoneNumber": "1111111111", "isWorkLocation": true, "isMailingAddress": false, "isFilingAddress": true } ] } } }, "headers": {} } }, "security": [] } }, "/reports/getActiveUsers": { "get": { "summary": "getActiveUsers", "deprecated": false, "description": "The `getActiveUsers` API is used to retrieve comprehensive information about all currently active users in the system. This report provides essential user data for payroll processing, compliance tracking, and workforce management.\n\n### What it does:\n\n- Returns detailed information for active users including wage and address\n\n### Notes:\n\n- Only active users are fetched by this API call. Deactivated or terminated users will not appear in the results\n- Requests are worker type specific (W2 for employees and 1099 for contractors)\n- Returns the same fields as `getUsers`, which can be used to retrieve a full list of activated, deactivated and terminated users", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "getActiveUsers" }, "companyId": { "type": "string" }, "workerType": { "type": "string" } }, "required": [ "method", "companyId", "workerType" ] }, "example": { "method": "getActiveUsers", "companyId": "01A33366-EE1C-4E13-BCB9-E482AC3A4545", "workerType": "W2" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "string" }, "userId": { "type": "string" }, "userReferenceId": { "type": "string" }, "companyId": { "type": "string" }, "status": { "type": "object", "properties": { "userStatus": { "type": "string" } }, "required": [ "userStatus" ] }, "WorkerType": { "type": "object", "properties": { "WorkerType": { "type": "string" } }, "required": [ "WorkerType" ] }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "middleName": { "type": "string" }, "phoneNumber": { "type": "string" }, "kycStatus": { "type": "string" }, "jobTitle": { "type": "string" }, "dateOfJoin": { "type": "string" }, "email": { "type": "string" }, "userWages": { "type": "array", "items": { "type": "object", "properties": { "WageRate": { "type": "number" }, "WageBasis": { "type": "object", "properties": { "WageBasis": { "type": "string" } }, "required": [ "WageBasis" ] }, "paymentMethod": { "type": "object", "properties": { "PaymentMethod": { "type": "string" } }, "required": [ "PaymentMethod" ] } }, "required": [ "WageRate", "WageBasis", "paymentMethod" ] } }, "userAddress": { "type": "object", "properties": { "address1": { "type": "string" }, "address2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zipcode": { "type": "string" }, "country": { "type": "string" } }, "required": [ "address1", "city", "state", "zipcode", "country" ] } }, "required": [ "user", "userId", "userReferenceId", "companyId", "status", "WorkerType", "firstName", "lastName", "phoneNumber", "kycStatus", "jobTitle", "dateOfJoin", "email", "userWages", "userAddress" ] } } }, "required": [ "user" ] }, "example": { "user": [ { "user": "Ryan Lee Allen", "userId": "94380CA2-3612-46D7-92EA-02D8A2D0A094", "userReferenceId": "", "companyId": "B35D7C33-93EF-44EB-8C04-6BBD0907CCB4", "status": { "userStatus": "Active" }, "WorkerType": { "WorkerType": "W2" }, "firstName": "Ryan", "lastName": "Allen", "middleName": "Lee", "phoneNumber": "6449847893", "kycStatus": "passed", "jobTitle": "Maintenance Technician", "dateOfJoin": "2025-11-14", "email": "ryan.allen70819@mailsac.com", "userWages": [ { "WageRate": 25, "WageBasis": { "WageBasis": "Per Day" }, "paymentMethod": { "PaymentMethod": "Direct Deposit" } } ], "userAddress": { "address1": "1725 Reisterstown Rd", "address2": "", "city": "Randallstown", "state": "MD", "zipcode": "21133", "country": "US" } } ] } } }, "headers": {} } }, "security": [] } }, "/reports/getTerminatedUsers": { "get": { "summary": "getTerminatedUsers", "deprecated": false, "description": "\nThe `getTerminatedUsers` API retrieves comprehensive information about all users who have been terminated within a company.\n\n### What it does:\n\n- Provides user data for employees and contractors who have been terminated\n\n### Notes:\n\n- Terminated user data may need to be retained for compliance and to resolve outstanding tax withholdings\n- Returns the same fields as `getUsers`, which can be used to retrieve a full list of activated, deactivated and terminated users\n", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "getTerminatedUsers" ], "title": "getTerminatedUsers" }, "companyId": { "type": "string", "format": "uuid" }, "workerType": { "type": "string", "enum": [ "W2", "1099-NEC" ] } }, "required": [ "method", "companyId", "workerType" ] }, "example": { "method": "getTerminatedUsers", "companyId": "4c27f783-681a-4a7a-aaf2-03c719f5c9fc", "workerType": "W2" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "string" }, "userId": { "type": "string" }, "companyId": { "type": "string" }, "status": { "type": "object", "properties": { "userStatus": { "type": "string" } }, "required": [ "userStatus" ] }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "middleName": { "type": "string" }, "personalEmail": { "type": "string" }, "phoneNumber": { "type": "string" }, "kycStatus": { "type": "string" }, "jobTitle": { "type": "string" }, "dateOfJoin": { "type": "string" }, "email": { "type": "string" }, "userWages": { "type": "array", "items": { "type": "object", "properties": { "userWorkerType": { "type": "object", "properties": { "workerType": { "type": "string" } }, "required": [ "workerType" ] } } } }, "userAddress": { "type": "object", "properties": { "address1": { "type": "string" }, "address2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zipcode": { "type": "string" }, "country": { "type": "string" } }, "required": [ "address1", "address2", "city", "state", "zipcode", "country" ] } } } } }, "required": [ "user" ] }, "example": { "user": [ { "user": "Nelson Mandor", "userId": "842A1486-6947-4095-88E0-0FE8ADB8C266", "companyId": "4C27F783-681A-4A7A-AAF2-03C719F5C9FC", "status": { "userStatus": "Terminate" }, "firstName": "Nelson", "lastName": "Mandor", "middleName": null, "personalEmail": "hhjj@mail.com", "phoneNumber": "7788589652", "kycStatus": "passed", "jobTitle": "HR", "dateOfJoin": "2023-05-29", "email": "nelson789@mail.com", "userWages": [ { "userWorkerType": { "workerType": "W2" } } ], "userAddress": { "address1": "663 Calle Tulipan", "address2": null, "city": "Thousand Oaks", "state": "CA", "zipcode": "91360", "country": "US" } } ] } } }, "headers": {} } }, "security": [] } }, "/reports/getDeactivatedUsers": { "get": { "summary": "getDeactivatedUsers", "deprecated": false, "description": "\nThe `getDeactivatedUsers` API retrieves comprehensive information about all users who have been deactivated within a company.\n\n### What it does:\n\n- Provides user data for employees and contractors who have been temporarily deactivated but not terminated\n- Useful to fetch employees that are temporarily removed from the payroll but may be re-added at a later date\n\n### Notes:\n\n- Deactivated users can be reactivated using the `activateUser` endpoint if they return to work\n- Returns the same fields as `getUsers`, which can be used to retrieve a full list of activated, deactivated and terminated users", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "examples": [ "getDeactivatedUsers" ], "title": "getDeactivatedUsers" }, "companyId": { "type": "string", "format": "uuid" }, "workerType": { "type": "string", "enum": [ "W2", "1099-NEC" ] } }, "required": [ "method", "companyId", "workerType" ] }, "example": { "method": "getDeactivatedUsers", "companyId": "1b66dd5f-989e-4073-85af-9de16e0fb342", "workerType": "W2" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "string" }, "userId": { "type": "string" }, "companyId": { "type": "string" }, "status": { "type": "object", "properties": { "userStatus": { "type": "string" } }, "required": [ "userStatus" ] }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "middleName": { "type": "string" }, "personalEmail": { "type": "string" }, "phoneNumber": { "type": "string" }, "kycStatus": { "type": "string" }, "jobTitle": { "type": "string" }, "dateOfJoin": { "type": "string" }, "email": { "type": "string" }, "userWages": { "type": "array", "items": { "type": "object", "properties": { "userWorkerType": { "type": "object", "properties": { "workerType": { "type": "string" } }, "required": [ "workerType" ] } } } }, "userAddress": { "type": "object", "properties": { "address1": { "type": "string" }, "address2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zipcode": { "type": "string" }, "country": { "type": "string" } }, "required": [ "address1", "address2", "city", "state", "zipcode", "country" ] } } } } }, "required": [ "user" ] }, "example": { "user": [ { "user": "pat cummins", "userId": "609A13E9-CDC4-45A5-8407-B58500A244FE", "companyId": "1B66DD5F-989E-4073-85AF-9DE16E0FB342", "status": { "userStatus": "Deactivate" }, "firstName": "pat", "lastName": "cummins", "middleName": null, "personalEmail": "vjhj@mail.com", "phoneNumber": "7485963202", "kycStatus": "passed", "jobTitle": "QA", "dateOfJoin": "2023-08-01", "email": "pat999@mailsac.com", "userWages": [ { "userWorkerType": { "workerType": "W2" } } ], "userAddress": { "address1": "777 Alameda Street", "address2": null, "city": "Los Angeles", "state": "CA", "zipcode": "90021", "country": "US" } } ] } } }, "headers": {} } }, "security": [] } }, "/reports/getPaidEmployeesCountBasedOnDateRange": { "get": { "summary": "getPaidEmployeesCountBasedOnDateRange", "deprecated": false, "description": "\nThe `getPaidEmployeesCountBasedOnDateRange` API returns the total count of employees who received payment within a specified date range.\n\n### What it does:\n\n- Returns the number of employees paid during a specific time period\n", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "default": "getPaidEmployeesCountBasedOnDateRange", "examples": [ "getPaidEmployeesCountBasedOnDateRange" ], "title": "getPaidEmployeesCountBasedOnDateRange" }, "startDate": { "type": "string" }, "endDate": { "type": "string" }, "companyId": { "type": "string" } }, "required": [ "method", "companyId", "startDate", "endDate" ] }, "example": { "method": "getPaidEmployeesCountBasedOnDateRange", "companyId": "A7FC17FF-B50E-4A89-97DC-D900F3327D8E", "startDate": "2024-01-01", "endDate": "2024-04-20" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "filterStartDate": { "type": "string" }, "filterEndDate": { "type": "string" }, "companies": { "type": "array", "items": { "type": "object", "properties": { "company": { "type": "string" }, "companyId": { "type": "string" }, "paidEmployeesDistinctCount": { "type": "integer" }, "payPeriods": { "type": "array", "items": { "type": "object", "properties": { "payPeriod": { "type": "string" }, "payDate": { "type": "string" }, "paidEmployeesCount": { "type": "integer" }, "employees": { "type": "array", "items": { "type": "object", "properties": { "employee": { "type": "string" }, "employeeId": { "type": "string" } }, "required": [ "employee", "employeeId" ] } } }, "required": [ "payPeriod", "payDate", "paidEmployeesCount", "employees" ] } } }, "required": [ "companyId", "company" ] } } } } }, "example": [ { "filterStartDate": "2024-01-01", "filterEndDate": "2024-04-20", "companies": [ { "company": " WonderHub Inc", "companyId": "A7FC17FF-B50E-4A89-97DC-D900F3327D8E", "paidEmployeesDistinctCount": 1, "payPeriods": [ { "payPeriod": "02/26/2024 - 03/10/2024", "payDate": "2024-02-26", "paidEmployeesCount": 1, "employees": [ { "employee": "David Martin", "employeeId": "149B7B64-25AE-4AFB-8032-3BEC18B1B656" } ] }, { "payPeriod": "03/11/2024 - 03/24/2024", "payDate": "2024-03-11", "paidEmployeesCount": 1, "employees": [ { "employee": "David Martin", "employeeId": "149B7B64-25AE-4AFB-8032-3BEC18B1B656" } ] }, { "payPeriod": "03/25/2024 - 04/07/2024", "payDate": "2024-03-25", "paidEmployeesCount": 1, "employees": [ { "employee": "David Martin", "employeeId": "149B7B64-25AE-4AFB-8032-3BEC18B1B656" } ] }, { "payPeriod": "04/08/2024 - 04/21/2024", "payDate": "2024-04-08", "paidEmployeesCount": 1, "employees": [ { "employee": "David Martin", "employeeId": "149B7B64-25AE-4AFB-8032-3BEC18B1B656" } ] } ] } ] } ] } }, "headers": {} } }, "security": [] } }, "/reports/getMonthlyAndSemiMonthlyPayScheduleDates": { "get": { "summary": "getMonthlyAndSemiMonthlyPayScheduleDates", "deprecated": false, "description": "The `getMonthlyAndSemiMonthlyPayScheduleDates` API retrieves the pay schedule dates for monthly and semi-monthly payroll options.\n\n### What it does:\n- Returns the pay begin dates, pay end dates, deadlines to run payroll, and pay dates for each pay period.\n\n### Note:\n- Currently only Monthly and Semi-Monthly pay schedules are date-limited", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "compensationFrequency": { "type": "string" } }, "required": [ "method", "compensationFrequency" ] }, "example": { "method": "getMonthlyAndSemiMonthlyPayScheduleDates", "compensationFrequency": "Monthly" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "PayScheduleDates": { "type": "object", "properties": { "PayBeginDate": { "type": "string" }, "PayEndDate": { "type": "string" }, "DeadlineToRunPayroll": { "type": "string" }, "PayDate": { "type": "string" } }, "required": [ "PayBeginDate", "PayEndDate", "DeadlineToRunPayroll", "PayDate" ] } }, "required": [ "PayScheduleDates" ] }, "example": { "PayScheduleDates for Monthly": [ { "PayBeginDate": "2025-01-01", "PayEndDate": "2025-01-31", "DeadlineToRunPayroll": "2025-01-29", "PayDate": "2025-01-31" }, { "PayBeginDate": "2025-02-01", "PayEndDate": "2025-02-28", "DeadlineToRunPayroll": "2025-02-26", "PayDate": "2025-02-28" }, { "PayBeginDate": "2025-03-01", "PayEndDate": "2025-03-31", "DeadlineToRunPayroll": "2025-03-27", "PayDate": "2025-03-31" }, { "PayBeginDate": "2025-04-01", "PayEndDate": "2025-04-30", "DeadlineToRunPayroll": "2025-04-28", "PayDate": "2025-04-30" }, { "PayBeginDate": "2025-05-01", "PayEndDate": "2025-05-31", "DeadlineToRunPayroll": "2025-05-28", "PayDate": "2025-05-30" }, { "PayBeginDate": "2025-06-01", "PayEndDate": "2025-06-30", "DeadlineToRunPayroll": "2025-06-26", "PayDate": "2025-06-30" }, { "PayBeginDate": "2025-07-01", "PayEndDate": "2025-07-31", "DeadlineToRunPayroll": "2025-07-29", "PayDate": "2025-07-31" }, { "PayBeginDate": "2025-08-01", "PayEndDate": "2025-08-31", "DeadlineToRunPayroll": "2025-08-27", "PayDate": "2025-08-29" }, { "PayBeginDate": "2025-09-01", "PayEndDate": "2025-09-30", "DeadlineToRunPayroll": "2025-09-26", "PayDate": "2025-09-30" }, { "PayBeginDate": "2025-10-01", "PayEndDate": "2025-10-31", "DeadlineToRunPayroll": "2025-10-29", "PayDate": "2025-10-31" }, { "PayBeginDate": "2025-11-01", "PayEndDate": "2025-11-30", "DeadlineToRunPayroll": "2025-11-25", "PayDate": "2025-11-28" }, { "PayBeginDate": "2025-12-01", "PayEndDate": "2025-12-31", "DeadlineToRunPayroll": "2025-12-29", "PayDate": "2025-12-31" } ] } } }, "headers": {} } }, "security": [] } }, "/reports/getUsersByCompanyName": { "get": { "summary": "getUsersByCompanyName", "deprecated": false, "description": "\nThe `getUsersByCompanyName` API retrieves detailed information for all users within a company using company name as an identifier.\n\n### What it does:\n\n- Returns comprehensive user details for all employees and contractors within the specified company\n- Provides complete user profile information including personal information, employment status, wage, and contact data\n\n### Note:\n\n- The system allows companies with the same name within the same administrative environment. Company name should only be used as a fallback to locate users when the Company ID cannot be accessed.", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "getUsersByCompanyName", "examples": [ "getUsersByCompanyName" ] }, "companyName": { "type": "string" } }, "required": [ "method", "companyName" ] }, "example": { "method": "getUsersByCompanyName", "companyName": "3M" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "array", "items": { "type": "object", "properties": { "companyID": { "type": "string" }, "userID": { "type": "string" }, "user": { "type": "string" }, "firstName": { "type": "string" }, "middleName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "dateOfJoin": { "type": "string" }, "jobTitle": { "type": "string" }, "kycStatus": { "type": "string" }, "phoneNumber": { "type": "string" }, "workerType": { "type": "object", "properties": { "workerType": { "type": "string" } }, "required": [ "workerType" ] } }, "required": [ "user", "userID", "companyID", "workerType", "firstName", "lastName", "middleName", "phoneNumber", "kycStatus", "jobTitle", "dateOfJoin", "email" ] } } }, "required": [ "user" ] }, "example": { "users": [ { "companyID": "07D6D507-8764-4CD2-818E-D64CF554D018", "userID": "F4481532-51B0-4405-93E1-174FFA270AB7", "user": "Scarlett Orr", "firstName": "Scarlett", "middleName": "", "lastName": "Orr", "email": "scarlett123@mailsac.com", "dateOfJoin": "2023-08-23", "jobTitle": "HR", "kycStatus": "passed", "phoneNumber": "8965886658", "workerType": { "workerType": "W2" } }, { "companyID": "07D6D507-8764-4CD2-818E-D64CF554D018", "userID": "D91B2B72-66D5-49DC-9C79-41F983135D91", "user": "Robin Orr", "firstName": "Robin", "middleName": "", "lastName": "Orr", "email": "robin1234@mailsac.com", "dateOfJoin": "2023-09-11", "jobTitle": "HR", "kycStatus": "passed", "phoneNumber": "4569745665", "workerType": { "workerType": "W2" } }, { "companyID": "07D6D507-8764-4CD2-818E-D64CF554D018", "userID": "5E704B63-FD22-4444-964A-4C4C90D6C545", "user": "Santos Howard", "firstName": "Santos", "middleName": "", "lastName": "Howard", "email": "santos123@mailsac.com", "dateOfJoin": "2024-07-21", "jobTitle": "HR", "kycStatus": "passed", "phoneNumber": "7896325410", "workerType": { "workerType": "W2" } }, { "companyID": "07D6D507-8764-4CD2-818E-D64CF554D018", "userID": "80316182-54F6-479F-9DE0-5BA8AC214849", "user": "Grey Nancy", "firstName": "Grey", "middleName": "", "lastName": "Nancy", "email": "greynancy7748@mailsac.com", "dateOfJoin": "2024-02-02", "jobTitle": "HR", "kycStatus": "pending", "phoneNumber": "8444144414", "workerType": { "workerType": "W2" } }, { "companyID": "07D6D507-8764-4CD2-818E-D64CF554D018", "userID": "D864FBC7-AF7B-4C5C-B000-9FA11668721A", "user": "Otis Price", "firstName": "Otis", "middleName": "", "lastName": "Price", "email": "otis123@mailsac.com", "dateOfJoin": "2024-06-21", "jobTitle": "QA", "kycStatus": "passed", "phoneNumber": "7896546322", "workerType": { "workerType": "1099-NEC" } }, { "companyID": "07D6D507-8764-4CD2-818E-D64CF554D018", "userID": "DB14C767-4C87-479D-8752-CB31E1EDD067", "user": "Edi Beccker", "firstName": "Edi", "middleName": "", "lastName": "Beccker", "email": "edibecker@mailsac.com", "dateOfJoin": "2024-02-02", "jobTitle": "HR", "kycStatus": "pending", "phoneNumber": "0478954152", "workerType": { "workerType": "W2" } }, { "companyID": "07D6D507-8764-4CD2-818E-D64CF554D018", "userID": "E2DA74E1-1D03-4235-ADBD-CB508FF58513", "user": "Onyx Maddox", "firstName": "Onyx", "middleName": "", "lastName": "Maddox", "email": "onyx123@mailsac.com", "dateOfJoin": "2023-08-21", "jobTitle": "HR", "kycStatus": "passed", "phoneNumber": "7896552324", "workerType": { "workerType": "W2" } }, { "companyID": "07D6D507-8764-4CD2-818E-D64CF554D018", "userID": "BECE2900-6169-4514-AC12-DDC8CD90A953", "user": "Emily Orr", "firstName": "Emily", "middleName": "", "lastName": "Orr", "email": "emily123@mailsac.com", "dateOfJoin": "2023-08-23", "jobTitle": "HR", "kycStatus": "passed", "phoneNumber": "0233699856", "workerType": { "workerType": "W2" } } ] } } }, "headers": {} } }, "security": [] } }, "/reports/getCompanies": { "get": { "summary": "getCompanies", "deprecated": false, "description": "\nThe `getCompanies` API is used to retrieve a list of all companies accessible within a payroll management company's administrative environment. Company IDs are required for the majority of API calls.\n\n### What it does:\n\n- Returns a complete list of all companies under management with company names and unique identifiers\n- Provides the foundational data needed for company selection in multi-tenant management interfaces\n- Enables management companies to programmatically access their entire client portfolio for reporting, administration, and payroll processing workflows", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "getCompanies", "examples": [ "getCompanies" ] } }, "required": [ "method" ] }, "example": { "method": "getCompanies" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "Company": { "type": "array", "items": { "type": "object", "properties": { "company": { "type": "string" }, "companyID": { "type": "string" } } } } }, "required": [ "Company" ] }, "example": { "Company": [ { "company": "mozrt cooper external api test", "companyID": "DDFF1962-0B07-4898-BAB0-00E4F70309C0" }, { "company": "netflix inc", "companyID": "BB1919EE-B8AE-439F-94A0-031DFBB32913" }, { "company": "Martin inc", "companyID": "8A92C8D7-A93A-4F6C-9EC4-03638AFA2580" }, { "company": "Twilight inc", "companyID": "D50C6711-2D89-4A12-A909-03739BC8DD48" }, { "company": "Passport Zola inc", "companyID": "84AC186B-C6B9-4E94-8690-04E6FF5EDC43" }, { "company": "Wise Wonders co", "companyID": "092427B1-CF95-41E2-8057-05988AF00E63" }, { "company": "davis inc", "companyID": "3FD67BC6-DC38-4B9C-BEC0-084B0E289FB0" }, { "company": "Morgan inc", "companyID": "94B14725-BC52-43DC-B9FE-0B00EACCB29F" }, { "company": "PostManCompany", "companyID": "0C7E0A5B-4D07-4122-B3E7-0DCD3B341E2B" }, { "company": "fruity", "companyID": "5FA57449-3784-4343-BCD0-0E3494F56A57" }, { "company": "BankAccountTesting", "companyID": "0FA91EEC-75F5-4F3B-BF9E-0F1FA813D651" }, { "company": "JohnJohn Inc", "companyID": "E96DDB44-FD5F-479F-83C1-103F7B921F29" }, { "company": "American Express", "companyID": "8C56D43E-DE17-4851-A583-11A89FCEE484" }, { "company": "Passport hope api testing", "companyID": "E4D18B68-07E2-4024-98E2-12B283B3EED4" }, { "company": "Duck LLC", "companyID": "AA848481-08CA-46AD-B366-14977F28B5D7" }, { "company": "hh", "companyID": "F9F7E7EC-3A3F-44BA-9ABB-15D86EA1280D" }, { "company": "skylo inc", "companyID": "79E6361D-0E6E-44F9-8DE5-1631782A8874" }, { "company": "TestPostman2 Corp", "companyID": "03DAA48D-3155-4BF3-95CD-17790264E877" }, { "company": "abc inc", "companyID": "AABF2068-302C-4961-B985-1785100FE206" }, { "company": "mozrt thomas inc", "companyID": "0F9B400C-9864-48AA-BDA8-18FEFB2DD184" }, { "company": "go air", "companyID": "8670B319-50DB-47FC-AC53-215B24851625" }, { "company": "pears inc", "companyID": "BE3AFCC4-390B-46D2-99A0-22072FB32EF2" }, { "company": "ferry inc", "companyID": "7D2FA4F6-6571-4A60-9106-244EBB2D1668" }, { "company": "brigdestone inc", "companyID": "E02F8D74-9F04-4230-B05B-26041393C887" }, { "company": "Featherland", "companyID": "20D2B132-C97C-43D5-A796-26F343ADC9BF" }, { "company": "Wise Wonders co", "companyID": "DD7BD9A0-6258-4CCB-85AF-27A7DC4EAACC" }, { "company": "rollfi passport mora inc", "companyID": "81862C12-4912-4A07-B9B8-293607C98948" }, { "company": "park inn", "companyID": "8DA5F22A-F8D7-43E7-94D2-29C443E0E37D" }, { "company": "admin inc", "companyID": "176C56F8-DE95-4843-A087-29E9CBF9E29D" }, { "company": "peter and sons Inc", "companyID": "041A8A06-71A4-40BB-828B-2D0D138974DF" }, { "company": "math inc", "companyID": "AB2D0F4A-9554-4509-938E-2D42B4503F3E" }, { "company": "lucky inc", "companyID": "E1DED150-092D-4249-91FE-2E982C5E0A80" }, { "company": "Rollfi Passport api testing", "companyID": "47AE405E-82E6-4F9D-9427-36AB13BB36D9" }, { "company": "elle inc", "companyID": "8102DB40-4F98-4EC9-AC92-3893C9A089E0" }, { "company": "pay inc", "companyID": "282C623E-9743-438F-B9E1-39784BCDE284" }, { "company": "victory inc", "companyID": "F1E6543E-FCAF-4BA5-97D1-3AA8672D508E" }, { "company": "household test", "companyID": "947CB0C3-E235-4DC8-8FB5-3CA000501A11" }, { "company": "Passport Theo inc", "companyID": "79E48F6E-43BF-4BCE-8F6B-3EFA770B6401" }, { "company": "Arsenal FC", "companyID": "AF2E5AA3-04A1-4C35-AB5D-40E175020B33" }, { "company": "Prism", "companyID": "50F4D635-FBC9-4F58-9550-4176DE6ADA1F" }, { "company": "victory inc", "companyID": "F223E2BD-9409-4536-9DE7-4371708A9B20" }, { "company": "postman inc", "companyID": "8FDFD95B-2322-4160-88A8-442E0988644D" }, { "company": "mozrt testing", "companyID": "CA1861B0-ADB7-489A-8A63-45D28B1193BD" }, { "company": "mobile inc", "companyID": "27D66FEA-85D7-40F7-AE9B-479C7B33CF01" }, { "company": "royal inc", "companyID": "15D0CB52-3145-4EF1-BD47-4C417BB76DBE" }, { "company": "Prism", "companyID": "D7B36E05-42EA-4A4D-B61F-4E4AAE0F2B4E" }, { "company": "thanu", "companyID": "5C7BCB19-C10F-43B2-B53F-4EBF3387F69C" }, { "company": "fixit inc", "companyID": "46DA6E28-0A1E-42BA-8074-4F0EE08F265C" }, { "company": "zisco inc", "companyID": "076A92CB-5614-42EE-8683-5190CA5B5476" }, { "company": "qwerty inc", "companyID": "86C55099-C9E7-44AF-8707-52C4CAF470FE" }, { "company": "FBO legacy ", "companyID": "815A54AD-8093-4D0C-BD3E-53F0E9C8C515" }, { "company": "ten inc", "companyID": "FC7B559E-8E6B-49AC-977B-584888F20D6C" }, { "company": "PostManCompany", "companyID": "C5FCD4E3-B6BE-45B0-952B-585F9AA057D6" }, { "company": "oriflame inc", "companyID": "5659BCEF-A23C-4786-8798-599964AE9EFD" }, { "company": "priority inc", "companyID": "C3D5DBFD-B53B-4C8E-99F5-5B96DB14DA98" }, { "company": "Ferrary inc", "companyID": "2762C87F-C7D2-4A6E-9EAB-5D8B62728C9E" }, { "company": "Techi inc", "companyID": "D6F7080F-23B8-4DB4-A200-5FF012C84FB6" }, { "company": "dell inc", "companyID": "46750780-81FE-4A99-9F7D-605B81A7B61C" }, { "company": "henrik inc", "companyID": "88D5F2AC-0C26-4BAF-8F63-60C85CB50C4B" }, { "company": "Walmart", "companyID": "0DF4A846-1C1B-44F6-AC51-6659DDBBFCEB" }, { "company": "first inc", "companyID": "7DDF19C0-CE0A-404A-BE66-66D98F0D3D55" }, { "company": "PostManCompany", "companyID": "E2D5A5BB-222A-42E3-8E18-6754634A0F73" }, { "company": "PostManCompany", "companyID": "D3CE9FBD-7E40-4781-B9DD-678D7520ED69" }, { "company": "hhh", "companyID": "4AD6B95B-9B2A-43E6-A436-688C765A5B46" }, { "company": "bh", "companyID": "99052AAC-2A89-4E1C-9F94-69394396DC2D" }, { "company": "excelo ", "companyID": "2EE7FB6E-35F0-46BF-A345-69C75FD6BBEF" }, { "company": "godrej inc", "companyID": "485622A4-F9F4-4D99-A418-69DB284803E8" }, { "company": "Nova inc", "companyID": "1805F641-D6A1-48D7-ACF5-6B369394A302" }, { "company": "xyz", "companyID": "C8296676-817B-4D8D-83E3-6BF0DA068F13" }, { "company": "googles inc", "companyID": "3D72D161-52D6-4CF4-AD5A-6EB07AC6982C" }, { "company": "Mozrt external api testing", "companyID": "61D0FEE7-A454-49AB-9EF2-71E644CF1D96" }, { "company": "kellogs inc", "companyID": "3133F929-D015-48FF-95DD-73934A90E4F9" }, { "company": "Passport Testing", "companyID": "2AEBE3E2-6042-425F-BA19-76FF016092A7" }, { "company": "lamborgini", "companyID": "1073D222-7E6A-438C-AFAA-7826DC1B3EC4" }, { "company": "Passport angie inc", "companyID": "D7B602FC-5A72-4C6F-97E6-7AA096FC51C5" }, { "company": "lime light", "companyID": "945F4091-C083-43CF-9B92-7ABE5C3F941D" }, { "company": "gg", "companyID": "7B9AFF45-5009-4E23-8A67-7B20750EEA74" }, { "company": "zinc inc", "companyID": "D501ADA1-2934-472C-8C6B-7C5A9C50F14C" }, { "company": "success inc", "companyID": "604BEB28-3A95-47A6-AC09-80878245B843" }, { "company": "Visa Inc", "companyID": "4C4EBCA0-4893-46D4-B5CD-812B96F93F6E" }, { "company": "zee inc", "companyID": "E153DA59-7A8D-4934-9BAE-81BCC8CBF864" }, { "company": "lewis inc", "companyID": "3BF04CE8-3826-4512-A572-8380F1C78B8E" }, { "company": "zen inc", "companyID": "199A918A-C9EB-4B66-B73B-88E5A2884092" }, { "company": "PostManCompany", "companyID": "C71B9BB0-52C8-4B2A-93C5-89932A9CB0D4" }, { "company": "Maruthi Suzuki", "companyID": "AEBED19C-82EB-44BC-A296-8B56F1586C88" }, { "company": "PostManCompanytesting", "companyID": "25E23175-E30B-429D-964A-8C69B75168F7" }, { "company": "PostManCompanytesting", "companyID": "852D89C6-86AF-4E6E-825B-8D1548BD0FB4" }, { "company": "PostManCompanytesting", "companyID": "B753C6D8-2A2B-4552-833A-8D8C0EE49B39" }, { "company": "glow inc", "companyID": "F5F4139C-A0D1-471F-A05C-8E90EA69B224" }, { "company": "featherlands", "companyID": "3A8F9468-684A-416B-BB0D-90F64A7FF681" }, { "company": "Wise Wonders", "companyID": "9C952CC4-7652-4E2A-9303-912D876057AE" }, { "company": "Boeing", "companyID": "BEC6599B-0733-4463-BCAA-91383A98EA68" }, { "company": "Sandbox Inc", "companyID": "D07E3506-8ED3-48FF-BBB2-950A29C6A809" }, { "company": "Prism", "companyID": "96A3D8DE-35B4-43C9-B282-993AED0A5D26" }, { "company": "Tulip inc ", "companyID": "70E103FE-C1B7-40D1-BC21-9A3497A922D8" }, { "company": "Kenny Inc", "companyID": "2575B36E-5177-4244-8894-9D85EA0BE6BC" }, { "company": "Household testing", "companyID": "EEE9742A-AA1E-4253-B877-9F4158FFE340" }, { "company": "mike inc", "companyID": "999FFEDC-9D4C-44C4-853F-A08EB13FE728" }, { "company": "cookies inc", "companyID": "C942E4FB-373E-4843-8465-A21BB619E5FE" }, { "company": "Manchester United Football Club", "companyID": "518DC5BE-4152-4E7E-98C3-A21E9D06CD60" }, { "company": "brooklin", "companyID": "D9C5047A-BEE4-4F00-8253-A3750D13EA1C" }, { "company": "PostManCompany1", "companyID": "58DAFB70-E2D9-400F-B6C8-A7F0F107C79B" }, { "company": "PostManCompanytesting", "companyID": "9122EB11-AD14-4932-8273-A9E2CC81F725" }, { "company": "honey inc", "companyID": "5893AD81-9568-496E-897F-ABAC57FEC573" }, { "company": "brave inc", "companyID": "D9F42740-23C3-4C75-804B-AC28200504B3" }, { "company": "Prism", "companyID": "335FA409-BB04-42AD-A865-B2FFAD233BD8" }, { "company": "PostManCompany", "companyID": "37800531-C340-48BC-8E46-B45F9AC38D1D" }, { "company": "adam inc", "companyID": "8361D861-06C4-4EB1-8B35-B4F57DD08968" }, { "company": "Appache", "companyID": "CFC4D743-4869-4799-B1AF-B615D6CF21E5" }, { "company": "yono inc", "companyID": "A7EFEF5C-E592-4253-82D0-B68B27E742E2" }, { "company": "kaira", "companyID": "7E22DF46-535D-4F00-9524-B6DF97E4891E" }, { "company": "Kenny Industries", "companyID": "39D76F82-C37D-4887-A452-B75E67A48E94" }, { "company": "nyke inc", "companyID": "687B0D7B-C68D-4643-B46D-B9A57507CC99" }, { "company": "Kyle Arts", "companyID": "7D4812E1-F85E-43C3-8ED8-BB65F7C21F9B" }, { "company": "light inc", "companyID": "D00B4CCC-901F-43C7-AA69-BE43D7B8DAB1" }, { "company": "bata inc", "companyID": "593283D6-2B91-4AB8-8066-BE5B7EA88865" }, { "company": "slack inc", "companyID": "7C8824E5-045D-44EA-8B59-BED80F15FA76" }, { "company": "Nagarro Co", "companyID": "A3B9DBD7-136C-426F-8055-C5CB244C9288" }, { "company": "Neeraj Inc", "companyID": "C12AC09E-F8ED-4AB3-9355-C76A4CB4E8D0" }, { "company": "legal inc", "companyID": "62044D14-08CC-4197-85E5-C9C9F20F1F72" }, { "company": "road inc", "companyID": "8867273D-7768-48BC-8BE1-CDBCB1C94944" }, { "company": "hhh", "companyID": "5F44D7E4-ED16-4E5B-8886-CEB3556E816A" }, { "company": "nike inc", "companyID": "B5A48F35-2F78-4D64-8226-CEF2FC1614DD" }, { "company": "style inc", "companyID": "1D08F5DD-1DC6-4FBD-AAD6-CFD029B25875" }, { "company": "kim inc", "companyID": "0B2A1F43-1CDC-46CA-B99A-CFD16380869E" }, { "company": "TestPostman2 Corp", "companyID": "DF054EED-0C92-4330-BBFD-D04429D48456" }, { "company": "Laravel Inc", "companyID": "4787243D-5CF0-46E9-AE58-D2905AD35139" }, { "company": "creata inc", "companyID": "D1252E29-319B-451B-9BD1-D426C058B948" }, { "company": "redirecttesting", "companyID": "F978009D-08EF-48F4-B4CD-D5EE9C324EB6" }, { "company": "key inc", "companyID": "2B1246B6-D764-480D-A540-D5F36FAF441C" }, { "company": "3M", "companyID": "07D6D507-8764-4CD2-818E-D64CF554D018" }, { "company": "lucky inc", "companyID": "FDA0A66E-D5D3-4CB0-AA30-D9D816ACCDAE" }, { "company": "Audi inc ", "companyID": "290CFF38-1A62-477F-8FC7-E05F0EF4360F" }, { "company": "TestPostman2 Corp", "companyID": "DEE719E5-465E-4594-AE76-E0D56D1C10B0" }, { "company": "businessuser", "companyID": "004B92D1-E2E9-4C23-89DB-E6587FE42E88" }, { "company": "bagit inc", "companyID": "1D2611BC-3FD2-4A4C-9A84-E77AD8C1A468" }, { "company": "sam1 inc", "companyID": "B0BF014C-92F9-43CA-BB66-E7E73448FD12" }, { "company": "Prism", "companyID": "C865C23F-255B-429D-A60A-E8B76BD87417" }, { "company": "Martin Inc", "companyID": "0DA3A869-75FE-4217-A3DA-E8C2BFD45232" }, { "company": "legal inc", "companyID": "2E1C7093-37F6-4BBD-90BB-EBB731F44D5B" }, { "company": "Wise Wonders co", "companyID": "ADA22909-EF3D-4C4D-BC65-EEE1B80BB7EC" }, { "company": "Alcoa", "companyID": "AF4AB3A4-B61B-428E-BDBE-F18C391D4981" }, { "company": "PostManCompany", "companyID": "3B03B479-2DD6-44B6-B01B-F772C5744518" }, { "company": "Prism", "companyID": "53AD506E-CA08-4001-B8E8-F85C76CAB492" }, { "company": "Brenford FC", "companyID": "BCF7DB76-1E5E-49C8-A99F-F9222B5C47EE" }, { "company": "TestPostman2 Corp", "companyID": "047B1FA5-44DD-4C4F-81DE-F98132033CF1" }, { "company": "Prism", "companyID": "EE862D53-7660-41CD-9409-FD28081FD9F1" }, { "company": "still inc", "companyID": "A0F1C653-CE12-4B51-9FAE-FE60EBC29C8A" } ] } } }, "headers": {} } }, "security": [] } }, "/reports/getPayrollJournalReportDeprecated": { "get": { "summary": "getPayrollJournalReportDeprecated", "deprecated": false, "description": "\nThe `getPayrollJournalReport` API generates accounting journal entries for payroll transactions.\n\n### What it does:\n\n- Returns journal entry data for payroll transactions\n- Encompasses a single pay period\n- Provides highly detailed accounting information needed for accurate tax reporting\n- Reports year-to-date measures for employees\n\n### Notes:\n- Used for tax system integration and financial reporting\n- Retrieves data for all employees within a company so should be used as an administrative function", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "getPayrollJournalReport", "examples": [ "getPayrollJournalReport" ] }, "payPeriodId": { "type": "string", "format": "uuid" }, "companyId": { "type": "string", "format": "uuid" } }, "required": [ "method", "companyId", "payPeriodId" ] }, "example": { "method": "getPayrollJournalReport", "payPeriodId": "410C7053-4656-4C28-BA9D-727101406F30", "companyId": "01A33366-EE1C-4E13-BCB9-E482AC3A4545" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "Employee": { "type": "object", "properties": { "EmployeeID": { "type": "string", "format": "uuid" }, "CompanyID": { "type": "string", "format": "uuid" }, "Employee": { "type": "string" }, "PhoneNumber": { "type": "string" }, "JobTitle": { "type": "string" }, "Cust_EMP_ID": { "type": "string" }, "details": { "type": "object", "properties": { "Employee": { "type": "object", "properties": { "EmployeeID": { "type": "string" }, "CompanyID": { "type": "string" }, "Employee": { "type": "string" }, "PhoneNumber": { "type": "string" }, "Cust_EMP_ID": { "type": "string" }, "JobTitle": { "type": "string" }, "EmployeeWages": { "type": "object", "properties": { "WageRate": { "type": "string" }, "WageBasis": { "type": "object", "properties": { "WageBasis": { "type": "string" } }, "required": [ "WageBasis" ] }, "W4Informations": { "type": "object", "properties": { "W4FilingStatus": { "type": "object", "properties": { "W4FilingStatus": { "type": "string" } }, "required": [ "W4FilingStatus" ] }, "Dependents": { "type": "number" } }, "required": [ "W4FilingStatus", "Dependents" ] }, "EmployeeAddress": { "type": "object", "properties": { "Address": { "type": "string" }, "Address1": { "type": "string" }, "Address2": { "type": "string" }, "City": { "type": "string" }, "State": { "type": "string" }, "Zipcode": { "type": "string" } }, "required": [ "Address", "Address1", "City", "State", "Zipcode" ] }, "EntityTax": { "type": "object", "properties": { "TaxID": { "type": "string" } }, "required": [ "TaxID" ] }, "PayrollLineItem": { "type": "object", "properties": { "PayPeriodID": { "type": "string", "format": "uuid" }, "PayrollLineItemID": { "type": "string", "format": "uuid" }, "PayrollLineItemDetails": { "type": "object", "properties": { "CheckNumber": { "type": "string" }, "Amount": { "type": "string" }, "PayPercentage": { "type": "string" }, "EmployeePayAccount": { "type": "object", "properties": { "PayAccountTypeID": { "type": "string" }, "EmployeePayAccountEntities": { "type": "object", "properties": { "AccountNumber": { "type": "string" }, "RoutingNumber": { "type": "string" } }, "required": [ "AccountNumber", "RoutingNumber" ] } }, "required": [ "PayAccountTypeID", "EmployeePayAccountEntities" ] }, "PayPeriod": { "type": "object", "properties": { "PayPeriod_PaySchedule": { "type": "object", "properties": { "StandardWorkingHours": { "type": "string" } }, "required": [ "StandardWorkingHours" ] } }, "required": [ "PayPeriod_PaySchedule" ] }, "PayDate": { "type": "string" }, "PayBeginDate": { "type": "string" }, "PayEndDate": { "type": "string" }, "WorkerType": { "type": "object", "properties": { "WorkerType": { "type": "string" } }, "required": [ "WorkerType" ] }, "BaseTotal": { "type": "string" }, "GrossTotal": { "type": "string" }, "NetTotal": { "type": "string" }, "payrollLineItemDetailsEmployeeTax": { "type": "object", "properties": { "VertexRefTaxCodeMapping": { "type": "object", "properties": { "TaxIdentifierID": { "type": "string" }, "TaxIdentifier": { "type": "string" }, "TaxJurisdiction": { "type": "string" } }, "required": [ "TaxIdentifierID", "TaxIdentifier", "TaxJurisdiction" ] }, "TaxAmount": { "type": "string" }, "TaxAmountYTD": { "type": "string" } }, "required": [ "VertexRefTaxCodeMapping", "TaxAmount", "TaxAmountYTD" ] }, "payrollLineItemDetailsEmployerTax": { "type": "object", "properties": { "VertexRefTaxCodeMapping": { "type": "object", "properties": { "TaxIdentifierID": { "type": "string" }, "TaxIdentifier": { "type": "string" }, "TaxJurisdiction": { "type": "string" } }, "required": [ "TaxIdentifierID", "TaxIdentifier", "TaxJurisdiction" ] }, "TaxAmount": { "type": "string" }, "TaxAmountYTD": { "type": "string" } }, "required": [ "VertexRefTaxCodeMapping", "TaxAmount", "TaxAmountYTD" ] }, "PayrollLineItemDeductions": { "type": "object", "properties": {} }, "PayrollLineItemAdditionalCompensations": { "type": "object", "properties": {} }, "PayrollLineItemYTDs": { "type": "object", "properties": { "BaseTotal": { "type": "string" }, "GrossTotal": { "type": "string" }, "NetTotal": { "type": "string" } }, "required": [ "BaseTotal", "GrossTotal", "NetTotal" ] }, "payrollLineItemPrevious": { "type": "object", "properties": {} } }, "required": [ "Amount", "PayPercentage", "EmployeePayAccount", "PayPeriod", "PayDate", "PayBeginDate", "PayEndDate", "WorkerType", "BaseTotal", "GrossTotal", "NetTotal", "payrollLineItemDetailsEmployeeTax", "payrollLineItemDetailsEmployerTax", "PayrollLineItemDeductions", "PayrollLineItemAdditionalCompensations", "PayrollLineItemYTDs", "payrollLineItemPrevious" ] } }, "required": [ "PayPeriodID", "PayrollLineItemID", "PayrollLineItemDetails" ] } }, "required": [ "WageBasis", "WageRate", "W4Informations", "EmployeeAddress", "EntityTax", "PayrollLineItem" ] } }, "required": [ "EmployeeID", "CompanyID", "Employee", "PhoneNumber", "JobTitle", "EmployeeWages" ] } }, "required": [ "Employee" ] } }, "required": [ "EmployeeID", "CompanyID", "Employee", "PhoneNumber", "JobTitle", "details" ] } }, "required": [ "Employee" ] }, "example": { "Employee": [ { "employeeID": "4E80FBFB-7FFC-406F-B0E0-8F78CA7A29C8", "companyID": "01A33366-EE1C-4E13-BCB9-E482AC3A4545", "report": { "employeereportdetails": [ { "employeeID": "4E80FBFB-7FFC-406F-B0E0-8F78CA7A29C8", "companyID": "01A33366-EE1C-4E13-BCB9-E482AC3A4545", "employeeName": "Kim James", "phoneNumber": "9889890089", "custEmpID": "", "jobTitle": "Manager", "employeeWages": [ { "wageRate": 80, "DifferentialPay": "A52FFFA1-50E7-4579-B4A8-902C07EE51D5", "PayrollRefPaymentMethodID": "46AD1353-0DAA-456A-BCBB-DE137736EC7E", "wageBasis": { "wageBasis": "Per Week" } } ], "w4Informations": [ { "w4FilingStatus": { "w4FilingStatus": "Head of household" }, "dependents": 3 } ], "employeeAddress": { "address": "650 Capitol Mall, Sacramento, CA, 95814-4708", "address1": "650 Capitol Mall", "address2": "", "city": "Sacramento", "state": "CA", "zipcode": "95814-4708" } } ], "EntityTax": [ { "taxID": "120520000" } ], "PayrollLineItem": [ { "payPeriodID": "410C7053-4656-4C28-BA9D-727101406F30", "payrollLineItemID": "87BC8593-5D72-416C-BE6A-F8D7E6290A74", "quantity": 40, "retro": false, "retroAmount": 0, "payrollLineItemDetails": [ { "checkNumber": null, "amount": 96.44, "payPercentage": 100, "employeePayAccount": { "payAccountTypeID": "DF7ED049-B678-42BC-9921-D7E193B0BA28", "employeePayAccountEntities": [ { "accountNumber": "1111222233331111", "routingNumber": "011401533" } ] } } ], "payPeriod": { "payPeriod_paySchedule": { "standardWorkingHours": 8 }, "payPeriod": "01/10/2025 - 01/16/2025", "payDate": "2025-02-07", "payBeginDate": "2025-01-10", "payEndDate": "2025-01-16", "workerType": { "workerType": "W2" } }, "baseTotal": 111, "grossTotal": 111, "netTotal": 96.44, "PayrollLineItem_OverTimes": [], "PayrollLineItemReimbursements": [], "payrollLineItemDetailsEmployeeTax": [], "payrollLineItemDetailsEmployerTax": [], "payrollLineItemDeductions": [], "payrollLineItemAdditionalCompensations": [], "payrollLineItemYTDs": [ { "baseTotalYTD": 111, "grossTotalYTD": 111, "netTotalYTD": 96.44 } ] } ], "payrollLineItemPrevious": [] } }, { "employeeID": "D8934854-20F7-4607-8007-A4B78254007F", "companyID": "01A33366-EE1C-4E13-BCB9-E482AC3A4545", "report": { "employeereportdetails": [ { "employeeID": "D8934854-20F7-4607-8007-A4B78254007F", "companyID": "01A33366-EE1C-4E13-BCB9-E482AC3A4545", "employeeName": "Regina Wise", "phoneNumber": "2511630007", "custEmpID": null, "jobTitle": "HR", "employeeWages": [], "w4Informations": [], "employeeAddress": { "address": "102 Fallsgrove Blvd, Rockville, MD, 20850-4713", "address1": "102 Fallsgrove Blvd", "address2": "", "city": "Rockville", "state": "MD", "zipcode": "20850-4713" } } ], "EntityTax": [ { "taxID": "587400936" } ], "PayrollLineItem": [], "payrollLineItemPrevious": [] } } ], "Company": [ { "company": "Torp Group", "kybInformations": [ { "phoneNumber": "8587458008" } ] } ], "EntityTax": [ { "taxID": "600800500" } ], "CompanyLocation": [ { "address": "8435 Colard Ln, Lyons, CO, 80540", "companyLocation": "22 Main", "address1": "8435 Colard Ln", "address2": "", "city": "Lyons", "state": "CO", "zipcode": "80540" } ], "PayPeriod": [ { "payDate": "2025-02-07", "payBeginDate": "2025-01-10", "payEndDate": "2025-01-16", "payPeriod": "01/10/2025 - 01/16/2025", "workerType": { "workerType": "W2" }, "isProcessed": true, "isActive": true } ] } } }, "headers": {} } }, "security": [] } }, "/reports/getStateW4FormFields": { "get": { "summary": "getStateW4FormFields", "deprecated": false, "description": "The `getStateW4FormFields` API retrieves state-specific W4 form fields for an employee based on their location.\n\n### What it does:\n\n- Returns state-specific W4 form fields and their available options\n- Provides field descriptions for state tax withholding forms (e.g. Married, Single etc.)\n- Provides data type restrictions for W4 fields to prevent input error\n\n### Notes:\n\n- Employees state is determined using their **userId**\n- **userId or stateCode** is required to retrieve the correct fields for the state\n- Used before calling `addStateW4Information` to get the required fields for that state", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "getStateW4FormFeilds", "examples": [ "getStateW4FormFeilds" ] }, "userId": { "type": "string" }, "stateCode": { "type": "string" } }, "required": [ "method" ] }, "example": { "method": "getStateW4FormFields", "userId": "A31A0E84-3643-405A-B0E4-D229D0A194FB", "stateCode": "CA" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "employeeId": { "type": "string" }, "stateCode": { "type": "string" }, "stateW4FieldsList": { "type": "object", "properties": { "Filing Status": { "type": "string" }, "Withholding Allowance": { "type": "string" }, "Additional Withholding": { "type": "string" }, "NYC Withholding Allowance": { "type": "string" }, "NYC Additional Withholding": { "type": "string" } }, "required": [ "Filing Status", "Withholding Allowance", "Additional Withholding", "NYC Withholding Allowance", "NYC Additional Withholding" ] }, "fields": { "type": "array", "items": { "type": "object", "properties": { "fieldName": { "type": "string" }, "fieldDescription": { "type": "string" }, "options": { "type": "array", "items": { "type": "string" } }, "dataType": { "type": "string" } }, "required": [ "fieldName", "dataType" ] } } }, "required": [ "employeeId", "stateCode", "stateW4FieldsList", "fields" ] }, "example": { "employeeId": "A31A0E84-3643-405A-B0E4-D229D0A194FB", "stateCode": "NY", "stateW4FieldsList": { "Filing Status": "", "Withholding Allowance": "", "Additional Withholding": "", "NYC Withholding Allowance": "", "NYC Additional Withholding": "" }, "fields": [ { "fieldName": "Filing Status", "fieldDescription": "In most cases, use the same filing status that you used on your federal return. If unsure, read the official NY filing status definition(\"https://www.tax.ny.gov/pit/file/filing_status.htm/\")", "options": [ "Married, but withhold as single", "Married", "Single" ] }, { "fieldName": "Withholding Allowance", "fieldDescription": null, "dataType": "Number" }, { "fieldName": "Additional Withholding", "fieldDescription": null, "dataType": "Double" }, { "fieldName": "NYC Withholding Allowance", "fieldDescription": null, "dataType": "Number" }, { "fieldName": "NYC Additional Withholding", "fieldDescription": null, "dataType": "Double" } ] } } }, "headers": {} } }, "security": [] } }, "/reports/getEmployeeMiscellaneousStateTaxFormFields": { "get": { "summary": "getEmployeeMiscellaneousStateTaxFormFields", "deprecated": false, "description": "\nThe `getEmployeeMiscellaneousStateTaxFormFields ` API retrieves available miscellaneous state tax fields for users based on their state of residence.\n\n### What it does:\n\n- Returns fields that can be used to add state taxes on an employee by employee basis for payroll\n\n### Note:\n\n- Once retrieved these fields should be added to a user's record using `addEmployeeMiscellaneousStateTax`. This will allow them to be added to payroll later.\n", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "userId": { "type": "string" } }, "required": [ "method", "companyId", "userId" ] }, "example": { "method": "getEmployeeMiscellaneousStateTaxFormFields", "companyId": "C2019899-9EEF-49F7-9B51-70744AFAFE61", "userId": "B7C80B1C-B58B-4ADD-9193-1BB23674F514" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "EmployeeMiscellaneousStateTaxFormFields": { "type": "object", "properties": { "userId": { "type": "string" }, "stateCode": { "type": "string" }, "MiscellaneousStateTaxFieldList": { "type": "array", "items": { "type": "string" } }, "fields": { "type": "object", "properties": { "fieldName": { "type": "string" }, "fieldDescription": { "type": "string" }, "dataType": { "type": "string" } }, "required": [ "fieldName", "fieldDescription", "dataType" ] } }, "required": [ "userId", "stateCode", "MiscellaneousStateTaxFieldList", "fields" ] } }, "required": [ "EmployeeMiscellaneousStateTaxFormFields" ] }, "examples": { "1": { "summary": "Example 1", "value": { "EmployeeMiscellaneousStateTaxFormFields": [ { "userId": "98CCB6CF-08DD-4C17-A367-B339CD5526CD", "stateCode": "WA", "MiscellaneousStateTaxFieldList": { "CompositeRate": "", "RiskClassName": "", "RiskClassCode": "", "PayrollDeductionRate": "" }, "fields": [ { "fieldName": "CompositeRate", "fieldDescription": "", "dataType": "String" }, { "fieldName": "RiskClassName", "fieldDescription": "", "dataType": "String" }, { "fieldName": "RiskClassCode", "fieldDescription": "", "dataType": "String" }, { "fieldName": "PayrollDeductionRate", "fieldDescription": "", "dataType": "String" }, { "fieldName": "RiskClassName", "fieldDescription": "", "dataType": "String" } ] } ] } }, "2": { "summary": "Example 1", "value": { "error": { "code": 400, "message": "Company ID is required" } } } } } }, "headers": {} } }, "security": [] } }, "/reports/getEmployeeMiscellaneousStateTaxforPayroll": { "get": { "summary": "getEmployeeMiscellaneousStateTaxforPayroll", "deprecated": false, "description": "\nThe `getEmployeeMiscellaneousStateTaxforPayroll ` API retrieves the miscellaneous state tax fields that have previously been added to a user's record to be used in payroll processing.\n\n### What it does:\n\n- Retrieves the miscellaneous state tax information on a user-by-user basis to be added to payroll\n\n### Note:\n\n- Once retrieved these can be added to payroll for the specified user.\n", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "employeeId": { "type": "string" } }, "required": [ "method", "companyId", "employeeId" ] }, "example": { "method": "getEmployeeMiscellaneousStateTaxforPayroll", "companyId": "C2019899-9EEF-49F7-9B51-70744AFAFE61", "employeeId": "2F305A44-60EB-4B65-BACB-6E83FF2A49A6" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "miscellaneousStateTaxes": { "type": "object", "properties": { "stateCode": { "type": "string" }, "taxName": { "type": "string" }, "taxDetails": { "type": "object", "properties": { "riskClassName": { "type": "string" }, "noOfHours": { "type": "string" } }, "required": [ "riskClassName", "noOfHours" ] } }, "required": [ "stateCode", "taxName", "taxDetails" ] } }, "required": [ "miscellaneousStateTaxes" ] }, "example": { "miscellaneousStateTaxes": [ { "stateCode": "WA", "taxName": "Washington L&I", "taxDetails": [ { "riskClassName": "Electrician", "noOfHours": 0 } ] } ] } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": { "error": { "code": 400, "message": "User ID is required" } } } }, "headers": {} } }, "security": [] } }, "/reports/getPayBeginDates": { "get": { "summary": "getPayBeginDates", "deprecated": false, "description": "\nThe `getPayBeginDates` API returns available pay begin dates for Monthly and Semi-Monthly compensation frequencies.\n\n### What it does:\n\n- Returns valid pay begin date options for Monthly and Semi-Monthly pay schedules\n- Used when setting up pay schedules to ensure proper payroll calendar alignment", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "getUser" }, "compensationFrequency": { "type": "string" } }, "required": [ "method", "compensationFrequency" ] }, "example": { "method": "getMonthlyAndSemiMonthlyPayBeginDates", "compensationFrequency": "Monthly" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "PayBeginDates for Monthly": { "type": "array", "items": { "type": "string" } } }, "required": [ "PayBeginDates for Monthly" ] }, "example": { "PayBeginDates for Monthly": [ "2025-01-01", "2025-02-01", "2025-03-01", "2025-04-01", "2025-05-01", "2025-06-01", "2025-07-01", "2025-08-01", "2025-09-01", "2025-10-01", "2025-11-01", "2025-12-01" ] } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "EmployeeId is Mandatory." } } } }, "headers": {} } }, "security": [] } }, "/reports/getStateRegistrationFields": { "get": { "summary": "getStateRegistrationFields", "deprecated": false, "description": "\nThe `getStateRegistrationFields` API retrieves state registration information for a given state code.\n\n### What it does:\n\n- Provides state-specific registration information and requirements for payroll tax compliance", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "getUser" }, "code": { "type": "string" } }, "required": [ "method", "code" ] }, "example": { "method": "getStateRegistrationFields", "code": "WA" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "companyStateRegistrationFieldList": { "type": "object", "properties": { "Employment Security Department Account Number": { "type": "string" }, "Universal Business ID (UBI)": { "type": "string" }, "Labor and Industries Account Number": { "type": "string" }, "Required to pay PFML employer portion?": { "type": "string" }, "EAF Tax Rate": { "type": "string" }, "Unemployment Rate": { "type": "string" } }, "required": [ "Employment Security Department Account Number", "Universal Business ID (UBI)", "Labor and Industries Account Number", "Required to pay PFML employer portion?", "EAF Tax Rate", "Unemployment Rate" ] }, "fieldDescription": { "type": "object", "properties": { "Employment Security Department Account Number": { "type": "object", "properties": { "isMandatory": { "type": "boolean" } }, "required": [ "isMandatory" ] }, "Universal Business ID (UBI)": { "type": "object", "properties": { "isMandatory": { "type": "boolean" } }, "required": [ "isMandatory" ] }, "Labor and Industries Account Number": { "type": "object", "properties": { "isMandatory": { "type": "boolean" } }, "required": [ "isMandatory" ] }, "Required to pay PFML employer portion?": { "type": "object", "properties": { "isMandatory": { "type": "boolean" } }, "required": [ "isMandatory" ] }, "EAF Tax Rate": { "type": "object", "properties": { "isMandatory": { "type": "boolean" } }, "required": [ "isMandatory" ] }, "Unemployment Rate": { "type": "object", "properties": { "isMandatory": { "type": "boolean" } }, "required": [ "isMandatory" ] } }, "required": [ "Employment Security Department Account Number", "Universal Business ID (UBI)", "Labor and Industries Account Number", "Required to pay PFML employer portion?", "EAF Tax Rate", "Unemployment Rate" ] } }, "required": [ "code", "companyStateRegistrationFieldList", "fieldDescription" ] }, "examples": { "1": { "summary": "Success", "value": { "code": "WA", "companyStateRegistrationFieldList": { "Employment Security Department Account Number": "", "Universal Business ID (UBI)": "", "Labor and Industries Account Number": "", "Required to pay PFML employer portion?": "", "EAF Tax Rate": "", "Unemployment Rate": "" }, "fieldDescription": { "Employment Security Department Account Number": { "isMandatory": false }, "Universal Business ID (UBI)": { "isMandatory": false }, "Labor and Industries Account Number": { "isMandatory": false }, "Required to pay PFML employer portion?": { "isMandatory": true }, "EAF Tax Rate": { "isMandatory": false }, "Unemployment Rate": { "isMandatory": true } } } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "EmployeeId is Mandatory." } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } }, "headers": {} } }, "security": [] } }, "/reports/getOverTimeTypes": { "get": { "summary": "getOverTimeTypes", "deprecated": false, "description": "\nThe `getOverTimeTypes` API retrieves available overtime type identifiers that can be used in payroll processing and time tracking.\n\n### What it does:\n\n- Returns a list of accepted overtime types for payroll processing\n- Provides standardized overtime identifiers for time tracking and payroll calculations\n- Allows users to receive pay on top of their base amount that is recorded and taxed accordingly", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "getUser" } }, "required": [ "method" ] }, "example": { "method": "getOverTimeTypes" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "overTimeTypes": { "type": "array", "items": { "type": "string" } } }, "required": [ "overTimeTypes" ] }, "example": { "overTimeTypes": [ "Compensatory Time Off", "Holiday/Weekend OT", "Premium OT (over 20 hours)" ] } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "EmployeeId is Mandatory." } } } }, "headers": {} } }, "security": [] } }, "/reports/getDeductionDescription": { "get": { "summary": "getDeductionDescription", "deprecated": false, "description": "\nThe `getDeductionDescription` API retrieves available deduction identifiers that can be used in payroll processing to indicate employee contributions and voluntary withholdings.\n\n### What it does:\n\n- Returns a list of identifiers for different deduction programs which employees may subscribe to (Life Insurance, 401K, Vision Insurance etc.)\n- Provides information for non-tax withholdings which decrease an employees gross pay", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "getUser" } }, "required": [ "method" ] }, "example": { "method": "getDeductionDescription" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "deductionDescription": { "type": "array", "items": { "type": "string" } } }, "required": [ "deductionDescription" ] }, "example": { "deductionDescription": [ "125Adoption Assistance Reg", "125Adoption Assistance Sup", "125DC Reg", "125DC Sup", "125FSA Reg", "125FSA Sup", "125HSA CU Reg", "125HSA CU Sup", "125HSA Reg", "125HSA Sup", "401K CU2 Over 50 Reg", "401K CU2 Over 50 Sup", "401K Deferral Reg", "401K Deferral Sup", "403B CU 15 year Reg", "403B CU 15 year Sup", "403B CU2 Over 50 Reg", "403B CU2 Over 50 Sup", "403B Deferral Reg", "403B Deferral Sup", "408K CU2 Over 50", "408K CU2 Over 50 Sup", "408K Deferral Reg", "408K Deferral Sup", "408P CU2 Over 50 Reg", "408P CU2 Over 50 Sup", "408P Deferral Reg", "408P Deferral Sup", "409A Deferral Reg", "409A Deferral Sup", "457 CU2 Over 50 Reg", "457 CU2 Over 50 Sup", "457 Deferral Reg", "457 Deferral Sup", "457CU Increased Limit Reg", "457CU Increased Limit Sup", "Accident Insurance", "CN RPP", "CN RPP Sup", "CN RRSP Reg", "CN RRSP Sup", "CN Union Dues", "CN Union Dues Sup", "CN at Source", "CN at Source Sup", "Critical Illness Insurance", "Dental Insurance (Employee Contribution)", "Hospital Indemnity Insurance", "Insurance Benefits Reg", "Insurance Benefits Sup", "Life Insurance", "Life Insurance - Child", "Life Insurance - Spouse", "Long Term Disability (LTD) Insurance", "Medical Insurance (Employee Contribution)", "Other Supplemental Insurance", "Qualified Parking Reg", "Qualified Parking Sup", "Roth 401K Employee Contribution", "Roth 401K Reg", "Roth 401K Sup", "Short Term Disability (STD) Insurance", "Traditional IRA Employee Contribution", "Vanpool and Transit Passes Reg", "Vanpool and Transit Passes Sup", "Vision Insurance (Employee Contribution)" ] } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "EmployeeId is Mandatory." } } } }, "headers": {} } }, "security": [] } }, "/reports/getAdditionalCompensationDescription": { "get": { "summary": "getAdditionalCompensationDescription", "deprecated": false, "description": "The `getAdditionalCompensationDescription` API is used to retrieve available additional compensation descriptions that can be used in payroll processing.\n\n### What it does:\n\n- Returns a list of descriptions for additional payroll types (Bonus, HSA, Reported Tips etc.)\n- Provides compensation type identifiers that don't fit into the simple wage structure\n\n### Note:\n- WorkerType (optional) can be used to view additionalCompensations that are scoped only to W2s or 1099s", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "getUser" }, "workerType": { "type": "string", "enum": [ "W2", "1099-NEC" ] } }, "required": [ "method" ] }, "example": { "method": "getAdditionalCompensationDescription", "workerType": "W2" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "additionalCompensationDescription": { "type": "array", "items": { "type": "string" } } }, "required": [ "additionalCompensationDescription" ] }, "examples": { "1": { "summary": "Success", "value": { "additionalCompensationDescription": [ "3rd Party LTD 125 plan", "3rd Party STD 125 plan", "409A Distribution", "Adoption Assistance", "Adult Child Health Coverage", "Agent LTD 125 plan", "Agent STD 125 plan", "Bonus", "Cash", "Clergy Housing Allowance", "Deceased Worker Pay", "Domestic Partner Benefit Dependent", "Domestic Partner Benefit Non-Dependent", "ER LTD 125 plan", "ER STD 125 plan", "Educational Asst (Job Related)", "Educational Asst (Non-job Related)", "Emergency Paid Sick Leave", "Expanded Family and Medical Leave", "Golden Parachute", "Group Term Life Over $50000", "HSA", "HSA(125)", "Invalid 409A Deferral", "Meals for the convenience of ER", "Military Differential Pay", "Phone Reimbursement", "Qualified Moving Expenses Reimbursements", "Qualified Parking", "Reported Tips", "S Corp 2% Shareholder Insurance Premiums", "Same sex marriage spousal health care", "Severance Pay", "Severance Pay Required by law or contract", "Stock Options", "Training Reimbursement", "Van Pool & Transit Passes", "Well-Being Stipend" ] } }, "2": { "summary": "Exception", "value": { "error": { "code": 400, "message": "EmployeeId is Mandatory." } } } } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } }, "headers": {} } }, "security": [] } }, "/reports/getCompanyTask": { "get": { "summary": "getCompanyTask", "deprecated": false, "description": "\nThe `getCompanyTask` API retrieves a list of pending tasks that should be completed during onboarding and day-to-day operations.\n\n### What it does:\n\n- Identifies incomplete onboarding steps such as KYB verification, bank account setup, or pay schedule configuration\n- Returns pending tasks during day-to-day operation including reminders to run payroll, complete employee onboarding, sign vital forms, and submit state tax registration\n\n### Note:\n\n- Important outstanding tasks can prevent payroll running successfully. If a payroll fails this is the first place to check", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" } }, "required": [ "method", "companyId" ] }, "example": { "method": "getCompanyTask", "companyId": "2DFCA586-C2D4-4FD7-B823-063F2575A5E7" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "properties": { "task": { "type": "string" }, "description": { "type": "string" } }, "required": [ "task", "description" ] } } }, "required": [ "tasks" ] }, "example": { "tasks": [ { "task": "Add Wage", "description": "Enter pay details to 41 team members ready for payday" }, { "task": "Form DR-835 Signature request", "description": "Form DR-835 allows us to file and pay taxes on your behalf" }, { "task": "Form 8655 Signature request", "description": "Form 8655 allows us to file and pay taxes on your behalf" }, { "task": "Add check details", "description": "Provide check details" }, { "task": "Missing State tax information", "description": "Missing State Tax Registration Details for CO" }, { "task": "Run Payroll", "description": "Overdue for employees by 50 days to run payroll for [05/28/2025-06/03/2025]" } ] } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "EmployeeId is Mandatory." } } } }, "headers": {} } }, "security": [] } }, "/reports/getAllowedTaxAdjustmentsList": { "get": { "summary": "getAllowedTaxAdjustmentsList", "deprecated": false, "description": "The `getAllowedTaxAdjustmentsList` retrieves a list of taxes that apply to an employee for manual adjustment.\n\n### When to use:\n\n- To retrieve tax tyoes that can be manually adjusted\n- When taxes are calculated incorrectly and need to be ammended\n- When taxes were calculated incorrectly in a previous pay period to correct total YTD withholding for the employee\n\n### Note:\n- Once retrieved these adjustments can be added to an employee using the `addPayrollLineItemTaxAdjustments` API", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" } }, "required": [ "method" ] }, "example": { "method": "getAllowedTaxAdjustmentsList" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "allowedTaxAdjustments": { "type": "array", "items": { "type": "object", "properties": { "taxTypeCategory": { "type": "string" }, "taxName": { "type": "string" } } } } }, "required": [ "allowedTaxAdjustments" ] }, "example": { "allowedTaxAdjustments": [ { "taxTypeCategory": "Federal", "taxName": "Federal Withholding Tax" } ] } } }, "headers": {} } }, "security": [] } }, "/reports/getTaxNameForExemption": { "get": { "summary": "getTaxNameForExemption", "deprecated": false, "description": "Retrieves the taxNames that can be added as exemptions for employees and companies\n\nNote:\n- Once retrieved use these taxNames with the `addPayrollTaxExemption` API\n- userId is optional, include it to find employee specific taxNames or omit it to find company taxNames\n- Some taxes are returned with a `High Risk` indicator and a warning message. This message should be displayed clearly on your UI to limit legal liability", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "userId": { "type": "string" } }, "required": [ "method", "companyId" ] }, "example": { "method": "getTaxNameForExemption", "companyId": "ECF1B47E-108F-45C0-A520-6A128A727B04", "userId": "33820169-85C2-482A-BCCF-B2281419E96E" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "EmployerTaxName": { "type": "array", "items": { "type": "object", "properties": { "taxName": { "type": "string" }, "ExemptionStatus": { "type": "string" }, "warningMessage": { "type": "string" } }, "required": [ "taxName" ] } } }, "required": [ "EmployerTaxName" ] }, "example": { "EmployerTaxName": [ { "taxName": "FL - State Unemployment Insurance", "ExemptionStatus": "High Risk", "warningMessage": "High-risk tax exemption. Confirm eligibility and effective dates before saving. If applied incorrectly, this may result in inaccurate reporting, tax underpayment, and required corrections." }, { "taxName": "FUTA", "ExemptionStatus": "High Risk", "warningMessage": "High-risk tax exemption. Confirm eligibility and effective dates before saving. If applied incorrectly, this may result in inaccurate reporting, tax underpayment, and required corrections." }, { "taxName": "WA - Industrial Insurance EE" } ] } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": { "error": { "code": 400, "message": "companyId is required." } } } }, "headers": {} } }, "security": [] } }, "/reports/getUploadedDocuments": { "get": { "summary": "getUploadedDocuments", "deprecated": false, "description": "The `getUploadedDocuments` API retrieves a list of uploaded documents alongside their document-specific IDs.\n\n### What it does:\n- Retrieves uploaded documents that can then be downloaded using the `downloadDocument` API\n- Filters by `companyId`, `employeeId`, and `payPeriodId`\n- Returns a list of `documentId` values\n- Use this when selecting a document to download from a drop-down menu\n\n### State W-4s\n- Employees' pre-filled state W-4s are automatically generated after `initiateUserKyc`\n- State W-4 forms can be identified by their `documentType`: `{StateCode}W4Form`, e.g., `NJW4Form`\n- To download a pre-filled state W-4, use the `downloadDocument` API with the provided `documentId`\n\n### Note:\n- At least one ID must be included in the request for filtering", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "employeeId": { "type": "string" }, "payPeriodId": { "type": "string" } }, "required": [ "method" ] }, "example": { "method": "getUploadedDocuments", "companyId": "EB45E206-5E50-4079-8B41-04C05E4C5338" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "items": { "type": "object", "properties": { "documentId": { "type": "string" }, "companyId": { "type": "string" }, "employeeId": { "type": "string" }, "payPeriodId": { "type": "string" }, "fileName": { "type": "string" }, "documentType": { "type": "string" } }, "required": [ "documentId", "fileName", "documentType", "companyId" ] } } }, "required": [ "documents" ] }, "example": { "documents": [ { "documentId": "3F33DB6B-FFA2-4560-BE56-E7D76A840B57", "companyId": "EB45E206-5E50-4079-8B41-04C05E4C5338", "employeeId": "49720D41-693D-435B-982F-7D0C47ECAF61", "fileName": "FormW4.pdf", "documentType": "W4Form" }, { "documentId": "8EA08254-5EB3-4B2C-8677-E86AECF60B94", "companyId": "EB45E206-5E50-4079-8B41-04C05E4C5338", "fileName": "FormDR-835.pdf", "documentType": "DR-835Form" }, { "documentId": "04F235EE-8CEA-4171-A796-8E62CA92C8B1", "companyId": "EB45E206-5E50-4079-8B41-04C05E4C5338", "fileName": "FormTR-2000.pdf", "documentType": "TR-2000Form" }, { "documentId": "8654D9DC-2C37-45C9-B6EF-A4E036F78A8B", "companyId": "EB45E206-5E50-4079-8B41-04C05E4C5338", "employeeId": "9B3B66A3-94A5-413B-B2C4-F24A651297B8", "fileName": "FormW4.pdf", "documentType": "W4Form" }, { "documentId": "4F9C341A-B9AA-4E91-8C7C-2371F32A728F", "companyId": "EB45E206-5E50-4079-8B41-04C05E4C5338", "employeeId": "49720D41-693D-435B-982F-7D0C47ECAF61", "fileName": "FormW4.pdf", "documentType": "W4Form" }, { "documentId": "0264ACB0-F3A0-4A9B-9344-D700CC6168DB", "companyId": "EB45E206-5E50-4079-8B41-04C05E4C5338", "fileName": "Form8655.pdf", "documentType": "8655Form" } ] } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 400, "message": "At least one of companyId, employeeId, or payPeriodId is required" } } } }, "headers": {} } }, "security": [] } }, "/reports/getEmployeeTaxExemptions": { "get": { "summary": "getEmployeeTaxExemptions", "deprecated": false, "description": "Retrieves the current tax exemptions applied to an employee\n\n### What it does:\n- Used to display the exemptions that have been added for an employee\n- Once retrieved use `updatePayrollTaxExemption` API to remove the exemption or set the **effectiveEndDate**\n\n### Notes:\n- High Risk taxes will return the exemptionStatus and a warningMessage designed to limit legal liabilities\n- When a taxName is `High Risk`, include the warning message on your UI before using `addPayrollTaxExemptions`", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" }, "userId": { "type": "string" } }, "required": [ "method", "companyId", "userId" ] }, "example": { "method": "getEmployeeTaxExemptions", "companyId": "ECF1B47E-108F-45C0-A520-6A128A727B04", "userId": "33820169-85C2-482A-BCCF-B2281419E96E" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "employeeTaxExemptions": { "type": "array", "items": { "type": "object", "properties": { "taxName": { "type": "string" }, "exemptionEffectiveStartDate": { "type": "string" }, "exemptionEffectiveEndDate": { "type": "string" }, "exemptReason": { "type": "string" }, "ExemptionStatus": { "type": "string" }, "warningMessage": { "type": "string" } }, "required": [ "taxName", "exemptionEffectiveStartDate", "exemptionEffectiveEndDate", "exemptReason" ] } } }, "required": [ "employeeTaxExemptions" ] }, "example": { "employeeTaxExemptions": [ { "taxName": "CA - State Disability Insurance", "exemptionEffectiveStartDate": "2026-03-20", "exemptionEffectiveEndDate": null, "exemptReason": "Employee claimed exempt on W-4", "ExemptionStatus": "High Risk", "warningMessage": "High-risk tax exemption. Confirm eligibility and effective dates before saving. If applied incorrectly, this may result in inaccurate reporting, tax underpayment, and required corrections." }, { "taxName": "CO - State paid family and medical leave EE", "exemptionEffectiveStartDate": "2026-03-20", "exemptionEffectiveEndDate": null, "exemptReason": "Employee claimed exempt on W-4" } ] } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 404, "message": "Employee not found with ID: 33820169-85C2-482A-BCCF-B2f281419E96E for company: ECF1B47E-108F-45C0-A520-6A128A727B04" } } } }, "headers": {} } }, "security": [] } }, "/reports/getCompanyTaxExemptions": { "get": { "summary": "getCompanyTaxExemptions", "deprecated": false, "description": "Retrieves the current tax exemptions applied to an company\n\n### What it does:\n- Used to display the exemptions that have been added for an company\n- Once retrieved use `updatePayrollTaxExemption` API to remove the exemption or set the **effectiveEndDate**\n\n### Notes:\n- High Risk taxes will return the exemptionStatus and a warningMessage designed to limit legal liabilities\n- When a taxName is `High Risk`, include the warning message on your UI before using `addPayrollTaxExemptions`", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "companyId": { "type": "string" } }, "required": [ "method", "companyId" ] }, "example": { "method": "getCompanyTaxExemptions", "companyId": "ECF1B47E-108F-45C0-A520-6A128A727B04" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "companyTaxExemptions": { "type": "array", "items": { "type": "object", "properties": { "taxName": { "type": "string" }, "exemptionEffectiveStartDate": { "type": "string" }, "exemptionEffectiveEndDate": { "type": "string" }, "exemptReason": { "type": "string" }, "ExemptionStatus": { "type": "string" }, "warningMessage": { "type": "string" } }, "required": [ "taxName", "exemptionEffectiveStartDate", "exemptionEffectiveEndDate", "exemptReason" ] } } }, "required": [ "companyTaxExemptions" ] }, "example": { "companyTaxExemptions": [ { "taxName": "NY - State Unemployment Insurance", "exemptionEffectiveStartDate": "2026-03-20", "exemptionEffectiveEndDate": null, "exemptReason": "Employer claimed exempt on W-4", "ExemptionStatus": "High Risk", "warningMessage": "High-risk tax exemption. Confirm eligibility and effective dates before saving. If applied incorrectly, this may result in inaccurate reporting, tax underpayment, and required corrections." }, { "taxName": "FL - State Unemployment Insurance", "exemptionEffectiveStartDate": "2026-03-20", "exemptionEffectiveEndDate": "2026-03-30", "exemptReason": "Employer claimed exempt on W-4", "ExemptionStatus": "High Risk", "warningMessage": "High-risk tax exemption. Confirm eligibility and effective dates before saving. If applied incorrectly, this may result in inaccurate reporting, tax underpayment, and required corrections." }, { "taxName": "CA - State Unemployment Insurance", "exemptionEffectiveStartDate": "2026-03-20", "exemptionEffectiveEndDate": null, "exemptReason": "Employer claimed exempt on W-4", "ExemptionStatus": "High Risk", "warningMessage": "High-risk tax exemption. Confirm eligibility and effective dates before saving. If applied incorrectly, this may result in inaccurate reporting, tax underpayment, and required corrections." }, { "taxName": "NY - County Tax", "exemptionEffectiveStartDate": "2026-03-20", "exemptionEffectiveEndDate": null, "exemptReason": "Employer claimed exempt on W-4" } ] } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "example": { "error": { "code": 404, "message": "Company not found with ID: ECF1B47E-108F-45C0-A520-6A128A7d27B04" } } } }, "headers": {} } }, "security": [] } }, "/reports/getPayrollJournalReports": { "get": { "summary": "getPayrollJournalReports", "deprecated": false, "description": "The `getPayrollJournalReports` API generates accounting journal entries for payroll transactions.\n\n### What it does:\n\n- Returns journal entry data for payroll transactions\n- Encompasses a single pay period\n- Provides highly detailed accounting information needed for accurate tax reporting\n- Reports year-to-date measures for employees\n\n### Notes:\n\n- This is the updated and detailled version of the `getPayrollJournalReport` API\n- Used for tax system integration and financial reporting\n- Retrieves data for all employees within a company so should be used as an administrative function", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "getPayrollJournalReport", "examples": [ "getPayrollJournalReport" ] }, "payPeriodId": { "type": "string", "format": "uuid" }, "companyId": { "type": "string", "format": "uuid" } }, "required": [ "method", "companyId", "payPeriodId" ] }, "example": { "method": "getPayrollJournalReports", "payPeriodId": "5465C126-BACD-4593-97CE-24243FFFC998", "companyId": "C3C91397-CDBA-44E0-A296-0BFC9A4DFDF5" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "payrollJournalReport": { "type": "object", "properties": { "companyName": { "type": "string" }, "companyPhone": { "type": "string" }, "companyAddress": { "type": "object", "properties": { "address": { "type": "string" }, "address1": { "type": "string" }, "address2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zipcode": { "type": "string" } }, "required": [ "address", "address1", "address2", "city", "state", "zipcode" ] }, "payPeriod": { "type": "string" }, "payBeginDate": { "type": "string" }, "payEndDate": { "type": "string" }, "payDate": { "type": "string" }, "payPeriodStatus": { "type": "string" }, "workerType": { "type": "string" } }, "required": [ "companyName", "companyPhone", "companyAddress", "payPeriod", "payBeginDate", "payEndDate", "payDate", "payPeriodStatus", "workerType" ] }, "employees": { "type": "array", "items": { "type": "object", "properties": { "employeeName": { "type": "string" }, "employeeId": { "type": "string" }, "jobTitle": { "type": "string" }, "wageBasis": { "type": "string" }, "earnings": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "hours": { "type": [ "integer", "null" ] }, "total": { "type": [ "number", "integer" ] }, "rate": { "type": [ "number", "integer", "null" ] } }, "required": [ "description", "hours", "total", "rate" ] } }, "totalEarnings": { "type": [ "number", "integer" ] } }, "required": [ "items", "totalEarnings" ] }, "deductions": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "type": { "type": "string" }, "amount": { "type": "integer" }, "amountYTD": { "type": "integer" } }, "required": [ "description", "type", "amount", "amountYTD" ] } }, "garnishments": { "type": "array", "items": { "type": "string" } }, "totalDeductions": { "type": "integer" } }, "required": [ "items", "garnishments", "totalDeductions" ] }, "employeeTaxes": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "taxName": { "type": "string" }, "amount": { "type": [ "number", "integer" ] } }, "required": [ "taxName", "amount" ] } }, "totalEmployeeTaxes": { "type": [ "number", "integer" ] } }, "required": [ "items", "totalEmployeeTaxes" ] }, "employerTaxes": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "taxName": { "type": "string" }, "amount": { "type": [ "number", "integer" ] } }, "required": [ "taxName", "amount" ] } }, "totalEmployerTaxes": { "type": [ "number", "integer" ] } }, "required": [ "items", "totalEmployerTaxes" ] }, "netPayDistribution": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "amount": { "type": [ "number", "integer" ] } }, "required": [ "description", "amount" ] } }, "timeOffs": { "type": "array", "items": { "type": "object", "properties": { "leaveType": { "type": "string" }, "amount": { "type": "number" }, "hours": { "type": "integer" } }, "required": [ "leaveType", "hours" ] } }, "netPay": { "type": [ "number", "integer" ] } }, "required": [ "employeeName", "employeeId", "jobTitle", "wageBasis", "earnings", "deductions", "employeeTaxes", "employerTaxes", "netPayDistribution", "timeOffs", "netPay" ] } }, "companyTotal": { "type": "object", "properties": { "totalEarnings": { "type": "number" }, "totalDeductions": { "type": "integer" }, "employeeTaxes": { "type": "array", "items": { "type": "object", "properties": { "taxName": { "type": "string" }, "amount": { "type": [ "number", "integer" ] } }, "required": [ "taxName", "amount" ] } }, "totalEmployeeTaxes": { "type": "number" }, "employerTaxes": { "type": "array", "items": { "type": "object", "properties": { "taxName": { "type": "string" }, "amount": { "type": [ "number", "integer" ] } }, "required": [ "taxName", "amount" ] } }, "totalEmployerTaxes": { "type": "number" }, "netPay": { "type": "number" } }, "required": [ "totalEarnings", "totalDeductions", "employeeTaxes", "totalEmployeeTaxes", "employerTaxes", "totalEmployerTaxes", "netPay" ] } }, "required": [ "payrollJournalReport", "employees", "companyTotal" ] }, "example": { "payrollJournalReport": { "companyName": "timeTrack-02-25", "companyPhone": "9974574177", "companyAddress": { "address": "fejj Ste H Annapolis Junction MD 18263 US", "address1": "fejj", "address2": "Ste H", "city": "Annapolis Junction", "state": "MD", "zipcode": "18263" }, "payPeriod": "04/27/2026 - 05/03/2026", "payBeginDate": "2026-04-27", "payEndDate": "2026-05-03", "payDate": "2026-05-26", "payPeriodStatus": "DRAFT: NOT SUBMITTED", "workerType": "W2" }, "employees": [ { "employeeName": "Jim Diff", "employeeId": "7DDA5D2F-7559-4427-A0B9-1CD8C33288FC", "jobTitle": "CTO", "wageBasis": "Per Hour", "earnings": { "items": [ { "description": "Overtime Hours", "hours": 1, "rate": 0, "total": 0 }, { "description": "Regular Hours", "hours": 8, "rate": 0, "total": 0 } ], "totalEarnings": 0 }, "deductions": { "items": [], "garnishments": [], "totalDeductions": 0 }, "employeeTaxes": { "items": [], "totalEmployeeTaxes": 0 }, "employerTaxes": { "items": [], "totalEmployerTaxes": 0 }, "netPayDistribution": [], "timeOffs": [], "netPay": 0 }, { "employeeName": "Emma Marie Garcia", "employeeId": "F64EFF29-6516-4C1E-B14D-82F00B7EADF9", "jobTitle": "Software Engineer", "wageBasis": "Per Week", "earnings": { "items": [ { "description": "Salary", "hours": 8, "total": 3560 }, { "description": "Standard Overtime", "hours": null, "rate": null, "total": 133.5 } ], "totalEarnings": 3693.5 }, "deductions": { "items": [], "garnishments": [], "totalDeductions": 0 }, "employeeTaxes": { "items": [ { "taxName": "Medicare", "amount": 53.56 }, { "taxName": "Social Security Tax", "amount": 229 } ], "totalEmployeeTaxes": 282.56 }, "employerTaxes": { "items": [ { "taxName": "FUTA", "amount": 20.64 }, { "taxName": "Medicare Tax", "amount": 53.56 }, { "taxName": "Social Security", "amount": 229 }, { "taxName": "AZ - State Unemployment Insurance", "amount": 73.87 } ], "totalEmployerTaxes": 377.07 }, "netPayDistribution": [ { "description": "Acct 1111", "amount": 3410.94 } ], "timeOffs": [], "netPay": 3410.94 } ], "companyTotal": { "totalEarnings": 3693.5, "totalDeductions": 0, "employeeTaxes": [ { "taxName": "Medicare", "amount": 53.56 }, { "taxName": "Social Security Tax", "amount": 229 } ], "totalEmployeeTaxes": 282.56, "employerTaxes": [ { "taxName": "FUTA", "amount": 20.64 }, { "taxName": "Medicare Tax", "amount": 53.56 }, { "taxName": "Social Security", "amount": 229 }, { "taxName": "AZ - State Unemployment Insurance", "amount": 73.87 } ], "totalEmployerTaxes": 377.07, "netPay": 3410.94 } } } }, "headers": {} } }, "security": [] } }, "/reports/getCashRequirementsReport": { "get": { "summary": "getCashRequirementsReport", "deprecated": false, "description": "The `getCashRequirementsReport` API generates cash requirements including payroll account debits and other payroll liabilities settled outside of the Rollfi system\n\n### What it does:\n\n- Returns the total that will be pulled from the employer's account\n- Returns total cash required for check payments\n- Includes cash required for remaining liabilites handled outside of Rollfi including benefits contribuitons\n\n### Notes:\n- Used to confirm the business has the required funds to run the payroll and cover other liabilites\n- Provides a breakdown of the employee and employer taxes included in the total debit amount\n- Check employees are included in the cash requirement report even if their totals are $0\n- `Garnishments` in the electronicFundsTransferSummary are handled by Rollfi and are part of the debit amount. `otherGarnishments` are settled by the employer", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "getPayrollJournalReport", "examples": [ "getPayrollJournalReport" ] }, "payPeriodId": { "type": "string", "format": "uuid" }, "companyId": { "type": "string", "format": "uuid" } }, "required": [ "method", "companyId", "payPeriodId" ] }, "example": { "method": "getCashRequirementsReport", "payPeriodId": "5465C126-BACD-4593-97CE-24243FFFC998", "companyId": "C3C91397-CDBA-44E0-A296-0BFC9A4DFDF5" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "cashRequirementsReport": { "type": "object", "properties": { "company": { "type": "string" }, "payBeginDate": { "type": "string" }, "payEndDate": { "type": "string" }, "payDate": { "type": "string" }, "payPeriodStatus": { "type": "string" }, "payPeriodDisplay": { "type": "string" }, "cashRequirementSummary": { "type": "object", "properties": { "totalElectronicFundsTransfer": { "type": "number" }, "cashRequiredForCheckPayments": { "type": "integer" }, "remainingDeductionsLiabilitiesAndWithholdings": { "type": "integer" }, "totalCashRequired": { "type": "number" } }, "required": [ "totalElectronicFundsTransfer", "cashRequiredForCheckPayments", "remainingDeductionsLiabilitiesAndWithholdings", "totalCashRequired" ] }, "electronicFundsTransferSummary": { "type": "object", "properties": { "totalDirectDeposits": { "type": "number" }, "totalEmployeeTaxes": { "type": "number" }, "totalEmployerTaxes": { "type": "number" }, "garnishments": { "type": "integer" }, "totalEft": { "type": "number" } }, "required": [ "totalDirectDeposits", "totalEmployeeTaxes", "totalEmployerTaxes", "garnishments", "totalEft" ] }, "checkPaymentSummary": { "type": "object", "properties": { "employees": { "type": "array", "items": { "type": "object", "properties": { "employee": { "type": "string" }, "amount": { "type": "integer" } } } }, "totalCheckPayments": { "type": "integer" } }, "required": [ "employees", "totalCheckPayments" ] }, "remainingDeductionsAndLiabilities": { "type": "object", "properties": { "totalBenefitsDeductionsAndContributions": { "type": "integer" }, "otherGarnishments": { "type": "integer" }, "totalRemainingDeductionsAndLiabilities": { "type": "integer" } }, "required": [ "totalBenefitsDeductionsAndContributions", "otherGarnishments", "totalRemainingDeductionsAndLiabilities" ] } }, "required": [ "company", "payBeginDate", "payEndDate", "payDate", "payPeriodStatus", "payPeriodDisplay", "cashRequirementSummary", "electronicFundsTransferSummary", "checkPaymentSummary", "remainingDeductionsAndLiabilities" ] } }, "required": [ "cashRequirementsReport" ] }, "example": { "cashRequirementsReport": { "company": "test150UsersV2", "payBeginDate": "2026-05-01", "payEndDate": "2026-05-31", "payDate": "2026-05-29", "payPeriodStatus": "new", "payPeriodDisplay": "Pay Period: 05/01/2026 - 05/31/2026 - DRAFT: NOT SUBMITTED", "cashRequirementSummary": { "totalElectronicFundsTransfer": 469781.41, "cashRequiredForCheckPayments": 0, "remainingDeductionsLiabilitiesAndWithholdings": 620, "totalCashRequired": 470401.41 }, "electronicFundsTransferSummary": { "totalDirectDeposits": 331132.86, "totalEmployeeTaxes": 104517.99, "totalEmployerTaxes": 34130.56, "garnishments": 0, "totalEft": 469781.41 }, "checkPaymentSummary": { "employees": [ { "employee": "Danielle Edwards", "amount": 0 } ], "totalCheckPayments": 0 }, "remainingDeductionsAndLiabilities": { "totalBenefitsDeductionsAndContributions": 620, "otherGarnishments": 0, "totalRemainingDeductionsAndLiabilities": 620 } } } } }, "headers": {} } }, "security": [] } }, "/reports/getPayrollJournalReport": { "get": { "summary": "getPayrollJournalReport", "deprecated": false, "description": "The `getPayrollJournalReport` API generates accounting journal entries for payroll transactions.\n\n### What it does:\n\n- Returns journal entry data for payroll transactions\n- Encompasses a single pay period\n- Provides highly detailed accounting information needed for accurate tax reporting\n- Reports year-to-date measures for employees\n\n### Notes:\n\n- Either startDate **and** endDate or payPeriodId are required\n- Used for tax system integration and financial reporting\n- Retrieves data for all employees within a company so should be used as an administrative function", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "title": "getPayrollJournalReport", "examples": [ "getPayrollJournalReport" ] }, "payPeriodId": { "type": "string", "format": "uuid" }, "companyId": { "type": "string", "format": "uuid" }, "startDate": { "type": "string" }, "endDate": { "type": "string" } }, "required": [ "method", "companyId" ] }, "example": { "method": "getPayrollJournalReports", "payPeriodId": "5465C126-BACD-4593-97CE-24243FFFC998", "companyId": "C3C91397-CDBA-44E0-A296-0BFC9A4DFDF5" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "payrollJournalReport": { "type": "object", "properties": { "companyName": { "type": "string" }, "companyPhone": { "type": "string" }, "companyAddress": { "type": "object", "properties": { "address": { "type": "string" }, "address1": { "type": "string" }, "address2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zipcode": { "type": "string" } }, "required": [ "address", "address1", "address2", "city", "state", "zipcode" ] }, "payPeriod": { "type": "string" }, "payBeginDate": { "type": "string" }, "payEndDate": { "type": "string" }, "payDate": { "type": "string" }, "payPeriodStatus": { "type": "string" }, "workerType": { "type": "string" } }, "required": [ "companyName", "companyPhone", "companyAddress", "payPeriod", "payBeginDate", "payEndDate", "payDate", "payPeriodStatus", "workerType" ] }, "employees": { "type": "array", "items": { "type": "object", "properties": { "employeeName": { "type": "string" }, "employeeId": { "type": "string" }, "jobTitle": { "type": "string" }, "wageBasis": { "type": "string" }, "earnings": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "hours": { "type": [ "integer", "null" ] }, "total": { "type": [ "number", "integer" ] }, "rate": { "type": [ "number", "integer", "null" ] } }, "required": [ "description", "hours", "total", "rate" ] } }, "totalEarnings": { "type": [ "number", "integer" ] } }, "required": [ "items", "totalEarnings" ] }, "deductions": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "type": { "type": "string" }, "amount": { "type": "integer" }, "amountYTD": { "type": "integer" } }, "required": [ "description", "type", "amount", "amountYTD" ] } }, "garnishments": { "type": "array", "items": { "type": "string" } }, "totalDeductions": { "type": "integer" } }, "required": [ "items", "garnishments", "totalDeductions" ] }, "employeeTaxes": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "taxName": { "type": "string" }, "amount": { "type": [ "number", "integer" ] } }, "required": [ "taxName", "amount" ] } }, "totalEmployeeTaxes": { "type": [ "number", "integer" ] } }, "required": [ "items", "totalEmployeeTaxes" ] }, "employerTaxes": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "taxName": { "type": "string" }, "amount": { "type": [ "number", "integer" ] } }, "required": [ "taxName", "amount" ] } }, "totalEmployerTaxes": { "type": [ "number", "integer" ] } }, "required": [ "items", "totalEmployerTaxes" ] }, "netPayDistribution": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "amount": { "type": [ "number", "integer" ] } }, "required": [ "description", "amount" ] } }, "timeOffs": { "type": "array", "items": { "type": "object", "properties": { "leaveType": { "type": "string" }, "amount": { "type": "number" }, "hours": { "type": "integer" } }, "required": [ "leaveType", "hours" ] } }, "netPay": { "type": [ "number", "integer" ] } }, "required": [ "employeeName", "employeeId", "jobTitle", "wageBasis", "earnings", "deductions", "employeeTaxes", "employerTaxes", "netPayDistribution", "timeOffs", "netPay" ] } }, "companyTotal": { "type": "object", "properties": { "totalEarnings": { "type": "number" }, "totalDeductions": { "type": "integer" }, "employeeTaxes": { "type": "array", "items": { "type": "object", "properties": { "taxName": { "type": "string" }, "amount": { "type": [ "number", "integer" ] } }, "required": [ "taxName", "amount" ] } }, "totalEmployeeTaxes": { "type": "number" }, "employerTaxes": { "type": "array", "items": { "type": "object", "properties": { "taxName": { "type": "string" }, "amount": { "type": [ "number", "integer" ] } }, "required": [ "taxName", "amount" ] } }, "totalEmployerTaxes": { "type": "number" }, "netPay": { "type": "number" } }, "required": [ "totalEarnings", "totalDeductions", "employeeTaxes", "totalEmployeeTaxes", "employerTaxes", "totalEmployerTaxes", "netPay" ] } }, "required": [ "payrollJournalReport", "employees", "companyTotal" ] }, "example": { "startDate": "2024-01-01", "endDate": "2026-01-01", "payPeriods": [ { "payrollJournalReport": { "companyName": "Fax limited", "companyPhone": "8548566632", "companyAddress": { "address": "8745 Colard Ln , Lyons, CO, 80540", "address1": "8745 Colard Ln", "address2": "", "city": "Lyons", "state": "CO", "zipcode": "80540" }, "payPeriod": "10/10/2025 - 10/10/2025", "payBeginDate": "2025-10-10", "payEndDate": "2025-10-10", "payDate": "2025-09-25", "payPeriodStatus": "DRAFT: NOT SUBMITTED", "workerType": "W2" }, "employees": [ { "employeeName": "Eric Jale", "employeeId": "D74EFBA4-24E1-4174-B348-6515E6275FB3", "jobTitle": "HR", "wageBasis": "Per Month", "earnings": { "items": [ { "description": "Salary", "hours": 8, "total": 4.35 }, { "description": "Bonus", "hours": null, "rate": null, "total": 4000 }, { "description": "Driving", "hours": null, "rate": null, "total": 10 }, { "description": "Retro", "hours": null, "rate": null, "total": 10 } ], "totalEarnings": 4024.35 }, "deductions": { "items": [ { "description": "Simple IRA", "type": "Employee Deduction", "amount": 3, "amountYTD": 0 } ], "garnishments": [], "totalDeductions": 3 }, "employeeTaxes": { "items": [ { "taxName": "Medicare", "amount": 58.21 }, { "taxName": "Social Security Tax", "amount": 248.89 }, { "taxName": "Federal Income Tax", "amount": 880 }, { "taxName": "CO - State Income Tax", "amount": 176 }, { "taxName": "CO - Family Leave Insurance", "amount": 18.06 } ], "totalEmployeeTaxes": 1381.16 }, "employerTaxes": { "items": [ { "taxName": "Unemployment Tax", "amount": 24.09 }, { "taxName": "Medicare Tax", "amount": 58.21 }, { "taxName": "Social Security", "amount": 248.89 }, { "taxName": "CO - State Unemployment Insurance", "amount": 50.18 }, { "taxName": "CO - State Umeployment Tax Surcharge", "amount": 54.19 }, { "taxName": "CO - State Umeployment Tax Surcharge", "amount": 6.82 } ], "totalEmployerTaxes": 442.38 }, "netPayDistribution": [], "timeOffs": [ { "leaveType": "Unpaid", "hours": 2 } ], "netPay": 2640.19 } ], "companyTotal": { "totalEarnings": 4024.35, "totalDeductions": 3, "employeeTaxes": [ { "taxName": "Medicare", "amount": 58.21 }, { "taxName": "Social Security Tax", "amount": 248.89 }, { "taxName": "Federal Income Tax", "amount": 880 }, { "taxName": "CO - State Income Tax", "amount": 176 }, { "taxName": "CO - Family Leave Insurance", "amount": 18.06 } ], "totalEmployeeTaxes": 1381.16, "employerTaxes": [ { "taxName": "Unemployment Tax", "amount": 24.09 }, { "taxName": "Medicare Tax", "amount": 58.21 }, { "taxName": "Social Security", "amount": 248.89 }, { "taxName": "CO - State Unemployment Insurance", "amount": 50.18 }, { "taxName": "CO - State Umeployment Tax Surcharge", "amount": 61.01 } ], "totalEmployerTaxes": 442.38, "netPay": 2640.19 } }, { "payrollJournalReport": { "companyName": "Fax limited", "companyPhone": "8548566632", "companyAddress": { "address": "8745 Colard Ln , Lyons, CO, 80540", "address1": "8745 Colard Ln", "address2": "", "city": "Lyons", "state": "CO", "zipcode": "80540" }, "payPeriod": "10/02/2025 - 10/10/2025", "payBeginDate": "2025-10-02", "payEndDate": "2025-10-10", "payDate": "2025-10-10", "payPeriodStatus": "DRAFT: NOT SUBMITTED", "workerType": "W2" }, "employees": [ { "employeeName": "Abdul Pasha", "employeeId": "FA937C14-5DFE-40B3-B2C2-19BA2E988DCF", "jobTitle": "sde", "wageBasis": "Per Month", "earnings": { "items": [ { "description": "Salary", "hours": 56, "total": 3750.17 } ], "totalEarnings": 3750.17 }, "deductions": { "items": [], "garnishments": [], "totalDeductions": 0 }, "employeeTaxes": { "items": [ { "taxName": "Medicare", "amount": 54.38 }, { "taxName": "Social Security Tax", "amount": 232.51 }, { "taxName": "CA - State Disability Insurance", "amount": 45 } ], "totalEmployeeTaxes": 331.89 }, "employerTaxes": { "items": [ { "taxName": "Unemployment Tax", "amount": 22.5 }, { "taxName": "Medicare Tax", "amount": 54.38 }, { "taxName": "Social Security", "amount": 232.51 }, { "taxName": "CA - State Unemployment Insurance", "amount": 46.88 }, { "taxName": "CA - State Umeployment Tax Surcharge", "amount": 3.75 } ], "totalEmployerTaxes": 360.02 }, "netPayDistribution": [], "timeOffs": [], "netPay": 3418.28 }, { "employeeName": "Binny Shine", "employeeId": "FE2C85F1-A8DB-4AD7-A342-D375BD54F387", "jobTitle": "hr", "wageBasis": "Per Month", "earnings": { "items": [ { "description": "Salary", "hours": 56, "total": 2708.7 } ], "totalEarnings": 2708.7 }, "deductions": { "items": [], "garnishments": [], "totalDeductions": 0 }, "employeeTaxes": { "items": [ { "taxName": "Medicare", "amount": 39.28 }, { "taxName": "Social Security Tax", "amount": 167.94 }, { "taxName": "CO - Family Leave Insurance", "amount": 12.19 } ], "totalEmployeeTaxes": 219.41 }, "employerTaxes": { "items": [ { "taxName": "Unemployment Tax", "amount": 16.25 }, { "taxName": "Medicare Tax", "amount": 39.28 }, { "taxName": "Social Security", "amount": 167.94 }, { "taxName": "CO - State Unemployment Insurance", "amount": 33.86 }, { "taxName": "CO - State Umeployment Tax Surcharge", "amount": 36.57 }, { "taxName": "CO - State Umeployment Tax Surcharge", "amount": 4.6 } ], "totalEmployerTaxes": 298.5 }, "netPayDistribution": [], "timeOffs": [], "netPay": 2489.29 } ], "companyTotal": { "totalEarnings": 6458.87, "totalDeductions": 0, "employeeTaxes": [ { "taxName": "Medicare", "amount": 93.66 }, { "taxName": "Social Security Tax", "amount": 400.45 }, { "taxName": "CA - State Disability Insurance", "amount": 45 }, { "taxName": "CO - Family Leave Insurance", "amount": 12.19 } ], "totalEmployeeTaxes": 551.3, "employerTaxes": [ { "taxName": "Unemployment Tax", "amount": 38.75 }, { "taxName": "Medicare Tax", "amount": 93.66 }, { "taxName": "Social Security", "amount": 400.45 }, { "taxName": "CA - State Unemployment Insurance", "amount": 46.88 }, { "taxName": "CA - State Umeployment Tax Surcharge", "amount": 3.75 }, { "taxName": "CO - State Unemployment Insurance", "amount": 33.86 }, { "taxName": "CO - State Umeployment Tax Surcharge", "amount": 41.17 } ], "totalEmployerTaxes": 658.52, "netPay": 5907.57 } } ] } } }, "headers": {} } }, "security": [] } }, "/sso/getSsoRedirectLink": { "post": { "summary": "getSsoRedirectLink", "deprecated": false, "description": "The `getSsoRedirectLink` API exchanges an employee or businessUser email and their company for a link that will bypass traditional login.\n\n### What it does:\n- Allows a user to sign in on your system and gain access to the Rollfi UI for core payroll funcitonality\n- Bypasses username, password and 2FA which are usually required for logins\n\n### Security:\n- Generates a link to the Rollfi UI with a jwt containing the employee/businessUser's information\n- Signs the JWT with a securely held private key and sha256 to prevent tampering\n- When directed to the link with the included jwt, the credentials and signature are verified and login is bypassed\n\n### What's in the JWT?\n\n- `companyId`\n- `email`\n- `iat`\n- `exp`\n- `roles` when roles are supplied\n- `nbf`\n\n### Note:\n- At this time roles are only necessary for just in time provisioning - **w2Employee** and **contractor1099**\n- If you believe you may require JIT provisioning please contact support\n", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "email": { "type": "string" }, "companyId": { "type": "string" }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "w2Employee", "contractor1099", "businessUser", "beneficialOwner", "payrollAdmin", "bookKeeper" ] } } }, "required": [ "method", "email", "companyId" ] }, "example": { "method": "getSsoRedirectLink", "email": "test_no_info4@emailsac.com", "companyId": "82CCB239-764C-49BA-A3A8-00B9C37A59D4", "roles": [ "w2Employee" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "examples": { "1": { "summary": "Success", "value": { "success": true, "loginUrl": "https://app.sandbox.rollfi.xyz/?jwt=eyJhbGciOiJSUzI1NiJ9.eyJjb21wYW55SWQiOiI4MkNDQjIzOS03NjRDLTQ5QkEtQTNBOC0wMEI5QzM3QTU5RDQiLCJlbWFpbCI6InRlc3Rfbm9faW5mbzRAZW1haWxzYWMuY29tIiwiaWF0IjoxNzY5Nzk3NDQ3LCJleHAiOjE3Njk3OTgxMDcsIm5iZiI6MTc2OTc5NzQ0Nywicm9sZXMiOlsidzJFbXBsb3llZSJdfQ.i3YrGu63PZr6WM27dN8QW_zFG3_tTR9XMEZeq0TakvxhGWJNHx-P9eIs9Hv57oV2gWxGpL1wKBTpHZEmWxYFHq1sshNu4sD1x4pHstPSPBZls1BH1_5p5y3Smk7w0tPVe97piZV8SFH5XWVN5zU3sOazRqkLaxtiDlLy5GV1WAPNVhqia6kPOP3PNTBLg7cq6hJqW0hGqQBo_iNNKW6MHgmMNYTlEr4Ba3WdPcX-vfnBHqGDMEkvPYt8czyvdctOftgmJNUBJ8tTEJUTe0h86iRGj12PtB_8zW8wUG37RaZFtjUhCGz9dWeuxX5Uan2A0teOUpo-VObJkmsvzRxihA" } }, "2": { "summary": "Does Not Exist", "value": { "error": { "code": 403, "message": "Email does not exist for the company but JIT was not requested. Please check if the user already has an account before proceeding" } } }, "3": { "summary": "Invalid Company", "value": { "error": { "code": 400, "message": "Invalid CompanyId" } } }, "4": { "summary": "Invalid Email", "value": { "error": { "code": 400, "message": "email is required and must be valid" } } } } } }, "headers": {} } }, "security": [] } }, "/companyOnboarding/addFlexibleBusinessUser": { "post": { "summary": "addFlexibleBusinessUser", "deprecated": false, "description": "The `addFlexibleBusinessUser` API is a more flexible version of `addBusinessUser`\n\n### What it does:\n- Drops validation for beneficialOwners\n- Requires only companyId, firstName, lastName, phoneNumber and email for all businessUser roles\n\n### Note:\n- If a beneficialOwner is added using this method, they must be directed to complete their record in the `Settings` window of the UI.\n- This is only applicable when the beneficialOwner is not the businessUser added during company onboarding, since this validation is enforced in the onboarding screens.\n- If a the beneficialOwner does not complete their profile, it may prevent KYB completion and hold up a company's progress.\n", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "businessUser": { "type": "object", "properties": { "companyId": { "type": "string" }, "firstName": { "type": "string" }, "middleName": { "type": "string" }, "lastName": { "type": "string" }, "phoneNumber": { "type": "string" }, "email": { "type": "string" }, "address1": { "type": "string" }, "address2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zipcode": { "type": "string" }, "country": { "type": "string" }, "ssn": { "type": "string" }, "dateOfBirth": { "type": "string" }, "payrollAdmin": { "type": "boolean" }, "bookkeeper": { "type": "boolean" }, "beneficialOwner": { "type": "boolean" }, "ownershipPercentage": { "type": "integer" } }, "required": [ "companyId", "firstName", "lastName", "phoneNumber", "email" ] } }, "required": [ "method", "businessUser" ] }, "example": { "method": "addFlexibleBusinessUser", "businessUser": { "companyId": "D2FEFBD6-C15E-4EC7-8258-4158B0C8078D", "firstName": "Jim", "middleName": "", "lastName": "Smith", "phoneNumber": "2511630147", "email": "FlexibleJimSmith@mailsac.com", "address1": "102 Fallsgrove Blvd", "address2": "", "city": "Rockville", "state": "MD", "zipcode": "20850", "country": "US", "ssn": "273155826", "dateOfBirth": "2006-09-09", "payrollAdmin": true, "bookkeeper": true, "beneficialOwner": true, "ownershipPercentage": 25 } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "businessUser": { "type": "object", "properties": { "businessUserId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "businessUserId", "status", "message" ] } }, "required": [ "businessUser" ] }, "examples": { "1": { "summary": "Success", "value": { "businessUser": { "businessUserId": "211E2121-151B-4516-8394-8FFC2AFC3BA4", "status": "KYC Pending", "message": "Jim Smith has been successfully added as BusinessUser." } } }, "2": { "summary": "Email Already Exists", "value": { "error": { "code": 400, "message": "Email already exists for an account within this company." } } } } } }, "headers": {} } }, "security": [] } }, "/reports/generateZenithBillingReport": { "get": { "summary": "generateZenithBillingReport", "deprecated": false, "description": "The `generateZenithBillingReport` API returns high level billing information for all companies within Zenith's workspace\n\n### What it does:\n- Returns company level payroll information to determine billing amounts\n- Retrieves the number of employees eligible for payroll, number of unique employees paid, number of tax filings and packages for each company\n- Can also show the number of paychecks per employee in each company\n\n### Notes:\n- `TotalActiveUsers` conveys the number of employees that are active, or were active during the payPeriod. `TotalPaidUsers` shows the number of unique employees actually paid\n- Even if a company has not run payroll between the given dates, they will still be returned in the billing response\n- Including `detailed: true` will provide the number of paychecks for each employee in the date range. This will include employees that weren't paid with **paychecks: 0**", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "startDate": { "type": "string" }, "endDate": { "type": "string" }, "detailed": { "type": "boolean" } }, "required": [ "method", "startDate", "endDate" ] }, "example": { "method": "generateZenithBillingReport", "startDate": "2025-01-01", "endDate": "2025-03-31", "detailed": true } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ReportDetails": { "type": "object", "properties": { "startDate": { "type": "string" }, "endDate": { "type": "string" }, "detailed": { "type": "boolean" } }, "required": [ "startDate", "endDate", "detailed" ] }, "BillingInfo": { "type": "array", "items": { "type": "object", "properties": { "zenithCompanyId": { "type": "string" }, "companyId": { "type": "string" }, "company": { "type": "string" }, "EINs": { "type": "integer" }, "totalActiveUsers": { "type": "integer" }, "totalPaidUsers": { "type": "integer" }, "quarterlyTaxPackage": { "type": "integer" }, "W2Filings": { "type": "integer" }, "1099Filings": { "type": "integer" }, "users": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "zenithEmployeeId": { "type": "string" }, "paychecks": { "type": "integer" } }, "required": [ "userId", "zenithEmployeeId", "paychecks" ] } } }, "required": [ "zenithCompanyId", "companyId", "company", "EINs", "totalActiveUsers", "totalPaidUsers", "quarterlyTaxPackage", "W2Filings", "1099Filings" ] } } }, "required": [ "ReportDetails", "BillingInfo" ] }, "example": { "ReportDetails": { "startDate": "2025-01-01", "endDate": "2025-03-31", "detailed": true }, "BillingInfo": [ { "zenithCompanyId": "Z100.2000", "companyId": "3D608093-5677-439B-ADB7-5E6E2ABE8DC7", "company": "Test Company", "EINs": 1, "totalActiveUsers": 4, "totalPaidUsers": 3, "quarterlyTaxPackage": 1, "W2Filings": 2, "1099Filings": 1, "users": [ { "userId": "14091732-BFDC-4624-9A3C-02AD465CC9C5", "zenithEmployeeId": "Z100.2000.30001", "paychecks": 6 }, { "userId": "143D52F5-A1E4-4D72-A9A3-02C0F62FBE9C", "zenithEmployeeId": "Z100.2000.30002", "paychecks": 4 }, { "userId": "A6A67D20-BA48-4236-A36D-0688689C2914", "zenithEmployeeId": "Z100.2000.30003", "paychecks": 4 }, { "userId": "812F9FD4-6C01-4FE3-88F8-06BE6FE965E0", "zenithEmployeeId": "Z100.2000.30004", "paychecks": 0 } ] } ] } } }, "headers": {} }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": { "error": { "code": 400, "message": "Invalid payBeginDate" } } } }, "headers": {} } }, "security": [] } }, "/companyOnboarding/createMxcBusiness": { "post": { "summary": "createMxcBusiness", "deprecated": false, "description": "The `createMxcBusiness` API provides a consolidated MXC onboarding flow.\n\n### What it does\n1. Registers the company\n2. Adds KYB information\n3. Creates the initial company location\n4. Updates business user role flags\n5. Initiates KYB\n\n### Notes\n- If `registration.company` is missing, `registration.legalCompanyName` is required and is used as the company name.\n- Duplicate company name and duplicate EIN are returned as `registration` responses (not `error`) with a message.\n- On intermediate failure after registration, rollback is attempted to remove partially created records.", "operationId": "createMxcBusiness", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "method", "registration", "kybInformation", "companyLocation", "businessUser" ], "properties": { "method": { "type": "string", "enum": [ "createMxcBusiness" ] }, "registration": { "type": "object", "required": [ "isTermsAccepted" ], "properties": { "company": { "type": "string" }, "businessWebsite": { "type": "string" }, "doingBusinessAs": { "type": "string" }, "isTermsAccepted": { "type": "boolean" } } }, "kybInformation": { "type": "object", "required": [ "ein", "entityType", "incorporationState", "dateOfIncorporation", "irsAssisgnedFederalFilingForm", "payrollRunThisYear", "formerPaidThisYear" ], "properties": { "ein": { "type": "string", "description": "9-digit EIN." }, "entityType": { "type": "string", "enum": [ "C Corp", "S Corp", "LLC", "Single Member LLC", "LLP", "Partnership", "Sole Proprietor", "Non-Profit" ] }, "incorporationState": { "type": "string" }, "dateOfIncorporation": { "type": "string", "format": "date" }, "irsAssisgnedFederalFilingForm": { "type": "string", "enum": [ "941", "944" ] }, "payrollRunThisYear": { "type": "string" }, "formerPaidThisYear": { "type": "string" } } }, "companyLocation": { "type": "object", "required": [ "companyLocation", "address1", "city", "state", "zipcode", "isFilingAddress" ], "properties": { "companyLocation": { "type": "string" }, "address1": { "type": "string" }, "address2": { "type": [ "string", "null" ] }, "city": { "type": "string" }, "state": { "type": "string" }, "zipcode": { "type": "string" }, "phoneNumber": { "type": "string" }, "isWorkLocation": { "type": "boolean" }, "isMailingAddress": { "type": "boolean" }, "isFilingAddress": { "type": "boolean" }, "country": { "type": "string", "description": "Defaults to US when omitted." } } }, "businessUser": { "type": "object", "required": [ "firstName", "lastName", "email", "phoneNumber" ], "properties": { "firstName": { "type": "string" }, "middleName": { "type": [ "string", "null" ] }, "lastName": { "type": "string" }, "phoneNumber": { "type": "string" }, "email": { "type": "string", "format": "email" }, "address1": { "type": [ "string", "null" ] }, "address2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zipcode": { "type": [ "string", "null" ] }, "ssn": { "type": [ "string", "null" ] }, "dateOfBirth": { "type": [ "string", "null" ], "format": "date" }, "payrollAdmin": { "type": [ "boolean", "null" ] }, "bookkeeper": { "type": [ "boolean", "null" ] }, "bookKeeper": { "type": [ "boolean", "null" ] }, "beneficialOwner": { "type": [ "boolean", "null" ] }, "ownershipPercentage": { "type": [ "integer", "null" ] } } } } }, "example": { "method": "createMxcBusiness", "registration": { "company": "Best LLC", "businessWebsite": "www.schumm.com", "doingBusinessAs": "Best", "isTermsAccepted": true }, "kybInformation": { "ein": "109709569", "entityType": "LLP", "incorporationState": "Alabama", "dateOfIncorporation": "2015-02-25", "irsAssisgnedFederalFilingForm": "941", "payrollRunThisYear": "Yes", "formerPaidThisYear": "No" }, "companyLocation": { "companyLocation": "Main", "address1": "8745 Colard Ln", "address2": "", "city": "Lyons", "state": "CO", "zipcode": "80540", "phoneNumber": "9889890989", "isWorkLocation": true, "isMailingAddress": true, "isFilingAddress": true }, "businessUser": { "firstName": "Manoj", "middleName": "", "lastName": "Deshmukh", "phoneNumber": "9974574177", "email": "manoje901@mailsac.com", "address1": "8745 Colard Ln", "address2": "", "city": "Lyons", "state": "CO", "zipcode": "80540", "ssn": "458756985", "dateOfBirth": "2000-09-09", "payrollAdmin": true, "bookkeeper": true, "beneficialOwner": true, "ownershipPercentage": 25 } } } }, "required": true }, "responses": { "200": { "description": "Success, Duplicate or Exception", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "registration" ], "properties": { "registration": { "type": "object", "required": [ "companyId", "kybInformationId", "businessUserId", "companyLocationId", "status", "message" ], "properties": { "companyId": { "type": "string", "format": "uuid" }, "kybInformationId": { "type": "string", "format": "uuid" }, "businessUserId": { "type": "string", "format": "uuid" }, "companyLocationId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "Registered" ] }, "message": { "type": "string" } } } } }, { "type": "object", "required": [ "registration" ], "properties": { "registration": { "type": "object", "required": [ "companyId", "message" ], "properties": { "companyId": { "type": "string", "format": "uuid" }, "message": { "type": "string", "enum": [ "Company already exists", "EIN already exists. Please contact support if you believe there is an error." ] } } } } }, { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } } } } ] }, "examples": { "success": { "summary": "success", "value": { "registration": { "companyId": "98016CB2-FAA4-47E5-8173-DD6F29C7C397", "kybInformationId": "32E9AE44-529A-4B4E-9C40-56DFCE99E712", "businessUserId": "4B47C1DA-F279-40E8-ABF6-ADD82E7C2582", "companyLocationId": "FB3B168C-62C2-43D0-A1EF-B3C6C5C6FAE3", "status": "Registered", "message": "Company 'Wise Wonders Co' is registered successfully and KYB verification is in progress." } } }, "duplicateCompany": { "summary": "duplicateCompany", "value": { "registration": { "companyId": "98016CB2-FAA4-47E5-8173-DD6F29C7C397", "message": "Company already exists" } } }, "duplicateEin": { "summary": "duplicateEin", "value": { "registration": { "companyId": "98016CB2-FAA4-47E5-8173-DD6F29C7C397", "message": "EIN already exists. Please contact support if you believe there is an error." } } }, "Exception": { "summary": "Exception", "value": { "error": { "code": 400, "message": "firstName is mandatory." } } } } } }, "headers": {} } }, "security": [] } }, "/webhooks/getWebhookPublicKey": { "get": { "summary": "getWebhookPublicKey", "deprecated": false, "description": "The `getWebhookPublicKey` API retrieves the Active public key to verify incoming webhook signatures\n\n### What it does:\n- Returns the `Active` public key to verify the signature in a webhook header\n- Returns a `Retiring` key after rotation so webhooks in transit can be verified\n\n### Note:\n- Keys should be stored to prevent unecessary calls to this endpoint\n- Keys are identified by their unique keyID (`kid`)\n- This endpoint should only be used when a webhook is recieved with a `kid` you haven't previously seen", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" } }, "required": [ "method" ] }, "example": { "method": "getWebhookPublicKey" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookPublicKey": { "type": "array", "items": { "type": "object", "properties": { "publicKey": { "type": "string" }, "alg": { "type": "string" }, "kid": { "type": "string" }, "status": { "type": "string" }, "verifyUntil": { "type": "string" } }, "required": [ "publicKey", "alg", "kid", "status" ] } } }, "required": [ "webhookPublicKey" ] }, "example": { "webhookPublicKey": [ { "publicKey": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAx7X5aL03/0SX2yRkaQkY\no8n+wEGY0og5n9INWbDh/8Twv7dpWiYYhxTHOewYq4RNNu85vOeDP5I10k7NO0oU\nZHMpXtn03KL771bPo8TIhEmGkjSkCicf3czFpJ//MVS2wZbvy0Lq0lor1Ubx35Q5\n2OViygrfk9dC6yRkN64ggtKN+jTzq2vi4k7nNg9B6fmiC6N2FdY+g3xefTmtP47+\nrg6e/NjQd+xQg/KhLnCYdfTowTlGo4Uo5n6jOdW8Q21qWfkBg1+E2tSVjOicuhhF\n9YPHv9uln8T79hIMd3sw/L/Hj0VEhMzvVXjGt6XE4rDiiw73F/5HNpVWoYnAfno2\n8wIDAQAB\n-----END PUBLIC KEY-----", "alg": "RS256", "kid": "EF4F6093-3DFB-4BFB-AEF4-F45BAB72FA26", "status": "Active" }, { "publicKey": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAglTOVKUOsu1I9V4zOxN1\ncPQSiFtcqI/J9pqNoUWYTbcSrbIIxUBswyEo8ALezg5uP9+a3OoeBatCLfvrocav\njf0R67qFnkmBfSafgqaY4f23oEFSPcBnWq/U5ULIA15nvq/HO2bXuai/Xw8Cj05/\n2FXPTIPY6TJK1Lzzbec5H9XvTTb49cYQ8W2ZMrJsqIxa87jM6bxFYLobBpcWYgn1\nEAa7lU7jMHWD7C54M+lb/UJII3ScnhTh1s4o/StOWJ19bdx9IZq3bNzP1JFQRUs1\neB1OaFHyX+GqYxxeoSJmRqwlZlq7EgCVHI+l7XaHHUxMN6NSo+UC+bCH7UkB3OBt\nrQIDAQAB\n-----END PUBLIC KEY-----", "alg": "RS256", "kid": "5AAFD8C3-5323-4513-B202-1A2EB066EB26", "status": "Retiring", "verifyUntil": "2026-06-19T02:42:32.467Z" } ] } } }, "headers": {} } }, "security": [] } } }, "webhooks": { "payScheduleIsActive": { "post": { "summary": "Pay schedule status event", "deprecated": false, "description": "Emitted when a pay schedule is created or its activation state changes.\n\n### Events\n\n- `payschedule.paysheduleisactive.insert` — emitted when a pay schedule is created. The initial `status` is `active`.\n- `payschedule.paysheduleisactive.update` — emitted when the activation state changes. The `status` can be `active` or `inactive`.\n", "operationId": "payScheduleIsActive", "tags": [ "Pay Schedule Webhooks" ], "parameters": [ { "name": "X-Rollfi-Timestamp", "in": "header", "description": "Unix timestamp used when validating the webhook signature.", "required": false, "example": "", "schema": { "type": "string", "pattern": "^[0-9]+$", "examples": [ "1783551002" ] } }, { "name": "X-Rollfi-Signature", "in": "header", "description": "RS256 signature header in the format `kid=,alg=RS256,v1=`.", "required": false, "example": "", "schema": { "type": "string", "examples": [ "kid=rollfi-key-id,alg=RS256,v1=base64url-signature" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "trigger", "payload" ], "properties": { "trigger": { "type": "object", "required": [ "eventId", "eventType", "eventTimeStamp" ], "properties": { "eventId": { "type": "string", "format": "uuid", "description": "Stable event identifier that remains the same across retries." }, "eventType": { "type": "string", "enum": [ "payschedule.paysheduleisactive.insert", "payschedule.paysheduleisactive.update" ], "description": "Identifies whether the entity was created or subsequently updated." }, "eventTimeStamp": { "type": "string", "description": "UTC event timestamp in Rollfi's `MM/DD/YYYY HH:mm:ss` format.", "pattern": "^(0[1-9]|1[0-2])/(0[1-9]|[12][0-9]|3[01])/[0-9]{4} ([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$" } } }, "payload": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "paySchedule" ], "properties": { "paySchedule": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "payScheduleId", "payBeginDate", "payDate", "deadlineToRunPayroll", "standardWorkingHours", "workerType", "compensationFrequency", "paymentMode", "status" ], "properties": { "payScheduleId": { "type": "string", "format": "uuid", "description": "Unique identifier for the pay schedule." }, "payBeginDate": { "type": "string", "format": "date", "description": "Beginning date of the generated pay period." }, "payDate": { "type": "string", "format": "date", "description": "Date on which workers are scheduled to be paid." }, "deadlineToRunPayroll": { "type": "string", "format": "date", "description": "Deadline by which payroll must be submitted." }, "standardWorkingHours": { "type": "number", "format": "double", "description": "Standard working hours configured for the schedule.", "examples": [ 8 ] }, "workerType": { "type": "object", "required": [ "workerType" ], "properties": { "workerType": { "type": "string", "description": "Worker classification associated with the pay schedule.", "examples": [ "1099-NEC" ] } } }, "compensationFrequency": { "type": "object", "required": [ "compensationFrequency" ], "properties": { "compensationFrequency": { "type": "string", "description": "Frequency at which workers on the schedule are paid.", "examples": [ "BiWeekly" ] } } }, "paymentMode": { "type": "object", "required": [ "paymentMode" ], "properties": { "paymentMode": { "type": "string", "description": "Payment initiation mode configured for the schedule.", "examples": [ "Self-Initiated" ] } } }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Whether the pay schedule is currently active." } } } } } } } } }, "examples": { "activePayScheduleCreated": { "value": { "trigger": { "eventId": "2f197136-4aa0-4c50-9aaf-4f66d943bb80", "eventType": "payschedule.paysheduleisactive.insert", "eventTimeStamp": "07/08/2026 21:50:02" }, "payload": [ { "paySchedule": [ { "payScheduleId": "E6BCE1EB-0300-4E48-916A-435D35CED082", "payBeginDate": "2026-07-01", "payDate": "2026-08-03", "deadlineToRunPayroll": "2026-07-30", "standardWorkingHours": 8, "workerType": { "workerType": "1099-NEC" }, "compensationFrequency": { "compensationFrequency": "BiWeekly" }, "paymentMode": { "paymentMode": "Self-Initiated" }, "status": "active" } ] } ] }, "summary": "An active pay schedule is created" }, "payScheduleDeactivated": { "value": { "trigger": { "eventId": "99178195-b953-4ad1-816d-389c0bb9db0f", "eventType": "payschedule.paysheduleisactive.update", "eventTimeStamp": "07/09/2026 15:20:44" }, "payload": [ { "paySchedule": [ { "payScheduleId": "E6BCE1EB-0300-4E48-916A-435D35CED082", "payBeginDate": "2026-07-01", "payDate": "2026-08-03", "deadlineToRunPayroll": "2026-07-30", "standardWorkingHours": 8, "workerType": { "workerType": "1099-NEC" }, "compensationFrequency": { "compensationFrequency": "BiWeekly" }, "paymentMode": { "paymentMode": "Self-Initiated" }, "status": "inactive" } ] } ] }, "summary": "A pay schedule is deactivated" } } } }, "required": true }, "responses": { "200": { "description": "Pay schedule event accepted successfully.", "headers": {} } }, "security": [] } }, "payPeriodStatus": { "post": { "summary": "Pay period status event", "deprecated": false, "description": "Emitted when a pay period is created or its status changes.\n\n### Events\n\n- `payperiod.payperiodstatus.insert` — emitted when a pay period is created. The initial `PayPeriodStatus` is `new`.\n- `payperiod.payperiodstatus.update` — emitted when an existing pay period changes to `submitted`, `cancelled`, `inProcess`, `processed`, `failed`, `returned`, or `skipped`.\n\nWhen payroll initiation is cancelled, the status moves from `submitted` to `cancelled`; it does not return to `new`.\n", "operationId": "payPeriodStatus", "tags": [ "Pay Period Webhooks" ], "parameters": [ { "name": "X-Rollfi-Timestamp", "in": "header", "description": "Unix timestamp, in seconds, used when verifying the webhook signature.", "required": false, "example": "", "schema": { "type": "string", "pattern": "^\\d+$", "examples": [ "1767725956" ] } }, { "name": "X-Rollfi-Signature", "in": "header", "description": "Rollfi webhook signature containing the key ID, algorithm, and signature value.", "required": false, "example": "", "schema": { "type": "string", "examples": [ "kid=rollfi-webhook-key-01,alg=RS256,v1=eyJhbGciOiJSUzI1NiJ9" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "trigger", "payload" ], "properties": { "trigger": { "type": "object", "required": [ "eventId", "eventType", "eventTimeStamp" ], "properties": { "eventId": { "type": "string", "format": "uuid", "description": "Stable event identifier that remains the same across retries." }, "eventType": { "type": "string", "enum": [ "payperiod.payperiodstatus.insert", "payperiod.payperiodstatus.update" ], "description": "Identifies whether the entity was created or subsequently updated." }, "eventTimeStamp": { "type": "string", "description": "UTC event timestamp in Rollfi's `MM/DD/YYYY HH:mm:ss` format.", "pattern": "^(0[1-9]|1[0-2])/(0[1-9]|[12][0-9]|3[01])/[0-9]{4} ([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$" } } }, "payload": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "payPeriod" ], "properties": { "payPeriod": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "payPeriodId", "payPeriod", "deadLineToRunPayroll", "PayPeriodStatus", "isProcessed", "payDate", "payBeginDate", "payEndDate", "workerType", "payPeriodType", "payrollLineItems", "companyId" ], "properties": { "payPeriodId": { "type": "string", "format": "uuid" }, "payPeriod": { "type": "string", "description": "Display range for the pay period.", "examples": [ "09/01/2025 - 09/30/2025" ] }, "deadLineToRunPayroll": { "type": "string", "format": "date" }, "PayPeriodStatus": { "type": "string", "description": "Current pay-period state in Rollfi.", "enum": [ "new", "submitted", "cancelled", "inProcess", "processed", "failed", "returned", "skipped" ], "examples": [ "submitted" ] }, "total": { "type": "number" }, "debitAmount": { "type": "number" }, "employeeTaxSum": { "type": "number" }, "employerTaxSum": { "type": "number" }, "isProcessed": { "type": "boolean" }, "payDate": { "type": "string", "format": "date" }, "payBeginDate": { "type": "string", "format": "date" }, "payEndDate": { "type": "string", "format": "date" }, "workerType": { "type": "object", "required": [ "workerType" ], "properties": { "workerType": { "type": "string", "examples": [ "W2" ] } } }, "payPeriodType": { "type": "object", "required": [ "payPeriodType" ], "properties": { "payPeriodType": { "type": "string", "examples": [ "Regular" ] } } }, "payrollLineItems": { "type": "array", "items": { "type": "object", "required": [ "userName", "grossTotal", "netTotal", "payHours", "payRate", "employeeTax", "employerTax", "payMethod" ], "properties": { "userName": { "type": "string" }, "grossTotal": { "type": "number" }, "netTotal": { "type": "number" }, "payHours": { "type": "number" }, "payRate": { "type": "number" }, "employeeTax": { "type": "object", "properties": { "total": { "type": "number" }, "details": { "type": "array", "items": { "type": "object", "required": [ "name", "amount" ], "properties": { "name": { "type": "string" }, "amount": { "type": "number" } } } } } }, "employerTax": { "type": "object", "properties": { "total": { "type": "number" }, "details": { "type": "array", "items": { "type": "object", "required": [ "name", "amount" ], "properties": { "name": { "type": "string" }, "amount": { "type": "number" } } } } } }, "adjustments": { "type": "object", "properties": { "additionalCompensation": { "type": "number" }, "deductions": { "type": "number" }, "reimbursements": { "type": "number" } } }, "overtime": { "type": "array", "items": { "type": "object", "required": [ "type", "hours", "amount" ], "properties": { "type": { "type": "string" }, "hours": { "type": "number" }, "amount": { "type": "number" } } } }, "payMethod": { "type": "string", "examples": [ "Check" ] } } } }, "companyId": { "type": "string", "format": "uuid" } } } } } } } } }, "examples": { "payPeriodCreated": { "value": { "trigger": { "eventId": "5fd45e70-0676-419e-ba44-91f23cb71da9", "eventType": "payperiod.payperiodstatus.insert", "eventTimeStamp": "04/06/2026 22:07:04" }, "payload": [ { "payPeriod": [ { "payPeriodId": "30AF9044-3E27-4D01-9938-DAA958C88D8D", "payPeriod": "09/01/2025 - 09/30/2025", "deadLineToRunPayroll": "2025-09-26", "PayPeriodStatus": "new", "total": 3120, "debitAmount": 678.29, "employeeTaxSum": 393.4, "employerTaxSum": 284.89, "isProcessed": false, "payDate": "2025-09-30", "payBeginDate": "2025-09-01", "payEndDate": "2025-09-30", "workerType": { "workerType": "W2" }, "payPeriodType": { "payPeriodType": "Regular" }, "payrollLineItems": [], "companyId": "EB45E206-5E50-4079-8B41-04C05E4C5338" } ] } ] }, "summary": "Pay period created and still editable" }, "submitted": { "value": { "trigger": { "eventId": "5fd45e70-0676-419e-ba44-91f23cb71da9", "eventType": "payperiod.payperiodstatus.update", "eventTimeStamp": "04/06/2026 22:07:04" }, "payload": [ { "payPeriod": [ { "payPeriodId": "30AF9044-3E27-4D01-9938-DAA958C88D8D", "payPeriod": "09/01/2025 - 09/30/2025", "deadLineToRunPayroll": "2025-09-26", "PayPeriodStatus": "submitted", "total": 3120, "debitAmount": 678.29, "employeeTaxSum": 393.4, "employerTaxSum": 284.89, "isProcessed": false, "payDate": "2025-09-30", "payBeginDate": "2025-09-01", "payEndDate": "2025-09-30", "workerType": { "workerType": "W2" }, "payPeriodType": { "payPeriodType": "Regular" }, "payrollLineItems": [ { "userName": "John Ober", "grossTotal": 1900, "netTotal": 1611.59, "payHours": 16, "payRate": 100, "employeeTax": { "total": 288.41, "details": [ { "name": "Medicare", "amount": 27.55 }, { "name": "Social Security", "amount": 117.8 }, { "name": "Federal Income Tax", "amount": 143.06 } ] }, "employerTax": { "details": [ { "name": "Unemployment Tax", "amount": 11.4 }, { "name": "Medicare", "amount": 27.55 }, { "name": "Social Security", "amount": 117.8 } ] }, "overtime": [ { "type": "Standard Overtime", "hours": 2, "amount": 300 } ], "payMethod": "Check" }, { "userName": "Ben Fineman", "grossTotal": 2220, "netTotal": 2115.01, "payHours": 90, "payRate": 20, "employeeTax": { "total": 104.99, "details": [ { "name": "Medicare", "amount": 14.79 }, { "name": "Social Security", "amount": 63.24 }, { "name": "NY State Income Tax", "amount": 16.13 } ] }, "employerTax": { "details": [ { "name": "Unemployment Tax", "amount": 6.12 }, { "name": "Medicare", "amount": 14.79 }, { "name": "Social Security", "amount": 63.24 } ] }, "adjustments": { "additionalCompensation": 100, "deductions": 1000, "reimbursements": 1000 }, "overtime": [ { "type": "Holiday/Weekend OT", "hours": 3, "amount": 15 } ], "payMethod": "Check" } ], "companyId": "EB45E206-5E50-4079-8B41-04C05E4C5338" } ] } ] }, "summary": "Pay period submitted" }, "inProcess": { "value": { "trigger": { "eventId": "5fd45e70-0676-419e-ba44-91f23cb71da9", "eventType": "payperiod.payperiodstatus.update", "eventTimeStamp": "04/06/2026 22:07:04" }, "payload": [ { "payPeriod": [ { "payPeriodId": "30AF9044-3E27-4D01-9938-DAA958C88D8D", "payPeriod": "09/01/2025 - 09/30/2025", "deadLineToRunPayroll": "2025-09-26", "PayPeriodStatus": "inProcess", "total": 3120, "debitAmount": 678.29, "employeeTaxSum": 393.4, "employerTaxSum": 284.89, "isProcessed": false, "payDate": "2025-09-30", "payBeginDate": "2025-09-01", "payEndDate": "2025-09-30", "workerType": { "workerType": "W2" }, "payPeriodType": { "payPeriodType": "Regular" }, "payrollLineItems": [ { "userName": "John Ober", "grossTotal": 1900, "netTotal": 1611.59, "payHours": 16, "payRate": 100, "employeeTax": { "total": 288.41, "details": [ { "name": "Medicare", "amount": 27.55 }, { "name": "Social Security", "amount": 117.8 }, { "name": "Federal Income Tax", "amount": 143.06 } ] }, "employerTax": { "details": [ { "name": "Unemployment Tax", "amount": 11.4 }, { "name": "Medicare", "amount": 27.55 }, { "name": "Social Security", "amount": 117.8 } ] }, "overtime": [ { "type": "Standard Overtime", "hours": 2, "amount": 300 } ], "payMethod": "Check" }, { "userName": "Ben Fineman", "grossTotal": 2220, "netTotal": 2115.01, "payHours": 90, "payRate": 20, "employeeTax": { "total": 104.99, "details": [ { "name": "Medicare", "amount": 14.79 }, { "name": "Social Security", "amount": 63.24 }, { "name": "NY State Income Tax", "amount": 16.13 } ] }, "employerTax": { "details": [ { "name": "Unemployment Tax", "amount": 6.12 }, { "name": "Medicare", "amount": 14.79 }, { "name": "Social Security", "amount": 63.24 } ] }, "adjustments": { "additionalCompensation": 100, "deductions": 1000, "reimbursements": 1000 }, "overtime": [ { "type": "Holiday/Weekend OT", "hours": 3, "amount": 15 } ], "payMethod": "Check" } ], "companyId": "EB45E206-5E50-4079-8B41-04C05E4C5338" } ] } ] }, "summary": "Payroll is actively processing" }, "processed": { "value": { "trigger": { "eventId": "5bb2e7f6-5400-47cd-b417-24c2bb2f36d9", "eventType": "payperiod.payperiodstatus.update", "eventTimeStamp": "04/07/2026 09:42:27" }, "payload": [ { "payPeriod": [ { "payPeriodId": "30AF9044-3E27-4D01-9938-DAA958C88D8D", "payPeriod": "09/01/2025 - 09/30/2025", "deadLineToRunPayroll": "2025-09-26", "PayPeriodStatus": "processed", "total": 3120, "debitAmount": 678.29, "employeeTaxSum": 393.4, "employerTaxSum": 284.89, "isProcessed": true, "payDate": "2025-09-30", "payBeginDate": "2025-09-01", "payEndDate": "2025-09-30", "workerType": { "workerType": "W2" }, "payPeriodType": { "payPeriodType": "Regular" }, "payrollLineItems": [ { "userName": "John Ober", "grossTotal": 1900, "netTotal": 1611.59, "payHours": 16, "payRate": 100, "employeeTax": { "total": 288.41, "details": [ { "name": "Medicare", "amount": 27.55 }, { "name": "Social Security", "amount": 117.8 }, { "name": "Federal Income Tax", "amount": 143.06 } ] }, "employerTax": { "details": [ { "name": "Unemployment Tax", "amount": 11.4 }, { "name": "Medicare", "amount": 27.55 }, { "name": "Social Security", "amount": 117.8 } ] }, "overtime": [ { "type": "Standard Overtime", "hours": 2, "amount": 300 } ], "payMethod": "Check" }, { "userName": "Ben Fineman", "grossTotal": 2220, "netTotal": 2115.01, "payHours": 90, "payRate": 20, "employeeTax": { "total": 104.99, "details": [ { "name": "Medicare", "amount": 14.79 }, { "name": "Social Security", "amount": 63.24 }, { "name": "NY State Income Tax", "amount": 16.13 } ] }, "employerTax": { "details": [ { "name": "Unemployment Tax", "amount": 6.12 }, { "name": "Medicare", "amount": 14.79 }, { "name": "Social Security", "amount": 63.24 } ] }, "adjustments": { "additionalCompensation": 100, "deductions": 1000, "reimbursements": 1000 }, "overtime": [ { "type": "Holiday/Weekend OT", "hours": 3, "amount": 15 } ], "payMethod": "Check" } ], "companyId": "EB45E206-5E50-4079-8B41-04C05E4C5338" } ] } ] }, "summary": "Payroll processing completed" }, "failed": { "value": { "trigger": { "eventId": "5fd45e70-0676-419e-ba44-91f23cb71da9", "eventType": "payperiod.payperiodstatus.update", "eventTimeStamp": "04/06/2026 22:07:04" }, "payload": [ { "payPeriod": [ { "payPeriodId": "30AF9044-3E27-4D01-9938-DAA958C88D8D", "payPeriod": "09/01/2025 - 09/30/2025", "deadLineToRunPayroll": "2025-09-26", "PayPeriodStatus": "failed", "total": 3120, "debitAmount": 678.29, "employeeTaxSum": 393.4, "employerTaxSum": 284.89, "isProcessed": false, "payDate": "2025-09-30", "payBeginDate": "2025-09-01", "payEndDate": "2025-09-30", "workerType": { "workerType": "W2" }, "payPeriodType": { "payPeriodType": "Regular" }, "payrollLineItems": [ { "userName": "John Ober", "grossTotal": 1900, "netTotal": 1611.59, "payHours": 16, "payRate": 100, "employeeTax": { "total": 288.41, "details": [ { "name": "Medicare", "amount": 27.55 }, { "name": "Social Security", "amount": 117.8 }, { "name": "Federal Income Tax", "amount": 143.06 } ] }, "employerTax": { "details": [ { "name": "Unemployment Tax", "amount": 11.4 }, { "name": "Medicare", "amount": 27.55 }, { "name": "Social Security", "amount": 117.8 } ] }, "overtime": [ { "type": "Standard Overtime", "hours": 2, "amount": 300 } ], "payMethod": "Check" }, { "userName": "Ben Fineman", "grossTotal": 2220, "netTotal": 2115.01, "payHours": 90, "payRate": 20, "employeeTax": { "total": 104.99, "details": [ { "name": "Medicare", "amount": 14.79 }, { "name": "Social Security", "amount": 63.24 }, { "name": "NY State Income Tax", "amount": 16.13 } ] }, "employerTax": { "details": [ { "name": "Unemployment Tax", "amount": 6.12 }, { "name": "Medicare", "amount": 14.79 }, { "name": "Social Security", "amount": 63.24 } ] }, "adjustments": { "additionalCompensation": 100, "deductions": 1000, "reimbursements": 1000 }, "overtime": [ { "type": "Holiday/Weekend OT", "hours": 3, "amount": 15 } ], "payMethod": "Check" } ], "companyId": "EB45E206-5E50-4079-8B41-04C05E4C5338" } ] } ] }, "summary": "Payroll processing failed" }, "cancelled": { "value": { "trigger": { "eventId": "5fd45e70-0676-419e-ba44-91f23cb71da9", "eventType": "payperiod.payperiodstatus.update", "eventTimeStamp": "04/06/2026 22:07:04" }, "payload": [ { "payPeriod": [ { "payPeriodId": "30AF9044-3E27-4D01-9938-DAA958C88D8D", "payPeriod": "09/01/2025 - 09/30/2025", "deadLineToRunPayroll": "2025-09-26", "PayPeriodStatus": "cancelled", "total": 3120, "debitAmount": 678.29, "employeeTaxSum": 393.4, "employerTaxSum": 284.89, "isProcessed": false, "payDate": "2025-09-30", "payBeginDate": "2025-09-01", "payEndDate": "2025-09-30", "workerType": { "workerType": "W2" }, "payPeriodType": { "payPeriodType": "Regular" }, "payrollLineItems": [ { "userName": "John Ober", "grossTotal": 1900, "netTotal": 1611.59, "payHours": 16, "payRate": 100, "employeeTax": { "total": 288.41, "details": [ { "name": "Medicare", "amount": 27.55 }, { "name": "Social Security", "amount": 117.8 }, { "name": "Federal Income Tax", "amount": 143.06 } ] }, "employerTax": { "details": [ { "name": "Unemployment Tax", "amount": 11.4 }, { "name": "Medicare", "amount": 27.55 }, { "name": "Social Security", "amount": 117.8 } ] }, "overtime": [ { "type": "Standard Overtime", "hours": 2, "amount": 300 } ], "payMethod": "Check" }, { "userName": "Ben Fineman", "grossTotal": 2220, "netTotal": 2115.01, "payHours": 90, "payRate": 20, "employeeTax": { "total": 104.99, "details": [ { "name": "Medicare", "amount": 14.79 }, { "name": "Social Security", "amount": 63.24 }, { "name": "NY State Income Tax", "amount": 16.13 } ] }, "employerTax": { "details": [ { "name": "Unemployment Tax", "amount": 6.12 }, { "name": "Medicare", "amount": 14.79 }, { "name": "Social Security", "amount": 63.24 } ] }, "adjustments": { "additionalCompensation": 100, "deductions": 1000, "reimbursements": 1000 }, "overtime": [ { "type": "Holiday/Weekend OT", "hours": 3, "amount": 15 } ], "payMethod": "Check" } ], "companyId": "EB45E206-5E50-4079-8B41-04C05E4C5338" } ] } ] }, "summary": "Submitted payroll cancelled for editing" }, "returned": { "value": { "trigger": { "eventId": "5fd45e70-0676-419e-ba44-91f23cb71da9", "eventType": "payperiod.payperiodstatus.update", "eventTimeStamp": "04/06/2026 22:07:04" }, "payload": [ { "payPeriod": [ { "payPeriodId": "30AF9044-3E27-4D01-9938-DAA958C88D8D", "payPeriod": "09/01/2025 - 09/30/2025", "deadLineToRunPayroll": "2025-09-26", "PayPeriodStatus": "returned", "total": 3120, "debitAmount": 678.29, "employeeTaxSum": 393.4, "employerTaxSum": 284.89, "isProcessed": false, "payDate": "2025-09-30", "payBeginDate": "2025-09-01", "payEndDate": "2025-09-30", "workerType": { "workerType": "W2" }, "payPeriodType": { "payPeriodType": "Regular" }, "payrollLineItems": [ { "userName": "John Ober", "grossTotal": 1900, "netTotal": 1611.59, "payHours": 16, "payRate": 100, "employeeTax": { "total": 288.41, "details": [ { "name": "Medicare", "amount": 27.55 }, { "name": "Social Security", "amount": 117.8 }, { "name": "Federal Income Tax", "amount": 143.06 } ] }, "employerTax": { "details": [ { "name": "Unemployment Tax", "amount": 11.4 }, { "name": "Medicare", "amount": 27.55 }, { "name": "Social Security", "amount": 117.8 } ] }, "overtime": [ { "type": "Standard Overtime", "hours": 2, "amount": 300 } ], "payMethod": "Check" }, { "userName": "Ben Fineman", "grossTotal": 2220, "netTotal": 2115.01, "payHours": 90, "payRate": 20, "employeeTax": { "total": 104.99, "details": [ { "name": "Medicare", "amount": 14.79 }, { "name": "Social Security", "amount": 63.24 }, { "name": "NY State Income Tax", "amount": 16.13 } ] }, "employerTax": { "details": [ { "name": "Unemployment Tax", "amount": 6.12 }, { "name": "Medicare", "amount": 14.79 }, { "name": "Social Security", "amount": 63.24 } ] }, "adjustments": { "additionalCompensation": 100, "deductions": 1000, "reimbursements": 1000 }, "overtime": [ { "type": "Holiday/Weekend OT", "hours": 3, "amount": 15 } ], "payMethod": "Check" } ], "companyId": "EB45E206-5E50-4079-8B41-04C05E4C5338" } ] } ] }, "summary": "Payroll funds returned after processing" }, "skipped": { "value": { "trigger": { "eventId": "6a2b8cbc-76f6-4925-b8d1-9c4a113766fc", "eventType": "payperiod.payperiodstatus.update", "eventTimeStamp": "04/08/2026 14:12:49" }, "payload": [ { "payPeriod": [ { "payPeriodId": "30AF9044-3E27-4D01-9938-DAA958C88D8D", "payPeriod": "09/01/2025 - 09/30/2025", "deadLineToRunPayroll": "2025-09-26", "PayPeriodStatus": "skipped", "total": 3120, "debitAmount": 678.29, "employeeTaxSum": 393.4, "employerTaxSum": 284.89, "isProcessed": false, "payDate": "2025-09-30", "payBeginDate": "2025-09-01", "payEndDate": "2025-09-30", "workerType": { "workerType": "W2" }, "payPeriodType": { "payPeriodType": "Regular" }, "payrollLineItems": [], "companyId": "EB45E206-5E50-4079-8B41-04C05E4C5338" } ] } ] }, "summary": "Pay period skipped" } } } }, "required": true }, "responses": { "200": { "description": "Pay period status event accepted successfully.", "headers": {} } }, "security": [] } }, "employeeBankAccountStatus": { "post": { "summary": "Employee bank account status event", "deprecated": false, "description": "Emitted when an employee bank account is created or its verification status changes.\n\n### Events\n\n- `employeebankaccount.employeebankaccountstatus.insert` — emitted when the account is created. The initial bank-account `status` is `new`.\n- `employeebankaccount.employeebankaccountstatus.update` — emitted when the account moves to `pending` or `ready`.\n\nA direct-deposit employee’s bank account must be `ready` before the employee can become Active.\n", "operationId": "employeeBankAccountStatus", "tags": [ "Employee Bank Account Webhooks" ], "parameters": [ { "name": "X-Rollfi-Timestamp", "in": "header", "description": "Unix timestamp, in seconds, used when verifying the webhook signature.", "required": false, "example": "", "schema": { "type": "string", "pattern": "^\\d+$", "examples": [ "1767725956" ] } }, { "name": "X-Rollfi-Signature", "in": "header", "description": "Rollfi webhook signature containing the key ID, algorithm, and signature value.", "required": false, "example": "", "schema": { "type": "string", "examples": [ "kid=rollfi-webhook-key-01,alg=RS256,v1=eyJhbGciOiJSUzI1NiJ9" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "trigger", "payload" ], "properties": { "trigger": { "type": "object", "required": [ "eventId", "eventType", "eventTimeStamp" ], "properties": { "eventId": { "type": "string", "format": "uuid", "description": "Stable event identifier that remains the same across retries." }, "eventType": { "type": "string", "enum": [ "employeebankaccount.employeebankaccountstatus.insert", "employeebankaccount.employeebankaccountstatus.update" ], "description": "Identifies whether the entity was created or subsequently updated." }, "eventTimeStamp": { "type": "string", "description": "UTC event timestamp in Rollfi's `MM/DD/YYYY HH:mm:ss` format.", "pattern": "^(0[1-9]|1[0-2])/(0[1-9]|[12][0-9]|3[01])/[0-9]{4} ([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$" } } }, "payload": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "user" ], "properties": { "user": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "user", "userId", "companyId", "status", "WorkerType", "firstName", "lastName", "kycStatus", "bankAccounts" ], "properties": { "user": { "type": "string", "examples": [ "Alex Morgan" ] }, "userId": { "type": "string", "format": "uuid" }, "companyId": { "type": "string", "format": "uuid" }, "status": { "type": "object", "required": [ "userStatus" ], "properties": { "userStatus": { "type": "string", "examples": [ "Invite Sent" ] } } }, "WorkerType": { "type": "object", "required": [ "WorkerType" ], "properties": { "WorkerType": { "type": "string", "examples": [ "W2" ] } } }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "phoneNumber": { "type": [ "string", "null" ] }, "kycStatus": { "type": "string", "enum": [ "kyc not initiated", "pending", "passed", "failed" ] }, "jobTitle": { "type": [ "string", "null" ] }, "dateOfJoin": { "type": [ "string", "null" ], "format": "date" }, "email": { "type": [ "string", "null" ], "format": "email" }, "userWages": { "type": "array", "items": { "type": "object", "properties": { "userWageId": { "type": "string", "format": "uuid" }, "WageRate": { "type": "number" }, "WageBasis": { "type": "object", "properties": { "WageBasis": { "type": "string" } } }, "paymentMethod": { "type": "object", "properties": { "PaymentMethod": { "type": "string" } } } } } }, "bankAccounts": { "type": "array", "items": { "type": "object", "required": [ "userPayAccountEntityId", "bankName", "accountName", "accountNumber", "payPercentage", "accountType", "status", "accountPriority" ], "properties": { "userPayAccountEntityId": { "type": "string", "format": "uuid" }, "bankName": { "type": "string", "examples": [ "First Platypus Bank" ] }, "accountName": { "type": "string", "examples": [ "Primary Checking" ] }, "accountNumber": { "type": "string", "description": "Masked account number.", "examples": [ "XXXXXXXXX1111" ] }, "payPercentage": { "type": "number", "minimum": 0, "maximum": 100, "examples": [ 100 ] }, "accountType": { "type": "string", "examples": [ "checking" ] }, "status": { "type": "string", "description": "Current bank-account status: `new` before verification, `pending` during verification or setup, and `ready` when verified and usable.", "enum": [ "new", "pending", "ready" ], "examples": [ "pending" ] }, "accountPriority": { "type": "string", "examples": [ "Primary" ] } } } } } } } } } } } }, "examples": { "bankAccountCreated": { "value": { "trigger": { "eventId": "4e8f2b91-5d64-4c0a-9c61-3b8e2c7d9f44", "eventType": "employeebankaccount.employeebankaccountstatus.insert", "eventTimeStamp": "01/07/2026 13:28:41" }, "payload": [ { "user": [ { "user": "Alex Morgan", "userId": "A12F45BC-9D31-4C9E-B28F-7F6E2C91D4A8", "companyId": "8E9F2B11-6A44-4D8C-B3A2-91F6D2E8C7A0", "status": { "userStatus": "Invite Sent" }, "WorkerType": { "WorkerType": "W2" }, "firstName": "Alex", "lastName": "Morgan", "phoneNumber": "5551234567", "kycStatus": "passed", "jobTitle": "Quality Analyst", "dateOfJoin": "2026-01-07", "email": "alex.morgan@example.com", "userWages": [ { "userWageId": "E4D92C17-1B55-4C3E-A9D8-2F5B9A1C7E44", "WageRate": 85, "WageBasis": { "WageBasis": "Per Month" }, "paymentMethod": { "PaymentMethod": "Direct Deposit" } } ], "bankAccounts": [ { "userPayAccountEntityId": "CBA649D6-8047-483F-A66F-0F5C745E3C3A", "bankName": "First Platypus Bank", "accountName": "Primary Checking", "accountNumber": "XXXXXXXXX1111", "payPercentage": 100, "accountType": "checking", "status": "new", "accountPriority": "Primary" } ] } ] } ] }, "summary": "Employee bank account created" }, "verificationPending": { "value": { "trigger": { "eventId": "4e8f2b91-5d64-4c0a-9c61-3b8e2c7d9f44", "eventType": "employeebankaccount.employeebankaccountstatus.update", "eventTimeStamp": "01/07/2026 13:28:41" }, "payload": [ { "user": [ { "user": "Alex Morgan", "userId": "A12F45BC-9D31-4C9E-B28F-7F6E2C91D4A8", "companyId": "8E9F2B11-6A44-4D8C-B3A2-91F6D2E8C7A0", "status": { "userStatus": "Invite Sent" }, "WorkerType": { "WorkerType": "W2" }, "firstName": "Alex", "lastName": "Morgan", "phoneNumber": "5551234567", "kycStatus": "passed", "jobTitle": "Quality Analyst", "dateOfJoin": "2026-01-07", "email": "alex.morgan@example.com", "userWages": [ { "userWageId": "E4D92C17-1B55-4C3E-A9D8-2F5B9A1C7E44", "WageRate": 85, "WageBasis": { "WageBasis": "Per Month" }, "paymentMethod": { "PaymentMethod": "Direct Deposit" } } ], "bankAccounts": [ { "userPayAccountEntityId": "CBA649D6-8047-483F-A66F-0F5C745E3C3A", "bankName": "First Platypus Bank", "accountName": "Primary Checking", "accountNumber": "XXXXXXXXX1111", "payPercentage": 100, "accountType": "checking", "status": "pending", "accountPriority": "Primary" } ] } ] } ] }, "summary": "Employee bank account verification pending" }, "ready": { "value": { "trigger": { "eventId": "92094e51-e890-412c-82c2-e3712e1b95d2", "eventType": "employeebankaccount.employeebankaccountstatus.update", "eventTimeStamp": "01/07/2026 14:09:03" }, "payload": [ { "user": [ { "user": "Alex Morgan", "userId": "A12F45BC-9D31-4C9E-B28F-7F6E2C91D4A8", "companyId": "8E9F2B11-6A44-4D8C-B3A2-91F6D2E8C7A0", "status": { "userStatus": "Invite Sent" }, "WorkerType": { "WorkerType": "W2" }, "firstName": "Alex", "lastName": "Morgan", "phoneNumber": "5551234567", "kycStatus": "passed", "jobTitle": "Quality Analyst", "dateOfJoin": "2026-01-07", "email": "alex.morgan@example.com", "userWages": [ { "userWageId": "E4D92C17-1B55-4C3E-A9D8-2F5B9A1C7E44", "WageRate": 85, "WageBasis": { "WageBasis": "Per Month" }, "paymentMethod": { "PaymentMethod": "Direct Deposit" } } ], "bankAccounts": [ { "userPayAccountEntityId": "CBA649D6-8047-483F-A66F-0F5C745E3C3A", "bankName": "First Platypus Bank", "accountName": "Primary Checking", "accountNumber": "XXXXXXXXX1111", "payPercentage": 100, "accountType": "checking", "status": "ready", "accountPriority": "Primary" } ] } ] } ] }, "summary": "Employee bank account ready for direct deposit" } } } }, "required": true }, "responses": { "200": { "description": "Employee bank account status event accepted successfully.", "headers": {} } }, "security": [] } }, "employeeKycStatus": { "post": { "summary": "Employee KYC status event", "deprecated": false, "description": "Emitted when an employee is created or their KYC verification status changes.\n\n### Events\n\n- `employee.kycstatus.insert` — emitted when the employee is created. The initial `kycStatus` is `kyc not initiated`.\n- `employee.kycstatus.update` — emitted when KYC moves to `pending`, `passed`, or `failed`.\n", "operationId": "employeeKycStatus", "tags": [ "Employee KYC Webhooks" ], "parameters": [ { "name": "X-Rollfi-Timestamp", "in": "header", "description": "Unix timestamp, in seconds, used when verifying the webhook signature.", "required": false, "example": "", "schema": { "type": "string", "pattern": "^\\d+$", "examples": [ "1767725956" ] } }, { "name": "X-Rollfi-Signature", "in": "header", "description": "Rollfi webhook signature containing the key ID, algorithm, and signature value.", "required": false, "example": "", "schema": { "type": "string", "examples": [ "kid=rollfi-webhook-key-01,alg=RS256,v1=eyJhbGciOiJSUzI1NiJ9" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "trigger", "payload" ], "properties": { "trigger": { "type": "object", "required": [ "eventId", "eventType", "eventTimeStamp" ], "properties": { "eventId": { "type": "string", "format": "uuid", "description": "Stable event identifier that remains the same across retries." }, "eventType": { "type": "string", "enum": [ "employee.kycstatus.insert", "employee.kycstatus.update" ], "description": "Identifies whether the entity was created or subsequently updated." }, "eventTimeStamp": { "type": "string", "description": "UTC event timestamp in Rollfi's `MM/DD/YYYY HH:mm:ss` format.", "pattern": "^(0[1-9]|1[0-2])/(0[1-9]|[12][0-9]|3[01])/[0-9]{4} ([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$" } } }, "payload": { "type": "array", "minItems": 1, "description": "Wrapper containing the affected employee record.", "items": { "type": "object", "required": [ "user" ], "properties": { "user": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "user", "userId", "companyId", "status", "WorkerType", "firstName", "lastName", "kycStatus" ], "properties": { "user": { "type": "string", "examples": [ "Alex Morgan" ] }, "userId": { "type": "string", "format": "uuid" }, "userReferenceId": { "type": [ "string", "null" ], "examples": [ "" ] }, "companyId": { "type": "string", "format": "uuid" }, "status": { "type": "object", "required": [ "userStatus" ], "properties": { "userStatus": { "type": "string", "description": "Current employee lifecycle status in Rollfi.", "enum": [ "Add Wage", "Invite Sent", "Active", "Deactivate", "Terminate", "Former", "Deleted" ], "examples": [ "Invite Sent" ] } } }, "WorkerType": { "type": "object", "required": [ "WorkerType" ], "properties": { "WorkerType": { "type": "string", "examples": [ "W2" ] } } }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "middleName": { "type": [ "string", "null" ] }, "phoneNumber": { "type": [ "string", "null" ], "examples": [ "5551234567" ] }, "kycStatus": { "type": "string", "description": "Current employee KYC status. `kyc not initiated` is the initial state; `passed` is required before the employee can become Active.", "enum": [ "kyc not initiated", "pending", "passed", "failed" ], "examples": [ "passed" ] }, "jobTitle": { "type": [ "string", "null" ] }, "dateOfJoin": { "type": [ "string", "null" ], "format": "date" }, "email": { "type": [ "string", "null" ], "format": "email" }, "userWages": { "type": "array", "items": { "type": "object", "required": [ "userWageId", "WageRate", "WageBasis", "paymentMethod" ], "properties": { "userWageId": { "type": "string", "format": "uuid" }, "standardWorkingHours": { "type": "number", "examples": [ 0 ] }, "WageRate": { "type": "number", "examples": [ 1500 ] }, "WageBasis": { "type": "object", "required": [ "WageBasis" ], "properties": { "WageBasis": { "type": "string", "examples": [ "Per Month" ] } } }, "paymentMethod": { "type": "object", "required": [ "PaymentMethod" ], "properties": { "PaymentMethod": { "type": "string", "examples": [ "Direct Deposit" ] } } }, "employeeRefTaxExempt": { "type": [ "string", "null" ], "examples": [ "No, this employee is not tax exempt" ] }, "employeeType": { "type": [ "string", "null" ], "examples": [ "Salary/Eligible for overtime" ] }, "differentialPay": { "type": [ "object", "null" ], "additionalProperties": true, "properties": {} }, "employmentStatus": { "type": [ "string", "null" ], "examples": [ "Full Time (30+ Hours per week)" ] } } } }, "userRemoteLocations": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": {} } }, "companyLocationCategory": { "type": [ "object", "null" ], "properties": { "companyLocationCategory": { "type": "string", "examples": [ "Office" ] } } }, "companyLocation": { "type": [ "object", "null" ], "properties": { "companyLocation": { "type": "string", "examples": [ "Primary Residence" ] }, "companyLocationId": { "type": "string", "format": "uuid" }, "Address1": { "type": "string", "examples": [ "6875 Sand Lake Rd" ] }, "Address2": { "type": "string", "examples": [ "" ] }, "City": { "type": "string", "examples": [ "Orlando" ] }, "Country": { "type": "string", "examples": [ "US" ] }, "State": { "type": "string", "examples": [ "FL" ] }, "Zipcode": { "type": "string", "examples": [ "32819" ] } } }, "stateCode": { "type": [ "string", "null" ] }, "W4Informations": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": {} } }, "ssn": { "type": [ "string", "null" ], "description": "May be null or omitted depending on the event and permissions." }, "userRemoteLocation": { "type": [ "object", "null" ], "additionalProperties": true, "properties": {} }, "stateW4Informations": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": {} } }, "bankAccounts": { "type": "array", "items": { "type": "object", "properties": { "userPayAccountEntityId": { "type": "string", "format": "uuid" }, "bankName": { "type": "string" }, "accountName": { "type": "string" }, "accountNumber": { "type": "string", "description": "Masked account number." }, "payPercentage": { "type": "number" }, "accountType": { "type": "string" }, "status": { "type": "string" }, "accountPriority": { "type": "string" } }, "additionalProperties": true } }, "timeOffRequests": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": {} } }, "employeeGarnishments": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": {} } } } } } } } } } }, "examples": { "employeeCreated": { "value": { "trigger": { "eventId": "6f91c2a4-8d31-4a1b-b5f4-91a2d7c4e810", "eventType": "employee.kycstatus.insert", "eventTimeStamp": "01/07/2026 15:27:12" }, "payload": [ { "user": [ { "user": "Alex Morgan", "userId": "A12F45BC-9D31-4C9E-B28F-7F6E2C91D4A8", "userReferenceId": "", "companyId": "8E9F2B11-6A44-4D8C-B3A2-91F6D2E8C7A0", "status": { "userStatus": "Add Wage" }, "WorkerType": { "WorkerType": "W2" }, "firstName": "Alex", "lastName": "Morgan", "middleName": "", "phoneNumber": "5551234567", "kycStatus": "kyc not initiated", "jobTitle": "Quality Analyst", "dateOfJoin": "2026-01-07", "email": "alex.morgan@example.com", "userWages": [ { "userWageId": "E4D92C17-1B55-4C3E-A9D8-2F5B9A1C7E44", "standardWorkingHours": 0, "WageRate": 85, "WageBasis": { "WageBasis": "Per Month" }, "paymentMethod": { "PaymentMethod": "Check" } } ], "bankAccounts": [] } ] } ] }, "summary": "Employee created before KYC is initiated" }, "kycPending": { "value": { "trigger": { "eventId": "6f91c2a4-8d31-4a1b-b5f4-91a2d7c4e810", "eventType": "employee.kycstatus.update", "eventTimeStamp": "01/07/2026 15:27:12" }, "payload": [ { "user": [ { "user": "Alex Morgan", "userId": "A12F45BC-9D31-4C9E-B28F-7F6E2C91D4A8", "userReferenceId": "", "companyId": "8E9F2B11-6A44-4D8C-B3A2-91F6D2E8C7A0", "status": { "userStatus": "Invite Sent" }, "WorkerType": { "WorkerType": "W2" }, "firstName": "Alex", "lastName": "Morgan", "middleName": "", "phoneNumber": "5551234567", "kycStatus": "pending", "jobTitle": "Quality Analyst", "dateOfJoin": "2026-01-07", "email": "alex.morgan@example.com", "userWages": [ { "userWageId": "E4D92C17-1B55-4C3E-A9D8-2F5B9A1C7E44", "standardWorkingHours": 0, "WageRate": 85, "WageBasis": { "WageBasis": "Per Month" }, "paymentMethod": { "PaymentMethod": "Direct Deposit" } } ], "bankAccounts": [] } ] } ] }, "summary": "KYC verification is in progress" }, "kycPassed": { "value": { "trigger": { "eventId": "6f91c2a4-8d31-4a1b-b5f4-91a2d7c4e810", "eventType": "employee.kycstatus.update", "eventTimeStamp": "01/07/2026 15:27:12" }, "payload": [ { "user": [ { "user": "Alex Morgan", "userId": "A12F45BC-9D31-4C9E-B28F-7F6E2C91D4A8", "userReferenceId": "", "companyId": "8E9F2B11-6A44-4D8C-B3A2-91F6D2E8C7A0", "status": { "userStatus": "Invite Sent" }, "WorkerType": { "WorkerType": "W2" }, "firstName": "Alex", "lastName": "Morgan", "middleName": "", "phoneNumber": "5551234567", "kycStatus": "passed", "jobTitle": "Quality Analyst", "dateOfJoin": "2026-01-07", "email": "alex.morgan@example.com", "userWages": [ { "userWageId": "E4D92C17-1B55-4C3E-A9D8-2F5B9A1C7E44", "standardWorkingHours": 0, "WageRate": 85, "WageBasis": { "WageBasis": "Per Month" }, "paymentMethod": { "PaymentMethod": "Direct Deposit" } } ], "bankAccounts": [] } ] } ] }, "summary": "KYC verification passed" }, "kycFailed": { "value": { "trigger": { "eventId": "81e602ae-14de-41fd-811f-63adb0f9d31e", "eventType": "employee.kycstatus.update", "eventTimeStamp": "01/07/2026 16:04:44" }, "payload": [ { "user": [ { "user": "Alex Morgan", "userId": "A12F45BC-9D31-4C9E-B28F-7F6E2C91D4A8", "userReferenceId": "", "companyId": "8E9F2B11-6A44-4D8C-B3A2-91F6D2E8C7A0", "status": { "userStatus": "Invite Sent" }, "WorkerType": { "WorkerType": "W2" }, "firstName": "Alex", "lastName": "Morgan", "middleName": "", "phoneNumber": "5551234567", "kycStatus": "failed", "jobTitle": "Quality Analyst", "dateOfJoin": "2026-01-07", "email": "alex.morgan@example.com", "userWages": [ { "userWageId": "E4D92C17-1B55-4C3E-A9D8-2F5B9A1C7E44", "standardWorkingHours": 0, "WageRate": 85, "WageBasis": { "WageBasis": "Per Month" }, "paymentMethod": { "PaymentMethod": "Direct Deposit" } } ], "bankAccounts": [] } ] } ] }, "summary": "KYC verification failed" } } } }, "required": true }, "responses": { "200": { "description": "Employee KYC status accepted successfully.", "headers": {} } }, "security": [] } }, "companyBankAccountStatus": { "post": { "summary": "Company bank account status event", "deprecated": false, "description": "Emitted when a company funding source is created or its verification status changes.\n\n### Events\n\n- `companybankaccount.companybankaccountstatus.insert` — emitted when the account is created. The initial bank-account `status` is `new`.\n- `companybankaccount.companybankaccountstatus.update` — emitted when the account moves to `pending` or `ready`.\n\nPayroll cannot proceed until the funding source is `ready`.\n", "operationId": "companyBankAccountStatus", "tags": [ "Company Bank Account Webhooks" ], "parameters": [ { "name": "X-Rollfi-Timestamp", "in": "header", "description": "Unix timestamp, in seconds, used when verifying the webhook signature.", "required": false, "example": "", "schema": { "type": "string", "pattern": "^\\d+$", "examples": [ "1767725956" ] } }, { "name": "X-Rollfi-Signature", "in": "header", "description": "Rollfi webhook signature containing the key ID, algorithm, and signature value.", "required": false, "example": "", "schema": { "type": "string", "examples": [ "kid=rollfi-webhook-key-01,alg=RS256,v1=eyJhbGciOiJSUzI1NiJ9" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "trigger", "payload" ], "properties": { "trigger": { "type": "object", "required": [ "eventId", "eventType", "eventTimeStamp" ], "properties": { "eventId": { "type": "string", "format": "uuid", "description": "Stable event identifier that remains the same across retries." }, "eventType": { "type": "string", "enum": [ "companybankaccount.companybankaccountstatus.insert", "companybankaccount.companybankaccountstatus.update" ], "description": "Identifies whether the entity was created or subsequently updated." }, "eventTimeStamp": { "type": "string", "description": "UTC event timestamp in Rollfi's `MM/DD/YYYY HH:mm:ss` format.", "pattern": "^(0[1-9]|1[0-2])/(0[1-9]|[12][0-9]|3[01])/[0-9]{4} ([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$" } } }, "payload": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "Company" ], "properties": { "Company": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "company", "companyID", "kycStatus", "BankAccounts" ], "properties": { "company": { "type": "string", "examples": [ "Acme Operations LLC" ] }, "companyID": { "type": "string", "format": "uuid" }, "businessWebsite": { "type": [ "string", "null" ], "format": "uri" }, "registration": { "type": "object", "properties": { "isTermsAccepted": { "type": "boolean", "examples": [ true ] } } }, "CompanyLocations": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": {} } }, "KYBInformations": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": {} } }, "kycStatus": { "type": "string", "enum": [ "new", "pending", "passed", "failed" ] }, "BankAccounts": { "type": "array", "items": { "type": "object", "required": [ "companyFundingSourceEntityId", "bankName", "accountName", "accountNumber", "accountType", "status" ], "properties": { "companyFundingSourceEntityId": { "type": "string", "format": "uuid" }, "bankName": { "type": "string", "examples": [ "Chase" ] }, "accountName": { "type": "string", "examples": [ "Primary Operating Account" ] }, "accountNumber": { "type": "string", "description": "Masked account number.", "examples": [ "XXXXXXXXX4321" ] }, "accountType": { "type": "string", "examples": [ "checking" ] }, "status": { "type": "string", "description": "Current bank-account status: `new` before verification, `pending` during verification or setup, and `ready` when verified and usable.", "enum": [ "new", "pending", "ready" ], "examples": [ "pending" ] }, "bankBalance": { "type": [ "number", "null" ], "examples": [ 2500 ] } } } }, "PaySchedules": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": {} } }, "StateTaxRegistrations": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": {} } } } } } } } } } }, "examples": { "bankAccountCreated": { "value": { "trigger": { "eventId": "9a7f4c21-3b5a-4a8c-9f6e-1d2e8b9c4a77", "eventType": "companybankaccount.companybankaccountstatus.insert", "eventTimeStamp": "01/06/2026 19:05:02" }, "payload": [ { "Company": [ { "company": "Acme Operations LLC", "companyID": "9F3A1C7E-5B22-4D91-8E6A-2C9E47B8A103", "businessWebsite": "https://www.acme-operations.com", "registration": { "isTermsAccepted": true }, "CompanyLocations": [], "KYBInformations": [], "kycStatus": "passed", "BankAccounts": [ { "companyFundingSourceEntityId": "E6237EA0-FA05-4AD6-A4AE-7E4360E876C9", "bankName": "Chase", "accountName": "Primary Operating Account", "accountNumber": "XXXXXXXXX4321", "accountType": "checking", "status": "new", "bankBalance": 2500 } ], "PaySchedules": [], "StateTaxRegistrations": [] } ] } ] }, "summary": "Company bank account created" }, "verificationPending": { "value": { "trigger": { "eventId": "9a7f4c21-3b5a-4a8c-9f6e-1d2e8b9c4a77", "eventType": "companybankaccount.companybankaccountstatus.update", "eventTimeStamp": "01/06/2026 19:05:02" }, "payload": [ { "Company": [ { "company": "Acme Operations LLC", "companyID": "9F3A1C7E-5B22-4D91-8E6A-2C9E47B8A103", "businessWebsite": "https://www.acme-operations.com", "registration": { "isTermsAccepted": true }, "CompanyLocations": [], "KYBInformations": [], "kycStatus": "passed", "BankAccounts": [ { "companyFundingSourceEntityId": "E6237EA0-FA05-4AD6-A4AE-7E4360E876C9", "bankName": "Chase", "accountName": "Primary Operating Account", "accountNumber": "XXXXXXXXX4321", "accountType": "checking", "status": "pending", "bankBalance": 2500 } ], "PaySchedules": [], "StateTaxRegistrations": [] } ] } ] }, "summary": "Company bank account verification pending" }, "ready": { "value": { "trigger": { "eventId": "887965e2-bdc8-4876-8ac3-f3cc004bbb95", "eventType": "companybankaccount.companybankaccountstatus.update", "eventTimeStamp": "01/06/2026 20:14:17" }, "payload": [ { "Company": [ { "company": "Acme Operations LLC", "companyID": "9F3A1C7E-5B22-4D91-8E6A-2C9E47B8A103", "businessWebsite": "https://www.acme-operations.com", "registration": { "isTermsAccepted": true }, "CompanyLocations": [], "KYBInformations": [], "kycStatus": "passed", "BankAccounts": [ { "companyFundingSourceEntityId": "E6237EA0-FA05-4AD6-A4AE-7E4360E876C9", "bankName": "Chase", "accountName": "Primary Operating Account", "accountNumber": "XXXXXXXXX4321", "accountType": "checking", "status": "ready", "bankBalance": 2500 } ], "PaySchedules": [], "StateTaxRegistrations": [] } ] } ] }, "summary": "Company bank account ready for payroll funding" } } } }, "required": true }, "responses": { "200": { "description": "Company bank account status event accepted successfully.", "headers": {} } }, "security": [] } }, "companyKybStatus": { "post": { "summary": "Company KYB status event", "deprecated": false, "description": "Emitted when a company is created or its KYB verification status changes.\n\n### Events\n\n- `company.kybstatus.insert` — emitted when the company is created. The initial `kycStatus` is `new`.\n- `company.kybstatus.update` — emitted when KYB moves to `pending`, `passed`, or `failed`.\n", "operationId": "companyKybStatus", "tags": [ "Company Webhooks" ], "parameters": [ { "name": "X-Rollfi-Timestamp", "in": "header", "description": "Unix timestamp, in seconds, used when verifying the webhook signature.", "required": true, "example": "", "schema": { "type": "string", "pattern": "^\\d+$", "examples": [ "1767725956" ] } }, { "name": "X-Rollfi-Signature", "in": "header", "description": "Rollfi webhook signature containing the key ID, algorithm, and signature value.", "required": true, "example": "", "schema": { "type": "string", "examples": [ "kid=rollfi-webhook-key-01,alg=RS256,v1=eyJhbGciOiJSUzI1NiJ9" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "trigger": { "type": "object", "properties": { "eventId": { "type": "string", "description": "Stable event identifier that remains the same across retries." }, "eventType": { "type": "string", "enum": [ "company.kybstatus.insert", "company.kybstatus.update" ], "description": "Identifies whether the entity was created or subsequently updated." }, "eventTimeStamp": { "type": "string", "description": "UTC event timestamp in Rollfi's `MM/DD/YYYY HH:mm:ss` format." } }, "required": [ "eventId", "eventType", "eventTimeStamp" ] }, "payload": { "type": "array", "items": { "type": "object", "properties": { "Company": { "type": "array", "items": { "type": "object", "properties": { "company": { "type": "string", "description": "Legal or display name of the company." }, "companyID": { "type": "string", "description": "Rollfi company identifier." }, "businessWebsite": { "type": "string" }, "registration": { "type": "object", "properties": { "isTermsAccepted": { "type": "boolean", "description": "Whether the company accepted the applicable terms." } }, "required": [ "isTermsAccepted" ] }, "CompanyLocations": { "type": "array", "items": { "type": "object", "properties": { "address1": { "type": "string" }, "address2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zipcode": { "type": "string" }, "country": { "type": "string" }, "companyLocation": { "type": "string" } } } }, "KYBInformations": { "type": "array", "items": { "type": "object", "properties": { "KybInformationId": { "type": "string" }, "ein": { "type": "string" }, "email": { "type": "string" }, "EntityType": { "type": "object", "properties": { "entityType": { "type": "string" } }, "required": [ "entityType" ] }, "phoneNumber": { "type": "string" }, "dateOfIncorporation": { "type": "string" } } } }, "kycStatus": { "type": "string", "description": "Current company KYB status:\n\n- `new`: Company created; KYB has not been initiated.\n- `pending`: KYB is being processed by the KYB provider.\n- `passed`: KYB passed and full platform functionality is unlocked.\n- `failed`: KYB failed and requires intervention before resubmission.\n", "enum": [ "new", "pending", "passed", "failed" ] }, "BankAccounts": { "type": "array", "items": { "type": "string" } }, "PaySchedules": { "type": "array", "items": { "type": "string" } }, "StateTaxRegistrations": { "type": "array", "items": { "type": "string" } } }, "required": [ "company", "companyID", "kycStatus" ] } } }, "required": [ "Company" ] }, "description": "Wrapper containing the affected company record." } }, "required": [ "trigger", "payload" ] }, "examples": { "companyCreated": { "value": { "trigger": { "eventId": "d2a34d4a-8e7b-4f9f-9d3f-1b9d6d7f6c10", "eventType": "company.kybstatus.insert", "eventTimeStamp": "01/06/2026 18:59:16" }, "payload": [ { "Company": [ { "company": "Acme Operations LLC", "companyID": "9F3A1C7E-5B22-4D91-8E6A-2C9E47B8A103", "businessWebsite": "https://www.acme-operations.com", "registration": { "isTermsAccepted": true }, "CompanyLocations": [], "KYBInformations": [], "kycStatus": "new", "BankAccounts": [], "PaySchedules": [], "StateTaxRegistrations": [] } ] } ] }, "summary": "Company created with a new KYB status" }, "kybPending": { "value": { "trigger": { "eventId": "d2a34d4a-8e7b-4f9f-9d3f-1b9d6d7f6c10", "eventType": "company.kybstatus.update", "eventTimeStamp": "01/06/2026 18:59:16" }, "payload": [ { "Company": [ { "company": "Acme Operations LLC", "companyID": "9F3A1C7E-5B22-4D91-8E6A-2C9E47B8A103", "businessWebsite": "https://www.acme-operations.com", "registration": { "isTermsAccepted": true }, "CompanyLocations": [ { "address1": "1234 N Broadway Ave", "address2": "Suite 400", "city": "Oklahoma City", "state": "OK", "zipcode": "73102", "country": "US", "companyLocation": "Headquarters" } ], "KYBInformations": [ { "KybInformationId": "3C7D9E51-8A24-4B6F-92D1-E5A8B3C4F702", "ein": "12-3456789", "email": "finance@acme-operations.com", "EntityType": { "entityType": "LLC" }, "phoneNumber": "5551234567", "dateOfIncorporation": "2019-03-15" } ], "kycStatus": "pending", "BankAccounts": [], "PaySchedules": [], "StateTaxRegistrations": [] } ] } ] }, "summary": "KYB review is in progress" }, "kybPassed": { "value": { "trigger": { "eventId": "d2a34d4a-8e7b-4f9f-9d3f-1b9d6d7f6c10", "eventType": "company.kybstatus.update", "eventTimeStamp": "01/06/2026 18:59:16" }, "payload": [ { "Company": [ { "company": "Acme Operations LLC", "companyID": "9F3A1C7E-5B22-4D91-8E6A-2C9E47B8A103", "businessWebsite": "https://www.acme-operations.com", "registration": { "isTermsAccepted": true }, "CompanyLocations": [ { "address1": "1234 N Broadway Ave", "address2": "Suite 400", "city": "Oklahoma City", "state": "OK", "zipcode": "73102", "country": "US", "companyLocation": "Headquarters" } ], "KYBInformations": [ { "KybInformationId": "3C7D9E51-8A24-4B6F-92D1-E5A8B3C4F702", "ein": "12-3456789", "email": "finance@acme-operations.com", "EntityType": { "entityType": "LLC" }, "phoneNumber": "5551234567", "dateOfIncorporation": "2019-03-15" } ], "kycStatus": "passed", "BankAccounts": [], "PaySchedules": [], "StateTaxRegistrations": [] } ] } ] }, "summary": "KYB review passed" }, "kybFailed": { "value": { "trigger": { "eventId": "d2a34d4a-8e7b-4f9f-9d3f-1b9d6d7f6c10", "eventType": "company.kybstatus.update", "eventTimeStamp": "01/06/2026 18:59:16" }, "payload": [ { "Company": [ { "company": "Acme Operations LLC", "companyID": "9F3A1C7E-5B22-4D91-8E6A-2C9E47B8A103", "businessWebsite": "https://www.acme-operations.com", "registration": { "isTermsAccepted": true }, "CompanyLocations": [ { "address1": "1234 N Broadway Ave", "address2": "Suite 400", "city": "Oklahoma City", "state": "OK", "zipcode": "73102", "country": "US", "companyLocation": "Headquarters" } ], "KYBInformations": [ { "KybInformationId": "3C7D9E51-8A24-4B6F-92D1-E5A8B3C4F702", "ein": "12-3456789", "email": "finance@acme-operations.com", "EntityType": { "entityType": "LLC" }, "phoneNumber": "5551234567", "dateOfIncorporation": "2019-03-15" } ], "kycStatus": "failed", "BankAccounts": [], "PaySchedules": [], "StateTaxRegistrations": [] } ] } ] }, "summary": "KYB review failed" } } } }, "required": true }, "responses": { "200": { "description": "Company KYB status accepted successfully.", "headers": {} } }, "security": [] } }, "employeeStatus": { "post": { "summary": "Employee status event", "deprecated": false, "description": "Emitted when an employee is created or their lifecycle status changes.\n\n### Events\n\n- `employee.employeestatus.insert` — emitted when the employee is created. The initial `userStatus` is `Add Wage`.\n- `employee.employeestatus.update` — emitted when the employee lifecycle status changes after creation.\n", "operationId": "employeeStatus", "tags": [ "Employee Status Webhooks" ], "parameters": [ { "name": "X-Rollfi-Timestamp", "in": "header", "description": "Unix timestamp, in seconds, used when verifying the webhook signature.", "required": true, "example": "", "schema": { "type": "string", "pattern": "^\\d+$", "examples": [ "1767725956" ] } }, { "name": "X-Rollfi-Signature", "in": "header", "description": "Rollfi webhook signature containing the key ID, algorithm, and signature value.", "required": true, "example": "", "schema": { "type": "string", "examples": [ "kid=rollfi-webhook-key-01,alg=RS256,v1=eyJhbGciOiJSUzI1NiJ9" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "trigger", "payload" ], "properties": { "trigger": { "type": "object", "required": [ "eventId", "eventType", "eventTimeStamp" ], "properties": { "eventId": { "type": "string", "format": "uuid", "description": "Stable event identifier that remains the same across retries." }, "eventType": { "type": "string", "enum": [ "employee.employeestatus.insert", "employee.employeestatus.update" ], "description": "Identifies whether the entity was created or subsequently updated." }, "eventTimeStamp": { "type": "string", "description": "UTC event timestamp in Rollfi's `MM/DD/YYYY HH:mm:ss` format.", "pattern": "^(0[1-9]|1[0-2])/(0[1-9]|[12][0-9]|3[01])/[0-9]{4} ([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$" } } }, "payload": { "type": "array", "minItems": 1, "description": "Wrapper containing the affected employee record.", "items": { "type": "object", "required": [ "user" ], "properties": { "user": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "user", "userId", "companyId", "status", "WorkerType", "firstName", "lastName", "kycStatus" ], "properties": { "user": { "type": "string", "examples": [ "Alex Morgan" ] }, "userId": { "type": "string", "format": "uuid" }, "userReferenceId": { "type": [ "string", "null" ], "examples": [ "" ] }, "companyId": { "type": "string", "format": "uuid" }, "status": { "type": "object", "required": [ "userStatus" ], "properties": { "userStatus": { "type": "string", "description": "Current employee lifecycle status in Rollfi.", "enum": [ "Add Wage", "Invite Sent", "Active", "Deactivate", "Terminate", "Former", "Deleted" ], "examples": [ "Invite Sent" ] } } }, "WorkerType": { "type": "object", "required": [ "WorkerType" ], "properties": { "WorkerType": { "type": "string", "examples": [ "W2" ] } } }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "middleName": { "type": [ "string", "null" ] }, "phoneNumber": { "type": [ "string", "null" ], "examples": [ "5551234567" ] }, "kycStatus": { "type": "string", "description": "Current employee KYC status. `kyc not initiated` is the initial state; `passed` is required before the employee can become Active.", "enum": [ "kyc not initiated", "pending", "passed", "failed" ], "examples": [ "passed" ] }, "jobTitle": { "type": [ "string", "null" ] }, "dateOfJoin": { "type": [ "string", "null" ], "format": "date" }, "email": { "type": [ "string", "null" ], "format": "email" }, "userWages": { "type": "array", "items": { "type": "object", "required": [ "userWageId", "WageRate", "WageBasis", "paymentMethod" ], "properties": { "userWageId": { "type": "string", "format": "uuid" }, "standardWorkingHours": { "type": "number", "examples": [ 0 ] }, "WageRate": { "type": "number", "examples": [ 1500 ] }, "WageBasis": { "type": "object", "required": [ "WageBasis" ], "properties": { "WageBasis": { "type": "string", "examples": [ "Per Month" ] } } }, "paymentMethod": { "type": "object", "required": [ "PaymentMethod" ], "properties": { "PaymentMethod": { "type": "string", "examples": [ "Direct Deposit" ] } } }, "employeeRefTaxExempt": { "type": [ "string", "null" ], "examples": [ "No, this employee is not tax exempt" ] }, "employeeType": { "type": [ "string", "null" ], "examples": [ "Salary/Eligible for overtime" ] }, "differentialPay": { "type": [ "object", "null" ], "additionalProperties": true, "properties": {} }, "employmentStatus": { "type": [ "string", "null" ], "examples": [ "Full Time (30+ Hours per week)" ] } } } }, "userRemoteLocations": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": {} } }, "companyLocationCategory": { "type": [ "object", "null" ], "properties": { "companyLocationCategory": { "type": "string", "examples": [ "Office" ] } } }, "companyLocation": { "type": [ "object", "null" ], "properties": { "companyLocation": { "type": "string", "examples": [ "Primary Residence" ] }, "companyLocationId": { "type": "string", "format": "uuid" }, "Address1": { "type": "string", "examples": [ "6875 Sand Lake Rd" ] }, "Address2": { "type": "string", "examples": [ "" ] }, "City": { "type": "string", "examples": [ "Orlando" ] }, "Country": { "type": "string", "examples": [ "US" ] }, "State": { "type": "string", "examples": [ "FL" ] }, "Zipcode": { "type": "string", "examples": [ "32819" ] } } }, "stateCode": { "type": [ "string", "null" ] }, "W4Informations": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": {} } }, "ssn": { "type": [ "string", "null" ], "description": "May be null or omitted depending on the event and permissions." }, "userRemoteLocation": { "type": [ "object", "null" ], "additionalProperties": true, "properties": {} }, "stateW4Informations": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": {} } }, "bankAccounts": { "type": "array", "items": { "type": "object", "properties": { "userPayAccountEntityId": { "type": "string", "format": "uuid" }, "bankName": { "type": "string" }, "accountName": { "type": "string" }, "accountNumber": { "type": "string", "description": "Masked account number." }, "payPercentage": { "type": "number" }, "accountType": { "type": "string" }, "status": { "type": "string" }, "accountPriority": { "type": "string" } }, "additionalProperties": true } }, "timeOffRequests": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": {} } }, "employeeGarnishments": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": {} } } } } } } } } } }, "examples": { "5": { "value": { "trigger": { "eventId": "6f91c2a4-8d31-4a1b-b5f4-91a2d7c4e810", "eventType": "employee.employeestatus.update", "eventTimeStamp": "01/07/2026 15:27:12" }, "payload": [ { "user": [ { "user": "Alex Morgan", "userId": "A12F45BC-9D31-4C9E-B28F-7F6E2C91D4A8", "userReferenceId": "", "companyId": "8E9F2B11-6A44-4D8C-B3A2-91F6D2E8C7A0", "status": { "userStatus": "Former" }, "WorkerType": { "WorkerType": "W2" }, "firstName": "Alex", "lastName": "Morgan", "middleName": "", "phoneNumber": "5551234567", "kycStatus": "passed", "jobTitle": "Quality Analyst", "dateOfJoin": "2026-01-07", "email": "alex.morgan@example.com", "userWages": [ { "userWageId": "E4D92C17-1B55-4C3E-A9D8-2F5B9A1C7E44", "standardWorkingHours": 0, "WageRate": 85, "WageBasis": { "WageBasis": "Per Month" }, "paymentMethod": { "PaymentMethod": "Check" } } ], "bankAccounts": [] } ] } ] }, "summary": "Former Employee" }, "6": { "value": { "trigger": { "eventId": "6f91c2a4-8d31-4a1b-b5f4-91a2d7c4e810", "eventType": "employee.employeestatus.update", "eventTimeStamp": "01/07/2026 15:27:12" }, "payload": [ { "user": [ { "user": "Alex Morgan", "userId": "A12F45BC-9D31-4C9E-B28F-7F6E2C91D4A8", "userReferenceId": "", "companyId": "8E9F2B11-6A44-4D8C-B3A2-91F6D2E8C7A0", "status": { "userStatus": "Deleted" }, "WorkerType": { "WorkerType": "W2" }, "firstName": "Alex", "lastName": "Morgan", "middleName": "", "phoneNumber": "5551234567", "kycStatus": "passed", "jobTitle": "Quality Analyst", "dateOfJoin": "2026-01-07", "email": "alex.morgan@example.com", "userWages": [], "bankAccounts": [] } ] } ] }, "summary": "Deleted Employee" }, "employeeCreated": { "value": { "trigger": { "eventId": "7d21ea80-f7cd-4765-83b4-d0ea74fa3095", "eventType": "employee.employeestatus.insert", "eventTimeStamp": "07/15/2026 14:21:19" }, "payload": [ { "user": [ { "user": "John Doe", "userId": "4207E6BB-50BD-4F49-BAE1-19F3D3A749A7", "userReferenceId": "", "companyId": "EB45E206-5E50-4079-8B41-04C05E4C5338", "status": { "userStatus": "Add Wage" }, "WorkerType": { "WorkerType": "W2" }, "firstName": "John", "lastName": "Doe", "middleName": "", "phoneNumber": "5698563259", "kycStatus": "kyc not initiated", "jobTitle": "HR", "dateOfJoin": "2027-02-27", "email": "testJohnDoe@mailsac.com", "userWages": [], "userRemoteLocations": [], "companyLocationCategory": { "companyLocationCategory": "Remote" }, "companyLocation": null, "stateCode": "KS", "W4Informations": [], "ssn": null, "userRemoteLocation": null, "stateW4Informations": [], "bankAccounts": [], "timeOffRequests": [], "timeOffPolicies": [], "employeeGarnishments": [], "recurringPayItems": { "additionalCompensations": [], "additionalDeductions": [], "recurringReimbursements": [] } } ] } ] }, "summary": "Employee created and awaiting wage information" }, "inviteSent": { "value": { "trigger": { "eventId": "ce5beb7f-93b4-4f3f-bef6-9ce3bd4e574f", "eventType": "employee.employeestatus.update", "eventTimeStamp": "01/08/2026 12:21:54" }, "payload": [ { "user": [ { "user": "Alex Morgan", "userId": "A12F45BC-9D31-4C9E-B28F-7F6E2C91D4A8", "userReferenceId": "", "companyId": "8E9F2B11-6A44-4D8C-B3A2-91F6D2E8C7A0", "status": { "userStatus": "Invite Sent" }, "WorkerType": { "WorkerType": "W2" }, "firstName": "Alex", "lastName": "Morgan", "middleName": "", "phoneNumber": "5551234567", "kycStatus": "kyc not initiated", "jobTitle": "Quality Analyst", "dateOfJoin": "2026-01-07", "email": "alex.morgan@example.com", "userWages": [ { "userWageId": "E4D92C17-1B55-4C3E-A9D8-2F5B9A1C7E44", "standardWorkingHours": 0, "WageRate": 85, "WageBasis": { "WageBasis": "Per Month" }, "paymentMethod": { "PaymentMethod": "Direct Deposit" }, "employeeRefTaxExempt": "No, this employee is not tax exempt", "employeeType": "Salary/Eligible for overtime", "differentialPay": null, "employmentStatus": "Full Time (30+ Hours per week)" } ], "bankAccounts": [], "userRemoteLocations": [], "companyLocationCategory": { "companyLocationCategory": "Office" }, "companyLocation": { "companyLocation": "Primary Residence", "companyLocationId": "746398E0-B335-47C6-BF78-D268D034594E", "Address1": "6875 Sand Lake Rd", "Address2": "", "City": "Orlando", "Country": "US", "State": "FL", "Zipcode": "32819" }, "stateCode": null, "W4Informations": [], "ssn": null, "userRemoteLocation": null, "stateW4Informations": [], "timeOffRequests": [], "employeeGarnishments": [] } ] } ] }, "summary": "Employee invitation sent" }, "active": { "value": { "trigger": { "eventId": "c68d4dc1-638a-4baa-9ccb-26a2520e38a2", "eventType": "employee.employeestatus.update", "eventTimeStamp": "01/08/2026 13:10:02" }, "payload": [ { "user": [ { "user": "Alex Morgan", "userId": "A12F45BC-9D31-4C9E-B28F-7F6E2C91D4A8", "userReferenceId": "", "companyId": "8E9F2B11-6A44-4D8C-B3A2-91F6D2E8C7A0", "status": { "userStatus": "Active" }, "WorkerType": { "WorkerType": "W2" }, "firstName": "Alex", "lastName": "Morgan", "middleName": "", "phoneNumber": "5551234567", "kycStatus": "passed", "jobTitle": "Quality Analyst", "dateOfJoin": "2026-01-07", "email": "alex.morgan@example.com", "userWages": [ { "userWageId": "E4D92C17-1B55-4C3E-A9D8-2F5B9A1C7E44", "standardWorkingHours": 0, "WageRate": 85, "WageBasis": { "WageBasis": "Per Month" }, "paymentMethod": { "PaymentMethod": "Direct Deposit" }, "employeeRefTaxExempt": "No, this employee is not tax exempt", "employeeType": "Salary/Eligible for overtime", "differentialPay": null, "employmentStatus": "Full Time (30+ Hours per week)" } ], "bankAccounts": [ { "userPayAccountEntityId": "5B8E2D91-4C77-4F1A-9E3B-8D2A6C4F7E10", "bankName": "Chase", "accountName": "Alex Morgan Checking", "accountNumber": "XXXXXXXXX4321", "payPercentage": 100, "accountType": "checking", "status": "ready", "accountPriority": "Primary" } ], "userRemoteLocations": [], "companyLocationCategory": { "companyLocationCategory": "Office" }, "companyLocation": { "companyLocation": "Primary Residence", "companyLocationId": "746398E0-B335-47C6-BF78-D268D034594E", "Address1": "6875 Sand Lake Rd", "Address2": "", "City": "Orlando", "Country": "US", "State": "FL", "Zipcode": "32819" }, "stateCode": null, "W4Informations": [], "ssn": "974619053", "userRemoteLocation": null, "stateW4Informations": [], "timeOffRequests": [], "employeeGarnishments": [] } ] } ] }, "summary": "Employee is payroll ready" }, "inactive": { "value": { "trigger": { "eventId": "c68d4dc1-638a-4baa-9ccb-26a2520e38a2", "eventType": "employee.employeestatus.update", "eventTimeStamp": "01/08/2026 13:10:02" }, "payload": [ { "user": [ { "user": "Alex Morgan", "userId": "A12F45BC-9D31-4C9E-B28F-7F6E2C91D4A8", "userReferenceId": "", "companyId": "8E9F2B11-6A44-4D8C-B3A2-91F6D2E8C7A0", "status": { "userStatus": "Deactivate" }, "WorkerType": { "WorkerType": "W2" }, "firstName": "Alex", "lastName": "Morgan", "middleName": "", "phoneNumber": "5551234567", "kycStatus": "passed", "jobTitle": "Quality Analyst", "dateOfJoin": "2026-01-07", "email": "alex.morgan@example.com", "userWages": [ { "userWageId": "E4D92C17-1B55-4C3E-A9D8-2F5B9A1C7E44", "standardWorkingHours": 0, "WageRate": 85, "WageBasis": { "WageBasis": "Per Month" }, "paymentMethod": { "PaymentMethod": "Direct Deposit" }, "employeeRefTaxExempt": "No, this employee is not tax exempt", "employeeType": "Salary/Eligible for overtime", "differentialPay": null, "employmentStatus": "Full Time (30+ Hours per week)" } ], "bankAccounts": [ { "userPayAccountEntityId": "5B8E2D91-4C77-4F1A-9E3B-8D2A6C4F7E10", "bankName": "Chase", "accountName": "Alex Morgan Checking", "accountNumber": "XXXXXXXXX4321", "payPercentage": 100, "accountType": "checking", "status": "ready", "accountPriority": "Primary" } ], "userRemoteLocations": [], "companyLocationCategory": { "companyLocationCategory": "Office" }, "companyLocation": { "companyLocation": "Primary Residence", "companyLocationId": "746398E0-B335-47C6-BF78-D268D034594E", "Address1": "6875 Sand Lake Rd", "Address2": "", "City": "Orlando", "Country": "US", "State": "FL", "Zipcode": "32819" }, "stateCode": null, "W4Informations": [], "ssn": "974619053", "userRemoteLocation": null, "stateW4Informations": [], "timeOffRequests": [], "employeeGarnishments": [] } ] } ] }, "summary": "Employee temporarily deactivated" }, "terminated": { "value": { "trigger": { "eventId": "c68d4dc1-638a-4baa-9ccb-26a2520e38a2", "eventType": "employee.employeestatus.update", "eventTimeStamp": "01/08/2026 13:10:02" }, "payload": [ { "user": [ { "user": "Alex Morgan", "userId": "A12F45BC-9D31-4C9E-B28F-7F6E2C91D4A8", "userReferenceId": "", "companyId": "8E9F2B11-6A44-4D8C-B3A2-91F6D2E8C7A0", "status": { "userStatus": "Terminate" }, "WorkerType": { "WorkerType": "W2" }, "firstName": "Alex", "lastName": "Morgan", "middleName": "", "phoneNumber": "5551234567", "kycStatus": "passed", "jobTitle": "Quality Analyst", "dateOfJoin": "2026-01-07", "email": "alex.morgan@example.com", "userWages": [ { "userWageId": "E4D92C17-1B55-4C3E-A9D8-2F5B9A1C7E44", "standardWorkingHours": 0, "WageRate": 85, "WageBasis": { "WageBasis": "Per Month" }, "paymentMethod": { "PaymentMethod": "Direct Deposit" }, "employeeRefTaxExempt": "No, this employee is not tax exempt", "employeeType": "Salary/Eligible for overtime", "differentialPay": null, "employmentStatus": "Full Time (30+ Hours per week)" } ], "bankAccounts": [ { "userPayAccountEntityId": "5B8E2D91-4C77-4F1A-9E3B-8D2A6C4F7E10", "bankName": "Chase", "accountName": "Alex Morgan Checking", "accountNumber": "XXXXXXXXX4321", "payPercentage": 100, "accountType": "checking", "status": "ready", "accountPriority": "Primary" } ], "userRemoteLocations": [], "companyLocationCategory": { "companyLocationCategory": "Office" }, "companyLocation": { "companyLocation": "Primary Residence", "companyLocationId": "746398E0-B335-47C6-BF78-D268D034594E", "Address1": "6875 Sand Lake Rd", "Address2": "", "City": "Orlando", "Country": "US", "State": "FL", "Zipcode": "32819" }, "stateCode": null, "W4Informations": [], "ssn": "974619053", "userRemoteLocation": null, "stateW4Informations": [], "timeOffRequests": [], "employeeGarnishments": [] } ] } ] }, "summary": "Employee terminated" } } } }, "required": true }, "responses": { "200": { "description": "Employee status event accepted successfully.", "headers": {} } }, "security": [] } } }, "components": { "schemas": {}, "responses": {}, "securitySchemes": {} }, "servers": [], "security": [] }