Search API basics

Use the Search API to find entities that match criteria. This page explains how to adapt a query; for a complete first search, follow Find companies with the Search API.

Request structure

Send a POST request to https://api.crunchbase.com/v4/data/searches/{collection}, replacing {collection} with a supported collection such as organizations. Collections, fields, and operators depend on your licensed package; use its API Reference.

Authenticate with your provisioned key in the X-cb-user-key header. Send JSON with Content-Type: application/json and request JSON with Accept: application/json. See authentication setup.

This example body searches organizations classified as SaaS, returns their identifiers and descriptions, and sorts by organization rank:

{
  "field_ids": ["identifier", "short_description"],
  "query": [
    {
      "type": "predicate",
      "field_id": "categories",
      "operator_id": "includes",
      "values": ["5c4e6926-5ff7-b188-0892-c8eb036c5ace"]
    }
  ],
  "order": [{"field_id": "rank_org", "sort": "asc"}],
  "limit": 3
}

The UUID identifies the SaaS category. The walkthrough’s filter-selection step shows how to discover and verify it with Autocomplete. This is a request body for POST /v4/data/searches/organizations, not a complete terminal command.

Select fields separately from filters

field_ids controls the data returned. query controls which entities match. Adding website_url to field_ids requests that field; it does not restrict the results to organizations with a website.

Use the selected endpoint’s request schema to find supported field IDs, filter fields, and operators. Use its response schema to understand each returned value’s shape. A field available for output is not automatically supported for filtering or sorting.

Request only the fields you need. Treat optional values as optional: an omitted field is not equivalent to zero, false, or an empty relationship. HTTP 200 alone does not confirm that every requested field was returned.

Build a predicate

Each predicate identifies a field, an operator, and its input values:

Do not assume the same operator or value format works across all fields. Identifier filters may require UUIDs, while dates, numbers, and monetary values have their own formats. Check the endpoint schema before substituting values.

For category and location criteria, use Autocomplete and inspect the suggested entity’s type, name, permalink, and description. Resolve ambiguous matches before using an identifier.

Combining filters: AND and OR

Separate predicates in query are combined with AND: every predicate must match. A SaaS category predicate plus a San Francisco headquarters predicate means SaaS and headquartered in that location.

Within a predicate, the operator determines how multiple values are matched:

• includes, where supported, matches any listed value. Two category UUIDs mean either category.
• includes_all, where supported, requires all listed values.

Do not assume every operator treats its values as alternatives. For example, the values for a range operator describe a range rather than independent alternatives.

For OR across separate predicates, make separate searches, paginate each as needed, combine the results, and remove duplicates by entity UUID. Do not add an unsupported OR wrapper to the query array.

Sort and size the results

Each order entry specifies a supported field_id and sort: "asc" or sort: "desc". The example uses ascending rank_org, so lower organization-rank values come first. The sort schema also supports nulls: "first" or nulls: "last" for positioning missing values.

Set an explicit order when your workflow depends on it; do not interpret an unspecified order as a recommendation or a stable ranking. Sorting does not freeze the dataset.

limit sets a page size, not the total number of matching entities. A page of three results is not a complete market list. Request additional pages when needed.

Read the response

Search returns an entities array. For each result:

Here, i is the array index. Check that the array contains an item before reading it. Unlike Autocomplete, Search places the requested fields inside properties.

An empty entities array means this request returned no results. A missing or malformed array is a response problem to investigate, not an empty result set.

To enrich a match, pass its UUID to the appropriate Entity Lookup endpoint. Request cards there; card_ids is not part of this Search request body. The walkthrough demonstrates the handoff and checks that the returned UUID matches.

Paginate through results

For forward pagination, use the last returned entity’s uuid as after_id in the next request body. Keep the query, fields, order, and limit unchanged. Do not send before_id and after_id together.

Follow Paginate search results for the complete loop, stopping conditions, duplicate handling, and repeated-cursor checks.

Pagination does not provide a transactional snapshot across requests. Records can change during traversal; follow the pagination guide’s reconciliation guidance.

Diagnose a query

• Invalid filter or request: inspect the response message and verify the field, operator, value type, and JSON syntax against your package’s endpoint schema.
• No matches: confirm the identifiers and test predicates individually to isolate the restriction. Restore the intended criteria before reporting results.
• Missing fields: check exact field names and package availability. Preserve unknown values rather than inferring business facts.
• Authentication, access, throttling, or transient errors: follow authentication, limits, and retry guidance. Repeating an invalid query unchanged will not repair it.

Related guides

• Find companies with the Search API — a complete search-to-lookup walkthrough.
• Search API examples — additional query examples.
• Paginate search results — retrieve further pages reliably.