0
# Zoho CRM Node.js SDK 2.0
1

2
The Zoho CRM Node.js SDK provides a comprehensive interface for integrating Node.js applications with Zoho CRM APIs. It features OAuth 2.0 authentication, multi-user support, complete CRUD operations for all CRM entities, and support for multiple data centers and environments.
3

4
## Package Information
5

6
- **Package Name**: @zohocrm/nodejs-sdk-2.0
7
- **Package Type**: npm
8
- **Language**: JavaScript (Node.js)
9
- **Installation**: `npm install @zohocrm/nodejs-sdk-2.0`
10

11
## Core Imports
12

13
```javascript
14
const { InitializeBuilder } = require("@zohocrm/nodejs-sdk-2.0/routes/initialize_builder");
15
const { UserSignature } = require("@zohocrm/nodejs-sdk-2.0/routes/user_signature");
16
const { OAuthBuilder } = require("@zohocrm/nodejs-sdk-2.0/models/authenticator/oauth_builder");
17
const { USDataCenter } = require("@zohocrm/nodejs-sdk-2.0/routes/dc/us_data_center");
18
```
19

20
For ES modules:
21
```javascript
22
import { InitializeBuilder } from "@zohocrm/nodejs-sdk-2.0/routes/initialize_builder";
23
import { UserSignature } from "@zohocrm/nodejs-sdk-2.0/routes/user_signature";
24
import { OAuthBuilder } from "@zohocrm/nodejs-sdk-2.0/models/authenticator/oauth_builder";
25
import { USDataCenter } from "@zohocrm/nodejs-sdk-2.0/routes/dc/us_data_center";
26
```
27

28
## Basic Usage
29

30
```javascript
31
const { InitializeBuilder } = require("@zohocrm/nodejs-sdk-2.0/routes/initialize_builder");
32
const { UserSignature } = require("@zohocrm/nodejs-sdk-2.0/routes/user_signature");
33
const { OAuthBuilder } = require("@zohocrm/nodejs-sdk-2.0/models/authenticator/oauth_builder");
34
const { USDataCenter } = require("@zohocrm/nodejs-sdk-2.0/routes/dc/us_data_center");
35
const { RecordOperations } = require("@zohocrm/nodejs-sdk-2.0/core/com/zoho/crm/api/record/record_operations");
36

37
// Initialize the SDK
38
async function initializeSDK() {
39
    const user = new UserSignature("user@example.com");
40
    const environment = USDataCenter.PRODUCTION();
41
    const token = new OAuthBuilder()
42
        .clientId("your_client_id")
43
        .clientSecret("your_client_secret")
44
        .refreshToken("your_refresh_token")
45
        .redirectURL("your_redirect_url")
46
        .build();
47

48
    await new InitializeBuilder()
49
        .user(user)
50
        .environment(environment)
51
        .token(token)
52
        .initialize();
53
}
54

55
// Use the SDK
56
async function getRecords() {
57
    const recordOperations = new RecordOperations();
58
    const response = await recordOperations.getRecords("Leads");
59

60
    if (response != null) {
61
        console.log("Status Code: " + response.statusCode);
62
        const responseObject = response.object;
63
        // Process response...
64
    }
65
}
66
```
67

68
## Architecture
69

70
The Zoho CRM SDK is built around several key architectural patterns:
71

72
- **Initialization Framework**: Centralized SDK configuration through `InitializeBuilder` with support for multiple users, environments, and token stores
73
- **Operations Pattern**: Each CRM module has a dedicated Operations class (e.g., `RecordOperations`, `UsersOperations`) serving as the primary interface
74
- **Data Center Abstraction**: Support for multiple global data centers (US, EU, IN, AU, CN, JP) with environment-specific configurations
75
- **OAuth 2.0 Integration**: Complete OAuth implementation with flexible token persistence (file, database, or custom)
76
- **Response Wrapper System**: Standardized response handling with specific wrappers for different operation types
77
- **Multi-User Support**: Dynamic user switching capabilities for multi-tenant applications
78

79
## Capabilities
80

81
### SDK Initialization
82

83
Core SDK initialization and configuration, including user authentication, environment setup, and multi-user support.
84

