Back to Top

FullContact Developer API Documentation

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 or XML format. Some endpoints support HTML or vCard formatted responses. Sign up for a free account to get an API Key and get started.

API Key

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.

There are two methods to specify the API key in a request: 1. Specify it using the apiKey= query parameter; 2. specify the API key in the HTTP request header using an extended header field with name X-FullContact-APIKey.

The use of the HTTP header field rather than the apiKey query parameter 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 the logs of HTTP servers which process the requests.

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 Code Description
200 OK Your request processed successfully.
202 Accepted Your request is currently being processed. You can check again later to see the request has been processed.
400 Bad Request Your request was malformed.
403 Forbidden Your API key is invalid, missing, or has exceeded its quota. **Paid plans will not receive a 403 response when they exceed their alotted matches. They will only receive a 403 for exceeding rate limit quotas.
404 Not Found This person was searched in the past 24 hours and nothing was found.
405 Method Not Allowed You have queried the API with an unsupported HTTP method. Retry your query with either GET or POST.
410 Gone This resource cannot be found. You will receive this status code if you attempt to query our deprecated V1 endpoints.
422 Invalid Invalid or missing API query parameter.
500 Internal Server Error There was an unexpected error on our server. If you see this please contact support@fullcontact.com.

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:

Header Name Example Value Description
X-Rate-Limit-Limit 600 The rate limit ceiling for your request
X-Rate-Limit-Remaining 10 The number of requests left in the 60 second window.
X-Rate-Limit-Reset 20 The number of UTC epoch seconds remaining until the 60 second window resets
Thanks to Twitter and Github for this pattern.

Social Network Types

Below is a list of type ids for photos, socialProfiles, and icons returned by the person method.

Site typeId Site typeId
About.me aboutme Academia.edu academiaedu
Amplify amplify AngelList angellist
Aol Chat aolchat Bandcamp bandcamp
Bebo bebo Behance behance
BitBucket bitbucket BlipFM blipfm
Blippy blippy Blogger blogger
Crunchbase crunchbase DandyId dandyid
Delicious delicious Deviant Art deviantart
Digg digg Diigo diigo
Disqus disqus Do You Buzz doyoubuzz
Dribbble dribble eConsultancy econsultancy
Facebook facebook Facebook Chat facebookchat
Flavors.me flavorsme Flickr flickr
FourSquare foursquare FriendFeed friendfeed
Friendster friendster FullContact fullcontact
gdgt gdgt Get Glue getglue
Get Satisfaction getsatisfaction Gist gist
GitHub github Google Profile googleprofile
Google Plus googleplus Good Reads goodreads
Gravatar gravatar GTalk gtalkchat
Hacker News hackernews Hi5 hi5
Hunch hunch HypeMachine hypemachine
Hyves hyves ICQ icqchat
Identi.ca identica IMDB imdb
Intense Debate intensedebate IRC ircchat
Klout klout Lanyrd lanyrd
Last.FM lastfm LinkedIn linkedin
LiveJournal livejournal Meadiciona meadiciona
Meetup meetup Mixcloud mixcloud
Mixi mixi MySpace myspace
Ohloh ohloh Orkut orkut
Other other Pandora pandora
Picasa picasa Pin Board pinboard
Pinterest pinterest Plancast plancast
Plaxo plaxo Plurk plurk
Qik qik Quora quora
Reddit reddit Ren Ren renren
Reverb Nation reverbnation Scribd scribd
Shelfari shelfari Skype skype
SlideShare slideshare Smug Mug smugmug
Sound Cloud soundcloud StackExchange stackexchange
StackOverflow stackoverflow Steam steam
Stumble Upon stumbleupon Tagged tagged
Tripit tripit Tumblr tumblr
Twitter twitter Type Pad typepad
Vimeo vimeo VK vk
WordPress.com wordpress WordPress.org wordpress
Xing xing Yahoo! yahoo
Yahoo! Chat yahoochat Yelp yelp
YouTube youtube
Last modified: March 20 2014 11:03:06