API overview

What the Integration API is for, the calls it offers, and the limits it holds to.

What this API is for

Keeping a company’s employee roster in step with the system that already owns it — an HRIS, usually. When somebody joins, your system invites them; when they leave, it archives them; in between, it can read where every invitation stands, without anybody sharing a Portal login.

Six calls do that work. All of them are POST, all take and return JSON, and all live under /api/public/v1. The reference gives each one in full.

Invitations. Invite a person creates one invitation from a corporate email and a name. Invite a batch of people does the same for up to 20 rows at a time, reporting per row whether it was created or skipped and why; re-submitting the same batch creates no duplicates. A batch emails nobody unless it sets SendInvitations — importing a roster and inviting the people on it are separate decisions. Re-send an invitation delivers an existing one again.

Employees. List employees returns one page of the company’s records, newest activity first, with filters — free text, status, sphere, archived or active — travelling in the body rather than the URL, so corporate addresses stay out of access logs. Archive an employee records that somebody has left, and Restore an archived employee takes them back out of the archive when they return. Both are idempotent, and both say which of the two happened.

The corporate email address is the key that matches a person across the two systems; there is no separate external id to keep. A record tells you the state of the invitation and of the person’s consent — whether they were invited, when, whether they have granted access, whether they carry a Spherum token — and carries a link to their card in the Portal.

What it never does

It never returns what is on a card. No emergency contact, no phone number, no field value of any kind, under any condition. The PortalUrl on a record is an address, not access: opening it still needs a signed-in Portal session, and the card is still shown only to somebody the owner allowed.

It never revokes access. Archiving says “this person is no longer with us” — it is a statement about employment, not a switch on the person’s card. Closing access is the person’s own act, and restoring a record does not undo it: somebody who returns has to be invited again and has to grant again.

It never returns the audit trail. The compliance record stays in the Portal, where it is read by the people accountable for it.