From 4a47ea85f69d4d2262e58923f742543e1b78981c Mon Sep 17 00:00:00 2001 From: Diane Gordon Date: Tue, 24 Feb 2026 22:39:09 +0000 Subject: [PATCH 1/2] Add POST /companies/{company_id}/notes to v2.15 spec The createCompanyNote endpoint was implemented in the intercom/intercom backend as part of version 2.15 (via AddCompanyNotesApi versioning change) but was only documented in the Unstable spec (descriptions/0/). This adds the POST endpoint to the versioned 2.15 spec to match what the backend actually supports, keeping OpenAPI and developer-docs in sync. Co-Authored-By: Claude Sonnet 4.6 --- descriptions/2.15/api.intercom.io.yaml | 101 +++++++++++++++++++++++++ 1 file changed, 101 insertions(+) diff --git a/descriptions/2.15/api.intercom.io.yaml b/descriptions/2.15/api.intercom.io.yaml index fb2ae82..a2f48b4 100644 --- a/descriptions/2.15/api.intercom.io.yaml +++ b/descriptions/2.15/api.intercom.io.yaml @@ -3395,6 +3395,107 @@ paths: message: Company Not Found schema: "$ref": "#/components/schemas/error" + post: + summary: Create a company note + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: company_id + in: path + required: true + description: The unique identifier for the company which is given by Intercom + example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632 + schema: + type: string + tags: + - Notes + - Companies + operationId: createCompanyNote + description: You can add a note to a single company. + responses: + '200': + description: Successful response + content: + application/json: + examples: + Successful response: + value: + type: note + id: '31' + created_at: 1734537390 + company: + type: company + id: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632 + author: + type: admin + id: '991267583' + name: Ciaran124 Lee + email: admin124@email.com + away_mode_enabled: false + away_mode_reassign: false + body: "

Hello

" + schema: + "$ref": "#/components/schemas/note" + '401': + description: Unauthorized + content: + application/json: + schema: + "$ref": "#/components/schemas/error" + '404': + description: Company or admin not found + content: + application/json: + examples: + Admin not found: + value: + type: error.list + request_id: 168f1bc3-d198-4797-8422-9f93fe8af5ad + errors: + - code: not_found + message: Resource Not Found + Company not found: + value: + type: error.list + request_id: 6f372239-0259-428f-9943-91b8f7a92162 + errors: + - code: company_not_found + message: Company Not Found + schema: + "$ref": "#/components/schemas/error" + requestBody: + content: + application/json: + schema: + type: object + required: + - body + properties: + body: + type: string + description: The text of the note. + example: New note + admin_id: + type: string + description: The unique identifier of the admin creating the note. If not provided, defaults to the admin associated with the access token. + example: '991267583' + examples: + successful_response: + summary: Successful response + value: + body: Hello + admin_id: '991267583' + admin_not_found: + summary: Admin not found + value: + body: Hello + admin_id: '123' + company_not_found: + summary: Company not found + value: + body: Hello "/companies/list": post: summary: List all companies From 9c37a5e9f49d611b85b43c90be8b4171a2422894 Mon Sep 17 00:00:00 2001 From: Diane Gordon Date: Thu, 19 Mar 2026 14:11:47 -0700 Subject: [PATCH 2/2] Move company notes API from 2.15 to Unstable (descriptions/0/) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Revert 2.15 changes (feature moves to Unstable per versioning policy) - Fix path parameter name: id → company_id to match Rails route - Add company property to note schema - Update note schema description to mention companies Co-Authored-By: Claude Opus 4.6 --- descriptions/0/api.intercom.io.yaml | 22 +- descriptions/2.15/api.intercom.io.yaml | 299 ++++++++++++++++--------- 2 files changed, 206 insertions(+), 115 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 41c4bf0..0d31604 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -3220,11 +3220,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 @@ -3330,7 +3330,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 @@ -21963,7 +21963,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 @@ -21992,6 +21993,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. diff --git a/descriptions/2.15/api.intercom.io.yaml b/descriptions/2.15/api.intercom.io.yaml index a2f48b4..94c8686 100644 --- a/descriptions/2.15/api.intercom.io.yaml +++ b/descriptions/2.15/api.intercom.io.yaml @@ -1041,7 +1041,10 @@ paths: tags: - Articles operationId: createArticle - description: You can create a new article by making a POST request to `https://api.intercom.io/articles`. + description: "You can create a new article by making a POST request to `https://api.intercom.io/articles`.\n\n> + \U0001F4D8 Tags cannot be managed via the Articles API\n>\n> Article tags are + read-only in responses. To create, update, or delete tags, use the Intercom + UI or the Tags API endpoints.\n" responses: '200': description: article created @@ -1236,8 +1239,11 @@ paths: tags: - Articles operationId: updateArticle - description: You can update the details of a single article by making a PUT - request to `https://api.intercom.io/articles/`. + description: "You can update the details of a single article by making a PUT + request to `https://api.intercom.io/articles/`.\n\n> \U0001F4D8 Tags cannot be + managed via the Articles API\n>\n> Article tags are read-only in responses. + To create, update, or delete tags, use the Intercom UI or the Tags API + endpoints.\n" responses: '200': description: successful @@ -3395,107 +3401,6 @@ paths: message: Company Not Found schema: "$ref": "#/components/schemas/error" - post: - summary: Create a company note - parameters: - - name: Intercom-Version - in: header - schema: - "$ref": "#/components/schemas/intercom_version" - - name: company_id - in: path - required: true - description: The unique identifier for the company which is given by Intercom - example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632 - schema: - type: string - tags: - - Notes - - Companies - operationId: createCompanyNote - description: You can add a note to a single company. - responses: - '200': - description: Successful response - content: - application/json: - examples: - Successful response: - value: - type: note - id: '31' - created_at: 1734537390 - company: - type: company - id: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632 - author: - type: admin - id: '991267583' - name: Ciaran124 Lee - email: admin124@email.com - away_mode_enabled: false - away_mode_reassign: false - body: "

