# HollyHR for Make

The repository-owned HollyHR Make integration is ready for founder-present
private qualification. It has not yet been created or approved as a public Make
Apps listing. This guide documents the connector contract so invited testers
and reviewers can configure it safely before publication.

## What v1 supports

| Module                   | HollyHR scope    | Plan boundary                      |
| ------------------------ | ---------------- | ---------------------------------- |
| Watch People             | `people:read`    | Free and Standard                  |
| Watch Time Off           | `time_off:read`  | Free and Standard                  |
| Search People            | `people:read`    | Free and Standard                  |
| List Time Off Categories | `reference:read` | Free and Standard                  |
| Create a Person          | `people:write`   | Standard, with API writes approved |
| Create Time Off          | `time_off:write` | Standard, with API writes approved |
| Make an API call         | Key-dependent    | Existing key scopes and plan rules |

The read modules use HollyHR's safe public people, time-off, and reference
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 and grant only the scopes needed by your scenarios.
3. In Make, enter the workspace part of your HollyHR URL. For
   `https://acme.hollyhr.com`, enter `acme`.
4. Paste the API key once. Make checks `GET /me`, and HollyHR derives the
   organisation from that key. The app never accepts an organisation ID.

Use a separate read-only key for watch/search scenarios and a tightly scoped
write key for create scenarios where practical.

## Polling and pagination

The two Watch modules request up to 100 recently changed records in reverse
chronological order. Make combines each opaque resource ID with its
`updated_at` version, so a genuine later update can trigger while a repeated
poll of the same version cannot.

Search People follows HollyHR's opaque cursor until it reaches the scenario's
requested limit. Avoid enabling a Watch module during a bulk import that
changes more than 100 matching records inside one Make polling interval.
Complete the import first and then use the scenario for ongoing changes.

## Safe create retries

Both create modules require a **Source record key**. Map a stable unique value
from the source system, such as an employee, form-submission, or absence-request
ID. The app sends that value in HollyHR's `Idempotency-Key` header. If Make
retries the same request, 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. Make cannot bypass them.

## Make an API call

Make requires API-backed public apps to provide a universal API-call module.
HollyHR constrains its URL to the connected workspace under `/api`; enter a
relative versioned path such as `/v1/me` or `/v1/people?limit=10`.

The module cannot send the connection's bearer credential to another host.
Every call still passes through the key's scopes, plan entitlements, tenant
derivation, rate limits, and audit/request logging. Mutation routes still
require their documented idempotency and conditional headers.

## Data handling

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

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

## Revoke access

To stop one workflow, disable its Make scenario. 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

- **Connection failed:** confirm the workspace subdomain and replace any
  expired, revoked, or incorrectly copied key.
- **403 on a read:** add the exact missing read scope to a replacement key.
- **403 on a create:** the workspace must be Standard, public API writes must
  be approved, and the key needs the matching write scope.
- **No Watch bundle yet:** allow for Make's scenario schedule and create a
  fresh change after enabling it.
- **Duplicate protection replayed an older result:** use a different source
  record key for a genuinely different source event.
- **429 response:** Make preserves its rate-limit retry behaviour; reduce
  scenario frequency or wait for the reported limit window.

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