API v3 Compared to API v3.1

Our new API v3.1 builds upon the current API v3, but has new capabilities incorporated in order to allow you to get the data that you want in the most efficient manner possible. At a high level, enhancements included in v3.1 include:

New API v3.1 Features

More Refined Searches

When you query an entity, you're now able to specify exactly what results you want to see. Previously with v3, you'd see results for all relationships included in your query. Now you can customize your query to pull only the results that you want to see. For example, if you're only interested in funding rounds and investors of a company, you can specify this in your query to see only those results. To do this, just add the relationships you'd like to see the results for at the end of the query.

https://api.crunchbase.com/v3.1/organizations/facebook?relationships=funding_rounds,investors&user_key=INSERT_KEY_HERE

Batch Search Capabilities

A new batching endpoint will allow you to pass parameters for several query requests in a single HTTP call, and even specify the relationships for each query. Your queries will be processed in parallel and results will be returned sequentially in the original order. Once all requests have been completed, a consolidated response will be passed back to you and the HTTP connection will be closed. To leverage this, you can now call our batch endpoint:

http://api.crunchbase.com/v3.1/batch

Use an array of requests with the following parameters when calling the batch endpoint:

  • entity_type: any available type that has a collection (Organization, Person, Product, FundingRound, Acquisition, Ipo, Fund)
  • entity_uuid: UUID of corresponding entity
  • relationships: An array with the relationships name (string)
{"requests": [
  { "type": "<entity_type>", "uuid": "<entity_uuid>", "relationships": ["<relationship_name>"]}
]
}
{"requests":[
    { "type":"Organization","uuid":"df6628127f970b439d3e12f64f504fbb","relationships": ["investors","funding_rounds"]},
    { "type":"Organization","uuid":"fd80725f53fc70099878aeecf1e9ffbb","relationships": ["news","featured_team"]},
    { "type":"Organization","uuid":"902deab4ec4168ced9dfc0c959578176","relationships": ["investments","funds"]},
    { "type":"Person","uuid":"43b343a7ff56090a63fa5f833e55ea6d","relationships": ["primary_location","jobs","investments"]},
    { "type":"Product","uuid":"1767f73acc385927b66e51d1308d6c9d","relationships": ["owner","websites"]},
    { "type":"FundingRound","uuid":"08c74f1c6f8d9a2b95a095e61e558ccf","relationships": ["investments","investors","funded_organization"]},
    { "type":"Acquisition","uuid":"11cc4a63be13d7d3191c50bd2cd73a71","relationships": ["acquiree","acquirer","news"]},
    { "type":"Ipo","uuid":"bee91e2e4cfb70deb19d42e4bf991848","relationships": ["funded_company","news"]},
    { "type":"Fund","uuid":"a90b8ad0668ab1d2d5b4162277a3e6df","relationships": ["venture_firm","news"]}
    ]
}

Faster Pagination

Key set pagination will enable you to traverse our dataset faster. If you’re looking to extract all data results from a given endpoint, you will no longer have to paginate through the entire collection using the page number. We now provide pre-populated pagination URLs in your query results so that you can paginate through the collection efficiently as possible. Using page numbers to traverse a set can cause you to miss entities as the set changes while you paginate. Switching to keyset pagination guarantees that you will never miss an entity! As the set changes the keys remain constant so you can rely on the provided URLs never missing a beat.

In your query results, under the 'data' array, there will now be the following fields:

  • next_page_url
  • prev_page_url
  • key_set_url

For any queries that return more than 100 results and require pagination, the key_set_url will have the compiled version of the respective fast pagination, so if you continuously use the key_set_url for each page of the results, it will traverse through the collection until you reach the end of the results in which case it will return NULL.

Changes to the API

In the next section we list each endpoint with associated changes...

/organizations/

*As a note, some permalinks have changed in our migration process.

  <th>
    Field Name
  </th>

  <th>
    Changes in v3.1
  </th>
