Product that suits modern B2B Tech companies

BACK

Paylocity API architecture: authentication and data access

Platform APIs

October 1, 2024

Summarise the blog with AI

Key takeaways

Use these distinctions to define your implementation contract:

Paylocity authentication uses a bearer token, but approved data access is a separate requirement.
API family and environment determine which documented token-request contract you should implement.
Employee retrieval requires a named endpoint contract, with its own identity, completeness, pagination and record-selection rules.
Webhooks tell you which record to re-read, and future-dated changes only fire once they take effect.
Version maintenance belongs in the implementation contract, with an inventory, warning review and migration owner.
A unified API changes who runs the work, not what Paylocity has approved you to read.

A working Paylocity token proves less than it looks like. The rates domain can still come back masked. The employee list returns IDs and status codes, not profiles. A pay raise entered today will not fire a webhook until payroll moves the company onto the check date it takes effect.

Paylocity sends bearer tokens in the HTTP Authorization header. Its Integration Requirements then test two further things: that the credentials reach each endpoint you requested, and that the customer signed off on the access level to their company data. Plan for three separate acceptance tests.

This guide follows the order you will hit them: pick the API family and environment, run the token lifecycle, prove approved access, define employee retrieval, design sync around webhooks and polling, and own version retirement. It is for engineers at HR, payroll and benefits platforms building customer-authorized access.

Select the API-family and environment contract

Your Paylocity token configuration must match the API family and environment provisioned for the integration. Do not combine a token URL from one family with request assumptions from another.

Paylocity's Authentication and WebLink Authentication references both document form-encoded client-credentials requests, but they specify different token endpoints. Record the full configuration instead of using a setting labeled only "Paylocity."

Use this matrix to identify the applicable documented contract:

API family	Environment	Documented token endpoint	Documented token-request parameters	Boundary against transferring another family's assumptions
General platform	Testing	`https://dc1demogwext.paylocity.com/public/security/v1/token`	Form-encoded client-credentials request; the general example contains no `scope` parameter	Absence from the example does not establish that scopes can never apply
General platform	Production	`https://dc1prodgwext.paylocity.com/public/security/v1/token`	Form-encoded client-credentials request; the general example contains no `scope` parameter	Confirm the provisioned production contract rather than copying WebLink parameters
WebLink	Testing	`https://dc1demogw.paylocity.com/IdentityServer/connect/token`	`client_id`, `client_secret`, `grant_type=client_credentials`, `scope=WebLinkAPI`	These are WebLink's documented parameters, not universal Paylocity requirements
WebLink	Production	`https://api.paylocity.com/IdentityServer/connect/token`	`client_id`, `client_secret`, `grant_type=client_credentials`, `scope=WebLinkAPI`	Keep production credentials and destinations separate from testing

In particular, scope=WebLinkAPI belongs to Paylocity's documented WebLink token request. Keep it out of requests to the general platform's token endpoint.

The two documented testing requests side by side:

Request

# General platform, testing
curl -X POST "https://dc1demogwext.paylocity.com/public/security/v1/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "client_id=" \
  --data-urlencode "client_secret=" \
  --data-urlencode "grant_type=client_credentials"

# WebLink, testing: different host, and scope is required
curl -X POST "https://dc1demogw.paylocity.com/IdentityServer/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "client_id=" \
  --data-urlencode "client_secret=" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "scope=WebLinkAPI"

Both return the same shape:

JSON

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

How those credentials get issued in the first place is covered in Paylocity API access and credential provisioning.

When turning a Paylocity API Overview into implementation requirements, distinguish the module you need from the authentication configuration you received. Record the family, environment, token endpoint, documented request parameters and intended API destination in your configuration.

Use that record to define the boundaries for credential storage and token reuse. Keep the same distinctions in the token cache rather than treating all Paylocity tokens alike.

Operate credentials and tokens as a lifecycle

Your service needs protected credentials, configuration-specific token caching, expiry-aware renewal and an assigned rotation owner. Paylocity documents some of those requirements; the storage and isolation design remains your application's responsibility.

