# Search & Filter Companies

Retrieve a list of companies and their corresponding details.

Endpoint: POST /data-api/v1/company/search
Security: authorization

## Request fields (application/json):

  - `fields` (array,null, required)
    List of fields to be selected.
    Enum: "company_id", "company_name", "domain_name", "domain_name_normalized"

  - `filters` (object, required)
    Filters object
    Example: {"company_identifiers":{"company_ids":{"ids":["1698C53EBC888758570396E0334965C1"],"inclusion_method":"ANY_PRESENT"}},"corporate_hierarchy":{"is_domestic_parent":true,"is_global_headquarters":true},"firmographics":{"country_codes":[{"ids":["US"],"inclusion_method":"ANY_PRESENT"}],"employees":{"max":2500000,"min":1500000},"industries":[{"ids":[16],"inclusion_method":"ANY_PRESENT"}],"region_names":{"ids":["AMER"],"inclusion_method":"ANY_PRESENT"},"revenue":{"max":700000000000,"min":600000000000}},"installs":{"product_attributes":{"ids":[222],"inclusion_method":"ANY_PRESENT"},"product_categories":{"ids":["319D067B229178F03BCFA1DA4AC4DEDE"],"inclusion_method":"ANY_PRESENT"},"products":[{"ids":[814],"inclusion_method":"ANY_PRESENT"}],"vendors":[{"ids":[316],"inclusion_method":"ANY_PRESENT"}]},"intent":{"signal_score":"MEDIUM","topics":{"ids":["19861D3AC60455102792F87A33AF533F"],"inclusion_method":"ANY_PRESENT"}},"spend":[{"categories":{"ids":["3B36D42E7F8E60BE58BA4356B6AF40C"],"inclusion_method":"ANY_PRESENT"},"range":{"min":2000000000}}]}

  - `filters.company_identifiers` (object)
    Filters based around company identifiers.
    Example: {"company_ids":{"ids":["1698C53EBC888758570396E0334965C1"],"inclusion_method":"ANY_PRESENT"}}

  - `filters.company_identifiers.company_ids` (object)
    A list of hex encoded company identifiers to filter your results by.
Any company that matches one of the provided identifiers will be returned.
    Example: {"ids":["1698C53EBC888758570396E0334965C1"],"inclusion_method":"ANY_PRESENT"}

  - `filters.company_identifiers.company_ids.ids` (array, required)
    Hex Encoded IDs
    Example: ["1698C53EBC888758570396E0334965C1"]

  - `filters.company_identifiers.company_ids.inclusion_method` (string, required)
    Inclusion method for just ANY_PRESENT
    Enum: "ANY_PRESENT"

  - `filters.company_identifiers.company_ids_including_corporate_relatives` (object)
    A list of hex encoded company identifiers to filter your results by.
Results will include both the companies which match the provided IDs, as well as all other companies within it's corporate hierarchy.
    Example: {"ids":["1698C53EBC888758570396E0334965C1"],"inclusion_method":"ANY_PRESENT"}

  - `filters.corporate_hierarchy` (object)
    Filters based on a company's corporate hierarchy classification.
    Example: {"is_domestic_parent":true,"is_global_headquarters":true}

  - `filters.corporate_hierarchy.is_corporate_parent` (boolean)
    Filter based on if a company is classified as a corporate parent or not.

  - `filters.corporate_hierarchy.is_domestic_parent` (boolean)
    Filter based on if a company is classified as a domestic parent or not.
    Example: true

  - `filters.corporate_hierarchy.is_global_headquarters` (boolean)
    Filter based on if a company is classified as a global headquarters or not.
    Example: true

  - `filters.firmographics` (object)
    Firmographic based filters for companies.
    Example: {"country_codes":[{"ids":["US"],"inclusion_method":"ANY_PRESENT"}],"employees":{"max":2500000,"min":1500000},"industries":[{"ids":[16],"inclusion_method":"ANY_PRESENT"}],"region_names":{"ids":["AMER"],"inclusion_method":"ANY_PRESENT"},"revenue":{"max":700000000000,"min":600000000000}}

  - `filters.firmographics.country_codes` (array)
    Filter by the country in which a company is based.
