How to Integrate Bolt.new with Ortto (Autopilot)

Ortto uses simple API key authentication — all requests include your key in the Authorization header as 'Bearer {apiKey}'. No OAuth flows, no token expiry, no scopes to configure. To get your API key, log into Ortto, click your account name in the top-left corner, select Settings, then navigate to the API section (or search for 'API' in Settings). Click 'New API Key', give it a descriptive name like 'Bolt.new App', and copy the generated key. Store it immediately since Ortto may not let you see the full key again after initial creation. Ortto's API base URL is https://api.ap3api.com/v1/ for the current version. If you find older documentation referencing Autopilot's API (api.autopilothq.com), those endpoints have been migrated to the new domain with some path changes. The primary endpoints for most Bolt.new integrations are: person/merge for creating or updating contacts, activity/create for firing custom activities, and person/get for fetching contact data. One important concept in Ortto: contacts are identified by email address. When you call person/merge, Ortto checks if a contact with that email already exists and updates them, or creates a new one. This upsert behavior means you can safely call the merge endpoint for both new signups and existing user profile updates — Ortto handles deduplication automatically. Custom fields are defined in Ortto's interface (Data → Custom Fields) and then referenced in your API calls using their field ID. Ortto uses a workspace-based data model. All API calls are scoped to the workspace associated with your API key. Most single-product companies have one workspace; agencies may have multiple. The workspace ID does not need to be passed in API calls — it is determined by the API key.

1# .env — add to project root in Bolt
2# Found at: Ortto → Settings → API Keys → New API Key
3ORTTO_API_KEY=your_ortto_api_key_here
4
5# Ortto API base URL
6# Note: formerly api.autopilothq.com (legacy Autopilot)
7ORTTO_API_BASE=https://api.ap3api.com/v1

The person/merge endpoint is the foundation of the Ortto integration — it creates new contacts or updates existing ones by email, keeping your Ortto contact database in sync with your Bolt.new app's user data. This endpoint handles deduplication automatically, making it safe to call whenever user data changes without worrying about creating duplicates. The request body for person/merge is a JSON object with a fields property containing the contact's data. The email field is required and used for deduplication. Other standard fields include first_name, last_name, phone, company, and website. Custom fields you have defined in Ortto are referenced by their field ID in the custom_fields property. The response includes the contact's Ortto ID (person_id) which you can store in your Supabase user table for future reference. Create a Next.js API route that handles contact upserts. The route accepts your app's user data (from form submissions, sign-up events, or profile updates), formats it for Ortto's API, and calls person/merge. Since this is an outbound HTTP call from your server to Ortto's servers, it works in Bolt's WebContainer development preview — no deployment required for testing. For a sign-up flow integration: call this API route after successful user creation in Supabase. Pass the user's email, name, plan type (if applicable), and any other relevant attributes you want to track in Ortto. Ortto will create the contact and make them available for journey enrollment, email targeting, and segmentation. Add the Ortto person_id to your Supabase users table as an ortto_id column for fast lookups when firing activities for existing users.

