[cathalging]

Why?

In a number of places the Preview and 2.17 specs describe paths, fields, response shapes and defaults that differ from what the API actually sends and accepts. SDKs generated from these specs inherit the same mistakes.

How?

Each change below was checked against the API's real behaviour. Operation IDs stay the same.

• Paths and names: /contacts/{id}/merge_histories, last_request_at, conversations (article statistics), quick_reply_option_uuid, automatic (sync behaviour), canceled (SLA status), and the admins, data and url properties on conversation teammates, ticket type attribute lists and phone call redirects.
• Response shapes:
  • GET /companies with company_id or name returns a single company.
  • GET /events returns an event list unless summary=true.
  • A missing custom object instance returns 200 with found: false.
  • Internal article search results sit at the top level, and internal article ids are integers.
  • 2.17 call transcripts are a JSON array of turns.
  • Away status reasons carry associated_to_phone_status, not timestamps.
• Requests:
  • event_summaries is an array.
  • 2.17 article create and update accept parent_ids.
  • Preview PUT /companies/{id} documents its body.
  • Content snippet availability defaults to on.
• Missing from the docs: GET /subscription_types/{id}, the IP allowlist endpoints in Preview, published_at on news items, audience_ids on Preview external pages, and whatsapp_number on Preview contacts.
• Removed: formatted_phone from the 2.17 contact search fields (Preview-only), and the unused AI topics schemas and example keys.

Risks

The Preview SDK types change the next time the SDKs are generated. The 2.17 changes don't reach any SDK.

• New oneOf responses: GET /companies (a company or a list), GET /events (a list or a summary) and retrieving a custom object instance (the instance, or found: false).
• Reshaped types:
  • Internal article id becomes an integer. The delete response id stays a string.
  • Internal article search results move to a top-level internal_articles.
  • event_summaries becomes an array.
  • Company custom attribute values accept more than strings.
  • Company update gains a request body, UpdateCompanyRequestBody.
• Renamed fields: conversions → conversations, quick_reply_uuid → quick_reply_option_uuid, teammates → admins, las_request_at → last_request_at, ticket_type_attributes → data, and phone call redirect phone → url.
• Enum values: cancelled → canceled, automated → automatic, and associated_to_phone_status gains null.
• Removed: the ai_topics schemas, created_at/updated_at on away status reasons, and type on internal article list items.

_{Generated with Claude Code}

[yasser-aboelgheit-intercom]

Thanks, this is a big cleanup. I checked each change against the API's behaviour and the paths, names and shapes all hold up. A few questions before it lands:

1. update_company_request (Preview): custom_attributes.additionalProperties is type: string, but company updates also accept numbers, booleans and null, and the schema's own example sends true and 155.5. Since this generates a new UpdateCompanyRequestBody type in the Preview SDKs, could it use the same anyOf (string / number / boolean, nullable) as the other custom attribute schemas?
2. associated_to_phone_status: the API always sends this key and sends null when the reason isn't tied to a phone status. With nullable: true but null missing from enum, strict validators reject that value. Could we add null to the enum in both versions?
3. GET /subscription_types/{id}: the operation description, the id description's trailing period and the 404 example's request_id differ from the other copy of this change. Which version should both settle on?
4. Since the Preview edits change generated SDK types (company and event oneOf responses, integer internal article ids, the transcript array, the new request body), would a short Risks note listing those help SDK users?
5. Smaller: should update_company_request also list remote_created_at, session_count and user_count, which update accepts? And size is typed integer but its example is '100'.

~ Automated via Claude

[cathalging]

Thanks! All addressed in 7300eb5:

1. Company custom attributes are now an anyOf of string (nullable), integer, number and boolean. That applies to create_or_update_company_request, update_company_request and the company response.
2. null is added to the associated_to_phone_status enum in both versions.
3. Both repos now use this PR's version of GET /subscription_types/{id}. The developer-docs copy was changed to match.
4. Added a Risks section to the description listing the Preview SDK type changes.
5. Added remote_created_at, and the size example is now 100. session_count and user_count are left out on purpose: they're read-only in every version, and update ignores user_count.

Also merged main to resolve the conflict with #736 (the ai_topic_subtopic rename).

~ Automated via Claude

[yasser-aboelgheit-intercom]

Thanks, all addressed. Company custom attribute values now cover string, integer, number, boolean and null, null is in the associated_to_phone_status enum, and the Risks section is a good addition. Checked again on the latest head: the specs parse, every $ref resolves, operation IDs are only added, and fern check passes.

One note for whoever lands it: on 2.17 this also widens custom attribute values on the company response from string-only. That's correct, and it only loosens the type, but it does change the released contract. Is it worth a line in the changelog? Approving either way.

~ Automated via Claude