Import your company

Load a whole company (locations, teams and people with their managers) in one call, preview it, then commit. Re-run it any time: it updates what exists and creates what's missing.

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

1. Initialise the company#

On a new company, call org.setup.init once. It creates whatever is missing: the legal entity, a "Head office" location, the company root unit and your own person record. It's safe to call again.

curl https://api.bizisy.com/v1/org/setup.init -H "Authorization: Bearer $BIZISY_API_KEY" -H "Content-Type: application/json" -d '{}'

2. Build the payload#

org.setup.apply takes three lists. Items refer to each other by name (units, locations) and by work email (managers), in any order:

{
  "locations": [{ "name": "Porto", "country": "PT", "city": "Porto" }],
  "units": [
    { "name": "Engineering", "kind": "department" },
    { "name": "Platform", "kind": "team", "parent": "Engineering" }
  ],
  "people": [
    { "given_name": "Rui", "family_name": "Costa", "work_email": "rui@acme.com", "title": "CTO", "unit": "Engineering", "location": "Porto", "start_date": "2023-02-01" },
    { "given_name": "Bea", "family_name": "Santos", "work_email": "bea@acme.com", "title": "Engineer", "unit": "Platform", "manager_email": "rui@acme.com", "location": "Porto", "start_date": "2024-05-06", "contract_type": "permanent" }
  ]
}

• Matching: locations and units by name (case-insensitive), people by work_email. Existing records are updated; missing ones created.
• Unit kinds: division, department or team. Without parent, a unit sits under the company root.
• People may carry contract terms, legal_entity (a legal name) and custom fields by key. Pay is never set here, and payroll details are refused through a key.
• No manager means the team lead. A person without manager_email gets the lead of their unit as manager (team_lead_managers in the result counts them); send "manager_email": null for no manager. See The team lead as default manager.
• At most 250 people per call. Split bigger companies into batches; put managers in an earlier batch or the same one.

3. Preview#

Send it with ?dry_run=true:

curl "https://api.bizisy.com/v1/org/setup.apply?dry_run=true" \
  -H "Authorization: Bearer $BIZISY_API_KEY" -H "Content-Type: application/json" \
  -d @company.json

{
  "data": {
    "created": { "locations": 1, "units": 2, "people": 2 },
    "updated": { "locations": 0, "units": 0, "people": 0 },
    "warnings": []
  },
  "dry_run": true,
  "events": […]
}

If anything is wrong, the call fails with validation_failed and details lists every problem with its path (people[3].manager_email); nothing is written. Fix and preview again. Show the counts and warnings to whoever owns the data.

4. Commit#

The same call without dry_run, with an Idempotency-Key:

curl https://api.bizisy.com/v1/org/setup.apply \
  -H "Authorization: Bearer $BIZISY_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d @company.json

It all happens in one transaction: either every change is saved or none is. Each hire, unit and location is recorded in Activity, and the matching webhooks are sent.

From a CSV file instead#

If the data is a spreadsheet, send the CSV text to org.people.import_csv: first row is the header (given_name,family_name,work_email,title,team,manager_email,location,start_date,…), comma or semicolon separated, at most 1 MB and 250 people. Teams that don't exist become teams under the company root; locations and legal entities must exist. Preview with ?dry_run=true: if row_errors isn't empty, nothing is applied, and each error has its spreadsheet row number.

jq -Rs '{csv: .}' people.csv | curl "https://api.bizisy.com/v1/org/people.import_csv?dry_run=true" \
  -H "Authorization: Bearer $BIZISY_API_KEY" -H "Content-Type: application/json" -d @-

5. Invite people to sign in#

Imported people don't have logins yet. Invite them one by one with org.invites.create: Bizisy emails each person a sign-in link (through a key, the link itself is never returned). Or invite from People in Manage.