REST API Documentation

  • Introduction
  • OAuth2.0 & Introduction
  • OAuth Requests & Step 1: Register your application
  • Step 2: Authorization Request
  • Step 3: Generate Access Token and Refresh Token
  • Step 4: Refresh Access Tokens
  • Step 5: Revoking Tokens
  • Multi DC
  • API Limits
  • API Dashboards
  • HTTP Status Codes
  • HTTP Methods
  • Modules APIs & Get list of modules
  • Users APIs & Get users
  • Get single user data
  • Roles APIs & Get roles
  • Get single role data
  • Profiles APIs & Get profiles
  • Get single profile data
  • Layouts
  • Single Layout
  • Custom Views
  • Single Custom View
  • Organization API & Organization Data
  • Upload Organization photo
  • Subscription APIs & Subscribe for notifications
  • Get subscription details
  • Update subscription details
  • Update Specific information of a Notification
  • Unsubscribe to notifications
  • Unsubscribe to specific notifications
  • Bulk Record APIs & Get list of records
  • Insert records
  • Update records
  • Insert or Update (upsert)
  • Delete records
  • Get list of deleted records
  • Search records
  • Single Record APIs & Get a specific record
  • Insert a specific record
  • Update a specific record
  • Delete a specific record
  • Convert Lead
  • Subform APIs
  • Bulk Read APIs & Create Bulk Read Job
  • Get Bulk Read Job details
  • Download Bulk Read Job result
  • Tag APIs & Get Tags
  • Get record counts for a specific tag
  • Create new tags
  • Merge tags
  • Single tag update
  • Multiple tag updates
  • Delete a tag
  • Add tags to a single record
  • Add tags to multiple records
  • Remove tags from a single record
  • Remove tags from multiple records
  • Notes APIs & Get notes
  • Get specific notes data
  • Create notes
  • Create specific notes
  • Update notes
  • Delete specific notes
  • Delete notes
  • Files and Attachments APIs & Get list of attachments
  • Upload an attachment
  • Download an attachment
  • Delete an attachment
  • Upload a photo
  • Download a photo
  • Delete a photo
+
  • Introduction
    • OAuth2.0
      • Introduction
        • OAuth Requests
          • Step 1: Register your application
          • Step 2: Authorization Request
          • Step 3: Generate Access Token and Refresh Token
          • Step 4: Refresh Access Tokens
          • Step 5: Revoking Tokens
      • Multi DC
  • API Limits
  • GDPR Compliance
  • API Dashboards
  • HTTP Status Codes
  • HTTP Methods
    • Subscription APIs
      • Subscribe for Notifications
      • Get Subscription Details
      • Update Subscription Details of a Notification
      • Update Specific information of a Notification
      • Unsubscribe to Notifications
      • Unsubscribe to Specific Notifications
    • Bulk Read APIs
      • Overview
      • Create a Bulk Read (Export) Job
      • Get Bulk Read Job Details
      • Download Bulk Read Result
      • Limitations
  • Modules APIs
    • Users APIs
      • Get Users
      • Get single user data
    • Roles APIs
      • Get Roles
      • Get single role data
    • Profiles APIs
      • Get Profiles
      • Get single profile data
      • Module Meta Data
      • Layouts
      • Single Layout
      • Custom Views
      • Single Custom View
    • Variables APIs
      • Get Variables
      • Get Single Variable Data
      • Get Variable Groups
      • Create Variables
      • Update Variables
      • Update Specific Variables
      • Delete Variables
      • Delete Multiple Variables
    • Organization APIs
      • Get Organization data
      • Upload Organization photo
    • Record APIs
        • Bulk Records APIs
          • Get list of records
          • Insert records
          • Update records
          • Insert or Update (upsert)
          • Delete records
          • Get list of deleted records
          • Search records
        • Single Record APIs
          • Get a specific record
          • Insert a specific record
          • Update a specific record
          • Delete a specific record
          • Convert Lead
      • Subform APIs
    • Blueprint APIs
      • Get Blueprint details
      • Update Blueprint record details
    • Tag APIs
      • Get Tags
      • Get record count for a specific tag
      • Create New Tags
      • Merge Tags
      • Single Tag Update
      • Multiple Tag Update
      • Delete a Tag
      • Add Tags to a Specific record
      • Add Tags to Multiple records
      • Remove Tags from a Specific record
      • Remove Tags from Multiple record
      • Get related records
    • Notes APIs
      • Get notes
      • Get specific notes data
      • Create notes
      • Create specific notes
      • Update notes
      • Delete specific notes
      • Delete notes
    • Files and Attachments APIs
      • Get list of attachments
      • Upload an attachment
      • Download an attachment
      • Delete an attachment
      • Upload a photo
      • Download a photo
      • Delete a photo

Introduction

Zoho CRM provides REST API (Application Programming Interface) that lets you integrate CRM with third-party applications such as, accounting, ERP, ecommerce, self-service portals and others.

The REST API uses simple HTTP methods, such as GET, POST, PUT and DELETE. These methods allow CRM data to be extracted in JSON format including errors, making it easy to develop new applications and also to integrate with existing business applications.

Note:

All requests to the API should be made over HTTPS. The API requests and responses are formatted in JSON.

Software Development Kits (SDKs)

SDKs for Zoho CRM APIs provides wrapper for Zoho CRM APIs. Hence invoking a Zoho CRM API from your client application is just a method call.

OAuth2.0

Introduction

The Zoho CRM API is authenticated using OAuth2.0 protocol. This allows you to share specific data with any application while keeping your usernames and passwords private. This protocol provides users with a secure and easy way to use authentication.

Why use OAuth2.0?

  • You can revoke a customer's access to the application any time.
  • No need for disclosing credentials to clients.
  • No information will be revealed even if the client is hacked, since access tokens are issued to individual applications and not the client as a whole.
  • Specific scopes can be applied to either restrict or provide access to certain data for the client. It would be different for each client application.

How OAuth2.0 works?


There are different type of tokens defined by OAuth2.0, which are used to serve different purposes in the authentication process. Please take a look at the following terms and the differences between each of them.

Protected resources

The Zoho CRM resources, such as Leads, Contacts, Deals, etc.

Resource server

The Zoho CRM server that hosts the protected resources.

Resource owner

Any end user of your account, who can grant access to the protected resources.

Client

An application that sends requests to the resource server to access the protected resources on behalf of the end user.

Authentication server

Authorization server provides the necessary credentials (such as Access and Refresh tokens) to the client. In this case, it will be the Zoho CRM authorization server.

Authentication code

A temporary token created by the authorization server and sent to the client via the browser. The client will send this code to the authorization server in order to obtain an access and refresh tokens.

Access Token

A token that is sent to the resource server to access the protected resources of the user. The Access token provides a secure and temporary access to Zoho CRM APIs and is used by the applications to make requests to the connected app. Each access token will be valid only for an hour, and can be used only for the set of operations that is described in the scope.

Refresh Token

A token that can be used to obtain new access tokens. This token has an unlimited lifetime until it is revoked by the end user.

Scope

While accessing each endpoint, you need to authenticate your application using an appropriate key and scope. The Zoho CRM API uses selected scopes, which control the type of resource that can be accessed by the client application. Tokens are usually created with various scopes to ensure improved security. For example, you can generate a scope to create or view a lead, or to view metadata and so on.

Available Scopes

Scope Name Associated Methods
users users.all
org org.all
settings settings.all, settings.territories, settings.custom_views, settings.related_lists, settings.modules, settings.tab_groups, settings.fields, settings.layouts, settings.macros, settings.custom_links, settings.custom_buttons, settings.roles, and settings.profiles
modules modules.all, modules.approvals, modules.leads, modules.accounts, modules.contacts, modules.deals, modules.campaigns, modules.tasks, modules.cases, modules.events, modules.calls, modules.solutions, modules.products, modules.vendors, modules.pricebooks, modules.quotes, modules.salesorders, modules.purchaseorders, modules.invoices, modules.custom, modules.dashboards, modules.notes, modules.activities, modules.search

Scopes contain three parameters which are important. They are the service name, scope name and the operation type.

For instance,

https://accounts.zoho.com/oauth/v2/auth?scope=ZohoCRM.modules.ALL

In the above example, the service name of the API is "ZohoCRM". The scope name is "modules", which represents all of the modules of your Zoho CRM account. And the operation type is "ALL", which represents that you have full access to the modules.

The operation type can be ALL, READ, CREATE, DELETE or UPDATE.

Group Scopes

Group scopes are ones which provide complete access to all functions that can be performed on the record. For instance, group scopes allows a user to read, create, update and delete records of all modules whereas separate scopes allow access to only one or some modules based on the requirement.

For instance,

https://accounts.zoho.com/oauth/v2/auth?scope=ZohoCRM.modules.ALL,ZohoCRM.settings.ALL&
client_id={client_id}&response_type=code&
access_type={"offline"or"online"}&redirect_uri={redirect_uri}

The above scope gives the user access to all the modules available in the client ZohoCRM account.

You can also restrict certain permissions such as making the information read-only, by setting up specific scopes.

Some examples would be:

  • scope=ZohoCRM.modules.READ
  • scope=ZohoCRM.modules.CREATE
  • scope=ZohoCRM.modules.UPDATE
  • scope=ZohoCRM.modules.DELETE

Separate Scopes

Separate scopes are used to provide access to data in a particular module without access to other modules.

For instance,

https://accounts.zoho.com/oauth/v2/auth?scope=ZohoCRM.modules.leads.ALL,ZohoCRM.modules.deals.ALL,ZohoCRM.settings.ALL&
client_id={client_id}&response_type=code&
access_type={"offline"or"online"}&redirect_uri={redirect_uri}

The above scope gives the user access to only the leads and deals modules from the client ZohoCRM account.

Additionally, you can set specific permissions, like read, create, update or delete, for each module. For examples:

  • scope=ZohoCRM.modules.leads.READ
  • scope=ZohoCRM.modules.leads.CREATE
  • scope=ZohoCRM.modules.leads.UPDATE
  • scope=ZohoCRM.modules.leads.DELETE

Important

User Access Token must be kept confidential, since it defines the type of API that you use. Do NOT expose your Access Token anywhere in public forums, public repositories or on your website's client side code like HTML or JavaScript. Exposing it to public may lead to data theft, loss or corruption.

OAuth Requests

Step 1: Register your application

Before you get started with authorization and make any calls to the Zoho CRM API, you need to register your application with Zoho CRM API.

To register:

  • Go to the site: accounts.zoho.com/developerconsole
  • Click Add Client ID.
  • Enter the Client name, domain and redirect URL.
  • Click Create.
  • Note down your client ID.

Registered applications will receive the following credentials:

Client id – The consumer key generated from the connected app.

Client Secret – The consumer secret generated from the connected app.

Redirect URI – The Callback URL that you registered during the app registration.

Self-Client:

In case the user does not have a domain and a redirect URL, the self-client option can be used to get access token.

Step 1:

Step 2:

Clicking View Code will provide the user with a Grant token. Use the grant token to generate access and refresh token as mentioned in Step 3.

Step 2: Authorization Request

To authenticate your application, you need to redirect the user of the client application to the suitable authorization endpoint. On successful login, Zoho CRM will call your redirect URI along with an authorization code.

Now authorize yourself using the following parameters:

Parameter Description
scope Specifies what data can be accessed by your application. Refer “Scope” for more info.
client_id Specify the consumer key generated from the connected app.
redirect_uri Specify the Callback URL that you registered during the app registration.
response_type Specify response_type as code.
access_type Specify access_type as online or offline. If you want to generate the refresh token, please set the value as "offline".

To authorize your app:

  • Once you have your client ID, enter the Authorization URL in the browser, which would be like this:

    https://accounts.zoho.com/oauth/v2/auth?scope=ZohoCRM.users.ALL&client_id={client_id}
    &response_type=code&access_type={"offline"or"online"}&redirect_uri={redirect_uri}

  • In the resultant page, click Accept.
  • You will get redirected to the "redirect_uri" that you specified during registration of the app. The URL of that page would be like this:

    {redirect_uri}?code={grant_token}&location=us&accounts-server=https%3A%2F%2Faccounts.zoho.com

  • You will get redirected to the "redirect_uri" that you specified during registration of the app.
  • Note down the "code={grant_token}" parameter.
    This is a short-lived token (valid only for a minute) and will be used to generate the access token and refresh token.

Note:

The above authorization URL has the scope for the Users. You can change the scope as per your requirement.

Step 3: Generate Access Token and Refresh Token

OAuth2.0 requests are usually authenticated with an access token, which is passed as bearer token. To use this access token, you need to construct a normal HTTP request and include it in an Authorization header along with the value of Bearer.

The following parameters are required to generate the access token and refresh token:

Parameter Description
grant_type Enter the value as "authorization_code".
client_id Specify client-id obtained from the connected app.
client_secret Specify client-secret obtained from the connected app.
redirect_uri Specify the Callback URL that you registered during the app registration.
code Enter the grant token generated from previous step.

To generate access and refresh token:

  • Make a POST request with the following URL:

    https://accounts.zoho.com/oauth/v2/token?code={grant_token}&redirect_uri={redirect_uri}&client_id={client_id}&client_secret={client_secret}&grant_type=authorization_code

  • If the request is successful, you would receive the following:

    {
    "access_token": "{access_token}",
    "refresh_token": "{refresh_token}",
    "expires_in_sec": 3600,
    "api_domain": "https://www.zohoapis.com",
    "token_type": "Bearer",
    "expires_in": 3600000
    }

This completes the authentication. Once your app receives the access token, send the token in your HTTP authorization header to Zoho CRM API with the value "Zoho-oauthtoken {access_token}" for each endpoint (for each request). Please note that your "access_token" will be expired in an hour.

Step 4: Refresh Access Tokens

As obvious as it is, refresh tokens are used to generate new access tokens when the current ones are past the expiry time.

  • Make a POST request with the following URL:

    https://accounts.zoho.com/oauth/v2/token?refresh_token={refresh_token}&client_id={client_id}&client_secret={client_secret}&grant_type=refresh_token

  • If the request is successful, you will receive the following output

    {
    "access_token": "{new_access_token}",
    "expires_in_sec": 3600,
    "api_domain": "https://www.zohoapis.com",
    "token_type": "Bearer",
    "expires_in": 3600000
    }

Note:

  • A "User" in an organization can have a maximum of 20 refresh tokens. And each refresh token can have a maximum of 30 active access tokens (non expired).
  • When a user creates a 31st access token, the 1st created token will be deleted and the 31st will be created. However, when he creates a 21st refresh token, an error will be thrown.
  • We have provided with a sample test OAuth in all the examples, so that you can test any example on your own. You can replace the sample OAuth Token with your actual token to test requests from your CRM account.

Step 5: Revoking Tokens

In case if you wish to revoke the refresh_token, use the below approach.

  • Use the "POST" HTTP method and construct the following URL to revoke the refresh_token.

https://accounts.zoho.com/oauth/v2/token/revoke?token={refresh_token}

Multi DC

For an API to work under a heavy load, it is essential to have multiple data centres. Because not only does the load balance between data centres are maintained, but also it provides a better platform for analytics. What is Analytics? It is the accumulation of data and traffic which can be used for monitoring, analysis and reports and documentation.

Hence, there is a need for clear distinction between API calls by specifying the domain names. As a result, the availability and usage of data centres are determined by the location specified and this further helps to share and reduce the load on each data centre. The supported domains are:

  • United States - https://www.zohoapis.com/
  • Europe - https://www.zohoapis.eu/
  • China - http://www.zohoapis.com.cn/

In the second step of OAuth configuration, you would make a request using the authorisation URL which would be:

https://accounts.zoho.com/oauth/v2/auth?&scope=ZohoCRM.users.ALL&client_id={client_id}&response_type=code&access_type={"offline"or"online"}&redirect_uri={redirect_uri}

The response to the request would be:

{redirect_uri}?code={grant_token}&location=us&accounts-server=https%3A%2F%2Faccounts.zoho.com
Where redirect_uri would have to be specified by you in Step 1.

The most important part would be the section "location=us&accounts-server=https%3A%2F%2Faccounts.zoho.com” which represents the URL based on your location.

The request has to be made from “accounts.zoho.com” and once the request gets approved, it would be switched to other domains for ease of access.

API Limits

Zoho CRM uses a credit system to provide a rate limit to your application. Each API call made will result in reduction of 1 credit. However, for some APIs, the credit reduction would be different. For example, for a "Convert Lead API", 5 credits will be reduced for a single API call.

Credit system


API calls in Zoho CRM are associated with Credits. The credits are deducted from your Credit Count, based on the type of the API call that you make. The credit deduction is based upon the intensiveness of the performance, and the memory usage of the operations involved in the API calls. 


Maximum credit limits in a 24-hour window for various editions of Zoho CRM

Edition Allowed Credits Maximum Credits
Free Edition 5000 credits 5000 credits
Standard Edition 5,000 credits + (Number of User licenses x 250) 100,000 credits
Professional 10,000 credits + (Number of User licenses x 500) 200,000 credits
Enterprise/Zoho One/CRM Plus 10,000 credits + (Number of User licenses x 1000) 500,000 credits
Ultimate 10,000 credits + (Number of User licenses x 1000) 1,000,000 credits

Note:

  • For instance, in Standard edition, if an Organization has 10 User licenses, the minimum number of available API credits an organisation can make use of in a day is increased by (10 x 250) requests/day, making it 7500 credits.
  • Even if the number of user licenses are high, the API credit limit does not exceed the maximum limit. For ex: if the org account is the Enterprise Edition and the User licenses are 500, the total credits would become 510,000. However, the maximum api credits limit is 500,000.

The credit deduction for some of the API operations are listed below -

API Call Number of Credits Deducted
Get Users/Roles/Profiles 1
Get list of Modules 1
Get Field Meta Data 1
Get Module Meta Data 1
Get IDs of deleted records 2
Get records with cvid parameter 3
Convert Lead 5
Add/Remove Tags to Multiple records 1 credit for every 50 records
Insert/Update/Upsert 1 credit for every 10 records
Bulk Read Initialize 50
All other APIs 1

Note:

  • The Insert/Update/Upsert API call can be made for a maximum of 100 records, and the Add/Remove Tags to Multiple records API call can be made for a maximum of 500 records. Therefore, the maximum number of credits that can be deducted for these two API calls are 10.
  • The API call limit has a rolling 24 hours window, from the start of the call.

Concurrency limits for various editions of Zoho CRM


However, in addition to the above credit system, a Concurrency system is used to calculate API Limits based on the number of concurrent calls made per user per app in Zoho CRM. These concurrency limits therefore specify the maximum number of API calls that can be simultaneously active at a given point of time for a user per app. 

Since the API limits are based on the number of simultaneous active calls, there are no time-based API call restrictions in Zoho CRM. You can make any number of API calls in a minute, provided the number of concurrent calls are within the specified limits.

Edition Concurrency Limits for a User/App
Free 5
Standard 10
Professional 15
Enterprise/Zoho One/CRM Plus 20
Ultimate 25

GDPR Compliance

GDPR is a comprehensive set of rules that will replace the existing Data protection directive or Directive 95/46/EC, which will be enforced across the EU. It is designed to empower EU citizens by putting them directly in control of how they want their data to be processed and protect their data privacy due to the increasingly complex nature of personal data transmission across the world.

Note:

  • The content presented herein is not to be construed as legal advise. Please contact your legal advisor to know how GDPR impacts your organisation and what you need to do to comply with the GDPR.
  • The following changes to the API are applicable only for modules which have GDPR Compliance enabled.

Organization API

A new key "privacy_settings" is added in the Organization API. The data type of this field is boolean, i.e true/false.

Sample Request:

curl "https://www.zohoapis.com/crm/v2/org"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Sample response

Sample Response:

The purpose of this field is to check if GDPR is enabled or disabled for the said organization.

Note:

  • If privacy_settings=true, GDPR Compliance is enabled for the Org.
  • If privacy_settings=false, GDPR Compliance is disabled.

Fields API

A new field in CRM named "Data Processing Basis Details" will carry the lawful data processing basis for the particular record. You can determine the values in this field based on how you want to process your customer's data.

Currently, this field is supported only in Leads, Contacts, Vendors and Custom Modules.

Sample Request:

curl "https://www.zohoapis.com/crm/v2/settings/fields?module=Leads"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Sample response

Field Meta Data for Data Processing Basis Field:

A new key named "private" is added to the APIs, to mark the field as a protected field. The Value of the key is either a "JSON Object" or "null".

Sample Request of fields in Leads module:

curl "https://www.zohoapis.com/crm/v2/settings/fields?module=Leads"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Sample response

Sample Response of fields in Leads module:

Fields can be set to be "private" by enabling the option in the Layout editor. If the user creates a protected field but does not select the sensitivity of the data(sensitive/normal), then the private key is null.

The "type" attribute can be either "High" or "Low", based on the sensitivity of the data. Once the privacy settings is enabled for the Org, the private field value to be shown in records GET API will be based on the "Preferences" settings.

The "High" and "Low" values correspond to the "Sensitive" and "Normal" values as in the Personal Fields in the CRM UI.

Note:

  • If "restricted" in the private key is true, then the values of a field will not be exposed in any record related APIs.

Records API - INSERT

When Inserting or adding a record, the Data Processing Basis Details key must be given in the POST request. This new key contains the details of the consent form that is accepted by a customer. In another sense, within a request, this key can be used to add consent details to a particular record.

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Leads"

-X POST

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Sample request

Sample Request for Input Records:

The values in this key are in the form of a JSON Object.

Note:

  • The same request pattern is to be followed for Update and Upsert records APIs.
  • If the Data Processing Basis Details are not specified when inserting a record, Data_Processing_Basis_Details key becomes null.

Records API - GET

This API retrieves all the data of a record along with the Consent Details. In the following example, the "Email" field is marked as a private field. Hence, the value of the field becomes null.

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Leads/111111000000034001?include=private_fields"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Sample response

Sample Response:

Note:

  • The above example is also applicable for bulk operations (Bulk Get, Bulk Insert, etc).
  • In the above sample response, the "Email" field is privacy protected. Hence, the field has the value as "null", even if the email for the record exists.
  • Add "include=private_fields" in the params section of the Request URL to include the "private_fields" key in any GET APIs.
  • If the "$stop_processing" key for a particular record is true, then any Update, Upsert or ConvertLead process cannot be used on the record.

Search APIs

The Data Processing Basis (Lawful Basis) details are shown along with the record details in the Search APIs.

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Leads/search?criteria=(Last_Name:equals:Boyle)"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Sample response

Sample Response:

In the above example, the email field is marked as private (restricted=true) and hence, the value is null.

The following error is thrown when the record with the said email is searched through Criteria:

Sample response

Sample Error:

Note:

  • The output responses of Search APIs are similar to the GET APIs.
  • A restricted private field cannot be searched through Criteria.

API Dashboard

The new API dashboard features an all new interface to view your usage statistics. The interface is made up of a graph view and a table view. You can classifiy the stats based on modules, IP address from which the call was made, method, user or time. This dashboard supports the previous version of the API as well as the new version.

The New API Usage statistics:

  • The progress bar stays purple till 90% of the API calls are made, after which it turns red.
  • The new API follows the "Last 24 hours tracking" method.

Note:

  • The last 24 hours tracking method is practised only in the new version 2 API.
  • There would be a 15 minute delay in refreshing the statistics. However, the number of API calls used are updated immediately.
  • Statistics of API Usage older than 30 days will be deleted periodically.

The usage statistics helps you keep track of the number of API calls that you have made in order to plan how to use the CRM in the most effective way. The statistics for the V2 API(new) is classified in the following ways.

Application based:

The new API relies on making API calls from specific applications. Hence, the classification based on what application the call was made from would make more sense than classifying them based on the method of the API call.

Graph view:

A doughnut chart is used to represent the top 5 applications for which APIs were called.

Click the List view icon to view the top 5 most used applications in list format.

Note:

  • Click any of the application name to open the statistics for that application in Table view.

Table view:

The applications column is set as the default column and the rest of the information are arranged accordingly.

Module based:

You can view usage statistics based on API calls from modules.

Graph view:

Only the top 5 modules are displayed in the Graph view. Click on any of the module's name to open the stats in table view with the default column as "Module".

Note:

  • Click the list view button to view, the top 5 methods from which the API calls are made, can be viewed as a list.
  • Click View all to view the statistics of all the modules.

Table view:

The table view is even more precise as it displays all the information regarding the module in one go.

Note:

  • Click Sort order to sort the table in the required view.
  • Hover the pointer to the information and you can see the connection between the records.

IP Address based:

List view:

You can find the statistics based on the User's IP address in the Graph view page. In other words, the stats are displayed based on the Access points of the Users. The Top 5 IP Addresses classified based on number of API calls made from them, will be displayed. To view all of the User IP addresses, click View all.

Note:

  • Click on any of the IP addresses to open the Table view with IP address as the default column.

Table view:

The table view, the IP address column is set as default and the rest of the information is arranged based on it.

User based:

You can view the usage based on who made the API calls in the Prolific users section.

Graph view:

The top 3 users who made the most API calls are listed in this section.

Note:

  • Click View all, to view the number of API calls made by all individual users.

Table view:

The IP address, method and the module used by a User can be viewed by setting the User column as the default column in the Table view. However, refreshing the page resets the view.

Time based:

One of the easier way to know your usage and limits would be to take account of the time in which the API calls are made. This is available only in the graph view.

The graph displaying stats in a single day:

The graph displaying stats for a range of dates:

HTTP Status Codes

Status Codes Meaning Description
200 OK The API request is successful.
201 CREATED Request fulfilled for single record insertion.
202 ACCEPTED Request fulfilled for multiple records insertion.
204 NO CONTENT There is no content available for the request.
304 NOT MODIFIED The requested page has not been modified. In case "If-Modified-Since" header is used for GET APIs
400 BAD REQUEST The request or the authentication considered is invalid.
401 AUTHORIZATION ERROR Invalid API key provided.
403 FORBIDDEN No permission to do the operation.
404 NOT FOUND Invalid request.
405 METHOD NOT ALLOWED The specified method is not allowed.
413 REQUEST ENTITY TOO LARGE The server did not accept the request while uploading a file, since the limited file size has exceeded.
415 UNSUPPORTED MEDIA TYPE The server did not accept the request while uploading a file, since the media/ file type is not supported.
429 TOO MANY REQUESTS Number of API requests per minute/day has exceeded the limit.
500 INTERNAL SERVER ERROR Generic error that is encountered due to an unexpected server error.

HTTP Methods

Method Description
GET To retrieve data from the given server.
POST To insert or upload any new resource to the server.
PUT To update an existing resource. This replaces the target resource with the updated content.
DELETE To delete a resource at a particular location.

For example, using the GET method, you can retrieve the list of resources or get the details of a particular resource.

To get a list of modules, send request as shown below:

curl "https://www.zohoapis.com/crm/v2/settings/modules"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

To get the details of a specific record, send the record_id in your API request as shown below:

curl "https://www.zohoapis.com/crm/v2/Leads/410888000000698006"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Modules APIs

Zoho CRM has standard modules such as, Leads, Accounts, Contacts, Deals, Forecasts, Activities, etc,. Using Zoho CRM REST API, you can retrieve the list of available modules as shown in the examples below:

Get list of modules

Purpose

To get the module related data. This will retrieve the list of modules available in your CRM account.

Request URL

https://www.zohoapis.com/crm/v2/settings/modules

Scope

scope=ZohoCRM.settings.all
(or)
scope=ZohoCRM.settings.modules.{operation_type}

Possible operation types
ALL, READ

Request Method

GET

Curl Java PHP Python C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/settings/modules"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

ZCRMRestClient client = ZCRMRestClient.getInstance();

BulkAPIResponse response = client.getAllModules();

List<ZCRMModule> modules = (List<ZCRMModule>) response.getData();

Copy sample request

Sample Request:

try{
$ins=ZCRMRestClient::getInstance();
$moduleArr=$ins->getAllModules()->getData();
foreach ($moduleArr as $module)
{
echo "ModuleName:".$module->getModuleName();
echo "SingLabel:".$module->getSingularLabel();
echo "PluLabel:".$module->getPluralLabel();
echo "BusinesscardLimit:".$module->getBusinessCardFieldLimit();
echo "ApiName:".$module->getAPIName();
$fields=$module->getFields();
if($fields==null)
{
continue;
}
foreach ($fields as $field)
{
echo $field->getApiName().", ";
echo $field->getLength().", ";
echo $field->IsVisible().", ";
echo $field->getFieldLabel().", ";
echo $field->getCreatedSource().", ";
echo $field->isMandatory().", ";
echo $field->getSequenceNumber().", ";
echo $field->isReadOnly().", ";
echo $field->getDataType().", ";
echo $field->getId().", ";
echo $field->isCustomField().", ";
echo $field->isBusinessCardSupported().", ";
echo $field->getDefaultValue().", ";
}
}
}
catch (ZCRMException $e)
{
echo $e->getCode();
echo $e->getMessage();
echo $e->getExceptionCode();
}

Copy sample request

Sample Request:

Get api supported modules alone

zclient = ZohoCRMClient.get_client_objects(conf_file_location)[0]
Meta_data.get_module_names(zclient, true)

Get all module names

zclient = ZohoCRMClient.get_client_objects(conf_file_location)[0]
Meta_data.get_module_names(zclient, false)

Copy sample request

Sample Request:

ZCRMRestClient restClient = ZCRMRestClient.GetInstance();
BulkAPIResponse<ZCRMModule> response = restClient.GetAllModules();
List<ZCRMModule> modules = response.BulkData; // modules - list of ZCRMModule instances

Copy sample request

Sample Request:

