Search Persons

Endpoint Overview

The Search persons endpoint retrieves an array of person object models based on specific filters.

• URL: https://api.profileapi.com/2024-03-01/persons/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": "United States", "operator": "=" }

Filter Keys

Filter

Key	Value Type	Description
name	string
firstName	string
lastName	string
birthYear	number
unitedStatesStateCode	string	Complete List
unitedStatesCity	string
unitedStatesRegion	string	Complete List
countryCode	string	Complete List
worldRegion	string	Complete List
titleAtCurrentCompany	string
currentCompanyName	string
currentCompanyStartedAt	date
currentCompanyHeadcount	number	The total number of employees working at the company.
currentCompanyWebsite	string	A link to the company's website, formatted according to RFC 3986 guidelines.
currentCompanyUnitedStatesHeadquartersStateCode	string	The U.S. state codes where the company's headquarters are located, if applicable. Complete List
currentCompanyUnitedStatesHeadquartersCity	string	Name of the city.
currentCompanyUnitedStatesHeadquartersRegion	string	Details geographical locations of company headquarters in the United States. Complete List
currentCompanyHeadquartersCountryCode	string	The country codes where the company's headquarters are located, compliant with ISO 3166-1 alpha-2. Complete List
currentCompanyHeadquartersWorldRegion	string	Details geographical locations of company headquarters globally. Complete List
titleAtCurrentCompany	string
currentCompanyName	string
currentCompanyStartedAt	date
currentCompanyHeadcount	number	The total number of employees working at the company.
currentCompanyWebsite	string	A link to the company's website, formatted according to RFC 3986 guidelines.
currentCompanyUnitedStatesHeadquartersStateCode	string	The U.S. state codes where the company's headquarters are located, if applicable. Complete List
currentCompanyUnitedStatesHeadquartersCity	string	Name of the city.
currentCompanyUnitedStatesHeadquartersRegion	string	Details geographical locations of company headquarters in the United States. Complete List
currentCompanyHeadquartersCountryCode	string	The country codes where the company's headquarters are located, compliant with ISO 3166-1 alpha-2. Complete List
currentCompanyHeadquartersWorldRegion	string	Details geographical locations of company headquarters globally. Complete List
titleAtPreviousCompany	string
previousCompanyName	string
previousCompanyStartedAt	date
previousCompanyHeadcount	number	The total number of employees working at the company.
previousCompanyWebsite	string	A link to the company's website, formatted according to RFC 3986 guidelines.
previousCompanyUnitedStatesHeadquartersStateCode	string	The U.S. state codes where the company's headquarters are located, if applicable. Complete List
previousCompanyUnitedStatesHeadquartersCity	string	Name of the city.
previousCompanyUnitedStatesHeadquartersRegion	string	Details geographical locations of company headquarters in the United States. Complete List
previousCompanyHeadquartersCountryCode	string	The country codes where the company's headquarters are located, compliant with ISO 3166-1 alpha-2. Complete List
previousCompanyHeadquartersWorldRegion	string	Details geographical locations of company headquarters globally. Complete List

Operators

Operator	Valid Types	Description
=	string, number	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": "countryCode", "value": "US", "operator": "=" },
      { "key": "unitedStatesStateCode", "value": "CA", "operator": "=" },
    ],
    "any": [ 
      { "key": "titleAtCurrentCompany", "value": "CEO", "operator": "=" },
      { "key": "titleAtCurrentCompany", "value": "Founder", "operator": "=" },
     ]
  },
  "limit": 100
}

Response

The response returns an array of person 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
        }
      ]
    }
  }
}