--- updatedAt: 2026-05-19T16:20:43.000Z agentTools: projectIndex: https://docs.gtm.ai/llms.txt --- # Enrich Corporate Hierarchy Enrich the corporate hierarchy structure of up to 25 individual company records. Based on the provided inputs, ZoomInfo will find the Company that best matches in provided inputs and return the full corporate hierarchy structure for the matched Company. Corporate hierarchy structure includes the `familyTree` which starts at the top-level parent company for the matched Company, and lists all Subsidiaries, Acquisitions, Former Names (if a company within the hierarchy has officially changed names previously). The `familyTree` also lists all known Locations for each company within the hierarchy. If no match can be made from the provided input values, then a `NoMatch` record is returned. Additionally, if the company that was matched **IS NOT** the company at the top of the hierarchy structure, the `parentage` can be provided in the response. This lists the all of the parent companies for the matched company all the way to the top-level (ultimate parent) company. The desired `outputFields` must be provided for each request. For more details about all of the available output fields you can select, please use the [Lookup Enrich](ref:lookupenrichinterface_lookupenrich) endpoint (`filter[entity]=corporate-hierarchy` and `filter[fieldType]=output`). This will provide a description of each available field, as well as whether or not your account has access to this field. If you do not have access to a field that you need, please contact your ZoomInfo Account Manager for purchasing options. Each record returned by this endpoint will charge a credit from your account, unless that record is already under management (see [Credit Usage and Limits Guide](doc:credit-usage-and-limits) for more details). If we fail to find the record and return `NoMatch` or if we return an error code a credit will not be charged. # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "title": "Data API V1", "version": "1.0", "contact": { "name": "ZoomInfo Customer Support", "email": "help@zoominfo.com" }, "description": "The Data API" }, "tags": [ { "name": "Enrich" } ], "paths": { "/data/v1/companies/corporate-hierarchy/enrich": { "post": { "operationId": "EnrichInterface_enrichCorporateHierarchy", "summary": "Enrich Corporate Hierarchy", "description": "Enrich the corporate hierarchy structure of up to 25 individual company records. Based on the provided inputs, \nZoomInfo will find the Company that best matches in provided inputs and return the full corporate hierarchy\nstructure for the matched Company. Corporate hierarchy structure includes the `familyTree` which starts at the \ntop-level parent company for the matched Company, and lists all Subsidiaries, Acquisitions, Former Names (if a company\nwithin the hierarchy has officially changed names previously). The `familyTree` also lists all known Locations for each \ncompany within the hierarchy. If no match can be made from the provided input values, then a `NoMatch` record is returned.\n\nAdditionally, if the company that was matched **IS NOT** the company at the top of the hierarchy structure, the `parentage` can\nbe provided in the response. This lists the all of the parent companies for the matched company all the way to the top-level\n(ultimate parent) company.\n\nThe desired `outputFields` must be provided for each request. For more details about all of the available output fields \nyou can select, please use the [Lookup Enrich](https://docs.gtm.ai/zoominfoenterprise/reference/lookupenrichinterface_lookupenrich) endpoint (`filter[entity]=corporate-hierarchy`\nand `filter[fieldType]=output`). This will provide a description of each available field, as well as whether or not your account has\naccess to this field. If you do not have access to a field that you need, please contact your ZoomInfo Account Manager for purchasing options.\n\nEach record returned by this endpoint will charge a credit from your account, unless that record is already under management \n(see [Credit Usage and Limits Guide](https://docs.gtm.ai/zoominfoenterprise/docs/credit-usage-and-limits) for more details). If we fail to find the record and return \n`NoMatch` or if we return an error code a credit will not be charged.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/CorporateHierarchyEnrichResponse" }, "examples": { "Enrich Corporate Hierarchy Data by Company ID": { "summary": "Enrich Corporate Hierarchy Data by Company ID", "description": "This example demonstrates how to enrich corporate hierarchy data using a companyId input. The response includes the family tree showing ZoomInfo's subsidiaries with their organizational relationships.", "value": { "data": [ { "attributes": { "companyId": 344589814, "familyTree": [ { "companyId": 344589814, "name": "ZoomInfo", "city": "Vancouver", "state": "Washington", "familyNodes": [ { "name": "Comparably", "companyId": 382321985, "city": "Santa Monica", "state": "California", "subUnitTypeInfo": { "typeId": 4, "typeDescription": "Subsidiary" } }, { "name": "DiscoverOrg", "companyId": 346572700, "city": "Vancouver", "state": "Washington", "subUnitTypeInfo": { "typeId": 5, "typeDescription": "Acquisition" } } ] } ] }, "id": "344589814", "meta": { "input": { "companyId": 344589814 }, "matchStatus": "FULL_MATCH" }, "type": "CorporateHierarchy" } ] } } } } } }, "400": { "description": "Bad Request", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel" } } } }, "401": { "description": "Unauthorized", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel" } } } }, "403": { "description": "Forbidden", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel" } } } }, "429": { "description": "Too Many Requests", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel" } } } } }, "tags": [ "Enrich" ], "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/CorporateHierarchyEnrichRequest" }, "examples": { "Enrich Corporate Hierarchy Data by Company ID": { "summary": "Enrich Corporate Hierarchy Data by Company ID", "description": "This example demonstrates how to enrich corporate hierarchy data using a companyId input. The response includes the family tree showing ZoomInfo's subsidiaries with their organizational relationships.", "value": { "data": { "attributes": { "matchCompanyInput": [ { "companyId": 344589814 } ], "outputFields": [ "familyTree", "companyId" ] }, "type": "CorporateHierarchyEnrich" } } } } } }, "description": "The request body containing corporate hierarchy enrich criteria." }, "security": [ { "OAuth2Auth": [ "api:data:company" ] } ], "x-additional-content-types": [ "application/json" ], "x-api-roles": [ "fea:zia", "fea:api" ], "x-api-role-requirement": "ANY_REQUIRED" } } }, "security": [ { "OAuth2Auth": [] } ], "components": { "schemas": { "ZoomInfo.Core.Foundations.ErrorSourceModel": { "type": "object", "properties": { "cookie": { "type": "string", "description": "Identifies the cookie name that caused the issue" }, "header": { "type": "string", "description": "Identifies the header name that caused the error" }, "pointer": { "type": "string", "description": "An RFC 6901 compliant JSON pointer to the entity in the request body that caused the error" }, "parameter": { "type": "string", "description": "The name of the path or query parameter that caused the error" } } }, "ZoomInfo.Core.Foundations.ErrorModel": { "type": "object", "required": [ "id", "code", "status" ], "properties": { "id": { "type": "string", "description": "The unique id used to identify this specific error instance" }, "code": { "type": "string", "description": "The error code describing the error category. A full list of error codes can be found in the documentation for each service" }, "detail": { "type": "string", "description": "Message containing the specific details about this occurrence of the error" }, "source": { "allOf": [ { "$ref": "#/components/schemas/ZoomInfo.Core.Foundations.ErrorSourceModel" } ], "description": "An optional object identifying which part of the request caused the error" }, "status": { "type": "string", "description": "The HTTP status code for the error" }, "title": { "type": "string", "description": "The error name that describes this type of error" } }, "description": "The object describing a specific error from the API" }, "ZoomInfo.Core.Foundations.ErrorResponseModel": { "type": "object", "required": [ "errors" ], "properties": { "detail": { "type": "string", "description": "A high-level detail of the error(s) that occurred during the request" }, "title": { "type": "string", "description": "A high-level summary of the error(s) detected" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ZoomInfo.Core.Foundations.ErrorModel" }, "description": "The list of errors raised during the request" } }, "description": "The standard error response body model for the ZoomInfo API." }, "Warning": { "type": "object", "properties": { "code": { "type": "string", "description": "Warning code." }, "message": { "type": "string", "description": "Warning message." }, "fields": { "type": "array", "items": { "type": "string" }, "description": "Fields associated with the warning." } }, "description": "Warning details for validation issues." }, "CompanyMatchStatus": { "type": "string", "enum": [ "FULL_MATCH", "NO_MATCH", "LIMIT_EXCEEDED", "INVALID_INPUT" ], "x-enumDescriptions": { "FULL_MATCH": "Match status indicating a full match with all criteria met.", "NO_MATCH": "Match status indicating no match found.", "LIMIT_EXCEEDED": "Match status indicating the enrich request credit limit has been exceeded.", "INPUT_ERROR": "Match status indicating an error with the input data." } }, "Parentage": { "type": "object", "properties": { "city": { "type": "string", "description": "City of the company's primary address." }, "state": { "type": "string", "description": "State or province of the company's primary address." }, "companyId": { "type": "string", "description": "Unique ZoomInfo identifier for a company." }, "companyName": { "type": "string", "description": "Company name." }, "subUnitType": { "type": "string", "description": "Company sub types (e.g., division, subsidiary). Use this in conjunction with parentId or ultimateParentId." }, "subUnitDesc": { "type": "string", "description": "Contains a description of the sub unit listed in the corporate hierarchy." }, "acquiredByDate": { "type": "string", "description": "Denotes the date when the parent company acquired the input company if available." } }, "description": "Lists companies higher up in the corporate hierarchy for this company." }, "SubUnitTypeInfo": { "type": "object", "required": [ "typeDescription" ], "properties": { "typeId": { "type": "integer", "description": "ID of the sub unit type." }, "typeDescription": { "type": "string", "description": "Description of the sub unit type." } }, "description": "Denotes the type of sub-unit represented by a family node within the corporate hierarchy." }, "FamilyNode": { "type": "object", "required": [ "subUnitTypeInfo" ], "properties": { "city": { "type": "string", "description": "City of the company's primary address." }, "state": { "type": "string", "description": "State or province of the company's primary address." }, "name": { "type": "string", "description": "Company name." }, "companyId": { "type": "integer", "format": "int64", "description": "Unique ZoomInfo identifier for a company." }, "subUnitTypeInfo": { "allOf": [ { "$ref": "#/components/schemas/SubUnitTypeInfo" } ], "description": "Denotes the type of sub-unit represented by a family node within the corporate hierarchy." }, "familyNodes": { "description": "Denotes a branch or sub-branch of the family tree within the corporate hierarchy.", "type": "array", "items": { "$ref": "#/components/schemas/FamilyNode" } } }, "description": "Family node information." }, "FamilyTree": { "type": "object", "properties": { "city": { "type": "string", "description": "City of the company's primary address." }, "state": { "type": "string", "description": "State or province of the company's primary address." }, "companyId": { "type": "integer", "format": "int64", "description": "Unique ZoomInfo identifier for a company." }, "name": { "type": "string", "description": "Company name." }, "familyNodes": { "type": "array", "items": { "$ref": "#/components/schemas/FamilyNode" }, "description": "Denotes a branch or sub-branch of the family tree within the corporate hierarchy." } }, "description": "Family tree information." }, "CorporateHierarchyEnrichResponseAttributes": { "type": "object", "properties": { "companyId": { "type": "integer", "format": "int64", "description": "Unique ZoomInfo identifier for a company." }, "parentage": { "type": "array", "items": { "$ref": "#/components/schemas/Parentage" }, "description": "Lists companies higher up in the corporate hierarchy for this company." }, "familyTree": { "type": "array", "items": { "$ref": "#/components/schemas/FamilyTree" }, "description": "Lists companies and locations in the family tree for this company." } }, "description": "Corporate hierarchy enrich response attributes." }, "CorporateHierarchyEnrichRequestCriteria": { "type": "object", "properties": { "companyId": { "type": "integer", "format": "int64", "description": "Unique ZoomInfo identifier for a company." }, "companyName": { "type": "string", "description": "Company name." }, "companyWebsite": { "type": "string", "description": "Company website URL in http://www.example.com format." } }, "description": "Corporate hierarchy enrich request criteria." }, "CorporateHierarchyAttributeMeta": { "type": "object", "required": [ "matchStatus", "input" ], "properties": { "matchStatus": { "allOf": [ { "$ref": "#/components/schemas/CompanyMatchStatus" } ], "description": "The match status for the corporate hierarchy enrich operation, indicating whether a match was found and the type of match." }, "input": { "allOf": [ { "$ref": "#/components/schemas/CorporateHierarchyEnrichRequestCriteria" } ], "description": "The input criteria that was used to perform the corporate hierarchy enrich match. This provides traceability for the match result." }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/Warning" }, "description": "Details about any warnings encountered during the validation of the enrich request input criteria." } }, "description": "Metadata describing the result of a corporate hierarchy enrich match, including the match status and the input criteria used for the match. Used to provide additional context about how the corporate hierarchy enrich response was determined." }, "EnrichCorporateHierarchy": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The unique identifier for the resource" }, "type": { "type": "string", "description": "The type of the resource", "default": "CorporateHierarchy", "pattern": "CorporateHierarchy" }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/CorporateHierarchyEnrichResponseAttributes" } ], "description": "The attributes defining the resource" }, "meta": { "allOf": [ { "$ref": "#/components/schemas/CorporateHierarchyAttributeMeta" } ], "description": "Non-standard meta information about the resource" } }, "description": "A matching corporate hierarchy was identified from the provided input data. This result will always be a FULL_MATCH (where the company information matched). The match status can be found within the meta object for reference." }, "NoMatchCorporateHierarchy": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "The unique identifier of the resource" }, "type": { "type": "string", "description": "The type identifier of the resource", "default": "NoMatch", "pattern": "NoMatch" }, "meta": { "allOf": [ { "$ref": "#/components/schemas/CorporateHierarchyAttributeMeta" } ], "description": "Non-standard meta information about the resource" } }, "description": "There was not a matching corporate hierarchy found for the provided input or is been filtered out because of match statue - LIMIT_EXCEEDED (User credit limit has been exceeded). Exact details can be found within the meta object including the match status and other accompanying metadata." }, "CorporateHierarchyEnrichResponseResourceUnion": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/EnrichCorporateHierarchy" }, { "$ref": "#/components/schemas/NoMatchCorporateHierarchy" } ], "discriminator": { "propertyName": "type", "mapping": { "CorporateHierarchy": "#/components/schemas/EnrichCorporateHierarchy", "NoMatch": "#/components/schemas/NoMatchCorporateHierarchy" } }, "description": "Represents the possible resource types returned in a corporate hierarchy enrich response, including both a successful corporate hierarchy match and a no-match result. Used to encapsulate the response resource for corporate hierarchy enrichment." }, "CorporateHierarchyEnrichResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CorporateHierarchyEnrichResponseResourceUnion" }, "description": "The primary data of the document" } }, "description": "Corporate hierarchy enrich response." }, "CorporateHierarchyEnrichRequestAttributes": { "type": "object", "required": [ "outputFields", "matchCompanyInput" ], "properties": { "outputFields": { "type": "array", "items": { "type": "string" }, "description": "List of fields to be returned in the response." }, "matchCompanyInput": { "type": "array", "items": { "$ref": "#/components/schemas/CorporateHierarchyEnrichRequestCriteria" }, "minItems": 1, "maxItems": 25, "description": "List of criteria to match against." } }, "description": "Corporate hierarchy enrich request attributes." }, "CorporateHierarchyEnrichRequestResource": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "description": "The type of the resource", "default": "CorporateHierarchyEnrich", "pattern": "CorporateHierarchyEnrich" }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/CorporateHierarchyEnrichRequestAttributes" } ], "description": "The attributes defining the resource" } }, "description": "Corporate hierarchy enrich request resource." }, "CorporateHierarchyEnrichRequest": { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/CorporateHierarchyEnrichRequestResource" } ], "description": "The primary data of the document" } }, "description": "Corporate hierarchy enrich request." } }, "securitySchemes": { "OAuth2Auth": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://login.zoominfo.com", "tokenUrl": "https://okta-login.zoominfo.com/oauth2/default/v1/token", "scopes": { "api:data:contact": "Ability to search and enrich ZoomInfo Contact data", "api:data:company": "Ability to search and enrich ZoomInfo Company data", "api:data:intent": "Ability to search and enrich ZoomInfo Intent data", "api:data:news": "Ability to search and enrich ZoomInfo News data", "api:data:scoops": "Ability to search and enrich ZoomInfo Scoop data", "api:data:lookup": "Lookup ZoomInfo Data" } } } } } }, "servers": [ { "url": "https://api.zoominfo.com/gtm", "description": "Base URL for the Data API" } ] } ``` # Sibling pages * [Enrich Contacts](https://docs.gtm.ai/zoominfoenterprise/reference/enrichinterface_enrichcontact.md) * [Enrich Companies](https://docs.gtm.ai/zoominfoenterprise/reference/enrichinterface_enrichcompany.md) * [Enrich Intent](https://docs.gtm.ai/zoominfoenterprise/reference/enrichinterface_enrichintent.md) * [Enrich News](https://docs.gtm.ai/zoominfoenterprise/reference/enrichinterface_enrichnews.md) * [Enrich Org Charts](https://docs.gtm.ai/zoominfoenterprise/reference/enrichinterface_enrichorgchart.md) * [Enrich Scoops](https://docs.gtm.ai/zoominfoenterprise/reference/enrichinterface_enrichscoop.md) * [Enrich Technologies](https://docs.gtm.ai/zoominfoenterprise/reference/enrichinterface_enrichtechnology.md) * [Enrich Hashtags](https://docs.gtm.ai/zoominfoenterprise/reference/enrichinterface_enrichhashtag.md)