When querying the Person API endpoint, what type of information is needed in order to provide back data?
The Person API turns partial contacts into full contacts that contain rich social profiles including name, social networks, company, title, age, gender, location, photos and influencer scores powered by Klout.
You can search for information by:
- Email address
- Twitter handle
- Phone number*
Keep in mind that, for privacy reasons, we will not provide / return email addresses, phone numbers, or mail address info. You must specify the parameter you are using to lookup information. You must also include the apiKey parameter in the query. The endpoint supports GET requests.
*Lookup by phone number is in beta with a 1-2% match rate and only supports U.S.-based numbers.
How can I query the Person API endpoint?
By now, you probably have your FullContact API key in hand and you’re already reading through the documentation on how to get it set up inside of your application. However, did you know that you can also see FullContact Person API results right in your browser? You can, and it’s incredibly easy.
Open the email that we sent you that contains your API key. At the bottom, we give you an example JSON query that looks like this:
https://firstname.lastname@example.org&apiKey=[YOUR API KEY WILL BE HERE]
Entering that URL into a browser will show you the JSON response for email@example.com.
But if you change the person.json to person.html you’ll see the stylized version.
If you prefer an XML version, changing person.json to person.xml will show you those results.
Using your FullContact API key to call the Person API in the browser is handy for a number of reasons. It’s a great way to get a quick view of, to test new email data or to see a stylized version that’s easy to read.
Ready to get more in depth with the FullContact Person API? You can find everything you’ll need in our documentation.
What is the match/fill rate for the Person API endpoint?
Our match or fill rate is highly dependent on the set of emails, Twitter handles, or phone numbers we are given, and they vary from 20% to 60%. Keep in mind that querying via phone will likely result in 1-2% return.
Some lists, however, generate very high fill rates, whereas others may be low. This is due to the quality of the email domain, region and B2B vs. B2C addresses. We recommend you sign up for a test key or request a larger match test by contacting firstname.lastname@example.org to see what your match rate will be.
Why is it possible to return different types of LinkedIn URLs?
LinkedIn has several different types of URLs, which can contain LinkedIn IDs. Our Person API returns whatever URLs we can find related to the query in our API response. We do not return LinkedIn IDs. For customers looking for LinkedIn IDs, we recommend parsing these URLs to obtain the userID.
What pieces of data is a Person API query most likely to pull?
We are most likely to pull social profile URLs. The most common social profile URLs are Twitter, Facebook, and Google+. If we bring back a Twitter we will bring back Klout scores and topics associated with the data you send us. The next most likely are title, location, gender, and age.
What we pull for a given query is highly dependent on factors like the person's social media presence, how current their email address is, their privacy settings on various social networks, etc. You can find a full list of social network types returned by our Person API endpoint here.
Why does a Person API endpoint query return a Twitter handle without a Klout score?
According to Klout, there could be a few reasons why a Twitter handle does not have a Klout score:
- It is a private Twitter account (and not registered for Klout)
- The user has opted-out of Klout
- A Twitter account with little to no activity will actually not be picked up by Klout, and therefore not have a score associated with it. So, for all users who create a Twitter handle, never tweet, don't follow many people, etc., they might not be scored. Klout also uses a rolling 90-day window. If a user hasn't been replied to or retweeted within the last 90 days, then Klout has no scoring window for them (as they've never seen their handle and ID appear in the stream).
- If a user has changed their Twitter handle in those 90 days, and Klout hasn't seen them in the last 90 days, then Klout won't have picked up on their screen name change.
What is the difference between querying the Person API endpoint by email or social handle?
When searching by a social handle, we will almost always return a 200 response. This 200 response will include the confirmation of and data from the handle. However, there may not be information from any additional sources. We recommend that you use webhooks when querying by social data so we can run a search on the handle rather than just confirm it before returning data.
How fast is the response time for the Person API endpoint?
Our average response time is 50 milliseconds (ms) if you are on Amazon Web Services (AWS) and 500 ms if you are not. At this time, we use the AWS us-east1 region.