Onboarding Block

Complete user activation and journey management platform

The Onboarding Block is a comprehensive service for managing user onboarding flows, journeys, and activation processes. It provides multi-step flows, progress tracking, email automation, analytics, and re-engagement tools. It uses JWT authentication with multiple provider support and follows the JSON:API specification.

Key Features

Multi-step Onboarding Flows - Create dynamic, progressive onboarding journeys
User Journey Tracking - Real-time progress monitoring with detailed logs
Email Automation - Customizable templates with Mandrill integration
Analytics & Reporting - Completion rates, abandonment tracking, and insights
Smart Re-engagement - Recover abandoned users with automated campaigns
Multi-tenant Architecture - Complete data isolation per tenant
Multiple Auth Providers - Support for 23blocks, Auth0, Cognito, and Okta

API Endpoint

Service	URL
Onboarding	`https://onboarding.api.us.23blocks.com`

Environment Routing: Use the same URL for all environments. Your API key determines the environment:

pk_test_* / sk_test_* → Routes to Staging
pk_live_* / sk_live_* → Routes to Production

Quick Start

Installation

npm install @23blocks/sdk

Basic Usage

import { create23BlocksClient } from '@23blocks/sdk';

const client = create23BlocksClient({
  urls: { onboarding: 'https://onboarding.api.us.23blocks.com' },
  apiKey: 'your-api-key',
});

// Start a user's onboarding journey
const journey = await client.onboarding.startJourney({
  userId: 'user_123',
  onboardingId: 'new-user-flow'
});

// Complete a step
await client.onboarding.completeStep({
  journeyId: journey.id,
  stepId: 'profile-setup',
  payload: { completed: true }
});

// Check journey progress
console.log(`Progress: ${journey.progress}%`);

Authentication

Required Headers

All authenticated requests require:

Authorization: Bearer [JWT_TOKEN]
X-API-Key: [COMPANY_API_ACCESS_KEY]
Content-Type: application/json

Supported Auth Providers

23blocks (custom): Uses company-specific RSA public keys
Auth0 (OIDC): Fetches JWKS keys from Auth0
AWS Cognito (OIDC): Fetches JWKS keys from AWS Cognito
Okta (OIDC): Fetches JWKS keys from Okta

API Reference

Onboarding Management

List Onboardings

curl -X GET https://onboarding.api.us.23blocks.com/onboardings \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key"

Response:

{
  "data": [
    {
      "id": "789",
      "type": "Onboarding",
      "attributes": {
        "unique_id": "onboarding_12345",
        "name": "Employee Onboarding",
        "description": "Complete employee onboarding process",
        "total_steps": 5,
        "status": "active"
      }
    }
  ]
}

Create Onboarding

curl -X POST https://onboarding.api.us.23blocks.com/onboardings \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New User Onboarding",
    "description": "Guide new users through setup",
    "source": "web_app",
    "status": "active"
  }'

Add Step to Onboarding

curl -X PUT https://onboarding.api.us.23blocks.com/onboardings/onboarding_12345/steps \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Complete Profile",
    "order": 1,
    "step_url": "https://app.example.com/profile",
    "step_params": {
      "required_fields": ["email", "name"]
    }
  }'

User Journey Management

Start Onboarding Journey

curl -X POST https://onboarding.api.us.23blocks.com/users/user_123/register/onboarding_12345 \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key"

Response:

{
  "data": {
    "id": "202",
    "type": "UserJourney",
    "attributes": {
      "unique_id": "journey_34567",
      "onboarding_unique_id": "onboarding_12345",
      "onboarding_name": "New User Onboarding",
      "step_unique_id": "step_67890",
      "step_order": 1,
      "step_name": "Complete Profile",
      "step_url": "https://app.example.com/profile",
      "step_status": "in_progress",
      "user_unique_id": "user_123",
      "progress": 0.0,
      "status": "active"
    }
  }
}

Get User Journey

curl -X GET https://onboarding.api.us.23blocks.com/users/user_123/journey \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key"

