Skip to main content
Ben Nadel at cf.Objective() 2009 (Minneapolis, MN) with: Troy Pullis
Ben Nadel at cf.Objective() 2009 (Minneapolis, MN) with: Troy Pullis

Getting Contact, Photos, And Social Media Information Using FullContact.com And An Email Address

By
Published in Comments (32)

As the web becomes more socially-focused, it's becoming more important to give our software a social vibe. Often times, this can be accomplished by simply accenting the user interface with photos. Unfortunately, when it comes to users, the only substantial piece of information that we have [in the beginning] is the user's email address. Luckily, companies like FullContact are attacking this problem with intense focus. FullContact attempts to provide robust and extended contact information, including photos and social media data (ie. Facebook, Twitter, LinkedIn, etc.) given nothing more than an email address.

The FullContact.com API is simple. You give it an email address (and an API key) and it returns a contact. This information can be returned in JSON (JavaScript Object Notation), XML, or HTML if you want to use their layout logic. The documentation also provides for a JSONP (JSON with Padding) cross-domain response; however, this would require your API key to be passed publicly, which is probably something you'd like to avoid.

Obviously, the API is not magic; and, there's going to be a large variability in the amount of information that can be gotten based on any given email address. Some of this information has already been indexed in the FullContact database; other information will be searched as the API is used. This divergence will be indicated by the API response status code:

  • 200 response indicates that a contact has been found.

  • 202 response indicates that the request has been queued and the FullContact spiders will be searching for the contact. The contact may be available at a later time in a subsequent request.

  • 404 response indicates the the email address has been searched-for within the last 24 hours and yielded no valid information.

That's really all there is to it - the API is extremely straightforward. Let's take a look at some ColdFusion code to see how it works in practice. In the following demo, I'll be searching for my own email address.

<!--- Set up the API key for the FullContact application.--->
<cfset apiKey = "**************************" />

<!---
	Define the API url. This can use .JSON, .XML, and .HTML
	extensions to define the content-type of the response that
	comes back.

	NOTE: You can provide a "callback" param for a JSON(P) response;
	however, you should not publicize your API key... so, you
	probably shouldn't use that.
--->
<cfset apiUrl = "https://api.fullcontact.com/v1/person.json" />


<!--- ----------------------------------------------------- --->
<!--- ----------------------------------------------------- --->


<!---
	Make an HTTP request to the FullContact API (using either GET
	or POST) for contact information based on an EMAIL address.

	Useful Responses:

	200 : Request processed fully.
	202 : Request accepted (and queued - contact currenly unknown).
	404 : Email has been searched and does not resolve to a contact.
--->
<cfhttp
	result="fullContactResponse"
	method="get"
	url="#apiUrl#"
	useragent="ColdFusion/FullContact-API">

	<!--- Provide the API key. --->
	<cfhttpparam
		type="url"
		name="apiKey"
		value="#apiKey#"
		/>

	<!--- Provide the email address for which we are searching. --->
	<cfhttpparam
		type="url"
		name="email"
		value="ben@bennadel.com"
		/>

</cfhttp>


<!---
	Check to see if the email address resulted in a 200 (found)
	response. This means that we have valid contact information based
	on the email.
--->
<cfif find( "202", fullContactResponse.statusCode )>

	<!---
		This email address was not yet indexed in the FullContact
		database; it is now being searched - hopefully, you can check
		back later for a fleshed-out contact.
	--->
	<p>
		The contact is not yet indexed - check back later.
	</p>

	<!--- Stop processing. --->
	<cfexit />

<cfelseif !find( "200", fullContactResponse.statusCode )>

	<!---
		Something else went wrong - either the contact was not
		found OR the email address is not valid OR the API key
		is not valid.
	--->
	<p>
		Hmmm, that's not gonna work.
	</p>

	<!--- Stop processing. --->
	<cfexit />

</cfif>


<!--- ----------------------------------------------------- --->
<!--- ----------------------------------------------------- --->


