# Get the onboarding checklist

> The onboarding.get operation: GET /api/v1/onboarding in the REST API and the onboarding_get tool in the MCP server.

Returns the organization's onboarding checklist: seven steps in order, each `todo`, `in_progress`, `done` or
`skipped`, and the next one to do.

1. `legal_entity`: a legal entity whose tax ID is verified (VIES, HMRC, CH UID) or under review from a registry
   extract (`in_progress` while it's unverified);
2. `brand`: a brand;
3. `processor`: a processor connection (test or live);
4. `registrations`: the registrations review, done when someone confirms it (`onboarding.steps.update`);
5. `catalog`: an active test-mode price;
6. `test_checkout`: a successful test-mode payment;
7. `go_live`: a live brand (the go-live checklist, `brands.go_live`).

Steps other than the registrations review follow the organization's data, so they can't be marked done by hand.
Any step can be skipped and resumed. The checklist is `complete` once every step is done or skipped.

## At a glance

- **REST:** `GET /api/v1/onboarding`
- **MCP tool:** `onboarding_get`
- **Operation ID:** `onboarding.get`
- **Scope:** Organization
- **Permission:** `org:read`
- **Risk tier:** `read`
- **Dry run:** Not supported
- **Idempotency:** Not needed (read only)
- **Modes:** Test and live
- **Authentication:** API key with the `org:read` scope
- **Since:** M12

## Request

### Query parameters

This operation takes no query parameters.

## Response

`200 OK` with a JSON object:

| Field                 | Type                                                                                                        | Description                                                                              |
| --------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `object`              | `"onboarding_checklist"`                                                                                    |                                                                                          |
| `orgId`               | `org_…` ID                                                                                                  |                                                                                          |
| `complete`            | boolean                                                                                                     | Every step is done or skipped.                                                           |
| `next`                | one of `legal_entity`, `brand`, `processor`, `registrations`, `catalog`, `test_checkout`, `go_live` or null | The first step that is neither done nor skipped.                                         |
| `done`                | integer                                                                                                     |                                                                                          |
| `total`               | integer                                                                                                     |                                                                                          |
| `steps`               | array of object                                                                                             |                                                                                          |
| `steps[].step`        | one of `legal_entity`, `brand`, `processor`, `registrations`, `catalog`, `test_checkout`, `go_live`         |                                                                                          |
| `steps[].status`      | one of `todo`, `in_progress`, `done`, `skipped`                                                             |                                                                                          |
| `steps[].doneBy`      | one of `data`, `person` or null                                                                             | How a done step is known: from the organization's data, or from a person's confirmation. |
| `steps[].skippedAt`   | date-time or null                                                                                           |                                                                                          |
| `steps[].completedAt` | date-time or null                                                                                           | When a person confirmed the step (the registrations review only).                        |
| `completedAt`         | date-time or null                                                                                           | When the checklist was first complete.                                                   |
| `version`             | integer                                                                                                     | 0 until a step was first skipped or confirmed.                                           |

## Examples

### Halfway through onboarding

```http
GET /api/v1/onboarding
Authorization: Bearer or_test_…
```

Response (`200`):

```json
{
  "object": "onboarding_checklist",
  "orgId": "org_01m4tx5nj7ekd958x53w4bntcg",
  "complete": false,
  "next": "registrations",
  "done": 3,
  "total": 7,
  "steps": [
    {
      "step": "legal_entity",
      "status": "done",
      "doneBy": "data",
      "skippedAt": null,
      "completedAt": null
    },
    {
      "step": "brand",
      "status": "done",
      "doneBy": "data",
      "skippedAt": null,
      "completedAt": null
    },
    {
      "step": "processor",
      "status": "done",
      "doneBy": "data",
      "skippedAt": null,
      "completedAt": null
    },
    {
      "step": "registrations",
      "status": "todo",
      "doneBy": null,
      "skippedAt": null,
      "completedAt": null
    },
    {
      "step": "catalog",
      "status": "todo",
      "doneBy": null,
      "skippedAt": null,
      "completedAt": null
    },
    {
      "step": "test_checkout",
      "status": "todo",
      "doneBy": null,
      "skippedAt": null,
      "completedAt": null
    },
    {
      "step": "go_live",
      "status": "todo",
      "doneBy": null,
      "skippedAt": null,
      "completedAt": null
    }
  ],
  "completedAt": null,
  "version": 0
}
```

## Errors

| Code                                                                                   | HTTP status | When                              | What to do                                                                      |
| -------------------------------------------------------------------------------------- | ----------- | --------------------------------- | ------------------------------------------------------------------------------- |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403         | You can't read this organization. | Ask an organization owner or admin for a role or scope that allows this action. |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed), [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).