Progress Journey Step

curl -X PUT https://onboarding.api.us.23blocks.com/onboard/journey_34567 \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "step_status": "completed",
    "payload": {
      "completion_data": {
        "email": "user@example.com"
      }
    }
  }'

Suspend Journey

curl -X PUT https://onboarding.api.us.23blocks.com/onboard/journey_34567/suspend \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key"

Resume Journey

curl -X PUT https://onboarding.api.us.23blocks.com/onboard/journey_34567/resume \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key"

Email Templates

List Mail Templates

curl -X GET https://onboarding.api.us.23blocks.com/mailtemplates \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key"

Create Mail Template

curl -X POST https://onboarding.api.us.23blocks.com/mailtemplates \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "onboarding_welcome",
    "name": "Welcome Email",
    "template_html": "<html><body><h1>Welcome!</h1></body></html>",
    "template_text": "Welcome to our platform!",
    "from_address": "noreply@example.com",
    "from_name": "OnBoarding Team",
    "from_subject": "Welcome to Our Platform"
  }'

Send Journey Reminder

curl -X POST https://onboarding.api.us.23blocks.com/users/user_123/journey/reminder \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "reminder": {
      "template_id": "reminder_template"
    }
  }'

Analytics & Reporting

User Journey Summary

curl -X POST https://onboarding.api.us.23blocks.com/reports/user_journeys/summary \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "onboarding_unique_id": "onboarding_12345",
      "created_after": "2024-01-01T00:00:00Z"
    }
  }'

Response:

{
  "data": {
    "total_journeys": 150,
    "completed_journeys": 125,
    "completion_rate": 83.3,
    "average_completion_time": 3600,
    "abandonment_rate": 16.7
  }
}

Abandoned Journeys (Remarketing)

curl -X GET https://onboarding.api.us.23blocks.com/tools/remarketing/abandoned_journeys \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key"

Data Types

Onboarding

Field	Type	Description
`unique_id`	string	Unique identifier
`name`	string	Onboarding flow name
`description`	string	Detailed description
`total_steps`	integer	Number of steps
`status`	string	Flow status (active, inactive, draft)
`content_url`	string	URL to content
`image_url`	string	URL to image
`video_url`	string	URL to video

Step

Field	Type	Description
`unique_id`	string	Unique identifier
`name`	string	Step name
`order`	integer	Step sequence number
`step_url`	string	URL to complete step
`step_params`	object	Parameters for the step
`status`	string	Step status

UserJourney

Field	Type	Description
`unique_id`	string	Unique identifier
`onboarding_unique_id`	string	Parent onboarding ID
`user_unique_id`	string	User identifier
`step_unique_id`	string	Current step ID
`step_status`	string	Current step status
`progress`	float	Completion percentage (0-100)
`status`	string	Journey status (active, completed, suspended)
`next_step_url`	string	URL for next step
`attempts`	integer	Number of attempts

UserJourneyLog

Field	Type	Description
`unique_id`	string	Unique identifier
`step_name`	string	Step name
`step_status`	string	Step completion status
`started_at`	datetime	Step start timestamp
`completed_at`	datetime	Step completion timestamp
`elapsed`	integer	Time taken in seconds

MailTemplate

Field	Type	Description
`unique_id`	string	Unique identifier
`event_name`	string	Event trigger
`name`	string	Template name
`template_html`	string	HTML version
`template_text`	string	Plain text version
`from_address`	string	Sender email
`from_name`	string	Sender name
`from_subject`	string	Email subject
`provider`	string	Email provider (mandrill, sendgrid)

Error Handling

The API uses JSON:API error format:

{
  "error": "Error message",
  "details": "Detailed error description"
}

Common Error Codes

Status	Description
400	Invalid request data
401	Invalid authentication
403	Insufficient permissions
404	Resource not found
422	Validation errors
500	Server error

Rate Limiting

Endpoint Type	Limit
Standard endpoints	1000 requests/hour/API key
Authentication	100 requests/hour/IP
Bulk operations	50 requests/hour/API key

