> ## Documentation Index
> Fetch the complete documentation index at: https://docs.homecarehq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect PrismHR

> A plain-English guide to connecting your PrismHR account so HomecareHQ can read your workforce data.

This guide is written for the **PrismHR account owner/admin**. It walks you through getting the
three pieces of information HomecareHQ needs to securely read your PrismHR data. Hand it to
whoever administers your PrismHR Back Office — usually your PEO/HR admin.

<Info>
  **The short version:** PrismHR doesn't use a "Sign in with PrismHR" button. Instead, your
  admin creates a dedicated, locked-down **Web Service User** (a service account just for
  HomecareHQ) and gives us three things: a **User ID**, a **Password**, and your **PEO ID**.
</Info>

## The three things you'll hand us

| # | What                          | What it is                                                    | Secret? |
| - | ----------------------------- | ------------------------------------------------------------- | ------- |
| 1 | **Web Service User ID**       | The username of the service account you create for HomecareHQ | Yes     |
| 2 | **Web Service User Password** | That account's password                                       | **Yes** |
| 3 | **PEO ID**                    | Your organization identifier inside PrismHR (you look it up)  | No      |

If you can get those three, you're done. The rest of this guide is *how* to get them and how to
lock the account down to least privilege.

## Before you start: check API access

Most of this is **self-serve in your PrismHR Back Office**. There are only two cases where you'd
contact PrismHR support:

* **If the "Web Service Users" option isn't there** (step 3 below), your account likely doesn't
  have API access enabled yet — ask PrismHR to turn it on.
* **If your PEO ID is blank** (step 2), submit a support request to have it populated.

