ORGONAUT
Login Signup
Docs
Imports and setup
CSV field reference

CSV field reference

This reference covers the fields Orgonaut currently understands in import files, plus the validation rules that most often block a run.

Supported CSV formats

  • BambooHR export format
  • Orgonaut canonical CSV format

Orgonaut lowercases and normalizes headers internally, so common variants like First Name and first_name are handled.

For BambooHR imports, the parser also accepts directory-style headers such as Name, PersonID, SupervisorID, Work Email, and Email Address.

Minimum fields for a reliable import

At minimum, include:

  • first_name and last_name (or a combined BambooHR name column)
  • department or department_name
  • job_title
  • manager_email (optional for top-level leaders)
  • one durable identity for each person row:
    • email, or
    • source_hris + source_hris_id, or
    • for BambooHR imports, employee_id / PersonID

For BambooHR imports, Orgonaut promotes PersonID to the actor's canonical Bamboo source identity and uses that for reimports and manager linking. For generic CSV imports, email remains the default identity unless you explicitly provide source_hris and source_hris_id.

Guest conversation identity

When modelling an organisation with the Orgonaut plugin, keep any known email and HRIS identity. A guest OrgSpec actor can supply extensions.orgonaut.source_hris and extensions.orgonaut.source_hris_id together; email is optional with that pair. Never guess an email or a source record ID. People whose identities are still unknown can stay partial in the guest model. Saving gives those model records stable internal draft identities and leaves unknown contact details blank.

Claims use the same source-aware actor matching and conflict checks as CSV imports. Source identity and email must identify the same person. Supplying the same employee ID from two different HRIS sources identifies two distinct source records.

Ordinary OrgSpec uploads also allow people without email. Provide a known HRIS pair through extensions.orgonaut, or keep the stable actor id; Orgonaut uses orgspec + that ID when no HRIS pair is supplied. Reimports match the same source identity, preserve known email when omitted, and reject conflicting source/email matches. The OrgSpec CLI preserves the same identity pair when exporting an Orgonaut bridge.

Core person and org fields

  • email: contact email and compatibility identity when present
  • first_name, last_name, or name
  • department_name or department
  • team_name or team
  • job_title or job title
  • source_hris
  • source_hris_id
  • manager_email (also accepts common manager / supervisor email headers)
  • employee_id (also accepts BambooHR PersonID)
  • manager_employee_id (also accepts BambooHR SupervisorID)
  • manager_first_name, manager_last_name (optional disambiguation)

When a BambooHR file provides SupervisorID, Orgonaut stores each row's PersonID on the actor as source_hris = bamboohr and source_hris_id = PersonID, then performs a second pass to match SupervisorID against that imported source ID.

Capacity and allocation fields

  • fte
  • allocation_pct

Validation rules currently enforced:

  • fte: 0.01 to 3.00
  • allocation_pct: 0 to 300

Compensation and currency fields

  • currency
  • base_salary_cents
  • daily_rate_cents

If compensation is provided, currency must exist and be active in tenant settings (/settings/currencies).

Effective-date and status fields

  • valid_from (or hire date in BambooHR-style files)
  • start_date
  • end_date
  • status
  • location

Use ISO-style dates (YYYY-MM-DD) wherever possible for predictable parsing.

Canonical Orgonaut header set

Canonical headers you can use directly:

  • email
  • first_name
  • last_name
  • department_name
  • team_name
  • job_title
  • source_hris
  • source_hris_id
  • manager_email
  • employee_id
  • manager_employee_id
  • manager_first_name
  • manager_last_name
  • allocation_pct
  • fte
  • currency
  • base_salary_cents
  • daily_rate_cents
  • valid_from
  • start_date
  • end_date
  • location
  • status

Extra columns

Unrecognized columns are not discarded. They are preserved as metadata on imported entities where supported.

This is useful when your source CSV carries local attributes you still want retained for later analysis.

Preflight checklist

Before uploading:

  • ensure each row has either a valid email or a complete source identity
  • ensure emails and source identities are unique inside the file
  • normalize department/team naming conventions
  • verify currency codes exist in settings
  • confirm manager references point to real rows