How to Integrate Marketo with V0

Marketo API access requires credentials from your Marketo admin panel. You need three pieces of information: the Munchkin Account ID, a Client ID, and a Client Secret. These come from creating an API-only role and user in Marketo, then generating a LaunchPoint service. Step 1 — Create an API Role: In Marketo, go to Admin → Users & Roles → Roles → New Role. Name it 'API Integration Role'. Enable permissions based on what your integration needs: Access API (required), Read-Only Lead (for fetching leads), Read-Write Lead (for creating/updating leads), Access Analytics (for program data). Click Save. Step 2 — Create an API-Only User: Go to Admin → Users & Roles → Users → Invite New User. Enter an email (can be a service account email), set API Only: Yes. Assign the API Integration Role you created. Step 3 — Create a LaunchPoint Service: Go to Admin → LaunchPoint → New Service. Name it, select 'Custom' as service type, and assign the API-only user you created. After saving, click View Details to get the Client ID and Client Secret. Step 4 — Get your REST API base URL: Go to Admin → Web Services → REST API section. Your endpoint URL looks like: https://abc-123-xyz.mktorest.com. This is your MARKETO_BASE_URL. Your Munchkin Account ID is the subdomain portion (abc-123-xyz). Note: API credentials in Marketo are organization-level, not user-level. Anyone with Admin access can view and regenerate these credentials.

Marketo's authentication works in two steps: first call the identity endpoint to get an access token, then use that token in API requests. Access tokens expire after 3600 seconds (1 hour). Because V0 apps are deployed as serverless functions, implement a module-level token cache that reuses valid tokens across warm function invocations — this prevents unnecessary authentication API calls on every request. Create lib/marketo.ts as a shared authentication module that your API routes import. This separation keeps authentication logic in one place and makes it easy to update when Marketo changes their token endpoint. Marketo's token endpoint format is: {MARKETO_BASE_URL}/identity/oauth/token?grant_type=client_credentials&client_id={clientId}&client_secret={clientSecret}. The response includes an access_token and expires_in value in seconds. Marketo's API returns errors in two ways: HTTP-level errors (4xx, 5xx) and application-level errors embedded in a 200 OK response with a success: false field and an errors array. Always check both the HTTP status AND the success field in Marketo API responses — this is different from most APIs and is a common source of bugs in V0-generated Marketo integration code. Rate limits are a critical consideration for Marketo. Their REST API enforces: 100 calls per 20 seconds per access token (burst), and daily limits vary by subscription tier. Add error handling for HTTP 429 responses and implement basic retry logic with a delay.

1// lib/marketo.ts
2// Shared Marketo authentication utility
3
4interface TokenCache {
5  accessToken: string;
6  expiresAt: number;
7}
8
9let tokenCache: TokenCache | null = null;
10
11export async function getMarketoToken(): Promise<string> {
12  // Return cached token if still valid (with 5-minute buffer)
13  if (tokenCache && Date.now() < tokenCache.expiresAt - 300000) {
14    return tokenCache.accessToken;
15  }
16
17  const baseUrl = process.env.MARKETO_BASE_URL;
18  const clientId = process.env.MARKETO_CLIENT_ID;
19  const clientSecret = process.env.MARKETO_CLIENT_SECRET;
20
21  if (!baseUrl || !clientId || !clientSecret) {
22    throw new Error('Marketo environment variables not configured');
23  }
24
25  const tokenUrl = `${baseUrl}/identity/oauth/token?grant_type=client_credentials&client_id=${clientId}&client_secret=${clientSecret}`;
26
27  const response = await fetch(tokenUrl);
28  if (!response.ok) {
29    throw new Error(`Marketo auth failed: ${response.status}`);
30  }
31
32  const data = await response.json();
33  if (!data.access_token) {
34    throw new Error('Marketo returned no access token');
35  }
36
37  tokenCache = {
38    accessToken: data.access_token,
39    expiresAt: Date.now() + data.expires_in * 1000,
40  };
41
42  return tokenCache.accessToken;
43}
44
45export async function marketoRequest(
46  path: string,
47  options: RequestInit = {}
48): Promise<Response> {
49  const accessToken = await getMarketoToken();
50  const baseUrl = process.env.MARKETO_BASE_URL;
51
52  const url = `${baseUrl}/rest${path}`;
53
54  const response = await fetch(url, {
55    ...options,
56    headers: {
57      'Authorization': `Bearer ${accessToken}`,
58      'Content-Type': 'application/json',
59      ...(options.headers || {}),
60    },
61  });
62
63  return response;
64}
65
66// Marketo returns errors in a success: false response with HTTP 200
67// This helper checks both HTTP status and application-level success
68export async function parseMarketoResponse(response: Response) {
69  const data = await response.json();
70
71  if (!response.ok) {
72    throw new Error(`Marketo HTTP error: ${response.status}`);
73  }
74
75  if (data.success === false) {
76    const error = data.errors?.[0];
77    throw new Error(error?.message || 'Marketo API error');
78  }
79
80  return data;
81}

