{"slug":"developers/ONBOARDING_FLOW","title":"Onboarding Flow — Endpoints","section":"developers","sectionLabel":"Developers","status":"unclassified","type":"document","path":"developers/ONBOARDING_FLOW.mdx","bytes":8792,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\nThe 6-phase onboarding flow guides users from signup to active workspace.\n\n---\n\n## Flow Overview\n\n```\nPhase 1: Welcome        → Use case selection (personal/work/business)\nPhase 2: Profile        → Industry, department, company size\nPhase 3: Workspace      → Workspace name, goals\nPhase 4: Connectors     → Select data sources (Marketplace)\nPhase 5: Activation     → Initialize Spine, start sync\nPhase 6: Complete       → Redirect to workspace\n```\n\n---\n\n## Endpoints\n\n### Phase 1-3: Identity & Profile\n\n| Method | Endpoint                                | Phase | Description                  | Request Body                                 | Response                                   |\n| ------ | --------------------------------------- | ----- | ---------------------------- | -------------------------------------------- | ------------------------------------------ |\n| `GET`  | `/api/v1/workspace/onboarding-state`    | All   | Get current onboarding state | -                                            | `{onboarding: OnboardingState}`            |\n| `POST` | `/api/v1/workspace/initialize-spine`    | 5     | Initialize Spine schema      | `{domain, industry, department, connectors}` | `{tenantConfig, syncJobs}`                 |\n| `POST` | `/api/v1/workspace/complete-onboarding` | 6     | Complete onboarding          | `{preferences?}`                             | `{success, redirectUrl, backgroundJobs}`   |\n| `GET`  | `/api/v1/workspace/progress`            | 5     | Poll sync progress           | -                                            | `{type: \"sync_progress\", jobs: SyncJob[]}` |\n\n### Phase 4: Connector Selection\n\n| Method | Endpoint                                   | Description               | Response                          |\n| ------ | ------------------------------------------ | ------------------------- | --------------------------------- |\n| `GET`  | `/api/v1/workspace/connectors/catalog`     | Get available connectors  | `{connectors: [...], total: 100}` |\n| `GET`  | `/api/v1/workspace/connectors`             | List installed connectors | `{connectors: [...]}`             |\n| `POST` | `/api/v1/workspace/register-connector`     | Register connector        | `{success, connector_id}`         |\n| `POST` | `/api/v1/integrations/:provider/authorize` | Start OAuth flow          | `{auth_url, state}`               |\n| `GET`  | `/api/v1/integrations/callback`            | OAuth callback (public)   | Redirect to app                   |\n\n### Phase 5: Activation\n\n| Method | Endpoint                             | Description               | Response                               |\n| ------ | ------------------------------------ | ------------------------- | -------------------------------------- |\n| `POST` | `/api/v1/workspace/initialize-spine` | Initialize Spine          | `{tenantConfig, syncJobs}`             |\n| `GET`  | `/api/v1/loader/creamy/:jobId`       | Check extraction progress | `{status, progress, extractedCount}`   |\n| `GET`  | `/api/v1/workspace/progress`         | Poll sync progress        | `{type: \"sync_progress\", jobs: [...]}` |\n\n### Phase 6: Completion\n\n| Method | Endpoint                                | Description              | Response                 |\n| ------ | --------------------------------------- | ------------------------ | ------------------------ |\n| `POST` | `/api/v1/workspace/complete-onboarding` | Mark onboarding complete | `{success, redirectUrl}` |\n\n---\n\n## Request/Response Details\n\n### GET /api/v1/workspace/onboarding-state\n\nReturns the current onboarding state for the user.\n\n**Response:**\n\n```json\n{\n  \"onboarding\": {\n    \"status\": \"in_progress\",\n    \"currentStep\": \"profile\",\n    \"completedSteps\": [\"welcome\"],\n    \"connectorsConfig\": [{ \"provider\": \"salesforce\", \"flowType\": \"A\" }],\n    \"createdAt\": \"2026-07-21T10:00:00Z\"\n  }\n}\n```\n\n---\n\n### POST /api/v1/workspace/initialize-spine\n\nInitializes the Spine schema with domain, industry, and connectors.\n\n**Request:**\n\n```json\n{\n  \"domain\": \"SALES\",\n  \"industry\": \"technology\",\n  \"department\": \"Sales\",\n  \"connectors\": [\n    { \"provider\": \"salesforce\", \"flowType\": \"A\" },\n    { \"provider\": \"hubspot\", \"flowType\": \"A\" }\n  ]\n}\n```\n\n**Response:**\n\n```json\n{\n  \"tenantConfig\": {\n    \"id\": \"tenant_abc123\",\n    \"domain\": \"SALES\",\n    \"connectors\": {\n      \"salesforce\": { \"flowType\": \"A\" },\n      \"hubspot\": { \"flowType\": \"A\" }\n    }\n  },\n  \"syncJobs\": [\n    { \"jobId\": \"job_001\", \"connector\": \"salesforce\", \"status\": \"running\" },\n    { \"jobId\": \"job_002\", \"connector\": \"hubspot\", \"status\": \"pending\" }\n  ]\n}\n```\n\n---\n\n### POST /api/v1/workspace/complete-onboarding\n\nMarks onboarding as complete and returns redirect URL.\n\n**Request:**\n\n```json\n{\n  \"preferences\": {\n    \"theme\": \"light\",\n    \"notifications\": true\n  }\n}\n```\n\n**Response:**\n\n```json\n{\n  \"success\": true,\n  \"redirectUrl\": \"/app/work/dashboard\",\n  \"backgroundJobs\": [{ \"jobId\": \"job_001\", \"type\": \"sync\", \"status\": \"running\" }]\n}\n```\n\n---\n\n### GET /api/v1/workspace/progress\n\nPolls sync progress during activation phase.\n\n**Response:**\n\n```json\n{\n  \"type\": \"sync_progress\",\n  \"jobs\": [\n    {\n      \"jobId\": \"job_001\",\n      \"connector\": \"salesforce\",\n      \"phase\": \"creamy\",\n      \"status\": \"running\",\n      \"progress\": {\n        \"total\": 1250,\n        \"processed\": 800,\n        \"percentage\": 64,\n        \"stage\": \"extracting\"\n      }\n    }\n  ]\n}\n```\n\n---\n\n### GET /api/v1/loader/creamy/:jobId\n\nChecks extraction progress for a specific job.\n\n**Response:**\n\n```json\n{\n  \"jobId\": \"job_001\",\n  \"status\": \"running\",\n  \"progress\": {\n    \"total\": 1250,\n    \"processed\": 800,\n    \"percentage\": 64\n  },\n  \"extractedCount\": 800,\n  \"message\": \"Extracting accounts from Salesforce\"\n}\n```\n\n---\n\n## OnboardingState Type\n\n```typescript\ninterface OnboardingState {\n  status: \"not_started\" | \"in_progress\" | \"completed\";\n  currentStep: string;\n  completedSteps: string[];\n  connectorsConfig?: Array<{\n    provider: string;\n    flowType: \"A\" | \"B\" | \"C\";\n  }>;\n  creamyJobId?: string;\n  normalizerJobId?: string;\n  createdAt?: string;\n  completedAt?: string;\n}\n```\n\n## SyncJob Type\n\n```typescript\ninterface SyncJob {\n  jobId: string;\n  connector: string;\n  phase: \"creamy\" | \"needed\" | \"delta\";\n  status: \"pending\" | \"running\" | \"completed\" | \"failed\";\n  progress: {\n    total?: number;\n    processed?: number;\n    percentage?: number;\n    stage?: string;\n  };\n}\n```\n\n---\n\n## Frontend Implementation\n\n```typescript\nimport {\n  initializeSpine,\n  getOnboardingState,\n  completeOnboarding,\n  subscribeToProgress,\n} from \"@/api/workspace\";\n\n// Check onboarding state\nconst { onboarding } = await getOnboardingState();\n\n// Initialize Spine (Phase 5)\nconst { tenantConfig, syncJobs } = await initializeSpine({\n  domain: \"SALES\",\n  industry: \"technology\",\n  department: \"Sales\",\n  connectors: [\n    { provider: \"salesforce\", flowType: \"A\" },\n    { provider: \"hubspot\", flowType: \"A\" },\n  ],\n});\n\n// Subscribe to progress updates\nconst unsubscribe = subscribeToProgress(\n  (jobs) => {\n    jobs.forEach((job) => {\n      console.log(`${job.connector}: ${job.progress.percentage}%`);\n    });\n  },\n  (error) => console.error(error)\n);\n\n// Complete onboarding (Phase 6)\nconst { redirectUrl } = await completeOnboarding({\n  preferences: { theme: \"light\" },\n});\n\n// Redirect to workspace\nwindow.location.href = redirectUrl;\n```\n\n---\n\n## Domain Resolution\n\n| Use Case | Department       | Domain              |\n| -------- | ---------------- | ------------------- |\n| personal | \\*               | PERSONAL            |\n| work     | SALES            | SALES               |\n| work     | MARKETING        | MARKETING           |\n| work     | REVOPS           | REVOPS              |\n| work     | CUSTOMER_SUCCESS | CUSTOMER_SUCCESS    |\n| work     | ENGINEERING      | PRODUCT_ENGINEERING |\n| work     | PRODUCT          | PRODUCT_ENGINEERING |\n| work     | IT               | PRODUCT_ENGINEERING |\n| work     | OPERATIONS       | CUSTOMER_SUCCESS    |\n| work     | SUPPLY_CHAIN     | PROCUREMENT         |\n| work     | SERVICE_OPS      | SERVICE             |\n| work     | FINANCE          | FINANCE             |\n| work     | HR               | CUSTOMER_SUCCESS    |\n| work     | LEGAL            | CUSTOMER_SUCCESS    |\n\n---\n\n**Base URL:** `https://gateway.dev.integratewise.ai`  \n**Auth:** `Authorization: Bearer $INTEGRATEWISE_API_TOKEN` + `x-tenant-id: $INTEGRATEWISE_TENANT_ID`\n\n**Auth Endpoints (Clerk):**\n| Endpoint | URL |\n|----------|-----|\n| Sign In | `https://accounts.integratewise.ai/sign-in` |\n| Sign Up | `https://accounts.integratewise.ai/sign-up` |\n| OAuth Authorize | `https://integratewise.ai/clerk/oauth/authorize` |\n| OAuth Token | `https://integratewise.ai/clerk/oauth/token` |\n| User Info | `https://integratewise.ai/clerk/oauth/userinfo` |\n"}