Exploring the Contactually API

Contactually Overview

As a software professional I am interested in maintaining good relationships with my connections.    While I never thought to use a CRM for such a purpose, that just might change after coming across Contactually.



Contactually allows you to collect and merge contact information from various sources including e-mail, calendars and social networks (LinkedIn, Facebook, Twitter).   Contactually can help you with automatic reminders to follow-up with your connections, but that is just a small part of what the platform offers.  Some of the key features are centered around Buckets, Templates, Programs and Pipelines.

Buckets – Contacts are organized into named buckets which can be associated with specific accounts such as Gmail.   A contact can belong to multiple buckets.  Each bucket can be setup to prompt for follow-ups at certain intervals.

Templates – If you want to touch base with contacts periodically and find yourself saying the same thing, then an e-mail template is what you need.   Contactually will help you send e-mail using templates and even let you know if your message was opened.

Programs – This more advanced feature allows you to create a series of steps that are triggered to execute at a designated time.   You might for example create steps that issue reminders, send e-mail and add/follow on a social network.   A contact can only be associated with one program at a time.

Pipeline – If you are in sales (or perhaps recruiting) then you should definitely check out the Pipeline feature.  A Pipeline is broken into Stages with each Stage comprised of Deals.  One or more contacts can be associated with a Deal.  A Pipeline is great for letting you manage a process that can be described in a handful of discrete phases.

Contactually API

Contactually has a public API that is nicely documented at http://developers.contactually.com   It has a standard REST architecture and returns data in JSON format.

I decided to experiment with the API and create a simple app.  I published the project to GitHub at https://github.com/scottcarter/ContactuallySample.

The app allows you to retrieve your set of buckets from Contactually displayed in table view.  When you tap on a bucket, the list of contacts for that bucket is displayed in a new table view.


Universal Storyboard

This project was a good chance for me to use a Universal Storyboard which is new for Xcode 6 and iOS 8.   One storyboard can be used for an iPad and iPhone and the Split View Controller now supports both.

Caching using Core Data

ContactuallySample uses two instances of NSFetchedResultsController (one each for Master, Detail) along with Core Data.  When I fetch buckets or contacts using the API they are cached in Core Data.   The user can choose to manually reload contacts with a button on the navigation bar.

Perhaps a later version of the API might allow one to perform a check to see if any buckets or contacts have changed so that the sync can be automated.   I implemented such a feature in an app that I created – Contacts2Web.


I believe that OAuth is in the works for Contactually, but for now one can authenticate with a username/password or API Key (which can be obtained from the web site after login).   I chose the latter and added a pair of controllers to allow the user to copy/paste the API Key from a UIWebView and submit to the app via a textfield.   I store the API Key in the user’s keychain.

The lead controller of the pair, EnterApiKeyController, is presented modally after instantiating from the storyboard.


I connect to Contactually using NSURLSession.   Initially I was having some difficulties implementing a logout function  since I was using defaultSessionConfiguration and not clearing cookies!  This could have been handled by setting HTTPShouldSetCookies = NO, but instead I opted to use ephemeralSessionConfiguration instead which seemed more appropriate.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s