How can I 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:
Sample sizes of less than a few hundred can skew results, so the free calls may not suffice to give you a broad sense of how well your data matches with us.
We can run simple free tests or more complex paid pilots to give you a better idea of what results you'd see on a larger scale. Just email us at firstname.lastname@example.org 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 202s
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. 404s 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 paying customer.
How can I get started with FullContact's APIs?
You’ll receive an email from our team with your key to begin querying. To check your account, you’ll use our Developer Portal.
That being said, what can you expect with a free API key? From our Pricing page, you can expect the following:
With your free key, you’ll be to make 250 matches per month along with making 60 total requests in any given minute. While testing our API services with your free key, keep in mind that you won’t be able to retain any data that FullContact provides.
You’ll find examples for how to query Person, Company, Card Reader, Email, and Name API directly in the Developer Docs. For testing purposes, you’ll find examples of what to query for free, i.e. data that will not count against your monthly limit.
- Via Person API, you can use email@example.com in the following URL to get a better idea of the data that can be returned:
- Via Company API, you can use fullcontact.com in the following URL to get a better idea of Company data that can be returned:
Simply replace the ‘xxxx’ at the end of the URL with your key. That being said, in addition to pasting your API call directly into your browser, you or your developers can use our live API console to make a test query against one of our endpoints.
Lastly, you’ll want to get familiar with Response Codes, as displayed below:
All successful responses (except for Company API) are returned in JSON, XML, HTML or vCard, depending on the response format you request. Only queries that respond with a 200 response code (successfully completed) are counted towards monthly allowances.
How do I interact with FullContact APIs?
To interact with FullContact's Person API endpoint, you can query our RESTful API with HTTP GET or POST requests.
FullContact then cleans and enriches the data and then passes it back.
All successful responses are in JSON, XML, HTML, or vCard format, depending on the response format you request. Company API currently only supports JSON format.
For our paid endpoints, you will only be billed for queries that respond with a 200 response code, which indicates that there was a match.
Please see our API docs for additional information.
Where can I find API pricing information?
Here's a link to our Data Solutions pricing info and pricing matrix. If you sign up for a free key, you get 250 free matches/month.
Do I have to attribute data to FullContact in my app/software?
All plans require attribution unless otherwise specified by FullContact and your Account Executive or Manager.
Please review our attribution guidelines for helpful instructions. Putting our badge on your site is quick, requires no updating, and is non-obtrusive.
What do the various response codes mean?
The FullContact API docs are the best place to find the most up to date information on our response codes. Here is a direct link to that section. Possible reasons for most common responses:
Why am I getting 202 responses? How long does it take the FullContact Person API to perform the search after a 202 response?
- This is a new search request that we haven’t seen before and will search for it - hence the message stating that you should try again. A 202 response does not count as a match and is not counted in your monthly allowance of Person matches so a refresh is needed.
- A webhook URL was provided in the request and the response will be delivered to that URL
- The request had ‘queue=1’ on it, which will force a refresh of the record.
You should resubmit non-webhook queries that result in 202 responses so that you can get the final result of the search, which will be either a 200 result with the data for the person searched, or a 404 response, indicating the search did not find any information for the person queried. If you do not resubmit your query on 202 responses, you are potentially leaving a lot of matches on the table!
If you prefer not to have to track and resubmit queries that resulted in a 202 response, we recommend you use our webhooks capability. With webhooks you call the Person API with your query, and then we POST back your endpoint/URL once we have the complete response to your query. You do not need to resubmit your request. You can read more about how to implement webhooks in the Webhooks section of the Person API docs. Within the Person API documentation, you can also view a full diagram of the Person API process flow.
Why am I getting a 503 response when I query the Person API?
503 responses are "retryable errors." They generally happen when we are deploying code and requests get erroneously routed to an old server that is in the process of shutting down.
If you get a 503 error, you should be able to retry your request and get a non-503 response.
Why am I being rate limited?
Your API plan will have a rate limit. Please see our pricing matrix for the individual rate limitations.
To get our data we combine information from hundreds of public websites, social networks, APIs and trusted partners and users of our service. Some of these networks have their own rate limits that we have to manage to provide you back a response. To make sure that we provide the most complete, up to date, and accurate information for all of our users we have to rate limit on the number of queries per second.
If you are using the Company API, it has the same limit as the Person API endpoint but is counted separately.
Higher rate limits are available. Please contact our Sales team: firstname.lastname@example.org
While coding for rate limits we recommend using a rate limit header to maximize throughput in our system.
We return three headers that look like this:
Reset is the number of seconds until you can begin hitting the API again. Remaining is your calls remaining of the Limit in the 1-minute period.
We've had a lot of success having a single agent querying us and using the headers to dynamically adjust rates. We've also had success with multiple agents sharing this rate by synchronizing the state of these headers in memcached. Generally, we've used them to calculate sleeps on the querying thread(s). While not preferred, you can also make a many calls as quickly as you need up to this per-minute limit, so if it's easier to instead do 20 calls every 2 seconds, that's works.
These headers are only accurate for single query (e.g. GET /v2/person.json...) vs. the batch endpoint.
Also note, these rate limits apply for all response codes, 200, 202, 404.
Can I customize the look of HTML responses?
Yes, using the CSS parameter in your query. For example, here is how you would structure it:
You can download the person.html stylesheet template here. This includes the default stylesheet used by FullContact, a sample Person HTML file and a template stylesheet for your custom styles.