CRUD Zoho

connectx.crud.zoho

ZohoCRM

Bases: Rest

ConnectX connector for Zoho CRM.

Provides methods to interact with Zoho CRM REST API including standard CRUD operations, query building, ETL logging, and job management.

__init__

Initialize ZohoCRM connector and authenticate.

Parameters:

Name	Type	Description	Default
client_id	str	Zoho API client ID	required
client_secret	str	Zoho API client secret	required
refresh_token	str	Zoho API refresh token	required
url	str	Base URL for Zoho CRM API	'https://www.zohoapis.com'
account_url	str	Zoho account URL for token retrieval	'https://accounts.zoho.com'
api_version	str	Zoho CRM API version	'v7'
n_rows_read	int	Number of rows to fetch per request	200
n_rows_write	int	Number of rows to send per write request	100
n_concurrent	int	Maximum number of concurrent requests	4
die_on_error	bool	Raise exception on error	True
timeout		HTTP request timeout in seconds	120
verify		SSL verification parameter	None
cert		SSL certificate path	None

connect

Authenticate and establish a connection to Zoho CRM.

Refreshes the access token using the stored refresh token and validates the connection. If a valid token is already available, it reuses it.

Returns:

Type	Description
	The ZohoCRM instance with an active connection

Raises:

Type	Description
Exception	If authentication fails or Zoho API returns an error

count

Count the number of records in a Zoho module optionally filtered by criteria.

Parameters:

Name	Type	Description	Default
module	str	Zoho module name (e.g., 'Leads', 'Accounts', 'Deals')	required
filter		Optional criteria string or Zoho search filter	None

Returns:

Type	Description
int	Integer count of records matching the criteria

Raises:

Type	Description
Exception	If the Zoho API request fails

create

Create a new record in Zoho CRM.

Parameters:

Name	Type	Description	Default
module	str	Target Zoho module name (e.g., 'Leads', 'Contacts', 'Accounts')	required
data	dict	Dictionary containing record field values	required
trigger	list	Optional list of workflow triggers to execute	None

Returns:

Type	Description
dict | None	Created record details as a dictionary, or None if creation failed

delete

Delete a record from Zoho CRM by its ID.

Parameters:

Name	Type	Description	Default
module	str	Zoho module name (e.g., 'Leads', 'Contacts', 'Deals')	required
id	str	Unique record ID to delete	required

Returns:

Type	Description
dict | None	API response dictionary, or None if deletion failed

headers

Build the authorization headers for Zoho CRM API requests.

Returns:

Type	Description
dict	Dictionary containing the OAuth access token header

integrate

Create or update a Zoho CRM record using an external key (upsert operation).

If a record with the same value for the given sync key exists, it is updated; otherwise, a new record is created.

Parameters:

Name	Type	Description	Default
module	str	Zoho module name (e.g., 'Leads', 'Accounts', 'Contacts')	required
data	dict	Dictionary of field values to insert or update	required
sync_key	str	Field name used as an external unique identifier	required
trigger	list	Optional list of workflow or approval triggers to run during the operation	None

Returns:

Type	Description
dict | None	Created or updated record as a dictionary, or None if operation failed

load

Perform bulk or standard operations on Zoho CRM records.

Supports CREATE, UPDATE, DELETE, INTEGRATE (upsert), and RETRIEVE actions in parallel using threads and batch requests.

Parameters:

Name	Type	Description	Default
module	str	Zoho module name (e.g., 'Leads', 'Accounts', 'Deals')	required
data	DataFrame	Polars DataFrame containing the records to process	required
action	int	Action to perform (CREATE, UPDATE, DELETE, INTEGRATE, RETRIEVE)	required
sync_key	str	Field used as unique identifier for INTEGRATE action	'sync_key'
transform		Optional callable to transform each row before sending	None
picklist	dict	Optional dictionary for picklist value mapping	None
n_rows_write	int	Maximum number of rows per batch request	None
n_concurrent	int	Number of concurrent batch requests	None
die_on_error	bool	Raise an exception if any record fails	None
trigger	list	Optional list of triggers to execute in Zoho (e.g., workflow triggers)	None
callback	callable	Optional callable to report progress	None

Returns:

Type	Description
DataFrame	Polars DataFrame with original data plus 'success' and 'message' columns

Raises:

Type	Description
Exception	If Zoho API returns an error or batch processing fails

ping

Test the current Zoho CRM connection.

Sends a lightweight request to confirm authentication is still valid.

Returns:

Type	Description
bool	True if the connection is active, False otherwise

query_condition

Build a Zoho-compatible query condition for searching records.

Parameters:

Name	Type	Description	Default
field	str	Field name in the module to filter on	required
operator	QueryConditionOperator	Operator to apply (e.g., '=', '!=', '>', '<=', 'in', 'between')	required
value		Value to compare against	required
format	QueryConditionFormat	Format to convert the value into ('text', 'date', 'datetime', etc.)	'text'
utc	bool	Whether to convert datetime values to UTC	True

