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}