[cathalging]

Why?

Several API changes and smaller gaps never reached the 2.17 and Preview descriptions.

How?

Adds the missing Preview fields and operations, and in both versions adds the external page tag operations and corrects a few errors, examples and limits.

Risks

Preview types reach the generated SDKs. Most changes are new operations and new optional fields, but some existing types get stricter: ticket attribute values on create, update and change type must be strings, numbers, booleans, or arrays of integers or strings, and the Fin Voice call vendor_internal_id gains a 191-character limit.

_{Generated with Claude Code}

[markdennis22]

Mirrors my review on intercom/developer-docs#1311: the Fin Tasks 400 examples need to change before merge, plus a question and a nit inline.

Small drift from the docs PR: the per_page example summary says "above 250" here and "greater than 250" there, and the Fin Tasks 401s are written out here but use the shared Unauthorized response in the docs PR. Worth making them match so the next copy doesn't churn.

~ Automated via Claude

[markdennis22]

I don't think this 400 can happen today. The Fin Tasks controller raises its validation errors with a plain string, and the API error handler crashes reading that error's message, so the request ends as a 500. The controller's own spec expects a 500 for the segment_ids cases (spec/controllers/api/v3/fin/tasks_controller_spec.rb). The same goes for the two update examples and the Fin access check on create.

Could we drop these 400 examples until team-actions fix the controller? Its unused validation helper renders a 422, so the final status may not be 400 either. The 400 that does work today is parameter_missing when title is left out.

[markdennis22]

Same as the create example: both of these come back as a 500 today. Separately, update can also return a 403 permission_denied ("Missing required permission: ...") when the teammate is missing a permission, which isn't documented here.

[markdennis22]

Was dropping "any other value is treated as descending" deliberate? It's still how ticket search behaves: an unknown order value silently sorts newest first. Only contacts search rejects it, and the comment there says tickets and conversations keep the fallback on purpose. Without the sentence, someone sending asc gets descending results with no hint why. The same edit is in 2.17.

[markdennis22]

Nit: this schema and change_ticket_type_request got the markup sentence but not the array guidance and item types the shared ticket attributes schema got, so the Preview SDK ends up stricter on create than on update. Worth adding the same two sentences here, or pointing both at the shared schema?

[cathalging]

Thanks. Addressed in d0052e4, matching the docs PR:

• The Fin Tasks error examples now cover only the documented 400s, and the update description says to send title and description together.
• The ticket update and change-type request schemas have the same value types as the create schema, and the Risks paragraph now names all three.
• The per_page summary and the Fin Tasks 401s match the docs PR.

~ Automated via Claude

[markdennis22]

Re-checked against intercom master. The Fin Tasks examples now match what the API returns, including the case you found where title and description must both be sent. The ticket update and change-type schemas now match the shared one, and the two PRs now match each other exactly. I agree on the 403: the CC permission check only fires when a save adds a new address, and an API update can't add one. LGTM.

~ Automated via Claude