Zoho: Related Records

← Related records operations · Get started

Operation zoho.getrelatedrecords

Provider route: GET /crm/v8/{parentRecordModule}/{parentRecord}/{relatedList}. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/zoho with npm, or alter-sdk-zoho with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { ZohoIntegration } from "@alter-ai/zoho";

async function execute(input: Parameters<ZohoIntegration["relatedRecords"]["getRelatedRecords"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new ZohoIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.relatedRecords.getRelatedRecords(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_zoho import ZohoIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = ZohoIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.related_records.get_related_records(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
path	object	Required within parent	Additional keys: not allowed
path.parentRecordModule	string	Required within parent	Maximum length: 100 Pattern: ^[A-Za-z_][A-Za-z0-9_]*$
path.parentRecord	string	Required within parent	Maximum length: 20 Pattern: ^[0-9]+$
path.relatedList	string	Required within parent	Maximum length: 100 Pattern: ^[A-Za-z_][A-Za-z0-9_]*$
query	object	Required within parent	Additional keys: not allowed
query.fields	string	Required within parent	Maximum length: 1000 Pattern: ^[A-Za-z_][A-Za-z0-9_](,[A-Za-z_][A-Za-z0-9_])*$
query.page	integer	Optional	Default: 1 Format: int32 Maximum: 10000 Minimum: 1
query.perPage	integer	Optional	Default: 200 Format: int32 Maximum: 200 Minimum: 1
query.page_token	string	Optional	Maximum length: 500
query.ids	string	Optional	Maximum length: 2000 Pattern: ^[0-9]+(,[0-9]+)*$
query.sort_order	string	Optional	Default: desc One of: asc, desc
query.sort_by	string	Optional	Default: id One of: id, Created_Time, Modified_Time
query.converted	string	Optional	Default: false One of: true, false, both
query.approved	string	Optional	Default: true One of: true, false, both
query.approval_state	string	Optional	One of: webform_unapproved, approved, approval_process_pending, approval_process_rejected, webform_invalid, webform_invalid_approval, webform_double_optin, review_process_pending, review_process_rejected, merge_pending, zia_vision_pending, zia_vision_rejected, zia_vision_validation, email_parser_waiting, email_parser_rejected, approval_process_recalled
query.filters	Model	Optional	Expand Related Records — request body — query filters
headers	object	Optional	Additional keys: not allowed
headers.If-Modified-Since	string	Optional	Format: date-time

Referenced models: Related Records — request body — query filters

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	JSON	Root
$ (anyOf 1)	object	Alternative	Represents the response for a list of related records, including the record fields and pagination metadata. Additional keys: not allowed
$ (anyOf 1).data	array	Required within parent	Array of related record objects with requested fields. Maximum items: 200
$ (anyOf 1).data[]	object	Each item	Individual related record with dynamic CRM fields. Additional keys: allowed
$ (anyOf 1).data[].Created_Time	string	Optional	Represents the creation date and time of the related record. Format: date-time
$ (anyOf 1).data[].Modified_Time	string	Optional	Timestamp when the record was last modified. Format: date-time
$ (anyOf 1).data[].Moved_To__s	string	Optional	Stage value to which the record was moved (stage history / picklist movement). Maximum length: 255
$ (anyOf 1).data[].id	string	Optional	Unique identifier of the related record. Maximum length: 20 Pattern: ^[0-9]+$
$ (anyOf 1).info	object	Required within parent	Pagination and response metadata. Additional keys: not allowed
$ (anyOf 1).info.count	JSON	Required within parent
$ (anyOf 1).info.count (anyOf 1)	integer	Alternative	Number of records in current response. Format: int32 Minimum: 0
$ (anyOf 1).info.count (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
$ (anyOf 1).info.more_records	boolean	Required within parent	Indicates if more pages are available.
$ (anyOf 1).info.next_page_token	JSON	Optional
$ (anyOf 1).info.next_page_token (anyOf 1)	string	Alternative	Token to retrieve the next page of results. Maximum length: 500
$ (anyOf 1).info.next_page_token (anyOf 2)	null	Alternative	Token to retrieve the next page of results. Maximum length: 500
$ (anyOf 1).info.page	JSON	Required within parent
$ (anyOf 1).info.page (anyOf 1)	integer	Alternative	Current page number. Format: int32 Minimum: 1
$ (anyOf 1).info.page (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
$ (anyOf 1).info.page_token_expiry	JSON	Optional
$ (anyOf 1).info.page_token_expiry (anyOf 1)	string	Alternative	Expiration timestamp for the page token. Format: date-time
$ (anyOf 1).info.page_token_expiry (anyOf 2)	null	Alternative	Expiration timestamp for the page token. Format: date-time
$ (anyOf 1).info.per_page	JSON	Required within parent
$ (anyOf 1).info.per_page (anyOf 1)	integer	Alternative	Number of records per page. Format: int32 Maximum: 200 Minimum: 1
$ (anyOf 1).info.per_page (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
$ (anyOf 1).info.previous_page_token	JSON	Optional
$ (anyOf 1).info.previous_page_token (anyOf 1)	string	Alternative	Token to retrieve the previous page of results. Maximum length: 500
$ (anyOf 1).info.previous_page_token (anyOf 2)	null	Alternative	Token to retrieve the previous page of results. Maximum length: 500
$ (anyOf 2)	null	Alternative

Schemas

10 more schemas are linked from the tables above, on the schema pages.

Related Records — request body — query filters

Field	Type	Presence	Description and constraints
$	JSON	Root	Represents the top-level filter criterion for data selection, supporting both simple field-based filters and complex grouped filters with logical operators.
$ (anyOf 1)	Model	Alternative	Expand Related Records — request body — query filters value
$ (anyOf 2)	Model	Alternative	Expand Related Records — request body — query / filters / group_operator: AND, OR, and, or

Referenced models: Related Records — request body — query / filters / group_operator: AND, OR, and, or, Related Records — request body — query filters value

Related Records — request body — query / filters / group_operator: AND, OR, and, or

Field	Type	Presence	Description and constraints
$	object	Root	Represents a grouped filter criterion containing multiple filter conditions evaluated with a logical operator. Supports recursive nesting for complex filtering logic. Additional keys: not allowed
group	array	Required within parent	Contains an array of filter conditions grouped together and evaluated with the specified logical operator. Maximum items: 25 Minimum items: 2
group[]	JSON	Each item
group[] (anyOf 1)	Model	Alternative	Expand Related Records — request body — query filters value
group[] (anyOf 2)	Model	Alternative	Expand Related Records — request body — query / filters / group_operator: AND, OR, and, or
group_operator	string	Required within parent	Represents the logical operator applied between the filter conditions in the group. Possible values: AND - All conditions in the group must be satisfied. OR - At least one condition in the group must be satisfied. and - Equivalent to AND; all conditions in the group must be satisfied. or - Equivalent to OR; at least one condition in the group must be satisfied. One of: AND, OR, and, or

Referenced models: Related Records — request body — query / filters / group_operator: AND, OR, and, or, Related Records — request body — query filters value

Related Records — request body — query filters value

Field	Type	Presence	Description and constraints
$	JSON	Root	Represents a simple field-based filter criterion that dispatches to the appropriate comparator-specific schema. The equal and not_equal comparators support scalar or array values; text comparators support scalar or array strings; ordering comparators require a scalar; between and not_between comparators require a two-element array; in and not_in comparators require an array of primitives; and include_all, include_any, exclude_all, and exclude_any comparators require an array of lookup objects and apply only when the field's data_type is multiuserlookup or multiselectlookup.
$ (anyOf 1)	Model	Alternative	Expand Related Records — request body — query filters value value
$ (anyOf 2)	Model	Alternative	Expand Related Records — request body — query / filters / value / comparator: like, not like, starts with, ends with, contains, not contains, type: merge field, pre defined, value, field
$ (anyOf 3)	Model	Alternative	Expand Related Records — request body — query / filters / value / comparator: less than, less equal, greater than, greater equal, type: merge field, pre defined, value, field
$ (anyOf 4)	Model	Alternative	Expand Related Records — request body — query / filters / value / comparator: between, not between, type: merge field, pre defined, value, field
$ (anyOf 5)	Model	Alternative	Expand Related Records — request body — query / filters / value / comparator: in, not in, type: merge field, pre defined, value, field
$ (anyOf 6)	Model	Alternative	Expand Related Records — request body — query / filters / value / comparator: include all, include any, exclude all, exclude any, type: merge field, pre defined, value, field

Referenced models: Related Records — request body — query / filters / value / comparator: between, not between, type: merge field, pre defined, value, field, Related Records — request body — query filters value value, Related Records — request body — query / filters / value / comparator: include all, include any, exclude all, exclude any, type: merge field, pre defined, value, field, Related Records — request body — query / filters / value / comparator: less than, less equal, greater than, greater equal, type: merge field, pre defined, value, field, Related Records — request body — query / filters / value / comparator: in, not in, type: merge field, pre defined, value, field, Related Records — request body — query / filters / value / comparator: like, not like, starts with, ends with, contains, not contains, type: merge field, pre defined, value, field

Related Records — request body — query / filters / value / comparator: between, not between, type: merge field, pre defined, value, field

Field	Type	Presence	Description and constraints
$	object	Root	Represents a filter criterion for the between and not_between comparators. The value must be an array of exactly two elements — [lower_bound, upper_bound]. The value type is determined by the field's data_type: use SimpleFilterCriterionValueString for date or datetime fields, and SimpleFilterCriterionValueNumber for integer, currency, or double fields. Resolve the data_type from the field's FieldSchema. For formula fields, use formula.return_type as the effective data_type; for rollup_summary fields, use rollup_summary.return_type. Additional keys: not allowed
comparator	string	Required within parent	Represents the range comparison operator applied to the criterion, indicating whether the field value falls within or outside the specified bounds. Possible values: between - Matches records where the field value falls within the specified range. not_between - Matches records where the field value falls outside the specified range. One of: between, not_between
field	JSON	Required within parent	Represents the target field definition to which the range filter criterion is applied, conforming to the base field structure.
field (allOf 1)	Model	All variants apply	Expand Related Records — request body — query / filters / value / comparator: in, not in, type: merge field, pre defined, value, field field api name, id
field (allOf 2)	object	All variants apply	Represents the field reference constraint that requires the api_name property to be present for the range filter criterion. Additional keys: allowed
type	string	Optional	Indicates the value resolution mode of the criterion, distinguishing whether the filter value is a literal value, a merge field reference, a predefined system variable, or another field reference. Possible values: value - The value is a direct literal. merge_field - The value is a merge field reference. pre_defined - The value is a predefined system variable placeholder. field - The value references another field. Default: value One of: merge_field, pre_defined, value, field
value	array	Required within parent	Contains the two boundary values — [lower_bound, upper_bound] — against which the field is evaluated for the between or not_between comparator. Maximum items: 2 Minimum items: 2
value[]	JSON	Each item
value[] (anyOf 1)	string	Alternative	Represents a string filter criterion value applicable to fields with a data_type of text, textarea, email, phone, website, autonumber, picklist, multiselectpicklist, date, or datetime, as well as any data_type not explicitly covered by SimpleFilterCriterionValueNumber, SimpleFilterCriterionValueBoolean, SimpleFilterCriterionValueObjectRequest, SimpleFilterCriterionValueObjectResponse, or the multiselect lookup value schemas. Maximum length: 255
value[] (anyOf 2)	number	Alternative	Represents a numeric filter criterion value applicable to fields with a data_type of integer, currency, or double.

Referenced models: Related Records — request body — query / filters / value / comparator: in, not in, type: merge field, pre defined, value, field field api name, id

Related Records — request body — query filters value value

Field	Type	Presence	Description and constraints
$	JSON	Root	Represents an equality filter criterion that dispatches to either the EqualFilterCriterionRequest or NotEqualFilterCriterionRequest schema based on the comparator value.
$ (anyOf 1)	Model	Alternative	Expand Related Records — request body — query / filters / value / value / comparator: equal, type: merge field, pre defined, value, field
$ (anyOf 2)	Model	Alternative	Expand Related Records — request body — query / filters / value / value / comparator: not equal, type: merge field, pre defined, value, field

Referenced models: Related Records — request body — query / filters / value / value / comparator: equal, type: merge field, pre defined, value, field, Related Records — request body — query / filters / value / value / comparator: not equal, type: merge field, pre defined, value, field

Related Records — request body — query / filters / value / comparator: in, not in, type: merge field, pre defined, value, field field api name, id

Field	Type	Presence	Description and constraints
$	object	Root	Represents the base field reference used in filter operations, containing minimal required properties. The field's data_type is not part of this object; resolve it from the corresponding FieldSchema. For formula fields, use formula.return_type as the effective data_type; for rollup_summary fields, use rollup_summary.return_type. Additional keys: allowed
api_name	string	Optional	Represents the API name of the field used for filter application. Supports relationship notation, for example, Deals__r.Stage.
id	string	Optional	Represents the unique ID of the field used for filter operations. Format: int64

Policy, approvals and errors

SDK function policy ID: zoho.getrelatedrecords. Catalog operation: getRelatedRecords. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

No-content response statuses: [204]

Official provider source