</tr>
  <td>
    api\_url
  </td>

  <td>
    new field that includes the full URL of the API endpoint
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    primary\_image
  </td>

  <td>
    UUID, created\_at, and updated\_at will all refer to the entity; height, width, and filesize have been deprecated, these fields will always return 'null'
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    board\_members\_and\_advisors
  </td>

  <td>
    only current board members and advisors will be returned
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    headquarters
  </td>

  <td>
    the following fields have been removed: region\_code2, country\_code2, country\_code3, latitude and longitude
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    offices
  </td>

  <td>
    will only return headquarters location, multiple office locations has been deprecated
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    products
  </td>

  <td>
    product data has been deprecated, this field will always return an empty array
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    funding\_rounds
  </td>

  <td>
    the investments nodes which appear within relationships will no longer include copies of the funding\_round and  funding\_organization nodes.  the investments will contain a new node for partners.
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    investments
  </td>

  <td>
    within relationships we have added two nodes invested\_in and partners; invested\_in represents the company raising funds and partners represents the people at this organization who are responsible for the funding round
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    acquisition
  </td>

  <td>
    only the acquiree is returned in the response as the acquirer is implied
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    competitors
  </td>

  <td>
    competitor data has been deprecated, this field will always return an empty array
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    customers
  </td>

  <td>
    customer data has been deprecated, this field will always return an empty array
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    memberships
  </td>

  <td>
    membership data has been deprecated, this field will always return an empty array
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    members
  </td>

  <td>
    membership data has been deprecated, this field will always return an empty array
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    websites
  </td>

  <td>
    will only return 4 results: homepage, facebook, twitter, and linkedin; UUID, created\_at, and updated\_at will all refer to the entity; blogs have been deprecated, these fields will always return 'null'
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    images
  </td>

  <td>
    duplicates primary\_images field, support for multiple images has been deprecated
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    videos
  </td>

  <td>
    video data has been deprecated, this field will always return an empty array
  </td>
</tr>
Item
field

/people/

*As a note, some permalinks have changed in our migration process.

  <th>
    Field Name
  </th>

  <th>
    Changes in v3.1
  </th>
</tr>
  <td>
    api\_url
  </td>

  <td>
    new field that includes the full URL of the API endpoint
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    primary\_image
  </td>

  <td>
    UUID, created\_at, and updated\_at will all refer to the entity; height, width, and filesize have been deprecated, these fields will always return 'null'
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    advisory\_roles
  </td>

  <td>
    only current board members and advisors will be returned
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    investments
  </td>

  <td>
    within relationships we have added two nodes invested\_in and partners; invested\_in represents the company raising funds and partners represents the people at this organization who are responsible for the funding round
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    memberships
  </td>

  <td>
    membership data has been deprecated, this field will always return an empty array
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    websites
  </td>

  <td>
    will only return 4 results: homepage, facebook, twitter, and linkedin; UUID, created\_at, and updated\_at will all refer to the entity; blogs have been deprecated, these fields will always return 'null'
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    images
  </td>

  <td>
    duplicates primary\_images field, support for multiple images has been deprecated
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    videos
  </td>

  <td>
    video data has been deprecated, this field will always return an empty array
  </td>
</tr>
Item
field

/products

  <th>
    Field Name
  </th>

  <th>
    Changes in v3.1
  </th>
</tr>
  <td>

  </td>

  <td>
    product data has been deprecated, this field will always return an empty array
  </td>
</tr>
Item
collection

/ipos/

  <th>
    Field Name
  </th>

  <th>
    Changes in v3.1
  </th>
</tr>
  <td>
    api\_url
  </td>

  <td>
    new field that includes the full URL of the API endpoint
  </td>
</tr>

<tr>
  <td>
    field
  </td>

  <td>
    shares\_sold
  </td>

  <td>
    shares sold data has been deprecated, this field will always return an empty array
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    stock\_exchange
  </td>

  <td>
    UUID, created\_at, and updated\_at will all refer to the entity
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    websites
  </td>

  <td>
    will only return 4 results: homepage, facebook, twitter, and linkedin; UUID, created\_at, and updated\_at will all refer to the entity; blogs have been deprecated, these fields will always return 'null'
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    images
  </td>

  <td>
    duplicates primary\_images field, support for multiple images has been deprecated
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    videos
  </td>

  <td>
    video data has been deprecated, this field will always return an empty array
  </td>
</tr>
Item
field

/funds/

  <th>
    Field Name
  </th>

  <th>
    Changes in v3.1
  </th>
</tr>
  <td>
    investors
  </td>

  <td>
    the investors node will contain a list of investors in the fund.  today, the investors node always returns an empty array.
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    websites
  </td>

  <td>
    will only return 4 results: homepage, facebook, twitter, and linkedin; UUID, created\_at, and updated\_at will all refer to the entity; blogs have been deprecated, these fields will always return 'null'
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    images
  </td>

  <td>
    duplicates primary\_images field, support for multiple images has been deprecated
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    videos
  </td>

  <td>
    video data has been deprecated, this field will always return an empty array
  </td>
</tr>
Item
relationship

/funding-rounds/

  <th>
    Field Name
  </th>

  <th>
    Changes in v3.1
  </th>
