Search API Reference Overview
Welcome to the Pipl Search API Reference documentation. This section provides comprehensive documentation for the API, request parameters, response formats, and data fields.
The API Reference is organized into four main sections:
- Request - Learn how to construct search requests using parameters, Person objects, or search pointers
- Response - Understand response formats, error handling, and rate limiting
- Data Fields - Explore individual data fields returned by the API
- Data Field Containers - Learn about Person and Source container structures
Request​
Learn how to make search requests to the Pipl Search API. Understand search parameters, configuration options, match criteria, and different ways to structure your queries.
Request Overview
Learn about the API endpoint, request methods, and minimum search requirements. There are 3 ways to make a search: using search parameters, a Person object, or a search pointer.
Using Search Parameters
Construct searches using individual search parameters like name, email, phone, and more.
Full Person Object
Build complex searches using Person objects with multiple data fields.
Search Pointer
Use search pointers to expand a possible match and retrieve detailed information, or to requery a person of interest.
Match Criteria
Take advantage of Pipl's pay-per-match features and pay for only the data that you need.
Configuration Parameters
Customize API behavior with configuration parameters like minimum match, top match, and more.
Response​
Understand how the API responds to your requests, including response types, error handling, warnings, and rate limiting information.
Response Overview
Learn about response structure, fields, and how responses are formatted. Responses can be a Person (perfect match), Possible Persons (multiple matches), or No-Match (no data or match criteria used).
Response Types
Understand single person responses, possible persons arrays, no match, and when each is returned.
Errors
Learn about error codes, error messages, and how to handle API errors.
Warnings
Understand warning messages and how they can help improve your searches.
Rate Limiting
Learn about rate limits, how they're enforced, and best practices for managing them.
Available Data
Counts of data types available for a person, helping you assess what information Pipl has before retrieving full details.
The Source Layer
An in-depth guide to understanding how to work with the sources array and gain valuable data and insights from source attribution.
Data Fields​
Explore the individual data fields returned by the Pipl Search API. Each field contains specific information about a person.
First learn about the common attributes such as field metadata, timestamps, and inferred data indicators in the Data Fields Overview, before diving into each data field.
Name
Person names including first, middle, last, and display names. Current name as well as maiden name and nicknames.
Gender
Gender information (Male or Female) associated with the person.
Language
Languages spoken by the individual.
Origin Country
An individual's ancestral country.
Date of Birth
Birth dates with day, month, and year components. May be given as a range if exact date is unknown.
Address
Physical addresses including street, city, state, country, and postal codes. Home and work, current and past addresses.
Image
Profile images with URLs and thumbnail information. Image URLs of profile images and other images related to the person.
Username
Usernames in use online by the person. Includes screen names, handles, and nicknames from across the web, social media sites, forums, and more.
User ID
User identifiers from various online platforms.
URL
URLs of pages related to the person. Includes social profiles, professional licenses, publications, phone directories, court records, blogs, and much more.
Relationship
Friends, family, colleagues, social media followers, and other people associated with the person.
Phone
Phone numbers with country codes, line types, and display formats. Current and past, mobile and landline, home and office.
Email addresses with validation and type information. Personal and work emails.
Job
Employment information including title, organization, and industry. Current and past jobs with period, job title and organization.
Education
Educational background including degrees and institutions. Degrees from various schools with institution, degree, and period.
Vehicle
Vehicles owned by the individual. Vehicle registration information including make, model, and VIN.
Tag
Additional metadata tags associated with a person, including marriage records, divorce records, deceased information, property ownership, and more.
Date Range
Date ranges associated with various data fields when exact dates are not available.
Data Field Containers​
Understand the container structures that organize data fields in API responses. Containers provide context and grouping for related data.