Description

Overview

The Person Search API provides a dynamic and flexible tool for locating individuals by processing search queries using a multitude of parameters. This API is designed to cater to various search requirements, whether you’re conducting a broad sweep or a targeted hunt for specific individuals. By allowing a combination of different search filters, users can pinpoint the data they need efficiently and effectively.

When initiating a person search, the specificity of provided information directly influences the refinement of the search results. For instance, a query based on a First and Last Name combination may yield thousands of results due to the commonality of certain names. However, adding more parameters like City and State or a complete address narrows down the outcomes, providing a more concentrated set of data.

This API is versatile, allowing searches through combinations such as:

• First Name, Last Name, and Full Address
• First Name, Last Name, City, and State
• First Name, Last Name, and Date of Birth

Additionally, specific attributes can be queried to find individuals associated with particular details like:

• Phone Number
• Email Address
• Physical Address

This targeted approach is vital for various use cases, from background checks to people finding, offering both breadth and depth in search capabilities. The Person Search API is a critical tool for any organization or service that requires quick and precise access to individual personal data.

Pro Tip:

To achieve the most accurate results, it’s recommended to provide as much information as possible. The depth of detail can significantly enhance the search precision, making the Person Search API a powerful asset for any data-driven operation.

---

Request

Structure of a Request

When crafting a request to the Person Search API, you must include specific parameters that the API can recognize and process. The request is structured as a JSON object with key-value pairs that correspond to the search criteria. Below is the description of each field that can be included in the request body.

Input Parameters