Both Paylocity authentication references instruct callers to use TLS 1.2. They document a bearer-token lifetime of 3,600 seconds, renewal through another request to the token endpoint, and secret rotation every 365 days.

Work through the following sequence when defining the operational design:

Store the selected configuration: keep credentials in protected server-side storage with the family, environment and intended API destination recorded alongside them. Treat storage protection as application design, not a Paylocity storage feature.
Isolate cached tokens: key token reuse by the relevant credential, family and environment configuration. Do not reuse a token merely because another request also targets a Paylocity host.
Track expiration and renew: make another token request through the selected authentication contract when renewal is required. Do not substitute an undocumented refresh-token flow or prescribe an unsupported renewal margin.
Assign secret rotation: name the owner of the documented rotation requirement and specify how configuration changes will be validated. Do not assume an undocumented overlap period between old and new secrets.
Investigate authentication failures: compare the failing request with its recorded credential, family, environment, destination and token-expiration state. Keep this investigation separate from endpoint and company-data authorization tests.

The token-isolation recommendation also follows general OAuth security guidance. RFC 9700, published in January 2025, recommends audience-restricted access tokens and requires resource servers to refuse tokens intended for a different resource server.

That standard does not establish a Paylocity-specific audience parameter, token format or JWT-decoding requirement. Keep token configurations and destinations isolated to apply the architectural principle. Implement only the parameters documented for your provisioned contract.

A successful renewal test proves that your token lifecycle works. It still leaves the business-data access tests to be completed.

Verify provisioning and approved data access

Your access specification should distinguish project approval, endpoint access, company and record access, domain access, and module eligibility. These boundaries answer different questions and need different evidence.

Paylocity's Integration Requirements describe a customer company administrator submitting the integration project request through the customer's Paylocity account executive. Its Getting Started guidance says Paylocity provides OAuth credentials and sandbox access after reviewing and approving the access request, and requires sandbox testing before submission for review.

For each requested operation, collect approval evidence and define the corresponding acceptance test:

Required data or operation	Relevant access boundary	Evidence the implementation owner must collect	Acceptance test
Integration setup	Project approval and credential provisioning	Approved request, credential configuration and provided sandbox	Validate the integration in the provided sandbox before submission for review
Required endpoint calls	Endpoint authorization	Confirmation of the requested endpoint access	Exercise each required operation with the provisioned credentials
Customer company and employee records	Company and record authorization	Approved companies and authorized test fixtures	Retrieve permitted records and test unauthorized access only with authorized fixtures and environments
Employee demographic domains	Domain-specific resources and request configuration	Granted resources and expected omission or masking behavior	Check required domains and distinguish restricted responses from usable data
LMS operations	Module eligibility and operation access	Signed Paylocity technology partnership agreement and approved operations	Test the permitted content, metadata, usage, assignment or completion operations
Company-level job codes	Operation-specific access	Confirmation of the required job-code operations	Test the approved create, retrieve, update or delete operations

Test record access separately. OWASP API1:2023 explains that object-level authorization must check whether the caller may perform the requested action on the requested record. Access to an endpoint is not sufficient evidence of authorization for every record addressable through it.

Paylocity's Employee Demographics API v2 Overview identifies three distinct security resources: EmployeeDemographicv2ThirdPartyInfo, EmployeeDemographicv2ThirdPartyRates and EmployeeDemographicv2ThirdPartySensitive. Restricted domains may be omitted or masked according to granted access and request configuration. These names are security resources, not OAuth scope strings.

Suppose your benefits product requires pay-rate data. A returned employee identifier does not answer whether the rates domain is authorized or whether the requested response includes it. Specify the expected domain behavior before treating a response as complete.

Module capability and eligibility are also separate. Paylocity's LMS API supports adding training content and retrieving content metadata, usage, assignment and completion information, but its overview restricts endpoints to LMS providers with a signed Paylocity technology partnership agreement. Paylocity's Job Code API separately supports creating, retrieving, updating and deleting company-level job codes.

