Skip to content

Document removeAdmin on 2.17 and ticket scopes on Preview #786

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cathalging merged 4 commits into from
Nov 2, 2026
Merged

Document removeAdmin on 2.17 and ticket scopes on Preview #786

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ff7700d
Document removeAdmin on 2.17 and ticket scopes on Preview
cathalging Oct 30, 2026
37d8ba2
Tighten removeAdmin and ticket scope wording
cathalging Nov 2, 2026
fbe610c
Document the not_found 404 for removeAdmin
cathalging Nov 2, 2026
e3e4c61
Merge remote-tracking branch 'origin/main' into remove-admin-ticket-s…
cathalging Nov 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 50 additions & 16 deletions descriptions/0/api.intercom.io.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1174,8 +1174,8 @@ paths:
- name: reassign_conversations_admin_id
in: query
required: true
description: The unique identifier of a human admin with Inbox access to
reassign the removed admin's conversation replies to. Pass `0` to leave
description: The ID of an admin with Inbox access, or a team, to reassign
the removed admin's conversation replies to. Pass `0` to leave
conversations unassigned.
example: 456
schema:
Expand Down Expand Up @@ -1203,9 +1203,10 @@ paths:
You can remove a single admin (teammate) from your workspace.
Requires the `remove_admins` OAuth scope.

This removes the admin's access to the workspace and reassigns their
work — auto-messages, ownership, article authorship, and conversation
replies — to the admins named by the `reassign_*` parameters.
This removes the admin's access to the workspace. In most cases their
work is reassigned to the IDs given in the `reassign_*` parameters. In
workspaces with more than one seat type, no reassignment happens if the
admin has no seat, a Collaborator seat or a Lite seat.
responses:
'200':
description: Successful response
Expand Down Expand Up @@ -1235,7 +1236,9 @@ paths:
enum: ['true']
example: 'true'
'404':
description: Admin not found
description: Admin not found. A `reassign_conversations_admin_id` that is
missing, or doesn't match an admin or team, returns `404` with the
code `not_found` and the message "Resource Not Found".
content:
application/json:
examples:
Expand All @@ -1249,9 +1252,9 @@ paths:
schema:
"$ref": "#/components/schemas/error"
'405':
description: Method Not Allowed. Returned when `admin_id`, or one of
the `reassign_*_admin_id` parameters, refers to a bot or a team rather
than a human admin.
description: Method Not Allowed. Returned when `admin_id`,
`reassign_messages_admin_id`, `reassign_owner_admin_id` or
`reassign_articles_author_id` refers to a bot. A team ID in any of these four parameters returns `404`.
content:
application/json:
examples:
Expand All @@ -1266,7 +1269,8 @@ paths:
"$ref": "#/components/schemas/error"
'403':
description: Forbidden. Returned when `reassign_conversations_admin_id`
refers to an admin without Inbox access for the workspace.
refers to an admin without Inbox access for the workspace. This
includes teammates with a Lite seat.
content:
application/json:
examples:
Expand Down Expand Up @@ -17603,8 +17607,10 @@ paths:
- Tags
- Conversations
operationId: attachTagToConversation
description: You can tag a specific conversation. This will return a tag object
for the tag that was added to the conversation.
description: |
You can tag a specific conversation. This will return a tag object for the tag that was added to the conversation.

If the conversation is a ticket, the access token must include the `write_tickets` scope. Without it, the request returns a `401` with the error code `token_unauthorized`.
responses:
'200':
description: successful
Expand Down Expand Up @@ -17706,8 +17712,10 @@ paths:
- Tags
- Conversations
operationId: detachTagFromConversation
description: You can remove tag from a specific conversation. This will return
a tag object for the tag that was removed from the conversation.
description: |
You can remove tag from a specific conversation. This will return a tag object for the tag that was removed from the conversation.

If the conversation is a ticket, the access token must include the `write_tickets` scope. Without it, the request returns a `401` with the error code `token_unauthorized`.
responses:
'200':
description: successful
Expand Down Expand Up @@ -17835,6 +17843,8 @@ paths:
You can use pagination to limit the number of results returned. The default is `20` results per page.
See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#pagination-for-list-apis) for more details on how to use the `starting_after` param.
{% /admonition %}

Tickets are only included in the results if the access token has the `read_tickets` scope. Without it, tickets are left out and no error is returned.
responses:
'200':
description: successful
Expand Down Expand Up @@ -18267,6 +18277,8 @@ paths:
{% /admonition %}

