How do I add a Zoho CRM Lead with the Zoho CRM v2 API, using simple curl connections? The docs are not very clear on not only how to add a lead, but how to even get the proper oAuth token to create the lead.
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.
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}
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}
{"access_token":"1000.aaaa5579abeea73871b096c941ec1df8.7835dbb43bbf5122f2d5810f0b65aaa","refresh_token":"1000.aaaa2683a1723d1aeb7b58899849aaaa.aaaa4c22481da67e85e598f4b988aaa","api_domain":"https://www.zohoapis.com","token_type":"Bearer","expires_in":3600}
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}
{"access_token":"1000.aaa1c95788b34226c2844a841bfd1d5.6aff70f4adbc3fee9e6b57579e481aaa","api_domain":"https://www.zohoapis.com","token_type":"Bearer","expires_in":3600}
Authorization: Zoho-oauthtoken XXXXXX
...where XXXXXX is the access_token you received from the previous set of instructions.
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\n";
$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\n";
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.