<Steps>
  <Step title="Find your PEO ID (30 seconds)">
    In the PrismHR **Back Office**, go to **System → Change**, open the **System Parameters**
    form, and note the value in the **PEO ID** field. That's credential **#3** — read it, don't
    change it.
  </Step>

  <Step title="Create the Web Service User">
    In **Back Office**, go to **System → Change → System Parameters**, then from the **Actions**
    menu choose **Web Service Users**. Create a new user:

    | Field                   | What to enter                                                                                     |
    | ----------------------- | ------------------------------------------------------------------------------------------------- |
    | **User ID**             | Something recognizable, e.g. `homecarehq`. ⚠️ Can't be changed after saving. (Credential **#1**.) |
    | **User Name**           | A friendly label, e.g. "HomecareHQ Integration".                                                  |
    | **Password**            | A strong password. (Credential **#2**.)                                                           |
    | **Account Disabled**    | Leave **unchecked**.                                                                              |
    | **Minimum API Version** | Leave at the default unless support says otherwise.                                               |
  </Step>

  <Step title="Set company access">
    On **Company Access**, choose either *"Grant Access by Default, Deny to Specified"* (sees all
    your companies except those you list) or *"Deny by Default, Grant to Only Specified"* (sees
    only the companies you list). Use the second option to limit HomecareHQ to specific entities.
  </Step>

  <Step title="Grant least-privilege methods">
    On the **Allowed Methods** grid, grant **read** access to the services below (wildcards like
    `EmployeeService.*` are fine):

    | Grant                            | Why                                                | Required?             |
    | -------------------------------- | -------------------------------------------------- | --------------------- |
    | `LoginService.createPeoSession`  | Log in / start a session                           | **Always**            |
    | `LoginService.getAPIPermissions` | Confirm the account's access                       | **Always**            |
    | `EmployeeService.*` (read)       | Employee roster, contact, hire/term dates, status  | **Yes**               |
    | `ClientMasterService.*` (read)   | Company/client context                             | **Yes**               |
    | Onboarding methods               | New-hire task status & progress                    | **Yes**               |
    | Document methods                 | Document **references only** — never file contents | **Yes**               |
    | `PayrollService.*` (read)        | Pay statements, earnings, deductions               | **Optional** (opt-in) |
    | Benefit methods                  | Benefit elections, enrollment, plan details        | **Optional** (opt-in) |

    <Tip>
      Prefer not to hand-pick methods? Granting **read access to the services above** is fine —
      HomecareHQ only ever calls the methods it needs, for the data areas you've turned on.
    </Tip>
  </Step>

  <Step title="Allow our servers through (Allowed IPs)">
    PrismHR can restrict the account to specific **IP addresses**. Because HomecareHQ connects
    through our secure integration partner (Nango), requests come from *their* servers.

    * **Recommended:** ask HomecareHQ for our integration partner's current outbound IP list and
      enter it in **Allowed IPs**.
    * **Alternative (less secure):** check **Disable IP Restrictions** — PrismHR recommends
      against this outside testing.
  </Step>
</Steps>

## What we read — and what we don't

You control how much. By default we turn on the three low-sensitivity areas and leave the two
sensitive ones **off** until you opt in.

| Data area         | Default          | What we read                                                     |
| ----------------- | ---------------- | ---------------------------------------------------------------- |
| **Employee core** | **On**           | Demographics, contact, hire/termination dates, employment status |
| **Onboarding**    | **On**           | New-hire task status and completion progress                     |
| **Documents**     | **On**           | Document **references/metadata only — never file contents**      |
| **Payroll**       | **Off** (opt-in) | Pay statements, earnings, deductions, taxes                      |
| **Benefits**      | **Off** (opt-in) | Benefit elections, enrollment status, plan details               |

Two layers protect you: the permissions you set in step 4 are the hard ceiling, and even within
what's granted, HomecareHQ keeps Payroll and Benefits **off** until you enable them in
**Admin Settings → Integrations**.

## Hand us the credentials securely

<Steps>
  <Step title="Open Integrations">
    Sign in to HomecareHQ and go to **Admin Settings → Integrations**.
  </Step>

  <Step title="Connect PrismHR">
    On the **PrismHR** card, click **Connect**.
  </Step>

  <Step title="Enter your three credentials">
    In the secure dialog, enter the **Web Service User ID**, **Password**, and **PEO ID**.
  </Step>
</Steps>

<Note>
  **Your credentials never touch HomecareHQ's own systems.** When you connect a system, you
  enter its credentials into a secure dialog hosted by our credential vault partner
  (**Nango**), where they are encrypted and stored. HomecareHQ only ever asks the vault to
  fetch data on your behalf — it never sees or stores your password. You can disconnect at any
  time from **Admin Settings → Integrations**.
</Note>

<Warning>
  Never email or chat the password. If you need to share details with our team ahead of time,
  ask for our secure intake link.
</Warning>

## FAQ

<AccordionGroup>
  <Accordion title="Is this OAuth / 'Sign in with PrismHR'?">
    No. PrismHR uses a service-account model: a Web Service User (ID + password) plus your PEO
    ID. We exchange those for a short-lived session behind the scenes.
  </Accordion>

  <Accordion title="Will this let HomecareHQ change anything in PrismHR?">
    No. For chat and dashboards, HomecareHQ is **read-only** — grant read access only.
  </Accordion>

  <Accordion title="Does the session expire?">
    PrismHR sessions idle out after about 30 minutes. Our integration partner refreshes the
    session automatically — nothing for you to manage.
  </Accordion>

  <Accordion title="Can I revoke access later?">
    Yes — disable or delete the Web Service User in Back Office, or disconnect from
    **Admin Settings → Integrations**. Either immediately stops access.
  </Accordion>

  <Accordion title="Do you store our employee data?">
    We cache a working copy to answer questions quickly, isolated to your organization. For
    documents we store only references (the list), never file contents.
  </Accordion>
</AccordionGroup>

## PrismHR's own documentation

* [Welcome to the PrismHR Services API](https://api-docs.prismhr.com/docs/prismhr-api-docs/4b402d5ab3edd-welcome-to-the-prism-hr-services-api)
* [Setting up PrismHR and Web Service User accounts](https://api-docs.prismhr.com/docs/prismhr-api-docs/wf95feooavn5s-setting-up-prism-hr-and-web-service-user-accounts)