# PeopleBook Developer API

Base URL: https://peoplebook.wcreatesdigital.com/api/v1
Version: v1 — read API. Public documentation; company data requires authorisation.

## Get started
Company owner: sign in → Settings → AI connections → Other MCP client. Name the connection for the external system, select Read only and grant consent. Under Advanced settings choose expiry and explicitly allow payroll if required. Generate a private access key and store it server-side. The same key works for the read API.

curl 'https://peoplebook.wcreatesdigital.com/api/v1/companies' \
  -H "Authorization: Bearer $PEOPLEBOOK_API_KEY"

Use companyId from companies as company_id on all other endpoints.

curl 'https://peoplebook.wcreatesdigital.com/api/v1/employees?company_id=YOUR_COMPANY_ID&offset=0' \
  -H "Authorization: Bearer $PEOPLEBOOK_API_KEY"

## Endpoints
GET /api/v1/companies — Authorised companies. Response key: companies. Fields: companyId, name, mode, payrollAllowed.
GET /api/v1/summary — Company summary. Response key: company. Fields: Company identity, activeEmployees, pendingRequests, mode.
GET /api/v1/employees — Employee directory. Response key: employees. Fields: id, number, name, email, department, designation, branch, start_date, end_date, active, employment_type, pay_basis, weekly_hours.
GET /api/v1/leave-balances — Leave balances. Response key: balances. Fields: employee_id, leave_type, year, entitlement, pending, used, available.
GET /api/v1/requests — Request summaries. Response key: requests. Fields: id, employee_id, kind, title, start_date, end_date, leave_type, units, amount_cents, status, version.
GET /api/v1/attendance — Attendance records. Response key: attendance. Fields: id, employee_id, in_at, out_at, break_minutes.
GET /api/v1/shifts — Roster shifts. Response key: shifts. Fields: id, employee_id, title, starts_at, ends_at, break_minutes, published.
GET /api/v1/payroll — Payroll summaries. Response key: payroll. Fields: id, period, status, payment_status, totals; amountUnit: SGD integer cents.

All except companies require company_id UUID. Lists except companies accept offset (integer 0–10000, default 0); summary has no offset. Page size 50; follow nextOffset until null. Restart a full reconciliation if records change during offset pagination; there is no snapshot or updated-since filter.

## Security and limits
Authorization: Bearer pbkey_… . No public signup for keys, OAuth client registration or client-side credentials. Owner consent, company scope, expiry and revocation apply on every call. Payroll requires separate payroll consent. Reads exclude identity numbers, bank details, camera images, GPS and device secrets. Company-scoped calls share the connection's 60 calls/minute allowance with MCP; company discovery is not counted in this allowance. No CORS access for external browser apps. Use a server-side adapter.

## Accounting and payroll
External accounting and payroll software can pull directory, attendance, leave/request summaries and consented payroll summaries through an adapter. No built-in connector is implied for any vendor. Map PeopleBook company and employee IDs to external IDs, use SGD integer cents and explicit timezone offsets, deduplicate by stable record ID, reconcile record status, and keep sync logs in the adapter. Payroll totals are summaries, not payslip lines or bank files. Drafts must not trigger postings or payments. The current payroll engine is draft-only; production finalisation and automatic posting are not available. No generic write-back, outbound webhook, payroll calculation API or payment API is offered. SumBook has its own company linking and account-mapping flow in Settings; it is separate from these read keys.

## Device gateway
curl 'https://peoplebook.wcreatesdigital.com/api/attendance/device' \
  -H "Authorization: Bearer $PEOPLEBOOK_DEVICE_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"device_id":"YOUR_DEVICE_ID","validate_only":true,"events":[{"event_id":"terminal-01-0001","employee_number":"A0001","direction":"in","occurred_at":"2026-10-17T09:00:00+08:00"}]}'

Device keys are separate from API keys. HR/admin registers and enables a scanner in Attendance settings and obtains its device ID/key. GET /api/attendance/device?device_id=UUID checks credentials without creating a record. POST accepts 1–100 events and up to 50,000 characters/bytes (the request must satisfy both checks). Fields: event_id (nonblank, max100), employee_number (nonblank, max100), direction (in/out), occurred_at (ISO datetime with timezone). validate_only:true checks credentials and format, not employee mapping or punch sequence, and returns written:false. For real ingestion omit validate_only or set false; inspect every results item (including review errors), retry using original event IDs and keep acknowledgements. Door unlock alone is not attendance: the adapter must identify an employee and explicit direction. Vendor cloud API/SDK or a local gateway is required; universal lock support is not included. Do not send biometric templates.

## MCP
Private compatible clients: POST https://peoplebook.wcreatesdigital.com/api/mcp with Bearer key, application/json and MCP JSON-RPC. Use tools/list for exact schemas. Managed ChatGPT/Codex linking uses the PeopleBook plugin and its supplied managed endpoint, not a private key. READ denies writes, CONFIRM queues owner review and DIRECT enables only supported HR record creation after explicit consent. MCP cannot pay payroll, approve claims/leave, delete data or change access.

## Errors and testing
Read API errors use {error:string}. 400 invalid fields; 401 missing/malformed key; 403 inactive/revoked/expired/cross-company or payroll consent missing; 404 unknown resource; 429 rate limit (Retry-After:60); 503 temporary failure. A revoked/expired key returns an empty companies array on discovery. Refresh no credentials automatically: ask the owner for a replacement. Retry 429/503 with bounded exponential backoff; do not retry validation/auth errors blindly. Device errors and MCP envelopes follow their own documented contracts.
No separate hosted sandbox is available. Use a dedicated test company and synthetic records, with its owner's permission. The examples contain placeholders, never production credentials.