Paylocity icon

Paylocity payroll, punch and earned-wage APIs

Paylocity · Business

Paylocity is the mobile app of Paylocity, the Schaumburg, Illinois-based, Nasdaq-listed (PCTY) provider of cloud payroll and human-capital-management software founded in 1997, and it puts that platform in the hands of employees, supervisors and payroll administrators at its US client companies. Workers sign in with their company code and username or through single sign-on, then land on a home dashboard of quick actions, open tasks, time-off, W-2 tax forms, retirement and team widgets alongside posts from Paylocity's Community social feed. From there they clock in and out with the punch button, adding notes and cost centers, page through timesheets by pay period, check assigned shifts on My Schedule, review pay history and retirement contributions, and draw part of their earned wages before payday through On Demand Payment. Supervisors see their team, while payroll administrators follow in-flight regular and off-cycle payroll runs and the cash requirements each run must have funded by bank account before it is released. The app serves the US mid-market, where Paylocity competes with ADP, Paycom, Paychex and Paycor for employers' payroll, timekeeping and benefits business.

Time punches written from the clock button carry a signed timestamp, a punch type, an optional note, geolocation and costCenterIds, and they line up against the worker's pay-period windows (startDate, endDate) and rostered shifts with duration, position and costCenters. Payroll runs are listed by checkDate, periodBegin, periodEnd, isOffCycle and payFrequency, totalled into employeeCount, hours, gross, net, deductions and taxes, and broken down into the cash each run needs: per-bank totalEft and totalChecks keyed by accountNumberLastFour, plus direct-deposit, tax, agency and payroll liabilities.

Earned-wage records add each transfer's paymentAmount, transferFeeAmount, paymentStatus and payrollDeductionDate, and quotes that price a chosen paymentTransferSpeed into paymentFeeAmount and totalPaymentAmount. Retirement profiles split contributions into preTax, roth and yearToDateContributions, the home feed reports open tasks, timeOff and w2TaxFiling status, and every record is scoped to a companyCode and employeeId carrying isSupervisor and payType flags.

Treasury bots read the per-bank funding and liability totals to confirm a payroll is covered before its ACH file goes out; workforce-management systems post punches and diff them against rostered shifts for the same pay period; earned-wage clients show a worker the fee and total of an early payout before it is confirmed, with prior transfers alongside; and benefits tools paint year-to-date pre-tax and Roth contributions next to the home retirement widget. openData Studio makes these Paylocity punch, payroll-funding, earned-wage and retirement records callable open data for those integrations.

Screenshots

  • Paylocity screenshot 1
  • Paylocity screenshot 2
  • Paylocity screenshot 3
  • Paylocity screenshot 4
  • Paylocity screenshot 5
  • Paylocity screenshot 6
  • Paylocity screenshot 7
  • Paylocity screenshot 8

API surface

The endpoints and request/response examples below are reconstructed from the app's interface — illustrative, not a live capture.

  • Company login (jwt and gateway token)

    POST /v1/auth/login osint

    Signs the worker or payroll admin into a company and returns jwt, gatewayToken, refreshToken, sessionId plus the company and user envelopes that every later payroll, punch and schedule call is scoped to.

    Auth: Company code plus userName/password, or a PKCE code with codeChallenge, codeChallengeMethod and codeChallengeVerifier. No prior Bearer. The returned jwt is sent as Authorization: Bearer on later calls; gatewayToken is stored on the session.

    • jwt
    • gatewayToken
    • refreshToken
    • sessionId
    • accessTokenExpiration
    • company
    • user
    • companyCode
    • employeeId
    • email
    • identityKey
    POST /v1/auth/login HTTP/1.1
    Content-Type: application/json
    
    {
      "mode": "password",
      "company": "B1234",
      "userName": "jdoe",
      "password": "******"
    }
    {
      "data": {
        "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
        "gatewayToken": "gwt-8f21c4a0",
        "refreshToken": "rt-c91e2b77",
        "sessionId": "sess-10432",
        "accessTokenExpiration": "2026-09-29T18:40:00Z",
        "company": {"companyCode": "B1234", "companyName": "Acme Manufacturing", "doingBusinessAs": "Acme", "companySet": "prod-us"},
        "user": {"email": "[email protected]", "employeeId": "E-10432", "firstName": "Jane", "lastName": "Doe", "userName": "jdoe", "isSupervisor": false, "identityKey": "idk-77a1"}
      },
      "errors": []
    }
  • Refresh login tokens

    POST /v1/auth/token/refresh opendata

    Rotates jwt, gatewayToken and refreshToken so the signed-in session stays alive across the accessTokenExpiration window without another password prompt.

    Auth: Body carries the refreshToken from POST /v1/auth/login. Replaces the expired jwt without re-entering the password.

    • jwt
    • gatewayToken
    • refreshToken
    • sessionId
    • accessTokenExpiration
    POST /v1/auth/token/refresh HTTP/1.1
    Content-Type: application/json
    
    {
      "refreshToken": "rt-c91e2b77",
      "company": "B1234"
    }
    {
      "data": {
        "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
        "gatewayToken": "gwt-8f21c4a0",
        "refreshToken": "rt-d02f3c88",
        "sessionId": "sess-10432",
        "accessTokenExpiration": "2026-09-29T22:40:00Z"
      },
      "errors": []
    }
  • User and company context

    GET /v1/accounts/{companyId}/context osint

    Reloads the signed-in company and user envelope — companyCode, employeeId, supervisor and terminated flags, feature toggles — used to gate payroll, punch and earned-wage screens after a token refresh.

    Auth: Authorization: Bearer <jwt> from POST /v1/auth/login. companyId is the companyCode from the login envelope.

    • company
    • user
    • toggles
    • myPaylocity
    • companyCode
    • employeeId
    • isSupervisor
    • isTerminated
    • payType
    • personId
    GET /v1/accounts/B1234/context HTTP/1.1
    Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
    {
      "data": {
        "company": {"companyCode": "B1234", "companyName": "Acme Manufacturing", "doingBusinessAs": "Acme", "companySet": "prod-us"},
        "user": {"email": "[email protected]", "employeeId": "E-10432", "firstName": "Jane", "lastName": "Doe", "userName": "jdoe", "isSupervisor": false, "isTerminated": false, "payType": "hourly", "personId": "P-88120"},
        "toggles": [{"name": "earnedWageAccess", "enabled": true}],
        "myPaylocity": {"enabled": true}
      }
    }
  • Home dashboard

    GET /v1/accounts/{companyId}/dashboard opendata

    Returns the signed-in home feed: quick-action chips, latest punch state, open tasks, time-off, W-2 filing, retirement and team widgets that the dashboard renders after login.

    Auth: Authorization: Bearer <jwt> from POST /v1/auth/login.

    • quickActions
    • punch
    • tasks
    • timeOff
    • w2TaxFiling
    • retirement
    • socialCarousel
    • calendar
    • myTeam
    GET /v1/accounts/B1234/dashboard HTTP/1.1
    Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
    {
      "data": {
        "quickActions": {"chips": ["punch", "payHistory", "timeOff"]},
        "punch": {"latestPunchType": "in", "canPunch": true},
        "tasks": {"count": 2},
        "timeOff": {"upcoming": []},
        "w2TaxFiling": {"available": true},
        "retirement": {"hasProfile": true},
        "socialCarousel": {"items": []}
      }
    }
  • Active payroll runs

    GET /v1/accounts/{companyId}/payroll-runs openfinance

    Lists the company's in-flight payroll runs — check date, period begin/end, off-cycle flag, pay schedule — that the payroll home screen pages through.

    Auth: Authorization: Bearer <jwt> from POST /v1/auth/login. companyId is the signed-in companyCode.

    • id
    • checkDate
    • periodBegin
    • periodEnd
    • isOffCycle
    • payScheduleId
    • payFrequency
    GET /v1/accounts/B1234/payroll-runs HTTP/1.1
    Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
    {
      "items": [
        {
          "id": "PR-2026-09-25",
          "checkDate": "2026-09-25",
          "periodBegin": "2026-09-08",
          "periodEnd": "2026-09-21",
          "isOffCycle": false,
          "payScheduleId": "PS-WEEKLY",
          "payFrequency": "weekly"
        }
      ]
    }
  • Payroll run summary

    GET /v1/accounts/{companyId}/payroll-runs/{payrollId}/totals openfinance

    Returns headline totals for one payroll run: batch and employee counts, hours, live vs direct-deposit check counts, and cash amounts (gross, net, earnings, deductions, taxes).

    Auth: Authorization: Bearer <jwt> from POST /v1/auth/login.

    • payrollId
    • batchCount
    • employeeCount
    • hours
    • checkCounts
    • directDeposit
    • live
    • cashAmounts
    • gross
    • net
    • earnings
    • deductions
    • taxes
    GET /v1/accounts/B1234/payroll-runs/PR-2026-09-25/totals HTTP/1.1
    Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
    {
      "payrollId": "PR-2026-09-25",
      "batchCount": 3,
      "employeeCount": 412,
      "hours": 16480.50,
      "checkCounts": {"directDeposit": 390, "live": 22},
      "cashAmounts": {"gross": 1854320.11, "net": 1422100.44, "earnings": 1854320.11, "deductions": 210400.20, "taxes": 221819.47}
    }
  • Payroll cash requirements

    GET /v1/accounts/{companyId}/payroll-runs/{payrollId}/funding openbanking

    Shows the cash the company must have on hand to fund a payroll: per-bank EFT and check totals (last-four account) plus liability buckets for direct deposit, tax, agency and payroll.

    Auth: Authorization: Bearer <jwt> from POST /v1/auth/login. Payroll-admin session.

    • bankingSummary
    • accountNumberLastFour
    • totalEft
    • totalChecks
    • liabilities
    • directDeposit
    • tax
    • agency
    • payroll
    GET /v1/accounts/B1234/payroll-runs/PR-2026-09-25/funding HTTP/1.1
    Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
    {
      "bankingSummary": [
        {
          "name": "Operating - Wells Fargo",
          "accountNumberLastFour": "4421",
          "totalEft": 1385400.12,
          "totalChecks": 36700.32
        }
      ],
      "liabilities": {
        "directDeposit": {"amount": 1385400.12},
        "tax": {"amount": 221819.47},
        "agency": {"amount": 18400.00},
        "payroll": {"amount": 36700.32}
      }
    }
  • Create a time punch

    POST /v1/accounts/{companyId}/employees/{employeeId}/clock-events opendata

    Records a clock-in or clock-out for the signed-in employee, with signed timestamp, punch type, optional note, geolocation and cost-center ids — the write side of the punch button.

    Auth: Authorization: Bearer <jwt> from POST /v1/auth/login. employeeId is the signed-in worker.

    • timestamp
    • type
    • note
    • isManual
    • source
    • geolocation
    • costCenterIds
    • punchId
    POST /v1/accounts/B1234/employees/E-10432/clock-events HTTP/1.1
    Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
    Content-Type: application/json
    
    {
      "timestamp": {"value": "2026-09-29T12:01:04Z", "signature": "sig-aa12"},
      "type": "in",
      "note": "",
      "isManual": false,
      "source": "mobile",
      "geolocation": {"latitude": 41.8781, "longitude": -87.6298},
      "costCenterIds": ["CC-OPS"]
    }
    {
      "punchId": "PCH-99120",
      "timestamp": "2026-09-29T12:01:04Z",
      "type": "in",
      "isManual": false,
      "source": "mobile"
    }
  • Employee pay periods

    GET /v1/accounts/{companyId}/employees/{employeeId}/work-periods opendata

    Lists the employee's pay-period windows (startDate, endDate) that the timesheet and punch history screens page by.

    Auth: Authorization: Bearer <jwt> from POST /v1/auth/login.

    • startDate
    • endDate
    GET /v1/accounts/B1234/employees/E-10432/work-periods HTTP/1.1
    Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
    {
      "items": [
        {"startDate": "2026-09-08T00:00:00Z", "endDate": "2026-09-21T23:59:59Z"},
        {"startDate": "2026-09-22T00:00:00Z", "endDate": "2026-10-05T23:59:59Z"}
      ]
    }
  • My schedule shifts

    GET /v1/accounts/{companyId}/employees/{employeeId}/roster opendata

    Returns the signed-in employee's assigned shifts — id, type, duration, date range, job position and cost centers — behind the My Schedule screen.

    Auth: Authorization: Bearer <jwt> from POST /v1/auth/login.

    • items
    • id
    • type
    • duration
    • date
    • position
    • costCenters
    • status
    GET /v1/accounts/B1234/employees/E-10432/roster HTTP/1.1
    Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
    {
      "items": [
        {
          "id": "SH-44120",
          "type": "shift",
          "duration": {"hours": 8, "minutes": 0},
          "date": {"start": "2026-09-29T13:00:00Z", "end": "2026-09-29T21:00:00Z"},
          "position": {"name": "Line Operator"},
          "costCenters": [{"id": "CC-OPS", "name": "Operations"}],
          "status": "scheduled"
        }
      ]
    }
  • Earned-wage payments

    GET /v1/accounts/{companyId}/employees/{employeeId}/wage-advances openfinance

    Lists earned-wage transfers the employee has already taken this period — amount, fee, status, transfer time and the payroll date the amount will be deducted.

    Auth: Authorization: Bearer <jwt> from POST /v1/auth/login. Feature gated by the earnedWageAccess toggle on the account context.

    • paymentId
    • paymentDateTimeUtc
    • paymentStatus
    • paymentAmount
    • transferFeeAmount
    • payrollDeductionDate
    • transferredDateTimeUtc
    GET /v1/accounts/B1234/employees/E-10432/wage-advances HTTP/1.1
    Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
    {
      "items": [
        {
          "paymentId": "EWA-70012",
          "paymentDateTimeUtc": "2026-09-24T16:12:00Z",
          "paymentStatus": "completed",
          "paymentAmount": 150.00,
          "transferFeeAmount": 2.99,
          "payrollDeductionDate": "2026-09-25T00:00:00Z",
          "transferredDateTimeUtc": "2026-09-24T16:40:00Z"
        }
      ]
    }
  • Earned-wage payment preview

    POST /v1/accounts/{companyId}/employees/{employeeId}/wage-advance-quotes openfinance

    Quotes fee and total for an earned-wage transfer of a given amount and speed against a saved payment method, before the employee confirms the payout.

    Auth: Authorization: Bearer <jwt> from POST /v1/auth/login.

    • paymentMethodId
    • paymentTransferSpeed
    • paymentAmount
    • paymentPreviewId
    • paymentFeeAmount
    • totalPaymentAmount
    • transferByDate
    • paymentOption
    POST /v1/accounts/B1234/employees/E-10432/wage-advance-quotes HTTP/1.1
    Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
    Content-Type: application/json
    
    {
      "paymentMethodId": 4412,
      "paymentTransferSpeed": "instant",
      "paymentAmount": 125.00
    }
    {
      "paymentPreviewId": 88021,
      "paymentAmount": 125.00,
      "paymentFeeAmount": 2.99,
      "totalPaymentAmount": 127.99,
      "transferByDate": "2026-09-29T18:00:00Z",
      "paymentOption": {"code": "instant"}
    }
  • Retirement contribution profile

    GET /v1/accounts/{companyId}/assignments/{assignmentId}/retirement-summary openfinance

    Reads the worker's retirement contribution profile from pay history — pre-tax and Roth plans plus year-to-date employee and employer amounts — shown on the retirement card.

    Auth: Authorization: Bearer <jwt> from POST /v1/auth/login. assignmentId is the worker's payroll assignment.

    • companyId
    • assignmentId
    • currency
    • preTax
    • roth
    • yearToDateContributions
    GET /v1/accounts/B1234/assignments/AS-10432/retirement-summary HTTP/1.1
    Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
    {
      "companyId": "B1234",
      "assignmentId": "AS-10432",
      "currency": "USD",
      "preTax": [{"planName": "401(k)", "percent": 6.0}],
      "roth": [{"planName": "Roth 401(k)", "percent": 2.0}],
      "yearToDateContributions": {"employee": 4200.00, "employer": 2100.00}
    }

Data categories

  • login session
  • user profile
  • company context
  • home dashboard
  • payroll runs
  • payroll cash requirements
  • time punches
  • pay periods
  • work schedules
  • earned wage access
  • retirement contributions

Where teams use this data

  • Payroll cash-funding check

    A treasury bot signs in as a payroll admin, lists in-flight runs at GET /v1/accounts/{companyId}/payroll-runs, then reads GET /v1/accounts/{companyId}/payroll-runs/{payrollId}/funding for accountNumberLastFour, totalEft and tax liabilities before releasing the ACH file.

  • Clock and schedule reconciliation

    A workforce system posts punches to POST /v1/accounts/{companyId}/employees/{employeeId}/clock-events and diffs them against GET /v1/accounts/{companyId}/employees/{employeeId}/roster (duration, position, costCenters) for the same pay period from GET /v1/accounts/{companyId}/employees/{employeeId}/work-periods.

  • Earned-wage payout quote

    Before a worker confirms an early wage, the client POSTs paymentAmount and paymentTransferSpeed to /v1/accounts/{companyId}/employees/{employeeId}/wage-advance-quotes and shows paymentFeeAmount plus totalPaymentAmount; prior transfers come from GET .../wage-advances.

  • Retirement year-to-date card

    The benefits screen calls GET /v1/accounts/{companyId}/assignments/{assignmentId}/retirement-summary for preTax, roth and yearToDateContributions and paints them next to the home retirement widget from GET /v1/accounts/{companyId}/dashboard.

Frequently asked questions

How does Paylocity authenticate API calls?

POST /v1/auth/login accepts company, userName and password (or a PKCE code) and returns jwt, gatewayToken, refreshToken and sessionId. Later calls send Authorization: Bearer <jwt>. POST /v1/auth/token/refresh rotates the tokens; GET /v1/accounts/{companyId}/context reloads company, user and feature toggles.

Which payroll amounts are exposed?

GET /v1/accounts/{companyId}/payroll-runs lists in-flight runs (checkDate, periodBegin, periodEnd). GET .../payroll-runs/{payrollId}/totals returns gross, net, earnings, deductions, taxes and live vs direct-deposit check counts. GET /v1/accounts/{companyId}/payroll-runs/{payrollId}/funding adds per-bank totalEft, totalChecks and accountNumberLastFour plus tax and direct-deposit liabilities.

Can workers clock in and read their schedule?

Yes. POST /v1/accounts/{companyId}/employees/{employeeId}/clock-events records a punch with signed timestamp, type and geolocation. Pay-period windows come from GET /v1/accounts/{companyId}/employees/{employeeId}/work-periods. Assigned shifts are GET /v1/accounts/{companyId}/employees/{employeeId}/roster.

Apps similar to Paylocity

  • ADP Mobile Solutions — ADP's employee companion to its Workforce Now HCM suite, covering payroll, HR, time and talent for mid-market companies and competing with Paylocity on multi-state tax and compliance depth.
  • Workday — Workday is an enterprise suite that unifies HR, payroll and finance data on one system, aimed at organizations past roughly 1,000 employees.
  • UKG Pro — UKG is a payroll and HR platform built around scheduling and labor compliance, aimed at mid-market companies in industries like healthcare, retail, hospitality and manufacturing.
  • Paychex Flex — Paychex Flex bundles payroll, HR and benefits for small US businesses, with published pricing starting at $39 per month plus $5 per employee.
  • Gusto — Gusto is a US payroll platform with published pricing and unlimited payroll runs, aimed at small businesses of roughly 2 to 200 employees.
  • Paycom — Paycom is a single-database HCM platform for mid-to-large companies whose Beti feature has employees verify their own paychecks before payroll runs.
  • Rippling — Rippling unifies HR, IT and payroll in one system for tech-forward companies, automating work like app provisioning for new hires.

Topics

  • paylocity api
  • paylocity payroll
  • paylocity punch
  • earned wage access
  • payroll cash requirements
  • employee schedule api
  • paylocity login jwt

Need this app's data API integrated?

We deliver scoped integrations for any named app — from USD 500 with source-code handoff, or hosted access billed per call. Tell us the data you need.

  • NDA + SOW on every engagement
  • Delivery in 3–7 days
  • Payment only after acceptance
  • Work scoped to authorized use

Get a quote