• PersIds: An array of unique person identifiers (PersID), if known. This returns records for the specified IDs. (optional, string[])
• FirstName: The first name of the individual. (optional, string)
• MiddleName: The middle name or initial of the individual. (optional, string)
• LastName: The last name of the individual. (optional, string)
• Dob: The date of birth in the format mm/dd/yyyy. (optional, string)
• Age: The current age of the individual. (optional, int)
• AgeRangeMinAge: The minimum age in an age range for searching. (optional, int)
• AgeRangeMaxAge: The maximum age in an age range for searching. (optional, int)
• AgeRange: The age range, specified in the format ##-##. (optional, string)
• Ssn: The Social Security Number formatted as ###-##-####. (optional, string)
• Email: The email address of the individual. (optional, string)
• Phone: The phone number (formats: ###-###-####, (###)###-####). (optional, string)
• Addresses: An array of address objects where each address object can include:
  • AddressLine1: House number and street name or PO Box. (optional, string)
  • AddressLine2: State or City and State or Zip. (optional, string)
  • County: County of residence. (optional, string)
• Relatives: An array of names of relatives which may help in narrowing down the search. (optional, string[])

Mandatory Parameters

To utilize the Person Search API effectively, each request must include at least one of the following fields to ensure valid search criteria are provided:

• PersIds: An array of unique person identifiers (PersID).
• LastName: The last name of the individual.
• Ssn: The Social Security Number formatted as ###-##-####.
• Phone: The phone number (formats: ###-###-####, (###)###-####).
• Email: The email address of the individual.
• Addresses: An array of address objects, each containing AddressLine2 which includes the state or city and state or zip.

Example JSON Request Bodies

Search by Name and Address

{
  "FirstName": "John",
  "LastName": "Smith",
  "Addresses": [
    {
      "AddressLine2": "Sacramento, CA"
    }
  ]
}

Search by PersIds

{
  "PersIds": [
    "G-1662270887725024773"
  ]
}

Usage Notes

• All fields are optional and can be omitted if the information is not available or relevant to the search.
• Including more parameters will refine the search results and return a more specific dataset.
• The fields can be mixed and matched to suit the requirements of the search being conducted.
• The request body must be valid JSON, and care should be taken to ensure the correct data types are used as specified for each field.

---

Response

Overview

The Person Search API response is a comprehensive JSON object containing detailed information about individuals matching the search criteria. It provides structured data on personal details, locations, contact information, and other pertinent attributes. Below is a guide to understanding the structure and content of the API response.

Response structure

Top-level Elements:

• persons: An array of person objects, each representing an individual found in the search.
• counts: An object summarizing the counts of various elements found in the search results.
• smartSearchStatistics: Contains metrics and statistics related to the search execution.
• totalRequestExecutionTimeMs: The total time taken by the API to execute the request in milliseconds.
• requestGuid: A unique identifier for the search request.
• isError: A boolean indicating if there was an error in the request.
• error: Contains error details, if any, including input errors and warnings.

Persons Array

Each object within the persons array contains:

• persId: A unique identifier for the person within the system.
• name: An object with the person’s name information, including raw names and dates first seen.
• isPublic: A boolean indicating if the person’s information is public.
• isOptedOut: A boolean indicating if the person has opted out of sharing their information.
• sparseFlag: An indicator of the data completeness.
• isPremium: A boolean indicating if the record is from a premium data source.
• dob: Date of birth of the person (if available).
• age: The current calculated age of the person.
• akas: An array of alternate names or aliases associated with the person.
• locations: An array of city and state objects representing known locations for the person.
• addresses: Detailed information about each address associated with the person.
• phoneNumbers: An array of phone number objects with details on each number.
• emailAddresses: An array of email addresses associated with the person.
• fullName: The full name of the individual.
• indicators: An object containing boolean indicators for various records associated with the person.
• driversLicenseDetail: An array containing driver’s license details if available.
• hasAdditionalData: A boolean indicating if there is additional data available for the person.
• propensityToPayScore: An object with details related to the person’s propensity to pay score.

Counts Object

The counts object provides a summary of the elements found in the search results, such as:

• searchResults: The number of results returned.
• searchResultsOverflow: A boolean indicating if the results exceeded the maximum count limit.
• names: The count of different names found.
• And counts for other specific records like addresses, phoneNumbers, emailAddresses, etc.

Usage Notes

• Ensure your application logic can handle and parse each element of the response correctly.
• When handling large volumes of data, pay attention to pagination to fetch subsequent pages of results if needed.
• Check the isError flag and the error object for handling exceptions and errors gracefully.
• Use the counts object to provide a summary or validate the completeness of the search results.

---

Sample Response

{
    "persons": [
        {
            "persID": "P19876543210987654321",
            "name": {
                "prefix": "Mr.",
                "firstName": "Alexander",
                "middleName": "B",
                "lastName": "Smithson",
                "suffix": "III",
                "rawNames": [
                    "ALEXANDER B SMITHSON III",
                    "ALEX SMITHSON"
                ],
                "publicFirstSeenDate": "2/2/1990",
                "totalFirstSeenDate": "2/2/1990",
                "sourceSummary": null
            },
            "isPublic": true,
            "isOptedOut": false,
            "sparseFlag": 0,
            "isPremium": true,
            "dob": "02/03/1965",
            "age": 58,
            "dobFirstSeen": "6/15/1995",
            "dobLastSeen": "10/20/2023",
            "akas": [
                {
                    "prefix": "Mr.",
                    "firstName": "Alex",
                    "middleName": "Bernard",
                    "lastName": "Smithson",
                    "suffix": "",
                    "rawNames": [
                        "ALEX BERNARD SMITHSON"
                    ],
                    "publicFirstSeenDate": "3/3/1992",
                    "totalFirstSeenDate": "3/3/1992",
                    "sourceSummary": null
                }
            ],
            "locations": [
                {
                    "city": "Springfield",
                    "state": "IL"
                },
                {
                    "city": "Centerville",
                    "state": "IL"
                }
            ],
            "addresses": [
                {
                    "isDeliverable": true,
                    "isMergedAddress": false,
                    "isPublic": true,
                    "addressQualityCodes": [],
                    "addressHash": "1234567890abcdef1234567890abcdef",
                    "houseNumber": "1010",
                    "streetPreDirection": "N",
                    "streetName": "Maple",
                    "streetPostDirection": "",
                    "streetType": "St",
                    "unit": "Apt 5",
                    "unitType": "Apt",
                    "city": "Springfield",
                    "state": "IL",
                    "county": "Sangamon",
                    "zip": "62704",
                    "zip4": "1234",
                    "latitude": "39.781721",
                    "longitude": "-89.650148",
                    "addressOrder": 1,
                    "highRiskMarker": {
                        "isHighRisk": false,
                        "sic": "",
                        "addressType": ""
                    },
                    "propertyIndicator": "Single Family",
                    "bldgCode": "",
                    "utilityCode": "",
                    "unitCount": 1,
                    "firstReportedDate": "5/5/2005",
                    "lastReportedDate": "12/12/2022",
                    "publicFirstSeenDate": "5/5/2005",
                    "totalFirstSeenDate": "5/5/2005",
                    "phoneNumbers": [],
                    "neighbors": [],
                    "neighborSummaryRecords": [],
                    "fullAddress": "1010 N Maple St Apt 5; Springfield, IL 62704-1234",
                    "sourceSummary": null
                }
            ],
            "phoneNumbers": [
                {
                    "phoneNumber": "(217) 555-0199",
                    "company": "Springfield Telecom Co.",
                    "location": "SPRINGFIELD, IL",
                    "phoneType": "LandLine",
                    "isConnected": true,
                    "isPublic": true,
                    "latitude": "39.781721",
                    "longitude": "-89.650148",
                    "phoneOrder": 1,
                    "firstReportedDate": "6/6/2006",
                    "lastReportedDate": "1/1/2023",
                    "publicFirstSeenDate": "6/6/2006",
                    "totalFirstSeenDate": "6/6/2006",
                    "sourceSummary": null
                }
            ],
            "emailAddresses": [
                {
                    "emailAddress": "alexsmithson@example.com",
                    "emailOrdinal": 1,
                    "isPremium": false,
                    "nonBusiness": 1,
                    "sourceSummary": null
                }
            ],
            "fullName": "Alexander B Smithson III",
            "indicators": {
                "hasBankruptcyRecords": 0,
                "hasBusinessRecords": 0,
                "hasDivorceRecords": 0,
                "hasDomainsRecords": 0,
                "hasEvictionsRecords": 0,
                "hasFeinRecords": 0,
                "hasForeclosuresRecords": 0,
                "hasForeclosuresV2Records": 0,
                "hasJudgmentRecords": 0,
                "hasLienRecords": 0,
                "hasMarriageRecords": 0,
                "hasProfessionalLicenseRecords": 0,
                "hasPropertyRecords": 1,
                "hasVehicleRegistrationsRecords": 1,
                "hasWorkplaceRecords": 0,
                "hasDeaRecords": 0,
                "hasPropertyV2Records": 0,
                "hasUccRecords": 0,
                "hasUnbankedData": 0,
                "hasMobilePhones": 1,
                "hasLandLines": 1,
                "hasEmails": 1,
                "hasAddresses": 1,
                "hasCurrentAddresses": 1,
                "hasHistoricalAddresses": 0,
                "hasDebtRecords": 0
            },
            "driversLicenseDetail": [],
            "hasAdditionalData": false,
            "propensityToPayScore": {
                "transactionId": "trans-1234567890",
                "suffix": "III",
                "firstName": "Alexander",
                "middleName": "B",
                "lastName": "Smithson",
                "address": "1010 N Maple St Apt 5",
                "city": "Springfield",
                "state": "IL",
                "zip": "62704",
                "zip4": "1234",
                "measures": []
            }
        }
    ],
    "error": {
        "message": null
    },
    "counts": {
        "searchResults": 1,
        "searchResultsOverflow": false,
        "names": 9,
        "socialSecurityNumbers": 0,
        "datesOfBirth": 1,
        "datesOfDeath": 0,
        "deathRecords": 0,
        "addresses": 3,
        "phoneNumbers": 1,
        "emailAddresses": 1,
        "relatives": 0,
        "associates": 0,
        "businessRecords": 0,
        "debtRecords": 0,
        "evictionRecords": 0,
        "foreclosureRecords": 0,
        "foreclosureV2Records": 0,
        "professionalLicenseRecords": 0,
        "expectedCount": 3
    },
    "smartSearchStatistics": {
        "userInput": null,
        "criteriaGroupId": null,
        "isSuccessful": true,
        "successfulPattern": null,
        "totalTimeInMS": 250,
        "resultCount": 1,
        "patterns": [],
        "searches": []
    },
    "totalRequestExecutionTimeMs": 124,
    "isError": false,
    "requestGuid": "c422a845-2a6a-4971-9d39-0a5f2030f145"
}