Paylocity

Paylocity API

For general questions and support of the API, contact: webservices@paylocity.com Overview Paylocity Web Services API is an externally facing RESTful Internet…

Finance & banking#openapi#financial

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

For general questions and support of the API, contact: webservices@paylocity.com

Overview

Paylocity Web Services API is an externally facing RESTful Internet protocol. The Paylocity API uses HTTP verbs and a RESTful endpoint structure. OAuth 2.0 is used as the API Authorization framework. Request and response payloads are formatted as JSON.
Paylocity supports v1 and v2 versions of its API endpoints. v1, while supported, won't be enhanced with additional functionality. For direct link to v1 documentation, please click here. For additional resources regarding v1/v2 differences and conversion path, please contact webservices@paylocity.com.

Setup

Paylocity will provide the secure client credentials and set up the scope (type of requests and allowed company numbers). You will receive the unique client id, secret, and Paylocity public key for the data encryption. The secret will expire in 365 days.

  • Paylocity will send you an e-mail 10 days prior to the expiration date for the current secret. If not renewed, the second e-mail notification will be sent 5 days prior to secret's expiration. Each email will contain the code necessary to renew the client secret.
  • You can obtain the new secret by calling API endpoint using your current not yet expired credentials and the code that was sent with the notification email. For details on API endpoint, please see Client Credentials section.
  • Both the current secret value and the new secret value will be recognized during the transition period. After the current secret expires, you must use the new secret.
  • If you were unable to renew the secret via API endpoint, you can still contact Service and they will email you new secret via secure email.

When validating the request, Paylocity API will honor the defaults and required fields set up for the company default New Hire Template as defined in Web Pay.

Authorization

Paylocity Web Services API uses OAuth2.0 Authentication with JSON Message Format.

All requests of the Paylocity Web Services API require a bearer token which can be obtained by authenticating the client with the Paylocity Web Services API via OAuth 2.0.

The client must request a bearer token from the authorization endpoint:

auth-server for production: https://api.paylocity.com/IdentityServer/connect/token

auth-server for testing: https://apisandbox.paylocity.com/IdentityServer/connect/token

Paylocity reserves the right to impose rate limits on the number of calls made to our APIs. Changes to API features/functionality may be made at anytime with or without prior notice.

Authorization Header

The request is expected to be in the form of a basic authentication request, with the "Authorization" header containing the client-id and client-secret. This means the standard base-64 encoded user:password, prefixed with "Basic" as the value for the Authorization header, where user is the client-id and password is the client-secret.

Content-Type Header

The "Content-Type" header is required to be "application/x-www-form-urlencoded".

Additional Values

The request must post the following form encoded values within the request body:

grant_type = client_credentials
scope = WebLinkAPI

Responses

Success will return HTTP 200 OK with JSON content:

{
"access_token": "xxx",
"expires_in": 3600,
"token_type": "Bearer"
}

Encryption

Paylocity uses a combination of RSA and AES cryptography. As part of the setup, each client is issued a public RSA key.

Paylocity recommends the encryption of the incoming requests as additional protection of the sensitive data. Clients can opt-out of the encryption during the initial setup process. Opt-out will allow Paylocity to process unencrypted requests.

The Paylocity Public Key has the following properties:

  • 2048 bit key size
  • PKCS1 key format
  • PEM encoding

Properties

  • key (base 64 encoded): The AES symmetric key encrypted with the Paylocity Public Key. It is the key used to encrypt the content. Paylocity will decrypt the AES key using RSA decryption and use it to decrypt the content.
  • iv (base 64 encoded): The AES IV (Initialization Vector) used when encrypting the content.
  • content (base 64 encoded): The AES encrypted request. The key and iv provided in the secureContent request are used by Paylocity for decryption of the content.

We suggest using the following for the AES:

  • CBC cipher mode
  • PKCS7 padding
  • 128 bit block size
  • 256 bit key size

