What's new in API v4.0?
Overview
Crunchbase’s new API, version 4, delivers a brand new experience with refined search and filtering capabilities, improved performance, and access to new fields in parity with CSV v4.
- Tailor your search to view only the data you’re looking for
- Leverage increased reliability and speeds up to 10x faster
- Simplify operations with consistent data across formats
Alongside the familiar entities and expanded data fields, there may be some changes to how you access that data. This document details the various enhancements and changes to expect when using the new API (tentative GA date - Q2, 2020).
Key Highlights
Search for items within the API
Previously, API users would have to go through every item in the result and identify the ones of interest (e.g. “companies in SF”) in post-processing. Now, users can retrieve a much more specific list of results by providing the desired search filter criteria in the body of the Search API’s request.
POST https://api.crunchbase.com/api/v4/searches/organizations?user_key=INSERT_KEY_HERE
--Body Request--
{
"field_ids": [
"identifier",
"categories",
"location_identifiers",
"short_description",
"rank_org_company"
],
"order": [
{
"field_id": "rank_org_company",
"sort": "asc"
}
],
"query": [
{
"type": "predicate",
"field_id": "funding_total",
"operator_id": "between",
"values": [
{
"value": 1000000,
"currency": "usd"
},
{
"value": 10000000,
"currency": "usd"
}
]
},
{
"type": "predicate",
"field_id": "facet_ids",
"operator_id": "includes",
"values": ["company","investor"]
}
],
"limit": 10
}
curl --request POST 'https://api.crunchbase.com/api/v4/searches/organizations?user_key=INSERT_KEY_HERE' \
--header 'Content-Type: application/json' \
--data-raw '{
"field_ids": [
"identifier",
"categories",
"location_identifiers",
"short_description",
"rank_org_company"
],
"order": [
{
"field_id": "rank_org_company",
"sort": "asc"
}
],
"query": [
{
"type": "predicate",
"field_id": "funding_total",
"operator_id": "between",
"values": [
{
"value": 1000000,
"currency": "usd"
},
{
"value": 10000000,
"currency": "usd"
}
]
},
{
"type": "predicate",
"field_id": "facet_ids",
"operator_id": "includes",
"values": ["company","investor"]
}
],
"limit": 10
}'
Fetch only the data fields you need
For each item you request, you can now specify exactly the data fields and relationships that you need for increased efficiency. If only one field matters to you, you can set up your call so that each item in the response will only contain that one field. This is available in both the Entity Lookup API and Search API.
GET https://api.crunchbase.com/api/v4/entities/funding_rounds/crunchbase-series-c--020173ab?field_ids=announced_on,investment_type,money_raised,name,num_investors&card_ids=investors,press_references&user_key=INSERT_KEY_HERE
curl --request GET 'https://api.crunchbase.com/api/v4/entities/funding_rounds/crunchbase-series-c--020173ab?field_ids=announced_on,investment_type,money_raised,name,num_investors&card_ids=investors,press_references&user_key=INSERT_KEY_HERE'
Search deeper into a collection with equal performance
API 4.0 now uses keyset pagination to retrieve the next set of results. This means you will no longer face the performance deprivation that would occur paginating deep into a collection using API 3.1.
Keyset pagination also enables users to utilize our Search API - instead of CSV - to pull down all the data from a single entity type. Learn more about how to paginate your Search API response here
Simplify operations with data parity
All fields available in the CSV 4.0 are now available in API 4.0 to keep workflows seamless.
Because API 4.0 is rebuilt on the Crunchbase Platform, it also leverages the same backend and subsequent data updates as crunchbase.com. This gives API 4.0 data parity with Crunchbase Pro, excluding Marketplace partner data.
Improve performance and reliability today and tomorrow
Because API 4.0 is the Crunchbase Graph, we can assure that API 4.0 is more reliable and provides a faster and more consistent experience than the previous API 3.1.
Furthermore, future performance and platform enhancements that come to the Crunchbase Graph will be automatically available to the API 4.0 as well.
Leverage fully specified responses
Our API documentation includes a formal OpenAPI Specification (OAS 3.0).
This enables our customers to take advantage of the OAS ecosystem, helping to speed their integration and development.
For more details on OpenAPI and how it can benefit your development - read more here.
Use Cases API 4.0 Can Help Support
In the next section, we list out some common use cases that API 4.0 can support and provide some example for illustrative purposes.
Enrich specific data
With the new API 4.0, you have two different ways to enrich your database with the specific data you’re looking for: Entity Lookup API or Search API.
Using the Entity Lookup API
With the Entity Lookup API (e.g. /entities/organizations/{entity_id}), you can request information for a specific entity (e.g. Airbnb) and specify which data fields and relationships are returned.
Here is an example of how you can get founders, funding rounds, and general company information (e.g. categories and short description) for an Organization entity called "Crunchbase":
GET https://api.crunchbase.com/api/v4/entities/organizations/crunchbase?card_ids=[founders,raised_funding_rounds]&field_ids=[categories,short_description,rank_org_company]&user_key=INSERT_KEY_HERE
curl --request GET 'https://api.crunchbase.com/api/v4/entities/organizations/crunchbase?card_ids=[founders,raised_funding_rounds]&field_ids=[categories,short_description,rank_org_company]&user_key=INSERT_KEY_HERE'
Using the Search API
If you do not need relationship information, you can also use our Search API to retrieve data fields for multiple entities.
Here is an example of how you can get the data fields that you want for multiple investor profiles using the Search API endpoint for Principal with the facet_ids = “investor”
- Note: by using the principal search endpoint, we can search across both Organization and Person profiles as investors can be both.
In the below example, we are interested in finding investor information for 6 specific investors: Mayfield Fund, Emergence, Cowbooy Ventures, OMERS Ventures, Felicis Ventures, and Verizon Ventures.
POST https://api.crunchbase.com/api/v4/searches/principals?user_key=INSERT_KEY_HERE
--Body Request--
{
"field_ids": [
"identifier",
"location_identifiers",
"categories",
"investor_stage",
"investor_type",
"short_description",
"num_investments_funding_rounds",
"num_exits",
"rank_principal_investor"
],
"order": [
{
"field_id": "num_exits",
"sort": "asc"
}
],
"query": [
{
"type": "predicate",
"field_id": "identifier",
"operator_id": "includes",
"values": [
"3213cd7d-06e0-3ecb-3359-29aa8deddfa6",
"cc964bc0-a950-4d8f-4ef0-7c514e49d28a",
"0ea85f02-96e1-5c42-feeb-b786ecab2939",
"74b0e4ff-d6f2-fc71-625e-2d0781b8e3b4",
"735a53c6-a7ba-2434-d97d-b788536da89d",
"bfbcbd33-72c6-9635-8f4a-f61c0d08c03e"
]
},
{
"type": "predicate",
"field_id": "facet_ids",
"operator_id": "includes",
"values": ["investor"]
}
]
}
curl --request POST 'https://api.crunchbase.com/api/v4/searches/principals?user_key=INSERT_KEY_HERE' \
--header 'Content-Type: application/json' \
--data-raw '{
"field_ids": [
"identifier",
"location_identifiers",
"categories",
"investor_stage",
"investor_type",
"short_description",
"num_investments_funding_rounds",
"num_exits",
"rank_principal_investor"
],
"order": [
{
"field_id": "num_exits",
"sort": "asc"
}
],
"query": [
{
"type": "predicate",
"field_id": "identifier",
"operator_id": "includes",
"values": [
"3213cd7d-06e0-3ecb-3359-29aa8deddfa6",
"cc964bc0-a950-4d8f-4ef0-7c514e49d28a",
"0ea85f02-96e1-5c42-feeb-b786ecab2939",
"74b0e4ff-d6f2-fc71-625e-2d0781b8e3b4",
"735a53c6-a7ba-2434-d97d-b788536da89d",
"bfbcbd33-72c6-9635-8f4a-f61c0d08c03e"
]
},
{
"type": "predicate",
"field_id": "facet_ids",
"operator_id": "includes",
"values": ["investor"]
}
]
}'
POST https://api.crunchbase.com/api/v4/searches/principals?user_key=INSERT_KEY_HERE
--Body Request--
{
"field_ids": [
"identifier",
"location_identifiers",
"categories",
"investor_stage",
"investor_type",
"short_description",
"num_investments_funding_rounds",
"num_exits",
"rank_principal_investor"
],
"order": [
{
"field_id": "num_exits",
"sort": "asc"
}
],
"query": [
{
"type": "predicate",
"field_id": "identifier",
"operator_id": "includes",
"values": [
"omers-ventures",
"cowboy-ventures",
"verizon-ventures",
"emergence-capital-partners",
"felicis-ventures",
"mayfield-fund"
]
},
{
"type": "predicate",
"field_id": "facet_ids",
"operator_id": "includes",
"values": ["investor"]
}
]
}
curl --request POST 'https://api.crunchbase.com/api/v4/searches/principals?user_key=INSERT_KEY_HERE' \
--header 'Content-Type: application/json' \
--data-raw '{
"field_ids": [
"identifier",
"location_identifiers",
"categories",
"investor_stage",
"investor_type",
"short_description",
"num_investments_funding_rounds",
"num_exits",
"rank_principal_investor"
],
"order": [
{
"field_id": "num_exits",
"sort": "asc"
}
],
"query": [
{
"type": "predicate",
"field_id": "identifier",
"operator_id": "includes",
"values": [
"omers-ventures",
"cowboy-ventures",
"verizon-ventures",
"emergence-capital-partners",
"felicis-ventures",
"mayfield-fund"
]
},
{
"type": "predicate",
"field_id": "facet_ids",
"operator_id": "includes",
"values": ["investor"]
}
]
}'
Prospect for Companies
The prospecting power of Crunchbase Pro is now available in API 4.0 via our new Search API (e.g. /searches/organizations). With the Search API, you can now define a specific search criteria in the request body to return only the entities that match your search criteria.
Here is an example of the API request to get a list of Biotech companies that have a number of employees between 101 and 500.
POST https://api.crunchbase.com/api/v4/searches/organizations?user_key=INSERT_KEY_HERE
--Body Request--
{
"field_ids": [
"identifier",
"categories",
"short_description",
"rank_org_company"
],
"query": [
{
"type": "predicate",
"field_id": "num_employees_enum",
"operator_id": "includes",
"values": [
"c_00101_00250",
"c_00251_00500"
]
},
{
"type": "predicate",
"field_id": "categories",
"operator_id": "includes",
"values": [
"58842728-7ab9-5bd1-bb67-e8e55f6520a0"
]
},
{
"type": "predicate",
"field_id": "facet_ids",
"operator_id": "includes",
"values": ["company"]
}
]
}
curl --request POST 'https://api.crunchbase.com/api/v4/searches/organizations?user_key=INSERT_KEY_HERE' \
--header 'Content-Type: application/json' \
--data-raw '{
"field_ids": [
"identifier",
"categories",
"short_description",
"rank_org_company"
],
"query": [
{
"type": "predicate",
"field_id": "num_employees_enum",
"operator_id": "includes",
"values": [
"c_00101_00250",
"c_00251_00500"
]
},
{
"type": "predicate",
"field_id": "categories",
"operator_id": "includes",
"values": [
"58842728-7ab9-5bd1-bb67-e8e55f6520a0"
]
},
{
"type": "predicate",
"field_id": "facet_ids",
"operator_id": "includes",
"values": ["company"]
}
]
}'
Ingest all Crunchbase data within a collection
With API 4.0, you now have the option to ingest all of our data via the API by using a combination of keyset pagination and the Search API. (Note: if you prefer to ingest our data via a CSV, you can still do so with our CSV endpoint.)
Here is an example of the API request to get funding rounds after 2018, sorted in descending order based on their announced date. You can then paginate to the next set of results using keyset pagination.
POST https://api.crunchbase.com/api/v4/searches/funding_rounds?user_key=INSERT_KEY_HERE
--Body Request--
{
"field_ids": [
"identifier",
"announced_on",
"funded_organization_identifier",
"money_raised",
"investment_type"
],
"order": [
{
"field_id": "announced_on",
"sort": "desc"
}
],
"query": [
{
"type": "predicate",
"field_id": "announced_on",
"operator_id": "gte",
"values": [
"2018"
]
}
],
"limit": 100,
"after_id": "f6a0e67a-b0a2-4fb8-9783-46530f4baf6f"
}
curl --request POST 'https://api.crunchbase.com/api/v4/searches/funding_rounds?user_key=INSERT_KEY_HERE' \
--header 'Content-Type: application/json' \
--data-raw '{
"field_ids": [
"identifier",
"announced_on",
"funded_organization_identifier",
"money_raised",
"investment_type"
],
"order": [
{
"field_id": "announced_on",
"sort": "desc"
}
],
"query": [
{
"type": "predicate",
"field_id": "announced_on",
"operator_id": "gte",
"values": [
"2018"
]
}
],
"limit": 100,
"after_id": "f6a0e67a-b0a2-4fb8-9783-46530f4baf6f"
}'
Differences
Base URL Change
Base URL is now https://api.crunchbase.com/api/v4 instead of api.crunchbase.com/v3.1/.
HTTPS requirement
Https is now required to be used to call our endpoints.
Deprecated data removal
Data that was deprecated in the API 3.0 to API 3.1 migration will be completely removed from API 4.0. Since API 4.0 is a new design, we will no longer show relationships and fields that are tied to deprecated data.
Here are some examples:
- “products” relationship
- “customers” relationship
- “memberships” relationship
- “members” relationship
- “videos” relationship
Collection endpoints replaced with Search endpoints
Previously, the Collection endpoints (e.g. /organizations) could be used to retrieve the entire set and core properties of many entity types within Crunchbase. However, this method only returned 100 items per page, degraded in performance as the collection went deeper, didn’t allow search criteria to filter the results, and offered limited ways to sort the results.
In API 4.0, Search endpoints (e.g. /searches/organizations) allow you to do the same thing as Collection endpoints, but more. You can now get up to 1000 items per page and the performance remains consistent as you query further into the collection. You can also apply additional search criteria to narrow down your results (e.g. only Organizations in San Francisco) and sort the results with great greater flexibility (e.g. sorted organizations by their founded date in descending order).
Find more details in the Using the API page.
Entity Lookup endpoints available, but changed
Entity Lookup endpoints are still available in API 4.0, but there are three differences:
1) There is slight change to the URL of the endpoint
- instead of /organization/{permalink}, the Entity Lookup URL is now /entities/organizations/{entity_id}
2) Both permalink and uuid can be used to query for an entity
- e.g. to look up Kleiner Perkins, you can use both “kleiner-perkins-caufield-byers” or “2d0a5bf0-e53e-9a07-2243-9bcd561421ec”
3) The API request needs to specify the data fields and relationships that should be returned in the API response
- In the previous version of the API, the response always returns a defined set of data fields and relationships, which makes the response size heavy and inefficient if you only need a few fields.
- In API 4.0, you will need to always specify the data fields and relationships you want in the API request. This means ONLY the data that you want & need will ever be returned.
Find more details in the Using the API page.
Naming changes from API 3.1
One of the benefits of API 4.0 is that it is powered by the same data platform that powers crunchbase.com and Crunchbase Pro, so any data points you see there will be available in API 4.0 (assuming you have the right access permission). However, that also means the name of entity type, relationship, and fields may be different from API 3.1.
Below are some examples of naming differences:
- Entity Type
“news” → “press_references”
new entity type
“category_group”
“Event”
“OrganizationSummary” → removed
“PeopleSummary” → removed - Field
** Funding round’s “funding_type” → Funding round’s “investment_type”
Batch endpoint support
In API 4.0, there will no longer be support for a batch endpoint. Instead, we suggest using the Search API endpoint to retrieve data fields for multiple items from a collection (e.g. Organizations). If relationship information is needed, we suggest using the Entity Lookup endpoint to retrieve the information for each entity of interest.
Updated 5 months ago