Returns:

Type	Description
list	List containing a Zoho-formatted query condition string

read

Read records from a Zoho CRM module and return them as a Polars DataFrame.

Supports pagination, filtering, and field selection. Automatically flattens nested structures into separate columns.

Parameters:

Name	Type	Description	Default
module	str	Zoho module name (e.g., 'Leads', 'Accounts', 'Deals')	required
filter	list	Optional list of filter conditions formatted as Zoho CRM criteria	None
fields	list	Optional list of fields to retrieve; if None, retrieves all	None
order_by	str	Field used for sorting results (default: 'id')	'id'
limit	int	Maximum number of records to retrieve	None
n_rows_read	int	Number of records to fetch per request (page size)	None
callback	callable	Optional callable for progress reporting	None

Returns:

Type	Description
DataFrame	Polars DataFrame containing retrieved records

Raises:

Type	Description
Exception	If the request to Zoho CRM fails or response format is invalid

request

Send an HTTP request to the Zoho CRM API.

Extends the base request method to handle Zoho-specific error structures and responses.

Parameters:

Name	Type	Description	Default
method	str	HTTP method (GET, POST, PUT, PATCH, DELETE)	required
path	str	API endpoint path (relative to the CRM base URL)	required
headers	dict	Optional custom headers for the request	None
kwargs		Additional parameters passed to the request	{}

Returns:

Type	Description
dict | None	Parsed JSON response as a dictionary, or None if no content

Raises:

Type	Description
Exception	If Zoho API returns an error status or invalid response

retrieve

Retrieve a record from Zoho CRM by its ID.

Parameters:

Name	Type	Description	Default
module	str	Zoho module name (e.g., 'Leads', 'Contacts', 'Deals')	required
id	str	Unique record ID in Zoho CRM	required

Returns:

Type	Description
dict | None	Retrieved record as a dictionary, or None if not found or failed

update

Update an existing record in Zoho CRM.

Parameters:

Name	Type	Description	Default
module	str	Zoho module name (e.g., 'Leads', 'Accounts', 'Contacts')	required
data	dict	Dictionary containing updated field values	required
id	str	Optional record ID; if omitted, it is extracted from data	None

Returns:

Type	Description
dict | None	Updated record as a dictionary, or None if update failed

ZohoDesk

Bases: ZohoCRM

Zoho Desk connector class, extending ZohoCRM functionality for Desk API.

Provides CRUD operations and basic record counting for Zoho Desk modules.

count

Count records in a Zoho Desk module (not implemented).

Parameters:

Name	Type	Description	Default
module	str	Zoho Desk module name	required
filter		Optional filter criteria (not implemented)	None

Returns:

Type	Description
int	Integer count of records (currently always None)

create

Create a new record in a Zoho Desk module.

Parameters:

Name	Type	Description	Default
module	str	Zoho Desk module name (e.g., 'tickets', 'contacts')	required
data	dict	Dictionary of field values for the new record	required

Returns:

Type	Description
dict | None	Dictionary representing the created record, or None if failed

delete

Delete a record from a Zoho Desk module by ID.

Parameters:

Name	Type	Description	Default
module	str	Zoho Desk module name	required
id	str	ID of the record to delete	required

Returns:

Type	Description
dict | None	Dictionary with deletion status or None if deletion fails

read

Read records from a Zoho Desk module with optional filtering, field selection, and pagination.

Parameters:

Name	Type	Description	Default
module	str	Zoho Desk module name (e.g., 'tickets', 'contacts')	required
filter	list	List of filter conditions in Zoho Desk API format	None
fields	list	List of fields to retrieve; nested fields are automatically un-nested	None
order_by	str	Field name to sort the results by	'id'
limit	int	Maximum number of records to retrieve	None
n_rows_read	int	Number of records to read per request/page	None
callback	callable	Optional callable for reporting progress and logging	None

Returns:

Type	Description
DataFrame	Polars DataFrame containing the requested records

Raises:

Type	Description
Exception	If an error occurs during the API request or data processing

retrieve

Retrieve a record from a Zoho Desk module by ID.

Parameters:

Name	Type	Description	Default
module	str	Zoho Desk module name	required
id	str	ID of the record to retrieve	required

Returns:

Type	Description
dict | None	Dictionary representing the retrieved record, or None if not found

update

Update an existing record in a Zoho Desk module.

Parameters:

Name	Type	Description	Default
module	str	Zoho Desk module name	required
data	dict	Dictionary of field values to update	required
id	str	ID of the record to update; if None, uses the record's primary key from data	None

Returns:

Type	Description
dict | None	Dictionary representing the updated record, or None if update fails