How to Integrate ADP with V0

Open V0 at v0.dev and describe the HR interface you want to build. ADP data is structured and tabular, so V0's table and card components work very well for displaying employee records, payroll data, and attendance metrics. Be specific about the data fields you want to display, the filters and search functionality you need, and the visual style. For an employee directory, describe the table columns, pagination behavior, and filter controls. For a payroll dashboard, describe the KPI cards, chart types, and reporting periods. V0 generates React components with Tailwind CSS and shadcn/ui, so you can ask for specific component patterns like data tables with sorting, filter dropdowns, date range pickers, and metric cards. The key information to give V0 is which API route your component will call (e.g., /api/adp/workers for employee data), what the response shape looks like (an array of worker objects with name, jobTitle, department, etc.), and how you want pagination to work. Include loading skeleton states and empty state handling in your V0 prompt, since ADP API calls can take a few seconds. After generating the UI, push it to GitHub using V0's Git panel, then connect the repository to Vercel for deployment.

Create the Next.js API routes that handle ADP's OAuth 2.0 authentication and proxy requests to ADP's data endpoints. ADP uses the client credentials grant type, where your server posts your client ID and secret to ADP's token endpoint and receives a bearer token in response. This token must be included in all subsequent API calls as an Authorization: Bearer header. Because serverless functions are stateless and a new token request on every API call would be slow and wasteful, implement a simple token caching strategy. In a Next.js serverless context, a module-level variable can cache the token and its expiry time — while this cache is per-function-instance and not shared across instances, it significantly reduces unnecessary token fetches since ADP tokens are typically valid for 30 minutes or more. The workers API endpoint returns an array of worker objects with structured data for each employee including their legal name, job title, department, work location, employment status, and hire date. The payroll API provides pay statement data organized by pay period. Always use the ADP sandbox environment (api.adp.com/sandbox) during development and switch to production only after thorough testing. ADP requires mutual TLS (mTLS) for production API calls, which means you need a certificate and private key in addition to the client credentials — for development with the sandbox, standard TLS works without certificates.

1// app/api/adp/workers/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3
4const ADP_AUTH_URL = 'https://accounts.adp.com/auth/oauth/v2/token';
5const ADP_API_BASE = 'https://api.adp.com';
6
7// Simple in-memory token cache (per function instance)
8let tokenCache: { token: string; expiresAt: number } | null = null;
9
10async function getADPAccessToken(): Promise<string> {
11  // Return cached token if still valid (with 60s buffer)
12  if (tokenCache && tokenCache.expiresAt > Date.now() + 60_000) {
13    return tokenCache.token;
14  }
15
16  const clientId = process.env.ADP_CLIENT_ID!;
17  const clientSecret = process.env.ADP_CLIENT_SECRET!;
18
19  const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');
20
21  const response = await fetch(ADP_AUTH_URL, {
22    method: 'POST',
23    headers: {
24      Authorization: `Basic ${credentials}`,
25      'Content-Type': 'application/x-www-form-urlencoded',
26    },
27    body: 'grant_type=client_credentials',
28  });
29
30  if (!response.ok) {
31    throw new Error(`ADP auth failed: ${response.status} ${response.statusText}`);
32  }
33
34  const data = await response.json();
35  const expiresIn = data.expires_in ?? 1800; // Default 30 minutes
36
37  tokenCache = {
38    token: data.access_token,
39    expiresAt: Date.now() + expiresIn * 1000,
40  };
41
42  return data.access_token;
43}
44
45export async function GET(request: NextRequest) {
46  const clientId = process.env.ADP_CLIENT_ID;
47  const clientSecret = process.env.ADP_CLIENT_SECRET;
48
49  if (!clientId || !clientSecret) {
50    return NextResponse.json(
51      { error: 'ADP credentials not configured' },
52      { status: 500 }
53    );
54  }
55
56  const { searchParams } = new URL(request.url);
57  const page = parseInt(searchParams.get('page') ?? '1', 10);
58  const pageSize = parseInt(searchParams.get('pageSize') ?? '25', 10);
59  const department = searchParams.get('department') ?? '';
60
61  const skip = (page - 1) * pageSize;
62  const queryParams = new URLSearchParams({
63    $top: pageSize.toString(),
64    $skip: skip.toString(),
65  });
66
67  if (department) {
68    queryParams.set('$filter', `department/departmentCode/codeValue eq '${department}'`);
69  }
70
71  try {
72    const token = await getADPAccessToken();
73
74    const response = await fetch(
75      `${ADP_API_BASE}/hr/v2/workers?${queryParams.toString()}`,
76      {
77        headers: {
78          Authorization: `Bearer ${token}`,
79          'Content-Type': 'application/json',
80        },
81      }
82    );
83
84    if (!response.ok) {
85      throw new Error(`ADP API error: ${response.status}`);
86    }
87
88    const data = await response.json();
89
90    // Normalize the ADP worker data structure
91    const workers = (data.workers ?? []).map((worker: Record<string, unknown>) => {
92      const person = worker.person as Record<string, unknown> ?? {};
93      const legalName = person.legalName as Record<string, unknown> ?? {};
94      const assignment = ((worker.workAssignments as unknown[]) ?? [])[0] as Record<string, unknown> ?? {};
95
96      return {
97        id: worker.associateOID,
98        firstName: legalName.givenName,
99        lastName: legalName.familyName1,
100        jobTitle: (assignment.jobTitle as string) ?? '',
101        department: ((assignment.homeOrganizationalUnits as unknown[]) ?? [])[0] as string ?? '',
102        workLocation: (assignment.baseRemuneration as string) ?? '',
103        status: (assignment.workerTypeCode as Record<string, unknown>)?.shortName ?? 'Active',
104        hireDate: (assignment.hireDate as string) ?? '',
105      };
106    });
107
108    return NextResponse.json({
109      workers,
110      totalCount: data['@odata.count'] ?? workers.length,
111      page,
112      pageSize,
113    });
114  } catch (error) {
115    const message = error instanceof Error ? error.message : 'Unknown error';
116    console.error('ADP API error:', message);
117    return NextResponse.json(
118      { error: 'Failed to fetch employee data', details: message },
119      { status: 500 }
120    );
121  }
122}