def get_modules(self):

  try:

    resp=ZCRMRestClient.get_instance().get_all_modules()

    modules=resp.data

    print resp.status_code

    for module in modules:

      print "\n\n::MODULE::"

      print module.api_name

      print module.is_convertable

      print module.is_creatable

      print module.is_editable

      print module.is_deletable

      print module.web_link

      print module.singular_label

      print module.plural_label

      print module.modified_by

      print module.modified_time

      print module.is_viewable

      print module.is_api_supported

      print module.is_custom_module

      print module.is_scoring_supported

      print module.id

      print module.module_name

      print module.business_card_field_limit

      print module.business_card_fields

      profiles= module.profiles

      if profiles is not None:

        for profile inprofiles:

          print profile.name

          print profile.id

      print module.display_field_name

      print module.display_field_id

      if module.related_lists is not None:

        for relatedlist in module.related_lists:

          print relatedlist.display_label

          print relatedlist.is_visible

          print relatedlist.api_name

          print relatedlist.module

          print relatedlist.name

          print relatedlist.id

          print relatedlist.href

          print relatedlist.type

      if module.layouts is not None:

        for layout in module.layouts:

          self.print_layout(layout)

      if module.fields is not None:

        for field_ins in module.fields:

          self.print_filed(field_ins)

      if module.related_list_properties is not None:

        print module.related_list_properties.sort_by

        print module.related_list_properties.sort_order

        print module.related_list_properties.fields

      print module.properties

      print module.per_page

      print module.search_layout_fields

      print module.default_territory_name

      print module.default_territory_id

      print module.default_custom_view_id

      print module.default_custom_view

      print module.is_global_search_supported

      print module.sequence_number

except ZCRMException as ex:

    print ex.status_code

    print ex.error_message

    print ex.error_code

    print ex.error_details

    print ex.error_content

Copy sample response

Sample Response:

Attributes:

  • "convertable" : Describes if the user can convert the record into another type of record. For example: Convert Leads in to Deals.
  • "creatable" : Checks if the user can create a record in the current module.
  • "generated_type" : Describes the type of module which would be generated by the user. There are 4 types: default, web, custom, linking.
  • "api_supported" : The modules which are currently not accessible by APIs have value as "false". If the modules are supported in the future, the value automatically changes to "true".
  • "modified_time" : The date and time of changes made by the user.

Note:

The key "api_name" should be referred in the JSON data while accessing the resource. Every module, field and related lists will have a API name, which can be used in third party integrations. For example, if you want to access the Leads module, “Leads" has to be used as the api_name every time you access the resource. New API names are generated internally in Zoho CRM, while creating a custom module, custom field or related list label. Please note that, API Names for the default modules, fields and related lists cannot be altered. You are allowed to change the API names only for custom modules, fields and related lists.

The generated API name can contain only alphabets, numbers and underscore. The API name should start with an alphabet and should not have two consecutive underscores or end with an underscore.

Users APIs

In Zoho CRM, user is the one who is allowed to access and manage the CRM records. These users can be defined under various profiles and categories such as Administrators, Standard, etc,.

Using the Users APIs, you can retrieve the basic information of your available CRM users. Use the type parameter to get the required list of users. For example, you can set the param type as AdminUsers, to get the list of CRM users with Administrative profile. The detailed explanation of the Users API and the examples are shown below:

Get users

Purpose

To retrieve the users data specified in the API request. You can specify the type of users that needs to be retrieved using the Users API. For example, use type=AllUsers, to get the list of all the CRM users available.

Request URL

https://www.zohoapis.com/crm/v2/users

Scope

scope=ZohoCRM.users.{operation_type}

Possible operation types
ALL - Full access to users
READ - get user data

Request Method

GET

Parameters

Parameter Name Data Type Description
type String
AllUsers

To list all users in your organization (both active and inactive users)

ActiveUsers

To get the list of all Active Users

DeactiveUsers

To get the list of all users who were deactivated

ConfirmedUsers

To get the list of confirmed users

NotConfirmedUsers

To get the list of non-confirmed users

DeletedUsers

To get the list of deleted users

ActiveConfirmedUsers

To get the list of active users who are also confirmed

AdminUsers

To get the list of admin users.

ActiveConfirmedAdmins

To get the list of active users with the administrative privileges and are also confirmed

CurrentUser

To get the list of current CRM users

Curl Java PHP Python C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/users?type=AllUsers"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

Get All Users

ZCRMRestClient client = ZCRMRestClient.getInstance();

BulkAPIResponse response = client.getOrganisationInstance().getAllUsers();

List<ZCRMUser> users = (List<ZCRMUser>) response.getData();

Copy sample request

Sample Request:

try{
$bulkAPIResponse=ZCRMOrganization::getInstance()->getAllUsers();
$users=$bulkAPIResponse->getData();
foreach($users as $userInstance)
{
echo $userInstance->getCountry();
$roleInstance=$userInstance->getRole();
echo $roleInstance->getId();
echo $roleInstance->getName();
$customizeInstance=$userInstance->getCustomizeInfo();
if($customizeInstance!=null)
{
echo $customizeInstance->getNotesDesc();
echo $customizeInstance->getUnpinRecentItem();
echo $customizeInstance->isToShowRightPanel();
echo $customizeInstance->isBcView();
echo $customizeInstance->isToShowHome();
echo $customizeInstance->isToShowDetailView();
}
echo $userInstance->getCity();
echo $userInstance->getSignature();
echo $userInstance->getNameFormat();
echo $userInstance->getLanguage();
echo $userInstance->getLocale();
echo $userInstance->isPersonalAccount();
echo $userInstance->getDefaultTabGroup();
echo $userInstance->getAlias();
echo $userInstance->getStreet();
$themeInstance=$userInstance->getTheme();
if($themeInstance!=null)
{
echo $themeInstance->getNormalTabFontColor();
echo $themeInstance->getNormalTabBackground();
echo $themeInstance->getSelectedTabFontColor();
echo $themeInstance->getSelectedTabBackground();
}
echo $userInstance->getState();
echo $userInstance->getCountryLocale();
echo $userInstance->getFax();
echo $userInstance->getFirstName();
echo $userInstance->getEmail();
echo $userInstance->getZip();
echo $userInstance->getDecimalSeparator();
echo $userInstance->getWebsite();
echo $userInstance->getTimeFormat();
$profile= $userInstance->getProfile();
echo $profile->getId();
echo $profile->getName();
echo $userInstance->getMobile();
echo $userInstance->getLastName();
echo $userInstance->getTimeZone();
echo $userInstance->getZuid();
echo $userInstance->isConfirm();
echo $userInstance->getFullName();
echo $userInstance->getPhone();
echo $userInstance->getDob();
echo $userInstance->getDateFormat();
echo $userInstance->getStatus();
}
}
catch(ZCRMException $e)
{
echo $e->getMessage();
echo $e->getExceptionCode();
echo $e->getCode();
}

Copy sample request

Sample Request:

ZCRMRestClient restClient = ZCRMRestClient.GetInstance();
BulkAPIResponse<ZCRMUser> response = restClient.GetOrganizationInstance().GetAllUsers();
List<ZCRMUser> allUsers = response.BulkData; //response - list of ZCRMUser instances

Copy sample request

Sample Request:

def get_users(self,user_type):

  try:

    if user_type=='all':

      resp=ZCRMOrganization.get_instance().get_all_users()

    elif user_type=='DeactiveUsers':

      resp=ZCRMOrganization.get_instance().get_all_deactive_users()

    elif user_type=='ActiveUsers':

      resp=ZCRMOrganization.get_instance().get_all_active_users()

    elif user_type=='ConfirmedUsers':

      resp=ZCRMOrganization.get_instance().get_all_confirmed_users()

    elif user_type=='NotConfirmedUsers':

      resp=ZCRMOrganization.get_instance().get_all_not_confirmed_users()

    elif user_type=='DeletedUsers':

      resp=ZCRMOrganization.get_instance().get_all_deleted_users()

    elif user_type=='ActiveConfirmedUsers':

      resp=ZCRMOrganization.get_instance().get_all_active_confirmed_users()

    elif user_type=='AdminUsers':

      resp=ZCRMOrganization.get_instance().get_all_admin_users()

    elif user_type=='ActiveConfirmedAdmins':

      resp=ZCRMOrganization.get_instance().get_all_active_confirmed_admin_users()

    elif user_type=='CurrentUser':

      resp=ZCRMOrganization.get_instance().get_current_user()

    print resp.status_code

    if resp.status_code!=200:

      return

    users=resp.data

    for user in users:

      print "\n\n"

      print user.id

      print user.name

      print user.signature

      print user.country

      crm_role=user.role

      if crm_role is not None:

        print crm_role.name

        print crm_role.id

      customize_info= user.customize_info

      if customize_info is not None:

        print customize_info.notes_desc

        print customize_info.is_to_show_right_panel

        print customize_info.is_bc_view

        print customize_info.is_to_show_home

        print customize_info.is_to_show_detail_view

        print customize_info.unpin_recent_item

      print user.city

      print user.name_format

      print user.language

      print user.locale

      print user.is_personal_account

      print user.default_tab_group

      print user.street

      print user.alias

      user_theme=user.theme

      if user_theme is not None:

        print user_theme.normal_tab_font_color

        print user_theme.normal_tab_background

        print user_theme.selected_tab_font_color

        print user_theme.selected_tab_background

      print user.state

      print user.country_locale

      print user.fax

      print user.first_name

      print user.email

      print user.zip

      print user.decimal_separator

      print user.website

      print user.time_format

      crm_profile= user.profile

      if crm_profile is not None:

        print crm_profile.id

        print crm_profile.name

      print user.mobile

      print user.last_name

      print user.time_zone

      print user.zuid

 nbsp;     print user.is_confirm

      print user.full_name

      print user.phone

      print user.dob

      print user.date_format

      print user.status

  except ZCRMException as ex:

    print ex.status_code

    print ex.error_message

    print ex.error_code

    print ex.error_details

    print ex.error_content

Copy sample response

Sample Response:

Load more examples

Get single user data

Purpose

To get the details of any specific user. Specify the unique id of the user in your API request to get the data for that particular user.

Request URL

https://www.zohoapis.com/crm/v2/users/{user_id}

user_id - Specify the unique id of the user.

Scope

scope=ZohoCRM.users.{operation_type}

Possible operation types
ALL - Full access to users
READ - get user data

Request Method

GET

Curl Java PHP Python C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/users/4108880000469041"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

ZCRMRestClient client = ZCRMRestClient.getInstance();

APIResponse response =

client.getOrganisationInstance().getUser(123456789l);//userID

ZCRMUser user = (ZCRMUser) response.getData();

Copy sample request

Sample Request:

ZCRMRestClient restClient = ZCRMRestClient.GetInstance();
APIResponse response = restClient.GetOrganizationInstance().GetUser(33721640000); // 33721640000 is user id
ZCRMUser user = (ZCRMUser)response.Data;

Copy sample request

Sample Request:

try{
$apiResponse=ZCRMOrganization::getInstance()->getUser($userId); // $userId - ID of the user whose data has to be fetched.
$users=array($apiResponse->getData());
foreach($users as $userInstance)
{
echo $userInstance->getCountry();
$roleInstance=$userInstance->getRole();
echo $roleInstance->getId();
echo $roleInstance->getName();
$customizeInstance=$userInstance->getCustomizeInfo();
if($customizeInstance!=null)
{
echo $customizeInstance->getNotesDesc();
echo $customizeInstance->getUnpinRecentItem();
echo $customizeInstance->isToShowRightPanel();
echo $customizeInstance->isBcView();
echo $customizeInstance->isToShowHome();
echo $customizeInstance->isToShowDetailView();
}
echo $userInstance->getCity();
echo $userInstance->getSignature();
echo $userInstance->getNameFormat();
echo $userInstance->getLanguage();
echo $userInstance->getLocale();
echo $userInstance->isPersonalAccount();
echo $userInstance->getDefaultTabGroup();
echo $userInstance->getAlias();
echo $userInstance->getStreet();
$themeInstance=$userInstance->getTheme();
if($themeInstance!=null)
{
echo $themeInstance->getNormalTabFontColor();
echo $themeInstance->getNormalTabBackground();
echo $themeInstance->getSelectedTabFontColor();
echo $themeInstance->getSelectedTabBackground();
}
echo $userInstance->getState();
echo $userInstance->getCountryLocale();
echo $userInstance->getFax();
echo $userInstance->getFirstName();
echo $userInstance->getEmail();
echo $userInstance->getZip();
echo $userInstance->getDecimalSeparator();
echo $userInstance->getWebsite();
echo $userInstance->getTimeFormat();
$profile= $userInstance->getProfile();
echo $profile->getId();
echo $profile->getName();
echo $userInstance->getMobile();
echo $userInstance->getLastName();
echo $userInstance->getTimeZone();
echo $userInstance->getZuid();
echo $userInstance->isConfirm();
echo $userInstance->getFullName();
echo $userInstance->getPhone();
echo $userInstance->getDob();
echo $userInstance->getDateFormat();
echo $userInstance->getStatus();
}
}
catch(ZCRMException $e)
{
echo $e->getMessage();
echo $e->getExceptionCode();
echo $e->getCode();
}

Copy sample request

Sample Request:

def get_user(self):

  try:

    resp=ZCRMOrganization.get_instance().get_user(1386586000000105001)

    print resp.status_code

    if resp.status_code!=200:

      return

    users=[resp.data]

    for user in users:

      print user.id

      print user.name

      print user.signature

      print user.country

      crm_role=user.role

      if crm_role is not None:

        print crm_role.name

        print crm_role.id

      customize_info= user.customize_info

      if customize_info is not None:

        print customize_info.notes_desc

        print customize_info.is_to_show_right_panel

        print customize_info.is_bc_view

        print customize_info.is_to_show_home

        print customize_info.is_to_show_detail_view

        print customize_info.unpin_recent_item

      print user.city

      print user.name_format

      print user.language

      print user.locale

      print user.is_personal_account

      print user.default_tab_group

      print user.street

      print user.alias

      user_theme=user.theme

      if user_theme is not None:

        print user_theme.normal_tab_font_color

        print user_theme.normal_tab_background

        print user_theme.selected_tab_font_color

        print user_theme.selected_tab_background

      print user.state

      print user.country_locale

      print user.fax

      print user.first_name

      print user.email

      print user.zip

      print user.decimal_separator

      print user.website

      print user.time_format

      crm_profile= user.profile

      if crm_profile is not None:

        print crm_profile.id

        print crm_profile.name

      print user.mobile

      print user.last_name

      print user.time_zone

      print user.zuid

      print user.is_confirm

      print user.full_name

      print user.phone

      print user.dob

      print user.date_format

      print user.status

  except ZCRMException as ex:

    print ex.status_code

    print ex.error_message

    print ex.error_code

    print ex.error_details

    print ex.error_content

Copy sample response

Sample Response:

Roles APIs

In Zoho CRM, roles are issued to users by the Administrator. Usually, roles are meant to denote the different levels of employees in a company. For instance, it can be Managers, Sales Reps, Supervisors, Product Management Staff, etc.

Using the Roles APIs, you can retrieve the basic information of roles. The detailed explanation of the Roles APIs and the examples are shown below:

Get roles

Purpose

To retrieve the data of roles through an API request.

Request URL

https://www.zohoapis.com/crm/v2/settings/roles

Scope

scope=ZohoCRM.settings.roles.{operation_type}

Possible operation types
ALL - Full access to roles data
READ - get role data

Request Method

GET

Curl Python C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/settings/roles"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

Get All Users

Copy sample request

Sample Request:

Copy sample request

Sample Request:

ZCRMRestClient restClient = ZCRMRestClient.GetInstance();
BulkAPIResponse<ZCRMRole> response = restClient.GetOrganizationInstance().GetAllRoles();
List<ZCRMRole> roles = response.BulkData; // roles - list of ZCRMRole instance

Copy sample request

Sample Request:

def get_roles(self):

  try:

    resp=ZCRMOrganization.get_instance().get_all_roles()

    roles=resp.data

    print resp.status_code

    for role in roles:

      print "\n\n"

      print role.name

      print role.id

      print role.display_label

      print role.is_admin

      if role.reporting_to is not None:

        print role.reporting_to.id

        print role.reporting_to.name

  except ZCRMException as ex:

    print ex.status_code

    print ex.error_message

    print ex.error_code

    print ex.error_details

    print ex.error_content

Copy sample response

Sample Response:

Get single role data

Purpose

To get the details of any specific role. Specify the unique id of the role in your API request to get the data for that particular role.

Request URL

https://www.zohoapis.com/crm/v2/settings/roles/{role_id}

role_id - Specify the unique id of the role.

Scope

scope=ZohoCRM.settings.roles.{operation_type}

Possible operation types
ALL - Full access to roles data
READ - get role data

Request Method

GET

Curl Python C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/settings/roles/2883756000000026005"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

Copy sample request

Sample Request:

ZCRMRestClient restClient = ZCRMRestClient.GetInstance();
APIResponse response = restClient.GetOrganizationInstance().GetRole(33721640000000); // 33721640000000 is role id
ZCRMRole role = (ZCRMRole)response.Data;

Copy sample request

Sample Request:

def get_role(self):

  try:

    resp=ZCRMOrganization.get_instance().get_role(1386586000000026008)

    roles=[resp.data]

    print resp.status_code

    for role in roles:

      print role.name

      print role.id

      print role.display_label

      print role.is_admin

      if role.reporting_to is not None:

        print role.reporting_to.id

        print role.reporting_to.name

  except ZCRMException as ex:

    print ex.status_code

    print ex.error_message

    print ex.error_code

    print ex.error_details

    print ex.error_content

Copy sample response

Sample Response:

Profiles APIs

Profiles define a set of privileges a user has within Zoho CRM. The administrator gets to decide a user's level of data access. All users need to be assigned to a profile during initialization.

Using the Profiles APIs, you can retrieve the basic information of the profiles. The detailed explanation of the Profiles APIs and the examples are shown below:

Get profiles

Purpose

To retrieve the data of profiles through an API request.

Request URL

https://www.zohoapis.com/crm/v2/settings/profiles

Scope

scope=ZohoCRM.settings.profiles.{operation_type}

Possible operation types
ALL - Full access to profiles data
READ - get profile data

Request Method

GET

Curl Python C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/settings/profiles"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

Get All Users

Copy sample request

Sample Request:

Copy sample request

Sample Request:

ZCRMRestClient restClient = ZCRMRestClient.GetInstance();
BulkAPIResponse<ZCRMProfile> response = restClient.GetOrganizationInstance().GetAllProfiles();
List<ZCRMProfile> profiles = response.BulkData; // profiles - list of ZCRMProfile instance

Copy sample request

Sample Request:

def get_profiles(self):

  try:

    resp=ZCRMOrganization.get_instance().get_all_profiles()

    profiles=resp.data

    print resp.status_code

    for profile in profiles:

      print "\n\n"

      print profile.name

      print profile.id

      print profile.is_default

      print profile.created_time

      print profile.modified_time

      print profile.modified_by

      print profile.description

      print profile.created_by

      print profile.category

      print profile.permissions

      sections= profile.sections

      if sections is not None:

        for section in sections:

          print section.name

          print section.categories

  except ZCRMException as ex:

    print ex.status_code

    print ex.error_message

    print ex.error_code

    print ex.error_details

    print ex.error_content

Copy sample response

Sample Response:

Get single profile data

Purpose

To get the details of any specific profile. Specify the unique id of the profile in your API request to get the data for that particular profile.

Request URL

https://www.zohoapis.com/crm/v2/settings/profiles/{profile_id}

profile_id - Specify the unique id of the profile.

Scope

scope=ZohoCRM.settings.profiles.{operation_type}

Possible operation types
ALL - Full access to profile data
READ - get profile data

Request Method

GET

Curl Python C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/settings/profiles/2883756000000026011"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

Copy sample request

Sample Request:

ZCRMRestClient restClient = ZCRMRestClient.GetInstance();
APIResponse response = restClient.GetOrganizationInstance().GetProfile(33721640000000); // 33721640000000 is profile id
ZCRMProfile profile = (ZCRMProfile)response.Data;

Copy sample request

Sample Request:

def get_profile(self):

  try:

    resp=ZCRMOrganization.get_instance().get_profile(1386586000000026014)

    profiles=[resp.data]

    print resp.status_code

    for profile in profiles:

      print profile.name

      print profile.id

      print profile.is_default

      print profile.created_time

      print profile.modified_time

      print profile.modified_by

      print profile.description

      print profile.created_by

      print profile.category

      permissions= profile.permissions

      if permissions is not None:

        print ":::PERMISSIONS:::"

        for permission in permissions:

          print permission.name

          print permission.id

          print permission.display_label

          print permission.module

          print permission.is_enabled

      sections= profile.sections

      if sections is not None:

        for section in sections:

          print section.name

          categories=section.categories

          if categories is not None:

            print "::::CATEGORIES:::"

            for category in categories:

              print category.name

              print category.display_label

              print category.permission_ids

              print category.module

  except ZCRMException as ex:

    print ex.status_code

    print ex.error_message

    print ex.error_code

    print ex.error_details

    print ex.error_content

Copy sample response

Sample Response:

Bulk Read APIs

Bulk Read API allows you to fetch large set of data. This API is very useful whenever you require to export a large amount of data or to take a backup of your data without big impact on your API limits.

This is an asynchronous API, meaning that the response of your request is not available immediately. You will be notified to the callback URL when the data is ready to download or you can choose to check the job status periodically.

Note:

  • Please note that the results are available only as a downloadable CSV file.

How it Works


Step 1 : Create a bulk read job


Create a POST API call, by providing the module, the list of fields to be exported and a criteria, to filter the records. It will create an asynchronous job and return a unique identifier param, 'id', which is the reference of your request.

Step 2 : Check job status


If you require the system to automatically notify you on the job completion, you can simply provide the 'callback' URL while creating a bulk read job. Else, you can also choose to check the status of the job at periodic intervals, by making GET API call using the 'id' of the job.

Step 3 : Download the result


When the job is completed successfully, the 'download_url' is available in the 'result' attribute of the response of the API. Now, you can download the result of the job by calling the 'download_url’. A ZIP file will get downloaded, containing the CSV file within it.


Create Bulk Read job

Purpose

To create a bulk data export job. You can export a maximum of two hundred thousand records in a single job.

Request URL

https://www.zohoapis.com/crm/bulk/v2/read

Scope

scope=ZohoCRM.bulk.read
(and)
scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, tasks, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, users and custom. ALL - Full access to a record
READ - get bulk read job

Request JSON

Attributes Data Type Mandatory Description
callback Show properties JSON Object No A valid URL, which should allow HTTP Post method. The Bulk Read Job's details is posted to this URL on successful completion of job or on failure of job. Sample - "callback" : { "url": "https://sampledomain.com/getzohoresponse", "method": "post" }

Show Callback Properties

Attributes Data Type Mandatory Description
url String(URL) Yes A valid URL, which should allow HTTP POST method. The Bulk Read Job's details is posted to this URL on successful completion of job or on failure of job.
method String Yes Specifies the HTTP method of the callback url. Only HTTP POST method is supported, the allowed value 'post'.
query Show properties JSON Object Yes Please refer the below table for information on a query JSON object.

Show Query Properties

Attributes Data Type Mandatory Description
module String Yes Specifies the API Name of the module to be read. eg: Leads, Contacts. Sample - "module" : "Leads”.
fields Array No Specifies the API Name of the fields to be fetched. eg: First_Name, Last_Name, Email. Sample - "fields" : ["First_Name", "Last_Name", "Email”].
page Integer No Default value for page is 1. The page value '1' means that the first 200,000 records matching your query will get exported. If you want to fetch the records from the range 200,001 to 400,000 , then you should mention the page as '2'.
criteria Show properties JSON Object No To filter the records to be exported. Ex: The API Name of a module or field, comparators used to add two or more criteria, a group to which the record/module/field belongs to, etc.

Show Criteria Properties

Attributes Data Type Mandatory Description
api_name String Yes, if group & group_operator are not specified. API name of a field to be compared. eg: First_Name, Last_Name.
value String or Array Yes, if group & group_operator are not specified. Positive Integer values only
group_operator String Yes, if api_name, comparator & value are not specified. Logical operators. Supported values - and, or.
group Array (criteria JSON object) Yes, if api_name, comparator & value are not specified. Array of criteria objects.
comparator Show properties String Yes, if group & group_operator are not specified. Specifies any kind of comparator. eg: equal, greater_than. Refer the table given below for more details.

Show Comparator Details

Data Type Comparator Value Limits
Number (Integer)
Decimal/BigInteger/
Currency/Percent)
equal, not_equal, in, not_in, less_than, less_equal, greater_than, greater_equal Any number values or ${EMPTY} for empty value. Not more than 19 digits for big integer, allow decimal values for decimal & currency fields. In multi-currency enabled account, only home currency value is supported.
Text (Email, Phone, URL, Picklist, Multi-select, etc) equal, not_equal, in, not_in, contains, not_contains, starts_with, ends_with. Any text values or ${EMPTY} for empty value Not more than 255 characters.
Date equal, not_equal, in, not_in, between, not_between. Any date values in ISO 8601 format or ${EMPTY} for empty value.  
Date Time equal, not_equal, in, not_in, between, not_between. Any date time values in ISO 8601 format or ${EMPTY} for empty value. Milliseconds is not supported.
Boolean equal True / False.  
Lookup equal, not_equal, in, not_in Biginteger value of the lookup or ${EMPTY} for empty value. Lookup Name is not supported.
Text Area (Multiline)     Not Supported.

Response Structure

Attributes Data Type Description
status String Specifies the status of the API call. Sample - "status": "success".
message String Specifies the pre-defined comments for the job. Useful in case any errors occur. Sample - "message": "Added successfully.".
details Show properties JSON Object Please refer the below table for information on the "details" JSON object.

Details parameter Properties

Attributes Data Type Description
operation String Specifies the type of action the API completed. Sample - "operation" : "read”.
created_by JSON Object Specifies the ID and Name of the user who initiated the bulk read job. Sample - "created_by": { "id": "1000000031045", "name": "Chakra" },
created_time ISO8601 Specifies the created time of the bulk read job.
state String Specifies the current status of the bulk read job. Example: "state": "ADDED" or "IN PROGRESS" or "COMPLETED".
id String Specifies the unique identifier of the bulk read job. This attribute is very important, since it has to be used for checking the job status and for downloading the result. Sample - "id": "1000010760002".

Request Method

POST

Curl
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/bulk/v2/read"

-X POST

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

-d "@inputData.json"

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

In the above request, @inputData.json contains the sample input data.

Copy sample input

Sample Input:

Note:

  • A maximum of two hundred thousand records can be exported in a single export job. i.e, "page" would be "1" and the records in the page would be "200,000". To know more about the Bulk API limits, go here.
  • The first 200,000 records matching the criteria are taken for export if the value of the "page" is "1".
Copy sample response

Sample Response:

Get Bulk Read Job details

Purpose

To get the details of a bulk read job performed previously.

Request URL

https://www.zohoapis.com/crm/bulk/v2/read/{job_id}

job_id - Specifies the unique id of a bulk read job.

Scope

scope=ZohoCRM.bulk.read
(and)
scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, tasks, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, custom and users. ALL - Full access to related records
READ - get bulk read job

Request Method

GET

Response Structure

Attributes Data Type Description
operation String Specifies the type of action the API completed. Sample - "operation" : "read”.
created_by JSON Object Specifies the ID and Name of the user who initiated the bulk read job. Sample - "created_by": { "id": "1000000031045", "name": "Chakra" },
created_time ISO8601 Specifies the time period of when the bulk read job was initialized.
state String Specifies the current status of the bulk read job. Example: "state": "ADDED" or "IN PROGRESS" or "COMPLETED".
query JSON Object Specifies the "query" provided by the user when creating the bulk read job. The attributes are the same as in the Request JSON, with "modules", "fields", "criteria" and "page".
id String Specifies the unique identifier of the bulk read job. Sample - "id": "1000010760002".
result Show properties JSON Object It is available only after the completion of the job. Please refer the below table for information on the "result" JSON object.

Result parameter Properties

Attributes Data Type Description
page Integer Describes the range of the number of records exported. If the "page" is one, then the number of records would be between 1 - 200,000. If it's "two", then the records from 200,001 - 400,000 will be taken for export.
count Integer Specifies the actual number of records exported. Sample - "count": 14567
download_url String Specifies the url which contains the CSV file. User can send a GET request with your api domain attached to the download URL to download the file. Sample - "/crm/bulk/v2/read/2883756000001275012/result".
more_records Boolean The "more_records" key in the response can be used to detect if there are any further records. You can change the value of "page" key for additional export jobs.
Curl
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/bulk/v2/read/1000000031045"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Note:

  • To know more about the Bulk API limits, go here.
Copy sample response

Sample Response for Job Added

Note:

  • The "state" attribute would be "ADDED".
  • The "query" attribute in the response contains the details of the module, field and criteria that were used to select the records for export.
Copy sample response

Sample Response for Job In Progress

Note:

  • The response does not contain any special attributes if the job is in progress.
  • The "state" attribute would be "IN PROGRESS".
Copy sample response

Sample Response for Job Completed

Note:

  • The "state" attribute would be "COMPLETED".
  • The "result" attribute in the response contains information regarding the number of records exported and also the download link for the file which contains the exported records.

Things of Note:


  • Polling and Callback options are supported in this API.
  • This API is supported for all modules except Notes, Attachments, Emails and related and cross modules.
  • Sorting and Group by clause are not supported via this API endpoints.
  • Response contains a compressed file {job_id}.zip, which contains the result as a {job_id}.csv file.
  • A maximum of two hundred thousand records can be exported in a single export job. i.e, "page" would be "1".
  • In case there are additional records to be exported, the "page" key can be set to "2", which would fetch the records starting from 200,001 to 400,000.
  • In the CSV file, lookup fields do not contain the record name, but only the "id" of the record.

