PSBI + BambooHR

Set up BambooHR for background checks

Approve the connection, choose the field that starts a check, and set up the status field PSBI writes back to.

Overview

Integration details

Property	Value
Integration type	API \| Webhook-triggered
Authentication	OAuth 2.0, authorized once by a BambooHR administrator
Sync frequency	Event-based — fires when your chosen field changes
Fields read	Employee identity and contact details, job title or position
Fields written	Status on one designated custom field

Required roles

Your BambooHR administrator

Choose the field and value that means "ready for a background check"
Create one custom field for PSBI status updates
Approve the PSBI authorization request
Share your job-title-to-checklist mapping

PSBI

Register the connection for your company
Subscribe to update notifications on your chosen trigger field
Map job titles and positions to the correct screening checklist
Test the connection and review a dry run with you

Before you begin

You'll need:

A BambooHR administrator who can create webhooks, view field configuration, and approve API access.
The exact field and value that should trigger a background check — an existing status field, or a new one your administrator creates.
The job titles or positions you screen, and the PSBI checklist each one should use, or one default checklist if every hire follows the same workflow.
A name for the custom field PSBI will write status updates into — for example, "PSBI Background Check Status."

Configuration steps

BambooHR administrator

Authorize PSBI

1Your implementation lead sends you an authorization link. Open it while signed in to the BambooHR account that administers your hiring workflow.
2Review the request. PSBI asks to read employee records and subscribe to update notifications on the field you choose in step 2.
3Approve the request. Access is scoped to your company and can be revoked by you at any time.

The link is short-livedOpen it promptly. If it expires, ask your implementation lead for a fresh one — the same link cannot be reused.

BambooHR administrator

Create the trigger field

1Decide what "ready for a background check" means in your account — many BambooHR accounts already have a status or stage field that fits, such as Employment Status or Onboarding Status.
2If none of your existing fields cleanly signal this, add one. A simple dropdown works well.
3Tell PSBI the exact field and the value that means "start screening."

Renaming is safe; changing values is not — without telling us firstPSBI matches this field by its underlying field ID, not its display name, so relabeling it later will not break the connection. Adding or renaming the specific value that triggers screening does need to be shared with PSBI, because that value is matched exactly.

BambooHR administrator

Create the PSBI status field

1Add one custom field — for example, "PSBI Background Check Status" — for PSBI to write status updates into.
2Save, then tell PSBI the field exists. PSBI confirms the exact field with you during setup rather than guessing a name.

This field must exist before the connection goes liveA missing or misnamed field silently fails to update — BambooHR does not surface an error, so it needs to be confirmed by PSBI before you rely on it.

Shared decision

Send the mapping to PSBI

1Share your chosen trigger field and the exact value that means "start screening."
2Share a default PSBI checklist, and any job-title-to-checklist overrides.
3Share the name of the custom field PSBI should write status into, and an implementation contact for testing.

BambooHR value	PSBI destination
Registered Nurse	Clinical Hire Checklist
Administrative Assistant	Standard Hire Checklist
All other titles	Default checklist

Confirm exact titlesIf a job title has no specific override, PSBI uses the default checklist agreed during setup. Small spelling differences can prevent an override from matching.

Validation

Validate before launch

PSBI will validate the connection, test the trigger, and review the mappings with you before activating the feed. Do not go live until the full path works once.

TriggerThe field and value fire only when intended.

RoutingA sample person maps to the correct checklist.

WritebackStatus updates appear in the PSBI field on that person's BambooHR record.

IdempotencyNo person is enrolled twice.

Once it is running

Your team changes the trigger field to the agreed value on a person's record. PSBI reads the record, enrolls the person in the matching checklist, and writes status updates to the custom field you created — all without leaving BambooHR.

Data sync

When	Direction	What moves
Trigger field changes	BambooHR → PSBI	BambooHR sends an employee-update event. PSBI acts only on records where the monitored field changed to the agreed value.
Request is created	BambooHR → PSBI	The employee's identity and contact details, and their job title, which selects the checklist.
Screening progresses	PSBI → BambooHR	Status is written to the custom field created in step 3.

What PSBI never writes into BambooHRDisclosures, consent records, personal identifiers collected during intake, and the contents of the completed report. BambooHR holds a status only.

Troubleshooting

I can't find webhooks or approve the authorization request.

Webhook and API authorization in BambooHR require administrator access. Ask your BambooHR account owner to complete this step, or grant the needed permissions.

A person reached the trigger status and nothing happened in PSBI.

Confirm the field and value match exactly what was agreed during setup, and that the person's record has the name and email needed to enroll them. Send us the employee's BambooHR ID and PSBI can trace the event.

Status isn't showing up in BambooHR.

Confirm the custom field still exists and matches the field name shared during setup — a renamed or deleted field will silently stop receiving updates. PSBI can re-confirm the field ID with you.

The wrong checklist was selected.

Compare the person's job title against the mapping agreed during setup. Titles are matched exactly, so a renamed or newly added title needs to be shared with us before it's used.

We changed our trigger field, a job title, or added a new position.

Tell PSBI before relying on the new value. Trigger and mapping changes should be reviewed and tested so people don't enter the wrong checklist, or none at all.

Need a hand?

Contact your PSBI implementation lead. Include:

Your BambooHR company name
The affected employee or job title
The behavior you expected and what you saw instead

Do not include authorization links or applicant-sensitive data in the message.