Skip, resume or confirm an onboarding step

Changes one step of the organization's onboarding checklist and returns the checklist:

skip: the step is set aside (skipped) and the checklist moves on. It counts as done as soon as the organization's data shows it done;
resume: a skipped step is open again (and a confirmed registrations review is open again);
complete: confirms the registrations review (registrations): the home registration numbers are right, existing OSS, UK or other registrations are entered, and the blocked jurisdictions were reviewed. The other steps follow the organization's data and can't be marked done (onboarding_step_not_manual).

Needs org:write (organization owners and admins).

At a glance

REST: POST /api/v1/onboarding/steps/{step}
MCP tool: onboarding_steps_update
Operation ID: onboarding.steps.update
Scope: Organization
Permission: org:write
Risk tier: write
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key required
Modes: Test and live
Authentication: API key with the org:write scope
Since: M12

Request

Path parameters

Field	Type	Description
`step`	one of `legal_entity`, `brand`, `processor`, `registrations`, `catalog`, `test_checkout`, `go_live`

Body

A JSON object (Content-Type: application/json):

Field	Type	Required	Description
`action`	one of `skip`, `resume`, `complete`	Yes	`skip` a step, `resume` a skipped (or confirmed) one, or `complete` the registrations review.
`expectedVersion`	integer (at least 0)	No	The checklist's `version` you read (0 before the first change); a stale one is `version_conflict`.

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

Confirm the registrations review

HTTP

POST /api/v1/onboarding/steps/registrations
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
Content-Type: application/json

{
  "action": "complete"
}

Response (200):

JSON

{
  "object": "onboarding_checklist",
  "orgId": "org_01m4tx5nj7ekd958x53w4bntcg",
  "complete": false,
  "next": "catalog",
  "done": 4,
  "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": "done",
      "doneBy": "person",
      "skippedAt": null,
      "completedAt": "2026-10-26T09:00:00.000Z"
    },
    {
      "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": 1
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	The step or action is unknown.	Fix the fields listed in `details.issues` and send the request again.
`onboarding_step_not_manual`	400	`complete` on a step the organization's data decides.	Do the step (for example, create the brand), or skip it. Only the registrations review is marked done.
`onboarding_step_done`	409	`skip` or `complete` on a step that is already done.	Nothing to do. A done step can't be skipped or marked again.
`version_conflict`	409	The checklist changed since `expectedVersion`; read it again.	Fetch the object again and retry the change.
`permission_denied`	403	You can't change this organization's onboarding.	Ask an organization owner or admin for a role or scope that allows this action.

It can also return these common errors: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, resource_not_found, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Body#

Response#

Examples#

Confirm the registrations review#

Errors#