How to Integrate Retool with ADP

Before configuring Retool, you must register an application through ADP's developer ecosystem. Navigate to developers.adp.com and sign in with your ADP account. If your organization has an ADP Marketplace agreement, you may register through your ADP client administrator. In the developer portal, create a new application. Specify: - Application name: 'Retool Internal Dashboard' or similar - APIs needed: Select the specific ADP API products relevant to your use case: HR Management API (Workers), Payroll API (Pay), or Time Management API - Redirect URIs: For server-to-server (client credentials) flows, the redirect URI is not required, but you may need to specify a placeholder Once the application is created, ADP provides: 1. A Client ID (application identifier) 2. A Client Secret (confidential credential) 3. Instructions for generating or uploading an mTLS client certificate For the client certificate, ADP requires mutual TLS — every API call must present a client certificate that ADP verifies against your registered application. Generate a self-signed certificate or obtain one from your organization's PKI. Upload the public certificate (PEM format) to your ADP application configuration. Keep the private key secure. Store all credentials in Retool Settings → Configuration Variables as secret variables: ADP_CLIENT_ID, ADP_CLIENT_SECRET. The client certificate and private key require special handling — for self-hosted Retool, you can configure mTLS at the infrastructure level. For Retool Cloud, implement the token exchange in a JavaScript query that uses the certificate via a Node.js crypto library approach.

ADP's API requires an OAuth 2.0 Bearer token obtained via the client credentials grant type. The token request itself must also be made using the mTLS client certificate, making this a certificate-authenticated OAuth flow. Create a JavaScript query in your Retool app named getAdpToken. This query calls ADP's token endpoint. The ADP OAuth token URL for production is https://accounts.adp.com/auth/oauth/v2/token and for sandbox it is https://accounts.adpapis.com/auth/oauth/v2/token. The token request is a POST with: - Content-Type: application/x-www-form-urlencoded - Body: grant_type=client_credentials&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET} - The mTLS client certificate presented as part of the TLS handshake For Retool Cloud deployments where mTLS certificate configuration at the TLS layer is not possible, an alternative approach is to deploy a lightweight proxy service (a small Node.js or Python service in your infrastructure) that holds the client certificate and forwards authenticated requests. The Retool REST API Resource then points to this proxy rather than directly to ADP. For self-hosted Retool, configure the client certificate at the nginx or reverse proxy layer that fronts the Retool db_connector service. Set the certificate path in the db_connector environment configuration. Once configured, the token exchange and subsequent API calls are transparent — Retool presents the certificate automatically as part of each outbound HTTPS connection. Store the returned access_token in a Retool state variable. ADP tokens typically expire after 3600 seconds (1 hour). Run this query on page load and add an hourly refresh.

1// JavaScript query: exchange ADP client credentials for access token
2// Note: For full mTLS, this requires certificate configuration at the infrastructure level
3// For Retool Cloud, route through an mTLS-capable proxy service
4
5const clientId = retoolContext.configVars.ADP_CLIENT_ID;
6const clientSecret = retoolContext.configVars.ADP_CLIENT_SECRET;
7
8// Token endpoint — use sandbox URL for testing
9const tokenUrl = 'https://accounts.adp.com/auth/oauth/v2/token';
10
11const body = new URLSearchParams({
12  grant_type: 'client_credentials',
13  client_id: clientId,
14  client_secret: clientSecret
15}).toString();
16
17const response = await fetch(tokenUrl, {
18  method: 'POST',
19  headers: {
20    'Content-Type': 'application/x-www-form-urlencoded'
21  },
22  body: body
23  // mTLS certificate is configured at the infrastructure/proxy layer
24});
25
26const tokenData = await response.json();
27
28if (tokenData.access_token) {
29  await adpAccessToken.setValue(tokenData.access_token);
30  return { success: true, expires_in: tokenData.expires_in };
31} else {
32  throw new Error('ADP token exchange failed: ' + JSON.stringify(tokenData));
33}

Navigate to Resources tab → Add Resource → REST API. Configure the resource: - Name: ADP Workers API - Base URL: https://api.adp.com (production) or the ADP sandbox URL provided in your developer portal - Headers: Authorization: Bearer {{ adpAccessToken.value }} Click Save. Create a new query using this resource. Set the method to GET and the path to /hr/v2/workers. This is ADP's HR Management API endpoint for retrieving worker records. ADP's Workers endpoint supports several useful query parameters: - $top: {{ pagination.pageSize || 50 }} — number of records to return (ADP uses OData-style pagination) - $skip: {{ pagination.page * 50 || 0 }} — offset for pagination - $filter: add OData filter expressions for active workers: workers/workAssignments/assignmentStatus/statusCode/codeValue eq 'A' Set the query to Run on page load. Add a JavaScript transformer to flatten ADP's deeply nested response structure — ADP returns worker data with several layers of nesting (workers array → each worker → workAssignments array → businessCommunication → etc.). Drag a Table component onto the canvas. Bind it to {{ workersQuery.data }}. Configure columns for: associate OID (unique identifier), name, job title, department, location, hire date, and employment status. Add Search and filter components for department and location.

