At FullContact, we believe that having great API documentation is just as important has having a great API. Think about it: what good is a powerful API if no one understands how to use it?
Without well designed docs, even RESTful APIs like ours can be difficult to use. In tandem with the release of our Version 2 FullContact API, we’ve spent that past few weeks improving our FullContact API docs with a brand new design, new navigation, more detailed information, and a live FullContact API console.
FullContact Version 2 API Docs
We’ve also added tags to each section of the documentation, indicating whether an endpoint is free or paid. Currently all of our endpoints are free to use except for the Person endpoint, which provides enhanced contact information based on an email address or Twitter name.
The documentation for each endpoint begins with a high-level overview, describing the basic functionality, input parameters, and responses. Example API requests are provided for each response format, including JSON, XML, HTML, and vCard.
The parameters section contains descriptions of each available input parameter for a given endpoint. For example, the Person method requires that either an email address, twitter name, or phone number is submitted as input. Other parameters, such as webhookUrl, timeoutSeconds, queue, and callback are optional, and should only be used in certain contexts.
Example API responses are provided for each response format as well. Click the pill-shaped tabs across the top of the Responses table to toggle between JSON, XML, HTML, and vCard formats.
Live API Console
Our new Live API Console makes it easy to test the FullContact API methods right from within your browser. Once you’ve signed up for a free API key, navigate to the Live API Console page, follow the directions below the console, and start using the FullContact API endpoints immediately. We suggest you open the FullContact API docs in one browser window and the API console in another, so you can reference the docs while you make live test calls to the API.
Once a request is successfully made, you’ll be able to inspect the raw HTTP request and response data from tabs within the console.
Over the coming weeks we will continue to update and enhance our API docs. We’ll also be rolling out blog posts describing how to use our new endpoints. If you have any feedback or suggestions email me at firstname.lastname@example.org, and whatever you do, don’t be a grin fucker.