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
• HTTP Method: POST

Request

Parameters

Utilize the following parameters to refine your search and retrieve tailored person information

Expression

• Key: expression
• Data Type: object
• Description: Enables advanced filtering by specifying conditions that must be met. Use the all field to list conditions that must all be satisfied (with optional exclusions) and the any field to list conditions where at least one must be met.
• Structure:
  • all: An array of conditions that must all be satisfied. Conditions can also include an exclude flag.
  • any: An array of conditions where at least one must be satisfied.
• Example:

{
  "all": [
    {
      "categoryKey": "countryCode",
      "name": "US"
    },
    {
      "categoryKey": "unitedStatesStateCode",
      "name": "CA",
      "exclude": true
    }
  ],
  "any": [
    {"categoryKey": "seniority", "name": "C-Level+"},
    {"categoryKey": "seniority", "name": "Vice President"}
  ]
}

Limit

• Key: limit
• Data Type: number
• Description: Specifies the maximum number of results to return. The default value is 10, with a maximum allowed value of 1000.
• Example: 100

Fields To Return

• Key: fieldsToReturn
• Data Type: string
• Description: Specifies which fields should be returned in the response.
• Options:

Name	Default	Credits	Description
idOnly	false	0	Return only person IDs.
email	false	1	Return only the person's email.
phone	false	5	Return only the person's phone number.
basic	true	1	Return basic person fields (e.g., name, locations, and links) without email or phone.
basicWithEmail	false	2	Return basic person fields with email but without phone.
basicWithPhone	false	6	Return basic person fields with phone but without email.
basicWithEmailAndPhone	false	7	Return basic person fields with both email and phone.
premium	false	2	Return premium person fields (e.g., experiences, educations) without email or phone.
premiumWithEmail	false	3	Return premium person fields with email but without phone.
premiumWithPhone	false	7	Return premium person fields with phone but without email.
premiumWithEmailAndPhone	false	8	Return premium person fields with both email and phone.

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

Example

{
  "expression": {
    "all": [
      {
        "categoryKey": "countryCode",
        "name": "US"
      },
      {
        "categoryKey": "unitedStatesStateCode",
        "name": "CA",
        "exclude": true
      }
    ],
    "any": [
      {"categoryKey": "seniority", "name": "C-Level+"},
      {"categoryKey": "seniority", "name": "Vice President"}
    ]
  },
  "limit": 100,
  "fieldsToReturn": "idOnly"
}

Response

The response returns an array of person object models, 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,
        "emails": [
          {
            "email": "[email protected]",
            "type": "professional",
            "lastValidatedAt": "2020-08-12T02:12:33.231Z",
            "scoreValue": 0.95
          }
        ],
        "phones": [
          {
            "phone": "+1234567890",
            "type": "mobile",
            "lastValidatedAt": "2020-08-12T02:12:33.231Z",
            "scoreValue": 0.90
          }
        ],
        "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.",
            "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
        }
      ]
    }
  }
}