Developer journey

This is the red carpet from idea to a live App. Every step is paved for you — shared foundation, reference samples, AI skills, and automated review and promotion.

An App can be a custom automation (a form-driven workflow, a Factorial API job, a CSV/report export, an email notification, a scheduled task) or a marketplace integration (sync between Factorial and an external system, built on the integrations framework). The journey below is the same for both.

The journey has two phases: building the App and activating it for a customer.

For integrations, data flows in two directions:

• Inbound (Pull) — a scheduled process periodically fetches data from the external system and creates or updates records in Factorial.
• Outbound (Push) — a Factorial webhook fires when something happens in Factorial (e.g. a new employee is created) and the process pushes that data to the external system.

Both directions can live in the same App. Each direction is a separate process but business logic can be shared through modules.

Building the App

1. Request access — Developer. Fill the request-access form: contributor type and name, developer email, why you want to build on Factorial Code, and your Factorial contact. This is a one-time request to join the platform — not per App.
2. Get access approved — Factorial team. The team is notified and approves your request. Your development team is created and you receive an email to set up your account and sign in to the developer console.
3. Create an App — Developer. In the console, create a new App: its name, what it does, your language (JavaScript or Python), and the OAuth scopes it needs. Scopes are optional — an App that doesn’t call the Factorial API needs no OAuth application, and you can add scopes later from the App’s OAuth tab. The App is provisioned automatically — no approval step — and a development workspace dev-{app-id} is created, inheriting base-app (and base-integration-app for integrations). Create as many Apps as you need this way.
4. Clone the workspace locally — Developer.

   pnpm install -g @factorialco/fcode-cli
   fcode clone dev-{app-id}

   Clone sets up the Factorial Code AI skills by default, so your coding assistant knows the platform from the first prompt (pass --skipSkillsSetup to opt out). Base modules are available immediately: FactorialClient, fc-utils, checkWebhookChallenge, setupWebhook.
5. Build the App — Developer. Use your favourite AI agent — the skills carry worked examples and references, and the samples show complete Apps. Point it at the relevant material too: the Factorial platform docs and, for integrations, the external system’s API docs or specs. Build on the published SDKs for all Factorial API access.
6. Test locally — Developer. Run any process on your machine with fcode run {process-slug} — no deploy required. You may also build a test suite.
7. Push to the cloud — Developer. Sync your local workspace up to dev-{app-id} with fcode push.
8. Test from Factorial — Developer. Exercise the App from a Factorial demo environment, where the OAuth token is provided out of the box — no credential handling in your code (see OAuth & API token).
9. Request a release — Developer. Ask for a release of your development code. The requested version is published as a workspace version on your dev-{app-id} workspace — every process and module is snapshotted under that tag, with module imports pinned. The Factorial team reviews it and CI checks run automatically.
10. Promote to production — Factorial team. A prod-{app-id} workspace is created and the released workspace version is promoted to it, typically pointing the production alias at the released tag. Your App is now live for customers — and listed on the Factorial Marketplace. 🎉

Activating it for a customer

11. Request the integration — Customer / Factorial admin. Submit an install form with the customer_id and the integrations to activate.
12. Workspace provisioned — Platform, automatic. A deploy-{installation-id} workspace is created. Repeatable — add integrations anytime.
13. Configure the integration — Customer / Factorial admin. Run the {vendor}-setup process and provide the credentials or configurations the app may need. On submit, this will be saved, and Factorial webhook subscriptions or schedules are created.
14. Integration is live — Platform, ongoing. Inbound data flows in via the scheduled poll process; outbound events flow out via the webhook-triggered push process.