<!---
	If we've gotten this far, then we should have a valid contact
	based on the given email address.

	NOTE: Not all fields will be available - it depends on how much
	of the contact *can* be found based on email address. Linking
	your social networks (Facebook, Twitter, etc.) to the FullContact
	account can help increase the information.
--->
<cfset contact = deserializeJSON( fullContactResponse.fileContent ) />

<!--- Dump out the contact for debugging. --->
<cfdump
	var="#contact#"
	label="FullContact API"
	/>

As you can see, this is nothing more than an HTTP request followed by a JSON deserialization. And, here is the output that is generated by the CFDump:

A FullContact.com API response for contact and social media information given an email address.

That's a lot of information! And, all based on my email address. Of course, I participate in a number of online social circles which probably makes my information easier to come by. Based on my testing of the API, some email addresses returned almost no information at all - not even the contact's name. This makes sense; but, it makes the API a bit harder to use as you have to manually normalize the response.

Using the API costs 3 cents per contact. But, it looks like you get the first 3,000 contacts for free. And, it looks like you also get $50 in credit when you sign up. I've been testing this on my paid account and I have yet to enter any credit card information. So, clearly, there's some wiggle room when it comes to getting up and running.

I love that this API attempts to answer only a single, important question: I have an email address and I want contact information. I can definitely see myself using this kind of functionality in the software that I design going forward.

Want to use code from this post? Check out the license.

Reader Comments

357 Comments

This is a damn cool API... if a bit pricey. I mean it sounds like they give you a LOT of time to test. That's great. But _after_ that, 3 cents a pop would add up REAL fast.

15 Comments

That's seems a little bit stalker like and scary... although entirely understandable. It's all publicly available though.

In a non scary legit way it seems like a very useful idea though, I like the idea of tying together the numerous social profiles that exist.

It does seem expensive, but they have got a volume pricing option, I guess they'll do bulk discounts.

15,848 Comments

@Ray,

I had the same feeling - that the cost would add up. It definitely makes it harder to add to an application that is not necessarily generating any revenue :) Still, I love that this system is trying to solve one problem *well*.

@Peter,

There's definitely a stalker feel to it. But, I think that is simply going to come down to how people integrate it in their software. If you make it too obvious, it will be weird. But, if you use it to subtly enhance your software and make the user's experience seamless, then I think it will be awesome.

... where that balance exists? No idea :)

15,848 Comments

@Ray,

I don't know - I didn't even know that social media sites could be "indexed" by email address. There must be some secret-sauce in how they're finding the data??

357 Comments

All of them have some form of search.

I just did a search for me on FB and found me. Done. (I mean via the API of course.)

So... maybe not one hour, but, it should be possible.

15,848 Comments

@Neil,

I think Gravatar hashes the email address because the IMG SRC values are "public". As such, you don't necessarily want to publicize email addresses.

Calls to the FullContact.com API, on the other hand, are (or should be) done server-side where the email address is not visible to the public users. So, I think security is less of a concern.

But, that's just a guess.

383 Comments

This is all very interesting. It's exactly the kind of thing that really intrigues me. Of course, I'm able to get all sorts of information from probably less, but it's still interesting to know. It makes it much easier, and cuts down on the time it might would take otherwise. (I used to intern for the fbi, so I have some experience and knowledge that I gained from that). Not that I ever use that particular skill set anymore or anything, but it's there.

26 Comments

It always amazes me how little people care about when or where they reveal their data. FullContact seems to be able to relate your Youtube account to your Twitter account to your bio to your demographics. That is more that just a little scary to me...

@Ben, in your dump your usernames for the different social sites arelisted. That is half of what is needed in order to get acceess to your accounts. Doesn't that bother you? From a security point of view, for someone as public as you I'd recommend using something not as obvious as a username. ;-)

Cheers

Chris

15,848 Comments

@Aaron,

Very interesting. I had no idea that Google even had an API like that. I'll have to poke around with it.

@Christoph,

