How to Integrate Retool with Zoho CRM

Navigate to the Zoho Developer Console at developer.zoho.com (make sure you are logged in with your Zoho account). Click 'Add Client' and select 'Self Client' as the client type. Self-client is designed specifically for server-to-server integrations where there is no end-user browser redirect — it is the correct choice for Retool. Give the application a name like 'Retool CRM Integration' and click 'Create'. The Developer Console displays a Client ID and Client Secret — copy both values immediately. Next, you need to generate a refresh token. In the self-client application details, click 'Generate Code'. Enter the scopes your integration needs — for full CRM access, enter: ZohoCRM.modules.ALL,ZohoCRM.settings.ALL,ZohoCRM.bulk.ALL. Set the time duration to 3 minutes (the code is valid briefly). Copy the generated authorization code. Now make an API call to exchange this code for a refresh token: POST to accounts.zoho.com/oauth/v2/token with client_id, client_secret, code, redirect_uri=urn:ietf:wg:oauth:2.0:oob, and grant_type=authorization_code. You can use Postman or curl for this step. The response contains a refresh_token — this is long-lived and what Retool will use.

1// Exchange authorization code for refresh token
2// POST https://accounts.zoho.com/oauth/v2/token
3// (Adjust domain for your data center: .eu, .in, .com.au)
4
5// Form parameters:
6// client_id=your_client_id
7// client_secret=your_client_secret
8// code=the_authorization_code_from_developer_console
9// redirect_uri=urn:ietf:wg:oauth:2.0:oob
10// grant_type=authorization_code
11
12// Response includes:
13// {
14//   "access_token": "short-lived (1 hour)",
15//   "refresh_token": "long-lived - SAVE THIS",
16//   "token_type": "Bearer"
17// }

In Retool, go to Resources → Create New → REST API. Set the Base URL to your Zoho CRM API endpoint based on your data center: 'https://www.zohoapis.com/crm/v7' for US accounts, 'https://www.zohoapis.eu/crm/v7' for EU, 'https://www.zohoapis.in/crm/v7' for India. Under Authentication, select 'Custom Auth'. The Custom Auth system in Retool allows you to define a flow that fetches an access token using your refresh token and stores it for subsequent requests. In the Custom Auth configuration, add a step that makes a POST request to Zoho's token endpoint (accounts.zoho.com/oauth/v2/token) with grant_type=refresh_token, client_id, client_secret, and refresh_token from your configuration variables. Store the returned access_token in a variable. Set the Authorization header for the resource to 'Bearer {{ access_token }}'. Configure token refresh to run when a 401 response is received, or on a 3600-second (1 hour) interval since Zoho access tokens expire after 1 hour.

1// Resource Base URL: https://www.zohoapis.com/crm/v7
2
3// Custom Auth token refresh step:
4// POST https://accounts.zoho.com/oauth/v2/token
5// Body (form-encoded):
6// grant_type=refresh_token
7// client_id={{ retoolContext.configVars.ZOHO_CLIENT_ID }}
8// client_secret={{ retoolContext.configVars.ZOHO_CLIENT_SECRET }}
9// refresh_token={{ retoolContext.configVars.ZOHO_REFRESH_TOKEN }}
10
11// Store response.access_token as {{ zoho_access_token }}
12// Use in Authorization header: Bearer {{ zoho_access_token }}

Zoho CRM's COQL endpoint allows SQL-like queries across all CRM modules. Create a new query using the Zoho CRM resource with HTTP method POST and path '/coql'. The request body is a JSON object with a single 'select_query' field containing your COQL statement. COQL syntax mirrors SQL: SELECT field1, field2 FROM ModuleName WHERE condition ORDER BY field LIMIT n OFFSET m. Module names in Zoho CRM are plural (Leads, Contacts, Deals, Accounts, Tasks) but in COQL they are singular (Lead, Contact, Deal, Account). The WHERE clause supports comparison operators, IN lists, LIKE for text search, and BETWEEN for date ranges. Bind the WHERE clause conditions to Retool component values for dynamic filtering. The COQL response wraps results in a 'data' array with a 'info' object containing pagination details.

1// POST /coql
2// Request body:
3{
4  "select_query": "SELECT id, Last_Name, First_Name, Email, Lead_Status, Lead_Source, Annual_Revenue, Owner.name FROM Lead WHERE Lead_Status = '{{ statusFilter.value || 'New' }}' AND Created_Time >= '{{ dateRange.start || '2024-01-01T00:00:00+00:00' }}' ORDER BY Created_Time DESC LIMIT {{ pagination.pageSize || 50 }} OFFSET {{ (pagination.page - 1) * (pagination.pageSize || 50) || 0 }}"
5}

Add a transformer to the COQL query to normalize the Zoho response format. The COQL response nests results in data.data and includes owner information as a nested object. Flatten the owner name into a top-level field and format dates for display. Bind the transformer output to a Table component. For the dashboard layout, add a row of Select components for status and source filters, a DateRangePicker for date filtering, and a TextInput for name search. Wire each filter component's onChange event to trigger the COQL query. Add a Chart component showing lead distribution by status using a JavaScript query that aggregates the COQL data. Include a numeric stats row at the top showing total leads, new leads today, and conversion rate metrics.

1// Transformer: normalize Zoho COQL response
2const records = data.data || [];
3
4return records.map(record => ({
5  id: record.id,
6  name: `${record.First_Name || ''} ${record.Last_Name || ''}`.trim(),
7  email: record.Email || '',
8  status: record.Lead_Status || 'Unknown',
9  source: record.Lead_Source || 'Unknown',
10  owner: record.Owner?.name || 'Unassigned',
11  revenue: record.Annual_Revenue
12    ? `$${Number(record.Annual_Revenue).toLocaleString()}`
13    : 'N/A',
14  created: record.Created_Time
15    ? new Date(record.Created_Time).toLocaleDateString()
16    : 'N/A'
17}));

Create a write-back query to update CRM records. Use PUT method with path '/{{ module }}/{{ table1.selectedRow.id }}' where module is the CRM module name (Leads, Contacts, Deals). The request body is a JSON object with a 'data' array containing a single record object with the fields to update — only include fields you want to change, not the entire record. Create a Form component in Retool for the update panel with fields for status, owner, and notes. Wire the form's submit button to run the PUT query. For adding activity notes, create a separate POST query to '/Activities' with the note text, date, and related record ID. Add a confirmation modal before submitting to prevent accidental updates. For complex multi-module workflows and CRM automation, RapidDev's team can help build sophisticated Retool applications that integrate Zoho CRM with your other business tools.

1// PUT /Leads/{{ table1.selectedRow.id }}
2// Request body:
3{
4  "data": [
5    {
6      "Lead_Status": "{{ statusSelect.value }}",
7      "Owner": {
8        "id": "{{ ownerSelect.value }}"
9      }
10    }
11  ]
12}
13
14// POST /Notes (create activity note)
15// Request body:
16{
17  "data": [
18    {
19      "Note_Title": "Retool Update",
20      "Note_Content": "{{ noteInput.value }}",
21      "Parent_Id": {
22        "id": "{{ table1.selectedRow.id }}",
23        "module": "Leads"
24      }
25    }
26  ]
27}