Accepts a list of alpha-2 codes along with an inclusion method, with the inclusion method specifying whether companies should be included or excluded from the results based on the provided country codes.
Alpha-2 codes are based on the ISO 3166 international standard. A complete list can be found here: https://www.iso.org/obp/ui/#search",
    Example: [{"ids":["CA","US"],"inclusion_method":"ANY_PRESENT"},{"ids":["GB"],"inclusion_method":"NONE_PRESENT"}]

  - `filters.firmographics.country_codes.ids` (array, required)
    Country Codes
    Example: ["CA","US"]

  - `filters.firmographics.country_codes.inclusion_method` (string, required)
    Inclusion method for just ANY_PRESENT or NONE_PRESENT
    Enum: "ANY_PRESENT", "NONE_PRESENT"

  - `filters.firmographics.employees` (object)
    Filter by the number of employees working at a company. Some companies are listed as having a single discrete number of employees, while others are listed as a range. By default this filter will match against both.
    Example: {"has_fixed_employees":true,"max":2500,"min":500}

  - `filters.firmographics.employees.has_fixed_employees` (boolean,null)
    Whether to limit the companies returned to those with a fixed number of employees (and exclude those listed as a range).
    Example: true

  - `filters.firmographics.employees.max` (integer,null)
    The maximum number of employees to match against.
    Example: 2500

  - `filters.firmographics.employees.min` (integer,null)
    The minimum number of employees to match against.
    Example: 500

  - `filters.firmographics.industries` (array)
    Filter by the industry which a company is categorized by.
Accepts a list of HG Insights derived identifiers along with an inclusion method, with the inclusion method specifying whether companies should be included or excluded from the results based on the provided industry ids.
    Example: [{"ids":[16],"inclusion_method":"ANY_PRESENT"}]

  - `filters.firmographics.industries.ids` (array, required)
    Numeric IDs
    Example: [16994]

  - `filters.firmographics.region_names` (object)
    Inclusion filter object (using string names as IDs)
    Example: {"ids":["CA","APAC"],"inclusion_method":"ANY_PRESENT"}

  - `filters.firmographics.region_names.ids` (array, required)
    Name IDs
    Example: ["CA","APAC"]

  - `filters.firmographics.revenue` (object)
    Filter by the revenue earned by a company. Some companies are listed as having a single discrete revenue value, while others are listed as a range. By default this filter will match against both.
    Example: {"has_fixed_revenue":true,"max":50000000,"min":10000000}

  - `filters.firmographics.revenue.has_fixed_revenue` (boolean,null)
    Whether to limit the companies returned to those listed with a single/fixed revenue value (and exclude those listed as a range).
    Example: true

  - `filters.firmographics.revenue.max` (integer,null)
    The maximum revenue to match against.
    Example: 50000000

  - `filters.firmographics.revenue.min` (integer,null)
    The minimum revenue to match against.
    Example: 10000000

  - `filters.firmographics.state_ids` (object)
    Inclusion filter object for use with hex encoded IDs. Can filter ids by ANY_PRESENT inclusion method
    Example: {"ids":["1698C53EBC888758570396E0334965C1"],"inclusion_method":"ANY_PRESENT"}

  - `filters.installs` (object)
    Filters based around the install records detected at a company.
    Example: {"product_attributes":{"ids":[222],"inclusion_method":"ANY_PRESENT"},"product_categories":{"ids":["319D067B229178F03BCFA1DA4AC4DEDE"],"inclusion_method":"ANY_PRESENT"},"products":[{"ids":[814],"inclusion_method":"ANY_PRESENT"}],"vendors":[{"ids":[316],"inclusion_method":"ANY_PRESENT"}]}

  - `filters.installs.product_attributes` (object)
    Filter based on the product attributes associated with an install record.
    Example: {"ids":[16994],"inclusion_method":"ANY_PRESENT"}

  - `filters.installs.product_categories` (object)
    Filter by Product Category IDs
    Example: {"ids":["1698C53EBC888758570396E0334965C1"],"inclusion_method":"ANY_PRESENT"}

  - `filters.installs.products` (array)
    Filter based on the associated products for an install record. Can provide a list of product filters so different inclusion methods may be combined.
    Example: [{"ids":[814],"inclusion_method":"ANY_PRESENT"}]

  - `filters.installs.vendors` (array)
    Filter based on the associated vendor for an install record. Can provide a list of vendor filters so different inclusion methods may be combined.
    Example: [{"ids":[316],"inclusion_method":"ANY_PRESENT"}]

  - `filters.intent` (object)
    Filters based around intent signals.
