This guide walks you through connecting a custom app to Zoho CRM, enabling you to push or pull data between your app and your CRM. You’ll set up a Zoho client, authenticate with OAuth 2.0, and make your first API call. No coding experience is required, but you’ll need to follow the steps carefully.
What You’ll Need
- A Zoho CRM account (any edition, including the free trial).
- Access to the Zoho CRM Developer Console (you’ll be prompted to log in).
- A custom app you want to connect (could be a web app, mobile app, or script).
- Basic familiarity with HTTP requests and JSON (helpful, but not mandatory).
Step-by-Step
- Log into Zoho CRM and open the Developer Console. Go to your Zoho CRM home page, click the gear icon in the top-right, and select Developer Space → API. If you don’t see it, search for “API” in the settings.
- Create a self-client. In the API section, click Add Client and choose Self Client. This gives you a Client ID and Client Secret. (For production apps, you’d use “Web Client” or “Mobile Client,” but Self Client is the fastest for testing.)
- Copy your Client ID and Client Secret. Keep them in a safe place. You’ll need them to get an access token.
- Generate an OAuth token (grant token). In the same screen, click Generate Token. You’ll be asked to select scopes. For basic operations, check ZohoCRM.modules.ALL and ZohoCRM.users.ALL. Then click Create. A pop-up will ask you to log in and authorize; do so. You’ll receive a grant token (a long string).
- Exchange the grant token for an access token and refresh token. Use a REST API client (like Postman or cURL) to send a POST request to
https://accounts.zoho.com/oauth/v2/tokenwith the following parameters (as form-data):grant_type=authorization_codeclient_id= your Client IDclient_secret= your Client Secretredirect_uri=https://www.zoho.com/crm/(or whatever you set in the client creation step)code= the grant token from step 4
The response will contain an
access_token(valid for 1 hour) and arefresh_token(valid for longer). Save both. - Make your first API call. To test the connection, send a GET request to
https://www.zohoapis.com/crm/v6/Leadswith the headerAuthorization: Zoho-oauthtoken YOUR_ACCESS_TOKEN. If you get a JSON response with adataarray (even if empty), you’re connected. - Use the refresh token to get new access tokens. Since access tokens expire, your app should automatically request a new one using the refresh token. Send a POST request to the same token endpoint with
grant_type=refresh_token,client_id,client_secret, andrefresh_token. The response will give you a new access token. - Integrate into your custom app. Store the Client ID, Client Secret, and Refresh Token in your app’s configuration (preferably as environment variables). Write a function that calls the refresh token endpoint to get a fresh access token, then use that token for API calls.
Common Mistakes
- Using the wrong redirect URI. The redirect URI must exactly match what you set when creating the client. A common error is adding a trailing slash or using HTTP instead of HTTPS.
- Not including the full scope. If you only request
ZohoCRM.modules.ALLbut later try to access users, you’ll get a 401 error. Always request the scopes you need. - Hardcoding the access token. Access tokens expire after 60 minutes. If you hardcode it, your app will break. Always use the refresh token to get a new one.
- Ignoring the token endpoint region. Zoho has different data centers (US, EU, IN, etc.). If your account is in the EU, use
https://accounts.zoho.euinstead ofhttps://accounts.zoho.com. The API endpoint also changes (e.g.,https://www.zohoapis.eu/crm/v6/). - Not checking the response for errors. Always inspect the HTTP status code and the JSON body. Zoho returns error codes like 401 (unauthorized) or 429 (rate limit).
Tips
- Start with a small test. Before building a full integration, test with a single API call (like fetching a list of Leads) to confirm your tokens work.
- Use a library. If you’re using a language like Python, Java, or PHP, use Zoho’s official SDKs or community libraries to handle OAuth and API calls. They manage token refresh automatically.
- Store tokens securely. Never expose your Client Secret or Refresh Token in client-side code. Use environment variables or a secure vault.
- Handle rate limits. Zoho CRM has API limits (e.g., 250 requests per minute for most plans). Implement exponential backoff if you get a 429 error.
- Use webhooks for real-time updates. Instead of polling, set up webhooks to receive notifications when records change.
Troubleshooting
401 Unauthorized: Your access token is invalid or expired. Refresh it using the refresh token. If that fails, regenerate the grant token and repeat the token exchange.
Invalid grant token: The grant token is single-use and expires in a few minutes. If you get this error, go back to the Developer Console and generate a new one.
Redirect URI mismatch: Check that the redirect URI in your token request exactly matches the one in your client settings. Copy-paste it to avoid typos.
“Invalid Client” error: Your Client ID or Client Secret is incorrect. Double-check you copied them correctly, and ensure you’re using the right credentials for the same client.
API endpoint not found: Make sure you’re using the correct data center URL. If your Zoho account is in the EU, use zohoapis.eu. You can verify your data center by checking the URL when you log into Zoho (e.g., crm.zoho.eu).
Rate limit exceeded: Wait a minute and try again. If you’re consistently hitting limits, consider batching requests or upgrading your plan.
Frequently Asked Questions
Q: Can I use a custom app without OAuth?
A: No. Zoho CRM requires OAuth 2.0 for API access. There’s no API key option.
Q: How long does the refresh token last?
A: Refresh tokens for self-clients typically last 1 year. For production clients, they may be shorter. You’ll need to re-authorize when it expires.
Q: Can I connect multiple custom apps?
A: Yes, each app should have its own client ID and secret. You can create multiple clients in the Developer Console.
Q: Do I need to pay for API access?
A: No, API access is included in all Zoho CRM editions. However, there are rate limits based on your plan.
Q: What if I only want to read data, not write?
A: You can restrict scopes to read-only (e.g., ZohoCRM.modules.READ). This is a good security practice.
Q: Can I use the same access token for multiple users?
A: No, tokens are tied to the user who authorized. If you need to act on behalf of other users, use the “ZohoCRM.users.ALL” scope and impersonate users via the X-CRM-ORG header (advanced).
Related
General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.
More in this bed
- How to Enable Privacy Indicators on Chromebook
- How to Calculate Taxes on Overtime Pay
- VPN Not Working on iPhone? Fixes That Actually Work
- Hide & Unhide Apps on Samsung Phones
- Fix DNS Server Unavailable Error in Windows 11
- Fix iOS 17 Keyboard Not Working Properly