When to use the integrations framework?

The integrations framework is Factorial’s managed way to sync data out of Factorial into an external system — payroll software, ERPs, and similar. 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 the feedback end users get on every sync — success, errors, or a missing configuration that needs attention — surfaced right in Factorial instead of failing silently.

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

• Employee compensation
• Expenses
• Employee updates — for example, leaves.

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

When to use it

Use the integrations framework — and tick “This App implements the Factorial integrations framework” when you create the App in the console — when your App’s job is to push one of the supported capabilities (compensation, expenses, employee updates) from Factorial to an external system. This is the marketplace integration archetype.

When not to use it

Build a regular custom App instead when your App:

• runs a custom automation — forms, scheduled jobs, notifications, reports/exports;
• syncs inbound (external system → Factorial) rather than outbound;
• works with data types the framework doesn’t cover.

These don’t need the framework — leave the checkbox unticked. See Building Apps for the two archetypes.

The foundations we expose

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.
• 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.