Troubleshooting and FAQs

Use this page to diagnose a request or clarify common data questions. For a working baseline, follow Make your first API request. Authentication, request limits, and retry behavior are maintained in API essentials.

Diagnose a failed request

Start with the HTTP status and response body, not just your client's error message. In cURL, add --include to display the response headers before the JSON body. In the interactive reference, inspect the live response after clicking Try It!.

If the cause is unclear, try the minimal organization lookup from the first-request guide with the same key. A successful baseline confirms that the key works for that request; it does not establish access to every collection, field, or card.

Why did a successful request return no matches?

For Search, an HTTP 200 response with entities: [] means that request returned no matching records. It is different from an error response.

• On the first page: check the collection and filters. Predicates in the query are combined with AND; adding another condition can remove every match. Start with fewer conditions, and verify category or location identifiers before using them.
• On a later page: an empty entities array is the stopping condition. Keep the filters and ordering unchanged throughout the traversal. See Search pagination.
• For name matching: use Autocomplete to find candidates and compare their identity. Do not treat the first suggestion as a guaranteed match.

Why is a field or card missing from an HTTP 200 response?

A successful status does not guarantee that every requested field or card will appear. Check the following before interpreting an omission:

1. Selection: organization properties use field_ids; embedded related records use card_ids. A single-card endpoint uses card_field_ids for fields on its records.
2. Spelling and availability: compare the IDs with the reference for your licensed package. An unknown field can be omitted without producing an HTTP error.
3. The returned data: inspect the actual response and compare it with a known working example. An omitted value, null, zero, and an empty list are different states; do not convert them all to zero or assume an omitted card proves there are no related records.

See Entity Lookup for field and card selection. If a valid, licensed selection is still absent and the meaning matters to your application, ask your account team to clarify the specific case.

What should I include when asking for help?

Send your account team the endpoint and method, request timestamp with timezone, HTTP status, response error body, and the relevant parameters or JSON body. Include your API package and a minimal reproduction when possible. If the response provides a request identifier, include it.

Never include your API key. Remove it from headers, URLs, screenshots, logs, and copied commands. Include only the data needed to reproduce the issue.

How can I effectively search for companies using their name, especially when they're from the same country or when I have their address or website?

To search for companies more effectively, consider using the /data/searches/organizations endpoint with the location_identifiers and website_url fields. If you're primarily searching by name, the autocompletes endpoint remains the recommended method.

Can you explain the concept of card_id?

A card_id identifies a related-data section on an entity, such as the founders card on an organization. The card contains related records; it is not an organization property selected with field_ids. To retrieve more detail about a founder, take that founder record's identifier UUID and use it in a person lookup. You are following the related person's UUID, not a UUID for the card itself.

For a complete example, follow Understand the Crunchbase data model.

How can I search for all funds within a specific country, especially when I can't use the location_identifier field in the /data/searches/funds endpoint?

The Fund schema does not provide a directly searchable location field. First decide whether you mean the fund's domicile or the headquarters of the organization that manages it; these are different concepts. To find funds associated with an organization, use the Fund owner_identifier field with organization identifiers from a separate organization search, where supported by your package. This identifies funds by their owner, not their legal domicile. See the Fund search reference for available filters. Searching /data/searches/funding_rounds by funded_organization_location instead returns funding rounds by the funded company's location; it does not return funds by country.

How can I filter companies based on their type, such as “company”, “investor”, or “school”?

To filter companies based on their type, you can use the facet_ids field. For instance, to search for companies with an “investor” facet, include the following predicate in your search query: { "type": "predicate", "field_id": "facet_ids", "operator_id": "includes", "values": ["investor"] }. It's worth noting that this field type is enum_multi and the possible values for organizations are company, government_entity, investor, and school. See the facet_ids enumeration in the Organization reference.

Does the organization.updated_at property get updated when a funding round is added to an organization? Additionally, what exactly does updated_at represent?

No. organization.updated_at tracks changes to fields stored directly on the organization, such as its name or description. It does not provide a timestamp for every change to related or derived data.

For example, organization funding data is derived from funding-round entities. Adding or updating a funding round does not guarantee a change to organization.updated_at; funding rounds have their own updated_at fields.

For incremental synchronization, track updates in the relevant source entity collections as well as organizations. Do not rely on organization.updated_at alone to detect changes to data derived from other entities.

How do I accurately identify a company when multiple companies share the same name? Would the domain be the best identifier?

Use the website domain to find candidate organizations, not as a guaranteed unique identifier. Search /data/searches/organizations using the website_url field and the domain_eq operator. A domain search can return multiple organization records, including records that share the same website URL or use subdomains.

Compare the candidates' names, locations, descriptions, and company context to select the intended organization. Do not assume that the first result is the correct match; if the available information is insufficient, retain the ambiguity for review.

Once you have selected the correct organization, store its UUID and use that UUID for subsequent entity lookups.