Fields Meta Data

Purpose

To get the field metadata for the specified module. The fields displayed are from all layouts for the module. The response does not contain layout-specific fields like mandatory fields or picklist values.

Endpoints

GET /settings/fields?module={module_api_name}

Request Details

Request URL

{api-domain}/crm/{version}/settings/fields?module={module_api_name}&type=unused

Supported modules

Leads, Accounts, Contacts, Deals, Campaigns, Tasks, Cases, Events, Calls, Solutions, Products, Vendors, Price Books, Quotes, Sales Orders, Purchase Orders, Invoices, Custom, and Activities

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

scope=ZohoCRM.settings.fields.READ
(or)
scope=ZohoCRM.settings.fields.ALL
(or)
scope=ZohoCRM.settings.ALL

Parameters

modulestring, mandatory
Specify the API name of the required module. For example, Leads, Contacts, Accounts, Deals, and so on.
typestring, optional
The value unused fetches all the unused fields and all fetches all both used and unused fields in the module. By default, the system fetches all the used fields.

Note

Use the api_name of the fields in all API inputs instead of field labels. This ensures that the label name changes in custom modules or fields won't affect your existing integrations.
The fields whose permission is set as Don't Show will also be fetched in the response.
For the Users module,
- a new field Reporting_To is added.
- Timezone offset varies based on daylight settings. So, the picklist field's display_value will change accordingly.
- In the Country_Locale field, the picklist values are translated, if translation is enabled.

Sample Request

Curl PHP Ruby

Copiedcurl "https://www.zohoapis.com/crm/v2.1/settings/fields?module=Leads&type=unused"
-X GET
-H  "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

4.0.0

Copied//Get instance of FieldsOperations Class that takes moduleAPIName as parameter
$fieldOperations = new FieldsOperations($moduleAPIName);
//Call getField method which takes fieldId as parameter
$response = $fieldOperations->getField($fieldId);

2.1.0

Copiedfo = Fields::FieldsOperations.new(module_api_name)
# Call get_field method which takes field_id as parameter
response = fo.get_field(field_id)

Response JSON Keys