Definitely there is something undeniably creepy about being able to get all that information. Honestly, it feels like a breach of security to be able to related email address to accounts (as this would seem to be "private" information especially when the email address is NOT the login/username).

Before I posted this, I did look at the data to see if there was a stuff there I was scared to reveal. I guess the usernames didn't necessarily strike me as being too bad... could just be my naivete :(

383 Comments

@Ben, you're just being brave. :-P Plus, it's not like your username would be all that difficult to figure out anyway.

10 Comments

Yeah, up till now I was pretty content that quick searches for me (and now my email address) didn't reveal anything about me.

I never thought of using my username, which I use for nearly everything. It makes perfect sense when I think about it, but it is still unnerving to see how much stuff, going back a few years, shows up in a google search of that.

383 Comments

@Ken, I cringe at the things that are revealed about me when my name is searched. My old track records are still out there. I am glad I did track, but I wasn't competitive at all. My times sucked! I'd rather them not be out there, because I really did it for my own self fulfillment, but I would rather not everyone know how badly my times sucked. Oh well...

383 Comments

@Ken, would it make you feel really good if I said you could probably beat me at chess with one hand tied behind your back and all but one of the lobes of your brain missing? I have played chess very few times in my lifetime, and was never really very good at it. I think I have problems with looking ahead. I have never had problems with strategic games other than that, but I have not had many good chess games, and I have never won. I can be pretty competitive with some things, but I'm afraid chess is not one of those. :-/ Maybe if I found a good teacher and played more often, I might could get ok with it, but I have so far not played very well at all.

10 Comments

@Anna, not as much as you might think. Even though I do pretty well in chess, I play mostly on instinct (how the board "looks" to me, or whether I can see a pattern after glancing at it), with little planning. My strategy tends to be a defensive one, attacking when I see an opening, but not really planning for them. I could plan more, and I do much better when I do, but I'm too impatient and it isn't as fun that way.

10 Comments

Oh, and as proof that my defensive strategy isn't the best: Some Russian kid, who I'm told was #1 in all of Russia before he moved, only needed 29 moves to beat me.

383 Comments

@Ken, I can be impatient with certain things, and agree that it is less fun that way. A lot can be said for instinct, and don't underestimate the power of patterns. Have you ever seen A Beautiful Mind? A lot of times, people with a very mathematical mind see in patterns, and it leads to genius. That's one of the things I got out of watching the movie, anyway, but my analysis could be completely incorrect. :-)

And about the Russian kid beating you...I go mainly by instinct when I do Martial Arts grappling/greco-roman wrestling, and I once fought a Brittish chick who was "undefeated" in Great Brittain in submission fighting, and yeah, suffice it to say that she beat me pretty easily. Now, here, and fighting people who are not undefeated, I do pretty well as an instinct wrestler, but going against someone with experience and who is undefeated...yeah, I can be beat hands down. She was pretty strong! I'm not even going to throw in "for a girl", because she could probably have beaten a lot of the guys I have fought (and some I have beaten).

10 Comments

@Anna, lol, I'm not going to argue with anyone who likens me to Nash.

Also, you worked at the cia, you do martial arts, are you a spy by chance?

Bringing this back on topic, I think making a free service like this would be nice to let people see how visible they are. I'm wondering, though, how to go about exposing it. If the intent is to show people how public their lives are in case they are revealing more information than they wish, making a service that essentially is a stalk button seems to be wrong. If it were only based on email, I could see sending the results to the email, but I think user name provides more insight. any ideas?

I hope this all made sense, I'm using my phone right now anf sometimes I get ahead of myself.

383 Comments