85
```javascript { .api }
86
class InitializeBuilder {
87
    user(user: UserSignature): InitializeBuilder;
88
    environment(environment: Environment): InitializeBuilder;
89
    token(token: Token): InitializeBuilder;
90
    store(store: TokenStore): InitializeBuilder;
91
    SDKConfig(config: SDKConfig): InitializeBuilder;
92
    resourcePath(path: string): InitializeBuilder;
93
    logger(logger: Logger): InitializeBuilder;
94
    requestProxy(proxy: RequestProxy): InitializeBuilder;
95
    initialize(): Promise<void>;
96
    switchUser(): Promise<void>;
97
}
98

99
class UserSignature {
100
    constructor(email: string);
101
    getEmail(): string;
102
}
103
```
104

105
[SDK Initialization](./initialization.md)
106

107
### Authentication & Token Management
108

109
OAuth 2.0 authentication with support for various token storage methods and multi-user scenarios.
110

111
```javascript { .api }
112
class OAuthBuilder {
113
    clientId(clientId: string): OAuthBuilder;
114
    clientSecret(clientSecret: string): OAuthBuilder;
115
    refreshToken(refreshToken: string): OAuthBuilder;
116
    grantToken(grantToken: string): OAuthBuilder;
117
    accessToken(accessToken: string): OAuthBuilder;
118
    redirectURL(redirectURL: string): OAuthBuilder;
119
    id(id: string): OAuthBuilder;
120
    build(): OAuthToken;
121
}
122

123
abstract class TokenStore {
124
    getToken(user: UserSignature, token: Token): Promise<Token>;
125
    saveToken(user: UserSignature, token: Token): Promise<void>;
126
    deleteToken(token: Token): Promise<void>;
127
    getTokens(): Promise<Token[]>;
128
    deleteTokens(): Promise<void>;
129
    getTokenById(id: string, token: Token): Promise<Token>;
130
}
131
```
132

133
[Authentication](./authentication.md)
134

135
### Records Management
136

137
Complete CRUD operations for CRM records including creation, retrieval, updating, deletion, and bulk operations.
138

139
```javascript { .api }
140
class RecordOperations {
141
    getRecords(moduleAPIName: string, paramInstance?: ParameterMap, headerInstance?: HeaderMap): Promise<APIResponse>;
142
    createRecords(moduleAPIName: string, request: BodyWrapper): Promise<APIResponse>;
143
    updateRecords(moduleAPIName: string, request: BodyWrapper): Promise<APIResponse>;
144
    deleteRecords(moduleAPIName: string, paramInstance: ParameterMap): Promise<APIResponse>;
145
    upsertRecords(moduleAPIName: string, request: BodyWrapper): Promise<APIResponse>;
146
    getDeletedRecords(moduleAPIName: string, paramInstance?: ParameterMap, headerInstance?: HeaderMap): Promise<APIResponse>;
147
    searchRecords(moduleAPIName: string, paramInstance?: ParameterMap): Promise<APIResponse>;
148
    convertLead(leadId: BigInt, request: BodyWrapper): Promise<APIResponse>;
149
    getPhoto(moduleAPIName: string, recordId: BigInt): Promise<APIResponse>;
150
    uploadPhoto(moduleAPIName: string, recordId: BigInt, request: FileBodyWrapper): Promise<APIResponse>;
151
    deletePhoto(moduleAPIName: string, recordId: BigInt): Promise<APIResponse>;
152
    massUpdateRecords(moduleAPIName: string, request: BodyWrapper): Promise<APIResponse>;
153
    getMassUpdateStatus(moduleAPIName: string, paramInstance?: ParameterMap): Promise<APIResponse>;
154
    getRecordUsingExternalId(externalFieldValue: string, moduleAPIName: string, paramInstance?: ParameterMap, headerInstance?: HeaderMap): Promise<APIResponse>;
155
    updateRecordUsingExternalId(externalFieldValue: string, moduleAPIName: string, request: BodyWrapper, headerInstance?: HeaderMap): Promise<APIResponse>;
156
    deleteRecordUsingExternalId(externalFieldValue: string, moduleAPIName: string, paramInstance?: ParameterMap, headerInstance?: HeaderMap): Promise<APIResponse>;
157
    getRecord(moduleAPIName: string, recordId: BigInt, paramInstance?: ParameterMap, headerInstance?: HeaderMap): Promise<APIResponse>;
158
    updateRecord(moduleAPIName: string, recordId: BigInt, request: BodyWrapper): Promise<APIResponse>;
159
    deleteRecord(moduleAPIName: string, recordId: BigInt, paramInstance?: ParameterMap): Promise<APIResponse>;
160
}
161
```
162

