Overview

The FullContact Developer APIs are used to manage and enhance contact information. Use our APIs to provide social profiles in your app, improve contacts in address books, enrich CRM information, or create highly personalized marketing campaigns.

Our APIs are RESTful. Responses are delivered in JSON format with most endpoints also providing support for XML format. Some endpoints support HTML formatted responses. Sign up for a free account to get an API Key and get started.

Monitor and subscribe to status updates at http://status.fullcontact.com

Authentication

All requests to all endpoints require you to specify your unique API key. The API Key is assigned to you by FullContact and is used to identify and authorize each request. Your API key should be kept private, and should never be displayed publicly.

The primary and recommended method for authenticating with FullContact is to specify the API key in the HTTP request header using an extended header field with the name X-FullContact-APIKey.

curl -H"X-FullContact-APIKey:$your_key" https://api.fullcontact.com/v2/person.json?email=bart@fullcontact.com

FullContact supports an alternative means for authentication, which is by specifying the API key in the query parameter in the form of apiKey=. Keep in mind that we recommend use of the HTTP header field rather than the apiKey query parameter as it provides an added level of security. Although we utilize HTTPS to ensure that all requests are encrypted for network transport, there is a possibility that the plain-text URI, with the value of the apiKey, might appear in logs of HTTP servers which process the requests. Additionally, there are spyware exploits whereby certain browser extensions track and aggregate browsing behavior and sell that data to third parties, again use of apiKey as a query parameter could lend itself to unintentional exposure of your API key.

Only use query parameter based authentication for testing purposes, and first ensure you don’t have browser extensions that are tracking your browser history! Browser extensions have access to every URL you open and you could inadvertently expose your API key.

For additional security, FullContact supports an enterprise level feature called Mutual Authentication. Please contact your account manager for more details.

Solutions should not call the FullContact API suite using client-side javascript. Doing so will expose your API key to users of your application. It’s recommended that you build a server-side endpoint to proxy traffic to and from the FullContact API if direct access is necessary.

CORS headers are deprecated in our offering and will be removed at a future date.

Response Codes

All successful responses are returned in JSON, XML, HTML or vCard, depending on the response format you request. On our paid endpoints, such as the Person, Card Reader , and Disposable Email endpoints, only queries that respond with a 200 response code (successfully completed), are counted towards monthly allowances and overages.

Status CodeDescription
200 OKYour request processed successfully.
202 AcceptedYour request is currently being processed. You can check again later to see the request has been processed.
400 Bad RequestYour request was malformed.
403 ForbiddenYour API key is invalid, missing, or has exceeded its quota. **Plans that have overages enabled will not receive a 403 response when they exceed their allotted matches. They will only receive a 403 for exceeding rate limit quotas.
404 Not FoundThe request query was searched in the past 24 hours and nothing was found.
405 Method Not AllowedYou have queried the API with an unsupported HTTP method. Retry your query with either GET or POST.
410 GoneThis resource cannot be found. You will receive this status code if you attempt to query our deprecated V1 endpoints.
422 InvalidInvalid or missing API query parameter.
500 Internal Server ErrorThere was an unexpected error on our server. If you see this please contact Support.
503 Service Temporarily UnavailableThere is a transient downstream error condition. We include a 'Retry-After' header dictating when to attempt the call again.

Rate Limiting

All API requests are subject to rate limits that exist independently of your API key's monthly usage allowance. We track rate-limits on a 60-second basis. For example, if your API is subject to a 10/second rate limit, we'll allow you 600 requests per 60 second window. To make it easier for your application to determine if it is being rate-limited, or if it is likely to be in the future, we've added the following HTTP headers to successful responses:

What You Need to Know About Rate Limits by FullContact

Header NameExample ValueDescription
X-Rate-Limit-Limit600The rate limit ceiling for your request
X-Rate-Limit-Remaining10The number of requests left in the 60 second window.
X-Rate-Limit-Reset20The number of UTC epoch seconds remaining until the 60 second window resets

Thanks to Twitter and Github for this pattern.