Limits of Bulk Read APIs


  • Only 10 requests for download is allowed for 1 minute interval. Crossing the limit may result in an error (http code :429) returned to user as response. All downloads will be unsuccessful and the download request will be processed only after one minute.
  • After completing the bulk job, the downloadable file could be accessed only for a period of one day. After that job will not be accessible via endpoints.
  • Maximum of 200 select fields can be given via endpoint anything above 200, data will be exported with all fields available in that module.
  • Maximum value of "page" key in the export request body is 500.

Criteria Limits


  • Maximum number of criteria that can be used in a query is 25.
  • 'in' & 'not_in' comparisons can accept upto 20 values.

    For example: 'Lead Status' - 'in' - 'Cold,Warm,Hot,Junk,Contacted,Not Contacted,....(20 values)'
  • Criteria on Multiline text fields is not supported.

Download Bulk Read result

Purpose

To download the result of a bulk read job. The result is available in a CSV file compressed into a ZIP file, with the file name as "{job_id}.zip".

Extract the zip file to get a CSV file, with the file name as "{job_id}.csv".

Request URL

https://www.zohoapis.com/crm/bulk/v2/read/{job_id}/result

job_id - Specify the unique id of a bulk read job.

Scope

scope=ZohoCRM.bulk.read
(and)
scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, tasks, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, custom, notes. ALL - Full access to related records
READ - get bulk read job

Request Method

GET

Curl
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/bulk/v2/read/1000000031045/result"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Note:

  • Only 10 requests for download is allowed for 1 minute interval. Crossing the limit may result in an error (http code :429) returned to user as response. To know more about the Bulk API limits, go here.

Sample result

Note:

  • The above image shows a sample CSV file which contains the exported records.
  • If the "fields" attribute in the query JSON is left empty, all the fields available in CRM are listed in the CSV file. In case you need only specific fields, like in the above image, please specify the fields for export.
  • The "id" column is added by default in the CSV file, and it contains the id of the exported record's.
  • Lookup fields in the CSV file do not contain the name of the lookup. Only the "id" of the lookup is mentioned. For instance, in the above image, the "Created_By" column contains only the id of the user who created the record.
  • The "Data/Time" fields in the CSV file are given in the ISO8601 format.

Layouts

Purpose

To get the layouts associated with the particular module.

Request URL

https://www.zohoapis.com/crm/v2/settings/layouts

Scope

scope=ZohoCRM.settings.layouts.read
(or)
scope=ZohoCRM.settings.layouts.all
(or)
scope=ZohoCRM.settings.all

Request Method

GET

Parameters

Parameter Name Data Type Description
module (mandatory) String Specify the API name of the required module. For example, Leads, Contacts, Accounts, Deals, and so on.

Possible Errors

HTTP Status Error Code Message Reason
400 INVALID_MODULE The module name given seems to be invalid Invalid module name or no tab permission, or the module could have been removed from the organized module
400 INVALID_MODULE The given module is not supported in API The modules such as Documents and Projects are not supproted in the current API. (This error will not be shown, once these modules are been supported.)
Curl Java PHP Python C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/settings/layouts?module=Leads"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

ZCRMModule module = ZCRMModule.getInstance("Products"); // module apiname

BulkAPIResponse response = module.getLayouts();

List<ZCRMLayout> layouts = (List<ZCRMLayout>) response.getData();

Copy sample request

Sample Request:

$zcrmModuleIns = ZCRMModule::getInstance("Products");
$apiResponse= $zcrmModuleIns->getAllLayouts();
$layouts =$apiResponse->getData(); //Here $layouts is an array of ZCRMLayout instances

Copy sample request

Sample Request:

zclient, api_obj = ZohoCRMClient.get_client_objects(conf_file_location)
accounts_obj = api_obj.load_crm_module(“Accounts”)
layouts = accounts_obj.get_layouts #this is of the form Array<ZCRMLayout>

Copy sample request

Sample Request:

def get_all_layouts(self):

  try:

    module_ins=ZCRMModule.get_instance('Accounts') #module API Name

    resp=module_ins.get_all_layouts()

    print resp.status_code

    layout_ins_arr=resp.data

    for layout_ins in layout_ins_arr:

      print "\n\n:::LAYOUT DETAILS:::"

      print layout_ins.name

      print layout_ins.id

      print layout_ins.created_time

      print layout_ins.modified_time

      print layout_ins.convert_mapping

      print layout_ins.is_visible

      print layout_ins.modified_by.id

      profiles=layout_ins.accessible_profiles

      if profiles is not None:

        for profile in profiles:

          print "\n\n"

          print profile.id

          print profile.name

          print profile.is_default

      print layout_ins.created_by

      sections= layout_ins.sections

      if sections is not None:

        print "\n:::SECTION DETAILS:::"

        for secton in sections:

          print secton.name

          print secton.display_name

          print secton.column_count

          print secton.sequence_number

          fields=secton.fields

          if fields is not None:

            print "\n:::FIELD DETAILS:::"

            for field_ins in fields:

              print field_ins.api_name

              print field_ins.id

              print field_ins.is_custom_field

              print field_ins.lookup_field

              print field_ins.convert_mapping

              print field_ins.is_visible

              print field_ins.field_label

              print field_ins.length

              print field_ins.created_source

              print field_ins.default_value

              print field_ins.is_mandatory

              print field_ins.sequence_number

              print field_ins.is_read_only

              print field_ins.is_unique_field

              print field_ins.is_case_sensitive

              print field_ins.data_type

              print field_ins.is_formula_field

              print field_ins.is_currency_field

              print field_ins.picklist_values

              print field_ins.is_auto_number

              print field_ins.is_business_card_supported

              print field_ins.field_layout_permissions

              print field_ins.decimal_place

              print field_ins.precision

              print field_ins.rounding_option

              print field_ins.formula_return_type

              print field_ins.formula_expression

              print field_ins.prefix

              print field_ins.suffix

              print field_ins.start_number

              print field_ins.json_type

  except ZCRMException as ex:

    print ex.status_code

    print ex.error_message

    print ex.error_code

    print ex.error_details

    print ex.error_content

Copy sample request

Sample Request:

ZCRMModule moduleIns = ZCRMModule.GetInstance("Leads"); //module api name
BulkAPIResponse<ZCRMLayout> response = moduleIns.GetAllLayouts();
List<ZCRMLayout> layouts = response.BulkData; //layouts - list of ZCRMLayout instance

Copy sample response

Sample Response:

Single Layout

Purpose

To get the layout details of a particular module

Request URL

https://www.zohoapis.com/crm/v2/settings/layouts/{layout_id}

layout_id - Specify the unique id of the layout.

Scope

scope=ZohoCRM.settings.layouts.read
(or)
scope=ZohoCRM.settings.layouts.all
(or)
scope=ZohoCRM.settings.all

Request Method

GET

Parameters

Parameter Name Data Type Description
module (mandatory) String Specify the API name of the required module. For example, Leads, Contacts, Accounts, Deals, and so on.

Possible Errors

HTTP Status Error Code Message Reason
400 INVALID_MODULE The module name given seems to be invalid Invalid module name or no tab permission, or the module could have been removed from the organized module
400 INVALID_MODULE The given module is not supported in API The modules such as Documents and Projects are not supproted in the current API. (This error will not be shown, once these modules are been supported.)
Curl Java PHP Python C#
Copy sample request

Sample Request:

"https://www.zohoapis.com/crm/v2/settings/layouts/4108880000425045?module=Deals"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

ZCRMModule module = ZCRMModule.getInstance("Products");// module apiname

APIResponse response = module.getLayoutDetails(12345690l);//layoutID

ZCRMLayout layout = (ZCRMLayout) response.getData();

Copy sample request

Sample Request:

$zcrmModuleIns = ZCRMModule::getInstance("Products");
$apiResponse= $zcrmModuleIns->getLayoutDetails(410405000001021001);//LayoutId
$layout =$apiResponse->getData(); // Here $layout is ZCRMLayout instance

Copy sample request

Sample Request:

zclient, api_obj = get_client_objects(conf_file_location)[0]
accounts_obj = api_obj.load_crm_module(“Accounts”)
layout_id = “1234567890”
layout_obj = accounts_obj.get_layout(layout_id)

Copy sample request

Sample Request:

ZCRMModule moduleIns = ZCRMModule.GetInstance("Leads"); //module api name
APIResponse response = moduleIns.GetLayoutDetails(33721640000014); //33721640000014 is layout id
ZCRMLayout layout = (ZCRMLayout)response.Data;

Copy sample request

Sample Request:

def get_layout(self):

  try:

    module_ins=ZCRMModule.get_instance('Accounts') #module API Name

    resp=module_ins.get_layout(440872000000254001) #LAYOUT ID

    print resp.status_code

    layout_ins_arr=[resp.data]

    for layout_ins in layout_ins_arr:

      print "\n\n:::LAYOUT DETAILS:::"

      print layout_ins.name

      print layout_ins.id

      print layout_ins.created_time

      print layout_ins.modified_time

      print layout_ins.convert_mapping

      print layout_ins.is_visible

      print layout_ins.modified_by.id

      profiles=layout_ins.accessible_profiles

      if profiles is not None:

        for profile in profiles:

          print "\n\n"

          print profile.id

          print profile.name

          print profile.is_default

      print layout_ins.created_by.id

      sections= layout_ins.sections

      if sections is not None:

        print "\n:::SECTION DETAILS:::"

        for secton in sections:

          print secton.name

          print secton.display_name

          print secton.column_count

          print secton.sequence_number

          fields=secton.fields

          if fields is not None:

            print "\n:::FIELD DETAILS:::"

            for field_ins in fields:

              print field_ins.api_name

              print field_ins.id

              print field_ins.is_custom_field

              print field_ins.lookup_field

              print field_ins.convert_mapping

              print field_ins.is_visible

              print field_ins.field_label

              print field_ins.length

              print field_ins.created_source

              print field_ins.default_value

              print field_ins.is_mandatory

              print field_ins.sequence_number

              print field_ins.is_read_only

              print field_ins.is_unique_field

              print field_ins.is_case_sensitive

              print field_ins.data_type

              print field_ins.is_formula_field

              print field_ins.is_currency_field

              picklist_values=field_ins.picklist_values

              if picklist_values is not None:

                for picklist_value_ins in picklist_values:

                  print picklist_value_ins.display_value

                  print picklist_value_ins.actual_value

                  print picklist_value_ins.sequence_number

                  print picklist_value_ins.maps

              print field_ins.is_auto_number

              print field_ins.is_business_card_supported

              print field_ins.field_layout_permissions

              print field_ins.decimal_place

              print field_ins.precision

              print field_ins.rounding_option

              print field_ins.formula_return_type

              print field_ins.formula_expression

              print field_ins.prefix

              print field_ins.suffix

              print field_ins.start_number

              print field_ins.json_type

  except ZCRMException as ex:

    print ex.status_code

    print ex.error_message

    print ex.error_code

    print ex.error_details

    print ex.error_content

Copy sample response

Sample Response:

Custom Views

Purpose

To get the custom views data of a particular module. You need to specify the module name in your API request to which the custom view data has to be retrieved.

Request URL

https://www.zohoapis.com/crm/v2/settings/custom_views

Scope

scope=ZohoCRM.settings.custom_views.read
(or)
scope=ZohoCRM.settings.custom_views.all
(or)
scope=ZohoCRM.settings.all

Request Method

GET

Parameters

Parameter Name Data Type Description
module (mandatory) String Specify the API name of the required module. For example, Leads, Contacts, Accounts, Deals, and so on.

Possible Errors

HTTP Status Error Code Message Reason
400 INVALID_MODULE The module name given seems to be invalid Invalid module name or no tab permission, or the module could have been removed from the organized module
400 INVALID_MODULE The given module is not supported in API The modules such as Documents and Projects are not supproted in the current API. (This error will not be shown, once these modules are been supported.)
Curl Java PHP Python C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/settings/custom_views?module=Leads"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

ZCRMModule module = ZCRMModule.getInstance("Contacts");// module api name

BulkAPIResponse response = module.getCustomViews();

List<ZCRMCustomView> customViews = (List<ZCRMCustomView>)

response.getData();

Copy sample request

Sample Request:

$zcrmModuleIns = ZCRMModule::getInstance("Products");
$apiResponse=$zcrmModuleIns->getAllCustomViews();
$zcrmCustomViews=$apiResponse->getData(); // Here $zcrmCustomViews is an array of ZCRMCustomView instances

Copy sample request

Sample Request:

zclient, api_obj = ZohoCRMClient.get_client_objects(conf_file_location)
accounts_obj = api_obj.load_crm_module(“Accounts”)
custom_views = accounts_obj.get_custom_views

Copy sample request

Sample Request:

ZCRMModule moduleIns = ZCRMModule.GetInstance("Leads"); //module api name
BulkAPIResponse<ZCRMCustomView> response = moduleIns.GetAllCustomViews();
List<ZCRMCustomView> customViews = response.BulkData; //customViews - list of ZCRMCustomView instance

Copy sample request

Sample Request:

def get_all_customviews(self):

  try:

    module_ins=ZCRMModule.get_instance('Accounts') #module API Name

    resp=module_ins.get_all_customviews()

    print resp.status_code

    cv_ins_arr=resp.data

    for customview_ins in cv_ins_arr:

      print "\n\n:::CUSTOM VIEW DETAILS:::"

      print customview_ins.id

      print customview_ins.module_api_name

      print customview_ins.display_value

      print customview_ins.is_default

      print customview_ins.name

      print customview_ins.system_name

      print customview_ins.sort_by

      print customview_ins.category

      fields=customview_ins.fields

      print "\n:::FIELDS:::"

      for field in fields:

        print field

      print customview_ins.favorite

      print customview_ins.sort_order

      cv_criteria= customview_ins.criteria

      if cv_criteria is not None:

        print "\n\n :::CRITERIA::::"

        for criteria_ins in cv_criteria:

          print criteria_ins.field

          print criteria_ins.comparator

          print criteria_ins.value

        print customview_ins.criteria_pattern

   categories=customview_ins.categories

        print "\n\n :::CATEGORIES::::"

        if categories is not None:

          for category in categories:

            print category.actual_value

            print category.display_value

        print customview_ins.is_off_line

  except ZCRMException as ex:

    print ex.status_code

    print ex.error_message

    print ex.error_code

    print ex.error_details

    print ex.error_content

Copy sample response

Sample Response:

Single Custom View

Purpose

To get the data of any specific custom view of the module. Specify the custom view id of the module in your API request URL, so that the data related to that particular custom view will be retrieved.

Request URL

https://www.zohoapis.com/crm/v2/settings/custom_views/{custom_view_id}

custom_view_id - Specify the unique id of the custom view.

Scope

scope=ZohoCRM.settings.custom_views.read
(or)
scope=ZohoCRM.settings.custom_views.all
(or)
scope=ZohoCRM.settings.all

Request Method

GET

Parameters

Parameter Name Data Type Description
module (mandatory) String Specify the API name of the required module. For example, Leads, Contacts, Accounts, Deals, and so on.

Possible Errors

HTTP Status Error Code Message Reason
400 INVALID_MODULE The module name given seems to be invalid Invalid module name or no tab permission, or the module could have been removed from the organized module
400 INVALID_MODULE The given module is not supported in API The modules such as Documents and Projects are not supproted in the current API. (This error will not be shown, once these modules are been supported.)
Curl Java PHP Python C#
Copy sample request

Sample Request:

"https://www.zohoapis.com/crm/v2/settings/custom_views/4108880000066613?module=Leads"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

ZCRMModule module = ZCRMModule.getInstance("Contacts");

APIResponse response = module.getCustomView(98658369836l);

ZCRMCustomView customView = (ZCRMCustomView) response.getData();

Copy sample request

Sample Request:

$zcrmModuleIns = ZCRMModule::getInstance("Products");
$apiResponse=$zcrmModuleIns->getCustomView(410405000005108011);//custom view ID
$zcrmCustomView=$apiResponse->getData(); // Here $zcrmCustomView is an instance of ZCRMCustomView

Copy sample request

Sample Request:

zclient, api_obj = ZohoCRMClient.get_client_objects(conf_file_location)
accounts_obj = api_obj.load_crm_module(“Accounts”)
custom_views = accounts_obj.get_custom_views
custom_view_id = “1234567890”
custom_views.each do |cv_id, cv_hash|
if cv_id == custom_view_id then
return cv_hash #Hash containing corresponding custom view data
end
end

Copy sample request

Sample Request:

ZCRMModule moduleIns = ZCRMModule.GetInstance("Leads"); //module api name
APIResponse response = moduleIns.GetCustomView(33721640000006); //33721640000006 is customView id
ZCRMCustomView customView = (ZCRMCustomView)response.Data;

Copy sample request

Sample Request:

def get_customview(self):

  try:

    module_ins=ZCRMModule.get_instance('Accounts') #module API Name

    resp=module_ins.get_customview(440872000000091517) #CUSTOM VIEW ID

    print resp.status_code

    cv_ins_arr=[resp.data]

    for customview_ins in cv_ins_arr:

      print "\n\n:::CUSTOM VIEW DETAILS:::"

      print customview_ins.id

      print customview_ins.module_api_name

      print customview_ins.display_value

      print customview_ins.is_default

      print customview_ins.name

      print customview_ins.system_name

      print customview_ins.sort_by

      print customview_ins.category

      fields=customview_ins.fields

      print "\n:::FIELDS:::"

      for field in fields:

        print field

      print customview_ins.favorite

      print customview_ins.sort_order

      cv_criteria= customview_ins.criteria

      if cv_criteria is not None:

        print "\n\n :::CRITERIA::::"

        for criteria_ins in cv_criteria:

          print criteria_ins.field

          print criteria_ins.comparator

          print criteria_ins.value

        print customview_ins.criteria_pattern

      categories=customview_ins.categories

      print "\n\n :::CATEGORIES::::"

      if categories is not None:

        for category in categories:

          print category.actual_value

          print category.display_value

      print customview_ins.is_off_line

  except ZCRMException as ex:

    print ex.status_code

    print ex.error_message

    print ex.error_code

    print ex.error_details

    print ex.error_content


Copy sample response

Sample Response:

Variables API

A CRM Variable can have unique set of values and can be widely used as merge fields in Email templates, Mail merge templates, and Inventory templates. It can also be used as reusable authentication parameters in APIs.

Get Variables Data

Purpose

To retrieve all the available variables through an API request.

Request URL

https://www.zohoapis.com/crm/v2/settings/variables

Scope

scope=ZohoCRM.settings.variables.{operation_type}

Possible operation types
ALL - Full access to variable data
READ - get variable data

Request Method

GET

Note:

  • Group ID/group API name is mandatory in case of fetching specific variable data.
Curl
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/settings/variables"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

Get All Users

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample response

Sample Response:

Get Single Variable Data

Purpose

To get the details of any specific variable. Specify the unique id of the variable in your API request to get the data for that particular variable group.

Request URL

https://www.zohoapis.com/crm/v2/settings/variables/{variable_id}?group={variable_group_id}

variable_id - Specify the unique id of the variable.

variable_group_id - Specify the unique id of the variable group.

Scope

scope=ZohoCRM.settings.variables.{operation_type}

Possible operation types
ALL - Full access to variable data
READ - get variable data

Request Method

GET

Parameters

Parameter Name Data Type Description
group* Integer/String Specify the unique id/ API name of the group to which the variable belongs to.

Note:

  • Group ID/group API name is mandatory in case of fetching specific variable data. An error will throw up otherwise.
Curl
Copy sample request

Sample Request: Using Variable ID and Group ID

curl "https://www.zohoapis.com/crm/v2/settings/variables/40000000047003?group=40000000047001"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request: Using Variable API Name and Group ID

curl "https://www.zohoapis.com/crm/v2/settings/variables/VariableSix?group=40000000047001"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request: Using Variable ID and Group API Name

curl "https://www.zohoapis.com/crm/v2/settings/variables/40000000047003?group=Group2"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample response

Sample Response: For Variable ID and Group ID

Copy sample response

Sample Response: For Variable API Name and Group ID

Copy sample response

Sample Response: For Variable ID and Group API Name

Get Variable Group Data

Purpose

To get the details of any variable groups. Specify the unique id of the variable in your API request to get the data for that particular variable group.

Request URL

https://www.zohoapis.com/crm/v2/settings/variable_groups/{variable_group_id}

variable_id - Specify the unique id of the variable.

Scope

scope=ZohoCRM.settings.variable_groups.{operation_type}

Possible operation types
ALL - Full access to variable data
READ - get variable data

Request Method

GET

Curl
Copy sample request

Sample Request: Using Variable Group ID

curl "https://www.zohoapis.com/crm/v2/settings/variable_groups/40000000047003"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request: Using Variable Group API Name

curl "https://www.zohoapis.com/crm/v2/settings/variable_groups/Group3"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample response

Sample Response:

Copy sample response

Sample Response:

Create Variables

Purpose

To create a new variable in CRM.

Request URL

https://www.zohoapis.com/crm/v2/settings/variables

Scope

scope=ZohoCRM.settings.variables.{operation_type}

Possible operation types
ALL - Full access to variable data
CREATE - create variable data

Attributes Specifications

Variables can be created by giving a POST request with request body containing the following attributes:

Key Name Type Description Example Mandatory
name Text This is the display name of the variable that is going to be created. It is a "Unique" field. VariableName3 Yes
api_name Text This is the name with which the variable is to be referred in any API request. It is a "Unique" field. MainVariable Yes
type Text This is the data type of the variable. Integer No
variable_group JSON Object This is the group to which the variable should belong to. {"id": 40000000047005} or {"name":"Group2"} Yes
value Depends on the type of the variable. This is the initial value given to the variable. 123 No
description Text A short description of the variable. A short description of the variable. No

Note:

  • Variable data type cannot be changed after it's creation.
  • Variable Groups can be created only when creating Variables.
  • When creating a variable, if the variable group specified exists already, the variable is simply added to the group.
  • If the variable group specified does not exist, a new group is created, to which the variable is added.

Request Method

POST

Curl
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/settings/variables"

-X POST

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample input

Sample Input:

Copy sample response

Sample Response:

Update Variables

Purpose

To update details of a variable in CRM.

Request URL

https://www.zohoapis.com/crm/v2/settings/variables

Scope

scope=ZohoCRM.settings.variables.{operation_type}

Possible operation types
ALL - Full access to variable data
UPDATE - update variable data

Request Method

PUT

Curl
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/settings/variables"

-X PUT

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample input

Sample Input:

Copy sample response

Sample Response:

Update Specific Variables

Purpose

To update details of a specific variable in CRM.

Request URL

https://www.zohoapis.com/crm/v2/settings/variables/{variable_id (or) variable_api_name}

variable_id - Specify the unique id of the variable.

Scope

scope=ZohoCRM.settings.variables.{operation_type}

Possible operation types
ALL - Full access to variable data
UPDATE - update variable data

Request Method

PUT

Curl
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/settings/variables/40000000047010"

(or)

curl "https://www.zohoapis.com/crm/v2/settings/variables/Variable444"

-X PUT

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample input

Sample Input:

Copy sample response

Sample Response:

Delete Variables

Purpose

To delete details of a specific variable in CRM.

Request URL

https://www.zohoapis.com/crm/v2/settings/variables/{variable_id}

variable_id - Specify the unique id of the variable.

Scope

scope=ZohoCRM.settings.variables.{operation_type}

Possible operation types
ALL - Full access to variable data
DELETE - delete variable data

Request Method

DELETE

Curl
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/settings/variables/40000000047010"

-X DELETE

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample response

Sample Response:

Delete Multiple Variables

Purpose

To delete details of multiple variables in CRM simultaneously.

Request URL

https://www.zohoapis.com/crm/v2/settings/variables?ids={variable_id1, variable_id2, variable_id3}

variable_id - Specify the unique id of the variable.

Scope

scope=ZohoCRM.settings.variables.{operation_type}

Possible operation types
ALL - Full access to variable data
DELETE - delete variable data

Parameters

Parameter Name Data Type Description
ids* Integer Specify the unique ids of the variables.

Request Method

DELETE

Curl
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/settings/variables?ids=40000000047007,40000000047009,40000000047010"

-X DELETE

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample response

Sample Response:

Subscription APIs

This API is used to grant subscription for instant notifications on actions(create, edit and delete) performed on Zoho CRM data. Once the user subscribes for the instant sync of any module, whenever any action performed on the records of that module, a notification of it is sent to the URL provided by user.

Subscribe for Notifications

Purpose

To request subscription for instant notifications on actions performed on a module or a record.

Request URL

https://www.zohoapis.com/crm/v2/actions/watch

Scope

scope=ZohoCRM.notifications.{operation_type}

Possible operation types
ALL - Full access to notification data
CREATE - create instant notification's subscription
WRITE - write instant notification's subscription

Input JSON Keys

Keys Value Purpose
token (optional) String (Maximum of 50 Character length) To ensure that the notification is sent from Zoho CRM, by sending back the given value in notification URL body. By using this value, user can validate the notifications.
notify_url (mandatory) URL to be notified (POST request) Whenever any action gets triggered, the notification will be sent through notify url.
channel_id (mandatory) String (long) The given value is sent back in notification URL body to make sure that notification is for a particular channel.
channel_expiry String (ISO Date time) To set the expiry time for instant notifications. Maximum of only one day from subscribing time. If it is not specified or set for more than a day, the default expiry time is for one hour.
events (mandatory) JSONArray
["{module_api_name}.{operation}","{module_api_name}.{operation}"]
Ex: ["Leads.create","Sales_Orders.edit","Contacts.delete"]. Possible operation types - create, delete, edit, all
To subscribe based on particular operations of selected modules.

Request Method

POST

Curl
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/actions/watch"

-X POST

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

-d "@inputData.json"

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

In the above request, @inputData.json contains the sample input data.

Copy sample input

Sample Input:

Copy sample response

Sample Response: For new subscription

To get notification on a URL

On trigger of any subscribed event of a module, a notification from Zoho CRM will be sent to user through notify URL.

Copy sample input

Sample Request Body of Notification

Get subscription details

Purpose

To get the details of the subscription made by the user.

Request URL

https://www.zohoapis.com/crm/v2/actions/watch

Scope

scope=ZohoCRM.notifications.{operation_type}

Possible operation types
ALL - Full access to notification data
READ - get notification subscription details

Request Method

GET

Parameters

Parameter Name Data Type Description
page (optional) Integer To get the list of records from the respective pages. Default value for page is 1.
per_page (optional) Integer To get the list of records available per page. Default value for per page is 200.
channel_id (mandatory) Integer Specify the unique id of the notification channel
module String Specify the API name of the module for which the notification is subscribed.

Note:

  • The page and per_page parameter is used to fetch records according to their position in the CRM. Let's assume that the user has to fetch 400 records. The maximum number of records that one can get for an API call is 200. So, for records above the 200th position, they cannot be fetched. By using the page (1, 2, 3 and 4) and per_page (100) parameter, the user can fetch all 400 records using 4 API calls.
Curl
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/actions/watch?page=1&per_page=200"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request: Get subscriptions related to a specific Channel

curl "https://www.zohoapis.com/crm/v2/actions/watch?channel_id=1000000068001"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request: For subscriptions related to a module and a channel

curl "https://www.zohoapis.com/crm/v2/actions/watch?channel_id=1000000068001&module={module_api_name}"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample response

Sample Response:

Copy sample response

Sample Response: Get subscriptions related to a specific Channel

Copy sample response

Sample Response: For subscriptions related to a module and a channel

Update Subscription details

Purpose

To update the details of the subscription made by a user. All the provided details would be persisted and rest of the details would be removed.

Request URL

https://www.zohoapis.com/crm/v2/actions/watch

Scope

scope=ZohoCRM.notifications.{operation_type}

Possible operation types
ALL - Full access to notification data
WRITE - edit notification details
UPDATE - update notification details

Input JSON Keys

Keys Value Purpose
token String (Maximum of 50 Character length) To ensure that the notification is sent from Zoho CRM, by sending back the given value in notification URL body. By using this value, user can validate the notifications.
notify_url URL to be notified (POST Request) Whenever any action gets triggered, the notification will be sent through notify url.
channel_id String (long) The given value is sent back in notification URL body to make sure that notification is for a particular channel.
channel_expiry String (ISO Date time) To set the expiry time for instant notifications. Maximum of only one day from subscribing time. If it is not specified or set for more than a day, the default expiry time is for one hour.
events JSONArray
["{module_api_name}.{operation}","{module_api_name}.{operation}"]
Ex: ["Leads.create","Sales_Orders.edit","Contacts.delete"]. Possible operation types - create, delete, edit, all
To subscribe based on particular operations of selected modules.

Request Method

PUT

Curl
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/actions/watch"

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

-X PUT

-d "@inputData.json"

In the above request, @inputData.json contains the sample input data.

Copy sample input

Sample Input:

Copy sample response

Sample Response:

Update Specific information of a Notification

Purpose

To update only specific details of a specific subscription made by the user. All the provided details would be persisted and rest of the details will not be removed.

Request URL

https://www.zohoapis.com/crm/v2/actions/watch

Scope

scope=ZohoCRM.notifications.{operation_type}

Possible operation types
ALL - Full access to notification data
WRITE - edit notification details
UPDATE - update notification details

Input JSON Keys

Keys Value Purpose
token String (Maximum of 50 Character length) To ensure that the notification is sent from Zoho CRM, by sending back the given value in notification URL body. By using this value, user can validate the notifications.
notify_url URL to be notified (POST Request) Whenever any action gets triggered, the notification will be sent through notify url.
channel_id (mandatory) String (long) The given value is sent back in notification URL body to make sure that notification is for a particular channel.
channel_expiry String (ISO Date time) To set the expiry time for instant notifications. Maximum of only one day from subscribing time. If it is not specified or set for more than a day, the default expiry time is for one hour.
events JSONArray
["{module_api_name}.{operation}","{module_api_name}.{operation}"]
Ex: ["Leads.create","Sales_Orders.edit","Contacts.delete"]. Possible operation types - create, delete, edit, all
To subscribe based on particular operations of selected modules.

