# HollyHR for Zapier

The official HollyHR Zapier integration is currently in private qualification.
It is not yet a public Zapier App Directory listing. This guide documents the
connector contract so invited testers and reviewers can configure it safely
before publication.

## What v1 supports

| Operation               | HollyHR scope                       | Plan boundary                      |
| ----------------------- | ----------------------------------- | ---------------------------------- |
| New Person              | `people:read` + `webhooks:manage`   | Free and Standard                  |
| New or Updated Person   | `people:read` + `webhooks:manage`   | Free and Standard                  |
| Person Ended            | `people:read` + `webhooks:manage`   | Free and Standard                  |
| New or Updated Time Off | `time_off:read` + `webhooks:manage` | Free and Standard                  |
| Find Person             | `people:read`                       | Free and Standard                  |
| Create Person           | `people:write`                      | Standard, with API writes approved |
| Create Time Off         | `time_off:write`                    | Standard, with API writes approved |

The read operations use HollyHR's safe public people and time-off projections.
They do not expose personal contact details, home addresses, dates of birth,
demographic fields, compensation, bank or tax identifiers, document bytes,
time-off notes, or health-adjacent details.

## Connect a workspace

1. In HollyHR, open **Settings → Integrations → Developer tools** as a System
   Admin.
2. Create a dedicated key for Zapier and grant only the scopes needed by the
   Zaps you intend to enable.
3. In Zapier, enter the workspace part of your HollyHR URL. For
   `https://acme.hollyhr.com`, enter `acme`.
4. Paste the API key once. Zapier checks `GET /me`, and HollyHR derives the
   organisation from that key. The connector never accepts an organisation ID
   as user input.

For create actions, also grant `people:read`, `org_units:read`, and
`reference:read` if you want Zapier to populate the person, department,
workplace, work-type, and time-off-category dropdowns.

## Trigger timing and recovery

The four triggers use Zapier REST Hooks rather than polling. When a Zap is
enabled, Zapier creates an exact, signed HollyHR event subscription. A committed
matching change receives a best-effort immediate delivery attempt; a durable
one-minute worker remains authoritative for recovery and bounded retries.
Delivery is at least once, so use the event ID to make downstream steps
idempotent.

**Person Ended** runs when an employment end date is set or changed. It does not
wait until a future end date arrives.

Bulk imports record durable events without starting hundreds of request-lifetime
callbacks. Keep downstream Zap actions idempotent because recovery can redeliver
an event.

## Safe create retries

Both create actions require a **Source record key**. Map a stable unique value
from the Zap trigger, such as the source employee, form submission, or absence
request ID. HollyHR hashes it into an idempotency key. If Zapier retries the
same task, HollyHR replays the original response instead of creating a
duplicate person, seat, or time-off record.

HollyHR still applies the connected key's exact write scope, Standard-plan
entitlement, and write-approval state. The connector cannot bypass them.

## Data handling

Zapier receives only fields returned by the selected trigger, search, or action.
Any field mapped into a later Zap step is then processed under that destination
app's and Zapier's data-handling terms. Review every mapping before enabling a
Zap, particularly when employee names, work emails, leave dates, or status
leave HollyHR.

Use fictional records for testing. Never paste API keys, employee records, or
Zap task payloads into public support messages.

## Revoke access

To stop one Zap, turn it off in Zapier. To stop all access for a connection,
revoke its dedicated key in **Settings → Integrations → Developer tools**.
Revocation takes effect on the next request; reconnecting requires a new key.

## Troubleshooting

- **Authentication failed:** confirm the workspace subdomain, make sure the key
  has not expired or been revoked, and create a new dedicated key if necessary.
- **Missing choices:** add the relevant read scope (`people:read`,
  `org_units:read`, or `reference:read`) to a replacement key.
- **403 on a create action:** the workspace must be Standard, public API writes
  must be approved, and the key needs the matching write scope.
- **No trigger event yet:** confirm the Zap is enabled, make a fresh matching
  change, and inspect the webhook endpoint health and delivery activity in
  HollyHR. Recovery may take longer than the immediate delivery attempt.
- **Duplicate protection replayed an older result:** use a different source
  record key for a genuinely different source event.

If the problem continues, email [support@hollyhr.com](mailto:support@hollyhr.com)
with the HollyHR request ID shown in the Zap error. Do not include the API key
or employee data.