Name Search

Download OpenAPI description

openapi.json

openapi.yaml

Overview

Email apisupport@spokeo.com

Servers

https://api.spokeo.com/v5/

Name Search

Endpoint name: https://api.spokeo.com/v5/names

Use Spokeo's Name Search tool to find person profiles, contact details, and related data based on a person's name.

Search by first and last name to identify individuals, verify information, or enrich person records with public contact and background information.

Overview

Use this endpoint when you have a person's first and last name (optional: middle name, city, or state) and want to locate profiles associated with that individual.

This endpoint returns person records that may include public contact information, addresses, relatives, and aliases, along with unique Spokeo IDs for further enrichment.

Name Search is commonly used for person verification, background research, lead qualification, contact enrichment, and fraud prevention workflows.

When to Use

Use Name Search when you:

Want to identify or verify a person's profile, age, or location
Need to enrich CRM or customer records with fresher contact and address data
Are performing person verification, fraud detection, or investigative workflows

Do not use this endpoint to search by phone number, email, username, or street address — use Phone Search, Email Search, Username Search, or Address Search instead.

Required Parameters

Provide at least one name and an additional identifying field.

first_name (string) - The person's first name. (Conditionally Required)
last_name (string) - The person's last name. (Conditionally Required)

Response Includes

A successful Name Search returns an array of person profiles and associated metadata. Each result may include:

Name - First, middle, and last name
Age - Current age or age at death
Addresses - Known or current addresses (with street, city, state, ZIP, latitude, and longitude)
Phones - Phone numbers associated with the individual
Emails - Email addresses
Relatives - Family members or household relationships
Aliases - Known alternative names or name variations
Deceased Status - Indicator if the individual is deceased
Metadata - Result count, match confidence, and pagination details
Person ID - A unique Spokeo identifier used for follow-up enrichment with Person ID Search
Social Profiles - Linked public social media accounts, profile photos, and URLs
Work History - Job titles, company names, start and end dates, and whether the person is currently employed
Education History - Schools attended, attendance dates, and degrees earned

Common Use Cases

People Lookup - Identify profiles that match a person's name.
Person Verification - Confirm that a name matches information submitted or already on file with contact data.
Lead Enrichment - Add phone, email, and address data to name-based CRM records.
Fraud and Risk Detection - Verify individuals before transactions.
Background and Due Diligence - Research individuals for compliance or investigation workflows.

Operations

Search for a Person by Name

Request

Supported Query Combinations

Queries must satisfy the following conditions:

Provide at least one name:
- first_name or
- last_name
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

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

Invalid Examples

first_name only
last_name only

Query

first_namestring

The first name of the person you are searching for.

Conditionally required. 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.

Conditionally required. 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. Must be paired with street.

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. Must be paired with the city.

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.

curl -i -X GET \
  https://api.spokeo.com/v5/names \
  -H 'X-api-key: YOUR_API_KEY_HERE'

Responses

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

Bodyapplication/json

dataobject

data.peopleArray of objects

data.people[].idstring

A unique Spokeo identifier associated with the person. Input this ID into Person ID Search to retrieve person data, including contact information.

Example: 1234567890

data.people[].namesArray of objects

Names associated with the person.

data.people[].agenumber

The person’s current age or age at death.

Example: 30

data.people[].dob_monthnumber

The person’s dob month as a number.

Example: 12

data.people[].dob_yearnumber

The person’s dob year as a number.

Example: 1990

data.people[].is_deceasedboolean

A value of "true" signifies that the person is deceased, while "false" signifies that the person is alive.

Example: false

data.people[].phonesArray of objects

Phone numbers associated with the person.

data.people[].emailsArray of objects

Email addresses associated with the person.

data.people[].addressesArray of objects

Addresses associated with the person.

data.people[].relativesArray of objects

Relatives associated with the person.

data.people[].usernamesArray of strings

Usernames associated with the person.

Example: ["johndoe123"]

data.people[].work_historyArray of objects

Work history associated with the person.

data.people[].schoolsArray of objects

Schools associated with the person.

data.people[].phone_record_countnumber

The total number of phone records associated with the person.

Example: 5

data.people[].phone_record_delta_countnumber

The total change in the number of phone records associated with the person.

Example: 1

data.people[].email_record_countnumber

The total number of email records associated with the person.

Example: 5

data.people[].email_record_delta_countnumber

The total change in the number of email records associated with the person.

Example: 2

data.people[].address_countnumber

The total number of addresses associated with the person.

Example: 10

data.people[].address_record_delta_countnumber

The total change in the number of address records associated with the person.

Example: 0

data.people[].relative_countnumber

The total number of relatives associated with the person.

Example: 10

data.people[].username_countnumber

The total number of usernames associated with the person.

Example: 10

metadataobject

metadata.total_people_countnumber

The total count in the array of people returned based on your search inputs.

Example: 200

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: "Mg=="

Response

application/json

