Zoho CRM Integration - G-Tateth API Documentation

The Zoho CRM integration allows you to connect your Zoho CRM account and import your existing data (contacts, deals, tickets, notes, and activities) into G-Tateth CRM.

All API endpoints are documented in the API Reference tab. This guide focuses on concepts, workflows, and integration examples.

Overview

With the Zoho CRM integration, you can:

Connect Zoho Accounts - Securely connect multiple Zoho CRM accounts via OAuth 2.0
Import Historical Data - Import contacts, deals, tickets, notes, and activities
Data Mapping - Automatic mapping of Zoho fields to G-Tateth CRM entities
Incremental Imports - Import data for specific date ranges
Progress Tracking - Monitor import progress in real-time

How It Works

Data Flow

Zoho CRM → OAuth Connection → G-Tateth API → Import Job → Your CRM

Connect: Authorize G-Tateth to access your Zoho CRM account
Configure: Choose what data to import (contacts, deals, tickets, etc.)
Import: Data is imported asynchronously in the background
Monitor: Track progress and review results

Data Mapping

Zoho Contacts → G-Tateth Customers

Email, name, phone, company information
Custom fields preserved in customFields.zoho_*

Zoho Deals → G-Tateth Conversations

Deal name becomes conversation subject
Deal stage mapped to conversation status
Deal amount stored in metadata
Notes imported as messages

Zoho Tickets → G-Tateth Conversations

Ticket subject becomes conversation subject
Ticket status and priority mapped
Description and notes imported as messages

Complete Integration Flow

Here’s the complete flow for integrating Zoho CRM via API:

Get OAuth URL → GET /api/zoho/connect
Redirect user → User authorizes in Zoho
OAuth callback → Integration is created automatically
Get Integration ID → GET /api/zoho/integrations to retrieve the _id
Use Integration ID → Use _id in all subsequent API calls

Quick Start

1. Connect Your Zoho Account

You can connect Zoho CRM through: Dashboard UI:

Go to Apps → Integrations
Click Connect Zoho CRM
Authorize access in Zoho
Integration is connected automatically

API:

# Step 1: Get OAuth URL
curl -X GET https://api.g-tateth.com/api/zoho/connect \
  -H "Authorization: Bearer sk_live_your_api_key"

# Response:
# {
#   "success": true,
#   "authUrl": "https://accounts.zoho.com/oauth/v2/auth?...",
#   "state": "eyJ0ZW5hbnRJZCI6..."
# }

# Step 2: Redirect user to authUrl
# User authorizes in Zoho, then Zoho redirects to your callback URL
# The integration is automatically created

# Step 3: Get Integration ID
# After OAuth callback completes, list integrations to get the ID
curl -X GET https://api.g-tateth.com/api/zoho/integrations \
  -H "Authorization: Bearer sk_live_your_api_key"

# Response:
# {
#   "success": true,
#   "data": [
#     {
#       "_id": "507f1f77bcf86cd799439011",  // This is your integration_id
#       "accountName": "My Zoho Account",
#       "accountEmail": "account@example.com",
#       "isActive": true,
#       ...
#     }
#   ]
# }

Getting the Integration ID: After the OAuth callback completes, call GET /api/zoho/integrations to retrieve the newly created integration. Use the _id field as the integration_id in subsequent API calls.

2. Get Integration ID

After connecting, you need the integration_id to perform operations. Get it by listing all integrations:

curl -X GET https://api.g-tateth.com/api/zoho/integrations \
  -H "Authorization: Bearer sk_live_your_api_key"

Response:

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439011",  // Use this as integration_id
      "accountName": "My Zoho Account",
      "accountEmail": "account@example.com",
      "isActive": true,
      "lastSyncAt": "2024-01-01T12:00:00Z",
      "syncStatus": "idle"
    }
  ]
}

Multiple Integrations: If you have multiple Zoho accounts connected, you’ll see multiple items in the array. Use the _id of the integration you want to work with.

3. Start Importing Data

Once you have the integration_id, you can import your Zoho data: Via Dashboard:

Go to Settings → Integrations → Zoho
Click Start Import
Select what to import (contacts, deals, tickets, etc.)
Optionally set a date range
Click Start Import

Via API:

curl -X POST https://api.g-tateth.com/api/zoho/integrations/{integration_id}/import \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "importContacts": true,
    "importDeals": true,
    "importTickets": true,
    "importNotes": true,
    "dateRange": {
      "startDate": "2024-01-01",
      "endDate": "2025-01-01"
    }
  }'

4. Monitor Import Progress

Imports run asynchronously. Check status:

curl -X GET https://api.g-tateth.com/api/zoho/integrations/{integration_id}/import/status \
  -H "Authorization: Bearer sk_live_your_api_key"

Response includes:

Current status (idle, in_progress, completed, failed)
Progress metrics (total, processed, successful, failed)
Results (customers created, conversations created, messages created)
Any errors encountered