163
[Records Management](./records.md)
164

165
### Notes Management
166

167
Note and comment management for CRM records.
168

169
```javascript { .api }
170
class NotesOperations {
171
    getNotes(paramInstance?: ParameterMap, headerInstance?: HeaderMap): Promise<APIResponse>;
172
    createNotes(request: BodyWrapper): Promise<APIResponse>;
173
    updateNotes(request: BodyWrapper): Promise<APIResponse>;
174
    deleteNotes(paramInstance?: ParameterMap): Promise<APIResponse>;
175
    getNote(noteId: BigInt, paramInstance?: ParameterMap, headerInstance?: HeaderMap): Promise<APIResponse>;
176
    updateNote(noteId: BigInt, request: BodyWrapper): Promise<APIResponse>;
177
    deleteNote(noteId: BigInt): Promise<APIResponse>;
178
}
179
```
180

181
*Note: Notes operations are documented within [Records Management](./records.md#notes-operations) for comprehensive record-related functionality.*
182

183
### Users Management
184

185
User account management including user retrieval, creation, updates, and role assignments.
186

187
```javascript { .api }
188
class UsersOperations {
189
    getUsers(paramInstance?: ParameterMap, headerInstance?: HeaderMap): Promise<APIResponse>;
190
    createUser(request: BodyWrapper): Promise<APIResponse>;
191
    updateUser(userId: string, request: BodyWrapper): Promise<APIResponse>;
192
    deleteUser(userId: string): Promise<APIResponse>;
193
    getUser(userId: string, paramInstance?: ParameterMap, headerInstance?: HeaderMap): Promise<APIResponse>;
194
}
195

196
class RolesOperations {
197
    getRoles(): Promise<APIResponse>;
198
    getRole(roleId: BigInt): Promise<APIResponse>;
199
}
200

201
class ProfilesOperations {
202
    constructor(ifModifiedSince?: Date);
203
    getProfiles(): Promise<APIResponse>;
204
    getProfile(profileId: BigInt): Promise<APIResponse>;
205
}
206
```
207

208
[Users Management](./users.md)
209

210
### Fields & Metadata
211

212
Field definitions, picklist values, and CRM metadata management.
213

214
```javascript { .api }
215
class FieldsOperations {
216
    getFields(moduleAPIName: string): Promise<APIResponse>;
217
    getField(moduleAPIName: string, fieldId: string): Promise<APIResponse>;
218
}
219

220
class ModulesOperations {
221
    getModules(paramInstance?: ParameterMap, headerInstance?: HeaderMap): Promise<APIResponse>;
222
    getModule(moduleAPIName: string): Promise<APIResponse>;
223
    updateModuleByAPIName(moduleAPIName: string, request: BodyWrapper): Promise<APIResponse>;
224
    updateModuleById(moduleId: string, request: BodyWrapper): Promise<APIResponse>;
225
}
226

227
class LayoutsOperations {
228
    constructor(module?: string);
229
    getLayouts(): Promise<APIResponse>;
230
    getLayout(layoutId: BigInt): Promise<APIResponse>;
231
}
232

233
class CustomViewsOperations {
234
    constructor(module?: string);
235
    getCustomViews(paramInstance?: ParameterMap): Promise<APIResponse>;
236
    getCustomView(customViewId: BigInt, paramInstance?: ParameterMap): Promise<APIResponse>;
237
}
238

239
class BluePrintOperations {
240
    constructor(recordId: BigInt, moduleAPIName: string);
241
    getBlueprint(): Promise<APIResponse>;
242
    updateBlueprint(request: BodyWrapper): Promise<APIResponse>;
243
}
244
```
245

246
[Fields & Metadata](./fields-metadata.md)
247

248
### Bulk Operations
249

250
High-volume data import and export operations for handling large datasets efficiently.
251

252
```javascript { .api }
253
class BulkReadOperations {
254
    createBulkReadJob(request: RequestWrapper): Promise<APIResponse>;
255
    getBulkReadJobDetails(jobId: string): Promise<APIResponse>;
256
    downloadResult(jobId: string): Promise<APIResponse>;
257
}
258

259
class BulkWriteOperations {
260
    uploadFile(request: FileBodyWrapper): Promise<APIResponse>;
261
    createBulkWriteJob(request: RequestWrapper): Promise<APIResponse>;
262
    getBulkWriteJobDetails(jobId: string): Promise<APIResponse>;
263
    downloadBulkWriteResult(jobId: string): Promise<APIResponse>;
264
}
265
```
266

267
[Bulk Operations](./bulk-operations.md)
268

269
### Related Records
270

271
Managing relationships between CRM records including related lists and record associations.
272

273
```javascript { .api }
274
class RelatedRecordsOperations {
275
    getRelatedRecords(relatedListAPIName: string, recordId: BigInt, moduleAPIName: string, paramInstance?: ParameterMap, headerInstance?: HeaderMap): Promise<APIResponse>;
276
    updateRelatedRecords(relatedListAPIName: string, recordId: BigInt, moduleAPIName: string, request: BodyWrapper): Promise<APIResponse>;
277
    delinkRecords(relatedListAPIName: string, recordId: BigInt, moduleAPIName: string, paramInstance: ParameterMap): Promise<APIResponse>;
278
    getRelatedRecord(relatedListAPIName: string, recordId: BigInt, relatedRecordId: BigInt, moduleAPIName: string, paramInstance?: ParameterMap, headerInstance?: HeaderMap): Promise<APIResponse>;
279
    updateRelatedRecord(relatedListAPIName: string, recordId: BigInt, relatedRecordId: BigInt, moduleAPIName: string, request: BodyWrapper): Promise<APIResponse>;
280
    delinkRecord(relatedListAPIName: string, recordId: BigInt, relatedRecordId: BigInt, moduleAPIName: string): Promise<APIResponse>;
281
}
282
```
283

284
[Related Records](./related-records.md)
285

286
### Tags & Organization
287

288
Tag management, sharing controls, and organizational data access.
289

290
```javascript { .api }
291
class TagsOperations {
292
    getTags(moduleAPIName?: string, paramInstance?: ParameterMap): Promise<APIResponse>;
293
    createTags(moduleAPIName: string, request: BodyWrapper): Promise<APIResponse>;
294
    updateTags(moduleAPIName: string, request: BodyWrapper): Promise<APIResponse>;
295
    updateTag(moduleAPIName: string, tagId: string, request: BodyWrapper): Promise<APIResponse>;
296
    deleteTag(tagId: string): Promise<APIResponse>;
297
    mergeTags(tagId: string, request: BodyWrapper): Promise<APIResponse>;
298
    addTagsToRecord(moduleAPIName: string, recordId: BigInt, request: BodyWrapper): Promise<APIResponse>;
299
    removeTagsFromRecord(moduleAPIName: string, recordId: BigInt, paramInstance: ParameterMap): Promise<APIResponse>;
300
    addTagsToMultipleRecords(moduleAPIName: string, request: BodyWrapper): Promise<APIResponse>;
301
    removeTagsFromMultipleRecords(moduleAPIName: string, request: BodyWrapper): Promise<APIResponse>;
302
    getRecordCountForTag(moduleAPIName: string, tagId: string): Promise<APIResponse>;
303
}
304

305
class ShareRecordsOperations {
306
    getSharedRecordDetails(moduleAPIName: string, recordId: BigInt): Promise<APIResponse>;
307
    shareRecord(moduleAPIName: string, recordId: BigInt, request: BodyWrapper): Promise<APIResponse>;
308
    updateSharePermissions(moduleAPIName: string, recordId: BigInt, request: BodyWrapper): Promise<APIResponse>;
309
    revokeSharedRecord(moduleAPIName: string, recordId: BigInt, request: BodyWrapper): Promise<APIResponse>;
310
}
311
```
312

313
[Tags & Organization](./tags-organization.md)
314

315
### Attachments & Files
316

317
File upload, download, and attachment management for CRM records.
318

319
```javascript { .api }
320
class AttachmentsOperations {
321
    downloadAttachment(moduleAPIName: string, recordId: BigInt, attachmentId: BigInt): Promise<APIResponse>;
322
    deleteAttachment(moduleAPIName: string, recordId: BigInt, attachmentId: BigInt): Promise<APIResponse>;
323
    uploadAttachment(moduleAPIName: string, recordId: BigInt, request: FileBodyWrapper): Promise<APIResponse>;
324
    getAttachments(moduleAPIName: string, recordId: BigInt, paramInstance?: ParameterMap): Promise<APIResponse>;
325
}
326

327
class FileOperations {
328
    uploadFile(request: FileBodyWrapper): Promise<APIResponse>;
329
}
330
```
331

332
[Attachments & Files](./attachments-files.md)
333

334
### Organization Settings
335

336
Organization-level configuration including currency management, organization details, and custom variables.
337

338
```javascript { .api }
339
class CurrenciesOperations {
340
    getCurrencies(): Promise<APIResponse>;
341
    addCurrencies(request: BodyWrapper): Promise<APIResponse>;
342
    updateCurrencies(request: BodyWrapper): Promise<APIResponse>;
343
    enableMultipleCurrencies(request: BodyWrapper): Promise<APIResponse>;
344
    updateBaseCurrency(request: BodyWrapper): Promise<APIResponse>;
345
    getCurrency(currencyId: BigInt): Promise<APIResponse>;
346
    updateCurrency(currencyId: BigInt, request: BodyWrapper): Promise<APIResponse>;
347
}
348

349
class OrgOperations {
350
    getOrganization(): Promise<APIResponse>;
351
    uploadOrganizationPhoto(request: FileBodyWrapper): Promise<APIResponse>;
352
}
353

354
class VariablesOperations {
355
    getVariables(): Promise<APIResponse>;
356
    createVariables(request: BodyWrapper): Promise<APIResponse>;
357
    updateVariables(request: BodyWrapper): Promise<APIResponse>;
358
    deleteVariables(request: BodyWrapper): Promise<APIResponse>;
359
    getVariableById(variableId: BigInt): Promise<APIResponse>;
360
    updateVariableById(variableId: BigInt, request: BodyWrapper): Promise<APIResponse>;
361
    deleteVariable(variableId: BigInt): Promise<APIResponse>;
362
    getVariableForAPIName(apiName: string): Promise<APIResponse>;
363
    updateVariableByAPIName(apiName: string, request: BodyWrapper): Promise<APIResponse>;
364
}
365

366
class VariableGroupsOperations {
367
    getVariableGroups(): Promise<APIResponse>;
368
    getVariableGroupById(groupId: BigInt): Promise<APIResponse>;
369
    getVariableGroupByAPIName(apiName: string): Promise<APIResponse>;
370
}
371
```
372

373
[Organization Settings](./organization-settings.md)
374

375
## Data Centers & Environments
376

377
```javascript { .api }
378
class USDataCenter {
379
    static PRODUCTION(): Environment;
380
    static SANDBOX(): Environment;
381
    static DEVELOPER(): Environment;
382
}
383

384
class EUDataCenter {
385
    static PRODUCTION(): Environment;
386
    static SANDBOX(): Environment;
387
    static DEVELOPER(): Environment;
388
}
389

390
class INDataCenter {
391
    static PRODUCTION(): Environment;
392
    static SANDBOX(): Environment;
393
    static DEVELOPER(): Environment;
394
}
395

396
class AUDataCenter {
397
    static PRODUCTION(): Environment;
398
    static SANDBOX(): Environment;
399
    static DEVELOPER(): Environment;
400
}
401

402
class CNDataCenter {
403
    static PRODUCTION(): Environment;
404
    static SANDBOX(): Environment;
405
    static DEVELOPER(): Environment;
406
}
407

408
class JPDataCenter {
409
    static PRODUCTION(): Environment;
410
    static SANDBOX(): Environment;
411
    static DEVELOPER(): Environment;
412
}
413
```
414

415
## Core Types
416

417
```javascript { .api }
418
interface APIResponse {
419
    statusCode: number;
420
    object: any;
421
    headers: Map<string, string>;
422
}
423

424
class ParameterMap {
425
    add(param: Param, value: any): Promise<void>;
426
}
427

428
class HeaderMap {
429
    add(header: Header, value: any): Promise<void>;
430
}
431

432
class SDKConfig {
433
    autoRefreshFields: boolean;
434
    pickListValidation: boolean;
435
}
436

437
class SDKConfigBuilder {
438
    autoRefreshFields(autoRefreshFields: boolean): SDKConfigBuilder;
439
    pickListValidation(pickListValidation: boolean): SDKConfigBuilder;
440
    build(): SDKConfig;
441
}
442

443
class RequestProxy {
444
    host: string;
445
    port: number;
446
    user?: string;
447
    password?: string;
448
}
449

450
class ProxyBuilder {
451
    host(host: string): ProxyBuilder;
452
    port(port: number): ProxyBuilder;
453
    user(user: string): ProxyBuilder;
454
    password(password: string): ProxyBuilder;
455
    build(): RequestProxy;
456
}
457
```