Document per-customer employee field requirements alongside these approval tests. That field specification does not grant permissions; it tells you which permissions and response behaviors the implementation must verify.

Define the employee retrieval contract

Employee retrieval must be specified against a named endpoint, not a generic "employees" resource. Similar route names do not establish equivalent response shapes, pagination or availability.

Paylocity defines companyId as a specific payroll entity. Its WebLink employee reference states that employeeId is unique per company ID, so do not treat that identifier as globally unique.

For application storage, preserve the company-and-employee pair within your customer-isolation boundary. If two authorized payroll entities use the same employee identifier, the storage key must still distinguish their records.

Compare the contracts in Paylocity's named employee references:

Named endpoint and route	Response purpose or completeness	Pagination contract	Availability or test boundary	Implementation consequence
WebLink Get All Employees: `/api/v2/companies/{companyId}/employees`	Listing returns `employeeId`, `statusCode` and `statusTypeCode`; it is not the individual detail response	`pagesize` defaults to 25; `pagenumber` is zero-based; `includetotalcount` defaults to true	Validate the listing under the provisioned company and endpoint access	Use it for employee enumeration; do not infer a complete profile from the listing
WebLink Get Employee: `/api/v2/companies/{companyId}/employees/{employeeId}`	Individual employee detail retrieval	Do not transfer listing pagination to individual retrieval	Validate the required detail fields under approved access	Give detail retrieval a separate response-completeness test
EA Get Employee [Batch]: `/apiHub/coreHR/v2/companies/{companyId}/employees`	Compared batch employee response; define required fields against this contract	`limit` defaults to 20 and has a maximum of 20; `offset` defaults to zero; `includeTotalCount=true` requests matching total count	Reference labels this version beta/EA, limits it to approved adopters and requires explicit authorization for production use; `testMode=true` produces mocked, randomly generated responses	Keep its pagination, availability and test behavior separate from WebLink

The EA/beta label above belongs to the compared batch endpoint. It is not a statement that every endpoint on a newer Paylocity platform is beta.

Give pagination its own acceptance test. The WebLink listing uses a zero-based page number; the compared EA batch endpoint uses an offset and limit. Even the total-count parameter names differ in capitalization, so configuration should preserve the exact names rather than normalize them into one provider request.

Paylocity's EA batch reference describes testMode=true as producing mocked, randomly generated responses. Those results can exercise your application's test handling, but they do not establish production authorization or production data completeness.

Select effective records intentionally

Paylocity's Employee Demographics API v2 Overview describes temporal records for pay, status and position. Your mapping must select the applicable effective record rather than assume the first array element is current.

Imagine a position array containing a current assignment and a planned future move. Selecting the first element simply because it is first makes array order your business rule. Instead, document the relevant business date and the endpoint/version-specific record-selection rules.

Do not replace that work with a universal "latest timestamp wins" algorithm. Paylocity documents the need for intentional selection, not one rule for every temporal field.

Future-dated records also change when you hear about them. In Paylocity's own example, pay rates entered on March 6 for the March 24 check date trigger webhooks only after the March 17 payroll is processed and March 24 becomes the current check date. If your benefits product prices coverage off salary, a raise can sit in the temporal records for two weeks before any notification arrives.

Before accepting the retrieval specification as complete, check that it identifies the endpoint, approved company, employee identity, required fields, pagination, effective-record rules and evidence from the appropriate environment.

Design synchronization around authoritative reads

Treat Paylocity notifications as inputs to a synchronization workflow, not as a universal replacement for retrieving current state. Rate policy and webhook behavior must remain attached to the relevant API family or event.

Paylocity's WebLink rate policy permits up to 25 calls per second and returns HTTP 429 when that limit is exceeded. Do not transfer that numeric policy or an assumed quota partitioning to other Paylocity API families.

Use this behavior matrix to define the consumer's obligations:

Policy or event	Documented behavior	What it does not establish	Consumer responsibility
WebLink rate limits	Up to 25 calls per second; excess calls return HTTP 429. Paylocity recommends exponential backoff with jitter, a cap on repeated retries, caching, and spreading traffic evenly. It advises against token-bucket or other burst-allowing limiters	A universal Paylocity rate limit; other API families set their own per-endpoint limits	Use a leaky-bucket style limiter, bound retries, and observe both limits if you call WebLink and newer APIs
Employee Change Webhooks	Fires on a published list of fields (name, SSN, status, hire and term dates, cost centers, pay type, base rate, salary, supervisor, work location and others). Checked every minute, so several field changes can produce several notifications. The payload is only `companyId` and `employeeId`	Changes to deductions, benefit setup or direct deposit, which are not on the trigger list	Queue affected records, re-read through the API, and poll for the domains the list does not cover
Future-dated changes	Not a separate webhook. Existing webhooks fire when the future record becomes current, which happens when payroll processing moves the company onto the check date it takes effect	Notice at the time the change is entered	Read temporal records if your product needs upcoming changes early
Time Off Approval Webhooks	Paylocity states that request cancellations and changes are not supported	Complete coverage of the time-off request lifecycle	Define reconciliation for cancellations and changes
Payroll Processed Webhooks	Paylocity sends the event on the payroll process date, not the check date; notifications do not expose employee IDs	Employee-level notification targeting or check-date triggering	Design the authorized payroll reconciliation task without expecting employee IDs in the notification

An Employee Change notification is two identifiers and nothing else:

JSON

{ "companyId": "GC3456789", "employeeId": "12345" }

As application design, place an HTTPS receiver in front of a durable queue. Have a worker use the queued identifiers to make an authorized API reread and apply the retrieved state. For employee-change events, this follows Paylocity's instruction to retrieve current details rather than rely on the notification for all updated information.

Make processing duplicate-tolerant: multiple notifications should not make repeated application of the retrieved state unsafe. Apply the relevant rate policy to the worker's reads, use bounded retries, and monitor work that fails or remains queued. These are design recommendations, not Paylocity delivery guarantees.

Reconciliation is a separate responsibility. For example, a time-off approval notification cannot stand in for coverage of cancellations that the event does not support. Specify an authorized retrieval-based reconciliation task for those uncovered changes.

In the synchronization contract, state both how notifications trigger work and how the application handles missing coverage. Retry codes, acknowledgment and the polling fallback are covered in detail in Paylocity webhooks: events, retries and polling fallback.

Maintain endpoint and version contracts

Include Paylocity API Versioning in the integration's operating specification, with an inventory and a named migration owner. A connector labeled only "Paylocity" does not identify the contracts your application depends on.

Paylocity embeds version numbers in endpoint URLs. Its versioning policy says the documented deprecation stage typically precedes permanent retirement by at least 12 months, with bug-fix support but no enhancements.

During deprecation, Paylocity keeps documentation available with replacement references or notes about removed functionality. At retirement, the API and relevant technical documentation are no longer accessible, and proactive support ends. Establish the replacement contract during the deprecation period instead of waiting until retirement.

OWASP API9:2023 recommends an API inventory covering hosts, environments, access audiences and deployed versions, and identifies missing version-retirement plans as an inventory risk.

Use the inventory to maintain this checklist:

Record the deployed API family, host, environment, endpoint, version and access audience.
Review endpoint status and documented warning information as an owned maintenance task.
Confirm the replacement contract and any approval requirements before migration.
Test schema, pagination, field access, effective-record handling and operational behavior against the replacement.
Assign a retirement owner and define the evidence required to accept the migration.

Paylocity's versioning example includes X-Pcty-Warning, X-Pcty-Warning-Message, Deprecated, Retirement and a deprecation-reference Link. Paylocity recommends monitoring warning information; these are example signals, not a guarantee that every response contains every listed header.