</tr>
  <td>
    investments
  </td>

  <td>
    the investments nodes which appear within relationships will no longer include copies of the funding\_round and  funding\_organization nodes.  the investments will contain a new node for partners.
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    websites
  </td>

  <td>
    will only return 4 results: homepage, facebook, twitter, and linkedin; UUID, created\_at, and updated\_at will all refer to the entity; blogs have been deprecated, these fields will always return 'null'
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    images
  </td>

  <td>
    duplicates primary\_images field, support for multiple images has been deprecated
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    videos
  </td>

  <td>
    video data has been deprecated, this field will always return an empty array
  </td>
</tr>
Item
relationship

/acquisitions/

  <th>
    Field Name
  </th>

  <th>
    Changes in v3.1
  </th>
</tr>
  <td>
    images
  </td>

  <td>
    duplicates primary\_images field, support for multiple images has been deprecated
  </td>
</tr>

<tr>
  <td>
    relationship
  </td>

  <td>
    videos
  </td>

  <td>
    video data has been deprecated, this field will always return an empty array
  </td>
</tr>
Item
relationship

/locations

  <th>
    Field Name
  </th>

  <th>
    Changes in v3.1
  </th>
</tr>
  <td>
    region\_code2
  </td>

  <td>
    will be 'NULL' unless the location\_type is region (previously was always filled)
  </td>
</tr>

<tr>
  <td>
    field
  </td>

  <td>
    country\_code2
  </td>

  <td>
    will be 'NULL' unless the location\_type is country (previously was always filled)
  </td>
</tr>
Item
field

/categories

  <th>
    Field Name
  </th>

  <th>
    Changes in v3.1
  </th>
</tr>
  <td>
    organizations\_in\_category
  </td>

  <td>
    field has been deprecated and will always return 'NULL'
  </td>
</tr>

<tr>
  <td>
    field
  </td>

  <td>
    products\_in\_category
  </td>

  <td>
    field has been deprecated and will always return 'NULL'
  </td>
</tr>
Item
field

Changes to the CSV Exports

In addition to changes to the REST API, there will be some changes to our CSV exports.

*Formatting Changes: Category_list is now delimitated by a comma "," instead of a pipe "|"

  <th>
    Field Name
  </th>

  <th>
    Changes in v3.1
  </th>
</tr>
  <td>
    registration\_details, start\_time, end\_time, venue\_address, and cost
  </td>

  <td>
    These fields have been deprecated.
  </td>
</tr>

<tr>
  <td>
    funding\_rounds.csv
  </td>

  <td>
    funding\_round\_type, funding\_round\_code, investment\_type
  </td>

  <td>
    funding\_round\_type and funding\_round\_code has been deprecated. investment\_type is a composite of those two fields.
  </td>
</tr>

<tr>
  <td>
    funds.csv
  </td>

  <td>
    started\_on
  </td>

  <td>
    started\_on data has been deprecated.
  </td>
</tr>

<tr>
  <td>
    has\_competitor.csv
  </td>

  <td>
    all
  </td>

  <td>
    Competitor data has been deprecated.
  </td>
</tr>

<tr>
  <td>
    has\_customer.csv
  </td>

  <td>
    all
  </td>

  <td>
    Customer data has been deprecated.
  </td>
</tr>

<tr>
  <td>
    investors.csv
  </td>

  <td>
    category\_list, investor\_list, profile\_image\_url
  </td>

  <td>
    These fields have been deprecated.
  </td>
</tr>

<tr>
  <td>
    jobs.csv
  </td>

  <td>
    is\_advisor, is\_executive, job\_type
  </td>

  <td>
    The job\_type field is a replacement for is\_advisor and is\_executive.
  </td>
</tr>

<tr>
  <td>
    organizations.csv
  </td>

  <td>
    logo\_url, profile\_image\_url,\
    roles, aliases, first\_funding\_on, zip\_code
  </td>

  <td>
    Sizing parameters have been removed from the logo\_url. profile\_image\_url, first\_funding\_on, zip\_code have been deprecated. roles will now describe all roles and entity can fulfill (e.g. \{'investor, company, school'}). aliases is now an array data type.
  </td>
</tr>

<tr>
  <td>
    people.csv
  </td>

  <td>
    logo\_url, profile\_image\_url
  </td>

  <td>
    Sizing parameters have been removed from the logo\_url. profile\_image\_url has been deprecated.
  </td>
</tr>

<tr>
  <td>
    products.csv
  </td>

  <td>
    all
  </td>

  <td>
    Product data has been deprecated and CSV will be removed.
  </td>
</tr>

<tr>
  <td>
    schools.csv
  </td>

  <td>
    all
  </td>

  <td>
    School data is now reflected in the organizations.csv and schools.csv will be removed.
  </td>
</tr>
CSV File
events.csv