Create app/api/marketo/leads/route.ts for submitting new leads to Marketo from your V0 forms. Marketo's lead creation uses an 'upsert' endpoint — it creates the lead if the email does not exist, or updates the existing lead record if it does. This means form submissions are idempotent: submitting the same email twice updates the record rather than creating a duplicate. Marketo's create/update lead endpoint is POST /rest/v1/leads.json. The request body contains an action (createOrUpdate is standard), lookupField (email is the standard deduplication field), and input array (array of lead objects even when creating just one). After creating the lead in Marketo, you typically also want to add them to a specific Marketo program (nurture sequence, webinar, etc.) to trigger automated workflows. This is done via the Add Lead to Program endpoint: POST /rest/v1/programs/{programId}/leads.json. Include the programId as an environment variable or pass it in the form data for multi-program sites. Marketo does NOT return a conflict error for existing leads by default — the createOrUpdate action handles duplicates silently by updating the existing record. If you need to detect whether a lead was new or updated, check the result[0].status field in the response (it will be 'created' or 'updated').

1import { NextRequest, NextResponse } from 'next/server';
2import { marketoRequest, parseMarketoResponse } from '@/lib/marketo';
3
4export async function POST(request: NextRequest) {
5  const body = await request.json();
6  const {
7    firstName,
8    lastName,
9    email,
10    company,
11    companySize,
12    phone,
13    message,
14    marketingOptIn,
15    programId,
16  } = body;
17
18  // Validate required fields
19  if (!firstName || !lastName || !email || !company) {
20    return NextResponse.json(
21      { error: 'firstName, lastName, email, and company are required' },
22      { status: 400 }
23    );
24  }
25
26  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
27  if (!emailRegex.test(email)) {
28    return NextResponse.json({ error: 'Invalid email address format' }, { status: 400 });
29  }
30
31  try {
32    // Step 1: Create or update lead in Marketo
33    const leadResponse = await marketoRequest('/v1/leads.json', {
34      method: 'POST',
35      body: JSON.stringify({
36        action: 'createOrUpdate',
37        lookupField: 'email',
38        input: [
39          {
40            firstName,
41            lastName,
42            email,
43            company,
44            // Map custom fields to your Marketo field API names
45            numberOfEmployees: companySize,
46            phone: phone || '',
47            leadDescription: message || '',
48            emailOptedIn: marketingOptIn === true,
49            leadSource: 'Website Form',
50          },
51        ],
52      }),
53    });
54
55    const leadData = await parseMarketoResponse(leadResponse);
56    const leadResult = leadData.result?.[0];
57
58    if (!leadResult?.id) {
59      return NextResponse.json({ error: 'Lead creation failed' }, { status: 500 });
60    }
61
62    // Step 2: Optionally add to a program to trigger nurture sequence
63    const targetProgramId = programId || process.env.MARKETO_DEFAULT_PROGRAM_ID;
64    if (targetProgramId) {
65      const programResponse = await marketoRequest(`/v1/programs/${targetProgramId}/leads.json`, {
66        method: 'POST',
67        body: JSON.stringify({
68          input: [{ id: leadResult.id }],
69        }),
70      });
71      // Don't block on program membership errors — log and continue
72      const programData = await programResponse.json();
73      if (!programData.success) {
74        console.warn('Failed to add lead to program:', programData.errors);
75      }
76    }
77
78    return NextResponse.json({
79      success: true,
80      leadId: leadResult.id,
81      status: leadResult.status, // 'created' or 'updated'
82    });
83  } catch (error) {
84    console.error('Marketo lead submission error:', error);
85    const errorMessage = error instanceof Error ? error.message : 'Lead submission failed';
86    return NextResponse.json({ error: errorMessage }, { status: 500 });
87  }
88}

Configure your Marketo credentials in Vercel environment variables. You need MARKETO_BASE_URL (format: https://xxx-xxx-xxx.mktorest.com), MARKETO_CLIENT_ID, MARKETO_CLIENT_SECRET, and optionally MARKETO_DEFAULT_PROGRAM_ID (the ID of your default nurture program for lead submission). In Vercel Dashboard → your project → Settings → Environment Variables, add each variable as server-only (no NEXT_PUBLIC_ prefix). The base URL is not secret per se (it is visible in Marketo's Munchkin JavaScript), but storing it as an environment variable makes your deployment configuration cleaner. After adding all variables and redeploying, test your lead submission endpoint by submitting your own test form. Then verify in Marketo → Lead Database → All Leads that the test lead appeared with the correct fields populated. If the lead does not appear, check Vercel Function Logs for the Marketo API error response. Marketo field mapping is often the most time-consuming part of the integration. If your test lead appears in Marketo but fields are blank or mapped to the wrong place, you need to cross-reference the field API names in Marketo Admin → Field Management. Marketo custom fields have different API names than their display names, and these names vary per Marketo instance — there is no universal standard.