@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Paylocity API
@base https://api.paylocity.com/api
@version 2
@auth OAuth2
@common_fields {companyId: any # Company Id}
@endpoints 32
@hint download_for_search
@toc companies(30), credentials(1), weblinkstaging(1)

@group companies
@endpoint PUT /v2/companies/{companyId}/employees/{employeeId}/additionalRates
@desc Add/update additional rates
@required {json: map # Additional Rate Model, employeeId: any # Employee Id}
@returns(200) Successfully added or updated
@errors {400: Bad Request, 401: Unauthorized, 403: Forbidden, 429: Too Many Requests, 500: Internal Server Error}

@endgroup

@group credentials
@endpoint POST /v2/credentials/secrets
@desc Obtain new client secret.
@required {json: map # Add Client Secret Model}
@returns(200) Successfully added
@errors {400: Bad Request, 401: Unauthorized, 403: Forbidden, 429: Too Many Requests, 500: Internal Server Error}

@endgroup

@group companies
@endpoint GET /v2/companies/{companyId}/codes/{codeResource}
@desc Get All Company Codes
@required {codeResource: any # Type of Company Code. Common values costcenter1, costcenter2, costcenter3, deductions, earnings, taxes, paygrade, positions.}
@returns(200) Successfully retrieved
@errors {401: Unauthorized, 403: Forbidden, 404: Invalid Code Resource, 429: Too Many Requests, 500: Internal Server Error}

@endpoint GET /v2/companies/{companyId}/openapi
@desc Get Company-Specific Open API Documentation
@required {Authorization: any # Bearer + JWT}
@returns(200) Successfully retrieved
@errors {400: Bad Request, 403: Forbidden, 429: Too Many Requests, 500: Internal Server Error}

@endpoint GET /v2/companies/{companyId}/customfields/{category}
@desc Get All Custom Fields
@required {category: any # Custom Fields Category}
@returns(200) Successfully retrieved
@errors {401: Unauthorized, 403: Forbidden, 404: Invalid Category, 429: Too Many Requests, 500: Internal Server Error}

@endpoint GET /v2/companies/{companyId}/employees/{employeeId}/directDeposit
@desc Get All Direct Deposit
@required {employeeId: any # Employee Id}
@returns(200) Successfully Retrieved
@errors {401: Unauthorized, 403: Forbidden, 404: The employee, or direct deposit does not exist, 429: Too Many Requests, 500: Internal Server Error}

@endpoint PUT /v2/companies/{companyId}/employees/{employeeId}/earnings
@desc Add/Update Earning
@required {json: map # Earning Model, employeeId: any # Employee Id}
@returns(200) Successfully added or updated
@errors {400: Bad Request, 401: Unauthorized, 403: Forbidden, 429: Too Many Requests, 500: Internal Server Error}

@endpoint GET /v2/companies/{companyId}/employees/{employeeId}/earnings
@desc Get All Earnings
@required {employeeId: any # Employee Id}
@returns(200) Successfully retrieved
@errors {401: Unauthorized, 403: Forbidden, 404: The employee does not exist, 429: Too Many Requests, 500: Internal Server Error}

@endpoint DELETE /v2/companies/{companyId}/employees/{employeeId}/earnings/{earningCode}/{startDate}
@desc Delete Earning by Earning Code and Start Date
@required {employeeId: any # Employee Id, earningCode: any # Earning Code, startDate: any # Start Date}
@returns(204) Successfully deleted
@errors {400: Bad Request, 401: Unauthorized, 403: Forbidden, 404: The employee does not exist, or the specified earningCode-startDate combination does not exist, 429: Too Many Requests, 500: Internal Server Error}

@endpoint GET /v2/companies/{companyId}/employees/{employeeId}/earnings/{earningCode}/{startDate}
@desc Get Earning by Earning Code and Start Date
@required {employeeId: any # Employee Id, earningCode: any # Earning Code, startDate: any # Start Date}
@returns(200) Successfully retrieved
@errors {401: Unauthorized, 403: Forbidden, 404: The employee does not exist, or the specified earningCode-startDate combination does not exist, 429: Too Many Requests, 500: Internal Server Error}

@endpoint GET /v2/companies/{companyId}/employees/{employeeId}/earnings/{earningCode}
@desc Get Earnings by Earning Code
@required {employeeId: any # Employee Id, earningCode: any # Earning Code}
@returns(200) Successfully retrieved
@errors {401: Unauthorized, 403: Forbidden, 404: The employee does not exist, 429: Too Many Requests, 500: Internal Server Error}

@endpoint PUT /v2/companies/{companyId}/employees/{employeeId}/emergencyContacts
@desc Add/update emergency contacts
@required {json: map # Emergency Contact Model, employeeId: any # Employee Id}
@returns(200) Successfully added or updated
@errors {400: Bad Request, 401: Unauthorized, 403: Forbidden, 429: Too Many Requests, 500: Internal Server Error}

@endpoint PUT /v2/companies/{companyId}/employees/{employeeId}/benefitSetup
@desc Add/update employee's benefit setup
@required {json: map # BenefitSetup Model, employeeId: any # Employee Id}
@returns(200) Successfully added or updated
@errors {400: Bad Request, 401: Unauthorized, 403: Forbidden, 429: Too Many Requests, 500: Internal Server Error}

@endgroup

@group weblinkstaging
@endpoint POST /v2/weblinkstaging/companies/{companyId}/employees/newemployees
@desc Add new employee to Web Link
@required {json: map # StagedEmployee Model}
@returns(201) Successfully Added
@errors {400: Bad Request, 403: Forbidden, 429: Too Many Requests, 500: Internal Server Error}

@endgroup

@group companies
@endpoint POST /v2/companies/{companyId}/employees
@desc Add new employee
@required {json: map # Employee Model}
@returns(201) Successfully added
@errors {400: Bad Request, 401: Unauthorized, 403: Forbidden, 429: Too Many Requests, 500: Internal Server Error}

@endpoint GET /v2/companies/{companyId}/employees/
@desc Get all employees
@optional {pagesize: any # Number of records per page. Default value is 25., pagenumber: any # Page number to retrieve; page numbers are 0-based (so to get the first page of results, pass pagenumber=0). Default value is 0., includetotalcount: any # Whether to include the total record count in the header's X-Pcty-Total-Count property. Default value is true.}
@returns(200) Successfully Retrieved
@errors {401: Unauthorized, 403: Forbidden, 404: The company does not exist, 429: Too Many Requests, 500: Internal Server Error}

@endpoint GET /v2/companies/{companyId}/employees/{employeeId}
@desc Get employee
@required {employeeId: any # Employee Id}
@returns(200) Successfully Retrieved
@errors {401: Unauthorized, 403: Forbidden, 404: The employee does not exist, 429: Too Many Requests, 500: Internal Server Error}

@endpoint PATCH /v2/companies/{companyId}/employees/{employeeId}
@desc Update employee
@required {json: map # Employee Model, employeeId: any # Employee Id}
@returns(200) Successfully Updated
@errors {400: Bad Request, 401: Unauthorized, 403: Forbidden, 429: Too Many Requests, 500: Internal Server Error}

@endpoint POST /v2/companies/{companyId}/employees/{employeeId}/localTaxes
@desc Add new local tax
@required {json: map # LocalTax Model, employeeId: any # Employee Id}
@returns(201) Successfully added
@errors {400: Bad Request, 401: Unauthorized, 403: Forbidden, 429: Too Many Requests, 500: Internal Server Error}

@endpoint GET /v2/companies/{companyId}/employees/{employeeId}/localTaxes
@desc Get all local taxes
@required {employeeId: any # Employee Id}
@returns(200) Successfully retrieved
@errors {401: Unauthorized, 403: Forbidden, 404: The employee does not exist, 429: Too Many Requests, 500: Internal Server Error}

@endpoint DELETE /v2/companies/{companyId}/employees/{employeeId}/localTaxes/{taxCode}
@desc Delete local tax by tax code
@required {employeeId: any # Employee Id, taxCode: any # Tax Code}
@returns(204) Successfully deleted
@errors {400: Bad Request, 401: Unauthorized, 403: Forbidden, 404: The employee does not exist, or the specified tax code does not exist, 429: Too Many Requests, 500: Internal Server Error}

@endpoint GET /v2/companies/{companyId}/employees/{employeeId}/localTaxes/{taxCode}
@desc Get local taxes by tax code
@required {employeeId: any # Employee Id, taxCode: any # Tax Code}
@returns(200) Successfully retrieved
@errors {401: Unauthorized, 403: Forbidden, 404: The employee does not exist, or the specified tax code does not exist, 429: Too Many Requests, 500: Internal Server Error}

@endpoint PUT /v2/companies/{companyId}/employees/{employeeId}/nonprimaryStateTax
@desc Add/update non-primary state tax
@required {json: map # Non-Primary State Tax Model, employeeId: any # Employee Id}
@returns(200) Successfully added or updated
@errors {400: Bad Request, 401: Unauthorized, 403: Forbidden, 429: Too Many Requests, 500: Internal Server Error}

@endpoint POST /v2/companies/{companyId}/employeePayRateSearches
@desc Searches for pay rates for the specified company.
@required {searchModel: map # PayRateSearchesRequestModelV2}
@returns(200) Successfully Retrieved
@errors {400: Bad Request, 401: Unauthorized, 403: Forbidden, 429: Too Many Requests, 500: Internal Server Error}

@endpoint GET /v2/companies/{companyId}/employees/{employeeId}/paystatement/details/{year}/{checkDate}
@desc Get employee pay statement details data for the specified year and check date.
@required {employeeId: any # Employee Id, year: any # The year for which to retrieve pay statement data, checkDate: any # The check date for which to retrieve pay statement data}
@optional {pagesize: any # Number of records per page. Default value is 25., pagenumber: any # Page number to retrieve; page numbers are 0-based (so to get the first page of results, pass pagenumber=0). Default value is 0., includetotalcount: any # Whether to include the total record count in the header's X-Pcty-Total-Count property. Default value is true., codegroup: any # Retrieve pay statement details related to specific deduction, earning or tax types. Common values include 401k, Memo, Reg, OT, Cash Tips, FED and SITW.}
@returns(200) Successfully Retrieved
@errors {401: Unauthorized, 403: Forbidden, 404: The employee, specified year, or check date does not exist, 429: Too Many Requests, 500: Internal Server Error}

@endpoint GET /v2/companies/{companyId}/employees/{employeeId}/paystatement/details/{year}
@desc Get employee pay statement details data for the specified year.
@required {employeeId: any # Employee Id, year: any # The year for which to retrieve pay statement data}
@optional {pagesize: any # Number of records per page. Default value is 25., pagenumber: any # Page number to retrieve; page numbers are 0-based (so to get the first page of results, pass pagenumber=0). Default value is 0., includetotalcount: any # Whether to include the total record count in the header's X-Pcty-Total-Count property. Default value is true., codegroup: any # Retrieve pay statement details related to specific deduction, earning or tax types. Common values include 401k, Memo, Reg, OT, Cash Tips, FED and SITW.}
@returns(200) Successfully Retrieved
@errors {401: Unauthorized, 403: Forbidden, 404: The employee, specified year, or check date does not exist, 429: Too Many Requests, 500: Internal Server Error}

@endpoint GET /v2/companies/{companyId}/employees/{employeeId}/paystatement/summary/{year}/{checkDate}
@desc Get employee pay statement summary data for the specified year and check date.
@required {employeeId: any # Employee Id, year: any # The year for which to retrieve pay statement data, checkDate: any # The check date for which to retrieve pay statement data}
@optional {pagesize: any # Number of records per page. Default value is 25., pagenumber: any # Page number to retrieve; page numbers are 0-based (so to get the first page of results, pass pagenumber=0). Default value is 0., includetotalcount: any # Whether to include the total record count in the header's X-Pcty-Total-Count property. Default value is true., codegroup: any # Retrieve pay statement details related to specific deduction, earning or tax types. Common values include 401k, Memo, Reg, OT, Cash Tips, FED and SITW.}
@returns(200) Successfully Retrieved
@errors {401: Unauthorized, 403: Forbidden, 404: The employee, specified year, or check date does not exist, 429: Too Many Requests, 500: Internal Server Error}

@endpoint GET /v2/companies/{companyId}/employees/{employeeId}/paystatement/summary/{year}
@desc Get employee pay statement summary data for the specified year.
@required {employeeId: any # Employee Id, year: any # The year for which to retrieve pay statement data}
@optional {pagesize: any # Number of records per page. Default value is 25., pagenumber: any # Page number to retrieve; page numbers are 0-based (so to get the first page of results, pass pagenumber=0). Default value is 0., includetotalcount: any # Whether to include the total record count in the header's X-Pcty-Total-Count property. Default value is true., codegroup: any # Retrieve pay statement details related to specific deduction, earning or tax types. Common values include 401k, Memo, Reg, OT, Cash Tips, FED and SITW.}
@returns(200) Successfully Retrieved
@errors {401: Unauthorized, 403: Forbidden, 404: The employee, specified year, or check date does not exist, 429: Too Many Requests, 500: Internal Server Error}

@endpoint PUT /v2/companies/{companyId}/employees/{employeeId}/primaryStateTax
@desc Add/update primary state tax
@required {json: map # Primary State Tax Model, employeeId: any # Employee Id}
@returns(200) Successfully added or updated
@errors {400: Bad Request, 401: Unauthorized, 403: Forbidden, 429: Too Many Requests, 500: Internal Server Error}

@endpoint PUT /v2/companies/{companyId}/employees/{employeeId}/sensitivedata
@desc Add/update sensitive data
@required {json: map # Sensitive Data Model, employeeId: any # Employee Id}
@returns(200) Successfully added or updated
@errors {400: Bad Request, 401: Unauthorized, 403: Forbidden, 429: Too Many Requests, 500: Internal Server Error}

@endpoint GET /v2/companies/{companyId}/employees/{employeeId}/sensitivedata
@desc Get sensitive data
@required {employeeId: any # Employee Id}
@returns(200) Successfully Retrieved
@errors {400: Bad Request, 401: Unauthorized, 403: Forbidden, 429: Too Many Requests, 500: Internal Server Error}

@endpoint POST /v2/companies/{companyId}/employeeStatusSearches
@desc Searches for employee statuses for the specified company.
@required {request: map # StatusSearchesV2Request Model}
@returns(200) Successfully Retrieved
@errors {400: Bad Request, 401: Unauthorized, 403: Forbidden, 404: The employee does not exist, 429: Too Many Requests, 500: Internal Server Error}

@endgroup

@end