1// lib/ortto-client.ts
2const ORTTO_BASE = process.env.ORTTO_API_BASE || 'https://api.ap3api.com/v1';
3
4async function orttoRequest<T>(
5  endpoint: string,
6  body: unknown,
7  method: 'POST' | 'GET' = 'POST'
8): Promise<T> {
9  const apiKey = process.env.ORTTO_API_KEY;
10  if (!apiKey) throw new Error('ORTTO_API_KEY not configured');
11
12  const res = await fetch(`${ORTTO_BASE}${endpoint}`, {
13    method,
14    headers: {
15      Authorization: `Bearer ${apiKey}`,
16      'Content-Type': 'application/json',
17    },
18    body: method === 'POST' ? JSON.stringify(body) : undefined,
19  });
20
21  if (!res.ok) {
22    const error = await res.json().catch(() => ({ message: res.statusText }));
23    throw new Error(`Ortto API error ${res.status}: ${JSON.stringify(error)}`);
24  }
25
26  return res.json();
27}
28
29export interface OrttoContact {
30  email: string;
31  firstName?: string;
32  lastName?: string;
33  phone?: string;
34  company?: string;
35  customFields?: Record<string, string | number | boolean>;
36}
37
38export async function upsertContact(contact: OrttoContact) {
39  const body = {
40    fields: {
41      str::email: contact.email,
42      str::first: contact.firstName || '',
43      str::last: contact.lastName || '',
44      str::phone: contact.phone || '',
45      str::company: contact.company || '',
46      ...contact.customFields,
47    },
48    merge_by: ['str::email'], // Deduplicate by email
49    find_strategy: 0, // 0 = upsert
50  };
51
52  return orttoRequest<{ people: Array<{ id: string; fields: Record<string, unknown> }> }>(
53    '/person/merge',
54    body
55  );
56}
57
58export async function getContact(email: string) {
59  const body = {
60    filter: {
61      type: 'and',
62      filters: [{
63        field: { field_name: 'str::email', data_type: 'str' },
64        type: 'exact',
65        value: email,
66      }],
67    },
68    fields: ['str::email', 'str::first', 'str::last'],
69    limit: 1,
70  };
71
72  return orttoRequest<{ contacts: Array<Record<string, unknown>> }>('/person/get', body);
73}
74
75// app/api/ortto/contacts/route.ts
76import { NextResponse } from 'next/server';
77import { upsertContact } from '@/lib/ortto-client';
78
79export async function POST(request: Request) {
80  try {
81    const { email, firstName, lastName, company, customFields } = await request.json();
82
83    if (!email) {
84      return NextResponse.json({ error: 'Email is required' }, { status: 400 });
85    }
86
87    const result = await upsertContact({ email, firstName, lastName, company, customFields });
88    const person = result.people?.[0];
89
90    return NextResponse.json({
91      success: true,
92      personId: person?.id,
93    });
94  } catch (error) {
95    const message = error instanceof Error ? error.message : 'Failed to upsert contact';
96    return NextResponse.json({ error: message }, { status: 500 });
97  }
98}

Custom Activities are the most powerful part of the Ortto integration. Where contact creation adds a person to Ortto, activities represent things they do — and Ortto journeys react to these activities automatically. An activity could be 'User Completed Onboarding', 'Subscription Upgraded to Pro', 'Feature X Used for the First Time', or 'Invoice Paid'. When your Bolt.new app fires an activity, any Ortto journey that starts with 'When contact does activity X' runs for that contact. Before you can fire an activity from the API, you need to define it in Ortto's interface. Go to Ortto → Data → Activities → New Activity. Give it a name and optionally define attributes (data that can be attached to each activity instance). For example, a 'Plan Upgraded' activity might have attributes: previous_plan (string), new_plan (string), and mrr_cents (integer). These attributes are available in Ortto journeys for personalization and conditional branching. The activity creation API call is POST /v1/activity/create. The body includes the activity_id (from Ortto's activity settings), the contact identified by email, and optionally activity attributes. The activity_id is the machine-readable key you set when creating the activity in Ortto — typically snake_case like 'user_onboarding_completed' or 'subscription_upgraded'. For your Bolt.new app, fire activities at meaningful points in the user lifecycle: after onboarding completion, when a subscription upgrades, when a key feature is used for the first time, when a user invites a team member. Each activity gives Ortto's journey engine the signals it needs to send the right email at the right time. Build a centralized track() function in your Ortto client utility that any part of your app can call with a contact email, activity name, and optional attributes — this keeps the tracking logic consistent across the app.

