From b30d38dc15e58ceed8b51883be02ce4eeff675f5 Mon Sep 17 00:00:00 2001
From: Diane Gordon <diane.gordon@intercom.io>
Date: Wed, 25 Mar 2026 13:22:34 -0700
Subject: [PATCH] Move company notes API to Unstable: fix path params and add
 company property to note schema
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Fix path parameter: {id} → {company_id} to match Rails route
- Add company property to note schema (mirrors contact property)
- Update note schema description to mention companies

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 descriptions/0/api.intercom.io.yaml | 22 ++++++++++++++++++----
 1 file changed, 18 insertions(+), 4 deletions(-)

diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml
index 6b1623c..c4f6da3 100644
--- a/descriptions/0/api.intercom.io.yaml
+++ b/descriptions/0/api.intercom.io.yaml
@@ -3683,11 +3683,11 @@ paths:
                       message: Access Token Invalid
               schema:
                 "$ref": "#/components/schemas/error"
-  "/companies/{id}/notes":
+  "/companies/{company_id}/notes":
     get:
       summary: List all company notes
       parameters:
-      - name: id
+      - name: company_id
         in: path
         required: true
         description: The unique identifier for the company which is given by Intercom
@@ -3793,7 +3793,7 @@ paths:
         in: header
         schema:
           "$ref": "#/components/schemas/intercom_version"
-      - name: id
+      - name: company_id
         in: path
         required: true
         description: The unique identifier for the company which is given by Intercom
@@ -25021,7 +25021,8 @@ components:
       type: object
       x-tags:
       - Notes
-      description: Notes allow you to annotate and comment on your contacts.
+      description: Notes allow you to annotate and comment on your contacts and companies.
+        A note is attached to either a contact or a company, never both.
       properties:
         type:
           type: string
@@ -25050,6 +25051,19 @@ components:
               type: string
               description: The id of the contact.
               example: 214656d0c743eafcfde7f248
+        company:
+          type: object
+          description: Represents the company that the note was created about.
+          nullable: true
+          properties:
+            type:
+              type: string
+              description: String representing the object's type. Always has the value
+                `company`.
+            id:
+              type: string
+              description: The id of the company.
+              example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632
         author:
           "$ref": "#/components/schemas/admin"
           description: Optional. Represents the Admin that created the note.