From 2dc63ce7247be8f6e0f18d28752a17685571637f Mon Sep 17 00:00:00 2001 From: Mark Dennis Date: Thu, 22 Oct 2026 09:50:45 +0100 Subject: [PATCH 1/3] Align four shared 2.17 schemas with what the API sends Types custom_object_instance custom attribute values, gives admin.avatar its object shape, widens data_event metadata values, and lets an error code be an integer as a few validation errors send it. Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/2.17/api.intercom.io.yaml | 52 +++++++++++++++++++++----- 1 file changed, 42 insertions(+), 10 deletions(-) diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index c87a7a84..e7698cc8 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -26853,11 +26853,21 @@ components: items: type: integer avatar: - type: string - format: uri + type: object nullable: true - description: Image for the associated team or teammate - example: https://picsum.photos/200/300 + description: The teammate's avatar image. Left out when the teammate has + neither an uploaded avatar nor a gravatar. + properties: + type: + type: string + description: Value is `avatar`. Returned on the admin endpoints only. + example: avatar + image_url: + type: string + format: uri + nullable: true + description: The URL of the avatar image. + example: https://picsum.photos/200/300 team_priority_level: "$ref": "#/components/schemas/team_priority_level" role: @@ -34606,9 +34616,21 @@ components: example: Order custom_attributes: type: object - description: The custom attributes you have set on the custom object instance. + description: |- + The custom attributes you have set on the custom object instance. + + Each value is returned with the type of the attribute it is set on: a string, integer, number or boolean, or `null` when the attribute is unset. A list attribute returns the label of the selected option. A reference attribute returns an object holding the referenced records, under `contacts` for a contact reference, `conversations` for a conversation reference, or `instances` for a reference to another custom object type. additionalProperties: - type: string + anyOf: + - type: string + nullable: true + - type: integer + - type: number + - type: boolean + - type: object + example: + order_number: ORDER-12345 + total_amount: 99.99 custom_object_instance_deleted: title: Custom Object Instance Deleted type: object @@ -36384,9 +36406,15 @@ components: example: frodo.baggins@example.com metadata: type: object - description: Optional metadata about the event. + description: Optional metadata about the event. Values keep the type they + were sent with. additionalProperties: - type: string + anyOf: + - type: string + - type: integer + - type: number + - type: boolean + - type: object example: invite_code: ADDAFRIEND required: @@ -37048,9 +37076,13 @@ components: items: properties: code: - type: string + anyOf: + - type: string + - type: integer description: A string indicating the kind of error, used to further - qualify the HTTP response code + qualify the HTTP response code. A few request validation errors + send an HTTP status code as an integer here instead, for example + `422`. example: unauthorized message: type: string From fa3b70ff7b6148ed60aeeb1ff0e2e7ab12039710 Mon Sep 17 00:00:00 2001 From: Mark Dennis Date: Fri, 23 Oct 2026 15:25:56 +0100 Subject: [PATCH 2/3] Port the four shared schema changes to Preview Applies the same 2.17 changes to the Preview spec, merged operation by operation so Preview-only content stays, such as the `{id}` path parameter name. The next version is cut from Preview, and the Preview SDKs are generated from it. Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 53 +++++++++++++++++++++++------ 1 file changed, 43 insertions(+), 10 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 605b1b06..f7c5ff7d 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -30897,11 +30897,21 @@ components: items: type: integer avatar: - type: string - format: uri + type: object nullable: true - description: Image for the associated team or teammate - example: https://picsum.photos/200/300 + description: The teammate's avatar image. Left out when the teammate has + neither an uploaded avatar nor a gravatar. + properties: + type: + type: string + description: Value is `avatar`. Returned on the admin endpoints only. + example: avatar + image_url: + type: string + format: uri + nullable: true + description: The URL of the avatar image. + example: https://picsum.photos/200/300 team_priority_level: "$ref": "#/components/schemas/team_priority_level" role: @@ -39047,9 +39057,21 @@ components: example: Order custom_attributes: type: object - description: The custom attributes you have set on the custom object instance. + description: |- + The custom attributes you have set on the custom object instance. + + Each value is returned with the type of the attribute it is set on: a string, integer, number or boolean, or `null` when the attribute is unset. A list attribute returns the label of the selected option. A reference attribute returns an object holding the referenced records, under `contacts` for a contact reference, `conversations` for a conversation reference, or `instances` for a reference to another custom object type. additionalProperties: - type: string + anyOf: + - type: string + nullable: true + - type: integer + - type: number + - type: boolean + - type: object + example: + order_number: ORDER-12345 + total_amount: 99.99 custom_object_instance_deleted: title: Custom Object Instance Deleted type: object @@ -40927,8 +40949,15 @@ components: example: frodo.baggins@example.com metadata: type: object - description: Optional metadata about the event. - additionalProperties: true + description: Optional metadata about the event. Values keep the type they + were sent with. + additionalProperties: + anyOf: + - type: string + - type: integer + - type: number + - type: boolean + - type: object example: invite_code: ADDAFRIEND required: @@ -42183,9 +42212,13 @@ components: items: properties: code: - type: string + anyOf: + - type: string + - type: integer description: A string indicating the kind of error, used to further - qualify the HTTP response code + qualify the HTTP response code. A few request validation errors + send an HTTP status code as an integer here instead, for example + `422`. example: unauthorized message: type: string From e7083711c76e2d95fbb9073dc80363c2fbb92601 Mon Sep 17 00:00:00 2001 From: Mark Dennis Date: Tue, 27 Oct 2026 14:44:16 +0000 Subject: [PATCH 3/3] Scope admin.avatar wording to List all admins avatar.type is only sent by List all admins, and there avatar depends on display_avatar rather than an upload or gravatar. Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 7 ++++--- descriptions/2.17/api.intercom.io.yaml | 7 ++++--- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index f7c5ff7d..95d851fd 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -30899,12 +30899,13 @@ components: avatar: type: object nullable: true - description: The teammate's avatar image. Left out when the teammate has - neither an uploaded avatar nor a gravatar. + description: The teammate's avatar image. On List all admins it is only + included when `display_avatar` is `true`. Elsewhere it is left out when + the teammate has neither an uploaded avatar nor a gravatar. properties: type: type: string - description: Value is `avatar`. Returned on the admin endpoints only. + description: Value is `avatar`. Returned by List all admins only. example: avatar image_url: type: string diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index e7698cc8..48946e2a 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -26855,12 +26855,13 @@ components: avatar: type: object nullable: true - description: The teammate's avatar image. Left out when the teammate has - neither an uploaded avatar nor a gravatar. + description: The teammate's avatar image. On List all admins it is only + included when `display_avatar` is `true`. Elsewhere it is left out when + the teammate has neither an uploaded avatar nor a gravatar. properties: type: type: string - description: Value is `avatar`. Returned on the admin endpoints only. + description: Value is `avatar`. Returned by List all admins only. example: avatar image_url: type: string