Request Method

PATCH

Curl
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/actions/watch"

-X PATCH

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

-d "@inputData.json"

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

In the above request, @inputData.json contains the sample input data.

Copy sample input

Sample Input:

Copy sample response

Sample Response:

Unsubscribe to Notifications

Purpose

To stop all the instant notifications configured by the user.

Request URL

https://www.zohoapis.com/crm/v2/actions/watch

Scope

scope=ZohoCRM.notifications.{operation_type}

Possible operation types
ALL - Full access to notification data
WRITE - edit notification subscription details
DELETE - delete notification subscription details

Request Method

DELETE

Parameters

Parameter Name Data Type Description
channel_ids (mandatory) Integer Specify the unique ids of the notification channel to be unsubscribed, comma separated.
Curl
Copy sample request

Sample Request:

https://www.zohoapis.com/crm/v2/actions/watch?channel_ids=1000000068003,1000000068001,1000000068002"

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

-X DELETE

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample response

Sample Response:

Unsubscribe to specific Notifications

Purpose

To unsubscribe to particular notifications.

Request URL

https://www.zohoapis.com/crm/v2/actions/watch

Scope

scope=ZohoCRM.notifications.{operation_type}

Possible operation types
ALL - Full access to notification data
WRITE - edit notification subscription details
UPDATE - update notification subscription details

Request Method

PATCH

Curl
Copy sample request

Sample Request:

https://www.zohoapis.com/crm/v2/actions/watch"

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

-X PATCH

-d "@inputData.json"

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

In the above request, @inputData.json contains the sample input data.

Copy sample input

Sample Input:

Note:

  • "_delete_events" key is mandatory to unsubscribe specific notifications. If "_delete_events": false or "_delete_events" key is not given in the input, subscription will not be cancelled.
  • channel_id and events key is also mandatory.
Copy sample response

Sample Response:

Record Level Sharing APIs

This API is used to share records with users, get the sharing details, summary or revoke the sharing permissions of a record. Zoho CRM provides different levels of data sharing, one being the record-level sharing where users can share individual records from any module with other users in the organization. You can share records with related lists or without them.

Get Sharing Details of a Record

Purpose

To get the sharing details of a record along with the sharing permission provided.

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}/{record_id}/actions/share

module_api_name - The api name of the module.

record_id - Specify the unique id of a record.

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, cases, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices and custom. ALL - Full access
READ - view sharing permissions for a record

Request Method

GET

Curl
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Leads/2883756000000135187/actions/share"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample response

Sample Response: For new subscription

Get Sharing Summary of a Record

Purpose

To get a sharing summary of a record.

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}/{record_id}/actions/share?view=summary

module_api_name - The api name of the module.

record_id - Specify the unique id of a record.

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, cases, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices and custom. ALL - Full access
READ - view sharing permissions for a record

Request Method

GET

Parameters

Parameter Name Data Type Description
view - To display the shared record details similar to the Summary in the UI. Can be either "manage" or "summary".
sharedTo (optional) Integer Enter the User ID of the User to whom the record was shared to. It is used by the shared users, to know about who shared the records with him.
Curl
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Leads/2883756000000135187/actions/share?view=summary"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request: To view the User who shared the record:

curl "https://www.zohoapis.com/crm/v2/Leads/2883756000000135187/actions/share?view=summary&sharedTo=100000000000032641"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample response

Sample Response:

Copy sample response

Sample Response: To view the User who shared the record:

Get Shared User details

Purpose

To get the sharing details of a record along with the shared User information and the list of Users to whom the record can be shared.

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}/{record_id}/actions/share?view=manage

module_api_name - The api name of the module.

record_id - Specify the unique id of a record.

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, cases, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices and custom. ALL - Full access
READ - view sharing permissions for a record

Request Method

GET

Parameters

Parameter Name Data Type Description
view - To also show the list of users to whom the record can be shared. Can be either "manage" or "summary".
Curl
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Leads/2883756000000135187/actions/share?view=manage"

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

-X GET

Copy sample response

Sample Response:

Revoke Sharing permissions

Purpose

To revoke the sharing permissions for a record.

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}/{record_id}/actions/share

module_api_name - The api name of the module.

record_id - Specify the unique id of a record.

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, cases, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices and custom. ALL - Full access
DELETE - remove sharing permissions for a record

Request Method

DELETE

Curl
Copy sample request

Sample Request:

https://www.zohoapis.com/crm/v2/Leads/2883756000000135187/actions/share"

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

-X DELETE

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample response

Sample Response:

Organization API

Zoho CRM and it's APIs are used by Admins for management of their company. The Organization API allows access for third-party users to view information about the client's company. The information is quite secure, as administrators can enable read-only, create, or edit access to developers based on their requirements.

Get Organization Data

Purpose

To get the organization data

Request URL

https://www.zohoapis.com/crm/v2/org

Scope

scope=ZohoCRM.org.{operation_type}

Possible operation types
ALL - Full access to organization data
READ - get organization data

Request Method

GET

Curl Java PHP Python C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/org"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

ZCRMRestClient client = ZCRMRestClient.getInstance();

APIResponse response = client.getOrganizationDetails();

ZCRMOrganization org = (ZCRMOrganization) response.getData();

Copy sample request

Sample Request:

try{
$restIns=ZCRMRestClient::getInstance();
$res=$restIns->getOrganizationDetails();
$orgIns=$res->getData();
echo $orgIns->getCompanyName();
echo $orgIns->getOrgId();
echo $orgIns->getCountryCode();
echo $orgIns->getCountry();
echo $orgIns->getCurrencyLocale();
echo $orgIns->getFax();
echo $orgIns->getAlias();
echo $orgIns->getDescription();
echo $orgIns->getStreet();
echo $orgIns->getCity();
echo $orgIns->getState();
echo $orgIns->getZgid();
echo $orgIns->getWebSite();
echo $orgIns->getPrimaryEmail();
echo $orgIns->getPrimaryZuid();
echo $orgIns->getIsoCode();
echo $orgIns->getPhone();
echo $orgIns->getMobile();
echo $orgIns->getEmployeeCount();
echo $orgIns->getCurrencySymbol();
echo $orgIns->getTimeZone();
echo $orgIns->getMcStatus();
echo $orgIns->isGappsEnabled();
echo $orgIns->isPaidAccount();
echo $orgIns->getPaidExpiry();
echo $orgIns->getPaidType();
echo $orgIns->getTrialType();
echo $orgIns->getTrialExpiry();
echo $orgIns->getZipCode();
}
catch (ZCRMException $e)
{
echo $e->getCode();
echo $e->getExceptionDetails();
echo $e->getMessage();
echo $e->getTraceAsString();
}

Copy sample request

Sample Request:

ZCRMRestClient restClient = ZCRMRestClient.GetInstance();
APIResponse response = restClient.GetOrganizationDetails();
ZCRMOrganization organization = (ZCRMOrganization)response.Data;

Copy sample request

Sample Request:

def get_org_details(self):

  try:

    resp=ZCRMRestClient.get_instance().get_organization_details()

      print resp.status_code

org_ins=resp.data

      print org_ins.company_name

      print org_ins.org_id

      print org_ins.alias

      print org_ins.primary_zuid

      print org_ins.zgid

      print org_ins.primary_email

      print org_ins.website

      print org_ins.mobile

      print org_ins.phone

      print org_ins.employee_count

      print org_ins.description

      print org_ins.time_zone

      print org_ins.iso_code

      print org_ins.currency_locale

      print org_ins.currency_symbol

      print org_ins.street

      print org_ins.state

      print org_ins.city

      print org_ins.country

      print org_ins.zip_code

      print org_ins.country_code

      print org_ins.fax

      print org_ins.mc_status

      print org_ins.is_gapps_enabled

      print org_ins.paid_expiry

      print org_ins.trial_type

      print org_ins.trial_expiry

      print org_ins.is_paid_account

      print org_ins.paid_type

  except ZCRMException as ex:

      print ex.status_code

      print ex.error_message

      print ex.error_code

      print ex.error_details

      print ex.error_content

Copy sample response

Sample Response:

Attributes:

  • "iso_code" : string representing base currency of the current org
  • "mc_status" : Checks if Multi-Currency is enabled or disabled.

Upload Organization photo

Each organization has a unique logo or image. You can upload and update the organization photo using this API.

Purpose

To upload the brand logo or image of the organization

Request URL

https://www.zohoapis.com/crm/v2/org/photo

Scope

scope=ZohoCRM.org.{operation_type}

Possible operation types
ALL - Full access to organization data
CREATE - to upload organization photo
WRITE - sedit organization data

Request Method

GET

Curl
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/org/photo"

-X POST

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

-F "file=@img1.png"

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample response

Sample Response:

Record APIs

A record is an entity which stores all the combined information of a particular contact or company, which is acquired from various sources. The information may be acquired from a web-form or from social media services or advertisements, etc. The records API allows the user to get, create, update, delete or search records.

Get list of records

Purpose

To get the list of available records from a module

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}

module_api_name - The api name of the module.

Scope

scope=ZohoCRM.modules.all
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, tasks, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, custom, notes, approvals, dashboards, search and activities. ALL - Full access to record
READ - get records from a module

Request Method

GET

Parameters

Parameter Name Data Type Description Possible Values
fields (optional) String To list all the module records with respect to fields Multiple field API names, comma separated. For example: Last_Name,Email
sort_order (optional) String To sort the available list of records in either ascending or descending order asc - ascending order
desc - descending order
sort_by (optional) String To sort the available list of records based on given field Field API name
Example: Email
converted (optional) String To get the list of converted records. Default value is False. true - get only converted records
false - get only non-converted records
both - get all records
approved (optional) String To get the list of approved records. Default value is True. true - get only approved records
false - get only records which are not approved
both - get all records
page (optional) Integer To get the list of records from the respective pages. Default value for page is 1. Positive Integer values only
per_page (optional) Integer To get the list of records available per page. Default value for per page is 200. Positive Integer values only
cvid (optional) Integer To get the list of records based on custom views {custom_view_id}

Note:

  • sort_order applies to given sort_by field.
  • If sort_by field is not provided, then it applies to the system defined field.
  • The page and per_page parameter is used to fetch records according to their position in the CRM. Let's assume that the user has to fetch 400 records. The maximum number of records that one can get for an API call is 200. So, for records above the 200th position, they cannot be fetched. By using the page (1, 2, 3 and 4) and per_page (100) parameter, the user can fetch all 400 records using 4 API calls.

Request Headers

Header Name Data Type Description Example
If-Modified-Since (optional) DateTime(ISO 8601 format) To get the list of recently modifed records 2019-07-25T15:26:49+05:30

Possible Errors

HTTP Status Error Code Message Reason
400 INVALID_MODULE The module name given seems to be invalid Invalid module name or no tab permission, or the module could have been removed from the organized module
400 INVALID_MODULE The given module is not supported in API The modules such as Documents and Projects are not supproted in the current API. (This error will not be shown, once these modules are been supported.)
Curl Java PHP Python Functions C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Leads"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

ZCRMModule module = ZCRMModule.getInstance("Products");

BulkAPIResponse response = module.getRecords(425476547854l, "Company",

CommonUtil.SortOrder.asc, 1, 4);// get Records with cvID, sortField,

sortOrder, startIndex and endIndex.

List<ZCRMRecord> records = (List<ZCRMRecord>)response.getData();

Copy sample request

Sample Request:

$zcrmModuleIns = ZCRMModule::getInstance("Contacts");
$bulkAPIResponse=$zcrmModuleIns->getRecords();
$recordsArray = $bulkAPIResponse->getData(); // $recordsArray - array of ZCRMRecord instances

Copy sample request

Sample Request:

ZCRMModule moduleIns = ZCRMModule.GetInstance("Leads"); //module api name
List<string> fields = new List<string> {"Last_Name","Company", "Email","id" }; //field api name
BulkAPIResponse<ZCRMRecord> response = moduleIns.GetRecords(3372164000000087503, "Company",CommonUtil.SortOrder.asc, 1, 4, fields);// get Records with cvId, sortByField, sortOrder, startIndex, endIndex and fieldApiNamelist.
List<ZCRMRecord> records = response.BulkData; //records - list of ZCRMRecord instance

Copy sample request

Sample Request:

def get_records(self):

  try:

    module_ins=ZCRMModule.get_instance('Products') #module API Name

    resp=module_ins.get_records()

    print resp.status_code

    record_ins_arr=resp.data

    for record_ins in record_ins_arr:

      print record_ins.entity_id

      print record_ins.owner.id

      print record_ins.created_by.id

      print record_ins.modified_by.id

      print record_ins.created_time

      print record_ins.modified_time

      product_data=record_ins.field_data

      for key in product_data:

        print key+":"+str(product_data[key])

      print "\n\n"

  except ZCRMException as ex:

    print ex.status_code

    print ex.error_message

    print ex.error_code

    print ex.error_details

    print ex.error_content

Copy sample request

Sample Request Syntax:

zoho.crm.getRecords(<module String>,<page Long>,<perPage Long>,<optionalDataMap Map>,<connectionName String>,<userAccess Boolean>);
mandatory : module

Sample Request:

resp = zoho.crm.getRecords("Leads",5,2,{"converted":"false"});

Copy sample response

Sample Response:

Note:

  • While retrieving multiple records, subform records are not retrieved. Only the records count in a subform is retrieved
  • Subform details can also be fetched using the Records API. Please note that when bulk records are fetched, only the record count in a subform is displayed. To get the record details in a subform, you need to fetch the specific record information in a module.
Load more examples

Sample attributes:

  • The sample for Single Line:

    "Single_Line_1": "This is single line",

  • The sample for Multi Line:

    "Multi_Line_1": "This is the first line \n Now for the second Line",

  • The sample for Email:

    "Email_1": "p.boyle@zylker.com",

  • The sample for Phone:

    "Phone_1": "9900000000",

  • The sample for Picklist:

    "Picklist_1" : "In Progress",

  • The sample for Multi-select picklist:

    "Multi-Select_Picklist" : [
        "{Option_1}",
        "{Option_2}",
        "{Option_3}"

        ],

  • The sample for Date:

    "Date_1": "2017-08-16",

  • The sample for Date/time:

    "Date_Time": "2017-08-16T14:32:23+05:30",

  • The sample for Number:

    "Number_1": 575,

  • The sample for Currency:

    "Currency_1": 250000,

  • The sample for Decimal:

    "Decimal_1": 250000.50,

  • The sample for Percent:

    "Percent_1": 25,

  • The sample for Long Integer:

    "Long_Integer_1": "250000000000000",

  • The sample for Checkbox:

    "Checkbox_1": false,

  • The sample for URL:

    "URL_1": "https://www.zoho.com/crm",

  • The sample for Lookup:

    "Lookup" : {
        "name" : "James"
        "id" : "425248000000104001"
        },

  • The sample for the Record owner:

    "Owner": {
        "name" : "Patricia"
        "id": "425248000000104003"
        },

  • The sample for the Layout:

    "Layout": {
        "name" : "Custom Layout 1"
        "id": "425248000000404433"
        },

  • The sample for Auto Number:

    "Auto_Number_1": "LEAD44N",


    Where LEAD - Prefix, 44 - Assigment Number and N - Suffix.

Insert records

Purpose

To add a new entities to a module

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}

module_api_name - The api name of the module.

Scope

scope=ZohoCRM.modules.all
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, tasks, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, custom, notes. ALL - Full access to record
WRITE - edit records in a module
CREATE - create records in a module

Request Method

POST

Possible Errors

HTTP Status Error Code Message Reason Details Key Values
400 INVALID_MODULE The module name given seems to be invalid Invalid module name or no tab permission, or the module could have been removed from the organized module
400 INVALID_MODULE The given module is not supported in API The modules such as Documents and Projects are not supproted in the current API. (This error will not be shown, once these modules are been supported.)
403 NO_PERMISSION permission denied to create '{modulename}' No permission to insert records
400 MANDATORY_NOT_FOUND Required field not found. If the data key isn't available. {
"api_name": "data"
}
400 INVALID_DATA Invalid Data If the data key has the invalid data type. {
"expected_data_type":
"jsonarray",
"api_name": "data"
},
202 INVALID_DATA (at the record index) Invalid Data If the record passed isn't a JSON object {
"expected_data_type":
"jsonobject",
"index": 0
}
201 MANDATORY_NOT_FOUND Required field not found. If the mandatory fields are not available. {
"api_name":
"Last_Name"
}
202 INVALID_DATA Invalid Data If the datatype is mismatched. {
"expected_data_type":
"double", "api_name":
"Decimal_1"
}

Note:

  • An error is thrown if the field value length is more than the maximum length defined for that field.
  • If an API used inside a Function when the field value length exceeds the limit, then that function receives error response from the API. For ex: If the max length for a "Text field" is defined as 10, then value given for it in API cannot be "12345678901", as it has 11 characters.
Curl Java PHP Python Functions C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Leads"

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

-d "@newlead.json"

-X POST

Copy sample request

Sample Request:

List<ZCRMRecord> records = new ArrayList<>();

ZCRMRecord record1 = new ZCRMRecord("Products"); //module api name

ZCRMUser owner = ZCRMUser.getInstance(12345678l);// user id

record1.setOwner(owner);

record1.setFieldValue("Product_Name", "mass_create1");// field api name with its value

ZCRMRecord record2 = new ZCRMRecord("Products"); //module api name

ZCRMUser owner = ZCRMUser.getInstance(5676875678l);// user id

record2.setOwner(owner);

record2.setFieldValue("Product_Name", "mass_create2");// field api name with its value

records.add(record1);

records.add(record2);

ZCRMModule module = ZCRMModule.getInstance("Products"); //module api name

BulkAPIResponse response = module.createRecords(records);

List<ZCRMRecord> insertedRecords = (List<ZCRMRecord>) response.getData();

List<BulkAPIResponse.EntityResponse> entityResponses =

response.getEntityResponses();// to check the status of the request

String rec1Status = entityResponses.get(0).getStatus();//check status of record1

String rec2Status = entityResponses.get(1).getStatus();//check status of record2

Copy sample request

Sample Request:

$zcrmModuleIns = ZCRMModule::getInstance("Invoices");
$bulkAPIResponse=$zcrmModuleIns->createRecords($recordsArray); // $recordsArray - array of ZCRMRecord instances filled with required data for creation.
$entityResponses = $bulkAPIResponse->getEntityResponses();
foreach($entityResponses as $entityResponse)
{
if("success"==$entityResponse->getStatus())
{
echo "Status:".$entityResponse->getStatus();
echo "Message:".$entityResponse->getMessage();
echo "Code:".$entityResponse->getCode();
$createdRecordInstance=$entityResponse->getData();
echo "EntityID:".$createdRecordInstance->getEntityId();
echo "moduleAPIName:".$createdRecordInstance->getModuleAPIName();
….
}
}
Sample Invoice record instance with filled data
$record=ZCRMRecord::getInstance("Invoices",null);
$record->setFieldValue("Subject","Iphone sale to John");
$record->setFieldValue("Account_Name","410405000001016021");
$productInstance=ZCRMRecord::getInstance("Products",410405000001108011);
$lineItem=ZCRMInventoryLineItem::getInstance($productInstance);
$taxInstance1=ZCRMTax::getInstance("Sales Tax");
$taxInstance1->setPercentage(2);
$taxInstance1->setValue(10);
$lineItem->addLineTax($taxInstance1);
$taxInstance1=ZCRMTax::getInstance("Vat");
$taxInstance1->setPercentage(12);
$taxInstance1->setValue(60);
$lineItem->addLineTax($taxInstance1);
$lineItem->setQuantity(100);
$lineItem->setDiscount(0.5);
$record->addLineItem($lineItem);

Copy sample request

Sample Request:

List<ZCRMRecord> records = new List<ZCRMRecord>();
ZCRMUser owner = null;
ZCRMRecord record1 = new ZCRMRecord("Products"); //module api name
owner = ZCRMUser.GetInstance(3372164008765466021); // user id
record1.Owner = owner;
record1.SetFieldValue("Product_Name", "mass_create1"); // field api name with its value
ZCRMRecord record2 = new ZCRMRecord("Products"); //module api name
owner = ZCRMUser.GetInstance(3372164000008364020); // user id
record2.Owner = owner;
record2.SetFieldValue("Product_Name", "mass_create2"); // field api name with its value
records.Add(record1);
records.Add(record2);
ZCRMModule moduleIns = ZCRMModule.GetInstance("Products"); //module api name
BulkAPIResponse<ZCRMRecord> response = moduleIns.CreateRecords(records); //records - list of ZCRMRecord instances filled with required data for creation.
List<ZCRMRecord> insertedRecords = response.BulkData; //insertedRecords - list of ZCRMRecord instance
List<EntityResponse> entityResponses = response.BulkEntitiesResponse; //entityResponse - list of EntityResponse instance

Copy sample request

Sample Request:

def create_records(self):

  try:

    record_ins_list=list()

    for i in range(0,2):

      record=ZCRMRecord.get_instance('Invoices') #module API Name

      record.set_field_value('Subject', 'Invoice'+str(i))

      record.set_field_value('Account_Name', 'IIIT')

      user=ZCRMUser.get_instance(440872000000175001,'Python Automation User1')

      record.set_field_value('Owner',user)

      line_item=ZCRMInventoryLineItem.get_instance(ZCRMRecord.get_instance("Products",440872000000224005))

      line_item.discount=10

      line_item.list_price=8

      line_item.description='Product Description'

      line_item.quantity=100

      line_item.tax_amount=2.5

      taxIns=ZCRMTax.get_instance("Vat")

      taxIns.percentage=5

      line_item.line_tax.append(taxIns)

      record.add_line_item(line_item)

      record_ins_list.append(record)

    resp=ZCRMModule.get_instance('Invoices').create_records(record_ins_list)

    print resp.status_code

    entity_responses=resp.bulk_entity_response

    for entity_response in entity_responses:

      print entity_response.details

      print entity_response.status

      print entity_response.message

      print entity_response.code

      print entity_response.data.entity_id

      print entity_response.data.created_by.id

      print entity_response.data.created_time

      print entity_response.data.modified_by.id

      print "\n\n"

  except ZCRMException as ex:

    print ex.status_code

    print ex.error_message

    print ex.error_code

    print ex.error_details

    print ex.error_content

Copy sample request

Sample Request Syntax:

zoho.crm.bulkCreate(<module String>,<dataList List>,<optionalDataMap Map>,<connectionName String>,<userAccess Boolean>);
mandatory : module,dataList

Sample Request: Creating Price Book records

resp = zoho.crm.bulkCreate("Price_Books", [{"Owner": {"id": "7000000031553"},"Active": true,"Pricing_Details": [{"to_range": 5,"discount": 0,"from_range": 1},{"to_range": 11,"discount": 1,"from_range": 6},{"to_range": 17,"discount": 2,"from_range": 12},{"to_range": 23,"discount": 3,"from_range": 18},{"to_range": 29,"discount": 4,"from_range": 24}],"Pricing_Model": "Differential","Description": "Design your own layouts that align your business processes precisely. Assign them to profiles appropriately.","Price_Book_Name": "Price_Book_Name oops1"},{"Owner": {"id": "7000000031553"},"Active": true,"Pricing_Details": [{"to_range": 5,"discount": 0,"from_range": 1},{"to_range": 11,"discount": 1,"from_range": 6},{"to_range": 17,"discount": 2,"from_range": 12},{"to_range": 23,"discount": 3,"from_range": 18},{"to_range": 29,"discount": 4,"from_range": 24}],"Pricing_Model": "Differential","Description": "Design your own layouts that align your business processes precisely. Assign them to profiles appropriately.","Price_Book_Name": "Price_Book_Name oops2"}]);

Sample Request: Inserting Leads

resp = zoho.crm.bulkCreate("Leads", [{"Last_Name":"Patricia Boyle"},{"Last_Name":"Deborah Grogan"}], {"trigger":["workflow","blueprint","approval"]});

Sample Request: Creating records in a Custom Module ("Students")

resp=zoho.crm.bulkCreate("Students",[{"Name":"Patricia Boyle new","Owner":"7000000031553","Email":"p.boyle@zylker.com","Secondary_Email":"sdf@zylker.com","Single_Line":"Single_Line 22 new","Multi_Line_1":"Room for Negotiation","Currency_1":1.245,"Email_1":"adf@aps.com","Email_Opt_Out":true,"Decimal_1":2.34,"Phone_1":"9000000000","Percent_1":9,"Tag":{"tag"},"Pick_List_1":"new pick list","Long_Integer_1":"123456789012345690","Multi_Select_1":["Val 1","Val 2"],"Checkbox_1":true,"Date_1":"2018-01-31","website":"www.zoho.@","Date_Time_1":"2018-02-01T12:30:00+05:30","Lookup_1":{"id":"7000000032001"},"Number_1":1},{ "Name":"Deborah Grogan","Owner":"7000000031553","Email":"d.grogan@zylker.com","Secondary_Email":"dgrgn@zylker.com","Single_Line":"Single_Line 23 new","Multi_Line_1":"Negotiation succeeded","Currency_1":1.245,"Email_1":"adf@aps.com","Email_Opt_Out":true,"Decimal_1":2.34,"Phone_1":"9000000000","Percent_1":9,"Tag":{"tag"},"Pick_List_1":"new pick list","Long_Integer_1":"123456789012345690","Multi_Select_1":["Val 1","Val 2"],"Checkbox_1":true,"Date_1":"2018-01-31","website":"www.zylker.com","Date_Time_1":"2018-02-01T12:30:00+05:30","Lookup_1":{"id":"7000000032001"},"Number_1":1}]);

In the above request, @newlead.json contains the sample input data.

Note:

  • Duplicates are checked for every insert record API call based on unique fields.
  • A maximum of 100 records can be inserted per API call.
  • Provide the Field API names along with the corresponding values to be populated, in the Input.
  • The trigger input can be workflow, approval or blueprint. If the trigger is not mentioned, the workflows, approvals and blueprints related to the API will get executed. Enter the trigger value as [] to not execute the workflows.
Copy sample input

Sample Input:

Copy sample response

Sample Response:

Note:

  • Records with Subform details can also be inserted to CRM using the Records API. Please look at the below link to learn more about adding subform information within a record.
  • $approved key is used to set the records to be created in approval mode. Mostly used for leads and contacts procured from webforms.
Load more examples

Sample attributes:

  • The sample for Single Line:

    "Single_Line_1": "This is single line",

  • The sample for Multi Line:

    "Multi_Line_1": "This is the first line \n Now for the second Line",

  • The sample for Email:

    "Email_1": "p.boyle@zylker.com",

  • The sample for Phone:

    "Phone_1": "9900000000",

  • The sample for Picklist:

    "Picklist_1" : "In Progress",

  • The sample for Multi-select picklist:

    "Multi-Select_Picklist" : [
        "{Option_1}",
        "{Option_2}",
        "{Option_3}"

        ],

  • The sample for Date:

    "Date_1": "2017-08-16",

  • The sample for Date/time:

    "Date_Time": "2017-08-16T14:32:23+05:30",

  • The sample for Number:

    "Number_1": 575,

  • The sample for Currency:

    "Currency_1": 250000,

  • The sample for Decimal:

    "Decimal_1": 250000.50,

  • The sample for Percent:

    "Percent_1": 25,

  • The sample for Long Integer:

    "Long_Integer_1": "250000000000000",

  • The sample for Checkbox:

    "Checkbox_1": false,

  • The sample for URL:

    "URL_1": "https://www.zoho.com/crm",

  • The sample for Lookup:

    "Lookup" : {
        "id" : "425248000000104001"
        },

  • The sample for the Record owner:

    "Owner": {
        "id": "425248000000104003"
        },

  • The sample for the Layout:

    "Layout": {
        "id": "425248000000404433"
        },

Update records

Purpose

To update the existing entity in the module

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}

module_api_name - The api name of the module.

Scope

scope=ZohoCRM.modules.all
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, tasks, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, custom, notes. ALL - Full access to records
WRITE - edit records in module
UPDATE - update records in a module

Request Method

PUT

Possible Errors

HTTP Status Error Code Message Reason
400 INVALID_MODULE The module name given seems to be invalid Invalid module name or no tab permission, or the module could have been removed from the organized module
400 INVALID_MODULE The given module is not supported in API The modules such as Documents and Projects are not supproted in the current API. (This error will not be shown, once these modules are been supported.)

Note:

  • An error is thrown if the field value length is more than the maximum length defined for that field.
  • If an API used inside a Function when the field value length exceeds the limit, then that function receives error response from the API. For ex: If the max length for a "Text field" is defined as 10, then value given for it in API cannot be "12345678901", as it has 11 characters.
Curl Java PHP Python Functions C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Leads"

-X PUT

-d "@updatelead.json"

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

List<Long> entityIDs = new ArrayList<>();// list of record ids
entityIDs.add(426000621092l);
entityIDs.add(426859000010l);
ZCRMModule module = ZCRMModule.getInstance("Products");//module api name
BulkAPIResponse response = module.updateRecords(entityIDs,"Product_Name","massUpdate");//field api name with its value to update
List<ZCRMRecord> updatedRecords = (List<ZCRMRecord>) response.getData();
List<BulkAPIResponse.EntityResponse> entityResponses = response.getEntityResponses();// to check the status of the request
String rec1Status = entityResponses.get(0).getStatus();//check status of record1
String rec2Status = entityResponses.get(1).getStatus();//check status of record2

Copy sample request

Sample Request:

