Build and track pipeline with Crunchbase’s new HubSpot integration | LEARN MORE

Crunchbase API v2.0 Released

Today, we (finally) released version 2.0 of the Crunchbase API.

We originally released the 2.0 API into beta on May 3rd to gather feedback from the developer community. The response has been fantastic; over 1,800 developers have signed-up, and we’ve received a ton of feedback on both format and features.

Today’s release is about completing the foundation of the 2.0 API. We planned to release 2.0 on March 26th, and we missed that by a country mile. This extra time has, however, enabled us to incorporate significantly more feedback and produce a very solid foundation.

Our go-forward goal is to release only additive, non-breaking changes to the API. We know that changing even the smallest detail can wreak havoc on existing applications, and our goal is to make the API as stable as possible.

API Roadmap

Today’s release is just the beginning. We’re pleased to have finalized the foundation of the 2.0 API. We also know there is huge demand for additional API functionality.

Our developer community has been wonderfully supportive and very articulate in which features are most important. It’s this input that is guiding the following API priorities:

Search

By far, the most-requested API feature is search. Developers want to be able to search both the API generally and individual collections specifically. The priorities we’ve heard are as follows:

  1. General API Search
    • Name
    • Location(s)
  2. Organization Search / Filter
    • Name
    • Domain Name
    • Location(s)
    • Category / Categories
    • Type (e.g., company, investor, etc.)
  3. Person Search / Filter
    • Name
    • Location(s)
    • Organization Name + Job Title
  4. Product
    • Name
    • Organization
    • Category / Categories

We’re already working on the first two (General API and Organization search) and will share timing with the community as soon as we can. We recognize that these particular features are very important to the community and have prioritized them amongst everything else we’re doing at Crunchbase appropriately.

Documentation

Our documentation of the API at https://developer.crunchbase.com/docs is most definitely an MVP and needs a lot of time and attention. We do recognize that what we have is not sufficient to explain how to truly understand, interpret, or leverage the API, and we’re working to make it better.

Whereas it won’t happen overnight, we’re committed to making the API documentation both complete and first class, with annotated response examples and, ultimately, code samples.

v2.0 Changes

In finalizing the 2.0 API, we have released a number of changes, a few of which are, in fact, “breaking” changes that deviate from the 2.0 beta API. The changes are as follows:

created_at, updated_at

In the 2.0 beta API, we supported ordering the collections endpoints by created_at or updated_at, but we omitted the actual values of those properties. To some degree, this negated the value of sorting.

A common use case is wanting to get every Organization that has changed since the last time the /organizations endpoint was queried. In the 2.0 beta API, one could sort by updated_at DESC but without the updated_at property on every Organization, there was no way to compare an Organization’s update time with your last query time.

With today’s release, we’ve added created_at and updated_at to every item in the API (including related items such as Categories in detail endpoints). These two properties are exposed as Unix Timestamps.

An example is in this snippet from the Facebook detail:

data: {
  uuid: "df6628127f970b439d3e12f64f504fbb",
  type: "Organization",
  properties: {
    permalink: "facebook",
    homepage_url: "https://facebook.com",
    name: "Facebook",
    created_at: 1180153335,
    updated_at: 1401089687,
    ...
  }
},
...

Denormalized / Flattened Data on Organizations

Many members of the developer community asked that we pull some key data up to the “properties” level of the Organization Detail. Specifically, developers asked for the following:

  • Total Funding
  • Number of Investments
  • Number of Employees
  • Stock Exchange
  • Stock Symbol

Again using the Facebook detail as an example, these properties now appear as follows:

data: {
  uuid: "df6628127f970b439d3e12f64f504fbb",
  type: "Organization",
  properties: {
    permalink: "facebook",
    homepage_url: "https://facebook.com",
    name: "Facebook",
    created_at: 1180153335,
    updated_at: 1401089687,
    total_funding_usd: 2385000000,
    number_of_investments: 3,
    stock_symbol: "FB",
    stock_exchange: "NASDAQ",
    number_of_employees: 5299
  }
},
...

Please note that the Total Funding property is “total_funding_usd”. Funding is always converted to USD and exposed in this property.

New Relationships on Organization Detail

A number of developers also wrote in to request that we add two additional relationships to the Organization Detail endpoint, exposing both the Past Team and the Board Members and Advisors.

