Key takeaways

• PrismHR authenticates through a Web Service User account and a PEO ID via LoginService.createPeoSession. There is no authorization server and no token endpoint.
• A session carries a 30-minute idle timeout that resets on every call, so its lifespan depends on activity rather than a fixed expiry.
• Some integration guides describe PrismHR as OAuth. They are wrong, and following them costs you a debugging session.
• Access is configured per Web Service User across three axes: company access, allowed methods, and allowed IPs.
• SubscriptionService exists, so PrismHR can push events rather than forcing you to poll. Most integration write-ups miss it.

PrismHR API architecture, authentication, and data access

PrismHR's API looks like a normal modern platform API: REST endpoints, JSON payloads, a service-oriented structure. Ask how it authenticates, though, and you will find two different answers depending on where you look.

One version, repeated across a handful of third-party integration guides, describes an OAuth flow: hit a token endpoint, get a short-lived access token, refresh it before it expires. The other, PrismHR's own documentation, describes something else: a named Web Service User account, a PEO ID, and a session that lasts as long as you keep calling it.

Build against the first description and you will spend a debugging session chasing a 401 that has nothing to do with your credentials. Build against the second and it works on the first try.

This page covers three things an engineer scoping a PrismHR integration needs before writing code: how the API is structured, how the Web Service User session model actually works, and what governs access once you are authenticated.

How the PrismHR API is structured

PrismHR frames the API around real-time data exchange with connected systems: REST endpoints, JSON responses by default, XML available as an alternative, and pagination for result sets too large for a single response.

The API is organised into named service groups, each scoped to one part of the PEO relationship. The ones you will meet first:

This is the architecture you need to scope the integration, not the full endpoint reference you will need to write it. PrismHR's own docs site carries the complete method catalogue.

SubscriptionService is the one most write-ups leave out. It exposes createSubscription, getEvents, appendFilter, getAllSubscriptions, and cancelSubscription. If you assumed a PrismHR integration means polling on a schedule, check this before you design around a cron job.

Every service group sits behind the same gate: a valid session from LoginService.

Authentication: the Web Service User session model

Is the PrismHR API OAuth? No.

OAuth 2.0, as defined in RFC 6749, is a delegated-authorization framework. A third-party application gets scoped access to a resource without ever holding the resource owner's credentials, granted by an authorization server that issues short-lived tokens. PrismHR's model has none of that machinery.

What PrismHR's documentation describes is direct, credentialed authentication. A Web Service User account, created for your integration, authenticates with its own username and password plus a PEO ID identifying which PEO organisation it belongs to. No authorization server, no client ID or secret, no scope negotiation. LoginService.createPeoSession takes the three values and returns a session identifier you attach to every subsequent call.

Both values come from the same place in the back office. The Web Service User is created under System Parameters, through the Actions menu, and the PEO ID sits on that same System Parameters screen. If the PEO ID field comes back blank, PrismHR's documentation says to file a support request rather than guess at a value.

Some existing integration guides describe this as an OAuth exchange against a token endpoint, with access tokens that expire and need refreshing. That account does not match PrismHR's own documentation. Follow it and you will implement a credential exchange against a model that is not part of this system.

Creating and maintaining a session

• Authenticate. Call LoginService.createPeoSession with a username, password, and PEO ID.
• Receive the session. The call returns a session identifier, used on every subsequent request.
• Stay inside the window. Each call resets a 30-minute idle timeout. Let it lapse and the session is gone.
• Keep it alive on purpose. Call LoginService.keepAlive during any stretch with no other API activity. Available in version 1.24 and above.
• Invalidate on completion. Call LoginService.invalidateSession when the work is done rather than letting it expire. Available in version 1.25 and above.

Those two version floors matter. If you are building against an older PrismHR version, neither method is available to you and your session management has to work around their absence.

LoginService also carries the permission-inspection methods: getAPIPermissions returns the current permissions for the logged-in Web Service User, requestAPIPermissions saves a requested permission schema for the PEO or account owner to approve later, and checkPermissionsRequestStatus returns the status of that request. Being able to ask the API what you are allowed to call is genuinely useful during onboarding.

The 30-minute window is not arbitrary. OWASP's session management guidance treats an idle timeout as a control that bounds how long an abandoned or stolen session stays usable, and a session that resets on activity and expires on silence is exactly that kind of control. Treat an expired PrismHR session as expected behaviour rather than a bug, and re-authenticate.

Data access: what a session actually reaches

A session gets you into the API. What a given Web Service User can see and change is a separate configuration, set per user across three axes.

Responses default to JSON, the interchange format standardised in RFC 8259, and can be requested as XML instead. Pagination is available for endpoints returning large result sets.

Two more details are worth planning around. Certain Web Service User fields lock after the first save, so get the scoping right before you save rather than after. And the API is versioned, with endpoints deprecated or combined over time, notably in version 1.30. Track the version you are building against.

That adds up to a session model to implement correctly, three axes of per-user scoping to configure, and a versioned API to track. For how those three axes govern what you reach across a PEO's whole client base, see what the PrismHR API exposes across PEO client companies.

Building it yourself versus integrating once

Everything above describes finite, well-defined work: one authentication model, one access-control scheme, one versioned API. Doing it well does not make it disappear, and it does not transfer. The next HR, payroll, ATS, or benefits system on your roadmap has its own session model, its own service architecture, and its own scoping rules to learn from scratch.

A unified API absorbs that repetition. One integration surface for your engineering team, with each source system's actual authentication handled underneath rather than reimplemented per connection.

Bindbee connects to 67+ HRIS, payroll, ATS, and benefits systems through a single API, PrismHR included. Each connector authenticates the way its source system actually requires, PrismHR's Web Service User session included, with no screen scraping. Connectivity is direct API or SFTP depending on the system, and PrismHR is an API connector.

On PrismHR specifically, Bindbee normalises employee and company records into its unified models today. Across the wider catalogue, Bindbee covers 40+ unified data models spanning HRIS, payroll, ATS, and LMS, so the same endpoints and the same response shapes serve every connector your platform adds. Where a source field does not fit a standard object, Custom Fields carries it through, mapped by JMESPath onto the object it belongs on.

Production connectors sync every 24 hours by default, and the interval is configurable. Webhooks fire when a sync starts, finishes, or fails, and when synced records change.

PrismHR data includes benefits information, and depending on plan design, health information as well. Bindbee is SOC 2 Type II, ISO 27001, HIPAA, and GDPR compliant, and a standard BAA template is available.

The technical shape of a PrismHR integration is knowable well before you write code. Get the session model right, configure the three scoping axes deliberately, and track the version you are building against. Whether you build that yourself or reach it through a maintained connector is a resourcing decision.

Healthee replaced 15 custom integrations with Bindbee. Newfront cut client onboarding from 8 to 12 weeks down to 48 hours.

We build the integrations. You build the product.

FAQ

Does the PrismHR API use OAuth?

No. PrismHR authenticates through a Web Service User account and a PEO ID via LoginService.createPeoSession, which produces a session identifier rather than an OAuth access token. OAuth 2.0, defined in RFC 6749, is built around an authorization server and third-party token issuance. PrismHR's model has neither.

What does createPeoSession require and return?

It requires a username, password, and PEO ID, and it returns a session identifier that you attach to every subsequent call. There is no separate token exchange or refresh step.

How long does a PrismHR API session last?

There is no fixed lifespan. The session carries a 30-minute idle timeout that resets on every call, so a session under steady use can run indefinitely, while one that goes quiet for half an hour needs a fresh createPeoSession call.

Can PrismHR push events instead of making me poll?

Yes. SubscriptionService exposes createSubscription, getEvents, appendFilter, getAllSubscriptions, and cancelSubscription. Check it before designing around a polling schedule.

Where do I find my PEO ID?

In the back office, under System Parameters. The same screen carries the Actions menu entry for creating Web Service Users. If the PEO ID field is blank, PrismHR's documentation directs you to raise a support request rather than guess.