Integrating with HRIS and identity systems

Introduction

This article answers common questions when connecting a human resources information system (HRIS) or identity provider to Firstbase. For API setup and authentication, see Firstbase API: What's available and how to use it. For endpoint reference, see developers.firstbase.com.

Common integration use cases

The most common HRIS and identity integrations include:

• Onboarding: When a person is created in your HRIS or identity system, create them in Firstbase.
• Updates: When employee details change (name, email, address, package), update the person record in Firstbase.
• Offboarding: When someone leaves, start the offboarding workflow in Firstbase and coordinate equipment returns.

What triggers account creation?

Common triggers include signing an offer letter, completing a background check, reaching a date-based milestone (for example, two weeks before start date), or creating an account in your HRIS or identity provider.

What information is required to onboard employees?

When integrating directly via the API, you typically need:

• First name and last name
• Primary email address (usually personal email before the employee has a work inbox)
• Secondary email address (usually work email, when available)
• Mailing address (at minimum, the employee's country)
• Employee start date
• Package assignment (look up package IDs with GET /api/v1/packages — see List packages on the developer site)

Create people with POST /scim/v2/Users. See the Create person reference for the full schema.

Are accounts created before employees have work email?

Generally, yes. Most customers onboard employees before their start date. Set the personal email as the primary login email (userName in SCIM) so the employee can access Firstbase before their corporate inbox exists.

How does ordering work during onboarding?

Most customers use one of two package types:

• Standard packages: The employee chooses equipment from configured options after logging in.
• Automatic order packages: Equipment is ordered automatically when the person is assigned to the package.

Automatic order packages:

• An order is placed immediately after successful account creation.
• You must submit a complete mailing address in the create-person request.
• Automatic packages only support shipping to the employee's address. Office and flexible shipping options are not available.

For more on package shipping options, see How to Create and Manage Packages.

Offboarding triggers and timing

Offboarding starts as soon as Firstbase receives an offboarding request. For involuntary terminations, ensure internal processes account for this timing before the API call is made.

Recommended: Use POST /api/v1/people/{personId}/offboard when someone is leaving. This gives you control over return type, items to return, and address confirmation. See Offboard person.

Identity provider integrations: SCIM DELETE /scim/v2/Users/{id} also triggers offboarding but does not let you specify per-item return handling. Use this path when departures are driven automatically from your IdP.

Should we store the Firstbase person ID?

Yes, if your integration will update or offboard people later. Store the person ID returned from POST /scim/v2/Users, or look it up with GET /scim/v2/Users filtered by userName or email before sending updates or offboarding requests.

Note on Okta Workflows templates

Legacy Okta Workflows templates for Firstbase are deprecated. Prefer direct integration with your HRIS or identity provider using the Public API or SCIM. If you need help designing an integration, contact your Customer Success Manager.