Rate limit headers in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642248000

SDK Examples

TypeScript/JavaScript

import { create23BlocksClient } from '@23blocks/sdk';

const client = create23BlocksClient({
  urls: { onboarding: 'https://onboarding.api.us.23blocks.com' },
  apiKey: process.env.BLOCKS_API_KEY,
});

// Create an onboarding flow
const onboarding = await client.onboarding.create({
  name: 'New User Setup',
  description: 'Guide new users through initial setup'
});

// Add steps
await client.onboarding.addStep(onboarding.uniqueId, {
  name: 'Complete Profile',
  order: 1,
  stepUrl: '/onboarding/profile'
});

await client.onboarding.addStep(onboarding.uniqueId, {
  name: 'Connect Integrations',
  order: 2,
  stepUrl: '/onboarding/integrations'
});

// Start user on journey
const journey = await client.onboarding.startUserJourney(
  'user_123',
  onboarding.uniqueId
);

// Check progress
const userJourney = await client.onboarding.getUserJourney('user_123');
console.log(`User progress: ${userJourney.progress}%`);

// Complete current step
await client.onboarding.progressStep(journey.uniqueId, {
  stepStatus: 'completed',
  payload: { profileComplete: true }
});

React Hook Example

import { useOnboarding } from '@23blocks/react';

function OnboardingFlow() {
  const {
    journey,
    currentStep,
    progress,
    completeStep,
    isLoading
  } = useOnboarding();

  const handleStepComplete = async () => {
    await completeStep({
      stepStatus: 'completed',
      payload: { completed: true }
    });
  };

  if (isLoading) return <div>Loading...</div>;

  return (
    <div>
      <h2>{currentStep?.name}</h2>
      <progress value={progress} max={100} />
      <p>{progress}% complete</p>

      {/* Step content */}
      <div dangerouslySetInnerHTML={{ __html: currentStep?.content }} />

      <button onClick={handleStepComplete}>
        Complete Step
      </button>
    </div>
  );
}

Multi-tenant Considerations

Each request operates within a tenant context determined by the X-API-Key header
Database operations are automatically scoped to the tenant's schema
Cross-tenant data access is prevented
Tenant context tokens (30-minute duration) can be used for app switching scenarios

API Reference - Interactive API documentation
Frontend SDK - Client-side integration
Platform Status - Service uptime monitoring

Key Features​

API Endpoint​

Quick Start​

Installation​

Basic Usage​

Authentication​

Required Headers​

Supported Auth Providers​

API Reference​

Onboarding Management​

List Onboardings​

Create Onboarding​

Add Step to Onboarding​

User Journey Management​

Start Onboarding Journey​

Get User Journey​

Progress Journey Step​

Suspend Journey​

Resume Journey​

Email Templates​

List Mail Templates​

Create Mail Template​

Send Journey Reminder​

Analytics & Reporting​

User Journey Summary​

Abandoned Journeys (Remarketing)​

Data Types​

Onboarding​

Step​

UserJourney​

UserJourneyLog​

MailTemplate​

Error Handling​

Common Error Codes​

Rate Limiting​

SDK Examples​

TypeScript/JavaScript​

React Hook Example​

Multi-tenant Considerations​

Related Resources​

Key Features

API Endpoint

Quick Start

Installation

Basic Usage

Authentication

Required Headers

Supported Auth Providers

API Reference

Onboarding Management

List Onboardings

Create Onboarding

Add Step to Onboarding

User Journey Management

Start Onboarding Journey

Get User Journey

Progress Journey Step

Suspend Journey

Resume Journey

Email Templates

List Mail Templates

Create Mail Template

Send Journey Reminder

Analytics & Reporting

User Journey Summary

Abandoned Journeys (Remarketing)

Data Types

Onboarding

Step

UserJourney

UserJourneyLog

MailTemplate

Error Handling

Common Error Codes

Rate Limiting

SDK Examples

TypeScript/JavaScript

React Hook Example

Multi-tenant Considerations

Related Resources