--- title: "POST /api/v1/onboarding.session.search" method: POST path: "/api/v1/onboarding.session.search" tags: ["Onboarding V2"] --- # POST /api/v1/onboarding.session.search `POST /api/v1/onboarding.session.search` ## Request - Base URL: `https://api.partly.com` (the document declares no server; this is the origin it was published from) - URL: `https://api.partly.com/api/v1/onboarding.session.search` - Auth: none declared. Required headers: `authorization` Search onboarding sessions (Partly staff only). Supports cursor pagination and filtering by form name, HubSpot deal id and stage. ## Headers - `authorization` string, required: UTF-8 encoded string ## Request body - OnboardingSessionSearchRequest - `cursor` string: UTF-8 encoded string - `form_name` 'nz-workshop-v1' - `hubspot_deal_id` string: UTF-8 encoded string - `limit` integer: 32-bit unsigned integer - `stages` OnboardingV2DalSessionStateSessionStage[]: Expandable array type - union - 'draft': Session created, organization reserved, invite emails known. - 'contracts-sending': Contracts issued to the signing provider (PandaDoc); waiting on the customer to fill and sign them. - 'awaiting-payment-method': Contracts signed and a billing customer created; waiting on the customer to add a payment method. - 'form-in-draft': Payment settled; the customer is completing the operational form (users, groups, sites), accumulating patches. - 'provisioning': Form submitted and validated; provisioning businesses, users, groups and billing products. - 'in-staff-review': Fully provisioned; held for Partly staff review before completion. - 'syncing': Staff review cleared (or skipped): running the finalization tail — syncing the completed form to HubSpot and the signed contracts to billing — before completion. Distinct from `InStaffReview` so staff (and the customer) can see the session has moved past review and is finishing up. - 'inviting-users': Organization graduated out of `Onboarding` status; inviting the form's users so they can set a password and sign in. Entered only after the graduation, because `organizations.verify` refuses to mint an org token for a non-staff user while the organization is still onboarding — an invite sent earlier burns its one-shot set-password token on an account that cannot yet sign in. - 'completed': Terminal: onboarding complete. - 'cancelled': Terminal: cancelled or abandoned before completion. ## Response `200` 200 OK - OnboardingSessionSearchResponse - `items` OnboardingV2SessionView[], required: Expandable array type - `contracts` OnboardingV2PandadocContractView[], required: Expandable array type - `kind` string, required: UTF-8 encoded string - `status` union, required - 'not-sent' - 'sent' - 'signed' - `title` string, required: UTF-8 encoded string - `created_at` string, date-time, required: DateTime at a given timezone (RFC3339 format) - `form` OnboardingV2FormDraft, required - `nz_workshop_v1` OnboardingV2NzWorkshopV1Form, required - `address` Address, required - `city` string: UTF-8 encoded string - `country_code` integer: 32-bit signed integer - `geo` GeoLocation - `latitude` number, required: 64-bit floating point number - `longitude` number, required: 64-bit floating point number - `name` string: UTF-8 encoded string - `postcode` string: UTF-8 encoded string - `state` string: UTF-8 encoded string - `street_name` string: UTF-8 encoded string - `street_number` string: UTF-8 encoded string - `suburb` string: UTF-8 encoded string - `time_zone` string: UTF-8 encoded string - `unit` string: UTF-8 encoded string - `billing_email` string, required: UTF-8 encoded string - `business_phone` string, required: UTF-8 encoded string - `companies_office_number` string, required: UTF-8 encoded string - `current_parts_suppliers` string, required: UTF-8 encoded string - `gst_number` string, required: UTF-8 encoded string - `hoist_count` integer, required: 32-bit unsigned integer - `jobs_per_week` integer, required: 32-bit unsigned integer - `monthly_parts_spend_nzd` integer, required: 32-bit unsigned integer - `mta_member` boolean, required: Boolean value - `nzbn` string, required: UTF-8 encoded string - `parts_categories_sourced` OnboardingV2PartsCategorySourced[], required: Expandable array type - union - 'oem' - 'oec' - 'aftermarket' - 'used_recycled' - `parts_delivery_address` string, required: UTF-8 encoded string - `parts_mix_profile` union, required - 'mostly_oem' - 'mostly_oec' - 'mostly_aftermarket' - 'mostly_used_recycled' - 'even_oem_aftermarket_mix' - 'mixed_no_clear_majority' - `parts_sourcing_notes` string, required: UTF-8 encoded string - `parts_stocking_model` OnboardingV2PartsStockingModel[], required: Expandable array type - union - 'stocks_on_site' - 'sources_per_job' - 'both' - `primary_contact_email` string, required: UTF-8 encoded string - `primary_contact_phone` string, required: UTF-8 encoded string - `primary_workshop_contact` string, required: UTF-8 encoded string - `registered_company_name` string, required: UTF-8 encoded string - `secondary_contact_email` string, required: UTF-8 encoded string - `secondary_contact_name` string, required: UTF-8 encoded string - `secondary_contact_phone` string, required: UTF-8 encoded string - `service_advisors_count` integer, required: 32-bit unsigned integer - `services_offered` OnboardingV2ServiceOffered[], required: Expandable array type - union - 'wof_inspections' - 'wheel_alignment' - 'tyres' - 'ev_servicing' - 'diagnostics' - 'performance_tuning' - 'pre_purchase_inspections' - 'panel_paint' - 'adas' - 'other' - `sources_parts_overseas` boolean, required: Boolean value - `specialities` string, required: UTF-8 encoded string - `technician_count` integer, required: 32-bit unsigned integer - `trading_as_name` string, required: UTF-8 encoded string - `users` object, required: Key-value map type - `warranty_insurer_approvals` OnboardingV2WarrantyInsurerApproval[], required: Expandable array type - union - 'autosure' - 'provident' - 'protecta' - 'janssen' - 'other' - `website` string, required: UTF-8 encoded string - `workshop_area` union, required - 'far_north' - 'whangarei' - 'kaipara' - 'auckland_north_shore' - 'auckland_central' - 'auckland_west' - 'auckland_east' - 'auckland_south' - 'auckland_franklin' - 'north_waikato' - 'hamilton' - 'waipa' - 'matamata_piako' - 'hauraki' - 'thames_coromandel' - 'south_waikato' - 'taupo' - 'waitomo_king_country' - 'tauranga_western_bay_of_plenty' - 'rotorua' - 'whakatane_eastern_bay_of_plenty' - 'kawerau' - 'opotiki' - 'gisborne' - 'napier' - 'hastings' - 'central_hawkes_bay' - 'wairoa' - 'new_plymouth' - 'stratford' - 'south_taranaki' - 'palmerston_north' - 'manawatu' - 'whanganui' - 'horowhenua' - 'rangitikei' - 'ruapehu_taumarunui' - 'wellington_city' - 'lower_hutt' - 'upper_hutt' - 'porirua' - 'kapiti_coast' - 'wairarapa' - 'nelson' - 'richmond' - 'motueka' - 'golden_bay' - 'tasman_rural' - 'blenheim' - 'picton' - 'marlborough_sounds' - 'westport_buller' - 'greymouth_grey' - 'hokitika_westland' - 'christchurch_central' - 'christchurch_north' - 'christchurch_south' - 'christchurch_west' - 'waimakariri' - 'selwyn' - 'hurunui' - 'kaikoura' - 'ashburton_mid_canterbury' - 'timaru_south_canterbury' - 'mackenzie' - 'dunedin' - 'oamaru_waitaki' - 'central_otago' - 'queenstown_lakes' - 'clutha' - 'invercargill' - 'gore' - 'southland_district' - 'fiordland' - `workshop_network_affiliation` union, required - 'auto_super_shoppes' - 'automotive_solutions_nz' - 'bm_workshop' - 'ultimate_mechanics' - 'tyres_more' - 'aa_service_center' - 'mta' - 'other' - 'no_affiliation' - `workshop_region` union, required - 'northland' - 'auckland' - 'waikato' - 'bay_of_plenty' - 'gisborne' - 'hawkes_bay' - 'taranaki' - 'manawatu_whanganui' - 'wellington' - 'tasman' - 'nelson' - 'marlborough' - 'west_coast' - 'canterbury' - 'otago' - 'southland' - `form_name` 'nz-workshop-v1', required - `hubspot_deal_id` string, required: UTF-8 encoded string - `id` string, uuid, required: UUID value type - `invited_user_emails` StdStringString[], required: Expandable array type - `next_action` union, required - 'send-invite': Send the invite email for a freshly created session. - 'issue-contracts': Issue the contracts to the signing provider. - 'create-billing-customer': Create the billing customer once contracts are signed. - 'resolve-payment-link': Resolve the provider-hosted payment link for the started setup and record it on the session, so the customer can be redirected to complete payment. Blocked (no-op) until the billing-worker has produced the hosted action. - 'provision': Provision BNA based off the form's provisioning steps. - 'enter-staff-review': Enter staff review (post the review request). - 'sync-hubspot': Push the completed form's fields back to HubSpot. A distinct step (not folded into `Complete`) so its result is recorded durably before the session finalizes — a worker that dies after the push doesn't re-push on restart. - 'sync-contracts': Download the signed contracts from the signing provider (PandaDoc) and upload them onto the organization's billing customer, so the executed agreements live alongside the customer in the billing portal. A distinct step (like `SyncHubspot`) so its completion is recorded durably and a resumed worker doesn't re-upload. - 'promote-organization': Promote the organization out of `Onboarding` status, once the syncs have been recorded. A distinct step because the user invites that follow are only valid after it. - 'invite-users': Run the form's post-promotion user invite steps one per pass, then complete the session once none remain. - `organization_id` string, uuid, required: UUID value type - `organization_name` string, required: UTF-8 encoded string - `payment_link` OnboardingV2PaymentLinkView, required: FE-facing projection of the [`PaymentLink`] carried in the session state. - `expires_at` string, date-time, required: DateTime at a given timezone (RFC3339 format) - `url` string, required: UTF-8 encoded string - `recipient_emails` StdStringString[], required: Expandable array type - `requires_contracts` boolean, required: Boolean value - `requires_payment_method` boolean, required: Boolean value - `stage` union, required - 'draft': Session created, organization reserved, invite emails known. - 'contracts-sending': Contracts issued to the signing provider (PandaDoc); waiting on the customer to fill and sign them. - 'awaiting-payment-method': Contracts signed and a billing customer created; waiting on the customer to add a payment method. - 'form-in-draft': Payment settled; the customer is completing the operational form (users, groups, sites), accumulating patches. - 'provisioning': Form submitted and validated; provisioning businesses, users, groups and billing products. - 'in-staff-review': Fully provisioned; held for Partly staff review before completion. - 'syncing': Staff review cleared (or skipped): running the finalization tail — syncing the completed form to HubSpot and the signed contracts to billing — before completion. Distinct from `InStaffReview` so staff (and the customer) can see the session has moved past review and is finishing up. - 'inviting-users': Organization graduated out of `Onboarding` status; inviting the form's users so they can set a password and sign in. Entered only after the graduation, because `organizations.verify` refuses to mint an org token for a non-staff user while the organization is still onboarding — an invite sent earlier burns its one-shot set-password token on an account that cannot yet sign in. - 'completed': Terminal: onboarding complete. - 'cancelled': Terminal: cancelled or abandoned before completion. - `updated_at` string, date-time, required: DateTime at a given timezone (RFC3339 format) - `next_cursor` string, required: UTF-8 encoded string ## Other responses - `default`: Error cases ## Changes - **2026-10-15** `e1d6ccdf0c60`: 2 breaking, 1 info - removed the required property `items/items/form/oneOf[subschema #1: nz_workshop_v1]/nz_workshop_v1/agreement_signer_email` from the response with the `200` status - removed the required property `items/items/form/oneOf[subschema #1: nz_workshop_v1]/nz_workshop_v1/agreement_signer_name` from the response with the `200` status - added the required property `items/items/requires_contracts` to the response with the `200` status - **2026-10-15** `d73948080dc7`: 1 info - endpoint added [Operation history](https://skmtc.dev/partly/apis/core-server/changes/api/v1/onboarding.session.search/post.md) --- [API](https://skmtc.dev/partly/apis/core-server.md) · [All operations](https://skmtc.dev/partly/apis/core-server/llms.txt) · [OpenAPI document](https://skmtc.dev/partly/apis/core-server/revisions/19dd5c84162b?raw)