$idList=array(410405000001076001,410405000001021027,410405000000497012);
$zcrmModuleIns = ZCRMModule::getInstance("Contacts");
$bulkAPIResponse=$zcrmModuleIns->updateRecords($idList,"Account_Name","NewAccount");
$entityResponses = $bulkAPIResponse->getEntityResponses();
foreach($entityResponses as $entityResponse)
{
if("success"==$entityResponse->getStatus())
{
echo "Status:".$entityResponse->getStatus();
echo "Message:".$entityResponse->getMessage();
echo "Code:".$entityResponse->getCode();
$recordIns=$entityResponse->getData();
echo "EntityID:".$recordIns->getEntityId();
echo "moduleAPIName:".$recordIns->getModuleAPIName();
….
}
}

Copy sample request

Sample Request: Update Records

/** Update records*/
ZCRMRecord record = new ZCRMRecord("Leads"); //module api name
List<ZCRMRecord> records = new List<ZCRMRecord>();
record.SetFieldValue("id", 3372164000001632020);
record.SetFieldValue("Company", "ekhrj");
record.SetFieldValue("Last_Name", "smith");
record.SetFieldValue("Email", "smith@gmail.com");
records.Add(record);
ZCRMModule moduleIns = ZCRMModule.GetInstance("Leads"); //module api name
BulkAPIResponse<ZCRMRecord> response = moduleIns.UpdateRecords(records); //records - list of ZCRMRecord instances filled with required data for update.
List<ZCRMRecord> updatedRecords = response.BulkData; //updatedRecords - list of ZCRMRecord instance
List<EntityResponse> entityResponses = response.BulkEntitiesResponse; //entityResponses - list of EntityResponse instance

Copy sample request

Sample Request: Mass Update

List<long> entityIDs = new List<long>{ 3372164000001632010 , 3372164000001632009, 3372164000001622005 }; // list of record ids
ZCRMModule moduleIns = ZCRMModule.GetInstance("Products");//module api name
BulkAPIResponse<ZCRMRecord> response = moduleIns.MassUpdateRecords(entityIDs, "Product_Name", "massUpdate");//field api name with its value to update
List<ZCRMRecord> updatedRecords = response.BulkData; //updatedRecords - list of ZCRMRecord instance
List<EntityResponse> entityResponses = response.BulkEntitiesResponse; //entityResponses - list of EntityResponse instance

Copy sample request

Sample Request:

def update_records(self):

  try:

    module_ins=ZCRMModule.get_instance('Invoices') #module API Name

    entityid_list=[440872000000280035,440872000000278029,440872000000278028]

    bulk_resp=module_ins.update_records(entityid_list, 'Status', 'Created')

    print bulk_resp.status_code

    entity_responses=bulk_resp.bulk_entity_response

    for entity_response in entity_responses:

      print entity_response.details

      print entity_response.status

      print entity_response.message

      print entity_response.code

      print entity_response.data.entity_id

      print entity_response.data.created_by.id

      print entity_response.data.created_time

      print entity_response.data.modified_by.id

      print "\n\n"

  except ZCRMException as ex:

    print ex.status_code

    print ex.error_message

    print ex.error_code

    print ex.error_details

    print ex.error_content

Copy sample request

Sample Request Syntax:

zoho.crm.bulkUpdate(<module String>,<dataList List>,<optionalDataMap Map>,<connectionName String>,<userAccess Boolean>);
mandatory : module,dataList

Sample Request: Updating Price Book records

resp = zoho.crm.bulkUpdate("Price_Books", [{"Owner": {"id": "7000000031553"},"id":"7000000037030","Active": true,"Pricing_Details": [{"to_range": 5,"discount": 0,"from_range": 1},{"to_range": 11,"discount": 1,"from_range": 6},{"to_range": 17,"discount": 2,"from_range": 12},{"to_range": 23,"discount": 3,"from_range": 18},{"to_range": 29,"discount": 4,"from_range": 24}],"Pricing_Model": "Differential","Description": "Design your own layouts that align your business processes precisely. Assign them to profiles appropriately.","Price_Book_Name": "Price_Book_Name oops1 updated"},{"Owner": {"id": "7000000031553"},"Active": true,"Pricing_Details": [{"to_range": 5,"discount": 0,"from_range": 1},{"to_range": 11,"discount": 1,"from_range": 6},{"to_range": 17,"discount": 2,"from_range": 12},{"to_range": 23,"discount": 3,"from_range": 18},{"to_range": 29,"discount": 4,"from_range": 24}],"Pricing_Model": "Differential", "id":"7000000037031","Description": "Design your own layouts that align your business processes precisely. Assign them to profiles appropriately.","Price_Book_Name": "Price_Book_Name oops2 updated"}]);

Note:

In the above request, @updatelead.json contains the sample input.

Copy sample input

Sample Input:

Note:

  • Duplicates are checked for every update record API call based on unique fields.
  • A maximum of 100 records can be updated per API call.
  • Provide the Field API names along with the corresponding values to be populated, in the Input.
  • The trigger input can be workflow, approval or blueprint. If the trigger is not mentioned, the workflows, approvals and blueprints related to the API will get executed. Enter the trigger value as [] to not execute the workflows.
  • If the update API calls for a record are from DRE(Functions), due to workflow triggered on the same record's create / update, then workflow alone will not get executed, irrespective of the trigger param configuration.
Copy sample response

Sample Response:

Note:

  • Record details can be udpated with Subform details using the Records API. Please look at the below link to learn more about updating subform information within a record.
Load more examples

Sample attributes:

  • The sample for Single Line:

    "Single_Line_1": "This is single line",

  • The sample for Multi Line:

    "Multi_Line_1": "This is the first line \n Now for the second Line",

  • The sample for Email:

    "Email_1": "p.boyle@zylker.com",

  • The sample for Phone:

    "Phone_1": "9900000000",

  • The sample for Picklist:

    "Picklist_1" : "In Progress",

  • The sample for Multi-select picklist:

    "Multi-Select_Picklist" : [
        "{Option_1}",
        "{Option_2}",
        "{Option_3}"

        ],

  • The sample for Date:

    "Date_1": "2017-08-16",

  • The sample for Date/time:

    "Date_Time": "2017-08-16T14:32:23+05:30",

  • The sample for Number:

    "Number_1": 575,

  • The sample for Currency:

    "Currency_1": 250000,

  • The sample for Decimal:

    "Decimal_1": 250000.50,

  • The sample for Percent:

    "Percent_1": 25,

  • The sample for Long Integer:

    "Long_Integer_1": "250000000000000",

  • The sample for Checkbox:

    "Checkbox_1": false,

  • The sample for URL:

    "URL_1": "https://www.zoho.com/crm",

  • The sample for Lookup:

    "Lookup" : {
        "id" : "425248000000104001"
        },

  • The sample for the Record owner:

    "Owner": {
        "id": "425248000000104003"
        },

  • The sample for the Layout:

    "Layout": {
        "id": "425248000000404433"
        },

Insert or Update (upsert)

Purpose

To insert a new record, if the record does not exist (records will be inserted or updated based on duplicate checks). If the record already exists, then it will be updated accordingly. This is used to avoid creating duplicate records.

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}/upsert

module_api_name - The api name of the module.

Scope

scope=ZohoCRM.modules.all
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, cases, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, custom, notes. ALL - Full access to record
WRITE - edit records in a module
CREATE - create records in a module

Parameters

Parameter Name Data Type Description Possible Values
duplicate_check_fields (optional) String To check for duplicated records based on the fields specified in a strict sequential user-defined order followed by system-defined fields and remaining unique fields. Multiple field API names, comma separated. For example: Last_Name,Email

Note:

  • In case the user does not specify the duplicate_check_fields, the system-defined duplicate check fields followed by unique fields, are used by default. See below.

Request Method

POST

Possible Errors

HTTP Status Error Code Message Reason
400 INVALID_MODULE The module name given seems to be invalid Invalid module name or no tab permission, or the module could have been removed from the organized module
400 INVALID_MODULE The given module is not supported in API The modules such as Documents and Projects are not supproted in the current API. (This error will not be shown, once these modules are been supported.)

Note:

  • An error is thrown if the field value length is more than the maximum length defined for that field.
  • If an API used inside a Function when the field value length exceeds the limit, then that function receives error response from the API. For ex: If the max length for a "Text field" is defined as 10, then value given for it in API cannot be "12345678901", as it has 11 characters.
Curl Java PHP Python Functions C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Leads/upsert"

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

-d "@upsertlead.json"

-X POST

Copy sample request

Sample Request:

List records = new ArrayList<>();
ZCRMRecord record1 = new ZCRMRecord("Leads"); // module api name
record1.setFieldValue("Company", "Zylker");
record1.setFieldValue("First_name", "Daly");
record1.setFieldValue("Last_Name", "Paul");
record1.setFieldValue("Email", "p.daly@zylker.com");
record1.setFieldValue("State", "Texas");
ZCRMRecord record2 = new ZCRMRecord("Leads"); // module api name
record2.setFieldValue("Company", "ekhrj");
record2.setFieldValue("First_name", "John");
record2.setFieldValue("Last_Name", "smith");
record2.setFieldValue("Email", "john.a@ekhrj.com");
record2.setFieldValue("State", "Texas");
records.add(record1);
records.add(record2);
ZCRMModule module = ZCRMModule.getInstance("Leads"); //module api name
BulkAPIResponse response = module.upsertRecords(records);
List<ZCRMRecord> upsertedRecords = (List<ZCRMRecord>) response.getData();
List<BulkAPIResponse.EntityResponse> entityResponses = response.getEntityResponses();// to check the status of the request
String rec1Status = entityResponses.get(0).getStatus();//check status of record1
String rec2Status = entityResponses.get(1).getStatus();//check status of record2

Copy sample request

Sample Request:

$zcrmModuleIns = ZCRMModule::getInstance("Contacts");
$bulkAPIResponse=$zcrmModuleIns->upsertRecords($recordsArray); // $recordsArray - array of ZCRMRecord instances filled with required data for upsert.
$entityResponses = $bulkAPIResponse->getEntityResponses();
foreach($entityResponses as $entityResponse)
{
if("success"==$entityResponse->getStatus())
{
echo "Status:".$entityResponse->getStatus();
echo "Message:".$entityResponse->getMessage();
echo "Code:".$entityResponse->getCode();
$upsertData=$entityResponse->getUpsertDetails();
echo "UPSERT_ACTION:".$upsertData[“action”];
echo "UPSERT_DUPLICATE_FIELD:".$upsertData[“duplicate_field”];
$createdRecordInstance=$entityResponse->getData();
echo "EntityID:".$createdRecordInstance->getEntityId();
echo "moduleAPIName:".$createdRecordInstance->getModuleAPIName();
….
}
}

Copy sample request

Sample Request:

List<ZCRMRecord> records = new List<ZCRMRecord>();
ZCRMRecord record1 = new ZCRMRecord("Leads"); //module api name
record1.SetFieldValue("Company", "Zylker");
record1.SetFieldValue("First_name", "Daly");
record1.SetFieldValue("Last_Name", "Paul");
record1.SetFieldValue("Email", "p.daly@zylker.com");
record1.SetFieldValue("State", "Texas");
ZCRMRecord record2 = new ZCRMRecord("Leads"); //module api name
record2.SetFieldValue("Company", "ekhrj");
record2.SetFieldValue("First_name", "John");
record2.SetFieldValue("Last_Name", "smith");
record2.SetFieldValue("Email", "john.a@ekhrj.com");
record2.SetFieldValue("State", "Texas");
records.Add(record1);
records.Add(record2);
ZCRMModule moduleIns = ZCRMModule.GetInstance("Leads"); //module api name
BulkAPIResponse<ZCRMRecord> response = moduleIns.UpsertRecords(records); //records - list of ZCRMRecord instances filled with required data for upsert.
List<ZCRMRecord> upsertedRecords = response.BulkData; //upsertedRecords - list of ZCRMRecord instance
List<EntityResponse> entityResponses = response.BulkEntitiesResponse; //entityResponses - list of EntityResponses instance

Copy sample request

Sample Request:

def upsert_records(self):

  try:

    record_ins_list=list()

    for i in range(0,2):

      record=ZCRMRecord.get_instance('Invoices') #module API Name

      record.set_field_value('Subject', 'Invoice'+str(i))

      record.set_field_value('Account_Name', 'IIIT')

      user=ZCRMUser.get_instance(440872000000175001,'Python Automation User1')

      record.set_field_value('Owner',user

      line_item=ZCRMInventoryLineItem.get_instance(ZCRMRecord.get_instance("Products",440872000000224005))

      line_item.discount=10

      line_item.list_price=8

      line_item.description='Product Description'

      line_item.quantity=100

      line_item.tax_amount=2.5

      taxIns=ZCRMTax.get_instance("Vat")

      taxIns.percentage=5

      line_item.line_tax.append(taxIns)

      record.add_line_item(line_item)

      record_ins_list.append(record)

    record=ZCRMRecord.get_instance('Invoices',440872000000248818)

    record.set_field_value('Subject', 'Invoice1.1')

    line_item=ZCRMInventoryLineItem.get_instance(ZCRMRecord.get_instance("Products",440872000000224005))

    line_item.discount=10

    line_item.list_price=8

    line_item.description='Product Description'

    line_item.quantity=100

    line_item.tax_amount=2.5

    taxIns=ZCRMTax.get_instance("Vat")

    taxIns.percentage=5

    line_item.line_tax.append(taxIns)

    record.add_line_item(line_item)

    record_ins_list.append(record)

    resp=ZCRMModule.get_instance('Invoices').upsert_records(record_ins_list)

    print resp.status_code

    entity_responses=resp.bulk_entity_response

    for entity_response in entity_responses:

      print entity_response.details

      print entity_response.status

      print entity_response.message

      print entity_response.code

      print entity_response.data.entity_id

      print entity_response.data.created_by.id

      print entity_response.data.created_time

      print entity_response.data.modified_by.id

      print "\n\n"

  except ZCRMException as ex:

    print ex.status_code

    print ex.error_message

    print ex.error_code

    print ex.error_details

    print ex.error_content

Copy sample request

Sample Request Syntax:

zoho.crm.upsert(<module String>,<dataMap Map>,<optionalDataMap Map>,<connectionName String>,<userAccess Boolean>);
mandatory : module,dataMap

Sample Request:

resp = zoho.crm.upsert("Leads", {"Last_Name":"Patricia upsert UF2", "UF":"p.boyle@zylker.com", "Email":"d.grogan@zylker.com"}, {"duplicate_check_fields":["UF" , "Email"]});

Note:

In the above request, @upsertlead.json contains the sample input data.

Copy sample input

Sample Input:

Note:

  • A maximum of 100 records can be inserted/updated per API call.
  • Provide the Field API names along with the corresponding values to be populated, in the Input.
  • The trigger input can be workflow, approval or blueprint. If the trigger is not mentioned, the workflows, approvals and blueprints related to the API will get executed. Enter the trigger value as [] to not execute the workflows.
Copy sample response

Sample Response:

Note:

  • Record details can be udpated with Subform details using the Records API.

System-defined Duplicate Check Fields

  • The system-defined duplicate check fields are given in the format : {module_name} - {field_API_name}
  • Leads - Email, Accounts - Account_Name, Contacts - Email, Deals - Deal_Name, Campaigns - Campaign_Name, Cases - Subject, Solutions - Solution_Title, Products - Product_Name, Vendors - Vendor_Name, PriceBooks - Price_Book_Name, Quotes - Subject, SalesOrders - Subject, PurchaseOrders - Subject, Invoices - Subject, CustomModules - Name

Sample attributes:

  • The sample for Single Line:

    "Single_Line_1": "This is single line",

  • The sample for Multi Line:

    "Multi_Line_1": "This is the first line \n Now for the second Line",

  • The sample for Email:

    "Email_1": "p.boyle@zylker.com",

  • The sample for Phone:

    "Phone_1": "9900000000",

  • The sample for Picklist:

    "Picklist_1" : "In Progress",

  • The sample for Multi-select picklist:

    "Multi-Select_Picklist" : [
        "{Option_1}",
        "{Option_2}",
        "{Option_3}"

        ],

  • The sample for Date:

    "Date_1": "2017-08-16",

  • The sample for Date/time:

    "Date_Time": "2017-08-16T14:32:23+05:30",

  • The sample for Number:

    "Number_1": 575,

  • The sample for Currency:

    "Currency_1": 250000,

  • The sample for Decimal:

    "Decimal_1": 250000.50,

  • The sample for Percent:

    "Percent_1": 25,

  • The sample for Long Integer:

    "Long_Integer_1": "250000000000000",

  • The sample for Checkbox:

    "Checkbox_1": false,

  • The sample for URL:

    "URL_1": "https://www.zoho.com/crm",

  • The sample for Lookup:

    "Lookup" : {
        "id" : "425248000000104001"
        },

  • The sample for the Record owner:

    "Owner": {
        "id": "425248000000104003"
        },

  • The sample for the Layout:

    "Layout": {
        "id": "425248000000404433"
        },

Delete records

Purpose

To delete entities or records from a module.

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}?ids={EntityID}

module_api_name - The api name of the module.

Scope

scope=ZohoCRM.modules.all
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, tasks, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, custom, notes. ALL - Full access to a record
WRITE - edit records in a module
DELETE - delete records in a module

Request Method

DELETE

Parameters

Parameter Name Data Type Description Possible Values
ids (mandatory) Integer Specify the unique id of the record. Entity IDs separated by commas. For example: 410405000002264040,410405000002264025
Curl Python C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Leads?ids=410405000002264040,410405000002264025"

-X DELETE

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

In the above sample, the lead records with ids "410405000002264040" and "410405000002264025" will be deleted.

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

List<long> entityIDs = new List<long> { 3372164000001622004, 3372164000001632009, 3372164000001622005 }; // list of record ids
ZCRMModule moduleIns = ZCRMModule.GetInstance("Products"); //module api name
BulkAPIResponse<ZCRMEntity> response = moduleIns.DeleteRecords(entityIDs);
List<EntityResponse> entityResponses = response.BulkEntitiesResponse; //entityResponses - list of EntityResponses instance

Copy sample request

Sample Request:

def delete_records(self):

  try:

    entityid_list=[1386586000001856020,1386586000001856019]

    resp=ZCRMModule.get_instance('Invoices').delete_records(entityid_list)

    print resp.status_code

    entity_responses=resp.bulk_entity_response

    for entity_response in entity_responses:

      print entity_response.details

      print entity_response.status

      print entity_response.message

      print entity_response.code

      print entity_response.data.entity_id

      print "\n\n"

  except ZCRMException as ex:

    print ex.status_code

    print ex.error_message

    print ex.error_code

    print ex.error_details

    print ex.error_content

Note:

  • A maximum of 100 records can be deleted per API call.
  • By default, all the workflows related to this API will get executed.
  • All the subforms related to this API will get deleted.
Copy sample response

Sample Response:

Get list of deleted records

Purpose

To get the list of deleted records

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}/deleted

module_api_name - The api name of the module.

Scope

scope=ZohoCRM.modules.all
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, tasks, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, custom, notes. ALL - Full access to a record
READ - get records in a module

Request Method

GET

Request Headers

Header Name Data Type Description Example
If-Modified-Since (optional) DateTime(ISO 8601 format) To get the list of recently modifed records 2019-07-25T15:26:49+05:30

Parameters

Parameter Name Data Type Description
module (mandatory) String Specify the module API name
type String
All

To get the list of all deleted records

Recycle

To get the list of deleted records from recycle bin

Permanent

To get the list of permanently deleted records

page (optional) Integer To get the list of records from the respective pages. Default value for page is 1.
per_page (optional) Integer To get the list of records available per page. Default value for per page is 200.

Note:

The page and per_page parameter is used to fetch records according to their position in the CRM. Let's assume that the user has to fetch 400 records. The maximum number of records that one can get for an API call is 200. So, for records above the 200th position, they cannot be fetched. By using the page (1, 2, 3 and 4) and per_page (100) parameter, the user can fetch all 400 records using 4 API calls.

Possible Errors

HTTP Status Error Code Message Reason
400 INVALID_DATA invalid data Invalid type param value given.
Curl Java PHP Python C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Leads/deleted?type=All"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

ZCRMModule module = ZCRMModule.getInstance("Leads"); //module api name
BulkAPIResponse response = module.getAllDeletedRecords();
List<ZCRMRecord> deletedRecords = (List<ZCRMRecord>) response.getData();
List<ZCRMTrashRecord> recycleBinRecords = (List<ZCRMTrashRecord>) module.getRecycleBinRecords().getData();
List<ZCRMTrashRecord> permenantDeleteRecords = (List<ZCRMTrashRecord>) module.getPermanentlyDeletedRecords().getData();

Copy sample request

Sample Request:

To get all the deleted Records
$response=ZCRMModule::getInstance($moduleAPIName)->getAllDeletedRecords(); // $moduleAPIName - APIName of the module.
To get All the recyclebin records
$response=ZCRMModule::getInstance($moduleAPIName)->getRecycleBinRecords();
To get all the records which got deleted permanently
$response=ZCRMModule::getInstance($moduleAPIName)->getPermanentlyDeletedRecords();
$records=$response->getData();
try{
foreach ($records as $record){
echo $record->getEntityId();
echo $record->getDisplayName();
echo $record->getType();
$createdBy=$record->getCreatedBy();
$deletedBy=$record->getDeletedBy();
if($createdBy!=null)
{
echo $createdBy->getId();
}
if($deletedBy!=null)
{
echo $deletedBy->getId();
}
echo $record->getDeletedTime();
}
}
catch (ZCRMException $ex)
{
echo $ex->getMessage();
echo $ex->getExceptionCode();
echo $ex->getFile();
}

Copy sample request

Sample Request:

ZCRMModule moduleIns = ZCRMModule.GetInstance("Leads"); //module api name
BulkAPIResponse<ZCRMTrashRecord> response = moduleIns.GetAllDeletedRecords();
List<ZCRMTrashRecord> deletedRecords = response.BulkData; // deletedRecords - list of ZCRMTrashRecord instance both recyclebin records and permanently deleted records
List<ZCRMTrashRecord> recycleBinRecords = moduleIns.GetRecycleBinRecords().BulkData; // To get All the recyclebin records
List<ZCRMTrashRecord> permenantDeleteRecords = moduleIns.GetPermanentlyDeletedRecords().BulkData; //To get all the records which got deleted permanently

Copy sample request

Sample Request:

def get_deleted_records(self,delete_type):

  try:

    module_ins=ZCRMModule.get_instance('Invoices')

    if delete_type=='permanent':

      resp=module_ins.get_permanently_deleted_records()

    elif delete_type=='recycle':

      resp=module_ins.get_recyclebin_records()

    else: delete_type=='recycle':

      resp=module_ins.get_all_deleted_records()

    print resp.status_code

    trash_record_ins_arr=resp.data

    resp_info=resp.info

    print resp_info.count

    print resp_info.page

    print resp_info.per_page

    print resp_info.is_more_records

    for record_ins in trash_record_ins_arr:

      print record_ins.id

      print record_ins.type

      print record_ins.display_name

      if record_ins.created_by is not None:

        print record_ins.created_by.id

      if record_ins.deleted_by is not None:

        print record_ins.deleted_by.id

      print record_ins.deleted_time

      print "\n\n"

  except ZCRMException as ex:

    print ex.status_code

    print ex.error_message

    print ex.error_code

    print ex.error_details

    print ex.error_content

Copy sample response

Sample Response:

Search records

Purpose

To retrieve the records that matches your search criteria

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}/search

module_api_name - The api name of the module.

Scope

scope=ZohoCRM.modules.all
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, tasks, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, custom, notes and activities. ALL - Full access to a record
READ - get records in a module

Request Method

GET

Parameters

Parameter Name Data Type Description
criteria String Performs search by the following shown criteria. (({apiname}:{starts_with|equals}:{value}) and ({apiname}:{starts_with|equals}:{value})) You can search a maximum of 10 criteria (with same or different columns) with equals and starts_with conditions as shown above.
email String {email} - Performs module search by email. All the email fields of a particular module will be searched and listed.
phone String {Phone} - Performs module search by phone number. All the phone fields of a particular module will be searched and listed.
word String {Word}- Performs global search by word.
converted (optional) String To get the list of converted records. Default value is False.
true - get only converted records
false - get only non-converted records
both - get all records
approved (optional) String To get the list of approved records. Default value is True.
true - get only approved records
false - get only records which are not approved
both - get all records
page (optional) Integer To get the list of records from the respective pages. Default value for page is 1.
per_page (optional) Integer To get the list of records available per page. Default value for per page is 200.

Note:

  • Only one of the above four parameters would work at one point of time. Furthermore, if two parameters are given simultaneously, preference will be given in the order criteria, email, phone and word, and only one of them would work.
  • The page and per_page parameter is used to fetch records according to their position in the CRM. Let's assume that the user has to fetch 400 records. The maximum number of records that one can get for an API call is 200. So, for records above the 200th position, they cannot be fetched. By using the page (1, 2, 3 and 4) and per_page (100) parameter, the user can fetch all 400 records using 4 API calls.
Curl Java PHP Python Functions C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Contacts/search?phone=888-555-2145"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

Search by Phone:

ZCRMModule module = ZCRMModule.getInstance("Contacts"); // module api name
BulkAPIResponse response = module.searchByPhone("123456789", 1, 10);// get search records with page and per page count
List<ZCRMRecord> records = (List<ZCRMRecord>) response.getData(); //matching records

Copy sample request

Sample Request:

Search by Email:

ZCRMModule module = ZCRMModule.getInstance("Contacts"); // module api name
BulkAPIResponse response = module.searchByEmail("bruce@wayne.com", 1, 10);// get search records with page and per page count
List<ZCRMRecord> records = (List<ZCRMRecord>) response.getData(); //matching records

Copy sample request

Sample Request:

$zcrmModuleIns = ZCRMModule::getInstance("Products");
$bulkAPIResponse=$zcrmModuleIns->searchRecords("ip");
$records = $bulkAPIResponse->getData(); // $records - array of ZCRMRecord instances.

Copy sample request

Sample Request:

//Search by Phone:

ZCRMModule moduleIns = ZCRMModule.GetInstance("Leads"); // module api name

BulkAPIResponse<ZCRMRecord> response = moduleIns.SearchByPhone("95959595", 1, 10);// get search records with page and per page count

List<ZCRMRecord> records = response.BulkData; //matching records

Copy sample request

Sample Request:

//Search by Email:
ZCRMModule moduleIns = ZCRMModule.GetInstance("Leads"); // module api name
BulkAPIResponse<ZCRMRecord> response = moduleIns.SearchByEmail("email@zohocorp.com", 1, 10);// get search records with page and per page count
List<ZCRMRecord> records = response.BulkData; //matching records

Copy sample request

Sample Request:

def search_records(self):

  try:

    module_ins=ZCRMModule.get_instance('Products') #module API Name

    resp=module_ins.search_records('Orange') #search key word

    print resp.status_code

    resp_info=resp.info

    print resp_info.count

    print resp_info.page

    print resp_info.per_page

    print resp_info.is_more_records

    record_ins_arr=resp.data

    for record_ins in record_ins_arr:

      print record_ins.entity_id

      print record_ins.owner.id

      print record_ins.created_by.id

      print record_ins.modified_by.id

      print record_ins.created_time

      print record_ins.modified_time

      print record_ins.get_field_value('Product_Name')

      print record_ins.get_field_value('Product_Code')

      print record_ins.get_field_value('Vendor_Name')

      print record_ins.get_field_value('Commission_Rate')

      print record_ins.get_field_value('Qty_in_Demand')

      print record_ins.get_field_value('Tax')

      print record_ins.get_field_value('Unit_Price')

      print record_ins.get_field_value('Reorder_Level')

      print record_ins.get_field_value('Usage_Unit')

      print record_ins.get_field_value('Qty_Ordered')

      print record_ins.get_field_value('Qty_in_Stock')

      print record_ins.get_field_value('Sales_Start_Date')

      print record_ins.get_field_value('Sales_End_Date')

      print record_ins.get_field_value('Taxable')

      print record_ins.get_field_value('Support_Expiry_Date')

      print record_ins.get_field_value('Manufacturer')

      print record_ins.get_field_value('Description')

      print record_ins.field_data

      print "\n\n"

  except ZCRMException as ex:

    print ex.status_code

    print ex.error_message

    print ex.error_code

    print ex.error_details

    print ex.error_content

Copy sample request

Sample Request Syntax:

zoho.crm.searchRecords(<module String>,<criteria String>,<page Long>,<perPage Long>,<connectionName String>,<userAccess Boolean>);
mandatory : module,criteria

Sample Request:

resp = zoho.crm.searchRecords("Leads", "((Last_Name:equals:Hawkins) or (Last_Name:starts_with:Pat))");

Copy sample response

Sample Response:

Load more examples

To search by email

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Leads/search?email=p.daly@zylker.com"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample response

Sample Response:

Note:

  • Usually there would be some delay in getting the result for a search action. However, there are certains fields in certain modules, which when searched through this API, instantly gives a result without delays. For instance,
    Leads/Contacts - "Email" field
    Accounts - "Account_Name" field
    Potentials/Deals - "Deal_Name" field
    Campaigns - "Campaign_Name" field
    Cases - "Subject" field
    Solutions - "Solution_Title" field
    Products - "Product_Name" field
    Vendors - "Vendor_Name" field
    PriceBooks - "Price_Book_Name" field
    Quotes - "Subject" field
    SalesOrders - "Subject" field
    PurchaseOrders - "Subject" field
    Invoices - "Subject" field
    CustomModule - "Name" field
  • If any search API comes with the criteria containing only one above mentioned field for a module, you will get the result without any delay.

Single Record APIs

Get a specific record

Purpose

To get a particular entity or record

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}/{record_id}

module_api_name - The api name of the module.

