How to create records in Zoho

Creating records in Zoho CRM or Zoho Desk is straightforward once your OAuth connection and module permissions are properly configured — here's what you need to know to get it right.

> Beam Help is independent expert support for Zoho — not official Zoho support.

Why this matters

Whether you're adding new Leads, Contacts, Tickets, or Tasks, every record creation call depends on having the correct OAuth scopes authorised and a valid connection in place. Getting this wrong means silent failures or permission errors that can be hard to diagnose. Understanding the full flow — from scopes to the API call to the resulting record link — saves significant troubleshooting time.

Step-by-step

Step 1. Confirm your OAuth scopes include CREATE permissions.

Before any record can be written, your Zoho OAuth token must carry the appropriate scope. For Zoho CRM records you need scopes such as ZohoCRM.modules.ALL or a module-specific CREATE scope. For Zoho Desk, the relevant scopes include Desk.tickets.CREATE, Desk.contacts.CREATE, Desk.tasks.CREATE, and Desk.events.CREATE, among others. ^[2]

Step 2. Ensure your Zoho connection is active and authenticated.

Your application must hold a valid accesstoken and refreshtoken stored against your user account. These are captured during the OAuth callback and saved alongside your apidomain, dc (data centre), and crmorg_id. If the connection is missing or expired, any attempt to create a record will return an error such as *"Zoho is not connected for this app. Please reconnect."* ^[3][5]

Step 3. Identify the correct module for your record.

Every record belongs to a module — for example Leads, Contacts, Deals, or Accounts in Zoho CRM, or tickets in Zoho Desk. The module name is a required parameter passed alongside your record data. Make sure the module name matches exactly what the API expects, as a mismatch will cause the request to fail. ^[1]

Step 4. Submit the create request via the appropriate tool or API call.

Pass your chosen tool name and a params object that includes the module and all required field values. The system will execute the tool, and if the operation is classified as a write action, it may first be staged as a "planned" action with a risk_level assigned before execution is approved. ^[4]

Step 5. Approve the planned action if required.

Write operations — including record creation — are often held in a planned status stored in adminactions before they are applied. Once you confirm the plan, the system calls applyplan, which executes the tool with your parameters and attempts to create the record in Zoho. ^[6]

Step 6. Retrieve the direct link to your new record.

After a successful creation, the system builds a direct URL to the new record. For Zoho CRM, the link follows the pattern https://crm.zoho.{dc}/crm/tab/{Module}/{RecordId}. For Zoho Desk tickets, the pattern is https://desk.zoho.{dc}/agent/{portal}/tickets/details/{TicketId}. These links are returned alongside the API response so you can navigate straight to the new record. ^[1][6]

Common pitfalls

• Missing or insufficient scopes. If your OAuth token was generated without CREATE scopes for the relevant module, the API will reject the request. You must re-authorise and ensure all required scopes — such as Desk.tickets.CREATE or the CRM equivalent — are included. ^[2]

• Expired or missing connection. If no valid connection exists for your user account, the system cannot retrieve an access_token and will halt before making any API call. Re-authenticating through the OAuth flow will resolve this. ^[3][5]

• Wrong data centre (dc) setting. Your connection stores a dc value (e.g. com, eu, in) derived from the api_domain returned during OAuth. If this is incorrect, the generated record URLs and API endpoints will point to the wrong region, causing failures. ^[1][5]

• Write operations blocked in read-only mode. Some chat or automation contexts are initialised with read_only=True, which means create/write tools will not be offered or executed. Ensure you are operating in a context that permits write actions. ^[3]

What to check

• Verify your OAuth scopes include the relevant CREATE permission for your target module (CRM or Desk) before attempting record creation. ^[2]
• Confirm your connection record holds a non-expired accesstoken and the correct dc and crmorg_id values. ^[5]
• Check the returned record URL after creation to confirm the record was written to the expected module and data centre. ^[1][6]