intercom · steve-henry · Nov 12, 2025 · Nov 7, 2025 · Nov 10, 2025 · levindixon
diff --git a/README.md b/README.md
@@ -1,15 +1,73 @@
-# Intercom's REST API OpenAPI Description
+# Intercom REST API OpenAPI Description
-# Intercom REST API OpenAPI Description
+# OpenAPI description for Intercom’s REST API
-# Intercom REST API OpenAPI Description
+# OpenAPI description for Intercom’s REST API
 
-This repository contains [OpenAPI](https://www.openapis.org/) descriptions for [Intercom's REST API](https://developers.intercom.com/intercom-api-reference/reference/welcome). It covers API versions 2.7 and higher.
+This repository contains [OpenAPI](https://www.openapis.org/) descriptions for [Intercom’s REST API](https://developers.intercom.com/intercom-api-reference/reference/welcome).
+It defines the HTTP interface used to integrate with Intercom’s customer engagement and support platform.
+
+**Supported API versions:** 2.7 and higher.
+
+---
 
 ## What is OpenAPI?
 
 From the [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification):
 
 > The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.
 
+---
+
+## About the Intercom API
+
+The [Intercom API](https://developers.intercom.com/intercom-api-reference/) provides programmatic access to Intercom’s platform, including endpoints for messages, conversations, contacts, companies, and automation.
+
+Using this OpenAPI specification, developers can:
+- Generate SDKs or client libraries using tools such as [OpenAPI Generator](https://openapi-generator.tech/)
+- Explore schemas and models for Intercom’s API objects
+- Build, test, and validate integrations in a consistent and language-agnostic way
+
+---
+
+## Fin by Intercom
+
+The Intercom API can empower [Fin.ai](https://www.intercom.com/fin), Intercom’s AI assistant for customer support and automation.
+You can use the API to create and edit the articles that Fin uses when answering customers' questions.
+The API can also set data like conversation and user attributes to be referenced by Fin Guidance or control the flow of automations like Fin Procedures.
+
+**Fin Procedures**
+Define multi-step actions that Fin can execute through the API to handle structured or recurring workflows.
+Learn more on the [Fin Procedures overview](https://fin.ai/procedures) or read the [Fin Procedures help guide](https://fin.ai/help/en/articles/12628343-fin-procedures-explained).
+
+**Fin Voice**
+Build voice-based customer experiences powered by Fin’s conversational AI.
+Learn more on the [Fin Voice product page](https://fin.ai/voice) or see [Fin Voice setup instructions](https://www.intercom.com/help/en/articles/10697275-deploy-fin-ai-agent-over-phone).
-## Fin by Intercom
-
-The Intercom API can empower [Fin.ai](https://www.intercom.com/fin), Intercom’s AI assistant for customer support and automation.
-You can use the API to create and edit the articles that Fin uses when answering customers' questions.
-The API can also set data like conversation and user attributes to be referenced by Fin Guidance or control the flow of automations like Fin Procedures.
-
-**Fin Procedures**
-Define multi-step actions that Fin can execute through the API to handle structured or recurring workflows.
-Learn more on the [Fin Procedures overview](https://fin.ai/procedures) or read the [Fin Procedures help guide](https://fin.ai/help/en/articles/12628343-fin-procedures-explained).
-
-**Fin Voice**
-Build voice-based customer experiences powered by Fin’s conversational AI.
-Learn more on the [Fin Voice product page](https://fin.ai/voice) or see [Fin Voice setup instructions](https://www.intercom.com/help/en/articles/10697275-deploy-fin-ai-agent-over-phone).
+## Fin AI Agent
+
+Use the Intercom API to power Fin, the AI Agent for customer service, with the content and context it needs to resolve customer queries and run automations.
+
+You can:
+- Create and update the help center articles Fin uses to resolve customer queries
+- Set conversation and user attributes for Fin Guidance
+- Trigger or control automations such as Fin Procedures
+
+### Fin Procedures
+Define multi-step actions that Fin can execute via the API to handle structured or recurring workflows.  
+Learn more: [Fin Procedures overview](https://fin.ai/procedures). Read: [Fin Procedures help guide](https://fin.ai/help/en/articles/12628343-fin-procedures-explained).
+
+### Fin Voice
+Build voice-based customer experiences powered by Fin’s conversational AI.  
+Learn more: [Fin Voice product page](https://fin.ai/voice). Set up: [Deploy Fin AI Agent over the phone](https://www.intercom.com/help/en/articles/10697275-deploy-fin-ai-agent-over-phone).
-## Fin by Intercom
-
-The Intercom API can empower [Fin.ai](https://www.intercom.com/fin), Intercom’s AI assistant for customer support and automation.
-You can use the API to create and edit the articles that Fin uses when answering customers' questions.
-The API can also set data like conversation and user attributes to be referenced by Fin Guidance or control the flow of automations like Fin Procedures.
-
-**Fin Procedures**
-Define multi-step actions that Fin can execute through the API to handle structured or recurring workflows.
-Learn more on the [Fin Procedures overview](https://fin.ai/procedures) or read the [Fin Procedures help guide](https://fin.ai/help/en/articles/12628343-fin-procedures-explained).
-
-**Fin Voice**
-Build voice-based customer experiences powered by Fin’s conversational AI.
-Learn more on the [Fin Voice product page](https://fin.ai/voice) or see [Fin Voice setup instructions](https://www.intercom.com/help/en/articles/10697275-deploy-fin-ai-agent-over-phone).
+## Fin AI Agent
+
+Use the Intercom API to power Fin, the AI Agent for customer service, with the content and context it needs to resolve customer queries and run automations.
+
+You can:
+- Create and update the help center articles Fin uses to resolve customer queries
+- Set conversation and user attributes for Fin Guidance
+- Trigger or control automations such as Fin Procedures
+
+### Fin Procedures
+Define multi-step actions that Fin can execute via the API to handle structured or recurring workflows.  
+Learn more: [Fin Procedures overview](https://fin.ai/procedures). Read: [Fin Procedures help guide](https://fin.ai/help/en/articles/12628343-fin-procedures-explained).
+
+### Fin Voice
+Build voice-based customer experiences powered by Fin’s conversational AI.  
+Learn more: [Fin Voice product page](https://fin.ai/voice). Set up: [Deploy Fin AI Agent over the phone](https://www.intercom.com/help/en/articles/10697275-deploy-fin-ai-agent-over-phone).
+
+---
+
+## Related Resources
+
+- [Intercom API Reference](https://developers.intercom.com/intercom-api-reference/)
+- [Developer Documentation](https://www.intercom.com/developers)
+- [Fin.ai Overview](https://www.intercom.com/fin)
+- [Official SDKs and Client Libraries](https://github.com/intercom)
+- [Intercom Homepage](https://www.intercom.com)
+
+---
+
 ## Contributing
 
-Because this description is automatically generated from our internal codebase, we don't currently accept pull requests that directly modify the description. See [CONTRIBUTING.md](CONTRIBUTING.md) for more details.
+Because this description is automatically generated from Intercom’s internal codebase, so we do not currently accept direct pull requests that directly modify the specification.
-Because this description is automatically generated from Intercom’s internal codebase, so we do not currently accept direct pull requests that directly modify the specification.
+This description is automatically generated from Intercom’s internal codebase, so we don’t accept pull requests that modify the specification directly.
-Because this description is automatically generated from Intercom’s internal codebase, so we do not currently accept direct pull requests that directly modify the specification.
+This description is automatically generated from Intercom’s internal codebase, so we don’t accept pull requests that modify the specification directly.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for more details.
 
 If you've identified a mismatch between the Intercom API's behavior and these descriptions, or found an issue with the format of a schema, [please open an issue.](https://github.com/intercom/Intercom-OpenAPI/issues/new?template=schema-inaccuracy.md)
+
+---
+
+## Versioning
+
+This specification tracks the current Intercom API version.
+**Last updated:** October 2025.
+
+---
+
+## About Intercom
+
+[Intercom](https://www.intercom.com) is a platform for AI-powered customer communication, combining messaging, automation, and human support to help businesses connect with their customers at scale.