Hire someone, end to end

From an open role to a first day: plan the position, hire into it, invite the person and follow their onboarding. Every step can be previewed with ?dry_run=true, and every step shows in Activity.

You need a Manage key of an owner, admin or HR member.

1. Plan the role#

Create an open position (skip this if you hire without one):

curl https://api.bizisy.com/v1/org/positions.create \
  -H "Authorization: Bearer $BIZISY_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"title": "Product Designer", "unit_id": "u2", "reports_to_person_id": "p2", "target_start_date": "2026-11-02"}'

The result's id is the position. Ids of units and people come from org.units.list and org.people.list. The budget (pay_range) is set in the app, never through a key.

2. Hire#

org.people.hire adds the person with their first job. With position_id, the hire fills the position. Preview first:

curl "https://api.bizisy.com/v1/org/people.hire?dry_run=true" \
  -H "Authorization: Bearer $BIZISY_API_KEY" -H "Content-Type: application/json" \
  -d '{"given_name": "Bea", "family_name": "Santos", "work_email": "bea@acme.com", "title": "Product Designer", "start_date": "2026-11-02", "unit_id": "u2", "manager_id": "p2", "position_id": "pos1", "contract_type": "permanent"}'

Leave out manager_id and the team lead of unit_id becomes their manager (manager_default in the result says so; send null for no manager): see The team lead as default manager. A future start_date makes them pre_hire until that day. Then commit the same call without dry_run, with an Idempotency-Key. Bizisy sends person.hired and position.filled webhooks, and starts the onboarding checklists that start by themselves for new hires.

3. Invite them to sign in#

curl https://api.bizisy.com/v1/org/invites.create \
  -H "Authorization: Bearer $BIZISY_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"person_id": "<the new person id>", "role": "member"}'

Bizisy emails the person a sign-in link (reply-to you). email.status says whether it was sent; through a key, url is null: the link is a credential and only goes to the person. The link expires in 14 days. When they accept, member.joined is sent.

4. Follow onboarding#

org.checklists.runs.list with person_id shows their checklists and progress; tasks are ticked by their assignees in Bizisy, or with org.checklists.tasks.set_status. checklist.completed is sent when every task is done or skipped.

When it doesn't go to plan#

• They didn't start. org.positions.reopen reopens the position.
• A detail was wrong. Fix the job row with org.people.correct_job, or the profile with org.people.update_profile.