1// JavaScript transformer to flatten ADP Workers API response
2// ADP returns deeply nested JSON — this flattens it for Table display
3const workers = (data.workers || []);
4
5return workers.map(worker => {
6  const name = worker.person?.legalName || {};
7  const assignment = (worker.workAssignments || [])[0] || {};
8  const position = (assignment.homeOrganizationalUnits || [])[0] || {};
9  const dept = (assignment.homeOrganizationalUnits || []).find(u => u.typeCode?.codeValue === 'Department') || {};
10  const location = assignment.homeWorkLocation?.address?.cityName || '';
11
12  return {
13    associate_oid: worker.associateOID,
14    full_name: [name.givenName, name.familyName].filter(Boolean).join(' '),
15    job_title: assignment.jobTitle || '',
16    department: dept.nameCode?.longName || '',
17    location: location,
18    hire_date: assignment.hireDate || '',
19    status: assignment.assignmentStatus?.statusCode?.codeValue || '',
20    worker_id: assignment.workerID?.idValue || ''
21  };
22});

Extend your dashboard with payroll summary data. Create a second query using your ADP REST API Resource targeting the Pay API. ADP's Pay API endpoint for payroll run outputs is under the /payroll path. Set the method to GET and the path to /payroll/v1/payroll-output. Add query parameters for filtering by pay period. ADP's Pay API uses OData syntax for filtering: $filter=payrollAgreementID/idValue eq '{{ payGroupSelect.value }}'. Add a pay group Select component populated from a query to /payroll/v1/payroll-output (without filters) that returns available pay group IDs. The Pay API response includes earningsData, deductionsData, taxesData, and checkData arrays. Add a JavaScript transformer that aggregates these into department-level or cost-center-level summaries: Drag a second Table component onto a Payroll tab in your app. Bind it to the aggregated payroll data. Display columns: department/cost center, employee count, total gross pay, total deductions, total taxes, total net pay. Use Retool's Summary component (or a set of Stat components) to show organization-wide totals at the top. Add a DateRange or pay period Select component that filters the payroll query by pay period start/end dates. When the pay period changes, the query re-runs and the Table updates. For finance and HR leadership who need this data for budget reporting, add a download button that triggers a JavaScript query to format the table data as CSV and initiates a browser download using Retool's file download utility.

1// JavaScript transformer to aggregate ADP Pay API data by department
2const outputs = data.payrollOutput || data['payroll-output'] || [];
3
4// Aggregate by department cost center
5const deptMap = {};
6
7outputs.forEach(record => {
8  const dept = record.workerDepartmentCode || 'Unknown';
9  if (!deptMap[dept]) {
10    deptMap[dept] = { department: dept, employee_count: 0, gross_pay: 0, deductions: 0, taxes: 0, net_pay: 0 };
11  }
12  deptMap[dept].employee_count++;
13  deptMap[dept].gross_pay += parseFloat(record.totalGrossPayAmount?.amountValue || 0);
14  deptMap[dept].deductions += parseFloat(record.totalDeductionAmount?.amountValue || 0);
15  deptMap[dept].taxes += parseFloat(record.totalTaxAmount?.amountValue || 0);
16  deptMap[dept].net_pay += parseFloat(record.totalNetPayAmount?.amountValue || 0);
17});
18
19return Object.values(deptMap).map(d => ({
20  ...d,
21  gross_pay: d.gross_pay.toFixed(2),
22  deductions: d.deductions.toFixed(2),
23  taxes: d.taxes.toFixed(2),
24  net_pay: d.net_pay.toFixed(2)
25}));

Add a Time Management section to your HR dashboard using ADP's Time API. This gives managers visibility into their direct reports' time cards without requiring full ADP access. Create a third query using the ADP REST API Resource. Set the method to GET and the path to /time/v1/workers/{workerID}/time-cards (or the equivalent ADP Time API endpoint available in your subscription). Pass the worker IDs of the manager's direct reports as individual requests, or use the team-level endpoint if available in your ADP subscription. Since each manager should see only their team's data, add a personalization step: create a JavaScript query on page load that fetches the current Retool user's ADP worker ID from an internal mapping table (a PostgreSQL table that maps Retool user emails to ADP worker IDs). Then use that worker ID to query the ADP Workers API for the manager's direct reports, and use those worker IDs to fetch time card data. Drag a Table component onto a Time Cards tab. Display: employee name, pay period, regular hours, overtime hours, time-off hours, and approval status. Add conditional row colors for unapproved overtime (red) and time cards pending review (yellow). Add an Approve button that sends a POST or PATCH request to ADP's time approval endpoint for the selected employee's time card. Include a confirmation modal that shows the employee name and total hours being approved. In the success handler, refresh the time cards query and show a notification. For complex HR workflows involving ADP data combined with internal HR systems, Retool Workflows, and multi-step approval chains, RapidDev's team can help architect and implement the complete solution.

1// JavaScript transformer for ADP time cards
2const timeCards = Array.isArray(data) ? data : (data.timeCards || []);
3
4return timeCards.map(card => {
5  const totalRegular = parseFloat(card.regularHours?.quantity || 0);
6  const totalOT = parseFloat(card.overtimeHours?.quantity || 0);
7  const totalTO = parseFloat(card.timeOffHours?.quantity || 0);
8
9  return {
10    worker_id: card.worker?.workerID?.idValue || '',
11    employee_name: card.worker?.person?.legalName?.formattedName || '',
12    pay_period_start: card.payPeriod?.startDate || '',
13    pay_period_end: card.payPeriod?.endDate || '',
14    regular_hours: totalRegular.toFixed(2),
15    overtime_hours: totalOT.toFixed(2),
16    time_off_hours: totalTO.toFixed(2),
17    approval_status: card.approvalStatusCode?.codeValue || 'Pending',
18    has_unapproved_ot: totalOT > 0 && card.approvalStatusCode?.codeValue !== 'APPROVED'
19  };
20});