@Ken, as for your post making sense, is what you are talking about similar to the way companies hire hackers to expose their security risks? I'm not sure that what we are discussing above...the contact information scenario...could be handled in this way. I am really, really good at hiding myself, but a part of that ability and knowledge comes from the fact that I am good at researching and finding out information. In order to be good at hiding yourself, you almost need to be able to know how information is found. It's all necessary for me because of an ex I have. And I did work for the fbi as an intern, but not the cia. It was during the Monica Lewinsky times, so there were jokes about governmental interns, but it was a pretty good experience, and one of the things it taught me was about information and how it was found (and how to research certain things and find information on certain things). They had this awesome database. You could find out almost anything about anybody.

10 Comments

@Anna, Yeah, I realized after I clicked Post that you said fbi, not cia, but I stand by my theory :)

Also, it's not necessarily to expose people to security risks in that it would tell them how to "fix" issues, I was thinking more of it just showing them what is easily available, because a lot of people I know don't realize how much they have public. Kinda just a starting point for seeing if their online presence is acceptable to them. I think for a bunch of people (based on statistics I just made up), this would be more of a wake-up call so they would be more considerate when they are participating in things like social media, instead of just blindly putting their lives out there.

383 Comments

@Ken, I was a governmental intern, but I'm not a spy. :-)

I'm actually not a person, but a robot. I just took this picture of someone else and posted it as mine, but that's not really me. :-)

That would be a start, and it would probably make people think twice about putting stuff out there in the social media realm, but information was easy to come by before social media even came about or at least before it was so big, especially if you are good at finding it.

To give you an idea of how easy it is to get information on somebody, I had the first name and the name of a person this girl was dating. That's all the information I had...the first name and the name of the guy she was dating. From that, I was able to find out her first and last name, address, probably her phone number (I don't remember, but I am pretty sure), where she worked, her work and address phone numbers, and the last guy she dated, who had been her fiance, and the name of her two dogs. I also had the address of her ex-fiance as well. I'm not a stalker in that I don't actually do anything with this information. I don't go and sit outside of people's houses or anything creepy like that. But the information is out there if you know how to get it.

And I am pretty sure she doesn't even participate in "Social Media", or at least I am pretty sure she was not at that time.

On a somewhat related note, I kind of ran into her later when I volunteered for this group where we were taking our dogs and doing stuff with them, trying to help out the greater good of the community and all of that stuff, and that was kind of awkward, but I don't think she ever knew how much I knew about her.

1 Comments

Not sure my contacts would appreciate FullContact.com having their pertinent details, including picture. Although this information exists all over the place, the FullContact customer would provide the glue for all of the parts and then for 3 cents they have amazing contact information to resell, even if they say they wont or to lose (which honestly, I dont trust anyone who says they WONT lose personal information because........they all do in the end).

So, in this low-trust world, I think I will keep my clients' (and personal) contact information private.

:-)

15,848 Comments

@Ken,

Not to get too far off topic, but as far as playing chess based on how the board "looks", apparently this is the way most high-level players actually work. This is why chess grand masters even have (or at least, had) a chance against super computers. While the computer could analyze millions of moves at a time, the grand masters just saw patterns instinctively in the board.

When this was realized, the computer algorithms were adjusted to work in similar ways. Once this was done, humans didn't have a chance. But, all to say, a huge part of what makes the human brain so amazing is its pattern-matching abilities.

@All,

While you can use this information for evil, I suppose, it is all public. So, if someone was so determined, I assume they would be able to find it somehow. As such, I'm not gonna worry too much about the public nature of the data... though, it does make me think twice about the security of my passwords. They should probably be more secure!

To me, the real power here is going to come to building software that really incorporates people thoroughly. I can only speak for myself, but when I log into a new system and I see my photo there, my first is *not* "how did they get that?"; my first thought is, "awesome!"

1 Comments

Great, that looks very useful!

But did anybody think already of creating a Thunderbird addon from this?

I believe in love. I believe in compassion. I believe in human rights. I believe that we can afford to give more of these gifts to the world around us because it costs us nothing to be decent and kind and understanding. And, I want you to know that when you land on this site, you are accepted for who you are, no matter how you identify, what truths you live, or whatever kind of goofy shit makes you feel alive! Rock on with your bad self!
Ben Nadel