Add POST /companies/search (Preview)

[cox512]

Why?

Companies can be listed via the API but not searched. This adds a "Search companies" operation for parity with "Search contacts", letting integrators find companies by custom attributes.

How?

Adds the /companies/search POST operation to the Preview API description.

Companion PRs & merge order

This change spans three repos. Merge in this order:

1. intercom/intercom (monolith) — ships the behavior; must merge first -- https://github.com/intercom/intercom/pull/543548
2. This PR intercom/Intercom-OpenAPI (public spec)
3. intercom/developer-docs (reference + changelog): https://github.com/intercom/developer-docs/pull/1055

Merge #2 and #3 together, after this PR ships.

_{Generated with Claude Code}

[shrek-intercom]

✅ PR Review Summary: APPROVE

	Summary
✅	🎯 Problem — The PR clearly explains the problem (companies can be listed but not searched), the motivation (parity with contacts, enabling integrators to search by custom attributes), and provides helpful context about companion PRs across repos.
✅	📝 Alignment — The description accurately and completely matches the diff: only descriptions/0/api.intercom.io.yaml is modified, and exactly the claimed POST /companies/search operation is added with no phantom claims or omissions.
ℹ️	🧠 Correctness — Disabled for this repository.
✅	🦺 Safety — The change is purely additive, adding a single new POST /companies/search endpoint only to the Unstable/Preview tier spec without modifying any existing endpoints, schemas, or other files.
✅	🚦 Auto-approval — Within size limit (0/150 LOC).

Per-criterion details

Problem

Clear problem statement (companies can be listed but not searched), explains the why (parity with contacts, lets integrators find companies by custom attributes), and provides useful context about merge order for a multi-repo change. Concise and well-structured.

Alignment

The PR description claims to add a POST /companies/search operation to the Preview API description. The diff confirms exactly this:

1. File changed: descriptions/0/api.intercom.io.yaml — this is indeed the Preview API spec (version "0" is Preview per the repo's conventions documented in CLAUDE.md).

2. Operation added: The diff adds a /companies/search path with a post operation, summary "Search companies", operationId searchCompanies, tagged under "Companies". This matches the description's claim of adding a "Search companies" operation.

3. Parity with "Search contacts": The description mentions this is for parity with "Search contacts." The endpoint structure (POST with a search_request schema body, pagination, query operators) follows the pattern of a search endpoint, consistent with this claim.

4. Scope: The description says only the Preview API description is changed, and the diff only modifies descriptions/0/api.intercom.io.yaml. No other files are touched.

5. Companion PRs: The description mentions companion PRs in the monolith and developer-docs repos. This is contextual information about the broader change and doesn't conflict with anything in the diff.

There are no phantom claims, no significant omissions, and no scope mismatches. The description accurately and completely represents what the code change does.

Safety

This PR adds a single new POST /companies/search endpoint exclusively to descriptions/0/api.intercom.io.yaml — the Unstable/Preview tier spec. The change is purely additive: no lines are removed, no existing fields/endpoints are modified, and no other files are touched. The new endpoint follows existing conventions (references existing schemas like company_list, error, search_request; includes the standard Intercom-Version header parameter; provides response examples). It does not touch any released version specs, stable Fern overrides, scripts, CI/CD, or repo config.

<violated_criteria>
</violated_criteria>

_{Rate this comment 👍 / 👎 to help us improve 🙏 · Disagree with assessment? Establish ground truth here}

[zilleeizad-inter]

Went deeper on spec-internal consistency beyond what shrek-intercom checked (shrek explicitly disables correctness review for this repo). Two findings, both example/error-shape issues rather than structural problems — the diff parses fine and all $refs resolve.

[zilleeizad-inter]

[Medium] The 400 error example introduces code: invalid_field, which is used nowhere else in this spec. The established convention for "this value/field isn't valid" errors elsewhere in descriptions/0/api.intercom.io.yaml is code: parameter_invalid (26 occurrences) or, less commonly, code: bad_request (e.g. the dataset_id "is not a valid" example at line ~1801). invalid_field doesn't match either pattern.

Since Shrek's correctness check is disabled for this repo, this is worth a manual check against the actual response shape from the companion monolith PR (intercom/intercom#543548) before merge — if the real API returns parameter_invalid, this example will mislead SDK consumers and fail validation against real behavior. Also, the error schema has an optional field property ("used to identify a particular field... that was in error") that this example leaves unset even though the whole point of the example is a bad field name — populating field: segment_id would make it more complete and consistent with how the schema is meant to be used.

[zilleeizad-inter]

[Low] The request example sets pagination.per_page: 5, but the paired 200 response example (same successful example key) still shows per_page: 15 (the default) instead of 5. Compare with the sibling /contacts/search endpoint, where the request example's per_page: 5 matches the response example's per_page: 5 exactly. Minor, but example pairs that don't agree with each other can trip up doc generators/SDK snippet tooling that pair request/response examples by key.