How to Integrate Zoho CRM with V0

Navigate to Zoho's API Console at api-console.zoho.com. Click 'Add Client' and select 'Server-based Applications' as the client type. Enter a name like 'My V0 App', set the Authorized Redirect URI to `https://your-app.vercel.app/api/auth/zoho/callback` (you'll also add localhost for development), and click 'Create'. After creating the client, you'll see your Client ID and Client Secret. Copy both — you'll add them to Vercel environment variables. These credentials identify your application when making OAuth requests. For server-to-server integration (your app accessing your own CRM, not your users' CRMs), the recommended approach is generating a refresh token once and storing it. In the Zoho API Console, click on your app, then go to the 'Self Client' tab. Enter the required OAuth scopes for CRM access: `ZohoCRM.modules.ALL` for full access, or more specific scopes like `ZohoCRM.modules.Leads.CREATE,ZohoCRM.modules.Contacts.ALL` for limited access. Set the time duration to '10 minutes' and click 'Create'. Zoho generates a one-time authorization code. To exchange this code for a refresh token, make a POST request to `https://accounts.zoho.com/oauth/v2/token` with parameters: `code={your_code}`, `client_id={your_client_id}`, `client_secret={your_client_secret}`, `redirect_uri=https://your-app.vercel.app/api/auth/zoho/callback`, `grant_type=authorization_code`. The response includes a `refresh_token` — save this value, you won't see it again. This refresh token doesn't expire (unless you revoke it) and is what your API route will use to generate fresh access tokens.

Create a Next.js API route at `app/api/zoho/route.ts` that handles both token refresh and Zoho CRM API calls. The OAuth2 token refresh flow works as follows: your route calls Zoho's token endpoint with the refresh token to get a new access token (valid for 1 hour), then uses that access token in the Authorization header for Zoho CRM API calls. Zoho's CRM v3 API base URL depends on your data center: `https://www.zohoapis.com/crm/v3/` for US, `https://www.zohoapis.eu/crm/v3/` for Europe, `https://www.zohoapis.in/crm/v3/` for India. Store this as an environment variable. For creating leads, POST to `/crm/v3/Leads` with the lead data in a `data` array. Zoho's API wraps all records in an array even when creating a single record — this is the most common mistake developers make. The response includes the created record ID and status. For fetching contacts and deals, use GET requests to `/crm/v3/Contacts` and `/crm/v3/Deals`. Add `fields` parameter to specify which fields to return (avoiding fetching all 100+ CRM fields when you only need 5). Use `sort_by` and `sort_order` for ordering, and `page` with `per_page` for pagination. To avoid making a token refresh call on every API request (which wastes time and counts against Zoho's token call limits), cache the access token in a module-level variable with its expiry time. If the cached token is still valid (more than 5 minutes remaining), reuse it. Only refresh when the token is expired or about to expire.

1// app/api/zoho/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3
4const ZOHO_CLIENT_ID = process.env.ZOHO_CLIENT_ID!;
5const ZOHO_CLIENT_SECRET = process.env.ZOHO_CLIENT_SECRET!;
6const ZOHO_REFRESH_TOKEN = process.env.ZOHO_REFRESH_TOKEN!;
7const ZOHO_API_BASE = process.env.ZOHO_API_BASE || 'https://www.zohoapis.com/crm/v3';
8const ZOHO_ACCOUNTS_URL = process.env.ZOHO_ACCOUNTS_URL || 'https://accounts.zoho.com';
9
10// Module-level token cache
11let cachedToken: { token: string; expiresAt: number } | null = null;
12
13async function getAccessToken(): Promise<string> {
14  if (cachedToken && Date.now() < cachedToken.expiresAt - 60_000) {
15    return cachedToken.token;
16  }
17  const res = await fetch(`${ZOHO_ACCOUNTS_URL}/oauth/v2/token`, {
18    method: 'POST',
19    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
20    body: new URLSearchParams({
21      refresh_token: ZOHO_REFRESH_TOKEN,
22      client_id: ZOHO_CLIENT_ID,
23      client_secret: ZOHO_CLIENT_SECRET,
24      grant_type: 'refresh_token',
25    }),
26  });
27  const data = await res.json();
28  if (!data.access_token) throw new Error(`Token refresh failed: ${JSON.stringify(data)}`);
29  cachedToken = { token: data.access_token, expiresAt: Date.now() + data.expires_in * 1000 };
30  return data.access_token;
31}
32
33async function zohoFetch(method: string, path: string, body?: object) {
34  const token = await getAccessToken();
35  const res = await fetch(`${ZOHO_API_BASE}${path}`, {
36    method,
37    headers: {
38      Authorization: `Zoho-oauthtoken ${token}`,
39      'Content-Type': 'application/json',
40    },
41    body: body ? JSON.stringify(body) : undefined,
42  });
43  return res.json();
44}
45
46export async function POST(request: NextRequest) {
47  const { resource, data } = await request.json();
48  if (!resource || !data) return NextResponse.json({ error: 'resource and data required' }, { status: 400 });
49
50  try {
51    // Zoho requires records wrapped in { data: [] } array
52    const result = await zohoFetch('POST', `/${resource}`, { data: [data] });
53    return NextResponse.json(result);
54  } catch (err: any) {
55    return NextResponse.json({ error: err.message }, { status: 500 });
56  }
57}
58
59export async function GET(request: NextRequest) {
60  const { searchParams } = new URL(request.url);
61  const resource = searchParams.get('resource') || 'Contacts';
62  const fields = searchParams.get('fields') || 'id,Full_Name,Email,Phone,Lead_Status';
63  const page = searchParams.get('page') || '1';
64
65  try {
66    const result = await zohoFetch('GET', `/${resource}?fields=${fields}&page=${page}&per_page=50`);
67    return NextResponse.json(result);
68  } catch (err: any) {
69    return NextResponse.json({ error: err.message }, { status: 500 });
70  }
71}

