Looking for the FullContact Address Book App? You can now find it at Contacts+

Learn More

Developing Our Next Generation API

Written By:
Kory Cunningham

A big focus for us here at FullContact is our next generation APIs, including the release of our new Enrich API. As we continue to push the envelope and provide new and powerful capabilities, one important factor we are constantly evaluating and improving is the end-to-end experience for the developers consuming the FullContact API. In this post, I’d like to take you through a few examples of how our focus on developer experience surfaces itself through the design and capabilities of our next generation APIs.

Consistent structure of inputs and outputs

One of the biggest differences many developers will notice about our new API is that we’re moving away from a REST-style API and more towards an RPC model. Along with this, we’ve also made a significant change in how we accept query criteria when retrieving profiles. As mentioned in a previous blog post, “Our new Enrich API is a departure for us, in all the right ways,” our Enrich API supports sending multiple query elements, rather than just one. While that by itself is a significant advancement, how those query elements are sent to the API highlights a new, core concept in our API – the Person Summary object.

The Person Summary object is a JSON string that is used to submit data to our API, with keys for information such as a contact’s email address, phone number, or other information.  It is also sent back as the response when retrieving the data – letting you, as the developer, provide whatever data you have about a profile, and the FullContact API to “fill in the blanks” with any additional data that we have available, all in a consistent structure. For example, we can send a Person Summary object for our CEO and Co-Founder, Bart:


twitter”: “@bartlorang”,
fullName”: “Bart Lorang


In this example, we’re including two queryable pieces of information, Bart’s email address and his twitter handle, along with additional data that details Bart’s full name. When sent to our new Enrich API, we will use this object to locate any additional data we have about Bart, and we’ll return a Person Summary object that looks like this:


email“: “bart@fullcontact.com“,
emailHash“: “d77ff8a9f4d2d4fea4153c81ba5d39a2“,
twitter“: “@bartlorang“,
phone“: “+13035551234“,
fullName“: “Bart Lorang“,
ageRange“: “30-39“,
gender“: “Male“,
location“: “Denver, CO, United States“,
title“: “Co-Founder & CEO“,
organization“: “FullContact, Inc.“,
linkedin“: “https://www.linkedin.com/in/bartlorang“,
facebook“: “https://www.facebook.com/bart.lorang“,
bio“: “CEO & Co-Founder of @FullContact, Managing Director @v1vc_. Tech Entrepreneur, Investor. Husband to @parkerbenson and Father to Greyson Lorang“,
avatar“: “https://d2ojpxxtu63wzl.cloudfront.net/static/a7e6a5aba590d4933e35eaadabd97fd2_44e00e968ac57725a15b32f9ca714827aff8e4818d290cb0c611f2e2585253b3“,
website“: “https://www.fullcontact.com/bart“,
details“: {}


Notice that we’re returning back the same Person Summary structure, but now populated with the additional data we could find relevant to Bart’s profile.

By utilizing this new Person Summary object, we now have an API that provides a consistent developer experience when sending and retrieving data. While the example shown here is just the Enrich API, you’ll see this same Person Summary object in use in other endpoints coming soon.

Up-To-Date Data with Data Subscriptions

Our data asset is constantly evolving as new and updated profile information becomes available. People change jobs, update work titles, change their social profiles and more, and it makes sense that you want your application to always leverage the latest data for a given profile. In previous versions of the FullContact API, this could be accomplished, but often meant re-querying for the same profile on-demand or developing potentially complex logic and code to periodically poll on a per-profile basis. With the next generation of our API, we’ve helped solve this through Data Subscriptions.

In short, data subscriptions can be thought of as long-living webhooks – if you are unfamiliar with webhooks, take a look at another one of our blog posts, The Beginner’s Guide to Webhooks. With the latest version of our API, you can subscribe to a given profile by submitting a Person Summary object, along with a webhook URL. Any time FullContact has new or updated information about that profile, we’ll send that information to the providing webhook URL. We’ll continue to send updates for each profile until you unsubscribe.

By leveraging the new data subscriptions capabilities, you can forget about building complex logic or code to poll for updated information, and instead let FullContact notify your system as soon as we have any updates.

Configurable Responses with Data Packs

Our API provides a lot of valuable information for a given profile, such as name, location, social profiles, affinities, and more. And while valuable, we recognize that not every developer uses every piece of data that is available for a profile and that some portions of the profile are more important than others. Constraints such as bandwidth and connection speed make it important to limit the data being sent across the network. To improve this experience, we’re introducing Data Packs to enable you to configure your API response to return only the categories of data you’re interested in.

All API responses will come back with the Person Summary object, containing basic information available such as full name, current title and organization, etc. Maybe you would also like to receive a list of all of the known social profiles for that contact, we have a Data Pack for that. Want to retrieve affinity data as well? There’s a Data Pack for that too! Data Packs provide a means to let you pick and choose the categories of data you want to receive, letting you customize the response to return the data you’re interested in, and leave everything else out.

We’re Just Getting Started With Our Next Generation API

As a developer, your experience working with our API is very important to us. We’re building our next generation platform with that experience in mind. However, we’re only just getting started. There is a lot more we have in the works, but we need your help! We take your feedback seriously and fold it into everything we do at FullContact. It helps to shape our roadmap and platform capabilities. We’d love to hear what you have to say, so please reach out and make your voice heard.

Recent Posts