Encryption Flow

  • Generate the unencrypted JSON payload to POST/PUT
  • Encrypt this JSON payload using your _own key and IV_ (NOT with the Paylocity public key)
  • RSA encrypt the _key_ you used in step 2 with the Paylocity Public Key, then, base64 encode the result
  • Base64 encode the IV used to encrypt the JSON payload in step 2
  • Put together a "securecontent" JSON object:

{
…

Endpoints 30

Company Codes

  • GETGet All Company Codes/v2/companies/:companyId/codes/:codeResourceGet All Company Codes for the selected company and resource

Custom Fields

  • GETGet All Custom Fields/v2/companies/:companyId/customfields/:categoryGet All Custom Fields for the selected company

Employee

  • POSTAdd new employee/v2/companies/:companyId/employeesNew Employee API sends new employee data directly to Web Pay. Companies who use the New Hire Template in Web Pay may require additional fields when hiring…
  • GETGet all employees/v2/companies/:companyId/employees/?pagesize=0&pagenumber=0&includetotalcount=trueGet All Employees API will return employee data currently available in Web Pay.
  • GETGet employee/v2/companies/:companyId/employees/:employeeIdGet Employee API will return employee data currently available in Web Pay.
  • PATCHUpdate employee/v2/companies/:companyId/employees/:employeeIdUpdate Employee API will update existing employee data in WebPay.

Additional Rates

  • PUTAdd/update additional rates/v2/companies/:companyId/employees/:employeeId/additionalRatesSends new or updated employee additional rates information directly to Web Pay.

Employee Benefit Setup

  • PUTAdd/update employee's benefit setup/v2/companies/:companyId/employees/:employeeId/benefitSetupSends new or updated employee benefit setup information directly to Web Pay.

Direct Deposit

  • GETGet All Direct Deposit/v2/companies/:companyId/employees/:employeeId/directDepositGet All Direct Deposit returns main direct deposit and all additional direct depositsfor the selected employee.

Earnings

  • GETGet All Earnings/v2/companies/:companyId/employees/:employeeId/earningsGet All Earnings returns all earnings for the selected employee.
  • PUTAdd/Update Earning/v2/companies/:companyId/employees/:employeeId/earningsAdd/Update Earning API sends new or updated employee earnings information directly to Web Pay.
  • GETGet Earnings by Earning Code/v2/companies/:companyId/employees/:employeeId/earnings/:earningCodeGet Earnings returns all earnings with the provided earning code for the selected employee.
  • GETGet Earning by Earning Code and Start Date/v2/companies/:companyId/employees/:employeeId/earnings/:earningCode/:startDateGet Earnings returns the single earning with the provided earning code and start date for the selected employee.
  • DELETEDelete Earning by Earning Code and Start Date/v2/companies/:companyId/employees/:employeeId/earnings/:earningCode/:startDateDelete Earning by Earning Code and Start Date

Emergency Contacts

  • PUTAdd/update emergency contacts/v2/companies/:companyId/employees/:employeeId/emergencyContactsSends new or updated employee emergency contacts directly to Web Pay.

Local Taxes

  • GETGet all local taxes/v2/companies/:companyId/employees/:employeeId/localTaxesReturns all local taxes for the selected employee.
  • POSTAdd new local tax/v2/companies/:companyId/employees/:employeeId/localTaxesSends new employee local tax information directly to Web Pay.
  • GETGet local taxes by tax code/v2/companies/:companyId/employees/:employeeId/localTaxes/:taxCodeReturns all local taxes with the provided tax code for the selected employee.
  • DELETEDelete local tax by tax code/v2/companies/:companyId/employees/:employeeId/localTaxes/:taxCodeDelete local tax by tax code

Non-Primary State Tax

  • PUTAdd/update non-primary state tax/v2/companies/:companyId/employees/:employeeId/nonprimaryStateTaxSends new or updated employee non-primary state tax information directly to Web Pay.

PayStatements

  • GETGet employee pay statement details data for the specified year./v2/companies/:companyId/employees/:employeeId/paystatement/details/:year?pagesize=0&pagenumber=0&includetotalcount=true&codegroup=stringGet pay statement details API will return employee pay statement details data currently available in Web Pay for the specified year.
  • GETGet employee pay statement details data for the specified year and check date./v2/companies/:companyId/employees/:employeeId/paystatement/details/:year/:checkDate?pagesize=0&pagenumber=0&includetotalcount=true&codegroup=stringGet pay statement details API will return employee pay statement detail data currently available in Web Pay for the specified year and check date.
  • GETGet employee pay statement summary data for the specified year./v2/companies/:companyId/employees/:employeeId/paystatement/summary/:year?pagesize=0&pagenumber=0&includetotalcount=true&codegroup=stringGet pay statement summary API will return employee pay statement summary data currently available in Web Pay for the specified year.
  • GETGet employee pay statement summary data for the specified year and check date./v2/companies/:companyId/employees/:employeeId/paystatement/summary/:year/:checkDate?pagesize=0&pagenumber=0&includetotalcount=true&codegroup=stringGet pay statement summary API will return employee pay statement summary data currently available in Web Pay for the specified year and check date.

Primary State Tax

  • PUTAdd/update primary state tax/v2/companies/:companyId/employees/:employeeId/primaryStateTaxSends new or updated employee primary state tax information directly to Web Pay.

Sensitive Data

  • GETGet sensitive data/v2/companies/:companyId/employees/:employeeId/sensitivedataGets employee sensitive data information directly from Web Pay.
  • PUTAdd/update sensitive data/v2/companies/:companyId/employees/:employeeId/sensitivedataSends new or updated employee sensitive data information directly to Web Pay.

Company-Specific Schema

  • GETGet Company-Specific Open API Documentation/v2/companies/:companyId/openapiThe company-specific Open API endpoint allows the client to GET an Open API document for the Paylocity API that is customized with company-specific resource…

Client Credentials

  • POSTObtain new client secret./v2/credentials/secretsObtain new client secret for Paylocity-issued client id. See Setup section for details.

Employee Staging

  • POSTAdd new employee to Web Link/v2/weblinkstaging/companies/:companyId/employees/newemployeesAdd new employee to Web Link will send partially completed or potentially erroneous new hire record to Web Link, where it can be corrected and competed by…

API details

Base URL
https://api.paylocity.com/api
Authentication
OAuth 2.0 (client credentials flow) with 1 scope
Operations
30 operations on 24 pathsGET 16PUT 7POST 4DELETE 2PATCH 1
Main resources
Earnings 5Employee 4Local Taxes 4PayStatements 4Sensitive Data 2Additional Rates 1Client Credentials 1Company Codes 1Company-Specific Schema 1Custom Fields 1
Response formats
application/json
Description format
OpenAPI 3.0.0, API version 2
Listed from
APIs.guru OpenAPI Directory (CC0-1.0)
Source updated

How to test the Paylocity API in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Paylocity API collection, without the publisher's secrets.
  3. Add your credentialsThis API uses OAuth 2.0 (client credentials flow) with 1 scope. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “Get All Company Codes” (GET /v2/companies/:companyId/codes/:codeResource), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Paylocity API?

For general questions and support of the API, contact: webservices@paylocity.com Overview Paylocity Web Services API is an externally facing RESTful Internet… It is listed under Finance & banking and has 30 endpoints.

Who publishes the Paylocity API?

It is listed from Paylocity's public API description (an OpenAPI document), not published by Paylocity on Swastik Codes. Anyone who controls paylocity.com can claim the profile by adding a DNS TXT record.

What is the base URL of the Paylocity API?

Requests go to https://api.paylocity.com/api. Endpoint paths are added to this base URL.

How do I authenticate with the Paylocity API?

With OAuth 2.0 (client credentials flow) with 1 scope.

How many endpoints does the Paylocity API have?

30 operations on 24 paths (16 GET, 7 PUT, 4 POST, 2 DELETE, 1 PATCH). The largest groups are Earnings, Employee, Local Taxes, PayStatements.

Is forking the Paylocity API free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.