Navigate to your Vercel project → Settings → Environment Variables. Add the following variables, all as server-only (no NEXT_PUBLIC_ prefix). Add `ZOHO_CLIENT_ID` — the Client ID from your Zoho API Console application. Add `ZOHO_CLIENT_SECRET` — the Client Secret from the same application. Add `ZOHO_REFRESH_TOKEN` — the refresh token you generated in the Self Client flow. This is the most sensitive credential — treat it like a password and never commit it to Git. Add `ZOHO_API_BASE` — the Zoho CRM API base URL for your data center. US customers use `https://www.zohoapis.com/crm/v3`. European customers use `https://www.zohoapis.eu/crm/v3`. Indian customers use `https://www.zohoapis.in/crm/v3`. If you're unsure which data center you're on, log into Zoho CRM and check the URL — it will show your region. Add `ZOHO_ACCOUNTS_URL` — the Zoho accounts URL for token refresh. US: `https://accounts.zoho.com`, EU: `https://accounts.zoho.eu`, India: `https://accounts.zoho.in`. This must match your data center. After saving all variables, redeploy the application. Test the integration by making a POST request to `/api/zoho` with `{ resource: 'Leads', data: { Last_Name: 'Test', Email: 'test@example.com', Company: 'Test Co' } }` and verify the lead appears in your Zoho CRM. For EU GDPR compliance and other regional requirements, ensure all data is routed to the correct Zoho data center. Using the US endpoint from a EU-based app violates GDPR data residency requirements.

Update the V0-generated lead capture form to submit data to your Zoho API route. Map form fields to Zoho CRM's field API names — Zoho's field names use specific formats that differ from display names. Key Zoho CRM Lead field API names: `Last_Name` (required for Leads module), `First_Name`, `Email`, `Phone`, `Company` (required), `Lead_Source` (dropdown — values must match Zoho CRM's picklist: 'Web Site', 'Cold Call', 'Employee Referral', 'Partner', etc.), `Lead_Status` (default: 'Not Contacted'), `Description`. In your form submit handler, construct the Zoho data object with correct field names and POST to `/api/zoho`. Handle the response — Zoho returns a `data` array with status objects. A successful creation shows `{ code: 'SUCCESS', status: 'success', id: '...' }`. Handle duplicate records — if a lead with the same email exists, Zoho may return a duplicate error depending on your CRM's duplicate check settings. For additional automation value, add UTM parameter tracking to form submissions. Read UTM parameters from the URL (`document.referrer`, `window.location.search`) and include them in the lead's `Lead_Source` or custom fields. This tells your sales team exactly which campaign or ad drove each lead. For the CRM dashboard view, fetch leads from `/api/zoho?resource=Leads&fields=id,First_Name,Last_Name,Email,Company,Lead_Source,Lead_Status,Created_Time` and map them to table rows or Kanban cards. The dashboard should show each lead's status in the pipeline and allow clicking through to view more detail.

1// Form submit handler for Zoho lead creation
2async function handleFormSubmit(formData: {
3  firstName: string;
4  lastName: string;
5  email: string;
6  phone: string;
7  company: string;
8  message: string;
9  leadSource: string;
10}) {
11  const zohoLead = {
12    First_Name: formData.firstName,
13    Last_Name: formData.lastName,
14    Email: formData.email,
15    Phone: formData.phone,
16    Company: formData.company,
17    Description: formData.message,
18    Lead_Source: formData.leadSource,
19    Lead_Status: 'Not Contacted',
20  };
21
22  const res = await fetch('/api/zoho', {
23    method: 'POST',
24    headers: { 'Content-Type': 'application/json' },
25    body: JSON.stringify({ resource: 'Leads', data: zohoLead }),
26  });
27
28  const result = await res.json();
29  const status = result.data?.[0];
30
31  if (status?.status === 'success') {
32    return { success: true, id: status.details?.id };
33  } else if (status?.code === 'DUPLICATE_DATA') {
34    return { success: false, error: 'A contact with this email already exists.' };
35  } else {
36    return { success: false, error: 'Failed to submit. Please try again.' };
37  }
38}