Need Help? Support

Friends

These endpoints are depricated and will be disabled on August 5. (read more)

Developers should implement Singly Health Data Fabic, a fault-tolerant, schedulable system that pushes unified data from any apps or devices your users have authenticated, directly to your database.

Request access to Health Data Fabric

We are committed to make the transition smooth for current users, so if this will be an issue for you, please don't hesitate to contact us.

Overview

There are many common patterns for apps around friends including inviting them in to try the app, choosing specific ones to share to, and getting notified when a friend starts using the same app. The source of the data to make any of those experiences really great and seamless is diverse and difficult to work with, so we've built an API to offer the best-of-class friend features atop any data source.

The /friends/* endpoints are all normalized to a simple common format and will merge and de-duplicate contacts together from any of these sources (and features):

  • Facebook (interactions, activity, photos, location)
  • Twitter (interactions, activity, photos, location)
  • Linkedin (activity)
  • Google Contacts (phone, email)
  • Gmail (email, activity, interactions)
  • Mobile Address Book (phone, email)
  • Instagram (interactions, activity, photos, location)
  • Foursquare (interactions, activity, location)
  • Github (email)
  • Tumblr (interactions, activity)
  • Flickr (activity, photos, location)
  • Yammer (interactions, activity)
  • Klout
  • Need more? Just ask!

General

To merge friends from all contacts for all services connected to the given token:

GET `/friends/:group`

The different groups are:

  • all all friends from all services
  • facebook and twitter etc, any service name can be used to just return friends from that service
  • peers friends that are also using the same app
  • ios or android for any uploaded from a mobile device address book
  • more on the way in the roadmap (below) of friended invited and blocked

Common query parameters include:

  • limit is the number of results with a max of 20 (optimized for faster+smaller results for mobile usage and dynamic/progressive loading)
  • offset where to start into the list of friends
  • services is a comma delimited list of which services to reduce the list to, as a way to get just specific ones merged, like "services=facebook,linkedin"
  • full when set to true will return the full original profile data from the services (and is very verbose!)

Sorting

All of the groups have powerful sorting built in to enable the app to present the best possible list to the person depending on the situation.

The query parameter of sort supports the values of:

  • first (default)
  • last name
  • connected is how many services that friend is connected through, someone you're connected to on many networks sorts to the top

Table of Contents

If the parameter toc is set to true the returned array will always contain an extra entry, the first one, that is a special object containing a table of contents.

It works best when used for first and last name sorting, where this object has each letter of the alphabet as a key with the value being the offset where that letter starts, enabling a way to jump around quickly within large friends lists. Sometimes friends names don't have a letter (some twitter accounts, tumblr blogs, etc) and they will be grouped in *. A meta value has the totals for the whole set.

Here's an example:

GET /friends/all?toc=true

Searching

As-you-type style searching that will match the first or last name, email, or handle of any friend is available with the q parameter. Passing in progressive j then je then jer will return matching results for each step, refining closer each way.

Full text searching of a friends biographic information is available with the bio parameter. The requested value will be matched against profile description fields (like on twitter) as well as company and organization names in work and education history.

Peers

The special group /friends/peers will return just the friends that are also using the same app, as detected by whatever social networks they are friended via, and if that friend had connected any of those networks to their account on the app.

Any friend result for any group that is also a peer will always have the "peer":"account-id" key value pair set, containing the id of that peer's account within the app so that it can be used by the app as a key to enable additional features.

This also works for mobile address books, where as soon as they're sync'd, anyone using the app who is in the address book will have their peering status set. All peering is bi-directional, it's enabled for both accounts as soon as it's detected.

It's on the roadmap to generate notifications to the app whenever a new peering relationship is formed, to create friendly reminder emails of friends becoming active in the app and push notifications to mobile as well.

Discovery

To see how many friends exist in total and a breakdown by grouping:

GET `/friends`

Mobile Contacts

Mobile apps can sync their local address books to have those contacts included in the friends lists, dedup'd and merged with the rest, as well as enable the peering status detection to find friends using the same app. If you're using our iOS or Android SDKs they already will do this work on request so that your app doesn't have to.

To do this, they can POST a JSON array with the header of Content-Type: application/json included to /friends/ios or /friends/android (or other device specific namespace), and the array must contain objects with the format of:

{"id":"1234", "phone":"4242424269", "email":"jer@singly.com", "name":"Jeremie Miller"}

They can also contain a "phones":[] and "emails":[] that have a list of phone numbers or email addresses per contact (in addition to or in lieu of the single values). The contacts will be immediately included merged in /friends/all. The id value should be the one used on the device, so that any changes can be uploaded again and will just replace the existing one of the same id.

Very importantly, one contact must have a "self":true set on it to signify that it is the owner of the device and account, as those values will be used to detect the peering relationship for matching them in other app user's address books.

Roadmap

New groups and statuses on any friend, mutable anytime by the app!

  • friended just those who have been saved as friends within the app
  • invited friends that have been invited
  • blocked anyone that should be disabled or treated specially

Other features (some mentioned above)

  • Simple utility to send an invitation to a friend across any network (or choose the best)
  • Notification after a first-time auth or connect as soon as the newly added friends are included (usually seconds, but need easier methods than polling)
  • Having notifications when a friend changes states (starts using the app, accepts an invite, etc).
  • Location searching.
  • Interest-based filtering options (sports, health, games, etc)
  • Role-based filters (family, co-workers, brands/companies)
  • App-wide "suggested friends" recommendation features