API Documentation
Get started with the Open People Search developer platform
Getting Started
Ready to get started? Once you have signed up and created an account, you can try out a quick search using our Data Viewer form to query the Open People Search RESTful API:
Basics
This documentation uses a couple notes and documentation conventions that will be explained in this section.
- Open People Search uses OAth 2.0 Bearer Token authentication to handle communication between your application and our API. OAth 2.0 Bearer Token is required in the header of each request.
- Authentication is always required. To simplify the examples, however, the documentation will frequently omit showing the token header.
- Your account credentials or authorization token should not, in any circumstances, be shared with anyone else. Should either one be compromised, you will need to immediately request new credentials and a new token, or cancel your account. You are responsible for any costs incurred while accessing the API with your credentials.
- Only secure HTTPS requests are supported.
Authentication
Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. The name “Bearer authentication” can be understood as “give access to the bearer of this token.” The bearer token is a cryptic string, generated by the server in response to a login request. The client must send this token in the Authorization header when making requests to protected resources:
Your token is good for 7 days from date of authentication and a new token will need to be generated after current one expires.
Please Note: username refers to the email address you use when creating an account.
Curl
curl -X POST "https://api.openpeoplesearch.com/api/v1/User/authenticate" -H "accept: */*" -H "Content-Type: application/json" -d "{\"username\":\"**********\",\"password\":\"**********\"}"
Request URL
https://api.openpeoplesearch.com/api/v1/User/authenticate
Server Response
{
"username": "**********",
"token": "**********************************************************",
"message": "OK",
"token_expiry_utc": "2021-03-31T23:12:25.225209Z"
}
Search Types
There are 8 search types that include searches by name, phone, address, po box, business, email, name and date of birth, or name and address. Each search cost is the same and all searches return the same result set.
Enter a first name (partial okay), middle name (optional, partial okay) and last name and optionally, city/state or state. TIP: This is the widest possible search for discovery of public records associated with any given name. Middle name or initial is allowable, but not required. Many public records do not include middle name information so use of this field will potentially filter valid results.
Input any 10 digit (or 11 digit when there is a leading "1") U.S. phone number (3105551234 or 13105551234). TIPS: Any non-numeric characters in a phone number (example: 310-555-1234) will be removed before processing. Most public records do not include a phone number so do not assume that all records found with a phone search represents all actual records for the owner of this phone number. One best practice is to run a phone number to discover name and address, then run a second search by name and address to discover additional records. Results include cell phone, landlines, VOIPs.
Enter street address, city and state. TIP: Although we provide an option to provide a Unit Number, keep in mind that public records may exist without the Unit Number so this could result in dropped results. The Unit Number parameter is best used for searching very large apartment or office buildings with a large number of records at the location.
Enter the P.O. Box number, city and state.
Enter a business name and (optionally) city/state or state.
Input email address. TIP: Most public records do not include an email address so do not assume that all records found with an email address search represents all actual records for the user of this email address.
Enter a first name (partial ok) and last name and full DOB (04/26/1980) or YOB (00/00/1980). TIPS: Use this search when searching for a person with a common name for a more targeted result set. Most public records do not include DOB information so relying solely on this option will miss records that do not have DOB information.
Enter a first name (optional) and last name, address, city and state. TIP: Use this search to verify a specific person is at a given address. Also use this search to append phone numbers or email addresses when the person's name and address is already known.
Rate Limits
To prevent abuse and ensure service stability, all API requests are rate limited. Rate limits specify the maximum number of API calls that can be made per minute. The exact number of calls that your application can make is 100 per minute. (Note: High volume users who need a higher rate limit can request it here. Please specify your anticipated rate limit.)
Request
All request are made via an HTTP POST request with header information that includes "accept: text/plain", "Authorization: Bearer ***", and "Content-Type: application/json".
Request Example
Curl
curl -X POST "https://api.openpeoplesearch.com/api/v1/Consumer/PhoneSearch" -H "accept: text/plain" -H "Authorization: Bearer ****************************************" -H "Content-Type: application/json" -d "{\"phoneNumber\":\"5551234567\"}"
Request URL
https://api.openpeoplesearch.com/api/v1/Consumer/PhoneSearch
Request Parameters
{
"phoneNumber":"5551234567"
}
Response
The response header result will contain api information as well as rate limits, search rate limit remaining, and rate reset date.
Response headers
access-control-allow-origin: *
api-supported-versions: 1.0
content-type: application/json; charset=utf-8
date: Mon,10 May 2021 23:19:09 GMT
server: Microsoft-IIS/10.0
x-powered-by: ASP.NET
x-rate-limit-limit: 1m
x-rate-limit-remaining: 99
x-rate-limit-reset: 2021-05-10T23:20:07.0409191Z
Response body
The response body will contain unique search Id, search type, search criteria, status code, status message, error message, record, search cost, search date, and results.
Result Definitions:
- Line Type: The phone line type based on the number's area code, prefix and thousand block at the time of its original assignment. Does not include ported number information. Possible line types are cell phone, landline, VOIP, toll-free and unknown.
- Date of Birth: Open People Search believes in and practices responsible use of public data. Access to full DOBs is only available upon request. By default a partial DOB in the configuration of MM/00/YYYY or 00/00/YYYY is returned. Please note that many public agencies only provide partial DOBs. We provide what is available, which might be full DOB (if authorized for your account), partial DOB or YOB only. In addition, please note the majority of public records have no DOB information at all.
- Associated Domain: If an email address is found from whois records, we provide the domain name of the website registered.
- Data Type Name: A description of the data type used in this record.
- Data Category Name: A general category of public data that the record came from.
- Web Verification Link: A public website where the record shown can be verified. This is shown on an "as available" basis and is usually but not always the website of the entity named in the agency name field.
- Agency Name: The specific agency that the record was sourced from.
- Vol: The vol value is an internal reference and not used for any API purpose.
- Record Id: The record Id is an internal Id and not used for any API purpose.
{
"searchId": "6e7fca8203044bedbaee22a3f8a763f6",
"searchType": "Phone",
"searchCriteria": [
{
"searchName": "PhoneNumber",
"searchValue": "5551234567"
}
],
"statusCode": "200",
"statusMessage": "OK",
"errorMessages": [],
"records": 1,
"searchCost": 0.05,
"searchDate": "2021-05-10T16:52:27.4559222-07:00",
"results": [
{
"reportedDate": "2014-05-01T00:00:00"
"firstName": "JOHN",
"middleName": "S",
"lastName": "SMITH",
"address": "123 ANYWHERE LANE",
"city": "LOS ANGELES",
"state": "CA",
"zip": "92010",
"email": "",
"phone": "5551234567",
"lineType": "Cell Phone",
"dob": "",
"occupation": "",
"employer": "",
"associatedDomain": "",
"dataTypeName": "Phone Listings",
"dataCategoryName": "Whitepages",
"webVerificationLink": "",
"agencyName": "",
"vol": "Vol1"
"recordId": "1234567890"
}
]
}
Status Codes
When making API requests, there are several different HTTP status codes you may receive. If the status code is 200, everything is great. All other status codes indicate an error in processing the request.
The request was successful.
Missing required fields.
Invalid credentials or expired token.
Insufficient Funds.
Unexpected error has occurred.
The server is offline and not available.
Support
Any questions about our API can be sent here.