Import Options

What Can Be Imported

Contacts → Customers in G-Tateth
Deals → Conversations (sales pipeline)
Tickets → Conversations (support cases)
Notes → Messages in conversations
Activities → Call logs and tasks (optional)

Date Range Filtering

Import only data from a specific time period:

{
  "dateRange": {
    "startDate": "2024-01-01",
    "endDate": "2024-12-31"
  }
}

Use Cases:

Incremental Imports: Import only recent data
Historical Import: Import all historical data (omit dateRange)
Testing: Import small date range to test before full import

Selective Import

Choose what to import:

{
  "importContacts": true,    // Import contacts as customers
  "importDeals": true,       // Import deals as conversations
  "importTickets": true,     // Import tickets as conversations
  "importNotes": true,       // Import notes as messages
  "importActivities": false  // Import call logs (optional)
}

Data Mapping Details

Contacts → Customers

Zoho Field	g-tateth Field	Notes
`Email`	`profile.email`	Primary identifier
`First_Name`	`profile.firstName`
`Last_Name`	`profile.lastName`
`Phone` / `Mobile`	`profile.phone`
`Company`	`profile.company`
`Title`	`profile.jobTitle`
Custom fields	`customFields.zoho_*`	Preserved with prefix

Deals → Conversations

Zoho Field	g-tateth Field	Notes
`Deal_Name`	`subject`	Conversation title
`Stage`	`status`	Mapped to open/closed/pending
`Amount`	`metadata.dealAmount`	Stored in metadata
`Description`	Initial message	First message in conversation
`Closing_Date`	`metadata.closingDate`
Notes	Additional messages	Each note becomes a message

Tickets → Conversations

Zoho Field	g-tateth Field	Notes
`Subject`	`subject`	Conversation title
`Status`	`status`	Mapped to open/closed/pending
`Priority`	`priority`	Mapped to low/medium/high/urgent
`Description`	Initial message	First message in conversation
Notes	Additional messages	Each note becomes a message

Workflows

Complete Integration Flow (API)

Here’s a complete example showing how to connect and use Zoho integration via API:

// Step 1: Initiate OAuth
const connectResponse = await fetch('https://api.g-tateth.com/api/zoho/connect', {
  headers: {
    'Authorization': `Bearer ${apiKey}`
  }
});

const { authUrl, state } = await connectResponse.json();

// Step 2: Redirect user to authUrl (in browser)
// window.location.href = authUrl;
// Or in server-side flow, return authUrl to client

// Step 3: After OAuth callback, get the integration ID
// Poll or wait a moment, then fetch integrations
const integrationsResponse = await fetch('https://api.g-tateth.com/api/zoho/integrations', {
  headers: {
    'Authorization': `Bearer ${apiKey}`
  }
});

const { data: integrations } = await integrationsResponse.json();

// Get the most recent integration (or filter by accountName/accountEmail)
const integration = integrations[0]; // Most recent
const integrationId = integration._id;

// Step 4: Now you can use integrationId for operations
console.log(`Integration ID: ${integrationId}`);

// Step 5: Start import
await fetch(`https://api.g-tateth.com/api/zoho/integrations/${integrationId}/import`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    importContacts: true,
    importDeals: true
  })
});

Server-Side Flow: If you’re building a server-side integration, you’ll need to:

Store the state parameter when initiating OAuth
Set up a webhook or polling mechanism to detect when OAuth completes
Call GET /api/zoho/integrations to retrieve the new integration ID

Full Historical Import

Import all data from Zoho:

# 1. Connect Zoho (via UI or API)
# 2. Start full import (no date range)
curl -X POST https://api.g-tateth.com/api/zoho/integrations/{id}/import \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "importContacts": true,
    "importDeals": true,
    "importTickets": true,
    "importNotes": true
  }'

# 3. Poll status until complete
while true; do
  STATUS=$(curl -s -X GET https://api.g-tateth.com/api/zoho/integrations/{id}/import/status \
    -H "Authorization: Bearer sk_live_your_api_key" | jq -r '.data.status')
  
  if [ "$STATUS" = "completed" ]; then
    echo "Import completed!"
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "Import failed!"
    break
  fi
  
  sleep 5
done

Incremental Import

Import only recent data:

# Import last 30 days
curl -X POST https://api.g-tateth.com/api/zoho/integrations/{id}/import \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "importContacts": true,
    "importDeals": true,
    "dateRange": {
      "startDate": "2024-12-01",
      "endDate": "2024-12-31"
    }
  }'

Testing Import

Test with a small dataset first:

# Import only last week's data
curl -X POST https://api.g-tateth.com/api/zoho/integrations/{id}/import \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "importContacts": true,
    "importDeals": false,
    "importTickets": false,
    "dateRange": {
      "startDate": "2024-12-25",
      "endDate": "2024-12-31"
    }
  }'

Managing Integrations

List All Integrations