system_mandatoryboolean
Represents if current field is a system-mandatory field.
Possible values - true: The field is a system-mandatory field.
false: The field is not a system-mandatory field.
privateJSON object
Represents the details of compliance settings in your organization. For instance, "private": {
"restricted": true,
"type": "Low",
"export": true
}
- restricted(boolean)- Represents if normal/sensitive data have restricted access when accessed via API.
- export(boolean)- Represents if both normal/sensitive data have restricted access when accessed via export.
- type(string)- Represents the type of restriction. The possible values are Low/High based on field configuration in the layout.
webhookboolean
Represents if the field is supported in webhook.
json_typestring
Represents the JSON type of the field. For instance, JSON object, string, etc,.
cryptJSON object
Represents the status of the encryption. For instance: "crypt": {
"mode": "encryption",
"status": 1
}
The possible values for the "mode" key are: encryption, decryption;
The possible values for the "status" key are:
- 1 - Represents that the field is encrypted.
- 2- Represents that the encryption/decryption for the field is in progress.
The "null" value represents that the key is decrypted.
tooltipJSON object
Represents the details of the tooltip (name and value), if the field has one.
created_sourcestring
Represents the source of the filed. The possible values for this field are: default, extension, and integration.
display_labelstring
The display name of the field. This field will not be translated to user's preferred language. For instance, Lead Owner.
All display labels related to Events are renamed to Meetings.
field_labelstring
The display name of the field in the user's preferred language. All field labels related to Events are renamed to Meetings.
field_read_onlyboolean
Represents if the field is read-only always.
Possible values - true: The field is always read-only.
false: The field is not always a read-only field, it can be updated.
read_onlyboolean
Represents if the field is read-only for the current user.
Possible values - true: The field read-only for the current user.
false: The field is not read-only for the current user.
display_labelboolean
Represents the display label of the current field. For instance, Last Name.
quick_sequence_numberinteger
Represents the position of the field in the CRM.
businesscard_supportedboolean
Represents if the current field can be added to business card section.
Possible values - true: The field can be added to the business card section.
false: The field cannot be added to the business card section.
idstring
Represents the unique ID of the current field.
custom_fieldboolean
Represents if the current field is a custom field.
Possible values - true: The field is a custom field.
false: The current field is a default field.
visibleboolean
Represents if the current field is visible to the user.
Possible values - true: The field is visible to the user.
false: The current field is not visible to the user.
The profiles key represents the permission required for each profile to view this field.
profilesJSON array
Represents the different profiles that have access to this field and the access permission.
The value null represents that the user does not have the Module Customization permission.
display_typeinteger
Represents how the field is displayed based on its type .
The value -1 represents that the field is a normal field while the value 2 represents that the field is "select only" (Eg: Best time to contact field).
history_trackingJSON object
Represents the history of the picklist field if you have enabled history tracking.
The value null represents that history tracking is not enabled for the field.
wizardbigint
Represents that the field is a wizard.
multiselectlookupJSON object
Represents the details such as linking module, connected module, lookup API name etc, of a multi-select lookup field.
multiuserlookupJSON object
Represents the details such as linking module, connected module, lookup API name etc, of a multi-select user lookup field.
pick_list_values_sorted_lexicallyBoolean
Represents whether the values of the picklist are sorted alphabetically.
subformJSON object
Represents the details of the line items in the inventory modules.
lengthinteger
Represents the size of the current field.
sortableBoolean
Represents whether the field is sortable.
api_namestring
Represents API name of the current field.
data_typestring
Represents CRM field type of the current field. For instance, lookup.
formulaJSON object
Represents the formula details, if the current field is a formula field.
decimal_placeinteger
Represents the number of the decimal places allowed for the current field.
mass_updateboolean
Represents if the field can be mass updated.
Possible values - true: The current field can be mass updated.
false: The current field cannot be mass updated.
pick_list_valuesJSON array
Represents the list of all the picklist values, if the field is either a picklist or multi-select picklist field.
The value for the key type in each picklist option represents if that option is used or not.
The id represents the unique ID of every picklist option.
The response contains both used and unused picklist values.
auto_numberJSON object
Represents the auto-number details if the current field is an Auto-Number field.
hipaa_compliance_enabledboolean
Represents if Contains Personal Health Data is enabled for the field.
Possible values - true: The current field contains personal health data.
false: The current field does not contain personal health data.
hipaa_complianceJSON object
Represents the HIPAA compliance status of the field. The object includes the following keys
restricted_in_export: Represents if the data export is restricted for the field. The value is true if Restrict Data in Export option is enabled in the HIPAA compliance settings.
restricted: Represents if the field can be accessed via API. The value is true if Restrict Data access through API option is enabled in the HIPAA compliance settings.

Possible Errors

REQUIRED_PARAM_MISSINGHTTP 400
Bad Request
Resolution: You have not specified the mandatory parameter. Refer to parameters section above.
INVALID_MODULEHTTP 400
The module name given seems to be invalid
Resolution: You have specified an invalid module name or there is no tab permission, or the module could have been removed from the available modules. Specify a valid module API name.
INVALID_MODULEHTTP 400
The given module is not supported in API
Resolution: The modules such as Documents and Projects are not supported in the current API. (This error will not be shown, once these modules are been supported). Specify a valid module API name.
INVALID_URL_PATTERNHTTP 404
Please check if the URL trying to access is a correct one
Resolution: The request URL specified is incorrect. Specify a valid request URL. Refer to request URL section above.
OAUTH_SCOPE_MISMATCHHTTP 401
Unauthorized
Resolution: Client does not have ZohoCRM.settings.fields.READ scope. Create a new client with valid scope. Refer to scope section above.
NO_PERMISSIONHTTP 403
Permission denied to read
Resolution: The user does not have permission to read fields data. Contact your system administrator.
INTERNAL_ERRORHTTP 500
Internal Server Error
Resolution: Unexpected and unhandled exception in Server. Contact support team.
INVALID_REQUEST_METHODHTTP 400
The http request method type is not a valid one
Resolution: You have specified an invalid HTTP method to access the API URL. Specify a valid request method. Refer to endpoints section above.
AUTHORIZATION_FAILEDHTTP 400
User does not have sufficient privilege to read fields data
Resolution: The user does not have the permission to retrieve fields data. Contact your system administrator.

