Most Popular: Top 7 Ways to Get the Most Out of the FullContact API

As you get started using the FullContact API, here are some important tips that'll help you get the best results:

1: Get a Free Match Test

When testing out the Person API, sample sizes of less than a few hundred can skew results.

We can run a free match test on a larger sample to give you a better idea of what results you'd see on a larger scale. Just email us at and we'll set it up. 

2: Remember: You're charged for matches, not calls.

We only charge for successful matches - with the free API plan, you get up to 250 free matches per month.

A "match" is a response where we return fields to your query (a 200 response). Any other response code (404, 202) does not count against your monthly matches.

3: What happens when I make repeated calls for the same query?

Every 200 response counts as a match, even if you've made the query before.

4: 202 responses are normal.

A 202 means we haven't seen this query before so we're searching for public information. This search takes two minutes or less. If we haven't found anything by then, we return a 404.

Please see our docs for a complete flowchart of the response codes.

5: Implement webhooks to manage 202's.

The best way to deal with 202's is to implement webhooks. We'll POST a response back to your webhook listener when we've completed our search.

You can also make queue calls to seed our API then call back later.

6: 404's are also normal.

Sometimes we just can't find public information, due to the person's low social presence, high privacy settings, or the terms of service of some networks. In those cases we return a 404 response.

7: To retain data, you'll need to upgrade.

As a user on the free FullContact API plan, you are required to delete data we provide after seven days. If you upgrade to a paid plan, you can retain data for as long as you are a customer.

And there you have it. 7 things that will make your life using the FullContact API a lot easier. Thanks again for trying out our API!

For more comprehensive information, please visit our docs - or email us at if you have questions. We're glad to help.

If you like your free trial, our business plans start at just $99 per month for 6,000 matches.

FullContact Developer API

  1. Most Popular: Top 7 Ways to Get the Most Out of the FullContact API
  2. Most Popular: How can I test FullContact's APIs?
  3. Most Popular: How accurate is FullContact's data?
  4. Most Popular: Does my plan have any rate limits? What is the best way to handle them?
  5. Most Popular: How do I interact with FullContact APIs?
  6. Most Popular: Where does FullContact get its data?
  7. Most Popular: Can I add another user to my admin account?
  8. Person API: What type of information does FullContact need in a query to provide back data?
  9. Person API: What is the difference between querying this endpoint by email and social handle?
  10. Person API: What is the match/fill rate for the Person API?
  11. Person API: What pieces of data is a Person query most likely to pull?
  12. Person API: How can I use the FullContact Excel Macro?
  13. Person API: Why is it possible to return different types of LinkedIn URLs?
  14. Person API: Why does a query return a Twitter handle but no Klout score?
  15. Response Codes: What do the FullContact API response codes mean (202, 503)?
  16. Integration: Querying the API using Javascript
  17. Integration: Querying the API using Java
  18. Integration: What is a good tool for rate limiting in Java?
  19. Integration: How do FullContact's webhooks work?
  20. Integration: How do I implement webhooks in the Person API?
  21. Integration: Can I customize the look of HTML responses?
  22. DevOps: What IP address ranges does the FullContact API use for posting webhook responses to callback URLs?
  23. DevOps: How fast is the response time for the Person API?
  24. DevOps: What Amazon Web Services region does the FullContact use?
  25. Pricing: How often can I upgrade or downgrade FullContact API plans?
  26. Pricing: How do I cancel my API account?
  27. Pricing: When does FullContact invoice and charge for API plans?
  28. Terms: Can I relicense FullContact's data?
  29. Why do I receive an error when using the timeoutSeconds parameter?
  30. Terms: Do I have to attribute data to FullContact in my app/software?
  31. Company API: What is the match/fill rate?
  32. Company API: What formats are supported for this endpoint?
  33. Company API: What are the categories of companies returned?
  34. Most Popular: How do the FullContact algorithms connect-the-dots on social data?
  35. How to Claim Profile and Get More Precise Results for My Profile?
  36. Why am I getting a 404 error when using the API console?

Feedback and Knowledge Base