curl -X GET https://api.g-tateth.com/api/zoho/integrations \
  -H "Authorization: Bearer sk_live_your_api_key"

Get Integration Details

curl -X GET https://api.g-tateth.com/api/zoho/integrations/{id} \
  -H "Authorization: Bearer sk_live_your_api_key"

Disconnect Integration

curl -X DELETE https://api.g-tateth.com/api/zoho/integrations/{id} \
  -H "Authorization: Bearer sk_live_your_api_key"

Best Practices

1. Test Before Full Import

Always test with a small date range first:

{
  "dateRange": {
    "startDate": "2024-12-25",
    "endDate": "2024-12-31"
  }
}

2. Monitor Progress

Poll the status endpoint every 3-5 seconds during import:

async function monitorImport(integrationId, apiKey) {
  while (true) {
    const response = await fetch(
      `https://api.g-tateth.com/api/zoho/integrations/${integrationId}/import/status`,
      {
        headers: { 'Authorization': `Bearer ${apiKey}` }
      }
    );
    
    const { data } = await response.json();
    
    console.log(`Progress: ${data.progress.processed}/${data.progress.total}`);
    
    if (data.status === 'completed' || data.status === 'failed') {
      break;
    }
    
    await new Promise(resolve => setTimeout(resolve, 3000));
  }
}

3. Handle Errors

Review the errors array in the status response:

if (data.results.errors && data.results.errors.length > 0) {
  console.error('Import errors:', data.results.errors);
  // Log or handle errors appropriately
}

4. Use Date Ranges for Large Imports

For accounts with thousands of records, use date ranges to import in batches:

// Import in monthly batches
const months = [
  { start: '2024-01-01', end: '2024-01-31' },
  { start: '2024-02-01', end: '2024-02-29' },
  // ...
];

for (const month of months) {
  await startImport(integrationId, {
    dateRange: month
  });
  
  // Wait for completion before next batch
  await waitForCompletion(integrationId);
}

5. Preserve Data Integrity

Don’t re-import: Re-importing the same data creates duplicates
Check before import: Review what will be imported
Backup first: Ensure you have backups before large imports

Troubleshooting

Import Stuck or Slow

Large datasets: Use date ranges to import in smaller batches
Rate limits: Zoho API has rate limits; imports may take time
Check status: Use the status endpoint to see current progress

Missing Data

Check date range: Ensure date range includes the data you want
Verify Zoho access: Ensure integration has proper permissions
Review errors: Check the errors array in status response

OAuth Issues

Reconnect: Disconnect and reconnect the integration
Check permissions: Ensure Zoho app has required scopes
Verify redirect URI: Ensure redirect URI matches Zoho app settings

API Reference

For complete API endpoint documentation, see the API Reference tab. Key endpoints:

GET /api/zoho/connect - Initiate OAuth flow
GET /api/zoho/integrations - List integrations
POST /api/zoho/integrations/:id/import - Start import
GET /api/zoho/integrations/:id/import/status - Get import status
GET /api/zoho/integrations/:id/import/history - Get import history

Support

Questions about Zoho integration?

Email: api-support@g-tateth.com
Documentation: https://docs.g-tateth.com
API Reference: See the API Reference tab for endpoint details

​Overview

​How It Works

​Data Flow

​Data Mapping

​Complete Integration Flow

​Quick Start

​1. Connect Your Zoho Account

​2. Get Integration ID

​3. Start Importing Data

​4. Monitor Import Progress

​Import Options

​What Can Be Imported

​Date Range Filtering

​Selective Import

​Data Mapping Details

​Contacts → Customers

​Deals → Conversations

​Tickets → Conversations

​Workflows

​Complete Integration Flow (API)

​Full Historical Import

​Incremental Import

​Testing Import

​Managing Integrations

​List All Integrations

​Get Integration Details

​Disconnect Integration

​Best Practices

​1. Test Before Full Import

​2. Monitor Progress

​3. Handle Errors

​4. Use Date Ranges for Large Imports

​5. Preserve Data Integrity

​Troubleshooting

​Import Stuck or Slow

​Missing Data

​OAuth Issues

​API Reference

​Support

Overview

How It Works

Data Flow

Data Mapping

Complete Integration Flow

Quick Start

1. Connect Your Zoho Account

2. Get Integration ID

3. Start Importing Data

4. Monitor Import Progress

Import Options

What Can Be Imported

Date Range Filtering

Selective Import

Data Mapping Details

Contacts → Customers

Deals → Conversations

Tickets → Conversations

Workflows

Complete Integration Flow (API)

Full Historical Import

Incremental Import

Testing Import

Managing Integrations

List All Integrations

Get Integration Details

Disconnect Integration

Best Practices

1. Test Before Full Import

2. Monitor Progress

3. Handle Errors

4. Use Date Ranges for Large Imports

5. Preserve Data Integrity

Troubleshooting

Import Stuck or Slow

Missing Data

OAuth Issues

API Reference

Support