Skip to main content

​
After this article

You will be able to connect Justworks to Lumos via the Merge.dev partnership to sync employee data, and optionally use Justworks as a source of user data in Lumos.

​
Capabilities

As a Merge.dev-brokered HRIS integration, Lumos reconciles account status from the HRIS user status: Active maps to Active, Inactive maps to Suspended, Pending maps to Staged, and Deleted (no longer returned) maps to Deprovisioned. When Justworks is the User Source, employment status is reconciled separately: Active maps to Active, Inactive maps to Inactive, Pending maps to Staged, and Deleted maps to Inactive. Attributes available for mapping in User Sources include Manager, Team, Title, Employment Type, Start Date, and Termination Date. Per-app field support varies.

​
Required plan and roles

  • Justworks permissions: the connecting Justworks user needs the following permissions, each required by Merge to read HRIS data:
    • Edit Company Settings: required to view Company Information, Office Information + Location, and Department Information. Justworks requires EDIT access just to view this data, but Merge will not actually edit any settings.
    • Manage Employees: view Employee Information, and access the Employee Census Report and Work History Report.
    • View all employee information: view Employee Information, and access the Employee Census Report and Work History Report.
    • View basic employee information: view Employee Information, and access the Employee Census Report and Work History Report.
    • Upload and View all Documents: access the Employee Census Report and Work History Report.
    • View Invoices and Reporting: access the Employee Census Report and Work History Report.
  • Permission scoping: this is a read-only HRIS integration. Lumos syncs employee data but does not provision or change anything in Justworks, despite the Edit Company Settings requirement above.

​
Read-only access vs provisioning

Is read-only possible? Yes. This connector is read-only in every configuration. Lumos syncs employee data through Merge.dev but never provisions or changes anything in Justworks. What read-only requires. The Justworks permissions listed above (Edit Company Settings, Manage Employees, and the employee-information and reporting permissions), connected through the Merge.dev pop-up. Follow the steps below. Watch out for. The Edit Company Settings permission is required only because Justworks won’t expose company, office, and department data for viewing without it. Merge does not use it to write anything. Missing any of the other listed permissions results in incomplete employee or census data rather than a connection failure.

​
Instructions

Phase 1: Prepare Justworks
  1. Confirm your Justworks user has all the permissions listed above.
Phase 2: Connect in Lumos
  1. Click the Justworks card in your Lumos integrations (reconnect an existing card or add a new one).
  2. Click Connect Justworks.
  3. Follow the instructions in the Merge pop-up that appears to finish connecting.
  4. After connecting, you can set Justworks as a source of user data via the Source of Truth settings.

​
Troubleshooting

Connection succeeds but company/department data is missing. Confirm the connecting user has Edit Company Settings in Justworks. Justworks requires EDIT-level access for Merge to read company, office/location, and department information, even though nothing is edited. Employee data is incomplete. Verify all six permissions listed above. The census and work-history data require the report-related permissions (Manage Employees, View all/basic employee information, Upload and View all Documents, View Invoices and Reporting).