diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml
index bee6ac14..ddbc90da 100644
--- a/descriptions/0/api.intercom.io.yaml
+++ b/descriptions/0/api.intercom.io.yaml
@@ -8600,6 +8600,31 @@ paths:
example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632
schema:
type: string
+ - name: page
+ in: query
+ required: false
+ description: The page of results to return. Defaults to `1`.
+ example: 1
+ schema:
+ type: integer
+ - name: per_page
+ in: query
+ required: false
+ description: The number of notes to return per page. Defaults to `50`, maximum
+ `60`.
+ example: 50
+ schema:
+ type: integer
+ - name: order
+ in: query
+ required: false
+ description: The order the notes are returned in, by id. Defaults to `desc`.
+ example: desc
+ schema:
+ type: string
+ enum:
+ - asc
+ - desc
- name: Intercom-Version
in: header
schema:
@@ -8608,7 +8633,10 @@ paths:
- Notes
- Companies
operationId: listCompanyNotes
- description: You can fetch a list of notes that are associated to a company.
+ description: |
+ You can fetch a list of notes that are associated to a company.
+
+ Requires the `read_users_companies` OAuth scope.
responses:
'200':
description: Successful response
@@ -8678,6 +8706,41 @@ paths:
total_pages: 1
schema:
"$ref": "#/components/schemas/note_list"
+ '400':
+ description: Bad Request
+ content:
+ application/json:
+ examples:
+ Page size too big:
+ value:
+ type: error.list
+ request_id: 4a1f7c90-2b63-4f18-9d7a-0c5e8b41d9f2
+ errors:
+ - code: parameter_invalid
+ message: Per Page is too big
+ schema:
+ "$ref": "#/components/schemas/error"
+ '401':
+ description: Unauthorized
+ content:
+ application/json:
+ examples:
+ Unauthorized:
+ value:
+ type: error.list
+ request_id: 7d2e5b14-8a06-4c39-bf5d-91e07c3a6b48
+ errors:
+ - code: unauthorized
+ message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 0f6c3a92-57d1-4e80-b23f-6a9d5c8e14b7
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
+ schema:
+ "$ref": "#/components/schemas/error"
'404':
description: Company not found
content:
@@ -8710,7 +8773,10 @@ paths:
- Notes
- Companies
operationId: createCompanyNote
- description: You can add a note to a single company.
+ description: |
+ You can add a note to a single company.
+
+ Requires the `write_users_companies` OAuth scope.
responses:
'200':
description: Successful response
@@ -8735,10 +8801,39 @@ paths:
body: "Hello
"
schema:
"$ref": "#/components/schemas/note"
+ '400':
+ description: Bad Request
+ content:
+ application/json:
+ examples:
+ Body missing:
+ value:
+ type: error.list
+ request_id: 2b84c6e0-91fd-4a37-8c52-6e7d093af415
+ errors:
+ - code: parameter_invalid
+ message: Body can't be nil
+ schema:
+ "$ref": "#/components/schemas/error"
'401':
description: Unauthorized
content:
application/json:
+ examples:
+ Unauthorized:
+ value:
+ type: error.list
+ request_id: 5e9a2d71-6c04-4bf8-93ae-1d0f74b25c69
+ errors:
+ - code: unauthorized
+ message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 8c1b70d3-4f25-49ea-a6d8-3b5f92e07a14
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
'404':
@@ -10538,6 +10633,31 @@ paths:
description: The unique identifier of a contact.
schema:
type: integer
+ - name: page
+ in: query
+ required: false
+ description: The page of results to return. Defaults to `1`.
+ example: 1
+ schema:
+ type: integer
+ - name: per_page
+ in: query
+ required: false
+ description: The number of notes to return per page. Defaults to `50`, maximum
+ `60`.
+ example: 50
+ schema:
+ type: integer
+ - name: order
+ in: query
+ required: false
+ description: The order the notes are returned in, by id. Defaults to `desc`.
+ example: desc
+ schema:
+ type: string
+ enum:
+ - asc
+ - desc
- name: Intercom-Version
in: header
schema:
@@ -10546,7 +10666,10 @@ paths:
- Notes
- Contacts
operationId: listNotes
- description: You can fetch a list of notes that are associated to a contact.
+ description: |
+ You can fetch a list of notes that are associated to a contact.
+
+ Requires the `read_users_companies` or `read_write_users` OAuth scope.
responses:
'200':
description: Successful response
@@ -10608,6 +10731,41 @@ paths:
total_pages: 1
schema:
"$ref": "#/components/schemas/note_list"
+ '400':
+ description: Bad Request
+ content:
+ application/json:
+ examples:
+ Page size too big:
+ value:
+ type: error.list
+ request_id: 6f3b2d41-7ce9-4a05-91d8-2b74e0c6a93f
+ errors:
+ - code: parameter_invalid
+ message: Per Page is too big
+ schema:
+ "$ref": "#/components/schemas/error"
+ '401':
+ description: Unauthorized
+ content:
+ application/json:
+ examples:
+ Unauthorized:
+ value:
+ type: error.list
+ request_id: 3a7d90c5-14e6-4b28-bf03-85c1d6e742ab
+ errors:
+ - code: unauthorized
+ message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 9b5e41a7-0d38-4c6f-a920-7e3f85b14c6d
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
+ schema:
+ "$ref": "#/components/schemas/error"
'404':
description: Contact not found
content:
@@ -10633,14 +10791,17 @@ paths:
in: path
required: true
description: The unique identifier of a given contact.
- example: '123'
+ example: 6762f0ad1bb69f9f2193bb62
schema:
- type: integer
+ type: string
tags:
- Notes
- Contacts
operationId: createNote
- description: You can add a note to a single contact.
+ description: |
+ You can add a note to a single contact.
+
+ Requires the `read_write_users` or `write_users_companies` OAuth scope.
responses:
'200':
description: Successful response
@@ -10665,6 +10826,41 @@ paths:
body: "Hello
"
schema:
"$ref": "#/components/schemas/note"
+ '400':
+ description: Bad Request
+ content:
+ application/json:
+ examples:
+ Body missing:
+ value:
+ type: error.list
+ request_id: c40d9e58-1b76-4f23-85a0-7d6c2e914bf3
+ errors:
+ - code: parameter_invalid
+ message: Body can't be nil
+ schema:
+ "$ref": "#/components/schemas/error"
+ '401':
+ description: Unauthorized
+ content:
+ application/json:
+ examples:
+ Unauthorized:
+ value:
+ type: error.list
+ request_id: 1e68b70f-9c3d-4a51-b48e-20d9f7c536a1
+ errors:
+ - code: unauthorized
+ message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 74c0a9e3-5d81-4b62-9f07-e3a5861d2c4b
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
+ schema:
+ "$ref": "#/components/schemas/error"
'404':
description: Contact not found
content:
@@ -10698,10 +10894,6 @@ paths:
type: string
description: The text of the note.
example: New note
- contact_id:
- type: string
- description: The unique identifier of a given contact.
- example: '123'
admin_id:
type: string
description: The unique identifier of a given admin.
@@ -10710,20 +10902,17 @@ paths:
successful_response:
summary: Successful response
value:
- contact_id: 6762f0ad1bb69f9f2193bb62
- admin_id: 991267583
+ admin_id: '991267583'
body: Hello
admin_not_found:
summary: Admin not found
value:
- contact_id: 6762f0af1bb69f9f2193bb63
- admin_id: 123
+ admin_id: '123'
body: Hello
contact_not_found:
summary: Contact not found
value:
- contact_id: 123
- admin_id: 991267585
+ admin_id: '991267585'
body: Hello
"/contacts/{contact_id}/segments":
get:
@@ -25217,7 +25406,12 @@ paths:
tags:
- Jobs
operationId: jobsStatus
- description: Retrieve the status of job execution.
+ description: |
+ Retrieve the status of job execution.
+
+ `resource_id` and `resource_url` are returned only once `status` is `success`. While the job is `pending` or `failed` both keys are left out of the response rather than returned as `null`.
+
+ Requires the `read_jobs` OAuth scope.
responses:
'200':
description: Job execution status
@@ -25228,10 +25422,18 @@ paths:
value:
type: job
id: '2'
+ url: 'https://api.intercom.io/jobs/status/2'
status: success
resource_type: ticket
resource_id: '20'
resource_url: 'https://api.intercom.io/tickets/20'
+ job still pending:
+ value:
+ type: job
+ id: '2'
+ url: 'https://api.intercom.io/jobs/status/2'
+ status: pending
+ resource_type: ticket
schema:
"$ref": "#/components/schemas/jobs"
'404':
@@ -25260,6 +25462,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: ad9c4f05-6e31-4b7a-82d6-15c0e934b7f8
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
"/macros":
@@ -26861,9 +27070,9 @@ paths:
in: path
required: true
description: The unique identifier of a given note
- example: 1
+ example: '34'
schema:
- type: integer
+ type: string
tags:
- Notes
operationId: retrieveNote
@@ -26931,14 +27140,16 @@ paths:
in: path
required: true
description: The unique identifier of a given note
- example: 1
+ example: '34'
schema:
- type: integer
+ type: string
tags:
- Notes
operationId: deleteNote
- description: You can delete a single contact or company note. Notes of other
- kinds cannot be deleted through the API.
+ description: |
+ You can delete a single contact or company note. Notes of other kinds cannot be deleted through the API.
+
+ Requires the `write_users_companies` OAuth scope.
responses:
'200':
description: successful
@@ -26978,6 +27189,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: b24e8f37-0a91-4d5c-9e76-38c1b0da5f62
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
'400':
@@ -26991,7 +27209,7 @@ paths:
request_id: 9a2d6e4b-7c1f-4a83-b6d0-2f8e5c1a9b37
errors:
- code: intercom_version_invalid
- message: Requested resource is not available in current API version.
+ message: Requested resource is not available in current API version
schema:
"$ref": "#/components/schemas/error"
"/roles":
@@ -27317,14 +27535,32 @@ paths:
- name: include_count
in: query
required: false
- description: It includes the count of contacts that belong to each segment.
+ description: Includes the count of contacts that belong to each segment. The
+ counts are added whenever this parameter has a value in the query string,
+ even `false` or an empty one, so omit it entirely to leave them out. A
+ bare `include_count` with no `=` adds no counts. With `type=company`, a
+ company segment gets no count unless a contact segment has the same name,
+ and then it shows that contact segment's count.
example: true
schema:
type: boolean
+ - name: type
+ in: query
+ required: false
+ description: Pass `company` to list company segments. Any other value, or
+ no value, lists contact segments.
+ example: company
+ schema:
+ type: string
tags:
- Segments
operationId: listSegments
- description: You can fetch a list of all segments.
+ description: |
+ You can fetch a list of all segments.
+
+ Segment names are returned HTML-escaped, for example `&` as `&`.
+
+ Requires the `read_users_companies` or `write_users_companies` OAuth scope.
responses:
'200':
description: Successful response
@@ -27361,6 +27597,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 5fa31c82-7d64-4e09-b1a7-9c48d0e35b61
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
"/segments/{id}":
@@ -27378,10 +27621,25 @@ paths:
example: '123'
schema:
type: string
+ - name: include_count
+ in: query
+ required: false
+ description: Includes the count of contacts that belong to the segment. The
+ count is added whenever this parameter has a value in the query string, even
+ `false` or an empty one, so omit it entirely to leave it out. A bare
+ `include_count` with no `=` adds no count.
+ example: true
+ schema:
+ type: boolean
tags:
- Segments
operationId: retrieveSegment
- description: You can fetch the details of a single segment.
+ description: |
+ You can fetch the details of a single segment.
+
+ The segment name is returned HTML-escaped, for example `&` as `&`.
+
+ Requires the `read_users_companies` or `write_users_companies` OAuth scope.
responses:
'200':
description: Successful response
@@ -27424,6 +27682,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 36b0d794-82ce-4a15-9f63-71d4ea80c592
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
"/sla_rules":
@@ -27589,8 +27854,10 @@ paths:
tags:
- Subscription Types
operationId: listSubscriptionTypes
- description: You can list all subscription types. A list of subscription type
- objects will be returned.
+ description: |
+ You can list all subscription types. A list of subscription type objects will be returned.
+
+ Requires the `read_users_companies` OAuth scope.
responses:
'200':
description: Successful
@@ -27629,6 +27896,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: e8471b06-3d25-4c9f-b0a8-57fe2d619c3a
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
"/subscription_types/{id}":
@@ -27649,8 +27923,10 @@ paths:
tags:
- Subscription Types
operationId: getSubscriptionType
- description: You can fetch the details of a single subscription type by making
- a GET request to `https://api.intercom.io/subscription_types/`.
+ description: |
+ You can fetch the details of a single subscription type by making a GET request to `https://api.intercom.io/subscription_types/`.
+
+ Requires the `read_users_companies` OAuth scope.
responses:
'200':
description: Successful
@@ -27697,10 +27973,17 @@ paths:
Unauthorized:
value:
type: error.list
- request_id: 06d15b1f-19b0-42cc-aff9-a9d9db39402b
+ request_id: 9d3f28a5-6e07-4b14-8c92-45a0f7d6b318
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 41c7e95b-08a3-4d62-97f1-6b2d5c8a034e
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
"/phone_call_redirects":
@@ -28185,6 +28468,65 @@ paths:
get:
summary: List all tags
parameters:
+ - name: id
+ in: query
+ required: false
+ description: The unique identifier of a tag. When set, a single tag object
+ is returned instead of a list.
+ example: '123'
+ schema:
+ type: string
+ - name: taggable_type
+ in: query
+ required: false
+ description: Set to `user` or `company` to list the tags applied to one contact
+ or company instead of the whole workspace. Identify it with `taggable_id`,
+ `user_id`, `email`, `company_id` or `name`.
+ example: user
+ schema:
+ type: string
+ enum:
+ - user
+ - company
+ - name: taggable_id
+ in: query
+ required: false
+ description: The Intercom id of the contact or company whose tags you want,
+ used with `taggable_type`.
+ example: 536e564f316c83104c000020
+ schema:
+ type: string
+ - name: user_id
+ in: query
+ required: false
+ description: The external id of the contact whose tags you want, used with
+ `taggable_type=user`.
+ example: '25'
+ schema:
+ type: string
+ - name: email
+ in: query
+ required: false
+ description: The email address of the contact whose tags you want, used with
+ `taggable_type=user`.
+ example: jane@example.com
+ schema:
+ type: string
+ - name: company_id
+ in: query
+ required: false
+ description: The external id of the company whose tags you want, used with
+ `taggable_type=company`.
+ example: '6'
+ schema:
+ type: string
+ - name: name
+ in: query
+ required: false
+ description: The name of the company whose tags you want, used with `taggable_type=company`.
+ example: Intercom
+ schema:
+ type: string
- name: Intercom-Version
in: header
schema:
@@ -28192,7 +28534,12 @@ paths:
tags:
- Tags
operationId: listTags
- description: "You can fetch a list of all tags for a given workspace.\n\n"
+ description: |
+ You can fetch a list of all tags for a given workspace.
+
+ Passing `id` returns that one tag object instead of a list. Passing `taggable_type` returns a list of the tags applied to a single contact or company.
+
+ Requires the `read_tags` or `read_users_companies` OAuth scope.
responses:
'200':
description: successful
@@ -28206,8 +28553,15 @@ paths:
- type: tag
id: '102'
name: Manual tag 1
+ single tag:
+ value:
+ type: tag
+ id: '102'
+ name: Manual tag 1
schema:
- "$ref": "#/components/schemas/tag_list"
+ anyOf:
+ - "$ref": "#/components/schemas/tag_list"
+ - "$ref": "#/components/schemas/tag_basic"
'401':
description: Unauthorized
content:
@@ -28220,6 +28574,41 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 7a4e0c61-9b35-4d28-8f70-c2a916e5473d
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
+ schema:
+ "$ref": "#/components/schemas/error"
+ '404':
+ description: Tag, contact or company not found
+ content:
+ application/json:
+ examples:
+ Tag not found:
+ value:
+ type: error.list
+ request_id: 0c93d5a8-62f1-4e37-b54a-8d7016c9f2be
+ errors:
+ - code: not_found
+ message: Resource Not Found
+ Contact not found:
+ value:
+ type: error.list
+ request_id: 93e157b4-d0a2-4c86-bf39-5e702a1c4d86
+ errors:
+ - code: not_found
+ message: User Not Found
+ Company not found:
+ value:
+ type: error.list
+ request_id: 2d6f81e0-4a37-49b5-91c8-607de4a2b3f5
+ errors:
+ - code: company_not_found
+ message: Company Not Found
schema:
"$ref": "#/components/schemas/error"
post:
@@ -28246,6 +28635,10 @@ paths:
**5. Tag Multiple Users:** You can tag a list of users. You can tag the users by passing in the tag name and the user details as specified in "Tag Users Request Payload" described below.
Each operation will return a tag object.
+
+ Contacts and companies listed in `users` or `companies` that do not exist are skipped: they are left out of the `users` and `companies` arrays in the response and the request still succeeds. With `ids_to_add` it depends on `taggable_type`: a contact id that does not exist returns a 404, while a company id that does not exist is skipped. With `ids_to_add`, the `users` and `companies` arrays in the response are always empty, and a 404 still leaves the tag created or renamed.
+
+ Requires the `write_tags` or `write_users_companies` OAuth scope.
responses:
'200':
description: Action successful
@@ -28258,7 +28651,16 @@ paths:
id: '105'
name: test
users: []
- companies: [{ "id": "valid-123", "tagged": true }]
+ companies: []
+ Companies tagged:
+ value:
+ type: tag
+ id: '105'
+ name: test
+ users: []
+ companies:
+ - id: '6329e838deab40166d1a5400'
+ tagged: true
schema:
"$ref": "#/components/schemas/tag_create_response"
'400':
@@ -28287,13 +28689,41 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 6e02b8d5-91c7-4a30-bf68-74d1e953c0a2
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
+ schema:
+ "$ref": "#/components/schemas/error"
+ '404':
+ description: Tag or contact not found
+ content:
+ application/json:
+ examples:
+ Tag not found:
+ value:
+ type: error.list
+ request_id: 8f51c0a4-2d79-4e36-9b1a-50c7d2e86f43
+ errors:
+ - code: not_found
+ message: Resource Not Found
+ Contact in ids_to_add not found:
+ value:
+ type: error.list
+ request_id: d7b4169e-35fa-4c80-91d2-6e0853a7bc15
+ errors:
+ - code: not_found
+ message: User Not Found
schema:
"$ref": "#/components/schemas/error"
requestBody:
content:
application/json:
schema:
- oneOf:
+ anyOf:
- "$ref": "#/components/schemas/create_or_update_tag_request"
- "$ref": "#/components/schemas/tag_company_request"
- "$ref": "#/components/schemas/untag_company_request"
@@ -28303,10 +28733,35 @@ paths:
summary: Action successful
value:
name: test
+ companies_tagged:
+ summary: Companies tagged
+ value:
+ name: test
+ companies:
+ - company_id: '6'
invalid_parameters:
summary: Invalid parameters
value:
test: invalid
+ unknown_company_skipped:
+ summary: Unknown company skipped
+ value:
+ name: test
+ companies:
+ - company_id: '123'
+ unknown_user_skipped:
+ summary: Unknown user skipped
+ value:
+ name: test
+ users:
+ - id: '123'
+ contact_in_ids_to_add_not_found:
+ summary: Contact in ids_to_add not found
+ value:
+ name: test
+ taggable_type: user
+ ids_to_add:
+ - '123'
"/tags/{id}":
get:
summary: Find a specific tag
@@ -28328,6 +28783,8 @@ paths:
description: |
You can fetch the details of tags that are on the workspace by their id.
This will return a tag object.
+
+ Requires the `read_tags` or `read_users_companies` OAuth scope.
responses:
'200':
description: Tag found
@@ -28367,6 +28824,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: a05f7362-c194-4d8b-9e27-f63b85c1d409
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
delete:
@@ -28386,8 +28850,10 @@ paths:
tags:
- Tags
operationId: deleteTag
- description: You can delete the details of tags that are on the workspace by
- passing in the id.
+ description: |
+ You can delete the details of tags that are on the workspace by passing in the id.
+
+ Requires the `write_tags` or `write_users_companies` OAuth scope.
responses:
'200':
description: Successful
@@ -28432,6 +28898,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 1b8e4790-ad35-42f6-8c01-9e5d73a2bf64
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
"/teams":
@@ -42903,20 +43376,44 @@ components:
order_number: ORDER-12345
total_amount: 99.99
create_or_update_tag_request:
- description: You can create or update an existing tag.
+ description: You can create or update an existing tag, and optionally apply
+ it to a list of contact or company ids.
type: object
title: Create or Update Tag Request Payload
properties:
name:
type: string
+ maxLength: 191
description: The name of the tag, which will be created if not found, or
the new name for the tag if this is an update request. Names are case
- insensitive.
+ insensitive and can be at most 191 characters long. Creating a tag with
+ a longer name returns a 400. When updating by `id`, a longer name or one
+ that another tag already has returns 200 with the new name, but the tag
+ keeps its old name.
example: Independent
id:
type: string
description: The id of tag to updates.
example: '656452352'
+ ids_to_add:
+ type: array
+ description: The Intercom ids of the contacts or companies to apply the
+ tag to. A contact id that does not exist returns a 404; a company id
+ that does not exist is skipped. A 404 still leaves the tag created or
+ renamed. The `users` and `companies` arrays in the response are always
+ empty when this field is used.
+ items:
+ type: string
+ example:
+ - 536e564f316c83104c000020
+ taggable_type:
+ type: string
+ description: Whether the ids in `ids_to_add` are contacts or companies.
+ Defaults to `user`.
+ enum:
+ - user
+ - company
+ example: user
required:
- name
create_phone_switch_request:
@@ -47925,7 +48422,7 @@ components:
id:
type: string
description: The id of the job that's currently being processed or has completed.
- example: 20
+ example: '20'
url:
type: string
description: API endpoint URL to check the job status.
@@ -47943,13 +48440,13 @@ components:
example: ticket
resource_id:
type: string
- description: The id of the resource created during job execution (e.g. ticket id)
- example: 123
+ description: The id of the resource created during job execution (e.g. ticket id). Only set once the job has succeeded.
+ example: '123'
nullable: true
resource_url:
type: string
- description: The url of the resource created during job exeuction. Use this url to fetch the resource.
- example: http://api.intercom.io/tickets/123
+ description: The url of the resource created during job execution. Use this url to fetch the resource. Only set once the job has succeeded.
+ example: https://api.intercom.io/tickets/123
nullable: true
required:
- id
@@ -48970,8 +49467,13 @@ components:
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.
+ type: object
+ nullable: true
+ description: Represents the Admin that created the note. When the note has
+ no recorded admin, this is `null` on a single note and left out of each
+ note in a list.
+ allOf:
+ - "$ref": "#/components/schemas/admin"
body:
type: string
description: The body text of the note.
@@ -49121,6 +49623,7 @@ components:
title: Paginated Response
type: object
description: A paginated list of notes associated with a contact or a company.
+ On the last page, `pages.next` is `null`. These lists never send `pages.prev`.
properties:
type:
type: string
@@ -49137,7 +49640,7 @@ components:
description: A count of the total number of notes.
example: 1
pages:
- "$ref": "#/components/schemas/cursor_pages"
+ "$ref": "#/components/schemas/pages_link"
company_note:
title: Company Note
type: object
@@ -49543,14 +50046,15 @@ components:
count:
type: integer
description: The number of items in the user segment. It's returned when
- `include_count=true` is included in the request.
+ the request has `include_count` with a value. A company segment only gets
+ a count when a contact segment has the same name, and it shows that
+ segment's count.
example: 3
nullable: true
segment_list:
title: Segment List
type: object
- description: This will return a list of Segment Objects. The result may also
- have a pages object if the response is paginated.
+ description: This will return a list of Segment Objects. The list is not paginated.
properties:
type:
type: string
@@ -49563,10 +50067,6 @@ components:
description: A list of Segment objects
items:
"$ref": "#/components/schemas/segment"
- pages:
- type: object
- description: A pagination object, which may be empty, indicating no further
- pages to fetch.
single_filter_search_request:
title: Single Filter Search Request
description: Search using Intercoms Search APIs with a single filter.
@@ -49891,7 +50391,7 @@ components:
example: Test tag
applied_at:
type: integer
- format: date-time
+ format: timestamp
nullable: true
description: The time when the tag was applied to the object. Only present when the tag is returned as part of a tagging operation on a contact, conversation, ticket, article, internal article, or content snippet, when listing the tags on a contact, or when it is returned as part of an external page. `null` when the tag has just been removed from an article, internal article, content snippet or external page. Removing a tag from a contact, conversation or ticket returns the original value.
example: 1663597223
@@ -49968,7 +50468,9 @@ components:
properties:
name:
type: string
- description: The name of the tag, which will be created if not found.
+ maxLength: 191
+ description: The name of the tag, which will be created if not found. Names
+ can be at most 191 characters long.
example: Independent
companies:
type: array
@@ -49982,8 +50484,13 @@ components:
type: string
description: The company id you have defined for the company.
example: '6'
- description: The id or company_id of the company can be passed as input
- parameters.
+ name:
+ type: string
+ description: The name of the company, used to look it up when neither
+ `id` nor `company_id` is given.
+ example: Intercom
+ description: The id, company_id or name of the company can be passed as
+ input parameters. Companies that cannot be found are skipped.
required:
- name
- companies
@@ -50004,22 +50511,41 @@ components:
items:
"$ref": "#/components/schemas/tag"
tag_multiple_users_request:
- description: You can tag a list of users.
+ description: You can tag or untag a list of users.
type: object
title: Tag Users Request Payload
properties:
name:
type: string
- description: The name of the tag, which will be created if not found.
+ maxLength: 191
+ description: The name of the tag, which will be created if not found. Names
+ can be at most 191 characters long.
example: Independent
users:
type: array
+ description: The id, user_id or email of the user can be passed as input
+ parameters. Users that cannot be found are skipped.
items:
properties:
id:
type: string
description: The Intercom defined id representing the user.
example: 5f7f0d217289f8d2f4262080
+ user_id:
+ type: string
+ description: The user id you have defined for the user, used to look
+ it up when `id` is not given.
+ example: '25'
+ email:
+ type: string
+ description: The email address of the user, used to look it up when
+ neither `id` nor `user_id` is given.
+ example: jane@example.com
+ untag:
+ type: boolean
+ description: Set to true to remove the tag from this user instead
+ of applying it.
+ example: true
required:
- name
- users
@@ -51040,7 +51566,9 @@ components:
properties:
name:
type: string
- description: The name of the tag which will be untagged from the company
+ maxLength: 191
+ description: The name of the tag which will be untagged from the company.
+ Names can be at most 191 characters long.
example: Independent
companies:
type: array
@@ -51054,12 +51582,19 @@ components:
type: string
description: The company id you have defined for the company.
example: '6'
+ name:
+ type: string
+ description: The name of the company, used to look it up when neither
+ `id` nor `company_id` is given.
+ example: Intercom
untag:
type: boolean
description: Always set to true
- example: 'true'
- description: The id or company_id of the company can be passed as input
- parameters.
+ example: true
+ required:
+ - untag
+ description: The id, company_id or name of the company can be passed as
+ input parameters. Companies that cannot be found are skipped.
required:
- name
- companies
diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml
index a23d9504..cc814581 100644
--- a/descriptions/2.17/api.intercom.io.yaml
+++ b/descriptions/2.17/api.intercom.io.yaml
@@ -9982,6 +9982,31 @@ paths:
example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632
schema:
type: string
+ - name: page
+ in: query
+ required: false
+ description: The page of results to return. Defaults to `1`.
+ example: 1
+ schema:
+ type: integer
+ - name: per_page
+ in: query
+ required: false
+ description: The number of notes to return per page. Defaults to `50`, maximum
+ `60`.
+ example: 50
+ schema:
+ type: integer
+ - name: order
+ in: query
+ required: false
+ description: The order the notes are returned in, by id. Defaults to `desc`.
+ example: desc
+ schema:
+ type: string
+ enum:
+ - asc
+ - desc
- name: Intercom-Version
in: header
schema:
@@ -9990,7 +10015,10 @@ paths:
- Notes
- Companies
operationId: listCompanyNotes
- description: You can fetch a list of notes that are associated to a company.
+ description: |
+ You can fetch a list of notes that are associated to a company.
+
+ Requires the `read_users_companies` OAuth scope.
responses:
'200':
description: Successful response
@@ -10028,6 +10056,41 @@ paths:
total_pages: 1
schema:
"$ref": "#/components/schemas/note_list"
+ '400':
+ description: Bad Request
+ content:
+ application/json:
+ examples:
+ Page size too big:
+ value:
+ type: error.list
+ request_id: 4a1f7c90-2b63-4f18-9d7a-0c5e8b41d9f2
+ errors:
+ - code: parameter_invalid
+ message: Per Page is too big
+ schema:
+ "$ref": "#/components/schemas/error"
+ '401':
+ description: Unauthorized
+ content:
+ application/json:
+ examples:
+ Unauthorized:
+ value:
+ type: error.list
+ request_id: 7d2e5b14-8a06-4c39-bf5d-91e07c3a6b48
+ errors:
+ - code: unauthorized
+ message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 0f6c3a92-57d1-4e80-b23f-6a9d5c8e14b7
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
+ schema:
+ "$ref": "#/components/schemas/error"
'404':
description: Company not found
content:
@@ -10060,7 +10123,10 @@ paths:
- Notes
- Companies
operationId: createCompanyNote
- description: You can add a note to a single company.
+ description: |
+ You can add a note to a single company.
+
+ Requires the `write_users_companies` OAuth scope.
responses:
'200':
description: Successful response
@@ -10085,10 +10151,39 @@ paths:
body: "Hello
"
schema:
"$ref": "#/components/schemas/note"
+ '400':
+ description: Bad Request
+ content:
+ application/json:
+ examples:
+ Body missing:
+ value:
+ type: error.list
+ request_id: 2b84c6e0-91fd-4a37-8c52-6e7d093af415
+ errors:
+ - code: parameter_invalid
+ message: Body can't be nil
+ schema:
+ "$ref": "#/components/schemas/error"
'401':
description: Unauthorized
content:
application/json:
+ examples:
+ Unauthorized:
+ value:
+ type: error.list
+ request_id: 5e9a2d71-6c04-4bf8-93ae-1d0f74b25c69
+ errors:
+ - code: unauthorized
+ message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 8c1b70d3-4f25-49ea-a6d8-3b5f92e07a14
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
'404':
@@ -11024,6 +11119,31 @@ paths:
description: The unique identifier of a contact.
schema:
type: string
+ - name: page
+ in: query
+ required: false
+ description: The page of results to return. Defaults to `1`.
+ example: 1
+ schema:
+ type: integer
+ - name: per_page
+ in: query
+ required: false
+ description: The number of notes to return per page. Defaults to `50`, maximum
+ `60`.
+ example: 50
+ schema:
+ type: integer
+ - name: order
+ in: query
+ required: false
+ description: The order the notes are returned in, by id. Defaults to `desc`.
+ example: desc
+ schema:
+ type: string
+ enum:
+ - asc
+ - desc
- name: Intercom-Version
in: header
schema:
@@ -11032,7 +11152,10 @@ paths:
- Notes
- Contacts
operationId: listNotes
- description: You can fetch a list of notes that are associated to a contact.
+ description: |
+ You can fetch a list of notes that are associated to a contact.
+
+ Requires the `read_users_companies` or `read_write_users` OAuth scope.
responses:
'200':
description: Successful response
@@ -11094,6 +11217,41 @@ paths:
total_pages: 1
schema:
"$ref": "#/components/schemas/note_list"
+ '400':
+ description: Bad Request
+ content:
+ application/json:
+ examples:
+ Page size too big:
+ value:
+ type: error.list
+ request_id: 6f3b2d41-7ce9-4a05-91d8-2b74e0c6a93f
+ errors:
+ - code: parameter_invalid
+ message: Per Page is too big
+ schema:
+ "$ref": "#/components/schemas/error"
+ '401':
+ description: Unauthorized
+ content:
+ application/json:
+ examples:
+ Unauthorized:
+ value:
+ type: error.list
+ request_id: 3a7d90c5-14e6-4b28-bf03-85c1d6e742ab
+ errors:
+ - code: unauthorized
+ message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 9b5e41a7-0d38-4c6f-a920-7e3f85b14c6d
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
+ schema:
+ "$ref": "#/components/schemas/error"
'404':
description: Contact not found
content:
@@ -11119,14 +11277,17 @@ paths:
in: path
required: true
description: The unique identifier of a given contact.
- example: '123'
+ example: 6762f0ad1bb69f9f2193bb62
schema:
- type: integer
+ type: string
tags:
- Notes
- Contacts
operationId: createNote
- description: You can add a note to a single contact.
+ description: |
+ You can add a note to a single contact.
+
+ Requires the `read_write_users` or `write_users_companies` OAuth scope.
responses:
'200':
description: Successful response
@@ -11151,6 +11312,41 @@ paths:
body: "Hello
"
schema:
"$ref": "#/components/schemas/note"
+ '400':
+ description: Bad Request
+ content:
+ application/json:
+ examples:
+ Body missing:
+ value:
+ type: error.list
+ request_id: c40d9e58-1b76-4f23-85a0-7d6c2e914bf3
+ errors:
+ - code: parameter_invalid
+ message: Body can't be nil
+ schema:
+ "$ref": "#/components/schemas/error"
+ '401':
+ description: Unauthorized
+ content:
+ application/json:
+ examples:
+ Unauthorized:
+ value:
+ type: error.list
+ request_id: 1e68b70f-9c3d-4a51-b48e-20d9f7c536a1
+ errors:
+ - code: unauthorized
+ message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 74c0a9e3-5d81-4b62-9f07-e3a5861d2c4b
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
+ schema:
+ "$ref": "#/components/schemas/error"
'404':
description: Contact not found
content:
@@ -11192,20 +11388,17 @@ paths:
successful_response:
summary: Successful response
value:
- contact_id: 6762f0ad1bb69f9f2193bb62
- admin_id: 991267583
+ admin_id: '991267583'
body: Hello
admin_not_found:
summary: Admin not found
value:
- contact_id: 6762f0af1bb69f9f2193bb63
- admin_id: 123
+ admin_id: '123'
body: Hello
contact_not_found:
summary: Contact not found
value:
- contact_id: 123
- admin_id: 991267585
+ admin_id: '991267585'
body: Hello
"/contacts/{contact_id}/segments":
get:
@@ -23655,7 +23848,12 @@ paths:
tags:
- Jobs
operationId: jobsStatus
- description: Retrieve the status of job execution.
+ description: |
+ Retrieve the status of job execution.
+
+ `resource_id` and `resource_url` are returned only once `status` is `success`. While the job is `pending` or `failed` both keys are left out of the response rather than returned as `null`.
+
+ Requires the `read_jobs` OAuth scope.
responses:
'200':
description: Job execution status
@@ -23666,10 +23864,18 @@ paths:
value:
type: job
id: '2'
+ url: 'https://api.intercom.io/jobs/status/2'
status: success
resource_type: ticket
resource_id: '20'
resource_url: 'https://api.intercom.io/tickets/20'
+ job still pending:
+ value:
+ type: job
+ id: '2'
+ url: 'https://api.intercom.io/jobs/status/2'
+ status: pending
+ resource_type: ticket
schema:
"$ref": "#/components/schemas/jobs"
'404':
@@ -23698,6 +23904,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: ad9c4f05-6e31-4b7a-82d6-15c0e934b7f8
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
"/messages":
@@ -24718,9 +24931,9 @@ paths:
in: path
required: true
description: The unique identifier of a given note
- example: 1
+ example: '34'
schema:
- type: integer
+ type: string
tags:
- Notes
operationId: retrieveNote
@@ -24788,14 +25001,16 @@ paths:
in: path
required: true
description: The unique identifier of a given note
- example: 1
+ example: '34'
schema:
- type: integer
+ type: string
tags:
- Notes
operationId: deleteNote
- description: You can delete a single contact or company note. Notes of other
- kinds cannot be deleted through the API.
+ description: |
+ You can delete a single contact or company note. Notes of other kinds cannot be deleted through the API.
+
+ Requires the `write_users_companies` OAuth scope.
responses:
'200':
description: successful
@@ -24835,6 +25050,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: b24e8f37-0a91-4d5c-9e76-38c1b0da5f62
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
'400':
@@ -24848,7 +25070,7 @@ paths:
request_id: 9a2d6e4b-7c1f-4a83-b6d0-2f8e5c1a9b37
errors:
- code: intercom_version_invalid
- message: Requested resource is not available in current API version.
+ message: Requested resource is not available in current API version
schema:
"$ref": "#/components/schemas/error"
"/segments":
@@ -24862,14 +25084,32 @@ paths:
- name: include_count
in: query
required: false
- description: It includes the count of contacts that belong to each segment.
+ description: Includes the count of contacts that belong to each segment. The
+ counts are added whenever this parameter has a value in the query string,
+ even `false` or an empty one, so omit it entirely to leave them out. A
+ bare `include_count` with no `=` adds no counts. With `type=company`, a
+ company segment gets no count unless a contact segment has the same name,
+ and then it shows that contact segment's count.
example: true
schema:
type: boolean
+ - name: type
+ in: query
+ required: false
+ description: Pass `company` to list company segments. Any other value, or
+ no value, lists contact segments.
+ example: company
+ schema:
+ type: string
tags:
- Segments
operationId: listSegments
- description: You can fetch a list of all segments.
+ description: |
+ You can fetch a list of all segments.
+
+ Segment names are returned HTML-escaped, for example `&` as `&`.
+
+ Requires the `read_users_companies` or `write_users_companies` OAuth scope.
responses:
'200':
description: Successful response
@@ -24906,6 +25146,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 5fa31c82-7d64-4e09-b1a7-9c48d0e35b61
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
"/segments/{segment_id}":
@@ -24923,10 +25170,25 @@ paths:
example: '123'
schema:
type: string
+ - name: include_count
+ in: query
+ required: false
+ description: Includes the count of contacts that belong to the segment. The
+ count is added whenever this parameter has a value in the query string, even
+ `false` or an empty one, so omit it entirely to leave it out. A bare
+ `include_count` with no `=` adds no count.
+ example: true
+ schema:
+ type: boolean
tags:
- Segments
operationId: retrieveSegment
- description: You can fetch the details of a single segment.
+ description: |
+ You can fetch the details of a single segment.
+
+ The segment name is returned HTML-escaped, for example `&` as `&`.
+
+ Requires the `read_users_companies` or `write_users_companies` OAuth scope.
responses:
'200':
description: Successful response
@@ -24969,6 +25231,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 36b0d794-82ce-4a15-9f63-71d4ea80c592
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
"/subscription_types":
@@ -24982,8 +25251,10 @@ paths:
tags:
- Subscription Types
operationId: listSubscriptionTypes
- description: You can list all subscription types. A list of subscription type
- objects will be returned.
+ description: |
+ You can list all subscription types. A list of subscription type objects will be returned.
+
+ Requires the `read_users_companies` OAuth scope.
responses:
'200':
description: Successful
@@ -25022,6 +25293,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: e8471b06-3d25-4c9f-b0a8-57fe2d619c3a
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
"/subscription_types/{id}":
@@ -25042,8 +25320,10 @@ paths:
tags:
- Subscription Types
operationId: getSubscriptionType
- description: You can fetch the details of a single subscription type by making
- a GET request to `https://api.intercom.io/subscription_types/`.
+ description: |
+ You can fetch the details of a single subscription type by making a GET request to `https://api.intercom.io/subscription_types/`.
+
+ Requires the `read_users_companies` OAuth scope.
responses:
'200':
description: Successful
@@ -25090,10 +25370,17 @@ paths:
Unauthorized:
value:
type: error.list
- request_id: 06d15b1f-19b0-42cc-aff9-a9d9db39402b
+ request_id: 9d3f28a5-6e07-4b14-8c92-45a0f7d6b318
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 41c7e95b-08a3-4d62-97f1-6b2d5c8a034e
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
"/phone_call_redirects":
@@ -25559,6 +25846,65 @@ paths:
get:
summary: List all tags
parameters:
+ - name: id
+ in: query
+ required: false
+ description: The unique identifier of a tag. When set, a single tag object
+ is returned instead of a list.
+ example: '123'
+ schema:
+ type: string
+ - name: taggable_type
+ in: query
+ required: false
+ description: Set to `user` or `company` to list the tags applied to one contact
+ or company instead of the whole workspace. Identify it with `taggable_id`,
+ `user_id`, `email`, `company_id` or `name`.
+ example: user
+ schema:
+ type: string
+ enum:
+ - user
+ - company
+ - name: taggable_id
+ in: query
+ required: false
+ description: The Intercom id of the contact or company whose tags you want,
+ used with `taggable_type`.
+ example: 536e564f316c83104c000020
+ schema:
+ type: string
+ - name: user_id
+ in: query
+ required: false
+ description: The external id of the contact whose tags you want, used with
+ `taggable_type=user`.
+ example: '25'
+ schema:
+ type: string
+ - name: email
+ in: query
+ required: false
+ description: The email address of the contact whose tags you want, used with
+ `taggable_type=user`.
+ example: jane@example.com
+ schema:
+ type: string
+ - name: company_id
+ in: query
+ required: false
+ description: The external id of the company whose tags you want, used with
+ `taggable_type=company`.
+ example: '6'
+ schema:
+ type: string
+ - name: name
+ in: query
+ required: false
+ description: The name of the company whose tags you want, used with `taggable_type=company`.
+ example: Intercom
+ schema:
+ type: string
- name: Intercom-Version
in: header
schema:
@@ -25566,7 +25912,12 @@ paths:
tags:
- Tags
operationId: listTags
- description: "You can fetch a list of all tags for a given workspace.\n\n"
+ description: |
+ You can fetch a list of all tags for a given workspace.
+
+ Passing `id` returns that one tag object instead of a list. Passing `taggable_type` returns a list of the tags applied to a single contact or company.
+
+ Requires the `read_tags` or `read_users_companies` OAuth scope.
responses:
'200':
description: successful
@@ -25580,8 +25931,15 @@ paths:
- type: tag
id: '102'
name: Manual tag 1
+ single tag:
+ value:
+ type: tag
+ id: '102'
+ name: Manual tag 1
schema:
- "$ref": "#/components/schemas/tag_list"
+ anyOf:
+ - "$ref": "#/components/schemas/tag_list"
+ - "$ref": "#/components/schemas/tag_basic"
'401':
description: Unauthorized
content:
@@ -25594,6 +25952,41 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 7a4e0c61-9b35-4d28-8f70-c2a916e5473d
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
+ schema:
+ "$ref": "#/components/schemas/error"
+ '404':
+ description: Tag, contact or company not found
+ content:
+ application/json:
+ examples:
+ Tag not found:
+ value:
+ type: error.list
+ request_id: 0c93d5a8-62f1-4e37-b54a-8d7016c9f2be
+ errors:
+ - code: not_found
+ message: Resource Not Found
+ Contact not found:
+ value:
+ type: error.list
+ request_id: 93e157b4-d0a2-4c86-bf39-5e702a1c4d86
+ errors:
+ - code: not_found
+ message: User Not Found
+ Company not found:
+ value:
+ type: error.list
+ request_id: 2d6f81e0-4a37-49b5-91c8-607de4a2b3f5
+ errors:
+ - code: company_not_found
+ message: Company Not Found
schema:
"$ref": "#/components/schemas/error"
post:
@@ -25620,6 +26013,10 @@ paths:
**5. Tag Multiple Users:** You can tag a list of users. You can tag the users by passing in the tag name and the user details as specified in "Tag Users Request Payload" described below.
Each operation will return a tag object.
+
+ Contacts and companies listed in `users` or `companies` that do not exist are skipped: they are left out of the `users` and `companies` arrays in the response and the request still succeeds. With `ids_to_add` it depends on `taggable_type`: a contact id that does not exist returns a 404, while a company id that does not exist is skipped. With `ids_to_add`, the `users` and `companies` arrays in the response are always empty, and a 404 still leaves the tag created or renamed.
+
+ Requires the `write_tags` or `write_users_companies` OAuth scope.
responses:
'200':
description: Action successful
@@ -25627,13 +26024,20 @@ paths:
application/json:
examples:
Action successful:
+ value:
+ type: tag
+ id: '105'
+ name: test
+ users: []
+ companies: []
+ Companies tagged:
value:
type: tag
id: '105'
name: test
users: []
companies:
- - id: valid-123
+ - id: '6329e838deab40166d1a5400'
tagged: true
schema:
"$ref": "#/components/schemas/tag_create_response"
@@ -25663,13 +26067,41 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 6e02b8d5-91c7-4a30-bf68-74d1e953c0a2
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
+ schema:
+ "$ref": "#/components/schemas/error"
+ '404':
+ description: Tag or contact not found
+ content:
+ application/json:
+ examples:
+ Tag not found:
+ value:
+ type: error.list
+ request_id: 8f51c0a4-2d79-4e36-9b1a-50c7d2e86f43
+ errors:
+ - code: not_found
+ message: Resource Not Found
+ Contact in ids_to_add not found:
+ value:
+ type: error.list
+ request_id: d7b4169e-35fa-4c80-91d2-6e0853a7bc15
+ errors:
+ - code: not_found
+ message: User Not Found
schema:
"$ref": "#/components/schemas/error"
requestBody:
content:
application/json:
schema:
- oneOf:
+ anyOf:
- "$ref": "#/components/schemas/create_or_update_tag_request"
- "$ref": "#/components/schemas/tag_company_request"
- "$ref": "#/components/schemas/untag_company_request"
@@ -25679,22 +26111,35 @@ paths:
summary: Action successful
value:
name: test
+ companies_tagged:
+ summary: Companies tagged
+ value:
+ name: test
+ companies:
+ - company_id: '6'
invalid_parameters:
summary: Invalid parameters
value:
test: invalid
- company_not_found:
- summary: Company not found
+ unknown_company_skipped:
+ summary: Unknown company skipped
value:
name: test
companies:
- company_id: '123'
- user_not_found:
- summary: User not found
+ unknown_user_skipped:
+ summary: Unknown user skipped
value:
name: test
users:
- id: '123'
+ contact_in_ids_to_add_not_found:
+ summary: Contact in ids_to_add not found
+ value:
+ name: test
+ taggable_type: user
+ ids_to_add:
+ - '123'
"/tags/{tag_id}":
get:
summary: Find a specific tag
@@ -25716,6 +26161,8 @@ paths:
description: |
You can fetch the details of tags that are on the workspace by their id.
This will return a tag object.
+
+ Requires the `read_tags` or `read_users_companies` OAuth scope.
responses:
'200':
description: Tag found
@@ -25755,6 +26202,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: a05f7362-c194-4d8b-9e27-f63b85c1d409
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
delete:
@@ -25774,8 +26228,10 @@ paths:
tags:
- Tags
operationId: deleteTag
- description: You can delete the details of tags that are on the workspace by
- passing in the id.
+ description: |
+ You can delete the details of tags that are on the workspace by passing in the id.
+
+ Requires the `write_tags` or `write_users_companies` OAuth scope.
responses:
'200':
description: Successful
@@ -25820,6 +26276,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 1b8e4790-ad35-42f6-8c01-9e5d73a2bf64
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
"/teams":
@@ -37664,20 +38127,44 @@ components:
order_number: ORDER-12345
total_amount: 99.99
create_or_update_tag_request:
- description: You can create or update an existing tag.
+ description: You can create or update an existing tag, and optionally apply
+ it to a list of contact or company ids.
type: object
title: Create or Update Tag Request Payload
properties:
name:
type: string
+ maxLength: 191
description: The name of the tag, which will be created if not found, or
the new name for the tag if this is an update request. Names are case
- insensitive.
+ insensitive and can be at most 191 characters long. Creating a tag with
+ a longer name returns a 400. When updating by `id`, a longer name or one
+ that another tag already has returns 200 with the new name, but the tag
+ keeps its old name.
example: Independent
id:
type: string
description: The id of tag to updates.
example: '656452352'
+ ids_to_add:
+ type: array
+ description: The Intercom ids of the contacts or companies to apply the
+ tag to. A contact id that does not exist returns a 404; a company id
+ that does not exist is skipped. A 404 still leaves the tag created or
+ renamed. The `users` and `companies` arrays in the response are always
+ empty when this field is used.
+ items:
+ type: string
+ example:
+ - 536e564f316c83104c000020
+ taggable_type:
+ type: string
+ description: Whether the ids in `ids_to_add` are contacts or companies.
+ Defaults to `user`.
+ enum:
+ - user
+ - company
+ example: user
required:
- name
create_phone_switch_request:
@@ -41942,7 +42429,7 @@ components:
id:
type: string
description: The id of the job that's currently being processed or has completed.
- example: 20
+ example: '20'
url:
type: string
description: API endpoint URL to check the job status.
@@ -41960,13 +42447,13 @@ components:
example: ticket
resource_id:
type: string
- description: The id of the resource created during job execution (e.g. ticket id)
- example: 123
+ description: The id of the resource created during job execution (e.g. ticket id). Only set once the job has succeeded.
+ example: '123'
nullable: true
resource_url:
type: string
- description: The url of the resource created during job exeuction. Use this url to fetch the resource.
- example: http://api.intercom.io/tickets/123
+ description: The url of the resource created during job execution. Use this url to fetch the resource. Only set once the job has succeeded.
+ example: https://api.intercom.io/tickets/123
nullable: true
required:
- id
@@ -42932,8 +43419,13 @@ components:
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.
+ type: object
+ nullable: true
+ description: Represents the Admin that created the note. When the note has
+ no recorded admin, this is `null` on a single note and left out of each
+ note in a list.
+ allOf:
+ - "$ref": "#/components/schemas/admin"
body:
type: string
description: The body text of the note.
@@ -42942,6 +43434,7 @@ components:
title: Paginated Response
type: object
description: A paginated list of notes associated with a contact or a company.
+ On the last page, `pages.next` is `null`. These lists never send `pages.prev`.
properties:
type:
type: string
@@ -42958,7 +43451,7 @@ components:
description: A count of the total number of notes.
example: 1
pages:
- "$ref": "#/components/schemas/cursor_pages"
+ "$ref": "#/components/schemas/pages_link"
open_conversation_request:
title: Open Conversation Request
type: object
@@ -43285,14 +43778,15 @@ components:
count:
type: integer
description: The number of items in the user segment. It's returned when
- `include_count=true` is included in the request.
+ the request has `include_count` with a value. A company segment only gets
+ a count when a contact segment has the same name, and it shows that
+ segment's count.
example: 3
nullable: true
segment_list:
title: Segment List
type: object
- description: This will return a list of Segment Objects. The result may also
- have a pages object if the response is paginated.
+ description: This will return a list of Segment Objects. The list is not paginated.
properties:
type:
type: string
@@ -43305,10 +43799,6 @@ components:
description: A list of Segment objects
items:
"$ref": "#/components/schemas/segment"
- pages:
- type: object
- description: A pagination object, which may be empty, indicating no further
- pages to fetch.
single_filter_search_request:
title: Single Filter Search Request
description: Search using Intercoms Search APIs with a single filter.
@@ -43531,7 +44021,7 @@ components:
example: Test tag
applied_at:
type: integer
- format: date-time
+ format: timestamp
nullable: true
description: The time when the tag was applied to the object. Only present when the tag is returned as part of a tagging operation on a contact, conversation, ticket, article, internal article, or content snippet, when listing the tags on a contact, or when it is returned as part of an external page. `null` when the tag has just been removed from an article, internal article, content snippet or external page. Removing a tag from a contact, conversation or ticket returns the original value.
example: 1663597223
@@ -43608,7 +44098,9 @@ components:
properties:
name:
type: string
- description: The name of the tag, which will be created if not found.
+ maxLength: 191
+ description: The name of the tag, which will be created if not found. Names
+ can be at most 191 characters long.
example: Independent
companies:
type: array
@@ -43622,8 +44114,13 @@ components:
type: string
description: The company id you have defined for the company.
example: '6'
- description: The id or company_id of the company can be passed as input
- parameters.
+ name:
+ type: string
+ description: The name of the company, used to look it up when neither
+ `id` nor `company_id` is given.
+ example: Intercom
+ description: The id, company_id or name of the company can be passed as
+ input parameters. Companies that cannot be found are skipped.
required:
- name
- companies
@@ -43644,22 +44141,41 @@ components:
items:
"$ref": "#/components/schemas/tag"
tag_multiple_users_request:
- description: You can tag a list of users.
+ description: You can tag or untag a list of users.
type: object
title: Tag Users Request Payload
properties:
name:
type: string
- description: The name of the tag, which will be created if not found.
+ maxLength: 191
+ description: The name of the tag, which will be created if not found. Names
+ can be at most 191 characters long.
example: Independent
users:
type: array
+ description: The id, user_id or email of the user can be passed as input
+ parameters. Users that cannot be found are skipped.
items:
properties:
id:
type: string
description: The Intercom defined id representing the user.
example: 5f7f0d217289f8d2f4262080
+ user_id:
+ type: string
+ description: The user id you have defined for the user, used to look
+ it up when `id` is not given.
+ example: '25'
+ email:
+ type: string
+ description: The email address of the user, used to look it up when
+ neither `id` nor `user_id` is given.
+ example: jane@example.com
+ untag:
+ type: boolean
+ description: Set to true to remove the tag from this user instead
+ of applying it.
+ example: true
required:
- name
- users
@@ -44598,7 +45114,9 @@ components:
properties:
name:
type: string
- description: The name of the tag which will be untagged from the company
+ maxLength: 191
+ description: The name of the tag which will be untagged from the company.
+ Names can be at most 191 characters long.
example: Independent
companies:
type: array
@@ -44612,12 +45130,19 @@ components:
type: string
description: The company id you have defined for the company.
example: '6'
+ name:
+ type: string
+ description: The name of the company, used to look it up when neither
+ `id` nor `company_id` is given.
+ example: Intercom
untag:
type: boolean
description: Always set to true
- example: 'true'
- description: The id or company_id of the company can be passed as input
- parameters.
+ example: true
+ required:
+ - untag
+ description: The id, company_id or name of the company can be passed as
+ input parameters. Companies that cannot be found are skipped.
required:
- name
- companies