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.
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 has a 10-20% match rate on U.S.-based numbers. International numbers will be lower.
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 10-20% 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 our Sales team at 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+. 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.
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.
Does Person API support lookups by internationally formatted phone numbers?
If you're curious as to what query formations and internalization standards we support, don't be afraid to try! Sign up for a free API key, and we recommend reaching out to our Support team for additional troubleshooting. Keep in mind that our match rate for international phone numbers is quite low.