Subform API
A subform is a secondary form or a table, which will enable you to include multiple line items into a primary form. They are used to associate multiple items to a single record. On a more technical perspective, subforms easily solve the need for you to establish a one-to-many relationship with data in your CRM, in which many secondary items are associated to a single primary record.
The Subform API is available only in Enterprise and above editions of Zoho CRM.
Points-to-remember
The parent Module API name can be acquired using the modules API.
The Field API names of the subform can be acquired using Fields Metadata API of the parent module.
The Field API names of the individual fields in a subform can be acquired using Fields Metadata API, with the request URL as "fields?module={Sub_form_api_name}".
A module can have a maximum of two subforms for all editions except Ultimate. The Ultimate edition can have a maximum of 5 subforms.
A module can have a maximum of 200 subform records with each subform having a maximum of 100 records.
A maximum of 5 aggregate custom fields are available for a subform.
Get Subform Data
Purpose
To get the subform data in a record.
Request Details
Request URL
{api-domain}/crm/{version}/{module_api_name}/{record_id}
(or)
{api-domain}/crm/{version}/{subform_api_name}
Supported modules
Leads, Accounts, Contacts, Deals, Campaigns, Solutions, Products, Vendors, Custom, and Notes
Header
Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52
Scope
scope=ZohoCRM.modules.{module_name}.{operation_type}
Possible module names
leads, accounts, contacts, deals, campaigns, solutions, products, vendors, custom, and notes
Possible operation types
ALL - Full access to a record
READ - Get records in a module
You can get the API name of the subform from the Fields Metadata API.
Refer Response Structure for more details about the JSON keys, values, and their descriptions.
Sample Request
Copiedcurl "https://www.zohoapis.com/crm/v5/Contacts/554023000000298003"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"Copiedresponse = invokeurl
[
url: "https://www.zohoapis.com/crm/v5/Contacts/554023000000298003"
type: GET
connection:"crm_oauth_connection"
];
info response;Possible Errors
- 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.modules.{module_name}.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 subform records. 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 subform records
Resolution: The user does not have the permission to read subform records. Contact your system administrator.
Sample Response
Copied{
"data": [
{
"Owner": {
"name": "Patricia Boyle",
"id": "554023000000235011"
},
"Email": null,
"$currency_symbol": "Rs.",
"Other_Phone": null,
"Mailing_State": null,
"Other_State": null,
"Languages": [
{
"Proficiency": "Professional",
"$approval": {
"delegate": false,
"approve": false,
"reject": false,
"resubmit": false
},
"$currency_symbol": "Rs.",
"$process_flow": false,
"Languages_Known": "English",
"Parent_Id": {
"name": "Last_Name1",
"id": "554023000000298003"
},
"$editable": true,
"id": "554023000000473001",
"$approved": true
},
{
"Proficiency": "Native",
"$approval": {
"delegate": false,
"approve": false,
"reject": false,
"resubmit": false
},
"$currency_symbol": "Rs.",
"$process_flow": false,
"Languages_Known": "French",
"Parent_Id": {
"name": "Last_Name1",
"id": "554023000000298003"
},
"$editable": true,
"id": "554023000000473003",
"$approved": true
}
],
"Date_created": "2019-03-04",
"Other_Country": null,
"Last_Activity_Time": "2019-04-22T11:27:23+05:30",
"Department": null,
"$process_flow": false,
"Assistant": null,
"Mailing_Country": null,
"id": "554023000000298003",
"$approved": true,
"Reporting_To": null,
"$approval": {
"delegate": false,
"approve": false,
"reject": false,
"resubmit": false
},
"Other_City": null,
"Created_Time": "2019-03-04T11:51:53+05:30",
"$editable": true,
"No_of_Employees": null,
"Home_Phone": null,
"Created_By": {
"name": "Patricia Boyle",
"id": "554023000000235011"
},
"Secondary_Email": null,
"Description": null,
"Vendor_Name": null,
"Mailing_Zip": null,
"Twitter": null,
"Other_Zip": null,
"Mailing_Street": null,
"Salutation": null,
"First_Name": null,
"Asst_Phone": null,
"Full_Name": "Last_Name1",
"Record_Image": null,
"Modified_By": {
"name": "Patricia Boyle",
"id": "554023000000235011"
},
"Skype_ID": null,
"Phone": null,
"Account_Name": null,
"Email_Opt_Out": false,
"Modified_Time": "2019-04-22T11:27:23+05:30",
"Date_of_Birth": null,
"Mailing_City": null,
"Title": null,
"Other_Street": null,
"Mobile": null,
"Territories": [],
"Last_Name": "Last_Name1",
"Lead_Source": "Advertisement",
"Tag": [],
"Fax": null
}
]
}Show full
Show less
In this response, "Languages" is the subform in the Contacts module with two picklist fields "Languages_Known" and "Proficiency".