Intent signals are signals that indicate a company is showing interest in a particular topic.
    Example: {"signal_score":"MEDIUM","topics":{"ids":["19861D3AC60455102792F87A33AF533F"],"inclusion_method":"ANY_PRESENT"}}

  - `filters.intent.signal_score` (string, required)
    Filter based on the signal score for an intent signal.
Accepts either "MEDIUM" (from 65 to 84), and "HIGH" (from 85 to 100).
    Enum: "MEDIUM", "HIGH"

  - `filters.intent.topics` (object, required)
    Filter based on the topics associated with an intent signal.
    Example: {"ids":["1698C53EBC888758570396E0334965C1"],"inclusion_method":"ANY_PRESENT"}

  - `filters.intent.topics.inclusion_method` (string, required)
    Inclusion method for just ANY_PRESENT or ALL_PRESENT
    Enum: "ANY_PRESENT", "ALL_PRESENT"

  - `filters.spend` (array)
    Filter results based on spend filters
    Example: [{"categories":{"ids":["3B36D42E7F8E60BE58BA4356B6AF40C"],"inclusion_method":"ANY_PRESENT"},"range":{"min":2000000000}}]

  - `filters.spend.categories` (object, required)
    Inclusion filter object for use with hex encoded IDs. Can filter ids by ANY_PRESENT inclusion method
    Example: {"ids":["1698C53EBC888758570396E0334965C1"],"inclusion_method":"ANY_PRESENT"}

  - `filters.spend.range` (object, required)
    Example: {"max":100,"min":25}

  - `limit` (integer)
    The number of records to return in the request.

  - `offset` (integer)
    Used for paginating records.

  - `sorts` (array)
    List of Sort objects
    Example: [{"direction":"DESC","field":"company_name"}]

  - `sorts.direction` (string, required)
    Sort direction
    Enum: "ASC", "DESC"

  - `sorts.field` (string, required)
    Allowed fields to be selected and returned in the response.
    Enum: "company_id", "company_name", "domain_name", "domain_name_normalized"

## Response 200 fields (application/json):

  - `count` (integer)
    The total number of companies that match the search criteria.

  - `data` (array)

  - `data.company_name` (string)

  - `data.domain_name` (string)

  - `data.domain_name_normalized` (string)

  - `data.hg_id` (string)

## Response 401 fields (application/json):

  - `errors` (array)

  - `errors.detail` (string, required)
    Example: "The token provided is not valid"

  - `errors.source` (object)

  - `errors.title` (string, required)
    Example: "Unauthorized"

## Response 404 fields (application/json):

  - `errors` (array)

  - `errors.detail` (string, required)

  - `errors.source` (object)

  - `errors.title` (string, required)
    Example: "Not Found"

## Response 422 fields (application/json):

  - `errors` (array, required)

  - `errors.detail` (string, required)
    Example: "null value where string expected"

  - `errors.source` (object, required)

  - `errors.source.pointer` (string, required)
    Example: "/data/attributes/petName"

  - `errors.title` (string, required)
    Example: "Invalid value"