The docs are not very clear on this process. So, I'll simplify this. The biggest hurdle are the steps to get the refresh token. Once you have that, you can generate countless access tokens that are used to make the actual API calls.
How To Get Your Refresh Token
- Login to your Zoho CRM with an admin-level account and have that open in a tab. Then, in another browser tab, login into the Developer API Console: https://api-console.zoho.com/
- In the Developer API Console, you need to create a Server-Side Client. The fields should be populated like so: Client Name (any logical name you want), Homepage URL (the homepage of the domain where you're going to be making the API calls, or just use the same URL for where you're doing the redirects), Authorized Redirect URIs (put a web page up on the domain where you're going to make the API call and make it emit nothing more than "zoho confirmed"). (The "zoho confirmed" is not required and not mentioned in the docs, but does help you understand the process better.) Click Create.
- Once created, click on it again and there's a tab called Client Secret. Click it and record in a notepad your Client ID and Client Secret.
- Take a URL encoder script online (or use PHP or any other tool) and URL encode the following parameters for a new URL you need to compose and load in your browser in the next step:
scope: ZohoCRM.modules.ALL,ZohoCRM.settings.ALL,ZohoCRM.users.ALL,ZohoCRM.org.ALL,aaaserver.profile.ALL,ZohoCRM.settings.functions.all,ZohoCRM.notifications.all,ZohoCRM.coql.read,ZohoCRM.files.create,ZohoCRM.bulk.all
response_type: code
access_type: offline
client_id: {use the Client ID you recorded in step 3}
redirect_uri: {use the Authorized Redirect URI you generated in step 2}
- With those URL encoded parameters, pass them to the end of this URL in your browser:
https://accounts.zoho.com/oauth/v2/auth? Thus, you would have something similar to:
https://accounts.zoho.com/oauth/v2/auth?scope=ZohoCRM.modules.ALL%2CZohoCRM.settings.ALL%2CZohoCRM.users.ALL%2CZohoCRM.org.ALL%2Caaaserver.profile.ALL%2CZohoCRM.settings.functions.all%2CZohoCRM.notifications.all%2CZohoCRM.coql.read%2CZohoCRM.files.create%2CZohoCRM.bulk.all&client_id=1000.TTT0BSTTTC9TTTRILR3MGXBYAC82LH&response_type=code&access_type=offline&redirect_uri=https%3A%2F%2Fexample.com%3Azohoconfirm
Please note that if your redirect URI (like https://example.com/zohoconfirm, above) does another redirection with like a 301 or 302 redirect and doesn't also forward those query parameters, then you'll lose the parameters you need to see when finished.
Once you load that in your browser, you will see an Accept button. If you do not, then you may have missed that in step 1 you were supposed to login to the CRM in one tab, and then open a new tab to do other tasks. That makes a session open for you and it knows who you are when doing step 5.
After you click the Accept button, Zoho's account system will redirect you to your Authorized Redirect URI that you specified. So, if you followed these steps exactly, you should see some output like "zoho confirmed". But do not close the tab. Look at the URL of the tab and cut/paste it into your notepad. In there, grab that code parameter.
Now that you have that code parameter, you need to create a special Curl POST request. You can do this either via command line or with your favorite programming language. From command line on Linux, this would look something like the following:
curl "https://accounts.zoho.com/oauth/v2/token"
-X POST
-d "grant_type=authorization_code&code=1000.aaa1f9aa8582eaaaafeaddfaf0f3b6b.bf7fe646ba899783501c21a9a3240aaa&client_id=1000.AAAA0BSIC7C9AAAARILR3MGXBYAC8AAA&client_secret=aaa9aa9166055932ff8c0279c6253a65cb534daaaa&redirect_uri=https%3A%2F%2Fexample.com%2Fzohoconfirm"
The URL-encoded parameters you need to fill out are:
grant_type: authorization_code
code: {the code you recorded from step 7}
client_id: {the Client ID you recorded in step 3}
client_secret: {the Client Secret you recorded in step 3}
redirect_uri: {the Authorized Redirect URI you recorded in step 2}
- Once you run that Curl command, it will return some JSON that looks similar to the following:
{"access_token":"1000.aaaa5579abeea73871b096c941ec1df8.7835dbb43bbf5122f2d5810f0b65aaa","refresh_token":"1000.aaaa2683a1723d1aeb7b58899849aaaa.aaaa4c22481da67e85e598f4b988aaa","api_domain":"https://www.zohoapis.com","token_type":"Bearer","expires_in":3600}
- Now, in the JSON output, you could use that access_token to make an API call to generate the lead, but you're better off just taking that refresh_token and putting that in a configuration file for later use in your programming. According to their documentation, their refresh_token lasts forever. You should keep this in an extremely secure place.
How To Get Your Access Token
- Now that you get your refresh_token, you use it to generate a fresh access_token each time you need to make an API call. To do that, make another Curl POST with a URL similar to below. In Linux command line with Curl, as an example, here's what it would look like:
curl "https://accounts.zoho.com/oauth/v2/token"
-X POST
-d "grant_type=refresh_token&refresh_token=1000.aaaa2683a1723d1aeb7b58899849aaaa.aaaa4c22481da67e85e598f4b988aaa&client_id=1000.AAAA0BSIC7C9AAAARILR3MGXBYAC8AAA&client_secret=aaa9aa9166055932ff8c0279c6253a65cb534daaaa"
Here's an explanation of how to do the URL-encoded parameters:
grant_type: refresh_token
refresh_token: {use the refresh_token (the one I said that would last forever) from your stored config file from step 10 in the previous steps}
client_id: {use your client_id}
client_secret: {use your client_secret}
- Running the above command should return to you some JSON that looks similar to:
{"access_token":"1000.aaa1c95788b34226c2844a841bfd1d5.6aff70f4adbc3fee9e6b57579e481aaa","api_domain":"https://www.zohoapis.com","token_type":"Bearer","expires_in":3600}
- In your favorite programming language, you'll be storing that access_token you received in a temporary variable so that you can make an API call to do something like add a Zoho CRM Lead. That access token will last 3600 seconds (1 hour), but really is of no consequence because you can generate infinite access tokens since you have that refresh_token stored in a configuration file.
How To Create A Zoho CRM Lead
- In your favorite programming language, you'll be using that refresh token to create an access token, and then using it for the following header to pass in your API call:
Authorization: Zoho-oauthtoken XXXXXX
...where XXXXXX is the access_token you received from the previous set of instructions.
- Here's a sample in PHP with file_get_contents (although you can do the same with PHP's Curl) to make a request to add a Zoho CRM Lead. You can take the following example and recode it in your favorite programming language. Change the $sAccessToken value to the one you generated.
Note, below, we're also writing into a field called "Lead Source", and it's API-accessible name is "Lead_Source". (If you end up changing the code below to write into Contacts or Accounts, then you'll want to create a custom field, I'm sure, to indicate where the contact or account came from. For instance, if you have a shopping cart, then you could indicate the record came from completing that transaction, rather than a customer calling in.)
<?php
error_reporting(E_ALL);
ini_set('display_errors','On');
header('Content-Type: text/plain');
$sAccessToken = '1000.aaaa5579abeea73871b096c941ec1df8.7835daaa3bbf5122f2d5810f0b65aaaa'; // change me
$sJSON = json_encode(array(
'First_Name' => 'Mickey',
'Last_Name' => 'Mouse',
'Email' => 'mickey@example.com',
'Phone' => '444-444-4444',
'Lead_Source' => 'TEST1'
));
$sJSON = str_replace('{','[{',$sJSON);
$sJSON = str_replace('}','}]',$sJSON);
$sJSON = '{"data":' . $sJSON . '}';
echo "SENDING: $sJSON
";
$sURL = 'https://www.zohoapis.com/crm/v2/Leads';
$sResponse = @ file_get_contents($sURL,false,stream_context_create(array('http'=>array(
'ignore_errors' => TRUE, // critical if you want to see errors in response instead of empty on error
'method' => 'POST',
'header' => array(
'Content-Type: application/json',
"Authorization: Zoho-oauthtoken $sAccessToken",
'cache-control: no-cache'
),
'content' => $sJSON
))));
echo "$sResponse
";
If successful, this will generate a response similar to below:
{"data":[{"code":"SUCCESS","details":{"Modified_Time":"2020-05-21T20:45:24-04:00","Modified_By":{"name":"John Manager","id":"9999889000000279991"},"Created_Time":"2020-05-21T20:45:24-04:00","id":"9999889000000279991","Created_By":{"name":"John Manager","id":"9999889000000279991"}},"message":"record added","status":"success"}]}
...where John Manager would be the name of the admin-level user account you logged into the CRM with.
More information about the Zoho CRM Insert Record API can be found here: https://www.zoho.com/crm/developer/docs/api/insert-records.html
To understand where to find the API-addressable field names, in your CRM, go to: Setup > Developer Space > APIs > API Names > Leads. Choose "Fields" from the "Filter By" drop-down.
Note that this API does not look for duplicates. You can adapt the above to do an "upsert" instead of an "insert": https://www.zoho.com/crm/developer/docs/api/upsert-records.html
If you edit the Contacts and Accounts to have the same custom fields as Leads, then you can change the https://www.zohoapis.com/crm/v2/Leads line to https://www.zohoapis.com/crm/v2/Contacts or https://www.zohoapis.com/crm/v2/Accounts and write entries into those as well.