1// Add to lib/ortto-client.ts
2
3export async function trackActivity(
4  personEmail: string,
5  activityId: string,
6  attributes?: Record<string, string | number | boolean>
7) {
8  const body = {
9    activities: [
10      {
11        activity_id: activityId,
12        // Identify the contact by email
13        attributes: {
14          'str::email': personEmail,
15          ...attributes,
16        },
17      },
18    ],
19  };
20
21  return orttoRequest<{ count: number }>('/activity/create', body);
22}
23
24// app/api/ortto/activities/route.ts
25import { NextResponse } from 'next/server';
26import { trackActivity, upsertContact } from '@/lib/ortto-client';
27
28export async function POST(request: Request) {
29  try {
30    const { email, activityId, attributes, contactData } = await request.json();
31
32    if (!email || !activityId) {
33      return NextResponse.json(
34        { error: 'email and activityId are required' },
35        { status: 400 }
36      );
37    }
38
39    // Ensure the contact exists in Ortto before firing the activity
40    if (contactData) {
41      await upsertContact({ email, ...contactData });
42    }
43
44    const result = await trackActivity(email, activityId, attributes);
45
46    return NextResponse.json({
47      success: true,
48      activitiesCreated: result.count,
49    });
50  } catch (error) {
51    const message = error instanceof Error ? error.message : 'Failed to track activity';
52    return NextResponse.json({ error: message }, { status: 500 });
53  }
54}

Ortto can send webhook notifications to your Bolt.new app when specific events occur in Ortto's system — for example, when a contact is added to a journey, when an email is opened, or when a custom activity is completed. These outgoing webhooks from Ortto's servers let your app react to marketing automation events in real time. During development in Bolt's WebContainer, incoming webhooks cannot reach the browser-based runtime. Ortto's servers need to POST to a publicly accessible URL, and the WebContainer has no public URL — it runs inside a browser tab. This means webhook handlers must be built and tested after deploying to Netlify or Bolt Cloud. Once deployed, configure Ortto webhooks in Settings → Integrations → Webhooks → Add Webhook. Enter your deployed URL (e.g., https://your-app.netlify.app/api/webhooks/ortto) and select the events you want to receive. Ortto sends webhooks as JSON POST requests with event type and payload data in the body. Create a webhook handler API route that parses the incoming event and processes it — for example, updating a Supabase record when a contact completes a journey, logging email open events, or triggering a Slack notification when a high-value activity completes. Ortto webhook requests may include a signature header for verification (check Ortto's current documentation for the verification method, as it varies by Ortto version). Always return a 200 response quickly — process the webhook event asynchronously if the processing takes more than a few seconds. A common pattern is to save the raw webhook payload to a Supabase table immediately, then process it in a separate background operation. For production deployments, set ORTTO_API_KEY as a server-side environment variable in Netlify (Site settings → Environment variables) without the NEXT_PUBLIC_ prefix. Update this variable if you ever rotate your Ortto API key.

1// app/api/webhooks/ortto/route.ts
2import { NextResponse } from 'next/server';
3import { createClient } from '@supabase/supabase-js';
4
5interface OrttoWebhookPayload {
6  event: string;
7  contact?: { email?: string; id?: string };
8  activity?: { type: string; attributes?: Record<string, unknown> };
9  [key: string]: unknown;
10}
11
12export async function POST(request: Request) {
13  let payload: OrttoWebhookPayload;
14
15  try {
16    payload = await request.json();
17  } catch {
18    return NextResponse.json({ error: 'Invalid JSON body' }, { status: 400 });
19  }
20
21  const supabase = createClient(
22    process.env.NEXT_PUBLIC_SUPABASE_URL!,
23    process.env.SUPABASE_SERVICE_ROLE_KEY! // Service role bypasses RLS for event logging
24  );
25
26  // Log all events to Supabase for auditing
27  await supabase.from('ortto_events').insert({
28    event_type: payload.event,
29    contact_email: payload.contact?.email || null,
30    payload,
31    received_at: new Date().toISOString(),
32  }).then(({ error }) => {
33    if (error) console.error('Failed to log Ortto event:', error);
34  });
35
36  // Handle specific event types
37  switch (payload.event) {
38    case 'contact.unsubscribed':
39      if (payload.contact?.email) {
40        await supabase
41          .from('users')
42          .update({ marketing_opt_out: true })
43          .eq('email', payload.contact.email);
44      }
45      break;
46
47    case 'contact.email_opened':
48      if (payload.contact?.email) {
49        await supabase
50          .from('users')
51          .update({ last_email_opened_at: new Date().toISOString() })
52          .eq('email', payload.contact.email);
53      }
54      break;
55
56    default:
57      console.log(`Ortto webhook received: ${payload.event}`);
58  }
59
60  // Always return 200 quickly
61  return NextResponse.json({ received: true });
62}