Users API

Users API primarily works with a user’s membership in a company space. Responses and validations therefore combine data from the global user and that user’s membership in the space.

What to use it for

Users API is the bridge between your personnel records and people’s membership in the company space. It belongs wherever someone would otherwise retype people by hand.

• A new hire is entered once, in the HR system. HR creates a new employee. Your system creates them in the company space through Users API, which establishes an active membership. It uses personal_id as the key, because an e-mail can change over time. Nobody creates the same person twice.
• Leaving is archiving, not deletion. An employee leaves and the HR system archives them. The membership is revoked internally, but the record does not vanish. When they come back a year later, a restore returns the membership and no second account appears.
• A reorganisation writes in the new managers. A department gets a new head. Your system updates the supervisor for every member, referencing them by internal ID, personal_id or e-mail. No clicking through dozens of people by hand.
• A nightly comparison of two registers. A script lists the users, narrowed by state if needed, and compares them with HR. Whoever is missing gets created; whoever has left gets archived. Differences are not left for the audit.

Before you start, agree the primary identifier with the other side. The rest of the page explains why for HR it tends to be personal_id, and which edge cases you will meet.

Supported tasks

Task	Note
List users	Supports filtering by state and sync_status.
User detail	Can be looked up by internal ID or personal_id.
Create user	Creates active membership in the company space.
Update user	Changes user data and membership data.
Archive	Internally revokes the membership.
Restore	Returns revoked membership back to active use.

Identifiers

Integrations need to agree whether the primary identifier is:

• internal ID,
• personal_id,
• e-mail.

E-mail is readable, but it may not be stable. personal_id is often better for HR integrations.

Edge cases

• Archiving is not physical deletion.
• Changing full_name can affect other memberships of the same global user.
• Supervisor can be referenced by internal ID, personal_id, or e-mail.
• Last-owner validation protects the company space from losing its owner.