--- title: "Enrich Corporate Hierarchy" method: POST path: "/data/v1/companies/corporate-hierarchy/enrich" tags: ["Enrich"] --- # Enrich Corporate Hierarchy `POST /data/v1/companies/corporate-hierarchy/enrich` ## Request - Base URL: `https://api.zoominfo.com/gtm` - URL: `https://api.zoominfo.com/gtm/data/v1/companies/corporate-hierarchy/enrich` - Auth: OAuth 2 - Authorization code: `https://login.zoominfo.com` - Token URL: `https://okta-login.zoominfo.com/oauth2/default/v1/token` scopes: `api:data:company` 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. ## Request body - CorporateHierarchyEnrichRequest: Corporate hierarchy enrich request. - `data` CorporateHierarchyEnrichRequestResource, required: Corporate hierarchy enrich request resource. - `type` string, required: The type of the resource - `attributes` CorporateHierarchyEnrichRequestAttributes, required: Corporate hierarchy enrich request attributes. - `outputFields` string[], required: List of fields to be returned in the response. - `matchCompanyInput` CorporateHierarchyEnrichRequestCriteria[], required: List of criteria to match against. - `companyId` integer: Unique ZoomInfo identifier for a company. - `companyName` string: Company name. - `companyWebsite` string: Company website URL in http://www.example.com format. ## Response `200` Success - CorporateHierarchyEnrichResponse: Corporate hierarchy enrich response. - `data` CorporateHierarchyEnrichResponseResourceUnion[], required: The primary data of the document - union: 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. - object: 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. - `id` string, required: The unique identifier for the resource - `type` string, required: The type of the resource - `attributes` CorporateHierarchyEnrichResponseAttributes, required: Corporate hierarchy enrich response attributes. - `companyId` integer: Unique ZoomInfo identifier for a company. - `parentage` Parentage[]: Lists companies higher up in the corporate hierarchy for this company. - `city` string: City of the company's primary address. - `state` string: State or province of the company's primary address. - `companyId` string: Unique ZoomInfo identifier for a company. - `companyName` string: Company name. - `subUnitType` string: Company sub types (e.g., division, subsidiary). Use this in conjunction with parentId or ultimateParentId. - `subUnitDesc` string: Contains a description of the sub unit listed in the corporate hierarchy. - `acquiredByDate` string: Denotes the date when the parent company acquired the input company if available. - `familyTree` FamilyTree[]: Lists companies and locations in the family tree for this company. - `city` string: City of the company's primary address. - `state` string: State or province of the company's primary address. - `companyId` integer: Unique ZoomInfo identifier for a company. - `name` string: Company name. - `familyNodes` FamilyNode[]: Denotes a branch or sub-branch of the family tree within the corporate hierarchy. - … - `meta` CorporateHierarchyAttributeMeta: 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. - `matchStatus` 'FULL_MATCH' | 'NO_MATCH' | 'LIMIT_EXCEEDED' | 'INVALID_INPUT', required - `input` CorporateHierarchyEnrichRequestCriteria, required: Corporate hierarchy enrich request criteria. - `companyId` integer: Unique ZoomInfo identifier for a company. - `companyName` string: Company name. - `companyWebsite` string: Company website URL in http://www.example.com format. - `warnings` Warning[]: Details about any warnings encountered during the validation of the enrich request input criteria. - `code` string: Warning code. - `message` string: Warning message. - `fields` string[]: Fields associated with the warning. - object: 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. - `id` string, required: The unique identifier of the resource - `type` string, required: The type identifier of the resource - `meta` CorporateHierarchyAttributeMeta: 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. - `matchStatus` 'FULL_MATCH' | 'NO_MATCH' | 'LIMIT_EXCEEDED' | 'INVALID_INPUT', required - `input` CorporateHierarchyEnrichRequestCriteria, required: Corporate hierarchy enrich request criteria. - `companyId` integer: Unique ZoomInfo identifier for a company. - `companyName` string: Company name. - `companyWebsite` string: Company website URL in http://www.example.com format. - `warnings` Warning[]: Details about any warnings encountered during the validation of the enrich request input criteria. - `code` string: Warning code. - `message` string: Warning message. - `fields` string[]: Fields associated with the warning. ## Other responses - `400`: Bad Request - `401`: Unauthorized - `403`: Forbidden - `429`: Too Many Requests --- [API](https://skmtc.dev/zoominfo/apis/data-api-v1.md) - [All operations](https://skmtc.dev/zoominfo/apis/data-api-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/zoominfo/apis/data-api-v1/revisions/02250fbd2ef5?raw)