# Agency client onboarding

> When a deal is won, create a client space, share it and add the starter boards.

Source: https://mockflow.com/developers/examples/api/client-onboarding

An agency signs a new client and the same setup follows every time: a place for the project, the account team added, the client invited, and a kickoff board ready before the first meeting. This example does all of it from one command, so your CRM's "deal won" automation can run it.

[**Download the code**](/developers/assets/examples/mockflow-client-onboarding.zip) (Node.js 18 or later, no packages)

## What it creates

- A space named after the client and the project, such as "Northwind Coffee: Website redesign".
- The account team in the space as admin or editor, and the client's people as reviewers, who can view, comment and export.
- A **Kickoff workshop** board with an agenda, a preparation checklist and a mind map of project goals.
- A **Project brief** board with a brief template the client fills in, and an empty **Moodboard**.

## How it works

1. Check the plan's limits with [`GET /me/limits`](/developers/reference/me/get-limits), so a workspace without room for another space gets a clear message instead of an error halfway through.
2. [Create the space](/developers/reference/spaces/create-space) with `POST /spaces`.
3. [Share it with each person](/developers/reference/spaces/add-space-member) with `POST /spaces/{spaceId}/members`. Sharing happens on the space, so everyone added can open every board in it. Each person gets an invitation email.
4. [Create the three boards](/developers/reference/boards/create-board) with `POST /boards` and the space's `spaceId`.
5. Fill the kickoff board in one draw with a [batch](/developers/reference/items/batch-items): a section, a [markdown](/developers/reference/item-types/markdown) agenda, a [checklist](/developers/reference/item-types/checklist) and a [mind map](/developers/reference/item-types/mindmap).

Each create sends an [`Idempotency-Key`](/developers/concepts/idempotency) made from the client's name, so if the automation retries the same request within 24 hours, MockFlow returns the space or board it already made instead of a second one.

## Run the example

Create an API key in the [developer console](/developers/console/) with the scopes `user:read`, `boards:write` and `members:write`, then:

```bash
cp .env.example .env        # paste your key into .env
node onboard.js clients/northwind.json
```

Change the emails in `clients/northwind.json` before you run it: everyone listed gets an invitation.

## The key code

```javascript
const space = await mf.post('/spaces', { name: `${c.client}: ${c.project}` }, { idempotencyKey: key('space') });

for (const m of c.accountTeam) {
  await mf.post(`/spaces/${space.id}/members`, { email: m.email, role: m.role });
}
for (const email of c.clientContacts) {
  await mf.post(`/spaces/${space.id}/members`, { email, role: 'reviewer' });
}

const kickoff = await mf.post('/boards', { title: 'Kickoff workshop', spaceId: space.id }, { idempotencyKey: key('kickoff') });
```

## Adapt it

- **Consultancies and freelancers:** one space per engagement, with a discovery board and a proposal board.
- **HR and people teams:** one space per new hire, with an onboarding checklist board shared with their manager and buddy.
- **Schools:** one space per class; see [Term setup for teachers](/developers/examples/api/class-setup).

## What you need

An API key with `user:read`, `boards:write` and `members:write`. Plus or Max: Basic has one space and can share as reviewer only.