How to get fields in Zoho

Retrieving fields in Zoho CRM requires calling the correct API endpoint with valid authentication and the right module or layout context — here's how to do it reliably.

Why this matters

When building integrations, automations, or custom reports, you need to know exactly which fields exist in a given Zoho CRM module or layout. Without the correct field API names, queries and filters will fail with "invalid column" errors. Understanding how to fetch fields programmatically also helps you avoid hardcoding field names that may differ between organisations.

Step-by-step

Step 1. Ensure your OAuth connection is established and tokens are valid.

Before any API call, your integration must hold a valid access token for the target Zoho CRM organisation. The connection is stored alongside the refreshtoken, accesstoken, apidomain, and tokenexpires_at values. If the access token has expired, a token refresh flow fetches a new one automatically using the stored refresh token, then persists the updated token back to the connection record. ^[3]

Step 2. Identify the correct data centre for your organisation.

Zoho CRM is hosted across multiple data centres. The base URL for CRM follows the pattern https://crm.zoho.{dc}/crm/tab/{Module}/{RecordId}, where {dc} is the data centre suffix (for example, com, eu, in, com.au). The data centre is typically inferred from the api_domain returned during OAuth — specifically the portion after zohoapis. in that domain string. ^[1][5]

Step 3. Determine whether you need module-level fields or layout-level fields.

Zoho CRM distinguishes between fields attached to an entire module and fields scoped to a specific layout within that module. If you need layout-specific fields, you must first know the layoutId for the layout you are targeting. Layout IDs can be retrieved from the layouts endpoint before proceeding to the fields call.

Step 4. Call the fields endpoint for the relevant layout.

To retrieve fields scoped to a particular layout, issue a GET request to /api/v1/layouts/{layoutId}/fields, substituting the actual layout identifier. An optional query-parameter dictionary (p) can be passed to filter or paginate results. ^[4]

A minimal Python example of this call looks like:

def get_layout_fields(self, layoutId: str, p: dict = None):
    return self.c.request("GET", f"/api/v1/layouts/{layoutId}/fields", p, None)

^[4]

Step 5. Confirm the required OAuth scopes are in place.

The OAuth token used must include the appropriate Zoho CRM scopes. The scopes needed for broad CRM access include ZohoCRM.modules.ALL and ZohoCRM.org.ALL, among others. Without these scopes, the API will return a 401 or permission error. ^[8]

Step 6. Handle errors gracefully.

If the API returns an "invalid column" message, it typically means the field API name supplied in a subsequent query does not match what was returned by the fields endpoint. If a 401 status is returned, the access token has been rejected and the user should reconnect their Zoho account. ^[6]

---

Common pitfalls

• Wrong data centre: Using crm.zoho.com when your organisation is on crm.zoho.eu will result in authentication failures or empty responses. Always derive the data centre from the api_domain stored during OAuth. ^[5]
• Missing layoutId: The /api/v1/layouts/{layoutId}/fields endpoint requires a valid layout identifier. Passing a blank or incorrect ID will cause the request to fail. ^[4]
• Expired tokens: If the access token has lapsed and the refresh flow fails (for example, because the refresh token was revoked), the API instance will return None and no fields will be retrieved. Always verify the token refresher returns a valid access token before proceeding. ^[3]
• Insufficient scopes: If the OAuth grant did not include ZohoCRM.modules.ALL or equivalent, field retrieval calls will be rejected. Review the configured scopes and re-authorise if necessary. ^[8]
• "Invalid column" on follow-up queries: After retrieving fields, use the exact API name (not the display label) when constructing filters or COQL queries. A mismatch triggers an "invalid column name" error. ^[6]

---

What to check

• Token validity: Confirm the stored access_token is current and that the token refresher can successfully obtain a new one if needed. ^[3]
• Correct layout ID: Verify the layoutId you are passing to /api/v1/layouts/{layoutId}/fields corresponds to an actual layout in the target module. ^[4]
• Scope coverage: Check that your OAuth grant includes ZohoCRM.modules.ALL (or the minimum required scope) so the fields endpoint is accessible. ^[8]

---

*Beam Help provides independent expert support for Zoho — we are not official Zoho support. For platform-level issues, always cross-reference the official Zoho CRM API documentation.*