REST API

What it is

The CorpHands REST API lets your HR system, data warehouse or internal tools work with your CorpHands data. Every request uses an API key that belongs to your workspace and carries only the permissions you chose.

Typical Gulf use cases are pushing employees from Workday or SAP, and pulling approved volunteer hours into a group sustainability or BI dashboard.

What you can use it for

• GET /api/v1/employees (List employees): email, name, role, department, job title, employee number, active, joined date. Filter with active=true|false.
• POST /api/v1/employees (Create, update and deactivate employees): up to 5,000 people per request, matched by email; send "active": false to deactivate.
• GET /api/v1/activities?from=YYYY-MM-DD&to=YYYY-MM-DD (Read activities): activities with sign-up counts.
• GET /api/v1/hours?year=2026 (Read approved volunteer hours): approved hour records only.
• GET /api/v1/reports/summary?year=2026 (Read the yearly summary): the year's headline figures, from approved hours only.

How to do it

Create an API key

1. Open API keysGo to CSR workspace → Integrations → API keys.
2. Name it and choose permissionsGive the key a name, for example “Workday integration”, and tick only the Permissions it needs.
3. Copy the key onceSelect Create key. The key (corphands_live_…) is shown only once. Store it in your secrets manager. CorpHands keeps only a hash.

Make your first call

1. Send the key as a bearer tokenExample: curl -s "https://your-corphands-address/api/v1/employees?limit=50" -H "Authorization: Bearer $CORPHANDS_KEY"
2. Page through resultsUse limit (1–500, default 100) and offset.
3. Handle errorsErrors return {"error":{"code":…,"message":…}} with 401 (bad key), 403 (missing permission, plan or inactive subscription), 429 (rate limit) or 400/413 (bad or too large body).

Tips and good practice

• Give each integration its own key with the fewest permissions. Revoke a key at any time with Revoke.
• Limits: 120 requests per minute per key and 25 active keys per workspace.
• Use "deactivate_missing": true in a POST only when you send your full employee list. Roles sent through the API can only be employee or manager.
• Every API call that changes data is written to the audit log, and the Last used column shows when each key was last used.

Questions