---
title: "Create or resume an onboarding session"
method: POST
path: "/api/onboarding/sessions"
tags: ["Onboarding"]
---

# Create or resume an onboarding session

`POST /api/onboarding/sessions`

Creates a local-only session until valid contact details identify the lead. A prior lead token may be supplied in the `x-onboarding-lead-token` header, cookie, or request body. A submitted session can also be resumed from Attio with `resumeSessionId`.

## Request body

- object
  - `path` 'prescriber' | 'developer' | 'clinic' | 'enterprise' | 'platform' | 'other' — Public onboarding path id. Prefer `/onboard?type={id}` for new human links. Legacy `/onboard#{id}` and `/onboard#{id}-{payment_plan_tier}` links remain supported.
  - `trackingSummary` TrackingSummary
    - `source` string
    - `medium` string
    - `campaign` string
    - `referrer` string
    - `landingPath` string
  - `flowId` string, nullable — Browser-local flow id used before the server issues a session id.
  - `draftState` OnboardingSession
    - `sessionId` string, required
    - `path` 'prescriber' | 'developer' | 'clinic' | 'enterprise' | 'platform' | 'other', required — Public onboarding path id. Prefer `/onboard?type={id}` for new human links. Legacy `/onboard#{id}` and `/onboard#{id}-{payment_plan_tier}` links remain supported.
    - `status` 'draft' | 'identified' | 'submitted', required
    - `lastStep` string, required
    - `identifiedEmail` string, email
    - `submittedAt` string, date-time
    - `provisioningStatus` 'pending' | 'completed' | 'failed' | 'not_applicable'
    - `paymentStatus` 'not_required' | 'payment_required' | 'checkout_open' | 'paid' | 'failed' | 'expired'
    - `provisioningInviteUrl` string, uri
    - `provisioningFailureReason` union
      - string
      - object
        - `message` string
        - `debugMessage` string
    - `paymentPlanTier` string — Business tier / Stripe pricing plan lookup key.
    - `paymentPlanName` string — Display name returned by the billing catalog.
    - `paymentPlanDescription` string — Short display description returned by the billing catalog.
    - `paymentPrice` number — Monthly Checkout price in USD dollars.
    - `paymentIncludedMonthlyOrders` number — Included monthly order volume for the plan.
    - `paymentOveragePrice` number — Per-order overage price in USD dollars.
    - `stripeCustomerId` string
    - `stripeSubscriptionId` string
    - `attioEntryId` string
    - `attioPersonRecordId` string
  - `resumeSessionId` string, nullable — Submitted onboarding session id to resume from Attio when no lead token is present.
  - `paymentPlanTier` string, nullable — Optional Stripe pricing-plan lookup key to assign to the onboarding session.
  - `email` string, email, nullable — Optional email seed for URL-driven onboarding links. Browser `/onboard?email=` links start a fresh local session unless `session` is also present.
  - `orgId` string, nullable — Optional prefixed provisioning org id, such as `photon:org_...`, used to link checkout/provisioning to an existing account.
  - `stripeCustomerId` string, nullable — Optional Stripe customer id seed, such as `cus_...`, stored as `stripe_customer_id` when the session is identified.
  - `leadToken` string — Optional serialized lead token. Prefer the `x-onboarding-lead-token` header when available.

## Response `200`

Current onboarding session state.

