Understanding connected accounts

What it is

A connected account works like a standard Onboarded account. It has its own employees, placements, and tasks, its own dashboard users, and its own integrations. The difference is that it belongs to one platform account, usually held by a partner such as an ATS that offers Onboarded as the onboarding step in its own product. Each of the partner's customers gets its own connected account, and the platform account supplies much of its setup. See 📄 Understanding platform accounts for the partner's side.

The relationship runs one way. The partner's platform account can open and manage each customer's connected account. A connected account can't see its platform account or the other customers' accounts beside it.

If you remember nothing else: the partner's platform account decides what's shared, and the customer's connected account is where onboarding happens.

Why it matters

Most questions about a connected account come down to one thing: where did this come from, and where do I change it? A policy in a connected account might be the account's own, or a locked copy from the platform account that nobody in the connected account can edit. Knowing which tells you where to make the fix.

This matters most when:

• A connected account is missing a form, policy, or automation it needs.

• Someone in a connected account can't edit a policy or automation.

• You need to work with a connected account's employees or settings from the platform account or your API.

How it works

Creating and removing connected accounts

You create connected accounts from the platform account, in the connected accounts list, with New Connected Account. The form asks for basic company details such as Name, Business Email, and EIN. Your integration can also create them through the API with POST /api/v1/connected_organizations, using a live API key. The API calls them connected organizations. The dashboard calls them connected accounts.

Like every account, each connected account has a live side and a test side.

Deleting a connected account deletes all of its data and can't be undone.

What it gets from the platform account

When you create a connected account, Onboarded applies your platform account's default distribution modes to it. Every form, policy, and automation whose Default distribution mode isn't Don't distribute is sent to the new account. Custom attributes set to Auto-distribute to connected accounts are copied over too.

After that, how each distributed item follows the platform account depends on its distribution mode for this account:

• Auto Deploy. Every new version the platform account publishes arrives automatically. Policies and automations are locked: the connected account can't edit or delete them, though it can turn one off. Forms aren't locked. If the connected account publishes its own version of a form, the platform account sees Changed by connected account.

• Manual Deploy (forms only). Each new version arrives as a draft. The connected account can adjust it before publishing.

• No mode. A copy sent once with Deploy now, or kept after the platform account removed distribution, belongs to the connected account. It can edit it, and it no longer receives the platform account's updates.

Integrations work differently: nothing is copied. Your platform account decides which integrations each connected account can install, and the account installs them with its own credentials. Taking access away doesn't uninstall anything it already set up. See 📄 How do I let a connected account use an integration?.

See 📄 Understanding distribution to connected accounts for the full picture.

Branding can carry down too. If the platform account has a Dashboard Logo and the connected account doesn't have its own, the connected account shows the platform's logo in the sidebar in place of Onboarded's. Onboarded can also give each connected account its own custom subdomain, so that customer's dashboard and onboarding links use a branded address. Talk to your Onboarded team to set one up.

What it can do on its own

A connected account can build its own forms, policies, and automations from scratch, and it can edit any distributed copy that isn't locked.

A few things belong to the platform account only:

• Browsing the Compliance Library, and adding policies with Add from library. Connected accounts get library forms and policies through their platform account instead. See 📄 Understanding the Compliance Library.

• Distributing anything to other accounts.

How the platform account reaches in

From the platform account, you can work with a connected account three ways:

• Open it. Open the account from the connected accounts list and click Impersonate Account. You land in that account's dashboard, in whichever mode you were in, test or live. A red bar with the account's name sits at the bottom of the sidebar while you're there. Click it to return to the platform account.

• Call the API on its behalf. Send the account's ID in the Onboarded-Connected-Account-Id header with your platform API key. The Account id column in the connected accounts list shows the ID for the mode you're in.

• Receive its webhooks. Events in a connected account go to the connected account's own webhooks and to the platform account's webhooks.

The account's page in the platform account also has Automations, Forms, and Policies tabs, which show what the platform account sends it, in which mode, and whether the latest version arrived.

Users in the partner's platform account have full access inside every customer's connected account. A connected account's own users only see that account.

Example

Take the ATS from 📄 Understanding platform accounts, which offers Onboarded as the onboarding step in its product. One of its customers, Bellwether Health, signs on.

The ATS's integration creates Bellwether's connected account through the API. The ATS's I-9, W-4, and direct deposit forms and its onboarding policy default to Auto Deploy, so Bellwether has them on day one, and the policy is locked to the ATS's version. The handbook acknowledgment arrives on Manual Deploy, as a draft, so Bellwether's HR Engineer swaps in Bellwether's own handbook before publishing it.

Bellwether also needs a license verification form for its nurses that the ATS's other customers don't use. Bellwether's HR Engineer builds it inside Bellwether's account and adds it to a policy there.

A month later, Bellwether reports a typo in the instructions on the direct deposit form. Rather than each customer fixing its own copy, the ATS fixes it once in the platform account, and the corrected version reaches Bellwether and every other customer on Auto Deploy.

Read next

• 📄 Understanding platform accounts

• 📄 Understanding distribution to connected accounts

• 📄 How do I distribute a form to connected accounts?

• 📄 How do I distribute a policy to connected accounts?

• 📄 How do I distribute an automation to connected accounts?

• 📄 Understanding the Compliance Library