Zoho CRM

Open api-console.zoho.com in your browser and sign in with your Zoho account. Click 'Add Client' and select 'Self Client' from the application type options — this type is specifically designed for server-to-server integrations without a redirect URI, which is exactly what Bubble needs. Give your client a name like 'Bubble Integration' and click 'Create Now.' You will immediately see your Client ID and Client Secret — copy both and store them securely. Next, generate a grant code. Click the 'Generate Code' tab. In the Scope field, enter the permissions your Bubble app needs. For standard CRM access use: `ZohoCRM.modules.ALL,ZohoCRM.settings.ALL,ZohoCRM.coql.READ`. Set the Time Duration to the maximum available (typically 10 minutes) and click 'Create.' Copy the generated grant code — it expires in the time you selected, so act quickly. Now exchange the grant code for a refresh token. Open your browser's address bar and construct this URL — do NOT use Bubble for this step, it must be done manually once: ``` https://accounts.zoho.com/oauth/v2/token?code=YOUR_GRANT_CODE&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&redirect_uri=https://www.zoho.com&grant_type=authorization_code ``` Replace the placeholders and paste this URL into your browser. You will receive a JSON response containing `refresh_token` — copy it. This refresh token does not expire unless unused for 60 days or manually revoked. Store it safely alongside your Client ID and Secret.

1// Required OAuth scopes for full CRM access:
2// ZohoCRM.modules.ALL    → read/write all CRM modules (Leads, Contacts, Deals, Accounts)
3// ZohoCRM.settings.ALL   → read CRM settings and field metadata
4// ZohoCRM.coql.READ      → run COQL queries via POST /coql endpoint
5
6// Token exchange URL (run ONCE in browser address bar):
7// https://accounts.zoho.com/oauth/v2/token
8//   ?code=<grant_code>
9//   &client_id=<client_id>
10//   &client_secret=<client_secret>
11//   &redirect_uri=https://www.zoho.com
12//   &grant_type=authorization_code
13
14// Response will contain:
15// { "access_token": "...", "refresh_token": "...", "token_type": "Bearer", "expires_in": 3600 }

Before configuring the API Connector, set up the data structure and Backend Workflow that will keep your access token fresh. In your Bubble editor, go to the Data tab and click 'Add a data type.' Name it `Zoho_Auth`. Add three fields: `access_token` (text), `expires_at` (date), and `region` (text). This data type will hold exactly one record — the current valid access token. Now apply a privacy rule. Click 'Privacy' in the Data tab, click the Zoho_Auth data type, and add a rule: 'Everyone else → no fields visible.' This prevents end users from reading your access tokens through Bubble's Data API. Check 'Ignore privacy rules when using workflows' so Backend Workflows can still read the token. Now go to Backend Workflows (left sidebar). Click 'Add workflow' and name it `Refresh Zoho Token`. Inside this workflow, add the following actions: 1. Add action: 'API Connector → Refresh Access Token' (you will create this call in the next step — for now, plan for it). The call POSTs to Zoho's token endpoint with your refresh token. 2. Add action: Search for Zoho_Auth first item. If found, update `access_token` to the result and `expires_at` to Current date/time + 3540 seconds (59 minutes — slightly under the 3600-second TTL for safety). If not found, create a new Zoho_Auth record with the same values. You will link step 1 of this workflow to the actual API Connector call in the next step.

1// Zoho_Auth data type:
2// access_token   → text
3// expires_at     → date
4// region         → text  (e.g., 'com', 'eu', 'in', 'com.au')
5
6// Privacy rule on Zoho_Auth:
7// Everyone else → no fields visible
8// ✓ Ignore privacy rules when using workflows
9
10// Backend Workflow: Refresh Zoho Token
11// Step 1: API Connector → Zoho → Refresh Access Token (POST)
12// Step 2: Search for Zoho_Auth's first item
13//   IF found: Make changes → access_token = Step1's access_token
14//                            expires_at = Current date/time + 3540 seconds
15//   IF not found: Create new Zoho_Auth
16//                   access_token = Step1's access_token
17//                   expires_at = Current date/time + 3540 seconds