{
  "data": {
    "people": [
      {
        "id": 1234567890,
        "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,
        "is_deceased": false,
        "phones": [
          {
            "phone": 5551234567,
            "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",
            "zip": 12345,
            "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,
        "address_record_delta_count": 0,
        "relative_count": 10,
        "username_count": 10
      }
    ]
  },
  "metadata": {
    "total_people_count": 200
  },
  "position_token": "Mg=="
}

Person ID Search

Endpoint name: https://api.spokeo.com/v5/person_id/{id}

Use Spokeo’s Person ID Search tool to retrieve a person profile using a unique Spokeo Person ID.

Search by Person ID to enrich existing records with contact details, social profiles, addresses, and background information.

Overview

Use this endpoint when you already have a valid Spokeo Person ID (from any other Spokeo search endpoint) and want to retrieve or enrich the profile for that individual.

This endpoint returns person data, including contact information, addresses, relatives, social profiles, and work history.

Person ID Search is commonly used for person record enrichment, CRM updates, compliance checks, person verification, and investigative workflows.

When to Use

Use Person ID Search when you:

Want to retrieve the person profile associated with that ID
Need to enrich CRM or contact records with name, phone, email, address, or social data
Are performing person resolution, risk analysis, or investigative enrichment workflows

Do not use this endpoint to search by name, phone number, email, username, or street address — use Name Search, Phone Search, Email Search, Username Search, or Address Search instead.

Required Parameter

id (string) – The unique Person ID used to retrieve the profile. (Required; no optional parameters)

Response Includes

A successful Person ID Search returns a person record and associated metadata. Each result may include:

Name – Full name (first, middle, last) and known aliases
Demographics – Gender, age, marital status, and deceased indicator (with death month/year, if applicable)
Addresses – Current and historical addresses (with city, state, ZIP, latitude, and longitude)
Phones – Phone numbers linked to the person
Emails – Email addresses linked to the person
Social Profiles – Linked public social media accounts (with platform name, URLs, and profile photos)
Relatives – Relatives or household members (each with their own Spokeo Person ID for enrichment)
Work History – Employment data including company names, job titles, and employment dates
Education History – Schools attended, degrees earned, majors, and attendance dates
Certifications – Professional licenses, credentials, or certifications with issuing organizations and dates
Metadata – Match status and enrichment source indicators

Common Use Cases

Person ID Lookup – Retrieve the profile associated with a known Person ID.
Contact Enrichment – Add public phone, email, address, and social data to existing records.
Person Verification – Learn more about the information associated with a previously found ID.
Risk and Compliance Analysis – Support KYC, fraud prevention, or investigative workflows with profile data.
CRM Record Enhancement – Use Person IDs as stable references to keep customer records updated.

Operations

Phone Search

Endpoint name: https://api.spokeo.com/v5/phones

Use Spokeo’s Phone Search tool to find people, contact information, and background details associated with a given phone number.

Search by phone number to identify or verify a person and enrich contact records.

Overview

Use this endpoint when you have a valid 10-digit U.S. phone number (mobile, landline, or VOIP) and want to identify or verify the person associated with it.

This endpoint returns person profiles, contact details, and phone intelligence data connected to that number.

Phone Search is commonly used for contact enrichment, lead verification, fraud prevention, customer identification, and risk assessment.

When to Use

Use Phone Search when you:

Want to identify or verify ownership of that number
Need to enrich CRM or contact records with fresher name, email, address, or social data
Are performing fraud detection, risk assessment, or lead qualification workflows

Required Parameter

phone (string) – The 10-digit U.S. phone number to search. (Required; no optional parameters)

Response Includes

A successful Phone Search returns an array of current and previous owners and associated metadata. Each result may include:

Name – First and last name
Age – Current age or age at death
Contact Information – Public phone numbers, email addresses, and current address (with city, state, ZIP, latitude, and longitude)
Social Profiles – Linked social media accounts, profile photos, and URLs
Work History – Job titles, company names, start and end dates, and whether the person is currently employed
Education History – Schools attended, attendance dates, and degrees earned
Phone Intelligence – Carrier name, line type (mobile, landline, VOIP), activity status, time zone, and spam risk level
Metadata – Match counts and enrichment details
Person ID – A unique identifier used for follow-up enrichment with Profile Search

Common Use Cases

Reverse Phone Lookup – Identify who owns or uses a given phone number.
Contact Verification – Confirm that a number corresponds to a person or business.
Fraud and Risk Prevention – Detect fake, disconnected, or high-risk phone numbers.
Lead Enrichment – Add fresher attributes (name, email, address, and social data) to CRM or customer records.
Customer Identification – Resolve phone numbers to person profiles for compliance and personalization.

Operations

Address Search

Endpoint name: https://api.spokeo.com/v5/addresses

Use Spokeo’s Address Search tool to find public property information, property owners, residents, and related person data connected to a given street address.

Search by address to identify property details, confirm ownership, or enrich person and property records with new insights.

Overview

Use this endpoint when you have a valid U.S. street address (street, city, and state; optional unit) and want to identify who lives there, who owns the property, or retrieve additional property data.

This endpoint returns a complete property and resident profile, including ownership details, property structure data, valuation insights, and nearby school information.

Address Search is commonly used for real estate research, fraud detection, lead qualification, due diligence, and person verification.

When to Use

Use Address Search when you:

Want to identify property owners or current residents
Need to verify address details, property characteristics, or estimated valuation
Are performing real estate analysis, risk assessment, or fraud detection workflows

Required Parameters

street (string) – Street and address (e.g., “123 Main St”). (Required)
city (string) – City name. (Required)
state (string) – U.S. state (can be abbreviated). (Required)

Response Includes

A successful Address Search returns property, owner, and resident information along with related metadata. Each result may include:

Address Information – Street address, city, ZIP code, county, state, latitude, and longitude
Property Details – Lot size, living area, bedrooms, bathrooms, year built, structure style, stories, and property use
Ownership Information – Current and historical owners (with names, IDs for enrichment via Person ID Search, ownership type, and start dates)
Residents – People currently or previously living at the property (with IDs for follow-up enrichment)
Valuations – Market value range, valuation confidence, and latest valuation date
Financial Insights – Loan-to-value ratio, total loans, ownership tenure, absentee ownership indicators
Nearby Schools – Local school names, ratings, and district details
Metadata – Position token and pagination details for multi-unit or multi-property addresses

Common Use Cases

Reverse Address Lookup – Identify who owns or resides at a given property
Property Verification – Confirm that an address corresponds to a real property and verify its ownership details
Lead Qualification and Enrichment – Add property and owner attributes to CRM or customer records
Risk and Fraud Investigation – Verify address legitimacy and detect potential absentee or high-risk ownerships
Real Estate and Market Research – Retrieve property characteristics, valuation trends, and local school data

Operations

Email Search

Endpoint name: https://api.spokeo.com/v5/emails

Use Spokeo’s Email Search tool to find people, contact information, social profiles, and background details associated with that email.

Search by email address to identify or verify a person and enrich contact records.

Overview

Use this endpoint when you have a valid email address (contains “@” and a suffix) and want to identify or verify the person associated with it.

This endpoint returns person profiles, contact information, and social media accounts connected to that address.

Email Search is commonly used for contact enrichment, sales lead generation, candidate outreach, person verification, fraud prevention, and digital footprint resolution.

When to Use

Use Email Search when you:

Want to identify or verify ownership of that email
Need to enrich CRM or contact records with fresher name, phone, address, or social data
Are performing fraud detection, risk assessment, or candidate verification workflows

Do not use this endpoint to search by phone number, name, username handle, or street address — use Phone Search, Name Search, Username Search, or Address Search instead.

Required Parameter

email (string) – The email address to search. (Required; no optional parameters)

Response Includes

A successful Email Search returns an array of associated people and metadata. Each result may include:

Name – First and last name
Age – Current age or age at death
Contact Information – Phone numbers, secondary emails, and current address (with city, state, ZIP, latitude, and longitude)
Social Profiles – Linked social media accounts, profile photos, and URLs
Work History – Job titles, company names, start and end dates, and whether the person is currently employed
Education History – Schools attended, attendance dates, and degrees earned
Metadata – Match counts
Person ID – A unique identifier used for follow-up enrichment with Person ID Search

Common Use Cases

Reverse Email Lookup – Identify who owns or uses a given email address.
Contact Enrichment – Add attributes (name, phone, address) to existing records.
Fraud and Risk Prevention – Confirm that an email corresponds to a known name.
Marketing Personalization – Connect emails to social and demographic insights.

Operations

Username Search

Endpoint name: https://api.spokeo.com/v5/usernames

Use Spokeo’s Username Search tool to find people, contact information, and social profiles associated with a specific online handle or username.

Search by username or handle to identify who might be behind an online alias, verify authenticity, or enrich existing records.

Overview

Use this endpoint when you have a username or handle (for example, rainfire1967 or @rainfire1967) and want to identify or verify the person associated with it.

This endpoint returns person profiles, contact information, and social accounts connected to that username.

Username Search is commonly used for investigations, fraud prevention, and digital footprint enrichment.

When to Use

Use Username Search when you:

Want to identify or verify the person behind that handle or online account
Need to enrich records with name, phone, email, or address data connected to the username
Are performing fraud detection, social media investigations, or influencer verification

Do not use this endpoint to search by name, phone number, email address, or street address — use Name Search, Phone Search, Email Search, or Address Search instead.

Required Parameter

username (string) – The username or handle to search. (Required; no optional parameters)

Response Includes

A successful Username Search returns social profiles associated with that username or handle.

Common Use Cases

Reverse Username Lookup – Identify who owns or uses a given handle or alias
Social Media Verification – Confirm that a social media account corresponds to a real person
Fraud and Risk Investigation – Detect fake or duplicate accounts across platforms
Influencer and Brand Safety Checks – Verify authenticity of potential partners or creators

Operations