record_id - Specify the unique id of a record.

Scope

scope=ZohoCRM.modules.all
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, tasks, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, custom, notes, approvals and activities. ALL - Full access to a record
READ - get records in a module

Request Method

GET

Curl Java PHP Python Functions C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Leads/410888000000698006"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

In the above sample, the lead record with id "410888000000698006" will be retrieved.

Copy sample request

Sample Request:

ZCRMModule module = ZCRMModule.getInstance("Products");//module api name

APIResponse response = module.getRecord(1234567890l);//record id

ZCRMRecord record = (ZCRMRecord) response.getData();

Copy sample request

Sample Request:

$apiResponse=ZCRMModule::getInstance('Leads')->getRecord(410405000001519001); // 410405000001519001 - Lead Id
$record=$apiResponse->getData();
echo $record->getEntityId();
echo $record->getModuleApiName();
echo $record->getLookupLabel();
echo $record->getCreatedBy()->getId();
echo $record->getModifiedBy()->getId();
echo $record->getOwner()->getId();
echo $record->getCreatedTime();
echo $record->getModifiedTime();
$map=$record->getData();
foreach ($map as $key=>$value)
{
if($value instanceof ZCRMRecord)
{
echo "\n".$value->getEntityId().":".$value->getModuleApiName().":".$value->getLookupLabel();
}
else
{
echo $key.":".$value;
}
}

Copy sample request

Sample Request:

ZCRMModule moduleIns = ZCRMModule.GetInstance("Products"); //module api name
APIResponse response = moduleIns.GetRecord(3372164000000190001); //3372164000000190001 is record id
ZCRMRecord record = (ZCRMRecord)response.Data;

Copy sample request

Sample Request:

def get_record(self):
    try:
        #record=ZCRMRecord.get_instance('Leads',440872000000219003)#440872000000219003 is leadid
        record=ZCRMRecord.get_instance('Invoices',1386586000000803061)
        resp=record.get()
        print resp.status_code
        print resp.data.entity_id
        print resp.data.created_by.id
        print resp.data.modified_by.id
        print resp.data.owner.id
        print resp.data.created_by.name
        print resp.data.created_time
        print resp.data.modified_time
        print resp.data.get_field_value('Email')
        print resp.data.get_field_value('Last_Name')
        #print resp.data.field_data
        if resp.data.line_items is not None:
            for line_item in resp.data.line_items:
                print "::::::LINE ITEM DETAILS::::::"
                print line_item.id
                print line_item.product.lookup_label
                print line_item.product.get_field_value('Product_Code')
                print line_item.product.entity_id
                print line_item.list_price
                print line_item.quantity
                print line_item.description
                print line_item.total
                print line_item.discount
                print line_item.discount_percentage
                print line_item.total_after_discount
                print line_item.tax_amount
                print line_item.net_total
                print line_item.delete_flag
                if line_item.line_tax is not None:
                    for tax in line_item.line_tax:
                        print ":::::: TAX DETAILS ::::::"
                        print tax.name
                        print tax.value
                        print tax.percentage
    except ZCRMException as ex:
        print ex.status_code
        print ex.error_message
        print ex.error_code
        print ex.error_details
        print ex.error_content

Copy sample request

Sample Request Syntax:

zoho.crm.getRecordById(<module String>,<recordID Long>,<connectionName String>,<userAccess Boolean>);
mandatory : module,recordID

Sample Request:

resp = zoho.crm.getRecordById("Price_Books", 410888000000673626);

Copy sample response

Sample Response:

Note:

  • Subform details are also available within the JSON object of the response.
  • Subform details appear as the api name of the subform you created. For example, if the Subform name is "Sub form1", the api name in the response is "Sub_form1".

Sample attributes:

  • The sample for Single Line:

    "Single_Line_1": "This is single line",

  • The sample for Multi Line:

    "Multi_Line_1": "This is the first line \n Now for the second Line",

  • The sample for Email:

    "Email_1": "p.boyle@zylker.com",

  • The sample for Phone:

    "Phone_1": "9900000000",

  • The sample for Picklist:

    "Picklist_1" : "In Progress",

  • The sample for Multi-select picklist:

    "Multi-Select_Picklist" : [
        "{Option_1}",
        "{Option_2}",
        "{Option_3}"

        ],

  • The sample for Date:

    "Date_1": "2017-08-16",

  • The sample for Date/time:

    "Date_Time": "2017-08-16T14:32:23+05:30",

  • The sample for Number:

    "Number_1": 575,

  • The sample for Currency:

    "Currency_1": 250000,

  • The sample for Decimal:

    "Decimal_1": 250000.50,

  • The sample for Percent:

    "Percent_1": 25,

  • The sample for Long Integer:

    "Long_Integer_1": "250000000000000",

  • The sample for Checkbox:

    "Checkbox_1": false,

  • The sample for URL:

    "URL_1": "https://www.zoho.com/crm",

  • The sample for Lookup:

    "Lookup" : {
        "name" : "James"
        "id" : "425248000000104001"
        },

  • The sample for the Record owner:

    "Owner": {
        "name" : "Patricia"
        "id": "425248000000104003"
        },

  • The sample for the Layout:

    "Layout": {
        "name" : "Custom Layout 1"
        "id": "425248000000404433"
        },

  • The sample for Auto Number:

    "Auto_Number_1": "LEAD44N",


    Where LEAD - Prefix, 44 - Assigment Number and N - Suffix.

Insert a specific record

Purpose

To insert a new entity into a module

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}

module_api_name - The api name of the module.

Scope

scope=ZohoCRM.modules.all
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, tasks, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, custom, notes. ALL - Full access to record
WRITE - edit records in a module
CREATE - create records in a module

Request Method

POST

Possible Errors

HTTP Status Error Code Message Reason Details Key Values
400 INVALID_MODULE The module name given seems to be invalid Invalid module name or no tab permission, or the module could have been removed from the organized module
400 INVALID_MODULE The given module is not supported in API The modules such as Documents and Projects are not supproted in the current API. (This error will not be shown, once these modules are been supported.)
403 NO_PERMISSION permission denied to create '{modulename}' No permission to insert records
400 MANDATORY_NOT_FOUND Required field not found. If the data key isn't available. {
"api_name": "data"
}
400 INVALID_DATA Invalid Data If the data key has the invalid data type. {
"expected_data_type":
"jsonarray",
"api_name": "data"
},
202 INVALID_DATA (at the record index) Invalid Data If the record passed isn't a JSON object {
"expected_data_type":
"jsonobject",
"index": 0
}
201 MANDATORY_NOT_FOUND Required field not found. If the mandatory fields are not available. {
"api_name":
"Last_Name"
}
202 INVALID_DATA Invalid Data If the datatype is mismatched. {
"expected_data_type":
"double", "api_name":
"Decimal_1"
}

Note:

  • An error is thrown if the field value length is more than the maximum length defined for that field.
  • If an API used inside a Function when the field value length exceeds the limit, then that function receives error response from the API. For ex: If the max length for a "Text field" is defined as 10, then value given for it in API cannot be "12345678901", as it has 11 characters.
Curl Java PHP Python Functions C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Leads"

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

-d "@newlead.json"

-X POST

Copy sample request

Sample Request:

List<ZCRMRecord> records = new ArrayList<>();

ZCRMRecord record1 = new ZCRMRecord("Products"); //module api name

ZCRMUser owner = ZCRMUser.getInstance(12345678l);// user id

record1.setOwner(owner);

record1.setFieldValue("Product_Name", "mass_create1");// field api name with its value

ZCRMRecord record2 = new ZCRMRecord("Products"); //module api name

ZCRMUser owner = ZCRMUser.getInstance(5676875678l);// user id

record2.setOwner(owner);

record2.setFieldValue("Product_Name", "mass_create2");// field api name with its value

records.add(record1);

records.add(record2);

ZCRMModule module = ZCRMModule.getInstance("Products"); //module api name

BulkAPIResponse response = module.createRecords(records);

List<ZCRMRecord> insertedRecords = (List<ZCRMRecord>) response.getData();

List<BulkAPIResponse.EntityResponse> entityResponses =

response.getEntityResponses();// to check the status of the request

String rec1Status = entityResponses.get(0).getStatus();//check status of record1

String rec2Status = entityResponses.get(1).getStatus();//check status of record2

Copy sample request

Sample Request:

$zcrmModuleIns = ZCRMModule::getInstance("Invoices");
$bulkAPIResponse=$zcrmModuleIns->createRecords($recordsArray); // $recordsArray - array of ZCRMRecord instances filled with required data for creation.
$entityResponses = $bulkAPIResponse->getEntityResponses();
foreach($entityResponses as $entityResponse)
{
if("success"==$entityResponse->getStatus())
{
echo "Status:".$entityResponse->getStatus();
echo "Message:".$entityResponse->getMessage();
echo "Code:".$entityResponse->getCode();
$createdRecordInstance=$entityResponse->getData();
echo "EntityID:".$createdRecordInstance->getEntityId();
echo "moduleAPIName:".$createdRecordInstance->getModuleAPIName();
….
}
}
Sample Invoice record instance with filled data
$record=ZCRMRecord::getInstance("Invoices",null);
$record->setFieldValue("Subject","Iphone sale to John");
$record->setFieldValue("Account_Name","410405000001016021");
$productInstance=ZCRMRecord::getInstance("Products",410405000001108011);
$lineItem=ZCRMInventoryLineItem::getInstance($productInstance);
$taxInstance1=ZCRMTax::getInstance("Sales Tax");
$taxInstance1->setPercentage(2);
$taxInstance1->setValue(10);
$lineItem->addLineTax($taxInstance1);
$taxInstance1=ZCRMTax::getInstance("Vat");
$taxInstance1->setPercentage(12);
$taxInstance1->setValue(60);
$lineItem->addLineTax($taxInstance1);
$lineItem->setQuantity(100);
$lineItem->setDiscount(0.5);
$record->addLineItem($lineItem);

Copy sample request

Sample Request:

ZCRMRecord recordIns = new ZCRMRecord("Products"); //module api name
ZCRMUser owner = ZCRMUser.GetInstance(3362534000000166021); // user id
recordIns.Owner = owner;
recordIns.SetFieldValue("Product_Name", "mass_create1"); // field api name with its value
APIResponse response = recordIns.Create();
ZCRMRecord record = (ZCRMRecord)response.Data;

Copy sample request

Sample Request:

def create_record(self):
    try:
        record=ZCRMRecord.get_instance('Invoices')
        record.set_field_value('Subject', 'Inv4')
        record.set_field_value('Account_Name', 'IIIT')
        user=ZCRMUser.get_instance(1386586000000105001,'Python User1')
        record.set_field_value('Owner',user)
        line_item=ZCRMInventoryLineItem.get_instance(ZCRMRecord.get_instance("Products",1386586000000803073))
        line_item.discount=10
        line_item.list_price=8
        line_item.description='Product Description'
        line_item.quantity=100
        line_item.tax_amount=2.5
        taxIns=ZCRMTax.get_instance("Vat")
        taxIns.percentage=5
        line_item.line_tax.append(taxIns)
        record.add_line_item(line_item)
        resp=record.create()
        print resp.status_code
        print resp.code
        print resp.details
        print resp.message
        print resp.status
    except ZCRMException as ex:
        print ex.status_code
        print ex.error_message
        print ex.error_code
        print ex.error_details
        print ex.error_content

Copy sample request

Sample Request Syntax:

zoho.crm.create(<module String>,<dataMap Map>,<optionalDataMap Map>,<connectionName String>,<userAccess Boolean>);
mandatory : module,dataMap

Sample Request: Insert a Lead

resp = zoho.crm.create("Leads", {"Last_Name":"Patricia Boyle"},{"trigger":["workflow","blueprint","approval"]});

Sample Request: Insert a Price Book

resp = zoho.crm.create("Price_Books", {"Owner": {"id": 410888000000698436},"Active": true,"Pricing_Details": [{"to_range": 5,"discount": 0,"from_range": 1},{"to_range": 11,"discount": 1,"from_range": 6},{"to_range": 17,"discount": 2,"from_range": 12},{"to_range": 23,"discount": 3,"from_range": 18},{"to_range": 29,"discount": 4,"from_range": 24}],"Pricing_Model": "Differential","Description": "Design your own layouts that align your business processes precisely. Assign them to profiles appropriately.","Price_Book_Name": "Price_Book_Name"});

Sample Request: Insert a record in a Custom Module ("Students")

resp = zoho.crm.create("Students", {"Name" : "Sname"});

In the above request, @newlead.json contains the sample input data.

Note:

  • Duplicates are checked for every insert record API call based on unique fields.
  • Provide the Field API names along with the corresponding values to be populated, in the Input.
  • The trigger input can be workflow, approval or blueprint. If the trigger is not mentioned, the workflows, approvals and blueprints related to the API will get executed. Enter the trigger value as [] to not execute the workflows.
Copy sample input

Sample Input:

Copy sample response

Sample Response:

Note:

  • Records with Subform details can also be inserted to CRM using the Records API. Please look at the below link to learn more about adding subform information within a record.
Load more examples

Sample attributes:

  • The sample for Single Line:

    "Single_Line_1": "This is single line",

  • The sample for Multi Line:

    "Multi_Line_1": "This is the first line \n Now for the second Line",

  • The sample for Email:

    "Email_1": "p.boyle@zylker.com",

  • The sample for Phone:

    "Phone_1": "9900000000",

  • The sample for Picklist:

    "Picklist_1" : "In Progress",

  • The sample for Multi-select picklist:

    "Multi-Select_Picklist" : [
        "{Option_1}",
        "{Option_2}",
        "{Option_3}"

        ],

  • The sample for Date:

    "Date_1": "2017-08-16",

  • The sample for Date/time:

    "Date_Time": "2017-08-16T14:32:23+05:30",

  • The sample for Number:

    "Number_1": 575,

  • The sample for Currency:

    "Currency_1": 250000,

  • The sample for Decimal:

    "Decimal_1": 250000.50,

  • The sample for Percent:

    "Percent_1": 25,

  • The sample for Long Integer:

    "Long_Integer_1": "250000000000000",

  • The sample for Checkbox:

    "Checkbox_1": false,

  • The sample for URL:

    "URL_1": "https://www.zoho.com/crm",

  • The sample for Lookup:

    "Lookup" : {
        "id" : "425248000000104001"
        },

  • The sample for the Record owner:

    "Owner": {
        "id": "425248000000104003"
        },

  • The sample for the Layout:

    "Layout": {
        "id": "425248000000404433"
        },

Update a specific record

Purpose

To update a particular entity or record

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}/{record_id}

module_api_name - The api name of the module.

record_id - Specify the unique id of the record.

Scope

scope=ZohoCRM.modules.all
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, tasks, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, custom, notes and activities. ALL - Full access to a record
WRITE - edit records in a module
UPDATE - update records in a module

Request Method

PUT

Note:

  • An error is thrown if the field value length is more than the maximum length defined for that field.
  • If an API used inside a Function when the field value length exceeds the limit, then that function receives error response from the API. For ex: If the max length for a "Text field" is defined as 10, then value given for it in API cannot be "12345678901", as it has 11 characters.
Curl Java PHP Python Functions C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Leads/410888000000698006"

-X PUT

-d "@updatelead.json"

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

In the above sample, the lead record with id "410888000000698006" will be updated.

Copy sample request

Sample Request:

ZCRMRecord record = ZCRMRecord.getInstance("Products",1234567l);// module api name with its record id

record.setFieldValue("Product_Name","name");// field api name with the value to be updated

ZCRMRecord lookup = ZCRMRecord.getInstance("Vendors",123456789l);// vendor module api name with its record id

record.setFieldValue("Vendor_Name", lookup);

APIResponse response = record.update();

ZCRMRecord updatedRecord = (ZCRMRecord) response.getData();

String recStatus = response.getStatus(); // check status of the record

Copy sample request

Sample Request:

$zcrmRecordIns = ZCRMRecord::getInstance("Leads", 410405000001304021);
$zcrmRecordIns->setFieldValue("Product_Name", “iPhone 6s Plus”);
$apiResponse=$zcrmRecordIns->update();

Copy sample request

Sample Request:

ZCRMRecord recordIns = ZCRMRecord.GetInstance("Products", 3372164000001633018);// module api name with its record id
recordIns.SetFieldValue("Product_Name", "name");// field api name with the value to be updated
ZCRMRecord lookup = ZCRMRecord.GetInstance("Vendors", 3372164000000531084);// vendor module api name with its record id
recordIns.SetFieldValue("Vendor_Name", lookup);
APIResponse response = recordIns.Update();
ZCRMRecord updatedRecord = (ZCRMRecord)response.Data;

Copy sample request

Sample Request:

def update_record(self):
    try:
        record=ZCRMRecord.get_instance('Leads',1386586000001856002)#1386586000001856002 is leadid
        record.set_field_value('Last_Name', 'Python')
        record.set_field_value('Mobile', '9999999999')
        record.set_field_value('Phone', '9999999998')
        user=ZCRMUser.get_instance(1386586000000105001,'Python User1')
        record.set_field_value('Email', 'support@zohocrm.com')
        record.set_field_value('Owner',user)
        resp=record.update()
        print resp.status_code
        print resp.code
        print resp.details
        print resp.message
        print resp.status
    except ZCRMException as ex:
        print ex.status_code
        print ex.error_message
        print ex.error_code
        print ex.error_details
        print ex.error_content

Copy sample request

Sample Request Syntax:

zoho.crm.update(<module String>,<recordID Long>,<dataMap Map>,<optionalDataMap Map>,<connectionName String>,<userAccess Boolean>);
mandatory : module,recordID,dataMap

Sample Request: Update a Price Book record

resp = zoho.crm.update("Price_Books", "7000000037030", {"Owner": {"id": "7000000031553"},"Active": true,"Pricing_Details": [{"to_range": 5,"discount": 0,"from_range": 1},{"to_range": 11,"discount": 1,"from_range": 6},{"to_range": 17,"discount": 2,"from_range": 12},{"to_range": 23,"discount": 3,"from_range": 18},{"to_range": 29,"discount": 4,"from_range": 24}],"Pricing_Model": "Differential","Description": "Design your own layouts that align your business processes precisely. Assign them to profiles appropriately.","Price_Book_Name": "Price_Book_Name oops1 updated twice"});

Note:

  • Duplicates are checked for every update record API call based on unique fields.
  • Provide the Field API names along with the corresponding values to be populated, in the Input.
  • The trigger input can be workflow, approval or blueprint. If the trigger is not mentioned, the workflows, approvals and blueprints related to the API will get executed. Enter the trigger value as [] to not execute the workflows.
  • If the update API calls for a record are from DRE(Functions), due to workflow triggered on the same record's create / update, then workflow alone will not get executed, irrespective of the trigger param configuration.
Copy sample input

Sample Input:

Copy sample response

Sample Response:

Note:

  • Record details can be udpated with Subform details using the Records API. Please look at the below link to learn more about updating subform information within a record.
Load more examples

Sample attributes:

  • The sample for Single Line:

    "Single_Line_1": "This is single line",

  • The sample for Multi Line:

    "Multi_Line_1": "This is the first line \n Now for the second Line",

  • The sample for Email:

    "Email_1": "p.boyle@zylker.com",

  • The sample for Phone:

    "Phone_1": "9900000000",

  • The sample for Picklist:

    "Picklist_1" : "In Progress",

  • The sample for Multi-select picklist:

    "Multi-Select_Picklist" : [
        "{Option_1}",
        "{Option_2}",
        "{Option_3}"

        ],

  • The sample for Date:

    "Date_1": "2017-08-16",

  • The sample for Date/time:

    "Date_Time": "2017-08-16T14:32:23+05:30",

  • The sample for Number:

    "Number_1": 575,

  • The sample for Currency:

    "Currency_1": 250000,

  • The sample for Decimal:

    "Decimal_1": 250000.50,

  • The sample for Percent:

    "Percent_1": 25,

  • The sample for Long Integer:

    "Long_Integer_1": "250000000000000",

  • The sample for Checkbox:

    "Checkbox_1": false,

  • The sample for URL:

    "URL_1": "https://www.zoho.com/crm",

  • The sample for Lookup:

    "Lookup" : {
        "id" : "425248000000104001"
        },

  • The sample for the Record owner:

    "Owner": {
        "id": "425248000000104003"
        },

  • The sample for the Layout:

    "Layout": {
        "id": "425248000000404433"
        },

Delete a specific record

Purpose

To delete a particular entity or record

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}/{record_id}

module_api_name - The api name of the module.

record_id - Specify the unique id of the record

Scope

scope=ZohoCRM.modules.all
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, tasks, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, custom, notes and activities. ALL - Full access to a record
WRITE - edit records in a module
DELETE - delete records in a module

Request Method

DELETE

Curl Java PHP Python C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Leads/410888000000698006"

-X DELETE

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

In the above sample, the lead record with id "410888000000698006" will be deleted.

Copy sample request

Sample Request:

ZCRMRecord record = ZCRMRecord.getInstance("Products",12347986875l);//module api name with record id

APIResponse response = record.delete();

String recStatus = response.getStatus();

Copy sample request

Sample Request:

$zcrmRecordIns = ZCRMRecord::getInstance("Products", 410405000001042005); //record id
$apiResponse=$zcrmRecordIns->delete();

Copy sample request

Sample Request:

ZCRMRecord record = ZCRMRecord.GetInstance("Products", 3372164000001633018);//module api name with record id
APIResponse response = record.Delete();

Copy sample request

Sample Request:

def delete_record(self):
    try:
        record=ZCRMRecord.get_instance('Leads',1386586000001422011)#1386586000001422011 is leadid
        resp=record.delete()
        print resp.status_code
        print resp.code
        print resp.details
        print resp.message
        print resp.status
    except ZCRMException as ex:
        print ex.status_code
        print ex.error_message
        print ex.error_code
        print ex.error_details
        print ex.error_content

Note:

  • By default, all the workflows related to this API will get executed.
  • All the subforms related to this API will get deleted.
Copy sample response

Sample Response:

Convert Lead

Purpose

To convert a lead

Request URL

https://www.zohoapis.com/crm/v2/Leads/{record_id}/actions/convert

record_id - Specify the unique id of a record.

Scope

scope=ZohoCRM.modules.all
(or)
scope=ZohoCRM.modules.leads.{operation_type}

Possible operation types
ALL - Full access to a record
WRITE - edit records in a module
CREATE - create records in a module

Request Method

POST

Curl Java PHP Python Functions C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Leads/1000000145990/actions/convert"

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

-d "@convertlead.json"

-X POST

In the above request, @convertlead.json contains the sample input.

Copy sample request

Sample Request:

ZCRMRecord record = ZCRMRecord.getInstance("Leads", 3247354544l);//module api name with record id
HashMap<String,Long> map = record.convert();
//returns a map as {"Accounts":"42685937005","Deals":null,"Contacts":"42685937007"}
Long accountsId = map.get("Accounts");
Long dealsId = map.get("Deals");
Long contactsId = map.get("Contacts");

Copy sample request

Sample Request:

$record=ZCRMRecord::getInstance("Leads",410405000001518001); // 410405000001518001 - Lead ID.
$modIns=ZCRMModule::getInstance("Deals");
$record_deal=$modIns->getRecord(410405000001519001)->getData(); // 410405000001519001 - Deal ID.
$user_instance=ZCRMUser::getInstance(410405000001516001, null);
$responseMap=$record->convert($record_deal,$user_instance);
echo "Contact ID:".$responseMap['Contacts'];
if(isset($responseMap[“Accounts”]))
{
echo "Account ID:".$responseMap[“Accounts”];
}
if(isset($responseMap[“Deals”]))
{
echo "Deal ID:".$responseMap[“Deals”];
}

Copy sample request

Sample Request:

ZCRMRecord record = ZCRMRecord.GetInstance("Leads", 3372164000001606016); //module api name with record id
ZCRMRecord potentialRecord = new ZCRMRecord("Deals"); // module api name
potentialRecord.SetFieldValue("Stage", "Qualification");
potentialRecord.SetFieldValue("Closing_Date", "2019-01-25");
potentialRecord.SetFieldValue("Deal_Name", "Deal_Name");
ZCRMUser user = ZCRMUser.GetInstance(3372164000001253020);
Dictionary<string,long> response = record.Convert(potentialRecord,user); // response is KeyValuePair

Copy sample request

Sample Request:

def convert_record(self):
    try:
        record=ZCRMRecord.get_instance('Leads',1386586000001422007)#1386586000001422007 is leadid
        potential_record=ZCRMRecord.get_instance('Deals')
        potential_record.set_field_value('Deal_Name', 'SAI1')
        potential_record.set_field_value('Closing_Date', '2017-10-10')
        potential_record.set_field_value('Stage', 'Needs Analysis')
        assign_to_user=ZCRMUser.get_instance(1386586000000105001, None)
        resp=record.convert(potential_record, assign_to_user)
        print resp
        print resp[APIConstants.ACCOUNTS]
        print resp[APIConstants.DEALS]
        print resp[APIConstants.CONTACTS]
    except ZCRMException as ex:
        print ex.status_code
        print ex.error_message
        print ex.error_code
        print ex.error_details
        print ex.error_content

Copy sample request

Sample Request Syntax:

zoho.crm.convertLead(<leadId Long>,<dataMap Map>,<connectionName String>,<userAccess Boolean>);
mandatory : leadId,dataMap

Sample Request:

resp = zoho.crm.convertLead("7000000037308", { "overwrite": true, "notify_lead_owner": false, "notify_new_entity_owner": true, "Accounts": "7000000037323", "Deals": { "Deal_Name": "Robert", "Closing_Date": "2016-03-30", "Stage": "Closed Won", "Amount": 56.6 } });

Copy sample input

Sample Input:

Note:

1. In the input shown above, the assign_to value can only be the User ID.

2. You can associate the existing contact or account to the converting lead even if the lead is converted or not converted to a deal. To achieve this, you have to send the account id and contact id in your input data.

3. If both account id and overwrite values are true, then the account name will be replaced by the company name, while associating it with the existing account. However, the data of that account will remain the same.

4. If overwrite value is set false, then association will only happen. However, if you set the overview value without account id, the working of this method remains unchanged.

5. If contact id is given in your input, then the converting lead will be associated to the existing contact.

Copy sample response

Sample Response:

Subform APIs

A subform is a secondary form or a table, which will enable you to include multiple line items into a primary form. They are used to associate multiple items to a single record. On a more technical perspective, subforms easily solve the need for you to establish a one-to-many relationship with data in your CRM, in which many secondary items are associated to a single primary record.

The subform API is avaliable only in Enterprise and above editions of Zoho CRM.

Points-to-remember:

  • The parent Module API name can be acquired using the module API.
  • The Field API name of the subform is acquired using Fields meta data API of the parent module.
  • The Field API names of the individual fields in a subform are acquired using Fields meta data API, with the request URL as "fields?module={Sub_form_api_name}".
  • A maximum of 5 aggregate custom fields are available for a subform.

Scope

scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, solutions, products, vendors, custom, notes and activities. ALL - Full access to a record
READ - get records in a module
WRITE - edit records in a module
CREATE - create records in a module
UPDATE - update records in a module

The Subform API supports

Single Record APIs:


Bulk Record APIs:

Note:

  • When updating a subform record, the "ID" of the record (Ex: Lead ID) must be specified in the input.
  • When updating a subform record, the "ID" of the subform records must be specified.
  • Assuming that there are 3 rows(records) within the subform, if it is updated with a new record, the IDs of the other three subform records have to be mentioned. The record without the ID will get deleted. For example, if subform is updated with a new record along with records 1,3 then it will delete record 2 and create a new record (suppose with Id 4). The current subform records are 1, 3 and 4.
  • Update of subform records without any JSON objects deletes the subform information within the record. Ex: " subform_1:[] "
  • Whenever a record is deleted, all the subform details within the parent record will also get deleted.

Blueprint APIs

Zoho CRM's Blueprint is simply an online replica of a business process. It captures every detail of your entire offline process within the software. It facilitates automation, validation and collaboration of teams, thus making your process more efficient and free from loopholes.

Get blueprint data

Purpose

To get the next available transitions for that record, fields available for each transitions, current value of each field and their validation(if any).

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}/{id}/actions/blueprint

module_api_name - The api name of the module.

id - Specify the unique id of the record.

Scope

scope=ZohoCRM.modules.all
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, tasks, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, custom, notes, approvals, dashboards, search and activities. ALL - Full access to record
READ - get records from a module

Request Method

GET

Curl
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Leads/410888000000698006/actions/blueprint"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

ZCRMModule module = ZCRMModule.getInstance("Products");

BulkAPIResponse response = module.getRecords(425476547854l, "Company",

CommonUtil.SortOrder.asc, 1, 4);// get Records with cvID, sortField,

sortOrder, startIndex and endIndex.

List<ZCRMRecord> records = (List<ZCRMRecord>)response.getData();

Copy sample request

Sample Request:

$zcrmModuleIns = ZCRMModule::getInstance("Contacts");
$bulkAPIResponse=$zcrmModuleIns->getRecords();
$recordsArray = $bulkAPIResponse->getData(); // $recordsArray - array of ZCRMRecord instances

Copy sample request

Sample Request:

Hash of record id vs record obj - Hash<String, ZCRMRecord>

zclient, api_obj = ZohoCRMClient.get_client_objects(conf_file_location)
records = record_obj.get_records(200)
records.each do |record_id, record_obj|
print “Record id: #{record_id}”
print “Record object class: #{record_obj.class}”
end

Copy sample request

Sample Request:

def get_records(self):

  try:

    module_ins=ZCRMModule.get_instance('Products') #module API Name

    resp=module_ins.get_records()

    print resp.status_code

    record_ins_arr=resp.data

    for record_ins in record_ins_arr:

      print record_ins.entity_id

      print record_ins.owner.id

      print record_ins.created_by.id

      print record_ins.modified_by.id

      print record_ins.created_time

      print record_ins.modified_time

      product_data=record_ins.field_data

      for key in product_data:

        print key+":"+str(product_data[key])

      print "\n\n"

  except ZCRMException as ex:

    print ex.status_code

    print ex.error_message

    print ex.error_code

    print ex.error_details

    print ex.error_content

Copy sample request

Sample Request Syntax:

zoho.crm.getRecords(<module String>,<page Long>,<perPage Long>,<optionalDataMap Map>,<connectionName String>,<userAccess Boolean>);
mandatory : module

Sample Request:

resp = zoho.crm.getRecords("Leads",5,2,{"converted":"false"});

Copy sample response

Sample Response:

Update Blueprint Details

Purpose

To update a single transition at a time. An error will be thrown if the record is not in transition, transition_id is wrong, field_value data type mismatches or field validation fails.

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}/{id}/actions/blueprint

module_api_name - The api name of the module.

id - Specify the unique id of the record.

Scope

scope=ZohoCRM.modules.all
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, tasks, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, custom, notes. ALL - Full access to record
WRITE - edit records in a module
CREATE - create records in a module

Request Method

PUT

Curl
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Leads/410888000000698006/actions/blueprint"

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

-d "@blueprint1.json"

-X POST

Copy sample request

Sample Request:

List<ZCRMRecord> records = new ArrayList<>();

ZCRMRecord record1 = new ZCRMRecord("Products"); //module api name

ZCRMUser owner = ZCRMUser.getInstance(12345678l);// user id

record1.setOwner(owner);

record1.setFieldValue("Product_Name", "mass_create1");// field api name with its value

ZCRMRecord record2 = new ZCRMRecord("Products"); //module api name

ZCRMUser owner = ZCRMUser.getInstance(5676875678l);// user id

record2.setOwner(owner);

record2.setFieldValue("Product_Name", "mass_create2");// field api name with its value

records.add(record1);

records.add(record2);

ZCRMModule module = ZCRMModule.getInstance("Products"); //module api name

BulkAPIResponse response = module.createRecords(records);

List<ZCRMRecord> insertedRecords = (List<ZCRMRecord>) response.getData();

List<BulkAPIResponse.EntityResponse> entityResponses =

response.getEntityResponses();// to check the status of the request

String rec1Status = entityResponses.get(0).getStatus();//check status of record1

String rec2Status = entityResponses.get(1).getStatus();//check status of record2

Copy sample request

Sample Request:

$zcrmModuleIns = ZCRMModule::getInstance("Invoices");
$bulkAPIResponse=$zcrmModuleIns->createRecords($recordsArray); // $recordsArray - array of ZCRMRecord instances filled with required data for creation.
$entityResponses = $bulkAPIResponse->getEntityResponses();
foreach($entityResponses as $entityResponse)
{
if("success"==$entityResponse->getStatus())
{
echo "Status:".$entityResponse->getStatus();
echo "Message:".$entityResponse->getMessage();
echo "Code:".$entityResponse->getCode();
$createdRecordInstance=$entityResponse->getData();
echo "EntityID:".$createdRecordInstance->getEntityId();
echo "moduleAPIName:".$createdRecordInstance->getModuleAPIName();
….
}
}
Sample Invoice record instance with filled data
$record=ZCRMRecord::getInstance("Invoices",null);
$record->setFieldValue("Subject","Iphone sale to John");
$record->setFieldValue("Account_Name","410405000001016021");
$productInstance=ZCRMRecord::getInstance("Products",410405000001108011);
$lineItem=ZCRMInventoryLineItem::getInstance($productInstance);
$taxInstance1=ZCRMTax::getInstance("Sales Tax");
$taxInstance1->setPercentage(2);
$taxInstance1->setValue(10);
$lineItem->addLineTax($taxInstance1);
$taxInstance1=ZCRMTax::getInstance("Vat");
$taxInstance1->setPercentage(12);
$taxInstance1->setValue(60);
$lineItem->addLineTax($taxInstance1);
$lineItem->setQuantity(100);
$lineItem->setDiscount(0.5);
$record->addLineItem($lineItem);

Copy sample request

Sample Request:

zclient, api_obj = ZohoCRMClient.get_client_objects(conf_file_location)
accounts_module = api_obj.load_crm_module(“Accounts”)
records = []
record1 = accounts_module.get_new_record
user_id = “1234567890”
record1.set_owner(user_id, api_obj.load_user_data)
record1.setfield_byname(“Account_Name”, “Account 1”)
record2 = accounts_module.get_new_record
records[records.length] = record1
record2.set_owner(user_id, api_obj.load_user_data)
record1.setfield_byname(“Account_Name”, “Account 2”)
records[records.length] = record2
bool, message, ids = upsert(records)
print “Ids for the newly created records are #{ids.inspect}”

Copy sample request

Sample Request:

def create_records(self):

  try:

    record_ins_list=list()

    for i in range(0,2):

      record=ZCRMRecord.get_instance('Invoices') #module API Name

      record.set_field_value('Subject', 'Invoice'+str(i))

      record.set_field_value('Account_Name', 'IIIT')

      user=ZCRMUser.get_instance(440872000000175001,'Python Automation User1')

      record.set_field_value('Owner',user)

      line_item=ZCRMInventoryLineItem.get_instance(ZCRMRecord.get_instance("Products",440872000000224005))

      line_item.discount=10

      line_item.list_price=8

      line_item.description='Product Description'

      line_item.quantity=100

      line_item.tax_amount=2.5

      taxIns=ZCRMTax.get_instance("Vat")

      taxIns.percentage=5

      line_item.line_tax.append(taxIns)

      record.add_line_item(line_item)

      record_ins_list.append(record)

    resp=ZCRMModule.get_instance('Invoices').create_records(record_ins_list)

    print resp.status_code

    entity_responses=resp.bulk_entity_response

    for entity_response in entity_responses:

      print entity_response.details

      print entity_response.status

      print entity_response.message

      print entity_response.code

      print entity_response.data.entity_id

      print entity_response.data.created_by.id

      print entity_response.data.created_time

      print entity_response.data.modified_by.id

      print "\n\n"

  except ZCRMException as ex:

    print ex.status_code

    print ex.error_message

    print ex.error_code

    print ex.error_details

    print ex.error_content

Copy sample request

Sample Request Syntax:

zoho.crm.bulkCreate(<module String>,<dataList List>,<optionalDataMap Map>,<connectionName String>,<userAccess Boolean>);
mandatory : module,dataList

Sample Request: Creating Price Book records

resp = zoho.crm.bulkCreate("Price_Books", [{"Owner": {"id": "7000000031553"},"Active": true,"Pricing_Details": [{"to_range": 5,"discount": 0,"from_range": 1},{"to_range": 11,"discount": 1,"from_range": 6},{"to_range": 17,"discount": 2,"from_range": 12},{"to_range": 23,"discount": 3,"from_range": 18},{"to_range": 29,"discount": 4,"from_range": 24}],"Pricing_Model": "Differential","Description": "Design your own layouts that align your business processes precisely. Assign them to profiles appropriately.","Price_Book_Name": "Price_Book_Name oops1"},{"Owner": {"id": "7000000031553"},"Active": true,"Pricing_Details": [{"to_range": 5,"discount": 0,"from_range": 1},{"to_range": 11,"discount": 1,"from_range": 6},{"to_range": 17,"discount": 2,"from_range": 12},{"to_range": 23,"discount": 3,"from_range": 18},{"to_range": 29,"discount": 4,"from_range": 24}],"Pricing_Model": "Differential","Description": "Design your own layouts that align your business processes precisely. Assign them to profiles appropriately.","Price_Book_Name": "Price_Book_Name oops2"}]);

Sample Request: Inserting Leads

resp = zoho.crm.bulkCreate("Leads", [{"Last_Name":"Patricia Boyle"},{"Last_Name":"Deborah Grogan"}], {"trigger":["workflow","blueprint","approval"]});

Sample Request: Creating records in a Custom Module ("Students")

resp=zoho.crm.bulkCreate("Students",[{"Name":"Patricia Boyle new","Owner":"7000000031553","Email":"p.boyle@zylker.com","Secondary_Email":"sdf@zylker.com","Single_Line":"Single_Line 22 new","Multi_Line_1":"Room for Negotiation","Currency_1":1.245,"Email_1":"adf@aps.com","Email_Opt_Out":true,"Decimal_1":2.34,"Phone_1":"9000000000","Percent_1":9,"Tag":{"tag"},"Pick_List_1":"new pick list","Long_Integer_1":"123456789012345690","Multi_Select_1":["Val 1","Val 2"],"Checkbox_1":true,"Date_1":"2018-01-31","website":"www.zoho.@","Date_Time_1":"2018-02-01T12:30:00+05:30","Lookup_1":{"id":"7000000032001"},"Number_1":1},{ "Name":"Deborah Grogan","Owner":"7000000031553","Email":"d.grogan@zylker.com","Secondary_Email":"dgrgn@zylker.com","Single_Line":"Single_Line 23 new","Multi_Line_1":"Negotiation succeeded","Currency_1":1.245,"Email_1":"adf@aps.com","Email_Opt_Out":true,"Decimal_1":2.34,"Phone_1":"9000000000","Percent_1":9,"Tag":{"tag"},"Pick_List_1":"new pick list","Long_Integer_1":"123456789012345690","Multi_Select_1":["Val 1","Val 2"],"Checkbox_1":true,"Date_1":"2018-01-31","website":"www.zylker.com","Date_Time_1":"2018-02-01T12:30:00+05:30","Lookup_1":{"id":"7000000032001"},"Number_1":1}]);

In the above request, @blueprint1.json contains the sample input data.

Copy sample input

Sample Input: To add notes to a record in transition

Copy sample input

Sample Input: To Upload Attachments to the blueprint

Copy sample input

Sample Input: To handle Parent module fields during transition

Copy sample input

Sample Input: To update checklist information

Copy sample input

Sample Input: To update related list information

Copy sample response

Sample Response:

Note:

  • In the Related List sample, the key "Tasks" is the name of the list related to the record used in the transition.
  • The related list support for this API depends on the module of the record, which is used in the transition of the blueprint.
  • In case the number of fields in the input does not meet the required number, the "message" in the response would be "transition saved partially".

Tag APIs

Tags are keywords that help you categorize your records based on their characteristics. Tags help you sort your data and find it easily when you need it.

Get the tags

Purpose

To get and display all the tags in an organization.

Request URL

http://www.zohoapis.com/crm/v2/settings/tags?module={module_api_name}

Scope

scope=ZohoCRM.settings.all
(or)
scope=ZohoCRM.settings.tags.all
(or)
scope=ZohoCRM.settings.tags.read

Request Method

GET

Parameters

Parameter Name Data Type Description
module (mandatory) String Specify the API name of the module such as, Leads, Accounts, Deals, etc,.
my_tags (optional) String Displays the names of the tags created by the current user.
Curl PHP C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/settings/tags?module=Contacts"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

ZCRMModule moduleIns = ZCRMModule.GetInstance("Leads"); //module api name
BulkAPIResponse<ZCRMTag> response = moduleIns.GetTags();
List<ZCRMTag> tags = response.BulkData; // tags - List of ZCRMTag instances

Copy sample request

Sample Request:

/** Get the tags */
$zcrmModuleIns=ZCRMModule::getInstance("Leads");
$bulkAPIResponse = $zcrmModuleIns->getTags();
$tagsArray=$bulkAPIResponse->getData(); // $tagsArray - array of ZCRMTag instances

Copy sample request

Sample Request:

Copy sample response

Sample Response:

Attributes:

  • "allowed_count" : Represents the number of Tags that can be created in the current edition.
  • "count" : Represents the total number of Tags created.

Get Record count for a specific tag

Purpose

To get the total number of records under a tag.

Request URL

https://www.zohoapis.com/crm/v2/settings/tags/{tag_id}/actions/records_count?module={module_api_name}

tag_id - Specify the unique id of the tag.

Scope

scope=ZohoCRM.settings.all
(or)
scope=ZohoCRM.settings.tags.all
(or)
scope=ZohoCRM.settings.tags.read

Request Method

GET

Parameters

Parameter Name Data Type Description
module (mandatory) String Specify the API name of the required module. For example, Leads, Contacts, Accounts, Deals, and so on.
Curl PHP C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/settings/tags/2000000039007/actions/records_count?module=Contacts"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

ZCRMModule moduleIns = ZCRMModule.GetInstance("Leads"); //module api name
APIResponse count = moduleIns.GetTagCount(3372164000001521002); //3372164000001521002 tag id
ZCRMTag tagcount = (ZCRMTag)count.Data;

Copy sample request

Sample Request:

/** Get Record count for a specific tag */
$zcrmModuleIns=ZCRMModule::getInstance("Leads");
$apiResponse = $zcrmModuleIns->getTagCount("3372164000001521001"); //3372164000001521001 tag id
$tag=$apiResponse->getData(); //$tag - ZCRMTag instances

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample response

Sample Response:

Create New Tags

Purpose

To create new tags.

Request URL

https://www.zohoapis.com/crm/v2/settings/tags?module={module_api_name}

Scope

scope=ZohoCRM.settings.all
(or)
scope=ZohoCRM.settings.tags.{operation_type}

Possible operation types
ALL - Full data access
WRITE - edit tag data
CREATE - create tag data

Request Method

POST

Parameters

Parameter Name Data Type Description
module (mandatory) String Specify the API name of the required module. For example, Leads, Contacts, Accounts, Deals, and so on.
Curl PHP C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/settings/tags?module=Contacts"

-X POST

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

-d "@createnewtag.json"

Copy sample request

Sample Request:

Copy sample request

Sample Request:

/** Create New Tags */
$zcrmModuleIns=ZCRMModule::getInstance("Leads");
$tags= array();
$tag = ZCRMTag::getInstance();
$tag->setName("Name11");
array_push($tags, $tag);
$tag = ZCRMTag::getInstance();
$tag->setName("Name21");
array_push($tags, $tag);
$bulkAPIResponse = $zcrmModuleIns->createTags($tags); //$tags - array of ZCRMTag instances
$tagsArray=$bulkAPIResponse->getData(); //$tagsArray - array of ZCRMTag instances

Copy sample request

Sample Request:

ZCRMModule moduleIns = ZCRMModule.GetInstance("Leads"); //module api name
List<ZCRMTag> tags = new List<ZCRMTag>();
ZCRMTag tag1 = ZCRMTag.GetInstance();
tag1.Name = "Name1";
ZCRMTag tag2 = ZCRMTag.GetInstance();
tag2.Name = "Name2";
tags.Add(tag1);
tags.Add(tag2);
BulkAPIResponse<ZCRMTag> response = moduleIns.CreateTags(tags); //tags - list of ZCRMTag instances filled with required data for create.
List<ZCRMTag> insertedTags = response.BulkData; //insertedTags - list of ZCRMTag instances
List<EntityResponse> entityResponses = response.BulkEntitiesResponse; //entityResponses - list of EntityResponse instance

Copy sample request

Sample Request:

Copy sample input

Sample Input:

Copy sample response

Sample Response:

Merge Tags

Purpose

To merge tags and put all the records under the two tags into a single tag.

Request URL

https://www.zohoapis.com/crm/v2/settings/tags/{tag_id}/actions/merge

tag_id - Specify the unique id of the tag.

Scope

scope=ZohoCRM.settings.all
(or)
scope=ZohoCRM.settings.tags.{operation_type}

Possible operation types
ALL - Full data access
WRITE - edit tag data
CREATE - create tag data

Request Method

POST

Curl PHP C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/settings/tags/2000000035058/actions/merge"

-X POST

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

-d "@mergetag.json"

Copy sample request

Sample Request:

ZCRMTag tagIns = ZCRMTag.GetInstance(3372164000001557003); //3372164000001557003 tag id
ZCRMTag tagmergeIns = ZCRMTag.GetInstance(3372164000001521002); //3372164000001521002 conflict tag id
APIResponse response = tagIns.Merge(tagmergeIns);
ZCRMTag merge = (ZCRMTag)response.Data;

Copy sample request

Sample Request:

/** Merge Tags */
$mergeTagIns = ZCRMTag::getInstance("3372164000001521001"); //3372164000001521001 conflict tag id
$zcrmTagIns = ZCRMTag::getInstance("3372164000001597014"); //3372164000001597014 tag id
$apiResponse = $zcrmTagIns->merge($mergeTagIns); //$mergeTagIns conflict tag instance
$tag = $apiResponse->getData(); // $tag ZCRMTag instance

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample input

Sample Input:

Copy sample response

Sample Response:

Single Tag update

Purpose

To update a tag associated with a single record or multiple records.

Request URL

https://www.zohoapis.com/crm/v2/settings/tags/{tag_id}?module={module_api_name}

tag_id - Specify the unique id of the tag.

Scope

scope=ZohoCRM.settings.all
(or)
scope=ZohoCRM.settings.tags.{operation_type}

Possible operation types
ALL - Full data access
WRITE - edit tag data
UPDATE - update tag data

Request Method

PUT

Parameters

Parameter Name Data Type Description
module (mandatory) String Specify the API name of the required module. For example, Leads, Contacts, Accounts, Deals, and so on.
Curl PHP C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/settings/tags/2000000030444?module=Contacts"

-X PUT

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

-d "@singletagupdate.json"

Copy sample request

Sample Request:

ZCRMTag tagIns = ZCRMTag.GetInstance(3372164000001536001, "Leads");//3372164000001597013 tag id ,Module Api Name
tagIns.Name = "updateName";
APIResponse response = tagIns.Update();
ZCRMTag tag = (ZCRMTag)response.Data;

Copy sample request

Sample Request:

/** Single Tag update */
$zcrmTagIns= ZCRMTag::getInstance("3372164000001597013","Leads");//3372164000001597013 tag id ,Module Api Name
$zcrmTagIns->setName("Chems");
$apiResponse = $zcrmTagIns->update();
$tag = $apiResponse->getData(); //$tag - ZCRMTag instances

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample input

Sample Input:

Copy sample response

Sample Response:

Multiple Tag updates

Purpose

To update multiple tags simultaneously.

Request URL

https://www.zohoapis.com/crm/v2/settings/tags?module={module_api_name}

Scope

scope=ZohoCRM.settings.all
(or)
scope=ZohoCRM.settings.tags.{operation_type}

Possible operation types
ALL - Full data access
WRITE - edit tag data
UPDATE - update tag data

Request Method

PUT

Parameters

Parameter Name Data Type Description
module (mandatory) String Specify the API name of the required module. For example, Leads, Contacts, Accounts, Deals, and so on.
Curl PHP C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/settings/tags?module=Contacts"

-X PUT

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

-d "@multipletagupdate.json"

Copy sample request

Sample Request:

ZCRMModule modulesIns = ZCRMModule.GetInstance("Leads");
List<ZCRMTag> tags = new List<ZCRMTag>();
ZCRMTag tag1 = ZCRMTag.GetInstance(3372164000001536001);
tag1.Name = "Name3";
ZCRMTag tag2 = ZCRMTag.GetInstance(3372164000001536002);
tag2.Name = "Name4";
tags.Add(tag1);
tags.Add(tag2);
BulkAPIResponse<ZCRMTag> response = modulesIns.UpdateTags(tags); //tags - list of ZCRMTag instances filled with required data for update.
List<ZCRMTag> updatedtags = response.BulkData; //tags - list of ZCRMTag instances
List<EntityResponse> entityResponses = response.BulkEntitiesResponse; //entityResponses - list of EntityResponse instance

Copy sample request

Sample Request:

/** Multiple Tag updates */
$zcrmModuleIns=ZCRMModule::getInstance("Leads");
$tagsArray= array();
$tag = ZCRMTag::getInstance("3372164000001597013");
$tag->setName("Name3");
array_push($tagsArray, $tag);
$tag = ZCRMTag::getInstance("3372164000001585002");
$tag->setName("Name4");
array_push($tagsArray, $tag);
$bulkAPIResponse = $zcrmModuleIns->updateTags($tagsArray); //$tagsArray - array of ZCRMTag instances
$tags = $bulkAPIResponse->getData(); //$tags - array of ZCRMTag instances

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample input

Sample Input:

Copy sample response

Sample Response:

Delete a Tag

Purpose

To delete a tag from the module

Request URL

https://www.zohoapis.com/crm/v2/settings/tags/{tag_id}

tag_id - Specify the unique id of the tag.

Scope

scope=ZohoCRM.settings.all
(or)
scope=ZohoCRM.settings.tags.{operation_type}

Possible operation types
ALL - Full data access
WRITE - edit tag data
DELETE - delete tag data

Request Method

DELETE

Curl PHP C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/settings/tags/2000000035058"

-X DELETE

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

ZCRMTag tagIns = ZCRMTag.GetInstance(3372164000001539001); //3372164000001539001 tag id
APIResponse response = tagIns.Delete();
JObject tag = response.ResponseJSON; //tag is JArray

Copy sample request

Sample Request:

/** Delete a Tag */
$zcrmTagIns = ZCRMTag::getInstance("3372164000001585001"); //3372164000001585001 tag id
$apiResponse = $zcrmTagIns->delete();
$tag = $apiResponse->getResponseJSON(); //$tag - JSON Array

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample response

Sample Response:

Add Tags to a Specific record

Purpose

To add tags to a specific record

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}/{record_id}/actions/add_tags?tag_names={tag1},{tag2}

module_api_name - The api name of the module.

record_id - Specify the unique id of a record.

Scope

scope=ZohoCRM.modules.all
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, tasks, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, custom. ALL - Full data access
WRITE - edit tag data
CREATE - create tag data

Request Method

POST

Parameters

Parameter Name Data Type Description
tag_names (mandatory) String Specify the names of the tags to be added.
over_write Boolean Specify if existing tags are to be overwritten.
Curl PHP C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Contacts/2445013000000402006/actions/add_tags?tag_names=From Email,High Priority&over_write=true"

-X POST

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

ZCRMRecord recordIns = ZCRMRecord.GetInstance("Leads", 3372164000001600009);//Module Api Name , 3372164000001254034 record id
List<string> tagNames = new List<string>{ "Name5", "Name6" };
APIResponse response = recordIns.AddTags(tagNames); //tagNames is array
ZCRMRecord record = (ZCRMRecord)response.Data;

Copy sample request

Sample Request:

/** Add Tags to a Specific record */
$zcrmRecordIns = ZCRMRecord::getInstance("Leads","3372164000001254034"); //Module Api Name , 3372164000001254034 record id
$tagNames = array("Name5","Name6");
$apiResponse = $zcrmRecordIns->addTags($tagNames); //$tagNames is array
$record = $apiResponse->getData(); //$record - ZCRMRecord instances

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample response

Sample Response:

Add Tags to Multiple records

Purpose

To add tags to multiple records simultaneously.

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}/actions/add_tags?ids={entity_id}&tag_names={tag1},{tag2}

module_api_name - The api name of the module.

Scope

scope=ZohoCRM.modules.all
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, tasks, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, custom. ALL - Full data access
WRITE - edit tag data
CREATE - create tag data

Request Method

POST

Parameters

Parameter Name Data Type Description
tag_names String Specify the names of the tags to be added.
over_write Boolean Specify if the existing tags are to be overwritten.
ids (mandatory) Integer Specify the unique identifier for a record.
Curl PHP C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Contacts/actions/add_tags?ids=1234567890,123456789&tag_names=From Email,High Priority&over_write=true"

-X POST

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

ZCRMModule moduleIns = ZCRMModule.GetInstance("Leads"); // module api name
List<string> tagNames = new List<string>{ "Name7", "Name8" };
List<long> recordIds = new List<long>{3372164000001494008,3372164000001295433};
BulkAPIResponse<ZCRMRecord> response = moduleIns.AddTagsToRecords(recordIds, tagNames); //recordIds list of record id, tagNames list of tag names
List<ZCRMRecord> records = response.BulkData; //records - list of ZCRMRecord instances
List<EntityResponse> entityResponses = response.BulkEntitiesResponse; // entityResponses - list of EntityResponse instance

Copy sample request

Sample Request:

/** Add Tags to Multiple records */
$zcrmModuleIns = ZCRMModule::getInstance("Leads");
$tagNames = array("Name7","Name8");
$recordids = array("3372164000001494008","3372164000001295433");
$bulkAPIResponse = $zcrmModuleIns->addTagsToRecords($recordids, $tagNames); //$recordids array of record id, $tagName array of tag names
$records = $bulkAPIResponse->getData(); //$records - array of ZCRMRecord instances

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample response

Sample Response:

Remove Tags from a Specific record

Purpose

To delete the tag assocaited with a specific record

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}/{record_id}/actions/remove_tags?tag_names={tag1},{tag2}

module_api_name - The api name of the module.

record_id - Specify the unique id of a record.

Scope

scope=ZohoCRM.modules.all
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, tasks, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, custom. ALL - Full data access
WRITE - edit tag data
DELETE - delete tag data

Request Method

POST

Parameters

Parameter Name Data Type Description
tag_names (mandatory) String Specify the names of the tags to be removed from the record.
Curl PHP C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Contacts/2445013000000402006/actions/remove_tags?&tag_names=From Email,Low Priority"

-X POST

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

ZCRMRecord recordIns = ZCRMRecord.GetInstance("Leads", 3372164000001600009);//Module Api Name , 3372164000001254034 record id
List<string> tagNames = new List<string> { "Name5", "Name6" };
APIResponse response = recordIns.RemoveTags(tagNames); //tagNames is array
ZCRMRecord record = (ZCRMRecord)response.Data;

Copy sample request

Sample Request:

/** Remove Tags from a Specific record */
$zcrmRecordIns = ZCRMRecord::getInstance("Leads","3372164000001254034");
$tagNames = array("Name5","Name6");
$apiResponse = $zcrmRecordIns->removeTags($tagNames); //$tagNames is array
$record = $apiResponse->getData(); //$record - ZCRMRecord instances

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample response

Sample Response:

Remove Tags from Multiple records

Purpose

To delete the tags associated with multiple records.

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}/actions/remove_tags?ids={entity_id}&tag_names={tag1},{tag2}

module_api_name - The api name of the module.

Scope

scope=ZohoCRM.modules.all
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, tasks, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, custom. ALL - Full data access
WRITE - edit tag data
DELETE - delete tag data

Request Method

POST

Parameters

Parameter Name Data Type Description
ids (mandatory) Integer Specify the unique identifier of the records.
tag_names (mandatory) String Specify the names for the tags to be removed from the records.
Curl PHP C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Contacts/actions/remove_tags?ids=1234567890,123456789&tag_names=From Email,In progress"

-X POST

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

ZCRMModule moduleIns = ZCRMModule.GetInstance("Leads"); // module api name
List<string> tagNames = new List<string> { "Name7", "Name8" };
List<long> recordIds = new List<long> { 3372164000001494008, 3372164000001295433 };
BulkAPIResponse<ZCRMRecord> response = moduleIns.RemoveTagsFromRecords(recordIds, tagNames); //recordIds list of record id, tagNames list of tag names
List<ZCRMRecord> records = response.BulkData; //records - list of ZCRMRecord instances
List<EntityResponse> entityResponses = response.BulkEntitiesResponse; // entityResponses - list of EntityResponse instance

Copy sample request

Sample Request:

/** Remove Tags from Multiple records */
$zcrmModuleIns = ZCRMModule::getInstance("Leads");
$tagNames = array("Name7","Name8");
$recordids = array("3372164000001494008","3372164000001295433");
$bulkAPIResponse = $zcrmModuleIns->removeTagsFromRecords($recordids, $tagNames); //$recordids array of record id, $tagName array of tag names
$records = $bulkAPIResponse->getData(); //$records - array of ZCRMRecord instances

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample response

Sample Response:

Notes APIs

Notes are to provide some additional information about a contact, account, deal or task. The notes section can be found in most of the modules. Hence, with Notes API, you can create, delete or update notes. You can perform actions on single or multiple notes.

Get notes

Purpose

To get the list of notes

Request URL

https://www.zohoapis.com/crm/v2/Notes

Scope

scope=ZohoCRM.modules.notes.{operation_type}

Possible operation types
ALL - Full access to notes
READ - get note data

Parameters

Parameter Name Data Type Description
page (optional) Integer To get the list of records from the respective pages. Default value for page is 1.
per_page (optional) Integer To get the list of records available per page. Default value for per page is 200.

Note:

The page and per_page parameter is used to fetch records according to their position in the CRM. Let's assume that the user has to fetch 400 records. The maximum number of records that one can get for an API call is 200. So, for records above the 200th position, they cannot be fetched. By using the page (1, 2, 3 and 4) and per_page (100) parameter, the user can fetch all 400 records using 4 API calls.

Request Method

GET

Curl
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Notes"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

Copy sample response

Sample Response:

Get specific notes data

Purpose

To get the list of notes of a particular record of the module

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}/{record_id}/Notes

module_api_name - The api name of the module.

record_id - Specify the unique id of a record.

Scope

scope=ZohoCRM.modules.all
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, tasks, events, calls, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, custom. ALL - Full access to notes
READ - get note data

Request Method

GET

Curl Java PHP Python C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Leads/410888000000698006/Notes"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

The above request will retrieve the list of notes of a Lead's record with id 410888000000698006.

Copy sample request

Sample Request:

ZCRMRecord record = ZCRMRecord.getInstance("Leads",123456l);//module api name with record id
BulkAPIResponse response = record.getRelatedListRecords("Notes");
List<ZCRMNote> notes = (List<ZCRMNote>) response.getData();//relatedList name

Copy sample request

Sample Request:

try{
$record=ZCRMRecord::getInstance("Leads",410405000001111007);
$responseIns=$record->getNotes(null,null,1,50);
$records=$responseIns->getData();
foreach ($records as $note)
{
echo "\n";
echo $note->getId();
echo $note->getTitle();
echo $note->getContent();
$parentRecord=$note->getParentRecord();
echo $parentRecord->getEntityId();
echo $note->getParentName();
echo $note->getParentId();
$createdBy=$note->getCreatedBy();
echo $createdBy->getId();
echo $createdBy->getName();
$modifiedBy=$note->getModifiedBy();
echo $modifiedBy->getId();
echo $modifiedBy->getName();
$owner=$note->getOwner();
echo $owner->getId();
echo $owner->getName();
echo $note->getCreatedTime();
echo $note->getModifiedTime();
echo $note->isVoiceNote();
echo $note->getSize();
$attchments=$note->getAttachments();
if($attchments!=null)
{
foreach ($attchments as $attchmentIns)
{
echo "\nATTACHMENTS::\n";
echo $attchmentIns->getId();
echo $attchmentIns->getFileName();
echo $attchmentIns->getFileType();
echo $attchmentIns->getSize();
echo $attchmentIns->getParentModule();
$parentRecord=$attchmentIns->getParentRecord();
echo $parentRecord->getEntityId();
echo $attchmentIns->getParentName();
echo $attchmentIns->getParentId();
$createdBy=$attchmentIns->getCreatedBy();
echo $createdBy->getId();
echo $createdBy->getName();
$modifiedBy=$attchmentIns->getModifiedBy();
echo $modifiedBy->getId();
echo $modifiedBy->getName();
$owner=$attchmentIns->getOwner();
echo $owner->getId();
echo $owner->getName();
echo $attchmentIns->getCreatedTime();
echo $attchmentIns->getModifiedTime();
}
}
}
}catch (ZCRMException $e)
{
echo $e->getCode();
echo $e->getMessage();
echo $e->getExceptionCode();
}

Copy sample request

Sample Request:

zclient, api_obj = ZohoCRMClient.get_client_objects(conf_file_location)
accounts_module = api_obj.load_crm_module(“Accounts”)
account_id = “1234567890”
record = accounts_module.get_record(account_id)
notes = record.get_notes

Copy sample request

Sample Request:

ZCRMRecord recordIns = ZCRMRecord.GetInstance("Leads", 3372164000000614001); //module api name with record id
BulkAPIResponse<ZCRMNote> response = recordIns.GetNotes();
List<ZCRMNote> notes = response.BulkData; //notes - list of ZCRMNote instance

Copy sample request

Sample Request:

def get_notes(self):

  try:

    record=ZCRMRecord.get_instance('Leads',440872000000222019) #module API Name, entityId

    resp=record.get_notes()

    print resp.status_code

    note_ins_arr=resp.data

    for note_ins in note_ins_arr:

          print note_ins.id

          print note_ins.title

          print note_ins.content

          print note_ins.owner.id

          print note_ins.created_by.id

          print note_ins.modified_by.id

          print note_ins.created_time

          print note_ins.modified_time

          print "\n\n"

  except ZCRMException as ex:

      print ex.status_code

      print ex.error_message

      print ex.error_code

      print ex.error_details

      print ex.error_content

Copy sample response

Sample Response:

Create notes

Purpose

To add new notes

Request URL

https://www.zohoapis.com/crm/v2/Notes

Scope

scope=ZohoCRM.modules.notes.{operation_type}

Possible operation types
ALL - Full access to notes
WRITE - edit note data
CREATE - create note data

Request Method

POST

Curl
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Notes"

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

-d "@newnote.json"

-X POST

Note:

In the above request, @newnote.json contains the sample input.

In the Input, specify the field API names of the Notes module along with the corresponding values.

Copy sample input

Sample Input:

Copy sample request

Sample Response:

Create specific notes

Purpose

To add new notes to a particular record

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}/{record_id}/Notes

module_api_name - The api name of the module.

record_id - Specify the unique id of a record.

Scope

scope=ZohoCRM.modules.all
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, tasks, events, calls, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, custom. ALL - Full data access
WRITE - edit note data
CREATE - create note data

Request Method

POST

Curl Java PHP Python C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Leads/1000000145990/Notes"

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

-d "@newnote.json"

-X POST

In the above request, @newnote.json contains the sample input.

Copy sample request

Sample Request:

ZCRMRecord record = ZCRMRecord.getInstance("Products",23857634545l);//module api name with record id

ZCRMNote note = new ZCRMNote(record);

note.setContent("test msg");

note.setTitle("test class notes");

APIResponse response = record.addNote(note);

ZCRMNote createdNote = (ZCRMNote) response.getData();

String recStatus =response.getStatus();

Copy sample request

Sample Request:

try{
$record=ZCRMRecord::getInstance('Accounts',410405000000497012);
$noteIns=ZCRMNote::getInstance($record);
$noteIns->setTitle("Title_API1");
$noteIns->setContent("This is test content");
$responseIns=$record->addNote($noteIns);
$zcrmNote=$responseIns->getData();
echo "HTTP Status Code:".$responseIns->getHttpStatusCode();
echo "Status:".$responseIns->getStatus();
echo "Message:".$responseIns->getMessage();
echo "Code:".$responseIns->getCode();
echo "Details:".$responseIns->getDetails()['id'];
echo "Entity Id:".$zcrmNote->getId();
}
catch (ZCRMException $e)
{
echo $e->getCode();
echo $e->getMessage();
echo $e->getExceptionCode();
}

Copy sample request

Sample Request:

def add_note(self):

try:

    record=ZCRMRecord.get_instance('Leads',1386586000001856002)

    note_ins=ZCRMNote.get_instance(record, None)

    note_ins.title="title2"

    note_ins.content='content2...'

    resp=record.add_note(note_ins)

    print resp.status_code

    print resp.code

    print resp.data.id

    print resp.message

    print resp.status

  except ZCRMException as ex:

    print ex.status_code

    print ex.error_message

    print ex.error_code

    print ex.error_details

    print ex.error_content

Copy sample request

Sample Request:

ZCRMRecord recordIns = ZCRMRecord.GetInstance("Leads", 3372164000001601006); //module api name with record id
ZCRMNote note = new ZCRMNote(recordIns);
note.Content = "test msg";
note.Title = "test class notes";
APIResponse response = recordIns.AddNote(note);
ZCRMNote createdNote = (ZCRMNote)response.Data;

Note:

In the Input, specify the field API names of the Notes module along with the corresponding values.

Copy sample input

Sample Input:

Copy sample response

Sample Response:

Update notes

Purpose

To update the existing note

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}/{record_id}/Notes/{note_id}

module_api_name - The api name of a module.

record_id - Specify the unique id of a record.

note_id - Specify the unique id of a note.

Scope

scope=ZohoCRM.modules.all
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, tasks, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, custom. ALL - Full access to notes
WRITE - edit note data
UPDATE - update note data

Request Method

PUT

Curl Java PHP Python C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Leads/410888000000645234/Notes/410888000000643123"

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

-d "@updatenote.json"

-X PUT

In the above request, @updatenote.json contains the sample input.

Copy sample request

Sample Request:

ZCRMRecord record = ZCRMRecord.getInstance("Products",23857634545l);//module api name with record id

ZCRMNote note = ZCRMNote.getInstance(record,374968745l);// notesID

note.setContent("update message");

APIResponse response = record.updateNote(note);

ZCRMNote updatedNote = (ZCRMNote) response.getData();

String recStatus =response.getStatus();

Copy sample request

Sample Request:

try{
$record=ZCRMRecord::getInstance('Accounts',410405000000497012); // 410405000000497012 - Account ID.
$noteIns=ZCRMNote::getInstance($record,410405000000498056); // , 410405000000498056 - Note ID
$noteIns->setTitle("Title_API22..");
$noteIns->setContent("This is test content");
$responseIns=$record->updateNote($noteIns);
$zcrmNote=$responseIns->getData();
echo "HTTP Status Code:".$responseIns->getHttpStatusCode();
echo "Status:".$responseIns->getStatus();
echo "Message:".$responseIns->getMessage();
echo "Code:".$responseIns->getCode();
echo "Details:".$responseIns->getDetails()['id'];
echo "Entity Id:".$zcrmNote->getId();
}
catch (ZCRMException $e)
{
echo $e->getCode();
echo $e->getMessage();
echo $e->getExceptionCode();
}

Copy sample request

Sample Request:

zclient, api_obj = ZohoCRMClient.get_client_objects(conf_file_location)
accounts_module = api_obj.load_crm_module(“Accounts”)
account_id = “1234567890”
record = accounts_module.get_record(account_id)
notes = record.get_notes
note_id = “0987654321”
note_obj = nil
notes.each do |n_id, n_obj|
    if n_id == note_id then
      note_obj = n_obj
    end
end
note_obj.update_title(“Updated note title “)
note_obj.update_content(“Updated note content ”)
update_notes = {}
update_notes[note_id] = note_obj
note_ids = accounts_module.update_notes(update_notes)[1]

Copy sample request

Sample Request:

ZCRMRecord recordIns = ZCRMRecord.GetInstance("Leads", 3372164000000614001); //module api name with record id
ZCRMNote note = ZCRMNote.GetInstance(recordIns, 3372164000001625020); //record instance with note id
note.Content = "update message";
APIResponse response = recordIns.UpdateNote(note);
ZCRMNote updatedNote = (ZCRMNote)response.Data;

Copy sample request

Sample Request:

def update_note(self):

  try:

    record=ZCRMRecord.get_instance('Leads',440872000000222019) #module API Name, entityId

    note_ins=ZCRMNote.get_instance(record, 440872000000241025) #note ID

    note_ins.title="title2 updated"

    note_ins.content='content2 updated...'

    resp=record.update_note(note_ins)

      print resp.status_code

      print resp.code

      print resp.data.modified_by.id

      print resp.data.modified_by.name

      print resp.message

      print resp.status

  except ZCRMException as ex:

      print ex.status_code

      print ex.error_message

      print ex.error_code

      print ex.error_details

      print ex.error_content

#Here 440872000000222019 is Lead Id and 440872000000241025 is note id

Note:

In the Input, specify the field API names of the Notes module along with the corresponding values.

Copy sample input

Sample Input:

Copy sample response

Sample Response:

Delete specific notes

Purpose

To delete a note

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}/{record_id}/Notes/{note_id}

module_api_name - The api name of a module.

record_id - Specify the unique id of a record.

note_id - Specify the unique id of a note.

Scope

scope=ZohoCRM.modules.all
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, tasks, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, custom. ALL - Full access to notes
WRITE - edit note data
DELETE - delete note data

Request Method

DELETE

Curl Python C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Leads/2883756000000268053/Notes/2883756000000268003"

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

-X DELETE

Copy sample request

Sample Request:

def delete_note(self):

  try:

    record=ZCRMRecord.get_instance('Leads',1386586000001856002)

    note_ins=ZCRMNote.get_instance(record, 1386586000001859023)

    resp=record.delete_note(note_ins)

    print resp.status_code

    print resp.code

    print resp.details

    print resp.message

    print resp.status

  except ZCRMException as ex:

    print ex.status_code

    print ex.error_message

    print ex.error_code

    print ex.error_details

    print ex.error_content

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

ZCRMRecord recordIns = ZCRMRecord.GetInstance("Leads", 3372164000000614001); //module api name with record id
ZCRMNote note = ZCRMNote.GetInstance(recordIns, 3372164000001369220); //record instance with note id
APIResponse response = recordIns.DeleteNote(note);
ZCRMNote updatedNote = (ZCRMNote)response.Data;

Copy sample response

Sample Response:

Delete bulk notes

Purpose

To delete notes in bulk

Request URL

https://www.zohoapis.com/crm/v2/Notes?ids={Entity_ID1, Entity_ID2, Entity_ID3,..}

Entity_ID - The unique ID of the note.

Scope

scope=ZohoCRM.modules.notes.{operation_type}

Possible operation types
ALL - Full access to notes
WRITE - edit note data
DELETE - delete note data

Request Method

POST

Parameters

Parameter Name Data Type Description
ids (mandatory) Array Specify the unique IDs of the notes to be deleted.
Curl
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Notes?ids=2883756000000268003,2883756000000987654,2883756000000736435"

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

-X DELETE

Copy sample response

Sample Response:

Files and Attachments APIs

Attachments provide more information about a contact or a company, which normally cannot be displayed. You may also need to send images, text files or videos or any other type of files to contacts. The files and attachments API allows a user to get a list of attachments, upload or download a photo or a file.

Get list of attachments

Purpose

To get the list of attachments

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}/{record_id}/Attachments

module_api_name - The api name of the module.

record_id - Specify the unique id of a record.

Scope

scope=ZohoCRM.modules.all
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}
(and) scope=ZohoCRM.modules.attachments.all

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, tasks, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, custom, notes. ALL - Full access to attachments
READ - get attachment data

Request Method

GET

Curl Java PHP Python C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Leads/1000000231009/Attachments"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

ZCRMRecord record = ZCRMRecord.getInstance("Products",23857634545l);//module api name with record id

BulkAPIResponse response = record.getAllAttachmentsDetails();

List<ZCRMAttachment> list = ((List<ZCRMAttachment>) response.getData());

Copy sample request

Sample Request:

try{
$record=ZCRMRecord::getInstance("Leads",410405000001111007);
$responseIns=$record->getAttachments(1,50);
$records=$responseIns->getData();
foreach ($records as $attchmentIns)
{
echo $attchmentIns->getId();
echo $attchmentIns->getFileName();
echo $attchmentIns->getFileType();
echo $attchmentIns->getSize();
echo $attchmentIns->getParentModule();
$parentRecord=$attchmentIns->getParentRecord();
echo $parentRecord->getEntityId();
echo $attchmentIns->getParentName();
echo $attchmentIns->getParentId();
$createdBy=$attchmentIns->getCreatedBy();
echo $createdBy->getId();
echo $createdBy->getName();
$modifiedBy=$attchmentIns->getModifiedBy();
echo $modifiedBy->getId();
echo $modifiedBy->getName();
$owner=$attchmentIns->getOwner();
echo $owner->getId();
echo $owner->getName();
echo $attchmentIns->getCreatedTime();
echo $attchmentIns->getModifiedTime();
}
}catch (ZCRMException $e)
{
echo $e->getMessage();
echo $e->getExceptionCode();
echo $e->getCode();
}

Copy sample request

Sample Request:

zclient, api_obj = ZohoCRMClient.get_client_objects(conf_file_location)
accounts_module = api_obj.load_crm_module(“Accounts”)
account_id = “1234567890”
record = accounts_module.get_record(account_id)
attachments = record.get_attachments
#this is a Hash containing entries with attachment_id vs corresponding ZCRMAttachment object

Copy sample request

Sample Request:

ZCRMRecord recordIns = ZCRMRecord.GetInstance("Leads", 3372164000000614001); //module api name with record id
BulkAPIResponse<ZCRMAttachment> response = recordIns.GetAttachments();
List<ZCRMAttachment> attachments = response.BulkData; //attachments - list of ZCRMAttachment instance

Copy sample request

Sample Request:

def get_attachments(self):

  try:

    record=ZCRMRecord.get_instance('Leads',440872000000222019) #module API Name, entityId

    resp=record.get_attachments()

    print resp.status_code

    attachment_ins_arr=resp.data

    for attachment_ins in attachment_ins_arr:

      print attachment_ins.id

      print attachment_ins.file_name

      print attachment_ins.file_type

      print attachment_ins.size

      print attachment_ins.owner.id

      print attachment_ins.created_by.id

      print attachment_ins.modified_by.id

      print attachment_ins.created_time

      print attachment_ins.modified_time

      print attachment_ins.parent_module

      print attachment_ins.attachment_type

      print attachment_ins.parent_name

      print attachment_ins.parent_id

      print attachment_ins.parent_record.entity_id

      print "\n\n"

  except ZCRMException as ex:

    print ex.status_code

    print ex.error_message

    print ex.error_code

    print ex.error_details

    print ex.error_content

Copy sample response

Sample Response:

Upload an attachment

Purpose

To attach a file to a record (as MULTIPART). Specify the module name and the relavant record id in your API request to upload the attachment to your record.

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}/{record_id}/Attachments

module_api_name - The api name of the module.

record_id - Specify the unique id of a record.

Scope

scope=ZohoCRM.modules.all
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}
(and) scope=ZohoCRM.modules.attachments.all

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, tasks, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, custom, notes. ALL - Full access to attachments
WRITE - edit attachment data
CREATE - create attachment data

Request Method

POST

Curl Java PHP Python C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Leads/1000000231009/Attachments"

-X POST

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

-F "file=@attachment1.txt"

Copy sample request

Sample Request to upload a "link" as an attachment:

curl "https://www.zohoapis.com/crm/v2/Leads/1386586000003152001/Attachments"

-X POST

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

-F "attachmentUrl=https://www.zohocorp.com"

Copy sample request

Sample Request:

ZCRMRecord record = ZCRMRecord.getInstance("Products",23857634545l);//module api name with record id

APIResponse response = record.uploadAttachment("FilePath");

ZCRMAttachment uploadAttachment = (ZCRMAttachment) response.getData();

String requestStatus =response.getStatus();

Copy sample request

Sample Request:

try{
$record=ZCRMRecord::getInstance(“Leads”,”410405000001111007”);
$responseIns=$record->uploadAttachment($filePath); // $filePath - absolute path of the attachment to be uploaded.
echo "HTTP Status Code:".$responseIns->getHttpStatusCode();
echo "Status:".$responseIns->getStatus();
echo "Message:".$responseIns->getMessage();
echo "Code:".$responseIns->getCode();
echo "Details:".$responseIns->getDetails()['id'];
}catch(ZCRMException $e)
{
echo $e->getCode();
echo $e->getMessage();
echo $e->getExceptionCode();
}

Copy sample request

Sample Request:

zclient, api_obj = ZohoCRMClient.get_client_objects(conf_file_location)
accounts_module = api_obj.load_crm_module(“Accounts”)
account_id = “1234567890”
record = accounts_module.get_record(account_id)
file_path = “path/to/the/file/“
bool, attachment_id = record.upload_attachments(file_path)

Copy sample request

Sample Request:

ZCRMRecord recordIns = ZCRMRecord.GetInstance("Leads", 3372164000000614001);//module api name with record id
APIResponse response = recordIns.UploadAttachment("/Users/Bob/Desktop/testreport/report-dec-18.htm");
ZCRMAttachment uploadAttachment = (ZCRMAttachment)response.Data;

Copy sample request

Sample Request:

def upload_attachment(self):
    try:
        record=ZCRMRecord.get_instance('Leads',1386586000001856002)
        resp=record.upload_attachment('/Users/Downloads/sequel-pro-1.1.dmg')
        print resp.data.id
 nbsp;   except ZCRMException as ex:
        print ex.status_code
        print ex.error_message
        print ex.error_code
        print ex.error_details
        print ex.error_content

Copy sample response

Sample Response:

Download an attachment

Purpose

To download a file attached to a record. Specify the relevant attachment id and record id in your API request to download the required attachment.

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}/{record_id}/Attachments/{attachment_id}

module_api_name - The api name of a module.

record_id - Specify the unique id of a record.

attachment_id - Specify the unique id of an attachment.

Scope

scope=ZohoCRM.modules.all
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}
(and) scope=ZohoCRM.modules.attachments.all

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, tasks, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, custom, notes. ALL - Full access to attachments
READ - get attachment data

Request Method

GET

Curl Java PHP Python C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Leads/100023009/Attachments/100013547"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

The required file will be downloaded.

Copy sample request

Sample Request:

ZCRMRecord record = ZCRMRecord.getInstance("Products",12345l); //module api name with record id
FileAPIResponse response = record.downloadAttachment(456789l); //attachmentID
InputStream inputStream = response.getFileAsStream();
CommonUtil.saveStreamAsFile(inputStream, "/absolute/path/to/store/file",response.getFileName());

Copy sample request

Sample Request:

try{
$record=ZCRMRecord::getInstance(“Accounts”,410405000001519001);
$fileResponseIns=$record->downloadAttachment(410405000001519501); // 410405000001519501 - Attachment ID.
$fp=fopen($filePath.$fileResponseIns->getFileName(),"w"); // $filePath - absolute path where downloaded file has to be stored.
echo "HTTP Status Code:".$fileResponseIns->getHttpStatusCode();
echo "File Name:".$fileResponseIns->getFileName();
$stream=$fileResponseIns->getFileContent();
fputs($fp,$stream);
fclose($fp);
}catch (ZCRMException $e)
{
echo $e->getMessage();
echo $e->getExceptionCode();
echo $e->getCode();
}

Copy sample request

Sample Request:

zclient, api_obj = ZohoCRMClient.get_client_objects(conf_file_location)
accounts_module = api_obj.load_crm_module(“Accounts”)
account_id = “1234567890”
record = accounts_module.get_record(account_id)
attachment_id = “1234567890”
bool, file_name = accounts_module.download_attachment(attachment_id)

Copy sample request

Sample Request:

ZCRMRecord recordIns = ZCRMRecord.GetInstance("Leads", 3372164000000614001); //module api name with record id
FileAPIResponse response = recordIns.DownloadAttachment(3372164000001624007); //attachmentID
Stream file = response.GetFileAsStream();
CommonUtil.SaveStreamAsFile("FilePath", file, response.GetFileName());

Copy sample request

Sample Request:

def download_attachment(self):
    try:
        record=ZCRMRecord.get_instance('Leads',1386586000001856002)
        resp=record.download_attachment(1386586000001856008)
        print resp.response_headers
        if resp.status_code==200:
            print resp.file_name
            with open('/Users/Downloads/'+resp.file_name, 'wb') as f:
                for chunk in resp.response:
                    f.write(chunk)
            f.close()
    except ZCRMException as ex:
        print ex.status_code
        print ex.error_message
        print ex.error_code
        print ex.error_details
        print ex.error_content

Delete attachments

Purpose

To delete a file attached to a record

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}/{record_id}/Attachments/{attachment_id}

module_api_name - The api name of a module.

record_id - Specify the unique id of a record.

attachment_id - Specify the unique id of an attachment.

Scope

scope=ZohoCRM.modules.all
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}
(and) scope=ZohoCRM.modules.attachments.all

Possible module names Possible operation types
leads, accounts, contacts, deals, campaigns, tasks, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, custom, notes. ALL - Full access to attachments
DELETE - delete attachment data

Request Method

DELETE

Curl Python C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Leads/2883756000000261075/Attachments/2883756000000261017"

-X DELETE

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

def delete_attachment(self):
    try:
        record=ZCRMRecord.get_instance('Leads',1386586000001856002)
        resp=record.delete_attachment(1386586000001858011)
        print resp.status_code
        print resp.code
        print resp.details
        print resp.message
        print resp.status
    except ZCRMException as ex:
        print ex.status_code
        print ex.error_message
        print ex.error_code
        print ex.error_details
        print ex.error_content

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

ZCRMRecord recordIns = ZCRMRecord.GetInstance("Leads", 3372164000000614001); //module api name with record id
APIResponse response = recordIns.DeleteAttachment(3372164000001374374); //attachmentID
JObject attachment = response.ResponseJSON; //attachment is JArray

Copy sample response

Sample Response:

Upload a photo

Purpose

To upload a photo (as MULTIPART) to a record in Leads or Contacts. You need to provide the record id of the associated Lead or Contact in your API request to which the required photo has to be uploaded.

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}/{record_id}/photo

module_api_name - The api name of the module.

record_id - Specify the unique id of a record.

Scope

scope=ZohoCRM.modules.all
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names Possible operation types
leads, contacts, accounts, products, vendors and custom modules. ALL - Full access to images
WRITE - edit photo data
CREATE - create photo data

Request Method

POST

Curl Java PHP Python C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Leads/3000000038009/photo"

-X POST

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

-F "file=@img1.png"

Copy sample request

Sample Request:

ZCRMRecord record = ZCRMRecord.getInstance("Contacts", 975824386248l);//module apiname with record id

APIResponse response = record.uploadPhoto("ImagePath");

String requestStatus =response.getStatus();

Copy sample request

Sample Request:

try{
$record=ZCRMRecord::getInstance(“Leads”,”410405000001111007”);
$responseIns=$record->uploadPhoto($photoPath); // $photoPath - absolute path of the photo to be uploaded.
echo "HTTP Status Code:".$responseIns->getHttpStatusCode();
echo "Status:".$responseIns->getStatus();
echo "Message:".$responseIns->getMessage();
echo "Code:".$responseIns->getCode();
echo "Details:".$responseIns->getDetails()['id'];
}catch(ZCRMException $e)
{
echo $e->getCode();
echo $e->getMessage();
echo $e->getExceptionCode();
}

Copy sample request

Sample Request:

zclient, api_obj = ZohoCRMClient.get_client_objects(conf_file_location)
leads_module = api_obj.load_crm_module(“Leads”)
lead_id = “1234567890”
record = leads_module.get_record(lead_id)
image_path = “path/to/the/image”
is_upload_success = record.upload_photo(image_path)

Copy sample request

Sample Request:

ZCRMRecord recordIns = ZCRMRecord.GetInstance("Leads", 3372164000001632020); //module apiname with record id
APIResponse response = recordIns.UploadPhoto("ImagePath");
JObject photo = response.ResponseJSON; //photo is JArray

Copy sample request

Sample Request:

def upload_photo(self):
    try:
        record=ZCRMRecord.get_instance('Leads',1386586000001856002)
        resp=record.upload_photo('/Users/Pictures/image.png')
        print resp.status_code
        print resp.code
        print resp.message
        print resp.status
    except ZCRMException as ex:
        print ex.status_code
        print ex.error_message
        print ex.error_code
        print ex.error_details
        print ex.error_content

Copy sample response

Sample Response:

Download a photo

Purpose

To download the photo associated with a Lead/Contact. You need to send the unique id of the Lead or contact record in your API request to download the required photo.

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}/{record_id}/photo

module_api_name - The api name of the module.

record_id - Specify the unique id of a record.

Scope

scope=ZohoCRM.modules.all
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names Possible operation types
leads and contacts. ALL - Full access to images
READ - get photo data

Request Method

GET

Curl Java PHP Python C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Leads/3000000038009/photo"

-X GET

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

The required photo from the Leads record with id 3000000038009 will be downloaded.

Copy sample request

Sample Request:

ZCRMRecord record = ZCRMRecord.getInstance("Contacts",123456l);//module api name with record id
FileAPIResponse response = record.downloadPhoto();
InputStream inputStream = response.getFileAsStream();
CommonUtil.saveStreamAsFile(inputStream, "/absolute/path/to/store/file", response.getFileName());

Copy sample request

Sample Request:

try{
$record=ZCRMRecord::getInstance(“Leads”,”410405000001111007”);
$fileResponseIns=$record->downloadPhoto();
echo "HTTP Status Code:".$fileResponseIns->getHttpStatusCode();
echo "File Name:".$fileResponseIns->getFileName();
$fp=fopen($filePath.$fileResponseIns->getFileName(),"w"); // $filePath - absolute path where the downloaded photo is stored.
$stream=$fileResponseIns->getFileContent();
fputs($fp,$stream);
fclose($fp);
}catch(ZCRMException $e)
{
echo $e->getCode();
echo $e->getMessage();
echo $e->getExceptionCode();
}

Copy sample request

Sample Request:

zclient, api_obj = ZohoCRMClient.get_client_objects(conf_file_location)
leads_module = api_obj.load_crm_module(“Leads”)
lead_id = “1234567890”
record = leads_module.get_record(lead_id)
is_download_success = record.download_photo

Copy sample request

Sample Request:

ZCRMRecord recordIns = ZCRMRecord.GetInstance("Leads", 3372164000001632020); //module apiname with record id
FileAPIResponse response = recordIns.DownloadPhoto();
Stream photoStream = response.GetFileAsStream();
CommonUtil.SaveStreamAsFile("/Desktop/test", photoStream, response.GetFileName());

Copy sample request

Sample Request:

def download_photo(self):
    try:
        record=ZCRMRecord.get_instance('Leads',1386586000001856002)
        resp=record.download_photo()
        print resp.response_headers
        if resp.status_code==200:
            print resp.file_name
            with open('/Users/Downloads/'+resp.file_name, 'wb') as f:
                for chunk in resp.response:
                    f.write(chunk)
            f.close()
    except ZCRMException as ex:
        print ex.status_code
        print ex.error_message
        print ex.error_code
        print ex.error_details
        print ex.error_content

Delete a photo

Purpose

To delete a photo from a record in Leads or Contacts. You need to provide the record id of the associated Lead or Contact in your API request from which the required photo has to be deleted.

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}/{record_id}/photo

module_api_name - The api name of the module.

record_id - Specify the unique id of a record.

Scope

scope=ZohoCRM.modules.all
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names Possible operation types
leads and contacts. ALL - Full access to images
WRITE - edit photo
DELETE - delete photo

Request Method

DELETE

Curl Python C#
Copy sample request

Sample Request:

curl "https://www.zohoapis.com/crm/v2/Leads/3000000038009/photo"

-X DELETE

-H "Authorization: Zoho-oauthtoken d92d401c803988c5cb849d0b4215f52"

Copy sample request

Sample Request:

def delete_photo(self):
    try:
        record=ZCRMRecord.get_instance('Leads',1386586000001856002)
        resp=record.delete_photo()
        print resp.status_code
        print resp.code
        print resp.details
        print resp.message
        print resp.status
    except ZCRMException as ex:
        print ex.status_code
        print ex.error_message
        print ex.error_code
        print ex.error_details
        print ex.error_content

Copy sample request

Sample Request:

Copy sample request

Sample Request:

Copy sample request

Sample Request:

ZCRMRecord recordIns = ZCRMRecord.GetInstance("Leads", 3372164000001632020); //module apiname with record id
APIResponse response = recordIns.DeletePhoto();
JObject photo = response.ResponseJSON; //photo is JArray

Copy sample response

Sample Response: