Getting Contact, Photos, And Social Media Information Using FullContact.com And An Email Address
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:
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
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.
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.
@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 :)
I bet we could rebuild this in ColdFusion in a few hours. It's something I've been tempted to do myself.
@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??
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.
@Ray,
Hmm, that's pretty cool. I didn't know it was possible. So yeah, I could see this being doable.
Hmm, I wonder why they don't hash the email address like Gravatar.
@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.
Ben and Ray - you might like this one, too. Google has the Social Graph API, so if all you know is a social media URL (or email address) for someone, you can get pretty much all the publicly available social info about that person with a free (limited) and super-simple API - http://code.google.com/apis/socialgraph/docs/otherme.html
Well that is darn interesting Aaron! Unfortunately, I can't get it to return _anything_ on me at all.
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.
@Ray - strange, this works http://refynr.com/secure/account/TwitterUser.cfm?screenName=cfjedimaster (via your twitter URL, and you must be logged in to Refynr).
It really finds a lot on my account: http://refynr.com/secure/account/TwitterUser.cfm?screenName=aqlong
Interesting. THat worked for me. But I had tried searching via my email address and it found nothing. I then tried my blog url - ditto.
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
@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 :(
@Ben, you're just being brave. :-P Plus, it's not like your username would be all that difficult to figure out anyway.
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.
@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...
@Anna: Ah, the benefits of chess club. I'm pretty sure nobody outside it documented the games.
@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.
@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.
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.
@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).
@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.
@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.
@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.
@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.
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.
:-)
@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!"
any other information contact me.../
Great, that looks very useful!
But did anybody think already of creating a Thunderbird addon from this?