Skip to main content

Understanding Onboarding Schemas

Onboarding schemas let you declaratively define multi-step onboarding flows that provision an entire tenant setup — organizations, merchants, profile objects, access applications, and shareable links — from a single configuration. This page explains how the onboarding system works and the design decisions behind it.

For the full action specifications, output field tables, and configuration syntax, see the Onboarding Schema Reference.

What onboarding schemas solve​

When a new customer signs up, the platform often needs to create several related entities: an organization, a merchant, one or more access applications, shareable links for those applications, and profile objects to hold provider-specific data. Without onboarding schemas, each of these would require separate API calls with manually coordinated IDs.

Onboarding schemas solve this by letting you describe the desired end state declaratively. You specify what should be created and how entities relate to each other, and the system handles the sequencing, ID passing, and error handling.

Two levels of abstraction​

The onboarding system provides two ways to create entities, and understanding the distinction is important for choosing the right approach.

High-level actions (actions.*) are purpose-built workflows. create_organization doesn't just insert a row — it creates party records, customer records, and location records, then makes the new organization the active context for subsequent steps. create_access_application handles encryption key setup alongside the database record. These actions encapsulate multi-step processes behind a single declaration.

Database endpoints (db.v1.*) are thin wrappers around PostgREST API calls. They give you direct access to create any database record, but you're responsible for providing the right fields. Use these when no high-level action exists for what you need, or when you need precise control over the data being written.

The trade-off is convenience versus control. High-level actions handle complexity automatically (auto-injecting organization IDs, setting up encryption keys) but have fixed behavior. Database endpoints require more configuration but let you create any record type.

Field name differences​

This two-level design creates a practical quirk: high-level actions and database endpoints return different field names for the same concept. For example, create_access_application returns the application ID as a_id (a client-mapped name), while the equivalent db.v1.dsm_access_applications endpoint returns it as id (the raw API field name).

This matters when chaining actions — if you create an access application with a high-level action and then need its ID for a link, you reference {alias[0].a_id}. If you created it via the database endpoint, you reference {alias[0].id}.

Variable substitution​

Variables are the mechanism that connects wizard form inputs to onboarding actions and chains entity outputs between steps.

User input variables are the simplest and most common form. When a wizard page collects a field called org_name, you reference it as {org_name} in the onboarding schema. The system substitutes the user's input at execution time.

Entity reference variables connect steps together. When one action needs the output of a previous action — for example, creating a link for an access application — you use the {alias[index].field} syntax. The alias is the store_as value you assigned, and field is the output field name from that action.

Auto-generated aliases are available even without store_as. The system automatically stores outputs under the action's path (e.g. actions.create_organization[0]). Explicit store_as aliases are shorter and clearer, but both work.

Most onboarding schemas only need user input variables. Entity reference variables become necessary when you need to chain actions — typically when creating access application links that reference an access application created in an earlier step.

Automatic context injection​

Several fields are automatically injected by the system and should not be manually specified:

  • create_merchant receives party_id and customer_id from the current organization
  • create_access_application receives customer_id and org_id from the current organization

This design means create_organization must run before actions that depend on organization context. The system tracks the "current organization" and passes its IDs forward automatically, eliminating a common source of errors in manual API orchestration.

Execution order​

By default, all actions.* entries execute first, followed by all db.v1.* entries. Within each group, execution follows declaration order.

For most schemas this default is sufficient — you create an organization (action), then create profile objects (database endpoint). When you need fine-grained control — for example, creating a database record between two high-level actions — you can specify an explicit execution_order array that interleaves actions and database calls.