Dovkie
Sign in
Back to monitors

intercom

Intercom REST API

REST
OpenAPI (YAML)
https://raw.githubusercontent.com/intercom/Intercom-OpenAPI/main/descriptions/2.15/api.intercom.io.yaml
Breaking AI classification

merge_contacts_request fields 'from' and 'into' are now required

The merge_contacts_request schema now marks from and into as required fields. Clients that previously omitted either field (relying on them being optional) will now fail schema validation. This affects any integration that merges contacts without explicitly providing both identifiers.

Alert history

  • Breaking

    merge_contacts_request fields 'from' and 'into' are now required

    The merge_contacts_request schema now marks from and into as required fields. Clients that previously omitted either field (relying on them being optional) will now fail schema validation. This affects any integration that merges contacts without explicitly providing both identifiers.

  • Informational

    Clarify timestamp field search behavior across timezones

    Documentation updated to clarify that Contact Search timestamp field queries are interpreted using the workspace's timezone rather than UTC, which can cause different results across workspaces. This is informational documentation explaining existing behavior, not a functional API change.

  • Informational

    Reorganize export API under new "Reporting Data Export" tag

    The OpenAPI specification reorganized four export-related endpoints under a new Reporting Data Export tag (replacing the generic Export tag). A new tag definition was also added with documentation and a help article link. This is purely a documentation/organizational change with no impact on API behavior or functionality.

  • Additive

    Away status reasons endpoint now returns structured list

    The GET request to retrieve away status reasons now returns a wrapped response object with type and data fields instead of a raw array. A new away_status_reason_list schema was introduced to structure the response as {type: "list", data: [array of away_status_reason objects]}. This change ensures consistency with other Intercom list endpoints and properly encapsulates the list metadata.

  • Additive

    Add audience_ids support to content import sources

    The Intercom API adds optional audience_ids field to content import source objects and a new optional apply_audience_to_existing_content parameter for updates. These are purely additive changes — the new fields are optional and nullable, so existing clients will continue to work without modification. The changes enable customers to associate and manage audiences with content import sources.

  • Informational

    Clarified subscription endpoint response behavior

    Added clarification to the subscriptions endpoint documentation explaining that it only returns subscriptions where the contact has explicitly configured their preference, and excludes subscriptions in default state. This is documentation-only and does not change the actual API behavior.

  • Informational

    Clarify date range constraints on message event timestamps

    Updated descriptions for 11 message event timestamp fields to clarify that only events within the export job's requested date range are counted. This is a documentation clarification that does not change the API's behavior or contract—it explains existing behavior more clearly to help customers understand timestamp filtering in export operations.

  • Additive

    Add GET /conversations/{id}/handling_events endpoint

    New endpoint GET /conversations/{id}/handling_events added to list pause/resume events for conversations, along with supporting schema definitions (handling_event, handling_event_list, and teammate_reference). This is a purely additive change that cannot break existing integrations.

  • Informational

    Documentation update: bot email reply behavior clarification

    The POST /conversations/{id}/reply endpoint description now includes a warning admonition explaining that bot or Operator replies to inbound email conversations are not sent to customers by default—they're stored as unnotifiable bot comments. This is a documentation clarification with no changes to API behaviour, parameters, or response structure.

  • Additive

    Allow boolean values in custom attribute schema

    The custom attribute value field schema now accepts boolean type in addition to the existing string, integer, and array types. This is purely additive—existing integrations continue to work, and clients can now optionally send boolean values for custom attributes.

  • Additive

    Support for Intercom API v2.15

    The intercom_version parameter now includes 2.15 as a valid enum value, with the default version updated from 2.14 to 2.15. This is purely additive — existing integrations using earlier versions will continue to work.

  • Breaking

    PUT /conversations/{id} now returns 400 on duplicate custom attribute names

    The PUT /conversations/{id} endpoint now returns a 400 INVALID_PARAMETER error when the request body includes custom_attributes and the workspace has multiple non-archived conversation custom attributes sharing the same name. Previously, the request would silently succeed by applying the update to a non-deterministic attribute. Clients that rely on the old silent-success behaviour will now receive an error and must resolve duplicate attribute names in workspace settings before retrying.

  • Informational

    Clarify timestamp format in contact field descriptions

    Updated documentation for multiple timestamp fields on contact objects to explicitly state they are Unix timestamps in seconds (rather than just "UNIX timestamp"). This clarification helps developers understand the exact time unit for fields like created_at, updated_at, signed_up_at, and several others, but does not change the actual API behavior or response format.

  • Informational

    Clarified detachContactFromConversation operation docs

    Updated the description and warning section for the detachContactFromConversation operation to clarify that it removes (rather than adds) contacts from group conversations and cannot remove the last participant. This is a documentation correction that does not change the API's actual behaviour—it makes the docs more accurate.

  • Additive

    Add ai_sales_agent_availability response field

    The response schema now includes a new optional ai_sales_agent_availability boolean field that indicates whether an external page can be used to answer questions by AI Sales Agent. This is a purely additive change that does not break existing integrations.

  • Additive

    Add hide_csat_from_agents_setting_change activity type

    A new enum value hide_csat_from_agents_setting_change has been added to the activity type list in the Intercom REST API. This is a purely additive change that allows clients to handle a new workspace setting activity type without breaking existing integrations.