---
title: "Deep-merge one authenticated setup task slice"
method: PATCH
path: "/onboarding/v3/setup-state"
tags: ["Onboarding"]
---

# Deep-merge one authenticated setup task slice

`PATCH /onboarding/v3/setup-state`

## Request

- Base URL: `https://api.medianfi.com/api/v1`
- URL: `https://api.medianfi.com/api/v1/onboarding/v3/setup-state`
- Auth: HTTP bearer

The server is the sole setup-state authority. Completing Business Basics updates company identity and the primary legal entity in the same database transaction as this setup-state write.

## Headers

- `X-Median-App-Surface` 'qa'

## Request body

- union
  - OnboardingV3AuthoritySetupPatch
    - `taskId` 'authority', required
    - `task` OnboardingV3SetupTaskState
      - `status` 'done'
      - `owner` string
    - `data` union, required: Owner intent only. Invite lifecycle metadata is server-managed and cannot be supplied through the setup-state patch.
      - object
        - `isAuthority` true, required
        - `delegate` unknown
      - object
        - `isAuthority` false, required
        - `delegate` OnboardingV3AuthorityDelegateInput, required
          - `name` string, required
          - `email` string, email, required
  - OnboardingV3BusinessBasicsSetupPatch
    - `taskId` 'basics', required
    - `task` OnboardingV3SetupTaskState
      - `status` 'done'
      - `owner` string
    - `data` OnboardingV3BusinessBasicsData
      - `legalName` string: Required and at least two non-whitespace characters when completing.
      - `entityType` string
      - `state` string
      - `yearFounded` string
      - `fiscalYearEnd` string: Fiscal year end as MM-DD (must be a real date), or empty when not answered. Written to companies.fiscal_year_end on completion (#2019).
      - `industry` string
      - `industryOther` string
      - `books` string
      - `ein` string
      - `deferred` OnboardingV3BusinessBasicsDeferredInput[]
        - `id` 'entityType' | 'state' | 'yearFounded' | 'ein' | 'industry' | 'fiscalYearEnd', required
        - `label` string, required
        - `ask` string
  - union
    - OnboardingV3ConnectCompletionPatch
      - `taskId` 'connect', required
      - `task` OnboardingV3DoneSetupTaskState, required
        - `status` 'done', required
        - `owner` string
      - `data` OnboardingV3ConnectCompletionData, required
        - `integrationIds` string[], required
        - `accountIds` string[], required
        - `personalAccountIds` string[], required
    - OnboardingV3ConnectAdministrativePatch
      - `taskId` 'connect', required
      - `task` OnboardingV3ProviderOwnershipTaskState
        - `owner` string, required
      - `deferred` OnboardingV3DeferredInput[]
        - `id` string, required
        - `label` string, required
        - `ask` string
  - union
    - OnboardingV3DocumentsCompletionPatch
      - `taskId` 'documents', required
      - `task` OnboardingV3DoneSetupTaskState, required
        - `status` 'done', required
        - `owner` string
      - `data` OnboardingV3DocumentsCompletionData, required
        - `email` 'connected' | 'forwarding' | 'help_needed', required
    - OnboardingV3DocumentsAdministrativePatch
      - `taskId` 'documents', required
      - `task` OnboardingV3ProviderOwnershipTaskState
        - `owner` string, required
      - `deferred` OnboardingV3DeferredInput[]
        - `id` string, required
        - `label` string, required
        - `ask` string
  - union
    - OnboardingV3BooksCompletionPatch
      - `taskId` 'books', required
      - `task` OnboardingV3DoneSetupTaskState, required
        - `status` 'done', required
        - `owner` string
      - `data` union, required
        - OnboardingV3BooksInvitedCompletionData
          - `granted` true, required
          - `method` 'invited', required
        - OnboardingV3BooksConnectedCompletionData
          - `granted` true, required
          - `method` 'connected', required
          - `provider` 'quickbooks' | 'xero', required
          - `migrationJobId` string, uuid, required
    - OnboardingV3BooksAdministrativePatch
      - `taskId` 'books', required
      - `task` OnboardingV3ProviderOwnershipTaskState
        - `owner` string, required
      - `deferred` OnboardingV3DeferredInput[]
        - `id` string, required
        - `label` string, required
        - `ask` string
  - union
    - OnboardingV3HistoryCompletionPatch
      - `taskId` 'history', required
      - `task` OnboardingV3DoneSetupTaskState, required
        - `status` 'done', required
        - `owner` string
      - `data` OnboardingV3HistoryCompletionData, required
        - `byInstitution` OnboardingV3HistoryByInstitution, required
    - OnboardingV3HistoryAdministrativePatch
      - `taskId` 'history', required
      - `task` OnboardingV3ProviderOwnershipTaskState
        - `owner` string, required
      - `deferred` OnboardingV3DeferredInput[]
        - `id` string, required
        - `label` string, required
        - `ask` string
  - unknown

## Response `200`

Authoritative state after the task-scoped merge

- OnboardingV3SetupStateApiResponse
  - `success` true, required
  - `data` OnboardingV3SetupState, required
    - `companyId` string, uuid, required
    - `tasks` OnboardingV3SetupTaskRecord, required
    - `data` OnboardingV3SetupDataRecord, required
    - `deferred` OnboardingV3DeferredItem[], required
      - `id` string, required
      - `label` string, required
      - `ask` string
      - `taskId` 'authority' | 'basics' | 'connect' | 'processors' | 'payroll' | 'documents' | 'books' | 'history' | 'median-work' | 'call', required
    - `updatedAt` string, date-time, required

## Other responses

- `400`: Onboarding request body is not valid JSON
- `401`: Authentication required
- `403`: Insufficient permissions or not a company member
- `404`: Resource not found
- `409`: Request conflicts with the durable onboarding state
- `413`: Onboarding setup request exceeds the 32768-byte route limit
- `415`: Onboarding request charset or content encoding is unsupported
- `422`: Validation error

---

[API](https://skmtc.dev/medianfi/apis/median-api.md) · [All operations](https://skmtc.dev/medianfi/apis/median-api/llms.txt) · [OpenAPI document](https://skmtc.dev/medianfi/apis/median-api/revisions/20090ea32b0d?raw)