Define migration acceptance for each endpoint. Re-run the retrieval and access tests against the replacement, including company identity, required domains and pagination, rather than accepting a successful token request as sufficient evidence.

The lifecycle policy does not supply an endpoint-specific retirement date. Record the status and retirement information applicable to your deployed contract, then assign responsibility for deciding whether its migration is complete.

Where a unified API fits in a Paylocity integration

An API payroll integration is system-to-system data exchange. Everything above applies whether you build it yourself or put a unified API in front of Paylocity. What changes is who runs each part.

Bindbee has a live Paylocity connector. Per Bindbee's model availability matrix, the Paylocity API connector reads Employee, Employment, Compensation, Company, Group and Pay Group as supported models. Location, Payroll Run, Employee Payroll Run, Payroll Code, Benefit, Time Off, Timesheet Entry, Bank Info and Document are in beta. A separate Paylocity SFTP connector reads a file feed and adds dependents, benefit enrollments, benefit coverage and time-off balances, which the API connector does not return.

Responsibility	Direct integration	With Bindbee
Credentials and API-family config	You store credentials per family and environment, cache tokens, renew them before the hour is up and rotate secrets yearly	Bindbee holds the connection; your application sends a Bindbee API key plus one `X-Connector-Token` per customer
Employee retrieval	You implement WebLink paging, EA batch paging and effective-record selection	You read unified models from Bindbee's copy of the last completed sync
Restricted domains	You detect omitted or masked rates and sensitive data yourself	Scoping sets which models and fields are requested, and the customer's admin approves that list on the consent screen. One request with `include_raw_data=true` separates a permission gap from a mapping gap
Fields outside the unified model	You map them	Custom Fields map any value in the raw payload through a JMESPath expression
Paylocity endpoints Bindbee does not model	You call them	Passthrough sends your raw request using the credentials Bindbee already holds; the response is not normalized
Change detection	You run webhooks plus polling	Bindbee syncs every 24 hours by default, adjustable on request, and sends webhooks after each sync

Be precise about freshness. Bindbee webhooks fire because a sync ran: one created and one updated event per changed model, then connector.sync.completed. Each event carries record IDs, an id for deduplication and a per-connector sequence. They cannot report a Paylocity change before the next sync picks it up. If a termination has to reach your product within the hour, the 24-hour default does not meet that. Ask for a shorter interval, or force a resync for that connector when you know something changed.

None of this changes Paylocity's side. Approved access, the customer's sign-off on data access and the go-live review still apply, and a unified API can only return what the provisioned access can read. The three ways to reach a field your unified API doesn't have covers when to use Custom Fields, raw data or Passthrough.

To check your required fields against the connector, see the Paylocity integration page or book a technical review.

Frequently asked questions

Does Paylocity have a public API?

Yes, but access is not self-serve. Paylocity issues OAuth client credentials and a sandbox only after it reviews and approves an access request, and production use needs a separate go-live review against its integration requirements.

What authentication does the Paylocity API use?

OAuth 2.0 client credentials. You POST the client ID and secret to the token endpoint for your API family and environment, receive a bearer token valid for 3,600 seconds, and send it in the Authorization header. WebLink also requires scope=WebLinkAPI.

What is the Paylocity API rate limit?

WebLink allows up to 25 calls per second and returns HTTP 429 beyond that. Paylocity recommends exponential backoff with jitter and advises against burst-allowing limiters such as token buckets. Other API families set their own per-endpoint limits.

Is employeeId unique across Paylocity?

No. Paylocity's WebLink reference says employeeId is unique per companyId, and a company ID is a specific payroll entity. Store the company and employee pair together as your key.

How does Paylocity handle API versioning?

Version numbers sit in the endpoint URL. Deprecation typically precedes retirement by at least 12 months, and responses can carry warning headers such as X-Pcty-Warning, Deprecated and Retirement. Keep an inventory of the versions you call.

Kunal Tyagi

CTO

Bindbee

VIEW AUTHOR

Table of Contents