One of the benefits of building a modern JavaScript web application is that not only do you get an API for free, but also that the API has been tried and tested — you've eaten your own dog food so to speak.

In Sourcing.io, the frontend interface is a JavaScript web application which communicates with a backend JSON API. Today we're documenting that API, and opening up support to third party integration.

In fact, a number of companies are already using this API. Help Scout are using it to display developer's Sourcing profiles inside their application, and a few businesses are using it with their company newsletters, adding a job ad if the recipient is a software developer.

Getting started

The API endpoint is https://api.sourcing.io. All requests should be made over SSL. All request and response bodies are encoded in JSON.

Authentication is done via the API key which you can find in your account settings. Either pass it as an authorization query parameter, or as a bearer token in an Authorization header.

curl "https://api.sourcing.io/v1/people/email/[email protected]" \
        -H "Authorization: Bearer {key}"

Fetching people by email

The main endpoint is looking people up by their email address. We also support retrieving people by their Twitter or GitHub handles, but that's beyond the scope of this post.

The endpoint is GET /v1/people/email/{email}

For example:

curl "https://api.sourcing.io/v1/people/email/[email protected]" \
        -H "Authorization: Bearer {key}"

Will respond with:

{
   "id": "ac598534-010f-4f4e-947d-ef3dd3dee92b",
   "slug": "elliott-kember",
   "name": "Elliott Kember",
   "first_name": "Elliott",
   "last_name": "Kember",
   "email": "[email protected]",
   "url": "http://www.elliottkember.com",
   "score": 12.8,
   "headline": "JavaScript developer at Riot",
   "bio": "Glue-sniffing freelance kite designer",
   "twitter": "elliottkember",
   "twitter_id": 903351,
   "twitter_followers_count": 6310,
   "github": "elliottkember",
   "github_followers_count": 102,
   "linkedin": null,
   "facebook": "elliottkember",
   "languages": [
      "JavaScript",
      "Objective-C"
   ],
   "location": "Bath, Bath and North East Somerset, UK",
   "company_name": "Riot",
   "gravatar_id": "165ef5b4e31389ddf104f93e790bea13",
   "avatar_url": "https://secure.gravatar.com/avatar/165ef5b4e31389ddf104f93e790bea13",
   "hireable": null,
   "gems_count": 0,
   "packages_count": 0,
   "geocode_city": "Bath",
   "geocode_state": "England",
   "geocode_country": "GB",
   "connected": true,
   "twitter_connected": true,
   "favourited_users": [],
   "twitter_follower_users": [],
   "twitter_following_users": [],
   "twitter_mutual_users": [
      {
         "id": "b686d8e1-7f19-4d0c-85d4-14b8f9ad304d",
         "abbrev": "Alex M.",
         "name": "Alex MacCaw",
         "first_name": "Alex",
         "last_name": "MacCaw",
         "email": "[email protected]",
         "gravatar_id": "31e3bc3db733babac648c8521737fb51",
         "twitter_connected": true,
         "facebook_connected": true,
         "linkedin_connected": false,
         "github_connected": true
      }
   ],
   "linkedin_users": [],
   "facebook_users": [],
   "favorite": true,
   "repos": [
      {
         "name": "the-sexy-curls-jquery-plugin",
         "full_name": "elliottkember/the-sexy-curls-jquery-plugin",
         "description": "A page-turning plugin for jQuery",
         "language": "JavaScript",
         "watchers_count": 149,
         "forks_count": 26
      }
   ],
   "packages": [],
   "gems": []
}

Client bindings

As well as the raw REST API, we have a RubyGem client library. Either install the sourcing gem or if you're using Bundler add it to your Gemfile.

Sourcing.api_key = ENV['SOURCING_KEY']

person = Sourcing::Person[email: '[email protected]']

The gem also includes a sourcing executable, which you can use like this:

$ sourcing --twitter DanielZarick

    {
      "id" => "7baccc21-36a7-436c-8d55-e3d15b61dbdf",
      "name" => "Daniel Zarick",
      "headline" => "Developer at 33cc77",
      "url" => "http://danielzarick.com",
      ...

Patches welcome

Let us know how you end up using the API, and if you have any features or endpoints you'd like us to add — we're excited to see what people end up building with it!