For AI agent conversation metadata, please note that you need to have the agent enabled in your workspace, which is a [paid feature](https://www.intercom.com/help/en/articles/8205718-fin-resolutions#h_97f8c2e671).

If the conversation is a ticket, the access token must include the `read_tickets` scope. Without it, the request returns a `401` with the error code `token_unauthorized`.
responses:
'200':
description: conversation found
Expand Down Expand Up @@ -18936,6 +18948,8 @@ paths:
- Your workspace settings (Settings → Data → Conversations)
{% /admonition %}

If the conversation is a ticket, the access token must include the `write_tickets` scope. Without it, the request returns a `401` with the error code `token_unauthorized`.

responses:
'200':
description: update a conversation with an association to a custom object
Expand Down Expand Up @@ -19252,6 +19266,8 @@ paths:
{% /admonition %}

For more info, see [this help center article](https://www.intercom.com/help/en/articles/13885146-deleting-a-conversation).

If the conversation is a ticket, the access token must include the `write_tickets` scope. Without it, the request returns a `401` with the error code `token_unauthorized`.
responses:
'200':
description: successful
Expand Down Expand Up @@ -19437,6 +19453,9 @@ paths:
| !~ | String | Doesn't Contain |
| ^ | String | Starts With |
| $ | String | Ends With |

Tickets are only included in the results if the access token has the `read_tickets` scope. Without it, tickets are left out and no error is returned.

### Sorting

Results are sorted by `updated_at`, newest first. To sort differently, add a `sort` object to the request body with a `field` and an `order` of `ascending` or `descending`. `field` is required whenever `sort` is sent, and must be one of the fields in the table above, other than `type`, `state`, `source.subject`, `source.body`, `source.author.id`, `source.author.type`, `source.author.name`, `source.author.email`, `conversation_rating.remark`, `ai_agent.rating_remark` and `ai_agent.source_title`, which can't be sorted. A missing `field`, or one that isn't searchable, returns a `400` error with the code `invalid_field`.
Expand Down Expand Up @@ -19689,6 +19708,8 @@ paths:
{% admonition type="info" name="Managing a conversation" %}
To close, open, snooze or assign a conversation, use [Manage a conversation](/docs/references/preview/rest-api/api.intercom.io/conversations/manageconversation).
{% /admonition %}

If the conversation is a ticket, the access token must include the `write_tickets` scope. Without it, the request returns a `401` with the error code `token_unauthorized`.
responses:
'200':
description: User last conversation reply
Expand Down Expand Up @@ -20211,6 +20232,8 @@ paths:
{% admonition type="info" name="Sending messages" %}
To send a comment, note or quick reply, use [Reply to a conversation](/docs/references/preview/rest-api/api.intercom.io/conversations/replyconversation).
{% /admonition %}

If the conversation is a ticket, the access token must include the `write_tickets` scope. Without it, the request returns a `401` with the error code `token_unauthorized`.
responses:
'200':
description: Assign a conversation
Expand Down Expand Up @@ -20725,6 +20748,8 @@ paths:
{% admonition type="warning" name="Experimental" %}
This is an experimental endpoint. It requires a valid HMAC secret for authentication in addition to the standard bearer token.
{% /admonition %}

If the conversation is a ticket, the access token must include the `write_tickets` scope. Without it, the request returns a `401` with the error code `token_unauthorized`.
responses:
'200':
description: Conversation part updated
Expand Down Expand Up @@ -20865,6 +20890,8 @@ paths:
If you add a contact via the email parameter and there is no user/lead found on that workspace with he given email, then we will create a new contact with `role` set to `lead`.
{% /admonition %}

If the conversation is a ticket, the access token must include the `write_tickets` scope. Without it, the request returns a `401` with the error code `token_unauthorized`.

responses:
'200':
description: Attach a contact to a conversation
Expand Down Expand Up @@ -20984,6 +21011,8 @@ paths:
You cannot remove the last remaining contact from a conversation.
{% /admonition %}

If the conversation is a ticket, the access token must include the `write_tickets` scope. Without it, the request returns a `401` with the error code `token_unauthorized`.

responses:
'200':
description: Detach a contact from a group conversation
Expand Down Expand Up @@ -21462,6 +21491,8 @@ paths:
If you are redacting a conversation part, it must have a `body`. If you are redacting a source message, it must have been created by a contact. We will return a `conversation_part_not_redactable` error if these criteria are not met.
{% /admonition %}

If the conversation is a ticket, the access token must include the `write_tickets` scope. Without it, the request returns a `401` with the error code `token_unauthorized`.

responses:
'200':
description: Redact a conversation part
Expand Down Expand Up @@ -21622,8 +21653,9 @@ paths:
The secondary conversation is closed and linked to the primary, which
becomes the surviving thread. Returns the primary conversation on success.

Requires `write_conversations` OAuth scope. When the secondary is a ticket,
`write_tickets` scope is also required.
Requires `write_conversations` OAuth scope. When either conversation is a ticket,
the `read_tickets` and `write_tickets` scopes are also required. Without them,
the request returns a `401` with the error code `token_unauthorized`.
responses:
'200':
description: Conversation merged
Expand Down Expand Up @@ -34167,6 +34199,8 @@ paths:
{% /admonition %}

Deleting a ticket permanently removes it from the inbox. All sensitive data is deleted, including admin and user replies, ticket attributes, uploads, and related content. The ticket will still appear in reporting, though some data may be incomplete due to the deletion.

Requires the `write_conversations` OAuth scope. If the ID refers to a ticket, the access token must also include the `write_tickets` scope. Without it, the request returns a `401` with the error code `token_unauthorized`.
responses:
'200':
description: successful
Expand Down
168 changes: 166 additions & 2 deletions descriptions/2.17/api.intercom.io.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2334,6 +2334,171 @@ paths:
message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
"/admins/remove":
delete:
summary: Remove an admin
parameters:
- name: Intercom-Version
in: header
schema:
"$ref": "#/components/schemas/intercom_version"
- name: admin_id
in: query
required: true
description: The unique identifier of the admin to remove.
example: 123
schema:
type: integer
- name: reassign_messages_admin_id
in: query
required: true
description: The unique identifier of a human admin to reassign the removed
admin's auto-message ownership to.
example: 456
schema:
type: integer
- name: reassign_owner_admin_id
in: query
required: true
description: The unique identifier of a human admin to reassign the removed
admin's ownership (of users and leads) to.
example: 456
schema:
type: integer
- name: reassign_articles_author_id
in: query
required: true
description: The unique identifier of a human admin to reassign the removed
admin's article authorship to.
example: 456
schema:
type: integer
- name: reassign_conversations_admin_id
in: query
required: true
description: The ID of an admin with Inbox access, or a team, to reassign
the removed admin's conversation replies to. Pass `0` to leave
conversations unassigned.
example: 456
schema:
type: integer
- name: reassign_replies_teams
in: query
required: false
description: A list of teams and the admin each team's conversation replies
should be reassigned to.
schema:
type: array
items:
type: object
properties:
team_id:
type: integer
example: 789
assignee_id:
type: integer
example: 456
tags:
- Admins
operationId: removeAdmin
description: |-
You can remove a single admin (teammate) from your workspace.
Requires the `remove_admins` OAuth scope.

This removes the admin's access to the workspace. In most cases their
work is reassigned to the IDs given in the `reassign_*` parameters. In
workspaces with more than one seat type, no reassignment happens if the
admin has no seat, a Collaborator seat or a Lite seat.
responses:
'200':
description: Successful response
content:
application/json:
examples:
Successful response:
value:
id: '123'
object: admin
removed: 'true'
schema:
type: object
properties:
id:
type: string
description: The unique identifier of the removed admin.
example: '123'
object:
type: string
enum: [admin]
example: admin
removed:
type: string
description: Whether the admin was removed. Returned as the
string `"true"`.
enum: ['true']
example: 'true'
'404':
description: Admin not found. A `reassign_conversations_admin_id` that is
missing, or doesn't match an admin or team, returns `404` with the
code `not_found` and the message "Resource Not Found".
content:
application/json:
examples:
Admin not found:
value:
type: error.list
request_id: 00000000-0000-4000-8000-000000000001
errors:
- code: admin_not_found
message: "Admin for admin_id not found"
schema:
"$ref": "#/components/schemas/error"
'405':
description: Method Not Allowed. Returned when `admin_id`,
`reassign_messages_admin_id`, `reassign_owner_admin_id` or
`reassign_articles_author_id` refers to a bot. A team ID in any of these four parameters returns `404`.
content:
application/json:
examples:
Method Not Allowed:
value:
type: error.list
errors:
- code: action_forbidden
message: "This method is not allowed for this type of Admin
for admin_id"
schema:
"$ref": "#/components/schemas/error"
'403':
description: Forbidden. Returned when `reassign_conversations_admin_id`
refers to an admin without Inbox access for the workspace. This
includes teammates with a Lite seat.
content:
application/json:
examples:
Forbidden:
value:
type: error.list
errors:
- code: action_forbidden
message: "The admin for reassign_conversations_admin_id does
not have Inbox access permissions"
schema:
"$ref": "#/components/schemas/error"
'401':
description: Unauthorized
content:
application/json:
examples:
Unauthorized:
value:
type: error.list
request_id: 00000000-0000-4000-8000-000000000002
errors:
- code: unauthorized
message: Access Token Invalid
schema:
"$ref": "#/components/schemas/error"
"/ai/content_import_sources":
get:
summary: List content import sources
Expand Down Expand Up @@ -21196,8 +21361,7 @@ paths:
The secondary conversation is closed and linked to the primary, which
becomes the surviving thread. Returns the primary conversation on success.

Requires `write_conversations` OAuth scope. When the secondary is a ticket,
`write_tickets` scope is also required.
Requires `write_conversations` OAuth scope.
responses:
'200':
description: Conversation merged
Expand Down
Loading