Skip to content
Local environment Preproduction — not production data

When to use the integrations framework?

The integrations framework is Factorial’s managed way to sync data between Factorial and an external system — payroll software, ERPs, and similar — out of Factorial or, for imports, into it. For an outbound sync, Factorial fires the events; the framework handles webhook delivery, per-item status reporting, retries, and per-customer isolation, so your App only implements the mapping to the target system.

A key benefit is what the customer’s users get in Factorial. A sync run starts on a schedule, when a user starts it from Factorial’s UI (a sync or import button), or when your App’s own code starts it through the API (syncRuns.create), so a trigger of your own still works; either way they see there that everything synced, or which items failed and why, or a missing configuration that needs attention, instead of the sync failing silently. Imports into Factorial work the same way.

It currently supports these capabilities (the Factorial data types it can sync):

  • Employee compensation — out of Factorial (payroll variables) and into it (payroll results).
  • Expenses — in either direction.
  • Finance vendors and financial documents — imported into Factorial.
  • Employee updates — for example, leaves; in either direction.

For the full specification, see the Factorial integrations framework docs.

Use the integrations framework — and choose Integrations-framework app in the App type step when you create the App in the console — when your App’s job is to push one of the supported capabilities from Factorial to an external system, or to import them into Factorial from one (payroll results, expenses, vendors): see Tracking imports into Factorial. This is the marketplace integration archetype. In that step, pick the data the App syncs (leaves, expenses, worked time, compensations): the OAuth scopes step then opens with the scopes the framework and those data types need already selected, so you don’t have to work out which scope guards which endpoint.

Build a regular custom App instead when your App:

  • runs a custom automation — forms, scheduled jobs, notifications, reports for people to read (dashboards, digests, emailed summaries);
  • works with data types the framework doesn’t cover.

These don’t need the framework — keep Standard app as the App type. See Building Apps for the two archetypes.

You don’t implement the framework’s plumbing yourself. We expose its building blocks as workspaces you inherit and copy (in both JavaScript and Python):

  • base-integration-app — the generic OutboundSync orchestrator that drives the sync loop and reports per-item status back to Factorial. It also ships the inbound modules (InboundRecordSync), see Tracking imports into Factorial.
  • integration-app-sample — a vendor-neutral sample integration to copy as your starting point, with both file-upload and per-item-API delivery flavors.

See Sample apps & foundation for what each provides, and the Developer journey for the end-to-end flow.