From 97339a6f60be4aff2627975ca18036cd7d0ef7f9 Mon Sep 17 00:00:00 2001 From: Diane Gordon Date: Fri, 20 Feb 2026 12:17:54 +0000 Subject: [PATCH 1/2] Add POST /companies/{id}/notes endpoint to OpenAPI spec (Unstable) ### Why? The implementation in PR #470943 adds the ability to create notes on company records via the API, but requires corresponding OpenAPI documentation. ### How? Add the POST endpoint to the Unstable version of the OpenAPI spec, following the same pattern as the existing POST /contacts/{id}/notes endpoint. Generated with Claude Code --- descriptions/0/api.intercom.io.yaml | 103 ++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 2a79404..4c73c86 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -3323,6 +3323,109 @@ 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: 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" + '404': + description: Company 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 + company_id: + type: string + description: The unique identifier of a given company. + example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632 + admin_id: + type: string + description: The unique identifier of a given admin. + example: '991267583' + examples: + successful_response: + summary: Successful response + value: + company_id: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632 + admin_id: '991267583' + body: Hello + admin_not_found: + summary: Admin not found + value: + company_id: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632 + admin_id: '123' + body: Hello + company_not_found: + summary: Company not found + value: + company_id: '123' + admin_id: '991267583' + body: Hello "/companies/list": post: summary: List all companies From 0b98adad87766722ae8ac07db98cdee5ce58a2a9 Mon Sep 17 00:00:00 2001 From: Diane Gordon Date: Fri, 20 Feb 2026 14:26:16 +0000 Subject: [PATCH 2/2] Fix OpenAPI spec issues based on code review Fixes: - Remove company_id from request body (conflicts with path parameter) - Add 401 Unauthorized response - Clarify 404 description (company OR admin not found) - Improve admin_id description (explain default behavior) - Remove company_id from request examples Co-Authored-By: Claude Sonnet 4.5 --- descriptions/0/api.intercom.io.yaml | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 4c73c86..af07ea0 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -3366,8 +3366,14 @@ paths: body: "

Hello

" schema: "$ref": "#/components/schemas/note" + '401': + description: Unauthorized + content: + application/json: + schema: + "$ref": "#/components/schemas/error" '404': - description: Company not found + description: Company or admin not found content: application/json: examples: @@ -3399,32 +3405,24 @@ paths: type: string description: The text of the note. example: New note - company_id: - type: string - description: The unique identifier of a given company. - example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632 admin_id: type: string - description: The unique identifier of a given admin. + 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: - company_id: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632 - admin_id: '991267583' body: Hello + admin_id: '991267583' admin_not_found: summary: Admin not found value: - company_id: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632 - admin_id: '123' body: Hello + admin_id: '123' company_not_found: summary: Company not found value: - company_id: '123' - admin_id: '991267583' body: Hello "/companies/list": post: