Before you begin

  • Create a Zoho OAuth client or integration with access to the Leads module.
  • Confirm the correct Zoho data center domain for your account.
  • Confirm required fields on your Leads layout. Zoho requires `Last_Name` for Leads, and your org may require additional fields.
  • Choose insert for new-only workflows or upsert when email/phone should update an existing Lead.

Zoho field map

  • `lead.customer_name` -> `First_Name` and `Last_Name`; use a fallback `Last_Name` if only a company name is present.
  • `lead.company` -> `Company`.
  • `lead.email` -> `Email`.
  • `lead.phone` -> `Phone`.
  • `lead.source_platform` -> `Lead_Source` or a custom picklist value.
  • `lead.message` -> `Description`.

Lead insert payload

{
  "data": [
    {
      "First_Name": "Jamie",
      "Last_Name": "Lee",
      "Company": "Acme",
      "Email": "jamie@example.com",
      "Phone": "+15555550123",
      "Lead_Source": "InstaChime",
      "Description": "Need pricing today"
    }
  ]
}

Verify

  • Send a sample webhook and confirm the Zoho Lead record is created or updated.
  • Confirm mandatory-field and picklist validation errors appear in `/integrations` if the mapping is incomplete.
  • Confirm the Zoho record ID is returned in the delivery response.
  • Confirm duplicate handling matches your selected insert or upsert behavior.

Exact Zoho setup

  • Create a Zoho OAuth client or server-side integration for the correct Zoho data center.
  • Grant access to the Leads module.
  • Inspect the Leads module layout for required fields and picklist values.
  • Create custom fields for InstaChime lead ID, source platform, campaign, score, and sentiment if needed.
  • Build a bridge, Zap, or Make scenario that receives `lead.created`.
  • Use Insert Records for create-only flows or Upsert Records when email/phone/external ID should update existing records.
  • Return the Zoho Lead ID to InstaChime in the delivery response.

Zoho payload decisions

  • Send `Last_Name` on every request.
  • Send `Company` if your Zoho layout requires it.
  • Use exact API field names, for example `Lead_Source`, not visible labels that contain spaces differently.
  • Use exact picklist values configured in the target org.
  • Use duplicate check fields or upsert keys only after confirming they match your Zoho dedupe policy.

Zoho troubleshooting

  • If Zoho returns invalid data errors, inspect required fields, picklists, and field API names.
  • If OAuth fails, confirm the account data center and refresh token flow.
  • If upsert creates duplicates, confirm the duplicate-check field and value are included.
  • If API limits are hit, batch or queue writes in the bridge.
  • If owner assignment fails, confirm user IDs and territory rules in Zoho.

Official references

These vendor-owned pages explain the controls and requirements referenced in this guide.

  • Zoho CRM Insert RecordsOfficial documentation used to verify this setup path and its current vendor requirements.
  • Zoho CRM Upsert RecordsOfficial documentation used to verify this setup path and its current vendor requirements.
  • Zoho CRM API limitsOfficial documentation used to verify this setup path and its current vendor requirements.