Both of those relationships are now exposed (when present) in the Organization Detail and share the data structure of the existing current_team relationship.

A snippet of the past_team from Facebook is as follows:

past_team: {
  paging: {
    total_items: 175,
    first_page_url: "https://qa2.crunchbase.com/v/2/organization/facebook/past_team",
    sort_order: "created_at DESC"
  },
  items: [
    {
      first_name: "Dustin",
      last_name: "Moskovitz",
      title: "Co-Founder",
      started_on: null,
      ended_on: null,
      path: "person/dustin-moskovitz",
      created_at: 1180156505,
      updated_at: 1398010588
    },
    {
      first_name: "Matt",
      last_name: "Cohler",
      title: "VP of Product Management",
      started_on: null,
      ended_on: null,
      path: "person/matt-cohler",
      created_at: 1180156619,
      updated_at: 1398010404
    },
    ...
  ]
},
...

Categories

When a developer requests an Organization or Product Detail, part of the response is a list of Categories. These Categories appear in a relationship called “categories”. In the  2.0 beta API, the type of these items was “Market” and there was no unique identifier for individual Categories. An example is as follows:

categories: {
  paging: {
    total_items: 7,
    first_page_url: "https://api.crunchbase.com/v/2/organization/facebook/categories",
    sort_order: "created_at DESC"
  },
  items: [
    {
      type: "Market",
      name: "Networking",
      created_at: 1397980728,
      updated_at: 1397980728
    },
    {
      type: "Market",
      name: "Communities",
      created_at: 1397980728,
      updated_at: 1397980728
    },
    ...
  ]
},

This was both inconsistent with the front-end (where the word “Market” is not used) and was not forward-looking, as developers need a way to uniquely identify our Categories and store/relate them, both for relationships amongst Categories but also as we expose searching by Category.

To that end, we’ve changed the “type” property to “Category” and added the Category’s “uuid” (unique identifier). An example of the revised categories section is as follows:

categories: {
  paging: {
    total_items: 7,
    first_page_url: "https://api.crunchbase.com/v/2/organization/facebook/categories",
    sort_order: "created_at DESC"
  },
  items: [
    {
      type: "Category",
      name: "Networking",
      uuid: "cdf763fe4af9fc9e6ab9d51df5ee18c9",
      created_at: 1397980728,
      updated_at: 1397980728
    },
    {
      type: "Category",
      name: "Communities",
      uuid: "bc4ee7e1d4a1c228c55129d716ba971f",
      created_at: 1397980728,
      updated_at: 1397980728
    },
    ...
  ]
},

Person Location Identifier

Every Person in Crunchbase can optionally be attached to a Location (at the City level). In the 2.0 beta API, we initially did not expose this property, then later exposed a location_id property.

To ensure consistency across the API, we’re changed the name of this ID property to location_uuid. This will prove important as we move forward with searching and filtering by location.

And example snippet (from my own Person Detail) is as follows:

data: {
  uuid: "320210c6d721415db14e52d49ea4dc12",
  type: "Person",
  properties: {
    ...
    permalink: "kurt-freytag",
    ...
    location_uuid: "528f5e3c90d111115d1c2e4ff979d58e",
    created_at: 1400700329,
    updated_at: 1400700329
},
...

Person Degrees & Experience

In the 2.0 beta API, both a Person’s Degrees and Experience relationships had the name of the Organization at which the person studied / worked, but it did not expose the path to that Organization Detail. We corrected that and added organization_path to both relationships.

An example of the new payload response (for my own degrees) is as follows:

degrees: {
  paging: {
    total_items: 1,
    first_page_url: "https://api.crunchbase.com/v/2/person/kurt-freytag/degrees",
    sort_order: "created_at DESC"
  },
  items: [
    {
      started_on: "1989-01-01",
      completed_on: "1993-01-01",
      degree_type_name: "BA",
      degree_subject: "International Relations",
      type: "Degree",
      organization_name: "Stanford University",
      organization_path: "organization/stanford-university"
    }
  ]
},
...

Feedback

The feedback from our developer community up to this point has been fantastically helpful. Please keep it coming. We want to know what works and what doesn’t work to make this API as useful as possible for everyone leveraging Crunchbase data.

Email us at api@crunchbase.com.

Learn more about the API or sign up for a key at https://developer.crunchbase.com.

  • Originally published June 24, 2014