Find Companies

Endpoint Overview

The Find Companies endpoint returns an array of company objects based on specific filters. Search for companies using various criteria including identifiers, location, headcount, traits, and signals.

• URL: https://api.profileapi.com/2024-03-01/companies/find
• HTTP Method: POST

Request

Parameters

Filters

• Key: filters
• Data Type: object
• Required: true
• Description: Enables advanced filtering by specifying conditions that must be met.
• Structure
  • all: An array of filter that must all be satisfied.
  • any: An array of filter where at least one must be satisfied.

{
  "all": ["<filter>"],
  "any": ["<filter>"]
}

Filter

• Structure
  • key: The filter key. See Filter Keys below.
  • value (optional): The value of the filter. it's a string or a number
  • operator: The operators based on the key type. See below Operators.
• Example

{ "key": "headquartersCountryCode", "value": "US", "operator": "=" }

{ "key": "financeFundingLastRoundBetween1M5M", "operator": "?" }

Filter Keys

Key	Value Type	Description
id	string	Universally unique identifier (UUID) compliant with RFC 4122 specification, used to uniquely identify entities in the system. Presented without hyphens.
linkedInUrl	string	URL to a LinkedIn company profile. Format: https://linkedin.com/company/[handle]
linkedInId	string	LinkedIn company ID.
name	string	The company's name, including any suffixes such as "Inc." if applicable.
website	string	A link to the company's website, formatted according to RFC 3986 guidelines.
headcount	number	The total number of employees working at the company.
unitedStatesHeadquartersStateCode	string	The U.S. state codes where the company's headquarters are located, if applicable. Complete List
unitedStatesHeadquartersCity	string	Name of the city.
unitedStatesHeadquartersRegion	string	Geographical region of company headquarters in the U.S. Complete List
headquartersCountryCode	string	Country codes for company HQ, compliant with ISO 3166-1 alpha-2. Complete List
headquartersWorldRegion	string	World region of company headquarters. Complete List
trait.[traitKey].isActive	boolean	Whether the trait is currently active.
signalKey	string	A signal that describes the company's current or historical state.

important

To filter on a specific trait, use dot notation. For example, to find companies where the businessWebsitePageBlog trait is active, use:

{
  "key": "trait.businessWebsitePageBlog.isActive",
  "value": true,
  "operator": "="
}

Refer to the Complete List for valid traitKey values.

important

To filter on a specific signal, use the exists operator (?) and pass the signal value as the filter key. Do not include a value field. Example:

{ "key": "financeFundingLastRoundBetween1M5M", "operator": "?" }

Refer to the Complete List for valid signal values.

Operators

Operator	Valid Types	Description
=	string, number, boolean	Equals
!=	string, number	Doesn't Equal
<	number, date	Greater than
>	number, date	Lower than
~	string	Contains
!~	string	Doesn't Contain
?	N/A	Exists
!?	N/A	Not Exists

important

All string matches are case insensitive.

For the ? and !? operators, do not provide a value field in the filter object.

Dataset

• Key: dataset
• Data Type: Array of <string>
• Required: false
• Default: ["basic"]
• Description: Specifies which datasets to include in the response. Each dataset affects the credits charged per company.
• Options:

Name	Credits Per Company	Description
basic	0.25	Basic company information such as company Name, Website, Links, Headquarters Locations
all	4.5	All available datasets including AI generated traits and signals
market	1	Market AI dataset - industry, niche focus, service model, and software specialization
business	1	Business AI dataset - pricing models, revenue strategies, buyer types, and product delivery
culture	0.5	Culture AI dataset - internal values, work practices, and organizational identity
legal	0.5	Legal AI dataset - structural, regulatory, and compliance-related traits
website	0.5	Website AI dataset - digital presence, site structure, content signals, and traffic data
finance	1	Finance AI dataset - financial performance, funding status, and investment activity

• Example: ["market", "finance"]

important

When filtering by traits or signals, you can only use traits and signals that belong to the datasets specified in your request. For example, if you specify dataset: ["business"], you can only filter using business-related traits and signals. Attempting to filter using traits or signals from other datasets will return a 400 error.

The all dataset allows filtering by any trait or signal.

Refer to the Complete List of Traits and Complete List of Signals for valid values by dataset.

Please refer to company object model for field details by dataset.

Limit

• Key: limit
• Data Type: number
• Required: false
• Default: 10
• Description: Specifies the maximum number of results to return. Maximum allowed value of 100.
• Example: 100

Examples

Search by location and headcount

{
  "filters": {
    "all": [
      { "key": "headquartersCountryCode", "value": "US", "operator": "=" },
      {
        "key": "unitedStatesHeadquartersStateCode",
        "value": "CA",
        "operator": "!="
      }
    ],
    "any": [{ "key": "headcount", "value": 10, "operator": ">" }]
  },
  "dataset": ["market"],
  "limit": 100
}

Find by company ID

{
  "filters": {
    "all": [
      { "key": "id", "value": "9e6a55b258ef11edb8780242ac120002", "operator": "=" }
    ]
  },
  "dataset": ["all"]
}

Find by LinkedIn URL

{
  "filters": {
    "all": [
      { "key": "linkedInUrl", "value": "https://linkedin.com/company/acme", "operator": "=" }
    ]
  },
  "dataset": ["finance", "legal"]
}

Find by company name and website

{
  "filters": {
    "all": [
      { "key": "name", "value": "Acme Corporation", "operator": "=" },
      { "key": "website", "value": "https://acme.com", "operator": "=" }
    ]
  },
  "dataset": ["market", "business"]
}

Response

The response returns an array of company objects, along with pagination information.

Example

{
  "data": {
    "results": [
      {
        "id": "9e6a55b258ef11edb8780242ac120002",
        "name": "Acme Corporation",
        "logoUrl": "https://d1hbpr09pwz0sk.cloudfront.net/logo_url/607a654e",
        "headcount": 35,
        "stockSymbol": "ACME",
        "website": "https://acmecorp.com",
        "angellistUrl": "https://angel.co/acmecorp",
        "crunchbaseUrl": "https://www.crunchbase.com/organization/acmecorp",
        "facebookUrl": "https://facebook.com/acmecorp",
        "githubUrl": "https://github.com/acmecorp",
        "linkedInUrl": "https://linkedin.com/company/acmecorp",
        "xUrl": "https://twitter.com/acmecorp",
        "youtubeUrl": "https://youtube.com/user/acmecorp",
        "unitedStatesHeadquartersStateCodes": ["CA"],
        "unitedStatesHeadquartersCities": ["San Francisco"],
        "unitedStatesHeadquartersRegions": ["East Coast"],
        "headquartersCountryCodes": ["US"],
        "headquartersWorldRegions": ["North America"],
        "traits": [
          {
            "key": "legalComplianceCCPA",
            "isActive": true
          },
          {
            "key": "legalComplianceGDPR",
            "isActive": false
          },
          {
            "key": "businessModelTypeSubscription",
            "isActive": true
          },
          {
            "key": "businessModelB2B",
            "isActive": true
          }
        ],
        "signals": [
          "legalComplianceCCPALast12Months",
          "legalComplianceGDPRMoreThan12Months",
          "businessModelTypeSubscriptionLast12Months"
        ]
      }
    ],
    "pagination": {
      "nextStart": [
        {
          "id": "9e6a55b258ef11edb8780242ac121233",
          "score": 0.92
        }
      ]
    }
  }
}

info

You will only be charged credits on successful company matches. If we don't find a company, you will not be charged for that company.