Find Persons

Endpoint Overview

The Find Persons endpoint returns an array of person objects based on specific filters. Search for persons using various criteria including identifiers, location, current company information, and personal details.

• URL: https://api.profileapi.com/2024-03-01/persons/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: 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": "countryCode", "value": "US", "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 person profile. Format: https://linkedin.com/in/[handle]
name	string	Person's full name
unitedStatesStateCode	string	The U.S. state codes where the person is located, if applicable. Complete List
unitedStatesCity	string	Name of the city where the person is located
countryCode	string	Country codes for person location, compliant with ISO 3166-1 alpha-2. Complete List
worldRegion	string	World region where the person is located. Complete List
titleAtCurrentCompany	string	Current job title at their company
currentCompanyName	string	Name of the person's current company
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
currentCompanyTrait.[traitKey].isActive	boolean	Whether the trait is currently active.

important

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

{
  "key": "currentCompanyTrait.businessWebsitePageBlog.isActive",
  "value": true,
  "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 insensitive.

Fields To Return

• Key: fieldsToReturn
• Data Type: string
• Description: The fields to return
• Options:

Name	Default	Credits Per Person	Description
basic	true	1	Return basic person fields to include name, locations, links and current employment.
premium	false	2	Return premium person fields such as job and education history.

Please refer to person object model for a list of basic vs premium fields.

Latest Only

• Key: latestOnly
• Data Type: boolean
• Description: When set to true, returns only the latest experience and education entries (one element each). When false, returns all experiences and educations.
• Default: false
• Example: true

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: 50

important

Pagination is limited to the first 1000 results for any given combination of filter keys.
If you require access beyond this range, please reach out to us.

Examples

Search by location and job title

{
  "filters": {
    "all": [
      { "key": "countryCode", "value": "US", "operator": "=" },
      { "key": "unitedStatesStateCode", "value": "CA", "operator": "=" }
    ],
    "any": [
      { "key": "titleAtCurrentCompany", "value": "CEO", "operator": "=" },
      { "key": "titleAtCurrentCompany", "value": "Founder", "operator": "=" }
    ]
  },
  "fieldsToReturn": "premium",
  "limit": 100
}

Find by person ID

{
  "filters": {
    "all": [
      { "key": "id", "value": "9e6a55b258ef11edb8780242ac120002", "operator": "=" }
    ]
  },
  "fieldsToReturn": "premium",
  "latestOnly": true
}

Find by LinkedIn URL

{
  "filters": {
    "all": [
      { "key": "linkedInUrl", "value": "https://linkedin.com/in/joedoe", "operator": "=" }
    ]
  },
  "fieldsToReturn": "premium",
  "latestOnly": false
}

Response

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

Example

{
  "data": {
    "results": [
      {
        "id": "e7c2a3f458ef11edb8780242ac120002",
        "name": "Joe Doe",
        "firstName": "Joe",
        "lastName": "Doe",
        "photoUrl": "https://d1hbpr09pwz0sk.cloudfront.net/logourl/06f524f",
        "birthYear": 1988,
        "angellistUrl": "https://angel.co/joedoe",
        "crunchbaseUrl": "https://www.crunchbase.com/person/joedoe",
        "facebookUrl": "https://facebook.com/joedoe",
        "githubUrl": "https://github.com/joedoe",
        "linkedInUrl": "https://linkedin.com/in/joedoe",
        "xUrl": "https://twitter.com/joedoe",
        "youtubeUrl": "https://youtube.com/user/joedoe",
        "unitedStatesStateCode": "CA",
        "unitedStatesCity": "Seattle",
        "unitedStatesZipCode": "98119",
        "unitedStatesRegion": "West Coast",
        "countryCode": "US",
        "worldRegion": "Americas",
        "experiences": [
          {
            "id": "a1b2c3d4e5f611edb8780242ac120003",
            "name": "Acme Inc.",
            "title": "Senior Software Engineer",
            "department": "Engineering",
            "team": "Backend",
            "role": "Individual Contributor",
            "seniority": "Manager",
            "startedAt": "2018-06-15",
            "endedAt": "2022-11-30"
          }
        ],
        "educations": [
          {
            "degree": "Bachelor of Science",
            "institutionDivision": "Engineering",
            "institutionDivisionDepartment": "Computer Science",
            "institutionLevel": "University",
            "institutionName": "University of Washington",
            "startYear": "2006",
            "endYear": "2010"
          }
        ]
      }
    ],
    "pagination": {
      "nextStart": [
        {
          "id": "9e6a55b258ef11edb8780242ac121233",
          "score": 0.92
        }
      ]
    }
  }
}

info

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