Sample Response

Copied{
  "fields": [
    {
      "system_mandatory": false,
      "private": null,
      "webhook": false,
      "json_type": "jsonarray",
      "crypt": null,
      "field_label": "Languages1",
      "tooltip": null,
      "created_source": "default",
      "type": "unused",
      "field_read_only": false,
      "display_label": "Languages1",
      "display_type": -1,
      "read_only": false,
      "association_details": null,
      "businesscard_supported": false,
      "multi_module_lookup": {},
      "currency": {},
      "id": "3652397000000372398",
      "custom_field": true,
      "lookup": {},
      "convert_mapping": {
        "Contacts": null,
        "Deals": null,
        "Accounts": null
      },
      "visible": true,
      "profiles": [
        {
          "permission_type": "read_write",
          "name": "Administrator",
          "id": "3652397000000026011"
        },
        {
          "permission_type": "read_write",
          "name": "Standard",
          "id": "3652397000000026014"
        },
        {
          "permission_type": "read_write",
          "name": "Free",
          "id": "3652397000001614008"
        }
      ],
      "view_type": {
        "view": true,
        "edit": true,
        "quick_create": false,
        "create": true
      },
      "pick_list_values_sorted_lexically": false,
      "sortable": false,
      "subform": {
        "module": "Languages",
        "id": "3652397000000372341"
      },
      "external": null,
      "api_name": "Languages",
      "unique": {},
      "history_tracking": null,
      "data_type": "subform",
      "formula": {},
      "decimal_place": null,
      "mass_update": false,
      "multiselectlookup": {},
      "pick_list_values": [],
      "auto_number": {}
    },
    {
      "system_mandatory": false,
      "private": null,
      "webhook": true,
      "json_type": "jsonobject",
      "crypt": null,
      "field_label": "Associated_Contacts",
      "tooltip": null,
      "created_source": "default",
      "type": "unused",
      "field_read_only": false,
      "display_label": "Associated_Contacts",
      "display_type": -1,
      "read_only": false,
      "association_details": null,
      "businesscard_supported": false,
      "multi_module_lookup": {},
      "currency": {},
      "id": "3652397000000624032",
      "custom_field": true,
      "lookup": {
        "display_label": "Associated_Contacts",
        "api_name": "Associated_Contacts1",
        "module": "Contacts",
        "id": "3652397000000624036"
      },
      "convert_mapping": {
        "Contacts": null,
        "Deals": null,
        "Accounts": null
      },
      "visible": true,
      "profiles": [
        {
          "permission_type": "read_write",
          "name": "Administrator",
          "id": "3652397000000026011"
        },
        {
          "permission_type": "read_write",
          "name": "Standard",
          "id": "3652397000000026014"
        },
        {
          "permission_type": "read_write",
          "name": "Free",
          "id": "3652397000001614008"
        }
      ],
      "length": 120,
      "view_type": {
        "view": true,
        "edit": true,
        "quick_create": false,
        "create": true
      },
      "pick_list_values_sorted_lexically": false,
      "sortable": true,
      "subform": null,
      "external": null,
      "api_name": "Associated_Contacts",
      "unique": {},
      "history_tracking": null,
      "data_type": "lookup",
      "formula": {},
      "decimal_place": null,
      "mass_update": false,
      "multiselectlookup": {},
      "pick_list_values": [],
      "auto_number": {}
    },
    {
      "system_mandatory": false,
      "private": null,
      "webhook": true,
      "json_type": "jsonobject",
      "crypt": null,
      "field_label": "Account",
      "tooltip": {
        "name": "Info Icon",
        "value": "Select an account you want to link to this lead."
      },
      "created_source": "default",
      "type": "unused",
      "field_read_only": false,
      "display_label": "Account",
      "display_type": -1,
      "read_only": false,
      "association_details": null,
      "businesscard_supported": false,
      "multi_module_lookup": {},
      "currency": {},
      "id": "3652397000000624052",
      "custom_field": true,
      "lookup": {
        "display_label": "Associated_Leads",
        "api_name": "Associated_Accounts",
        "module": "Accounts",
        "id": "3652397000000624056"
      },
      "convert_mapping": {
        "Contacts": null,
        "Deals": null,
        "Accounts": null
      },
      "visible": true,
      "profiles": [
        {
          "permission_type": "read_write",
          "name": "Administrator",
          "id": "3652397000000026011"
        },
        {
          "permission_type": "read_write",
          "name": "Standard",
          "id": "3652397000000026014"
        },
        {
          "permission_type": "read_write",
          "name": "Free",
          "id": "3652397000001614008"
        }
      ],
      "length": 120,
      "view_type": {
        "view": true,
        "edit": true,
        "quick_create": false,
        "create": true
      },
      "pick_list_values_sorted_lexically": false,
      "sortable": true,
      "subform": null,
      "external": null,
      "api_name": "Account",
      "unique": {},
      "history_tracking": null,
      "data_type": "lookup",
      "formula": {},
      "decimal_place": null,
      "mass_update": false,
      "multiselectlookup": {},
      "pick_list_values": [],
      "auto_number": {}
    },
    {
      "system_mandatory": false,
      "private": null,
      "webhook": true,
      "json_type": "jsonarray",
      "crypt": null,
      "field_label": "File_upload_2",
      "tooltip": null,
      "created_source": "default",
      "type": "unused",
      "field_read_only": false,
      "display_label": "File_upload_2",
      "display_type": -1,
      "read_only": false,
      "association_details": null,
      "businesscard_supported": false,
      "multi_module_lookup": {},
      "currency": {},
      "id": "3652397000000906007",
      "custom_field": true,
      "lookup": {},
      "convert_mapping": {
        "Contacts": null,
        "Deals": null,
        "Accounts": null
      },
      "visible": true,
      "profiles": [
        {
          "permission_type": "read_write",
          "name": "Administrator",
          "id": "3652397000000026011"
        },
        {
          "permission_type": "read_write",
          "name": "Standard",
          "id": "3652397000000026014"
        },
        {
          "permission_type": "read_write",
          "name": "Free",
          "id": "3652397000001614008"
        }
      ],
      "length": 1,
      "view_type": {
        "view": true,
        "edit": true,
        "quick_create": false,
        "create": true
      },
      "pick_list_values_sorted_lexically": false,
      "sortable": false,
      "subform": null,
      "external": null,
      "api_name": "File_Upload_2",
      "unique": {},
      "history_tracking": null,
      "data_type": "fileupload",
      "formula": {},
      "decimal_place": null,
      "mass_update": false,
      "multiselectlookup": {},
      "pick_list_values": [],
      "auto_number": {}
    },
    {
      "system_mandatory": false,
      "private": null,
      "webhook": false,
      "json_type": "jsonarray",
      "crypt": null,
      "field_label": "Multi-Select Lookup 2",
      "tooltip": null,
      "created_source": "default",
      "type": "unused",
      "field_read_only": false,
      "display_label": "Multi-Select Lookup 2",
      "display_type": -1,
      "read_only": false,
      "association_details": null,
      "businesscard_supported": false,
      "multi_module_lookup": {},
      "currency": {},
      "id": "3652397000002279001",
      "custom_field": true,
      "lookup": {},
      "convert_mapping": {
        "Contacts": null,
        "Deals": null,
        "Accounts": null
      },
      "visible": true,
      "profiles": [
        {
          "permission_type": "read_write",
          "name": "Administrator",
          "id": "3652397000000026011"
        },
        {
          "permission_type": "read_write",
          "name": "Standard",
          "id": "3652397000000026014"
        },
        {
          "permission_type": "read_write",
          "name": "Free",
          "id": "3652397000001614008"
        }
      ],
      "length": 50,
      "view_type": {
        "view": true,
        "edit": true,
        "quick_create": false,
        "create": true
      },
      "pick_list_values_sorted_lexically": false,
      "sortable": false,
      "subform": null,
      "external": null,
      "api_name": "Multi_Select_Lookup_2",
      "unique": {},
      "history_tracking": null,
      "data_type": "multiselectlookup",
      "formula": {},
      "decimal_place": null,
      "mass_update": false,
      "multiselectlookup": {
        "display_label": "Accounts",
        "linking_module": "Leads_vs_Accounts",
        "lookup_apiname": "Associated_Leads",
        "connected_module": "Accounts",
        "api_name": "Accounts6",
        "connectedlookup_apiname": "Multi_Select_Lookup_2",
        "id": "3652397000002279096"
      },
      "pick_list_values": [],
      "auto_number": {}
    },
    {
      "system_mandatory": false,
      "private": null,
      "webhook": true,
      "json_type": "jsonobject",
      "crypt": null,
      "field_label": "Deals",
      "tooltip": null,
      "created_source": "default",
      "type": "unused",
      "field_read_only": false,
      "display_label": "Deals",
      "display_type": -1,
      "read_only": false,
      "association_details": null,
      "businesscard_supported": false,
      "multi_module_lookup": {},
      "currency": {},
      "id": "3652397000002685001",
      "custom_field": true,
      "lookup": {
        "display_label": "Deal_Lookup",
        "api_name": "Deal_Lookup",
        "module": "Deals",
        "id": "3652397000002685005"
      },
      "convert_mapping": {
        "Contacts": null,
        "Deals": null,
        "Accounts": null
      },
      "visible": true,
      "profiles": [
        {
          "permission_type": "read_write",
          "name": "Administrator",
          "id": "3652397000000026011"
        },
        {
          "permission_type": "read_write",
          "name": "Standard",
          "id": "3652397000000026014"
        },
        {
          "permission_type": "read_write",
          "name": "Free",
          "id": "3652397000001614008"
        }
      ],
      "length": 120,
      "view_type": {
        "view": true,
        "edit": true,
        "quick_create": false,
        "create": true
      },
      "pick_list_values_sorted_lexically": false,
      "sortable": true,
      "subform": null,
      "external": null,
      "api_name": "Deals",
      "unique": {},
      "history_tracking": null,
      "data_type": "lookup",
      "formula": {},
      "decimal_place": null,
      "mass_update": false,
      "multiselectlookup": {},
      "pick_list_values": [],
      "auto_number": {}
    },
    {
      "system_mandatory": false,
      "private": {
        "restricted": true,
        "type": "High",
        "export": true
      },
      "webhook": true,
      "json_type": "string",
      "crypt": null,
      "field_label": "HIPAA",
      "tooltip": null,
      "created_source": "default",
      "field_read_only": false,
      "display_label": "HIPAA",
      "ui_type": 1,
      "read_only": false,
      "association_details": null,
      "businesscard_supported": false,
      "currency": {},
      "id": "4150868000005292001",
      "custom_field": true,
      "lookup": {},
      "hipaa_compliance": {
        "restricted_in_export": true,
        "restricted": false
      },
      "convert_mapping": {
        "Contacts": null,
        "Deals": null,
        "Accounts": null
      },
      "visible": true,
      "length": 255,
      "view_type": {
        "view": true,
        "edit": true,
        "quick_create": false,
        "create": true
      },
      "subform": null,
      "external": null,
      "api_name": "HIPAA",
      "unique": {},
      "history_tracking": false,
      "data_type": "text",
      "formula": {},
      "hipaa_compliance_enabled": true,
      "decimal_place": null,
      "mass_update": true,
      "multiselectlookup": {},
      "pick_list_values": [],
      "auto_number": {}
    }
  ]
}