- OnboardingStateEnvelope
  - `data` object, required
    - `flow` OnboardingSession, required
      - `sessionId` string, required
      - `path` 'prescriber' | 'developer' | 'clinic' | 'enterprise' | 'platform' | 'other', required — Public onboarding path id. Prefer `/onboard?type={id}` for new human links. Legacy `/onboard#{id}` and `/onboard#{id}-{payment_plan_tier}` links remain supported.
      - `status` 'draft' | 'identified' | 'submitted', required
      - `lastStep` string, required
      - `identifiedEmail` string, email
      - `submittedAt` string, date-time
      - `provisioningStatus` 'pending' | 'completed' | 'failed' | 'not_applicable'
      - `paymentStatus` 'not_required' | 'payment_required' | 'checkout_open' | 'paid' | 'failed' | 'expired'
      - `provisioningInviteUrl` string, uri
      - `provisioningFailureReason` union
        - string
        - object
          - `message` string
          - `debugMessage` string
      - `paymentPlanTier` string — Business tier / Stripe pricing plan lookup key.
      - `paymentPlanName` string — Display name returned by the billing catalog.
      - `paymentPlanDescription` string — Short display description returned by the billing catalog.
      - `paymentPrice` number — Monthly Checkout price in USD dollars.
      - `paymentIncludedMonthlyOrders` number — Included monthly order volume for the plan.
      - `paymentOveragePrice` number — Per-order overage price in USD dollars.
      - `stripeCustomerId` string
      - `stripeSubscriptionId` string
      - `attioEntryId` string
      - `attioPersonRecordId` string
    - `session` OnboardingSession, required
      - `sessionId` string, required
      - `path` 'prescriber' | 'developer' | 'clinic' | 'enterprise' | 'platform' | 'other', required — Public onboarding path id. Prefer `/onboard?type={id}` for new human links. Legacy `/onboard#{id}` and `/onboard#{id}-{payment_plan_tier}` links remain supported.
      - `status` 'draft' | 'identified' | 'submitted', required
      - `lastStep` string, required
      - `identifiedEmail` string, email
      - `submittedAt` string, date-time
      - `provisioningStatus` 'pending' | 'completed' | 'failed' | 'not_applicable'
      - `paymentStatus` 'not_required' | 'payment_required' | 'checkout_open' | 'paid' | 'failed' | 'expired'
      - `provisioningInviteUrl` string, uri
      - `provisioningFailureReason` union
        - string
        - object
          - `message` string
          - `debugMessage` string
      - `paymentPlanTier` string — Business tier / Stripe pricing plan lookup key.
      - `paymentPlanName` string — Display name returned by the billing catalog.
      - `paymentPlanDescription` string — Short display description returned by the billing catalog.
      - `paymentPrice` number — Monthly Checkout price in USD dollars.
      - `paymentIncludedMonthlyOrders` number — Included monthly order volume for the plan.
      - `paymentOveragePrice` number — Per-order overage price in USD dollars.
      - `stripeCustomerId` string
      - `stripeSubscriptionId` string
      - `attioEntryId` string
      - `attioPersonRecordId` string
    - `leadToken` string, required
    - `schema` OnboardingSchema, required
      - `paths` OnboardingPathChoice[], required
        - `id` 'prescriber' | 'developer' | 'clinic' | 'enterprise' | 'platform' | 'other', required — Public onboarding path id. Prefer `/onboard?type={id}` for new human links. Legacy `/onboard#{id}` and `/onboard#{id}-{payment_plan_tier}` links remain supported.
        - `label` string, required
        - `description` string, required
        - `cta` string, required
        - `mode` 'self_serve' | 'verification_required' | 'sales_led', required
      - `allPaths` OnboardingFullPath[], required
        - `id` 'prescriber' | 'developer' | 'clinic' | 'enterprise' | 'platform' | 'other', required — Public onboarding path id. Prefer `/onboard?type={id}` for new human links. Legacy `/onboard#{id}` and `/onboard#{id}-{payment_plan_tier}` links remain supported.
        - `label` string, required
        - `description` string, required
        - `cta` string, required
        - `mode` 'self_serve' | 'verification_required' | 'sales_led', required
        - `provisioningMode` 'developer' | 'prescriber' | 'handoff', required
        - `entryPath` string, required
        - `steps` OnboardingStep[], required
          - `id` string, required
          - `title` string, required
          - `fields` OnboardingField[], required
            - `name` string, required
            - `label` string, required
            - `type` 'email' | 'multi-select' | 'radio-cards' | 'select' | 'tel' | 'text' | 'textarea' | 'url', required
            - `required` boolean
            - `options` union[]
              - …
            - `placeholder` string
            - `autoComplete` string
            - `inputMode` string
            - `showWhen` object
              - …
      - `path` 'prescriber' | 'developer' | 'clinic' | 'enterprise' | 'platform' | 'other', required — Public onboarding path id. Prefer `/onboard?type={id}` for new human links. Legacy `/onboard#{id}` and `/onboard#{id}-{payment_plan_tier}` links remain supported.
      - `steps` OnboardingStep[], required
        - `id` string, required
        - `title` string, required
        - `fields` OnboardingField[], required
          - `name` string, required
          - `label` string, required
          - `type` 'email' | 'multi-select' | 'radio-cards' | 'select' | 'tel' | 'text' | 'textarea' | 'url', required
          - `required` boolean
          - `options` union[]
            - union
              - …
          - `placeholder` string
          - `autoComplete` string
          - `inputMode` string
          - `showWhen` object
            - `field` string
            - `value` string
    - `answers` Answers, required
    - `errors` object
    - `checkoutUrl` string, uri, nullable
    - `identityRestartRequired` boolean
    - `nextStep` string

---

[API](https://skmtc.dev/photon/apis/photon-website-api.md) · [All operations](https://skmtc.dev/photon/apis/photon-website-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/photon/photon-website-api/revisions/ab555c915b80/schema)