Update your V0-generated dashboard components to fetch from the Next.js API routes and handle the response data correctly. The employee directory component should call GET /api/adp/workers with pagination parameters (?page=1&pageSize=25) and update when the user changes page or applies department filters. React's useEffect hook combined with useState for the current page and filter values is the standard pattern for this kind of stateful data fetching in V0-generated client components. Make sure the component is marked 'use client' since it uses interactive state. For the department filter dropdown, you can either hardcode known department names (if your org structure is stable) or add a separate GET /api/adp/departments endpoint that fetches distinct department values. When the user applies a filter, pass it as a query parameter to the API route, which forwards it to ADP's OData filtering syntax. Error handling in the component should display a user-friendly message when the API route fails, rather than an empty table — a simple alert banner or error card works well for internal HR tools. For the payroll and time/attendance sections, create additional API routes following the same pattern: GET /api/adp/pay-statements and GET /api/adp/timecards. Each route authenticates with the same getADPAccessToken function (which you can extract into a shared lib/adp.ts utility), then calls the appropriate ADP endpoint. For complex ADP integrations with multiple API routes and data types, RapidDev's team can help architect the data fetching layer and ensure efficient token management across your serverless functions.

Push your code to GitHub and configure ADP credentials in Vercel. Open the Vercel Dashboard, select your project, and go to Settings → Environment Variables. Add ADP_CLIENT_ID with your ADP application client ID and ADP_CLIENT_SECRET with your client secret — both are found in the ADP Developer Portal under your app registration. If you are using the ADP sandbox environment for testing, also add ADP_ENV with the value 'sandbox' so your API routes can conditionally use the sandbox base URL instead of the production URL. Neither variable should have the NEXT_PUBLIC_ prefix since all ADP communication happens server-side. If your production ADP integration requires mTLS certificates, you will need to store the certificate and private key as environment variables or use Vercel's secret files feature — add ADP_CLIENT_CERT and ADP_CLIENT_KEY as base64-encoded PEM strings and decode them in your API route before using Node's https module with the agent option. Set all environment variables for Production, Preview, and Development environments, then save and trigger a redeployment from the Deployments tab. After deployment, open the deployed URL and verify that the employee directory loads correctly with live ADP data. If you see authentication errors, double-check that your client credentials match the environment (sandbox vs. production) and that the ADP app registration is active.