Search Companies

Endpoint Overview

The Search Companies endpoint returns an array of company ids based on specific filters.

• URL: https://api.profileapi.com/2024-03-01/companies/search
• 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: 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": "=" }

Filter Keys

Key	Value Type	Description
name	string	The company's name, including any suffixes such as "Inc." if applicable.
headcount	number	The total number of employees working at the company.
website	string	A link to the company's website, formatted according to RFC 3986 guidelines.
industry	string	Industry that company belongs to. Complete List
niche	string	Niche that company is in. Complete List
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.
trait.[traitKey].firstSeenAt	date	When the trait was first observed on the company.
trait.[traitKey].lastSeenAt	date	The most recent time the trait was seen.
trait.[traitKey].lastUnseenAt	date	The time the trait was last confirmed to be inactive.

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": "="
}

You can also filter based on date fields such as firstSeenAt, lastSeenAt, or lastUnseenAt.

Absolute date example:

{
  "key": "trait.businessWebsitePageBlog.firstSeenAt",
  "value": "2024-01-01T00:00:00Z",
  "operator": ">"
}

Relative date example:

{
  "key": "trait.businessWebsitePageBlog.firstSeenAt",
  "value": "now-30d/d",
  "operator": ">"
}

Refer to the Complete List for valid traitKey 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

important

All string matches are case insensitives.

Limit

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

Example

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

Response

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

Id

• Key: id
• Data Type: uuid
• Description: A universally unique identifier (UUID) compliant with RFC 4122, used to uniquely identify a person. Presented without hyphens.
• Example: "9e6a55b258ef11edb8780242ac120002"

Example

{
  "data": {
    "results": ["9e6a55b258ef11edb8780242ac120002"],
    "pagination": {
      "nextStart": [
        {
          "id": "9e6a55b258ef11edb8780242ac121233",
          "score": 0.92
        }
      ]
    }
  }
}