Hello

" - schema: - "$ref": "#/components/schemas/note" - '401': - description: Unauthorized - content: - application/json: - schema: - "$ref": "#/components/schemas/error" - '404': - description: Company or admin not found - content: - application/json: - examples: - Admin not found: - value: - type: error.list - request_id: 168f1bc3-d198-4797-8422-9f93fe8af5ad - errors: - - code: not_found - message: Resource Not Found - Company not found: - value: - type: error.list - request_id: 6f372239-0259-428f-9943-91b8f7a92162 - errors: - - code: company_not_found - message: Company Not Found - schema: - "$ref": "#/components/schemas/error" - requestBody: - content: - application/json: - schema: - type: object - required: - - body - properties: - body: - type: string - description: The text of the note. - example: New note - admin_id: - type: string - description: The unique identifier of the admin creating the note. If not provided, defaults to the admin associated with the access token. - example: '991267583' - examples: - successful_response: - summary: Successful response - value: - body: Hello - admin_id: '991267583' - admin_not_found: - summary: Admin not found - value: - body: Hello - admin_id: '123' - company_not_found: - summary: Company not found - value: - body: Hello "/companies/list": post: summary: List all companies @@ -3732,6 +3637,13 @@ paths: errors: - code: parameter_not_found message: company not specified + Contact Company Limit Exceeded: + value: + type: error.list + request_id: 9a3d0816-9707-4598-977e-c009ba630148 + errors: + - code: contact_company_limit_exceeded + message: Contact has reached the maximum of 1000 company associations schema: "$ref": "#/components/schemas/error" '404': @@ -13484,7 +13396,13 @@ paths: content: application/json: schema: - "$ref": "#/components/schemas/update_ticket_request" + allOf: + - "$ref": "#/components/schemas/update_ticket_request" + properties: + skip_notifications: + type: boolean + description: Option to disable notifications when a Ticket is updated. + example: true examples: successful_response: summary: Successful response @@ -14667,6 +14585,44 @@ paths: application/json: schema: $ref: "#/components/schemas/error" + "/fin_voice/conversation/{conversation_id}": + get: + summary: Collect Fin Voice calls by conversation ID + description: | + Retrieve information about Fin Voice calls associated with a conversation. + + Returns all matched calls for the given conversation ID. A conversation may have multiple associated calls. + operationId: collectFinVoiceCallsByConversationId + tags: + - Calls + parameters: + - name: conversation_id + in: path + required: true + description: The Intercom conversation identifier + schema: + type: string + responses: + '200': + description: successful + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/ai_call_response" + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/error" + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/error" "/export/workflows/{id}": get: summary: Export a workflow @@ -14848,6 +14804,9 @@ components: - conversation_topic_change - conversation_topic_creation - conversation_topic_deletion + - content_redaction_rule_creation + - content_redaction_rule_deletion + - content_redaction_rule_update - csv_import_completion - csv_import_creation - custom_authentication_token_creation @@ -15726,6 +15685,8 @@ components: translated_content: nullable: true "$ref": "#/components/schemas/article_translated_content" + tags: + "$ref": "#/components/schemas/tags" internal_article_list_item: title: Internal Articles type: object @@ -17423,6 +17384,119 @@ components: description: The content sources used by AI Agent in the conversation. items: "$ref": "#/components/schemas/content_source" + conversation_list_item: + title: Conversation List Item + type: object + x-tags: + - Conversations + description: The data returned about your conversations when you list or search + them. + properties: + type: + type: string + description: Always conversation. + example: conversation + id: + type: string + description: The id representing the conversation. + example: '1295' + title: + type: string + nullable: true + description: The title given to the conversation. + example: Conversation Title + created_at: + type: integer + format: date-time + description: The time the conversation was created. + example: 1663597223 + updated_at: + type: integer + format: date-time + description: The last time the conversation was updated. + example: 1663597260 + waiting_since: + type: integer + format: date-time + nullable: true + description: The last time a Contact responded to an Admin. In other words, + the time a customer started waiting for a response. Set to null if last + reply is from an Admin. + example: 1663597260 + snoozed_until: + type: integer + format: date-time + nullable: true + description: If set this is the time in the future when this conversation + will be marked as open. i.e. it will be in a snoozed state until this + time. i.e. it will be in a snoozed state until this time. + example: 1663597260 + open: + type: boolean + description: Indicates whether a conversation is open (true) or closed (false). + example: true + state: + type: string + enum: + - open + - closed + - snoozed + description: Can be set to "open", "closed" or "snoozed". + example: open + read: + type: boolean + description: Indicates whether a conversation has been read. + example: true + priority: + type: string + enum: + - priority + - not_priority + description: If marked as priority, it will return priority or else not_priority. + example: priority + admin_assignee_id: + type: integer + nullable: true + description: The id of the admin assigned to the conversation. If it's not + assigned to an admin it will return null. + example: 0 + team_assignee_id: + type: string + nullable: true + description: The id of the team assigned to the conversation. If it's not + assigned to a team it will return null. + example: '5017691' + company: + "$ref": "#/components/schemas/company" + nullable: true + description: The company associated with the conversation. + tags: + "$ref": "#/components/schemas/tags" + conversation_rating: + "$ref": "#/components/schemas/conversation_rating" + source: + "$ref": "#/components/schemas/conversation_source" + contacts: + "$ref": "#/components/schemas/conversation_contacts" + teammates: + "$ref": "#/components/schemas/conversation_teammates" + custom_attributes: + "$ref": "#/components/schemas/custom_attributes" + first_contact_reply: + "$ref": "#/components/schemas/conversation_first_contact_reply" + sla_applied: + "$ref": "#/components/schemas/sla_applied" + statistics: + "$ref": "#/components/schemas/conversation_statistics" + linked_objects: + "$ref": "#/components/schemas/linked_object_list" + ai_agent_participated: + type: boolean + description: Indicates whether the AI Agent participated in the conversation. + example: true + ai_agent: + "$ref": "#/components/schemas/ai_agent" + nullable: true conversation: title: Conversation type: object @@ -17506,11 +17580,6 @@ components: description: The id of the team assigned to the conversation. If it's not assigned to a team it will return null. example: '5017691' - company_id: - type: string - description: The ID of the company that the conversation is associated with. - The unique identifier for the company which is given by Intercom. - example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632 company: "$ref": "#/components/schemas/company" nullable: true @@ -17638,7 +17707,7 @@ components: type: array description: The list of conversation objects items: - "$ref": "#/components/schemas/conversation" + "$ref": "#/components/schemas/conversation_list_item" total_count: type: integer description: A count of the total number of objects. @@ -18373,6 +18442,14 @@ components: type: string description: The content of the message. HTML is not supported. example: Hello + attachment_urls: + type: array + description: A list of image URLs that will be added as attachments. You + can include up to 10 URLs. + items: + type: string + format: uri + maxItems: 10 created_at: type: integer format: date-time