Sign in

v1

latestOpenAPI 3.1.02026-08-0666136.4 KB
Name Search

Search for a Person by Name

Supported Query Combinations

Queries must satisfy the following conditions:

  1. Provide at least one name:

    • first_name or
    • last_name

  2. Provide at least one of the following additional fields:

    • the other name (first_name or last_name, whichever wasn't used in the condition above)
    • middle_name
    • phone
    • email
    • street
    • city
    • state
    • relative_first_name
    • relative_last_name
    • age_min
    • age_max <br /><br />
Valid Examples
  • first_name + last_name
  • first_name + email
  • last_name + phone
  • first_name + state
  • first_name + city
  • first_name + relative_last_name
  • last_name + middle_name + state
  • first_name + city + distance
  • first_name + street + unit
  • first_name + age_min
  • last_name + age_max
  • first_name + age_min + age_max <br /><br />
Invalid Examples
  • first_name only
  • last_name only
get/names

Query parameters

first_namestring

The first name of the person you are searching for.

<span style="color: red;">Conditionally required.</span> Either provide both first_name and last_name, or provide this field with additional identifying fields.

middle_namestring

The middle name of the person you are searching for.

last_namestring

The last name of the person you are searching for.

<span style="color: red;">Conditionally required.</span> Either provide both first_name and last_name, or provide this field with additional identifying fields.

streetstring

A street address associated with the person you are searching for.

unitstring

A unit or suite number associated with the person you are searching for. <span style="color: red;">Must be paired with street</span>.

citystring

A city associated with the person you are searching for.

statestring

A state associated with the person you are searching for.

distancenumber

Restricts results to people associated with addresses located within the specified distance (in miles) of the city provided in the city parameter. The maximum accepted value is 999. <span style="color: red;">Must be paired with the city</span>.

emailstring

An email address associated with the person you are searching for.

phonestring

A 10-digit US phone number associated with the person you are searching for.

relative_first_namestring

The first name of a relative associated with the person you are searching for.

relative_last_namestring

The last name of a relative associated with the person you are searching for.

age_mininteger

The minimum age of the searched name.

age_maxinteger

The maximum age of the searched name.

start_indexstring

The starting index from which results should be fetched. This is a 1-based index. For example, if there are 10 total results and start_index is set to 3, results from the third item (index 3) through to the tenth item (index 10) will be returned.

end_indexstring

The ending index up to which results should be fetched. This is a 1-based index. For example, if there are 10 total results and end_index is set to 7, results from the first item (index 1) through to the seventh item (index 7) will be returned.

position_tokenstring

This method facilitates continuous data retrieval in a sequenced manner. If the response has position_token set, use the token obtained from the initial Name Search response as a parameter in the search URL to access the next set of results. Each response is limited to returning a maximum of 50 results.

include_possible_matchesboolean

This option includes similar results when exact matches are not found.

Response

OK - A successful Name Search returns an array of people.

position_tokenstring

A token indicating that there are additional results beyond those initially returned. Use the token obtained from the initial Name Search response as a parameter in the search URL to access the next set of results.

Example response

{
  "data": {
    "people": [
      {
        "names": [
          {
            "first_name": "John",
            "last_name": "Doe",
            "middle_name": "U",
            "full_name": "John U Doe Jr.",
            "suffix": "Jr.",
            "name_type": "main"
          }
        ],
        "age": 30,
        "dob_month": 12,
        "dob_year": 1990,
        "phones": [
          {
            "phone_is_new": true,
            "phone_is_new_rank_one": true
          }
        ],
        "emails": [
          {
            "email": "username@email.com",
            "email_is_new": true,
            "email_is_new_rank_one": true
          }
        ],
        "addresses": [
          {
            "city": "Anytown",
            "state": "CA",
            "street_address": "123 Main St",
            "latitude": 40.689247,
            "longitude": -74.0451471,
            "address_is_new": true,
            "address_is_new_rank_one": true
          }
        ],
        "relatives": [
          {
            "names": [
              {
                "first_name": "John",
                "last_name": "Doe",
                "full_name": "John Doe"
              }
            ]
          }
        ],
        "usernames": [
          "johndoe123"
        ],
        "work_history": [
          {
            "company_name": "Example Corp",
            "title": "Software Engineer",
            "location": "New York, NY"
          }
        ],
        "schools": [
          {
            "name": "Example University",
            "type": "Post-Secondary Institution",
            "location": "Boston, MA"
          }
        ],
        "phone_record_count": 5,
        "phone_record_delta_count": 1,
        "email_record_count": 5,
        "email_record_delta_count": 2,
        "address_count": 10,
        "relative_count": 10,
        "username_count": 10
      }
    ]
  },
  "metadata": {
    "total_people_count": 200
  },
  "position_token": "Mg=="
}