In your Bubble editor, go to Plugins → API Connector. Click 'Add another API' and name it `Zoho CRM`. Set the base URL based on your data center: - US accounts: `https://www.zohoapis.com/crm/v7` - EU accounts: `https://www.zohoapis.eu/crm/v7` - India accounts: `https://www.zohoapis.in/crm/v7` - Australia accounts: `https://www.zohoapis.com.au/crm/v7` Add a shared header (applies to all calls in this group): Header name `Authorization`, value `Zoho-oauthtoken <access_token>`. IMPORTANT: the prefix is `Zoho-oauthtoken` with a space before the token — not `Bearer`. Mark this header as a dynamic parameter of type Private so your Backend Workflow can inject the current token at runtime. Now add two API Connector calls within this group: Call 1 — Refresh Access Token: Click 'Add another call.' Name it `Refresh Access Token`. Method: POST. URL: `https://accounts.zoho.com/oauth/v2/token` (use your region's account URL if outside US — e.g., accounts.zoho.eu/oauth/v2/token). In the Body section, add these parameters: `grant_type` = `refresh_token`, `client_id` = your Client ID (mark Private), `client_secret` = your Client Secret (mark Private), `refresh_token` = your refresh token (mark Private). Set 'Use as' to Action. Click Initialize call — it should return a JSON response with `access_token`. Call 2 — COQL Search: Click 'Add another call.' Name it `COQL Search`. Method: POST. URL: `/coql` (relative to base URL). JSON body: `{ "select_query": "<query>" }` where `<query>` is a dynamic parameter. Set 'Use as' to Data. Initialize call with a test query: `SELECT Id, First_Name, Last_Name, Email, Phone FROM Lead LIMIT 5`. Now go back to your Refresh Zoho Token Backend Workflow and wire step 1 to the 'Refresh Access Token' call you just created.

1// Zoho CRM API Connector — shared header configuration
2{
3  "base_url": "https://www.zohoapis.com/crm/v7",  // change .com to .eu / .in / .com.au for other regions
4  "shared_headers": {
5    "Authorization": "Zoho-oauthtoken <access_token>"  // mark as Private dynamic param
6  }
7}
8
9// Call 1: Refresh Access Token
10{
11  "method": "POST",
12  "url": "https://accounts.zoho.com/oauth/v2/token",
13  "body": {
14    "grant_type": "refresh_token",
15    "client_id": "<your_client_id>",       // mark Private
16    "client_secret": "<your_client_secret>", // mark Private
17    "refresh_token": "<your_refresh_token>" // mark Private
18  }
19}
20
21// Call 2: COQL Search
22{
23  "method": "POST",
24  "url": "https://www.zohoapis.com/crm/v7/coql",
25  "headers": { "Authorization": "Zoho-oauthtoken <access_token>" },
26  "body": {
27    "select_query": "<dynamic_coql_query>"
28  }
29}
30
31// Example COQL queries:
32// Leads owned by a specific user:
33// SELECT Id, First_Name, Last_Name, Email, Stage FROM Lead WHERE Owner = 'user@example.com' LIMIT 20
34//
35// Open deals by closing date:
36// SELECT Id, Deal_Name, Amount, Stage, Closing_Date FROM Deal WHERE Stage != 'Closed Won' ORDER BY Closing_Date ASC LIMIT 10

Zoho CRM's write operations (create and update) require wrapping all record data inside a `data` array — flat JSON returns a 400 error. In the API Connector, within your Zoho CRM group, add two more calls: Call 3 — Create Lead: Method POST, URL `/Leads`. JSON body: ```json { "data": [ { "First_Name": "<first_name>", "Last_Name": "<last_name>", "Email": "<email>", "Phone": "<phone>", "Lead_Source": "<lead_source>" } ] } ``` Mark each `<dynamic>` field as a parameter that can be passed from the Bubble workflow. Set 'Use as' to Action. Call 4 — Update Deal Stage: Method PUT, URL `/Deals/<deal_id>` (mark `deal_id` as a dynamic parameter). JSON body: ```json { "data": [ { "Stage": "<stage>" } ] } ``` Now build the frontend workflows. When a user submits a form, trigger a Backend Workflow that: 1. Checks if Zoho_Auth's first item's expires_at is before Current date/time (or if no record exists) 2. If stale/missing: calls the Refresh Zoho Token workflow 3. Then calls the Create Lead action with the current access_token from Zoho_Auth and the form field values For the COQL search, bind a Repeating Group's data source to 'Get data from an external API → Zoho CRM → COQL Search' and pass the query string as a parameter built from page inputs. Always inject the current access_token from Zoho_Auth into the Authorization header parameter before the call.

1// Call 3: Create Lead
2{
3  "method": "POST",
4  "url": "https://www.zohoapis.com/crm/v7/Leads",
5  "headers": {
6    "Authorization": "Zoho-oauthtoken <access_token>",  // Private
7    "Content-Type": "application/json"
8  },
9  "body": {
10    "data": [
11      {
12        "First_Name": "<first_name>",
13        "Last_Name": "<last_name>",
14        "Email": "<email>",
15        "Phone": "<phone>",
16        "Lead_Source": "<lead_source>"
17      }
18    ]
19  }
20}
21
22// Call 4: Update Deal Stage
23{
24  "method": "PUT",
25  "url": "https://www.zohoapis.com/crm/v7/Deals/<deal_id>",
26  "headers": {
27    "Authorization": "Zoho-oauthtoken <access_token>",  // Private
28    "Content-Type": "application/json"
29  },
30  "body": {
31    "data": [
32      {
33        "Stage": "<stage>"
34      }
35    ]
36  }
37}

The final piece is wiring token refresh logic into every workflow that calls Zoho CRM. Bubble does not automatically retry failed calls — you need an explicit check before each API action. In any workflow that makes a Zoho CRM call: 1. Add a first action with a condition: 'Only when Zoho_Auth's count = 0 OR Zoho_Auth's first item's expires_at < Current date/time.' 2. Inside that condition: add action 'Schedule API Workflow → Refresh Zoho Token' and set it to run at Current date/time (immediate). 3. Then add the actual Zoho API call, referencing `Do a search for Zoho_Auth's first item's access_token` in the Authorization header parameter. For displaying CRM data in a Repeating Group: set the data source to 'Get data from an external API,' select 'Zoho CRM - COQL Search,' and build the COQL query string dynamically from dropdown and text input values on the page. Bubble's text composition handles string building for COQL. For example: `'SELECT Id, First_Name, Last_Name, Email FROM Lead WHERE Stage = '' + Dropdown_Stage's value + '' LIMIT 20'`. For a richer search experience, add a search input and build a COQL WHERE clause: `Email LIKE '%' + SearchInput's value + '%' OR First_Name LIKE '%' + SearchInput's value + '%'`. COQL's LIKE operator uses `%` wildcards. RapidDev's team has built dozens of Bubble apps with Zoho CRM and similar CRM integrations — if you would like a free scoping call on your specific data model and workflow design, visit rapidevelopers.com/contact.

1// Token freshness check pattern (add before every Zoho API action):
2// Condition: Only when:
3//   (Do a search for Zoho_Auth:count is 0)
4//   OR (Do a search for Zoho_Auth's first item's expires_at < Current date/time)
5// Action inside condition: Schedule API Workflow → Refresh Zoho Token → at Current date/time
6
7// Then in the main API call action:
8// Authorization param = Do a search for Zoho_Auth's first item's access_token
9
10// COQL query for filtered lead search:
11// SELECT Id, First_Name, Last_Name, Email, Phone, Stage, Lead_Source
12// FROM Lead
13// WHERE Stage = '<selected_stage>'
14//   AND (First_Name LIKE '%<search_term>%' OR Last_Name LIKE '%<search_term>%')
15// ORDER BY Created_Time DESC
16// LIMIT 20