API Documentation
Welcome to our API. This guide will help you integrate our data services into your applications.
Getting Started
Before you begin, please review these key requirements for using the API.
- API Access: API usage is available for users with a total deposit of $50 or more. You can check your eligibility on the Billing page .
- API Key:
All requests must include your personal
api_key. You can find this in your Account Settings . - API Endpoint: The base URL for all requests is: https://uidfinder.com/v1/
- Request
Method: The API accepts both
GETandPOSTrequests for all actions. - Encoding: All request parameters sent to the server must be URL-encoded.
- History: Data rows purchased via the API are saved to your account history, just like web purchases. You can view them in your History page .
- Limits: API requests are subject to rate limits (per minute, hour, and day).
Core Concepts
Data Types: People vs. RawData
Our service provides data in two distinct formats. Understanding this is essential for choosing the correct API action.
RawData
This mode returns all individual rows from all our sources where your search query matched. A single search can return many rows from different databases.
People
This is a separate, curated database. Data from various sources is collected, analyzed, and grouped by a specific person. This provides a comprehensive profile based on unique combinations.
How Billing Works
We believe in transparent and safe pricing. Here’s exactly when and how you are charged.
buy_rawdata
or
buy_people
) where data is found. All search actions (
search_...
), requests with errors, or searches that find no data are
completely free.
- Chargeable
Actions: Payment is only processed for
action=buy_rawdataandaction=buy_people. - Price:
Charges are based on your
current_price. You can check this on the Billing page or via theaccount_infoAPI request. -
rawdataCharge: You pay one fee for the entire result object (which can contain up to 100 data rows). -
peopleCharge: You pay one fee for each person (i.e., each object) you buy.
Search vs. Buy Responses
The API allows you to preview data before buying.
- Search
Actions (
search_rawdata,search_people,search_filter) return the complete data structure and all available fields. However, the actual data values are hidden (masked with '*'). This lets you see what we found before you decide to buy. - Buy
Actions (
buy_rawdata,buy_people) return the exact same structure and fields, but with all data values visible.
Important: How to Buy Data
The process for buying is different for `people` and `rawdata` .
To Buy `people` Data (Two-Step Process):
- Search first: You must first use
action=search_peopleoraction=search_filter. - Get IDs: From the search results, find the
db_nameandcodefor the specific person you want to purchase. - Buy: Use
action=buy_peopleand provide those exactdb_nameandcodevalues.
To Buy `rawdata` (One-Step Process):
You can buy
rawdata
directly without searching first. Simply use
action=buy_rawdata
and provide a
type
and
value
. You will only be charged if data is found.
API Actions & Parameters
All requests must contain an
action
parameter, which determines what you want to do.
action=account_infoNo additional parameters needed. Returns your
balance,current_price, and crypto deposit wallets (btc_wallet,ltc_wallet,usdt_wallet).action=check_paymentNo additional parameters needed. Use this to manually check for a recent crypto deposit if it hasn't been credited automatically.
action=search_rawdataSearches for `rawdata` matches. Returns one object containing all matches.
- Required Parameters:
type,value - Available types
:phone,email,username,full_name,vin,ssn
- Required Parameters:
action=search_peopleSearches the `people` database. Returns objects grouped by person.
- Required Parameters:
type,value - Available types
:phone,email,full_name,address,username,last_name,zip,vin,ssn
- Required Parameters:
action=search_filterSearches the `people` database using filters. Returns objects grouped by person.
- Required Parameter:
country: US, GB, DE, RU, IT, ES, BR, PT, FR
- Optional Parameters:
related:paypal,amazon,facebook,twitter,travel,crypto,datingdob_start: Year (e.g.,1980). Min 1920, Max 2010.dob_end: Year (e.g.,1990). Min 1920, Max 2010.gender:M(Male) orF(Female).
- Required Parameter:
action=buy_rawdataPurchases `rawdata` matches. Charges 1x
current_pricefor the entire result object.- Required Parameters:
type,value - (See Data Type Formatting section below for
typeandvaluerules). - Returns: Full data,
current_price(amount charged), anduser_balance(remaining).
- Required Parameters:
action=buy_peoplePurchases a specific person from the `people` database. Charges 1x
current_priceper person.- Required Parameters:
db_name,code - (You get these values from a
search_peopleorsearch_filterrequest). db_nameformat:[country_code]_data(e.g.,us_data,gb_data,fr_data, etc.)code: The unique ID number for the person.- Returns: Full data,
current_price(amount charged), anduser_balance(remaining).
- Required Parameters:
Data Type Formatting
When using
type
and
value
parameters, your
value
must match the expected format.
Parameter (type)
|
Value Format | Example (value)
|
Notes |
|---|---|---|---|
phone |
Digits only, E164 format without '+' | 12013427656 |
|
email |
Full email address | alex543@miller.com |
|
username |
Alphanumeric, no spaces | alex654 |
|
full_name |
First and Last Name (Latin, Cyrillic, European) | Donald Trump or Екатерина Мизулина |
|
last_name |
Last Name only (Latin, Cyrillic, European) | Miller or Дронов |
|
address |
Street and ZIP code | 54 Elm St 34532 |
US Only |
zip |
5-digit ZIP code (max 5 digits) | 00243 or 32954 |
US Only |
vin |
17 characters | 4M2CN8H72AKJ00549 |
US Only |
ssn |
9 digits, no dashes | 435655643 |
US Only |
Examples (Requests & Responses)
Here are practical examples. Replace
ZX2IZ7YNTNWY6FD9
with your own
api_key
.
This request retrieves your current account status, including balance, price per query, and your personal crypto deposit wallets.
https://uidfinder.com/v1/?api_key=ZX2IZ7YNTNWY6FD9&action=account_info
curl "https://uidfinder.com/v1/?api_key=ZX2IZ7YNTNWY6FD9&action=account_info"
As POST:
curl -X POST "https://uidfinder.com/v1/" \
-d "api_key=ZX2IZ7YNTNWY6FD9" \
-d "action=account_info"
{
"event_result": "account_info",
"username": "alex123",
"user_balance": "38.10",
"current_price": "0.40",
"wallet_btc": "bc1q0fdsur6m00jmjq4v4w6zv7r54w8pedh9acw394",
"wallet_ltc": "ltc1qq7rvszsn6wsuqzcjz7ghm0erwzr92f9mtlls6j",
"wallet_usdt": "TQpHcJHLAgJCFP79warxaduLfY6BYesfek"
}
Use this to manually check for a recent crypto deposit if it hasn't been credited automatically.
https://uidfinder.com/v1/?api_key=ZX2IZ7YNTNWY6FD9&action=check_payment
curl "https://uidfinder.com/v1/?api_key=ZX2IZ7YNTNWY6FD9&action=check_payment"
As POST:
curl -X POST "https://uidfinder.com/v1/" \
-d "api_key=ZX2IZ7YNTNWY6FD9" \
-d "action=check_payment"
{
"event_result": "no_new_deposits_found",
"user_balance": "38.10",
"deposits_sum": "321.40",
"current_price": "0.40"
}
This is a free search. It searches the rawdata
database for a
phone
. Note that the data values in the response are masked with
'
*
'.
https://uidfinder.com/v1/?api_key=ZX2IZ7YNTNWY6FD9&action=search_rawdata&type=phone&value=13362759580
curl "https://uidfinder.com/v1/?api_key=ZX2IZ7YNTNWY6FD9&action=search_rawdata&type=phone&value=13362759580"
As POST:
curl -X POST "https://uidfinder.com/v1/" \
-d "api_key=ZX2IZ7YNTNWY6FD9" \
-d "action=search_rawdata" \
-d "type=phone" \
-d "value=13362759580"
[
{
"search_object": "13362759580",
"search_type": "phone",
"data_mode": "rawdata",
"code": 0,
"row_count": 3,
"name_count": 3,
"email_count": 0,
"address_count": 2,
"phone_count": 1,
"results": [
{
"db_name": "luxottica_2021",
"code": "83191870",
"data": {
"full_name": "******* ***",
"phone": "***********",
"address": "**, ****** *****, *****, **** ********** **",
"country": "**"
}
},
{
"db_name": "npd_2024",
"code": "929840271",
"data": {
"full_name": "******* * ****",
"dob": "****-**-**",
"phone": "***********",
"address": "**, *** ***, *****, **** * ****** ***",
"county": "******",
"ssn9": "*********"
}
},
{
"db_name": "npd_2024",
"code": "946255671",
"data": {
"full_name": "***** * ****",
"dob": "****-**-**",
"phone": "***********",
"address": "**, *** ***, *****, **** * ****** ***",
"county": "******",
"ssn9": "*********"
}
}
],
"mode": 0.4
}
]
This is a free search. It searches the people
database for an
email
. Take note of the
db_name
(
us_data
) and
code
(
168696129
) in the response. You will need these to buy this person's
record.
https://uidfinder.com/v1/?api_key=ZX2IZ7YNTNWY6FD9&action=search_people&type=email&value=jenneee@comcast.net
curl "https://uidfinder.com/v1/?api_key=ZX2IZ7YNTNWY6FD9&action=search_people&type=email&value=jenneee@comcast.net"
As POST:
curl -X POST "https://uidfinder.com/v1/" \
-d "api_key=ZX2IZ7YNTNWY6FD9" \
-d "action=search_people" \
-d "type=email" \
-d "value=jenneee@comcast.net"
[
{
"db_name": "us_data",
"code": 168696129,
"first_name": "Jennifer",
"middle_name": "S",
"last_name": "Wails",
"marital": "******",
"gender": "F",
"dob_year": "1972",
"dob_month": "*",
"dob_day": "*",
"credit_capacity": "$*****",
"home_purchase_date": "****-**",
"vehicle_owned": "*",
"animals_pets": "*",
"family_religion_politics": "*,*,*,*",
"donor": "*,**",
"political_affiliation_donor": "*,*",
"credit_card_mail_order_buyers": "*,*,*,*,*,*,*,*",
"investing_finance": "*,*",
"hobby_interest": "*",
"cooking_food": "*,*",
"arts_history_science": "*",
"movie_music": "*,*,*",
"health_and_fitness": "*",
"collectibles_and_antiques": "*,*",
"outdoor_enthusiast": "*",
"last_name_rate": "**",
"full_name_rate": "*",
"income": "$100,000 to $149,999",
"networth": "$***,*** ** $***,***",
"address1": "**, **************, *****-****, *** ********* ***** ****|***_**** (***_****, **_********_****, ******_****, *********_***_****)",
"address1_location": "(**.******* -**.******)",
"address1_length_of_residence": "* ** * *****",
"address2": "**, **************, *****-****, **** ********** **|***_****, **_********_****, ******_**** (*********_****, *********_***_****)",
"address2_location": "(**.******* -**.******)",
"phone1": "* (***) ***-****, **|***_****, **_********_****, ******_**** (*********_****, ***_****, ***_****)",
"email1": "*******@comcast.net|***********",
"ssn9": "2**-**-****",
"ssn_issued_state": "**",
"ssn_alt_dob": "****-**-**"
}
]
This is a free search. It searches the people
database for German (
DE
) males (
M
) born
1970
-
1980
related to
dating
.
https://uidfinder.com/v1/?api_key=ZX2IZ7YNTNWY6FD9&action=search_filter&country=DE&related=dating&dob_start=1970&dob_end=1980&gender=M
curl "https://uidfinder.com/v1/?api_key=ZX2IZ7YNTNWY6FD9&action=search_filter&country=DE&related=dating&dob_start=1970&dob_end=1980&gender=M"
As POST:
curl -X POST "https://uidfinder.com/v1/" \
-d "api_key=ZX2IZ7YNTNWY6FD9" \
-d "action=search_filter" \
-d "country=DE" \
-d "related=dating" \
-d "dob_start=1970" \
-d "dob_end=1980" \
-d "gender=M"
[
{
"db_name": "de_data",
"code": 106108,
"first_name": "Seriba",
"middle_name": "",
"last_name": "Sidibe",
"gender": "M",
"dob_year": "1984",
"dob_month": "*",
"dob_day": "*",
"phone1": "** *** *** ****|******_****",
"email1": "********@yahoo.fr|************************",
"password1": "*******|*****_****"
},
{
"db_name": "de_data",
"code": 122134,
"first_name": "Volker",
"middle_name": "",
"last_name": "Knappkotter",
"gender": "M",
"dob_year": "1962",
"dob_month": "*",
"dob_day": "**",
"mode": 0.4,
"address1": "*****, *********, ******** **|******_****",
"phone1": "** *** *** ****|******_****",
"email1": "********@googlemail.com|**************************************",
"twitter_id": "**********",
"password1": "*********|*****_****"
},
{
"db_name": "de_data",
"code": 162505,
"first_name": "Axel",
"middle_name": "",
"last_name": "Kippenberg",
"gender": "M",
"dob_year": "1974",
"dob_month": "*",
"dob_day": "*",
"mode": 0.4,
"phone1": "** *** *** ****|******_****",
"email1": "*****@gmx.de|**************************************",
"username1": "*******|*****_****",
"password1": "*********|*****_****"
}
]
This is a paid action. It buys the rawdata
object for the
full_name
=
Claudio Bellino
. The response contains the *unmasked* data and your new
user_balance
.
Note: In the GET request, the space in
Claudio Bellino
is URL-encoded to
Claudio%20Bellino
.
https://uidfinder.com/v1/?api_key=ZX2IZ7YNTNWY6FD9&action=buy_rawdata&type=full_name&value=Claudio%20Bellino
curl "https://uidfinder.com/v1/?api_key=ZX2IZ7YNTNWY6FD9&action=buy_rawdata&type=full_name&value=Claudio%20Bellino"
As POST:
curl -X POST "https://uidfinder.com/v1/" \
-d "api_key=ZX2IZ7YNTNWY6FD9" \
-d "action=buy_rawdata" \
-d "type=full_name" \
-d "value=Claudio Bellino"
When using POST, curl automatically
handles the URL-encoding for the value.
[
{
"search_object": "Claudio Bellino",
"search_type": "full_name",
"data_mode": "rawdata",
"code": 0,
"row_count": 10,
"name_count": 2,
"email_count": 6,
"address_count": 3,
"phone_count": 1,
"results": [
{
"db_name": "flytap_2022",
"code": "1698284",
"data": {
"full_name": "Sig Claudio Bellino",
"dob": "1957-10-28",
"phone": "393490894901",
"email": "claudiob144@gmail.com",
"id": "28903837",
"id2": "431313794",
"gender": "M",
"reg_date": "2018-10-13",
"language": "IT"
}
},
{
"db_name": "pdl_2019",
"code": "5701919",
"data": {
"full_name": "Claudio Bellino",
"address": "Milan",
"country": "IT",
"region": "Lombardy",
"linkedin_ids": "beclaudio81"
}
},
{
"db_name": "pdl_2019",
"code": "6376157",
"data": {
"full_name": "Claudio Bellino",
"address": "Turin",
"country": "IT",
"region": "Piedmont",
"linkedin_ids": "claudio-bellino-9292b98a"
}
},
{
"db_name": "pdl_2019",
"code": "27070109",
"data": {
"full_name": "Claudio Bellino",
"country": "IT",
"linkedin_ids": "claudio-bellino-9666a687"
}
},
{
"db_name": "pdl_2019",
"code": "62274634",
"data": {
"full_name": "Claudio Bellino",
"email": "reverendo74@yahoo.it",
"address": "Turin",
"country": "IT",
"region": "Piedmont",
"linkedin_ids": "claudio-bellino-944a5146"
}
},
{
"db_name": "pdl_2019",
"code": "87028495",
"data": {
"full_name": "Claudio Bellino",
"email": "claudiobellino@hotmail.it",
"address": "Caserta",
"country": "IT",
"region": "Campania",
"linkedin_ids": "claudio-bellino-634b711b"
}
},
{
"db_name": "pdl_2019",
"code": "118393129",
"data": {
"full_name": "Claudio Bellino",
"email": "bellino_claudio@yahoo.it",
"country": "IT",
"linkedin_ids": "claudio-bellino-969a1445"
}
},
{
"db_name": "pdl_2019",
"code": "151494351",
"data": {
"full_name": "Claudio Bellino",
"email": "claudio.delbellino@libero.it",
"country": "IT",
"linkedin_ids": "claudio-del-bellino-7b6a3527"
}
},
{
"db_name": "twitter_2021",
"code": "154793345",
"data": {
"email": "klabell@email.it",
"full_name": "Claudio Bellino",
"username": "klabell57",
"reg_date": "2012-02-28",
"followers": "7"
}
},
{
"db_name": "twitter_2021",
"code": "187877908",
"data": {
"email": "bellino_claudio@yahoo.it",
"full_name": "Claudio Bellino",
"username": "ClaudioBellino",
"reg_date": "2011-08-11",
"followers": "8"
}
}
]
},
{
"current_price": 0.4,
"user_balance": 31.3
}
]
This is a paid action. It purchases a
specific person from the
us_data
database using the
code
=
14829199
.
You must get the
db_name
and
code
from a
search_people
or
search_filter
request first.
https://uidfinder.com/v1/?api_key=ZX2IZ7YNTNWY6FD9&action=buy_people&db_name=us_data&code=14829199
curl "https://uidfinder.com/v1/?api_key=ZX2IZ7YNTNWY6FD9&action=buy_people&db_name=us_data&code=14829199"
As POST:
curl -X POST "https://uidfinder.com/v1/" \
-d "api_key=ZX2IZ7YNTNWY6FD9" \
-d "action=buy_people" \
-d "db_name=us_data" \
-d "code=14829199"
[
{
"db_name": "us_data",
"code": 14829199,
"first_name": "Brian",
"middle_name": "S",
"last_name": "Hake",
"marital": "Married",
"gender": "M",
"dob_year": "1971",
"dob_month": 3,
"dob_day": 29,
"credit_capacity": "$29750",
"number_children": 4,
"home_purchase_date": "2016-11",
"vehicle_owned": "3",
"animals_pets": "1,2",
"donor": "3,6",
"credit_card_mail_order_buyers": "1,2,4,5,8,9",
"hobby_interest": "3",
"cooking_food": "1",
"movie_music": "2,4",
"health_and_fitness": "1,2,4",
"last_name_rate": "3100",
"full_name_rate": "31",
"mode": 0,
"last_name_ethnic": "English",
"income": "$150,000 to $174,999",
"networth": "$100,001 to $500,000",
"address1": "OH, Columbus, 43201-1352, 2078 Summit St|npd_2024 (att_2021, us_citizens_2023, acxiom_2020, cellphone_usa_2019)",
"address1_location": "(40.005736 -83.000534)",
"address1_length_of_residence": "10 to 14 Years",
"address2": "OH, Columbus, 43201-1426, 53 E Woodruff Ave|npd_2024 (att_2021, us_citizens_2023, drivesure_2020, acxiom_2020, luxottica_2021, cellphone_usa_2019)",
"address2_location": "(40.003906 -83.007289)",
"address3": "OH, Columbus, 43201, 22 E Northwood Ave|npd_2024",
"address4": "OH, Columbus, 43220, 2064 Park Run Dr D|npd_2024",
"address5": "OH, Columbus, 43220, 2064 Park Run Dr|npd_2024 (car_insurance_2016, drivesure_2020, luxottica_2021, cellphone_usa_2019)",
"address5_location": "(40.060495 -83.074342)",
"address6": "OH, Columbus, 43221-1618, 1070 Caniff Rd|npd_2024 (att_2021, us_citizens_2023, drivesure_2020, acxiom_2020, cellphone_usa_2019)",
"address6_location": "(40.02701 -83.043313)",
"address7": "OH, Lewis Center, 43035-6089, 1751 Royal Oak Dr|npd_2024, luxottica_2021 (us_citizens_2023, car_insurance_2016, acxiom_2020, cellphone_usa_2019)",
"address7_location": "(40.165497 -82.996472)",
"address8": "OH, Lewis Center, 43035-8306, 7338 Walker Wood Blvd|npd_2024, us_citizens_2023, car_insurance_2016, acxiom_2020, luxottica_2021 (att_2021, drivesure_2020)",
"address8_location": "(40.1671651 -82.9732176)",
"address9": "PA, Freedom, 15042-2828, 110 Pony Dr|npd_2024 (us_citizens_2023, luxottica_2021, cellphone_usa_2019)",
"address9_location": "(40.683824 -80.1512465)",
"address10": "PA, Pittsburgh, 15237-1608, 1549 Dalton Dr|npd_2024 (us_citizens_2023, acxiom_2020, luxottica_2021, cellphone_usa_2019)",
"address10_location": "(40.583274 -80.07746)",
"address11": "WI, Milwaukee, 53201, 3147 Po Box|npd_2024",
"phone1": "1 (614) 537-9402, OH, mobile|car_insurance_2016, acxiom_2020, mgm_2019 (att_2021, us_citizens_2023, drivesure_2020, luxottica_2021, cellphone_usa_2019)",
"phone2": "1 (740) 549-1711, OH|npd_2024, luxottica_2021 (att_2021)",
"phone3": "1 (740) 879-3172, OH|car_insurance_2016 (att_2021, drivesure_2020, pdl_2019)",
"vin1": "2FMHK6CC5BBD14097, 2011, Ford, Flex|car_insurance_2016",
"vin2": "JA4LS31W29Z002296, 2009, MINI SPORT UTILITY, MITSUBISHI, OUTLANDER, WAGON|car_insurance_2016",
"ssn9": "199-60-2734",
"ssn_issued_state": "PA"
},
{
"user_balance": 30.9,
"current_price": 0.4
}
]
Error Responses
If your request fails, the API will return a JSON object with an event_message.
These errors occur if your request is missing required parameters or uses invalid/misspelled values. Check your request against the documentation.
{"event_result":"error","event_message":"missing or invalid `api_key` parameter"}
Your api_key is missing, empty, or misspelled. This parameter is required for all requests.
{"event_result":"error","event_message":"missing or invalid `action` parameter"}
The action parameter is missing, empty, or misspelled. This parameter (e.g., action=account_info) is required for all requests.
{"event_result":"error","event_message":"unsupported or invalid value for `action` parameter"}
You provided an action, but its value is not recognized. For example, using action=get_info instead of action=account_info.
{"event_result":"error","event_message":"missing or invalid `type` parameter"}
The type parameter (e.g., type=phone) is required for this action (like search_rawdata or search_people) but was not provided or was misspelled.
{"event_result":"error","event_message":"missing or invalid `country` parameter"}
The country parameter is required for action=search_filter but was not provided or was misspelled.
{"event_result":"error","event_message":"unsupported or invalid value for `country` parameter"}
The value for country is invalid. It must be a 2-letter code (ISO 3166-1 alpha-2), like US, GB, or DE.
{"event_result":"error","event_message":"unsupported `type` value for `rawdata` mode"}
You used a type that is not supported for action=search_rawdata. For example, type=address is only valid for search_people.
{"event_result":"error","event_message":"unsupported `type` value for `people` mode"}
You used a type that is not supported for action=search_people. Check the "API Actions & Parameters" section for valid types.
{"event_result":"error","event_message":"missing or invalid `db_name` parameter"}
The db_name parameter is missing or misspelled. This is required for action=buy_people (e.g., db_name=us_data).
{"event_result":"error","event_message":"invalid value for `code` parameter"}
The code parameter is invalid. It must be the number (ID) of the person you want to buy, which you get from a search_people or search_filter request.
{"event_result":"error","event_message":"filter `related`, invalid value"}
The value for the optional related filter (in search_filter) is not on the allowed list (e.g., paypal, amazon, dating, etc.).
{"event_result":"error","event_message":"filter `dob_start`, out of range'"}
The dob_start filter value is out of range. It must be a 4-digit year between 1920 and 2010.
{"event_result":"error","event_message":"filter `dob_end`, out of range'"}
The dob_end filter value is out of range. It must be a 4-digit year between 1920 and 2010.
{"event_result":"error","event_message":"filter `gender`, invalid value"}
The gender filter value is invalid. It only accepts M (for Male) or F (for Female).
{"event_result":"error","event_message":"insufficient total deposit"}
Your account's total deposit amount is less than $50. API access is only granted after your total deposits reach this threshold. Check your status on the Billing page.
{"event_result":"error","event_message":"insufficient balance"}
You do not have enough funds in your current balance to make this purchase. Please top up your account.
{"event_result":"error","event_message":"server error"}
An unexpected internal error occurred on our server. We apologize for the inconvenience. Please try your request again in a few moments.
{"event_result":"error","event_message":"service unavailable"}
The service is temporarily down for maintenance or is overloaded. Please try again in a few minutes.