Text for the note.
" + url: "/companies/6762f07f1bb69f9f2193baf5/notes" + total_count: 1 has_more: false plan: {} custom_attributes: {} @@ -6533,6 +6609,28 @@ paths: oneOf: - "$ref": "#/components/schemas/company" - "$ref": "#/components/schemas/company_list" + - "$ref": "#/components/schemas/company_user_list" + '400': + description: Bad Request + content: + application/json: + examples: + Per page too big: + value: + type: error.list + request_id: 4a0e1b25-bd6f-4e92-be70-5f612c839ea4 + errors: + - code: parameter_invalid + message: Per Page is too big + Page limit reached: + value: + type: error.list + request_id: 5b1f2c36-ce70-4fa3-cf81-6a723d94afb5 + errors: + - code: bad_request + message: page limit reached, please use scroll API + schema: + "$ref": "#/components/schemas/error" '404': description: Company Not Found content: @@ -6561,6 +6659,20 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" + '503': + description: Service Unavailable + content: + application/json: + examples: + Search temporarily unavailable: + value: + type: error.list + request_id: 6c2a3d47-df81-40b4-d092-7b834ea5b0c6 + errors: + - code: service_unavailable + message: Feature temporarily unavailable + schema: + "$ref": "#/components/schemas/error" "/companies/{id}": get: summary: Retrieve a company by ID @@ -6576,6 +6688,37 @@ paths: example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632 schema: type: string + - name: type + in: query + required: false + description: Set to `user` or `users` to return the company's users instead + of the company. The response is then a `user.list` object with a `users` + array in the legacy user format. + example: users + schema: + type: string + enum: + - user + - users + - name: page + in: query + required: false + description: The page of users to fetch. Used only when `type` is `user` or + `users`. Defaults to first page. There is a limit of 10,000 users; a `page` + and `per_page` that go past it return a `400` error with code `bad_request`. + example: 1 + schema: + type: integer + - name: per_page + in: query + required: false + description: How many users to return per page. Used only when `type` is `user` + or `users`. Defaults to 50. A value above 60 returns a `400` error with code + `parameter_invalid`. + example: 50 + schema: + type: integer + maximum: 60 tags: - Companies operationId: RetrieveACompanyById @@ -6608,13 +6751,36 @@ paths: notes: type: note.list data: [] - url: "/companies/6762f0761bb69f9f2193bae2/notes" + url: "/companies/6762f07f1bb69f9f2193baf5/notes" total_count: 0 has_more: false plan: {} custom_attributes: {} schema: - "$ref": "#/components/schemas/company" + oneOf: + - "$ref": "#/components/schemas/company" + - "$ref": "#/components/schemas/company_user_list" + '400': + description: Bad Request + content: + application/json: + examples: + Per page too big: + value: + type: error.list + request_id: ebc33a9a-9163-41a5-8ac3-fde3d8098bf7 + errors: + - code: parameter_invalid + message: Per Page is too big + Page limit reached: + value: + type: error.list + request_id: b739b9c2-ed4a-46f2-9fe9-3e2e7ba028fa + errors: + - code: bad_request + message: page limit reached, please use scroll API + schema: + "$ref": "#/components/schemas/error" '404': description: Company Not Found content: @@ -6663,9 +6829,15 @@ paths: description: | You can update a single company using the Intercom provisioned `id`. + Every custom attribute you send must already exist in your workspace. Sending one that doesn't returns a `400` error. + + You can also send this request with `PATCH`; it behaves the same as `PUT`. + {% admonition type="warning" name="Using `company_id`" %} When updating a company it is not possible to update `company_id`. This can only be set once upon creation of the company. {% /admonition %} + + Requires the `write_users_companies` OAuth scope. requestBody: content: application/json: @@ -6712,6 +6884,27 @@ paths: custom_attributes: {} schema: "$ref": "#/components/schemas/company" + '400': + description: Bad Request + content: + application/json: + examples: + Custom attribute does not exist: + value: + type: error.list + request_id: 7d3b4e58-e092-41c5-e1a3-8c945fb6c1d7 + errors: + - code: parameter_invalid + message: Custom attribute 'plan_tier' does not exist + Custom attribute value is an object: + value: + type: error.list + request_id: 8e4c5f69-f1a3-42d6-f2b4-9da56ac7d2e8 + errors: + - code: nested_custom_attributes + message: Cannot submit an object as a custom attribute value + schema: + "$ref": "#/components/schemas/error" '404': description: Company Not Found content: @@ -6738,6 +6931,27 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 9f5d6a7a-02b4-43e7-a3c5-aeb67bd8e3f9 + errors: + - code: token_unauthorized + message: Not authorized to access resource + schema: + "$ref": "#/components/schemas/error" + '422': + description: Unprocessable Entity + content: + application/json: + examples: + Monthly spend out of range: + value: + type: error.list + request_id: b93c392a-918e-4fdf-bf6a-73554a31106c + errors: + - code: unprocessable_entity + message: monthly_spend has to be in range [-2147483648, 2147483647] schema: "$ref": "#/components/schemas/error" delete: @@ -6760,11 +6974,15 @@ paths: description: | Delete a single company. - The company record is kept in your workspace, but all contacts are detached. The contacts themselves are not deleted. Detaching contacts is permanent and can't be reversed. A `company.deleted` webhook is sent when the company is deleted. These changes may take some time to be reflected in your workspace. + The company record is kept in your workspace, but all contacts are detached. The contacts themselves are not deleted. Detaching contacts is permanent and can't be reversed. These changes may take some time to be reflected in your workspace. + + The response returns `"deleted": true` as soon as the request is accepted; the contacts are detached in the background. A `company.deleted` webhook is sent after that work finishes, so it arrives some time after the response. No webhook is sent for a company that has no contacts attached, because there is nothing to detach. {% admonition type="warning" %} Third-party integrations that sync companies into Intercom (for example, Salesforce or Chargebee) will recreate any company deleted through this endpoint on their next sync. To prevent recreation, remove or filter the company at the source integration before deleting it via the API. {% /admonition %} + + Requires the `write_users_companies` OAuth scope. responses: '200': description: Successful @@ -6804,6 +7022,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: a06e7b8b-13c5-44f8-b4d6-bfc78ce9f40a + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" "/companies/{id}/contacts": @@ -6821,11 +7046,36 @@ paths: example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632 schema: type: string + - name: per_page + in: query + required: false + description: How many contacts to return per page. Defaults to 50. + example: 50 + schema: + type: integer + - name: starting_after + in: query + required: false + description: The cursor to fetch the next page of contacts. Use the `starting_after` + value from `pages.next` in the previous response. + schema: + type: string + - name: include_merge_history + in: query + required: false + description: Set to `true` to include each contact's `merge_history`. Any + other value omits it. + example: 'true' + schema: + type: string tags: - Companies - Contacts operationId: ListAttachedContacts - description: You can fetch a list of all contacts that belong to a company. + description: | + You can fetch a list of all contacts that belong to a company. + + Requires the `read_users_companies` OAuth scope. responses: '200': description: Successful @@ -6844,6 +7094,21 @@ paths: total_pages: 0 schema: "$ref": "#/components/schemas/company_attached_contacts" + '400': + description: Bad Request + content: + application/json: + examples: + Invalid starting_after: + value: + type: error.list + request_id: b17f8a9b-139c-4418-b4e6-bfd79cf9040a + errors: + - code: client_error + message: Invalid starting_after param. Please try again using + a starting_after value from a paginated response + schema: + "$ref": "#/components/schemas/error" '404': description: Company Not Found content: @@ -6870,6 +7135,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: c281819c-24d6-4509-c5e7-c0d89adfa51b + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" "/companies/{id}/segments": @@ -6890,7 +7162,10 @@ paths: tags: - Companies operationId: ListAttachedSegmentsForCompanies - description: You can fetch a list of all segments that belong to a company. + description: | + You can fetch a list of all segments that belong to a company. + + Requires the `read_users_companies` OAuth scope. responses: '200': description: Successful @@ -6929,6 +7204,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: d392920d-35e7-461a-d6f8-d1e90be0b62c + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" "/companies/{company_id}/notes": @@ -7207,6 +7489,12 @@ paths: ### Sorting Pass an optional `sort` object with a `field` and an `order` (`ascending` or `descending`; defaults to `descending`) to order the results. An invalid `order` returns a `400` error with code `invalid_sort_order`. `tag_id` can be used as a filter but not as a sort field. + + ### Pagination + + Pass an optional `pagination` object with `per_page` and `starting_after`. `per_page` defaults to 15 and must be between 1 and 150; anything else returns a `400` error with code `invalid_per_page`. Take `starting_after` from `pages.next` in the previous response, and send it with the same `sort` you used for that response. A cursor from a sort on a text field such as `name`, sent with a sort on a number or date field (or the other way round), returns a `400` error with code `client_error`. Leaving out `sort` sorts by `last_request_at`, a date. A cursor sent with a different sort of the same kind is accepted, but the page it returns doesn't follow on from the previous one. + + Requires the `read_users_companies` OAuth scope. responses: '200': description: successful @@ -7224,7 +7512,7 @@ paths: per_page: 5 total_pages: 0 schema: - "$ref": "#/components/schemas/company_list" + "$ref": "#/components/schemas/company_search_response" '401': description: Unauthorized content: @@ -7237,6 +7525,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: e4a3a31e-46f8-422b-e709-e2fa1cf1c73d + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" '400': @@ -7251,6 +7546,58 @@ paths: errors: - code: invalid_field message: "segment_id is not a valid search field" + Invalid sort order: + value: + type: error.list + request_id: f5b4b42f-5709-433c-f81a-f30b2da2d84e + errors: + - code: invalid_sort_order + message: "Invalid sort order 'sideways'. Must be one of: ascending, + descending" + Sort is not an object: + value: + type: error.list + request_id: 06c5c530-681a-444d-092b-041c3eb3e95f + errors: + - code: client_error + message: Invalid sort parameter. Expected an object with 'field' + and 'order'. + Pagination is not an object: + value: + type: error.list + request_id: 17d6d641-792b-455e-1a3c-152d4fc4fa60 + errors: + - code: client_error + message: Invalid pagination parameter. Expected an object. + Per page out of range: + value: + type: error.list + request_id: 4a09095a-ac5e-4882-4d6f-485072f72d93 + errors: + - code: invalid_per_page + message: per_page must be an integer between 0 and 150 + Cursor does not match the sort: + value: + type: error.list + request_id: 28e7e752-8a3c-4660-2b4d-263e50d50b71 + errors: + - code: client_error + message: Invalid starting_after param. Please try again using + a starting_after value from a paginated response + schema: + "$ref": "#/components/schemas/error" + '503': + description: Service Unavailable + content: + application/json: + examples: + Search temporarily unavailable: + value: + type: error.list + request_id: 39f8f863-9b4d-4771-3c5e-374f61e61c82 + errors: + - code: service_unavailable + message: Feature temporarily unavailable schema: "$ref": "#/components/schemas/error" requestBody: @@ -7291,18 +7638,24 @@ paths: - name: per_page in: query required: false - description: How many results to return per page. Defaults to 15 + description: How many results to return per page. Defaults to 15. A value + above 60 returns a `400` error with code `parameter_invalid`. example: 15 schema: type: integer + maximum: 60 - name: order in: query required: false description: "`asc` or `desc`. Return the companies in ascending or descending - order. Defaults to desc" + order. Defaults to desc. Any other value returns a `400` error with code + `parameter_invalid`." example: desc schema: type: string + enum: + - asc + - desc tags: - Companies operationId: listAllCompanies @@ -7311,11 +7664,13 @@ paths: Note that the API does not include companies who have no associated users in list responses. - When using the Companies endpoint and the pages object to iterate through the returned companies, there is a limit of 10,000 Companies that can be returned. If you need to list or iterate on more than 10,000 Companies, please use the [Scroll API](https://developers.intercom.com/reference#iterating-over-all-companies). + When using the Companies endpoint and the pages object to iterate through the returned companies, there is a limit of 10,000 Companies that can be returned. If you need to list or iterate on more than 10,000 Companies, please use the [Scroll API](https://developers.intercom.com/reference#iterating-over-all-companies). Going past that limit returns a `400` error with code `bad_request`. {% admonition type="warning" name="Pagination" %} - 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. + This endpoint pages by page number, not by cursor. Use the `page` and `per_page` query parameters, and the `page`, `total_pages` and `next` values in the `pages` object of the response. The default is `15` 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. {% /admonition %} + + Requires the `write_users_companies` OAuth scope. A token with only read scopes cannot call this endpoint. responses: '200': description: Successful @@ -7360,6 +7715,27 @@ paths: total_count: 1 schema: "$ref": "#/components/schemas/company_list" + '400': + description: Bad Request + content: + application/json: + examples: + Per page too big: + value: + type: error.list + request_id: 5b1a1a6b-bd6f-4993-5e70-5961830833a4 + errors: + - code: parameter_invalid + message: Per Page is too big + Page limit reached: + value: + type: error.list + request_id: 7d3c3c8d-df81-4bb5-7092-7b83a52a55c6 + errors: + - code: bad_request + message: page limit reached, please use scroll API + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -7372,6 +7748,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 8e4d4d9e-e092-4cc6-81a3-8c94b63b66d7 + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" "/companies/scroll": @@ -7385,7 +7768,9 @@ paths: - name: scroll_param in: query required: false - description: '' + description: The `scroll_param` from the previous response. Omit it to start + a new scroll. + example: 69352cd2-ab5b-42ac-b004-a13d4e55e9b0 schema: type: string tags: @@ -7394,9 +7779,11 @@ paths: description: |2 The `list all companies` functionality does not work well for huge datasets, and can result in errors and performance problems when paging deeply. The Scroll API provides an efficient mechanism for iterating over all companies in a dataset. - - Each app can only have 1 scroll open at a time. You'll get an error message if you try to have more than one open per app. - - If the scroll isn't used for 1 minute, it expires and calls with that scroll param will fail - - If the end of the scroll is reached, "companies" will be empty and the scroll parameter will expire + - Each app can only have 1 scroll open at a time. Starting a second one returns a `400` error with code `scroll_exists`. + - If the scroll isn't used for 1 minute, it expires and calls with that scroll param return a `404` error with code `not_found`. + - If the end of the scroll is reached, `data` will be empty and the scroll parameter will expire. + + The response always has `pages` and `total_count` set to `null`. Use `scroll_param` to fetch the next page. {% admonition type="info" name="Scroll Parameter" %} You can get the first page of companies by simply sending a GET request to the scroll endpoint. @@ -7407,6 +7794,8 @@ paths: "Request failed due to an internal network error. Please restart the scroll operation." If this happens, you will need to restart your scroll query: It is not possible to continue from a specific point when using scroll. {% /admonition %} + + Requires the `read_users_companies` OAuth scope. responses: '200': description: Successful @@ -7447,6 +7836,34 @@ paths: scroll_param: 69352cd2-ab5b-42ac-b004-a13d4e55e9b0 schema: "$ref": "#/components/schemas/company_scroll" + '400': + description: Bad Request + content: + application/json: + examples: + Scroll already open: + value: + type: error.list + request_id: 9f5e5eaf-f1a3-4dd7-92b4-9da5c74c77e8 + errors: + - code: scroll_exists + message: scroll already exists for this workspace + schema: + "$ref": "#/components/schemas/error" + '404': + description: Scroll Parameter Not Found + content: + application/json: + examples: + Scroll parameter not found: + value: + type: error.list + request_id: a06f6fb0-02b4-4ee8-a3c5-aeb6d85d88f9 + errors: + - code: not_found + message: scroll parameter not found + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -7459,6 +7876,27 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: b17a7ac1-13c5-4ff9-b4d6-bfc7e96e99fa + errors: + - code: token_unauthorized + message: Not authorized to access resource + schema: + "$ref": "#/components/schemas/error" + '503': + description: Service Unavailable + content: + application/json: + examples: + Scroll temporarily unavailable: + value: + type: error.list + request_id: c28b8bd2-24d6-40aa-c5e7-c0d8fa7faa0b + errors: + - code: service_unavailable + message: Feature temporarily unavailable schema: "$ref": "#/components/schemas/error" "/contacts/{id}/companies": @@ -34627,7 +35065,8 @@ components: example: 531ee472cce572a6ec000006 name: type: string - description: The name of the company. + description: The name of the company. Returned HTML-escaped, for example + `&` as `&`. example: Blue Sun app_id: type: string @@ -34651,7 +35090,8 @@ components: example: Pro company_id: type: string - description: The company id you have defined for the company. + description: The company id you have defined for the company. Returned HTML-escaped, + for example `&` as `&`. example: '6' remote_created_at: type: integer @@ -34722,7 +35162,8 @@ components: "$ref": "#/components/schemas/tag_basic" segments: type: object - description: The list of segments associated with the company + description: Always returned empty. Fetch a company's segments with the + list attached segments endpoint. properties: type: type: string @@ -34742,10 +35183,24 @@ components: description: The type of the object enum: - note.list - notes: + data: type: array + description: The notes on the company, newest first. items: "$ref": "#/components/schemas/company_note" + url: + type: string + description: The relative URL of the company's notes. + example: "/companies/531ee472cce572a6ec000006/notes" + total_count: + type: integer + description: The number of notes in `data`. + example: 1 + has_more: + type: boolean + description: Always `false`. Every note on the company is returned in + `data`. + example: false company_attached_contacts: title: Company Attached Contacts type: object @@ -34787,7 +35242,30 @@ components: company_list: title: Companies type: object - description: This will return a list of companies for the App. + description: This will return a list of companies for the App. On the last page, + `pages.next` is `null`. + properties: + type: + type: string + description: The type of object - `list`. + enum: + - list + example: list + pages: + "$ref": "#/components/schemas/pages_link" + total_count: + type: integer + description: The total number of companies. + example: 100 + data: + type: array + description: An array containing Company Objects. + items: + "$ref": "#/components/schemas/company" + company_search_response: + title: Company Search Response + type: object + description: This will return a list of companies matching a search query. properties: type: type: string @@ -34825,17 +35303,47 @@ components: items: "$ref": "#/components/schemas/company" pages: - "$ref": "#/components/schemas/cursor_pages" + type: object + description: Always `null`. Page through a scroll with `scroll_param` instead. + nullable: true total_count: type: integer - description: The total number of companies + description: Always `null`. The scroll endpoint does not count the companies + it returns. nullable: true - example: 100 scroll_param: type: string description: The scroll parameter to use in the next request to fetch the next page of results. example: 25b649f7-4d33-4ef6-88f5-60e5b8244309 + company_user_list: + title: Company Users + type: object + description: The contacts attached to one company, returned when `type` is `user` + or `users` and the request names a single company. Contacts are in the legacy + user format. On the last page, `pages.next` is `null`. + properties: + type: + type: string + description: The type of object - `user.list`. + enum: + - user.list + example: user.list + users: + type: array + description: The contacts attached to the company, in the legacy user format. + items: + type: object + pages: + "$ref": "#/components/schemas/pages_link" + total_count: + type: integer + description: The total number of contacts attached to the company. + example: 1 + limited: + type: boolean + description: Always `false` for this list. + example: false contact: title: Contact type: object @@ -39220,17 +39728,23 @@ components: create_or_update_company_request: type: object title: Create Or Update Company Request Payload - description: You can create or update a Company + description: You can create or update a Company. Send either `company_id` or + `id`; a request with neither returns a `400` error. nullable: true properties: name: type: string - description: The name of the Company + description: The name of the Company. Leading and trailing whitespace is + removed. example: Intercom company_id: type: string description: The company id you have defined for the company. Can't be updated example: 625e90fc55ab113b6d92175f + id: + type: string + description: An alternative name for `company_id`. Supply this or `company_id`. + example: 625e90fc55ab113b6d92175f plan: type: string description: The name of the plan you have associated with the company. @@ -39270,10 +39784,10 @@ components: example: 1394531169 monthly_spend: type: integer - description: How much revenue the company generates for your business. Note - that this will truncate floats. i.e. it only allow for whole integers, - 155.98 will be truncated to 155. Note that this has an upper limit of - 2**31-1 or 2147483647.. + description: How much revenue the company generates for your business. Floats + are truncated to whole integers, so 155.98 is stored as 155. A value above + 2147483647 (2**31-1) is stored as 0. 2147483647 itself, or a value of -2147483648 + or below, returns a `422` error. example: 1000 update_last_request_at: type: boolean @@ -39287,8 +39801,13 @@ components: properties: name: type: string - description: The name of the Company + description: The name of the Company. Leading and trailing whitespace is + removed. example: Intercom + update_last_request_at: + type: boolean + description: Set to true to update the company's last seen time to now. + example: true plan: type: string description: The name of the plan you have associated with the company. @@ -39328,15 +39847,11 @@ components: example: 1394531169 monthly_spend: type: integer - description: How much revenue the company generates for your business. Note - that this will truncate floats. i.e. it only allow for whole integers, - 155.98 will be truncated to 155. Note that this has an upper limit of - 2**31-1 or 2147483647.. + description: How much revenue the company generates for your business. Floats + are truncated to whole integers, so 155.98 is stored as 155. A value above + 2147483647 (2**31-1) is stored as 0. 2147483647 itself, or a value of -2147483648 + or below, returns a `422` error. example: 1000 - update_last_request_at: - type: boolean - description: Set to true to update the company's last seen time to now. - example: true create_or_update_custom_object_instance_request: description: Payload to create or update a Custom Object instance type: object @@ -42192,7 +42707,8 @@ components: example: company deleted: type: boolean - description: Whether the company was deleted successfully or not. + description: Always `true`. The contacts are detached after the response + is sent. example: true deleted_object: title: Deleted Object @@ -45554,7 +46070,8 @@ components: type: object x-tags: - Notes - description: Notes allow you to annotate and comment on companies. + description: A note as it appears inside a company's `notes` list. Fetch the + full note with the retrieve note endpoint. properties: type: type: string @@ -45565,28 +46082,10 @@ components: type: string description: The id of the note. example: '17495962' - created_at: - type: integer - format: timestamp - description: The time the note was created. - example: 1674589321 - 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`. - example: company - id: - type: string - description: The id of the company. - example: 6329bd9ffe4e2e91dac76188 - author: - "$ref": "#/components/schemas/admin" - description: Optional. Represents the Admin that created the note. + url: + type: string + description: The relative URL of the note. + example: "/notes/17495962" body: type: string description: The body text of the note. diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index 811bb4c0..28dcb8e5 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -7581,9 +7581,15 @@ paths: Companies are looked up via `company_id` in a `POST` request, if not found via `company_id`, the new company will be created, if found, that company will be updated. + You must send either `company_id` or `id`. A request with neither returns a `400` error. + + Every custom attribute you send must already exist in your workspace. Sending one that doesn't returns a `400` error. + {% admonition type="warning" name="Using `company_id`" %} You can set a unique `company_id` value when creating a company. However, it is not possible to update `company_id`. Be sure to set a unique value once upon creation of the company. {% /admonition %} + + Requires the `write_users_companies` OAuth scope. responses: '200': description: Successful @@ -7612,6 +7618,12 @@ paths: plan: {} custom_attributes: industry: manufacturing + notes: + type: note.list + data: [] + url: "/companies/6762f0761bb69f9f2193bae2/notes" + total_count: 0 + has_more: false schema: "$ref": "#/components/schemas/company" '400': @@ -7626,6 +7638,34 @@ paths: errors: - code: bad_request message: bad 'test' parameter + Missing company_id: + value: + type: error.list + request_id: 0c6a6de1-7f2b-4a5e-9a3c-1b2d8e4f5a60 + errors: + - code: bad_request + message: missing 'company_id' parameter + Custom attribute does not exist: + value: + type: error.list + request_id: 1d7b7ef2-8a3c-4b6f-8b4d-2c3e9f506b71 + errors: + - code: parameter_invalid + message: Custom attribute 'plan_tier' does not exist + Custom attribute value is an object: + value: + type: error.list + request_id: 2e8c8f03-9b4d-4c70-9c5e-3d4f0a617c82 + errors: + - code: nested_custom_attributes + message: Cannot submit an object as a custom attribute value + Company is not an object: + value: + type: error.list + request_id: + errors: + - code: 422 + message: invalid company data structure schema: "$ref": "#/components/schemas/error" '401': @@ -7640,6 +7680,27 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 3f9d9014-ac5e-4d81-ad6f-4e501b728d93 + errors: + - code: token_unauthorized + message: Not authorized to access resource + schema: + "$ref": "#/components/schemas/error" + '422': + description: Unprocessable Entity + content: + application/json: + examples: + Monthly spend out of range: + value: + type: error.list + request_id: 3dfc2c5e-fe80-460e-9b42-765c2835beeb + errors: + - code: unprocessable_entity + message: monthly_spend has to be in range [-2147483648, 2147483647] schema: "$ref": "#/components/schemas/error" requestBody: @@ -7693,6 +7754,19 @@ paths: example: '98765' schema: type: string + - name: type + in: query + required: false + description: Set to `user` or `users`, together with `company_id` or `name`, + to return that company's users instead of the company. The response is then + a `user.list` object with a `users` array in the legacy user format, paged + with `page` and `per_page` (default 50). + example: users + schema: + type: string + enum: + - user + - users - name: page in: query required: false @@ -7703,10 +7777,12 @@ paths: - name: per_page in: query required: false - description: How many results to display per page. Defaults to 15 + description: How many results to display per page. Defaults to 15. A value + above 60 returns a `400` error with code `parameter_invalid`. example: 15 schema: type: integer + maximum: 60 tags: - Companies operationId: retrieveCompany @@ -7722,6 +7798,8 @@ paths: `https://api.intercom.io/companies?tag_id={tag_id}` `https://api.intercom.io/companies?segment_id={segment_id}` + + The list is paged by page number. There is a limit of 10,000 companies; beyond that the request returns a `400` error and you should use the scroll endpoint instead. responses: '200': description: Successful @@ -7751,6 +7829,12 @@ paths: segments: [] plan: {} custom_attributes: {} + notes: + type: note.list + data: [] + url: "/companies/6762f07a1bb69f9f2193baea/notes" + total_count: 0 + has_more: false pages: type: pages next: @@ -7779,10 +7863,42 @@ paths: segments: [] plan: {} custom_attributes: {} + notes: + type: note.list + data: + - id: '17495962' + type: note + url: "/notes/17495962" + body: "Text for the note.
" + url: "/companies/6762f07f1bb69f9f2193baf5/notes" + total_count: 1 + has_more: false schema: oneOf: - "$ref": "#/components/schemas/company" - "$ref": "#/components/schemas/company_list" + - "$ref": "#/components/schemas/company_user_list" + '400': + description: Bad Request + content: + application/json: + examples: + Per page too big: + value: + type: error.list + request_id: 4a0e1b25-bd6f-4e92-be70-5f612c839ea4 + errors: + - code: parameter_invalid + message: Per Page is too big + Page limit reached: + value: + type: error.list + request_id: 5b1f2c36-ce70-4fa3-cf81-6a723d94afb5 + errors: + - code: bad_request + message: page limit reached, please use scroll API + schema: + "$ref": "#/components/schemas/error" '404': description: Company Not Found content: @@ -7811,6 +7927,20 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" + '503': + description: Service Unavailable + content: + application/json: + examples: + Search temporarily unavailable: + value: + type: error.list + request_id: 6c2a3d47-df81-40b4-d092-7b834ea5b0c6 + errors: + - code: service_unavailable + message: Feature temporarily unavailable + schema: + "$ref": "#/components/schemas/error" "/companies/{company_id}": get: summary: Retrieve a company by ID @@ -7826,6 +7956,37 @@ paths: example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632 schema: type: string + - name: type + in: query + required: false + description: Set to `user` or `users` to return the company's users instead + of the company. The response is then a `user.list` object with a `users` + array in the legacy user format. + example: users + schema: + type: string + enum: + - user + - users + - name: page + in: query + required: false + description: The page of users to fetch. Used only when `type` is `user` or + `users`. Defaults to first page. There is a limit of 10,000 users; a `page` + and `per_page` that go past it return a `400` error with code `bad_request`. + example: 1 + schema: + type: integer + - name: per_page + in: query + required: false + description: How many users to return per page. Used only when `type` is `user` + or `users`. Defaults to 50. A value above 60 returns a `400` error with code + `parameter_invalid`. + example: 50 + schema: + type: integer + maximum: 60 tags: - Companies operationId: RetrieveACompanyById @@ -7857,8 +8018,37 @@ paths: segments: [] plan: {} custom_attributes: {} + notes: + type: note.list + data: [] + url: "/companies/6762f07f1bb69f9f2193baf5/notes" + total_count: 0 + has_more: false schema: - "$ref": "#/components/schemas/company" + oneOf: + - "$ref": "#/components/schemas/company" + - "$ref": "#/components/schemas/company_user_list" + '400': + description: Bad Request + content: + application/json: + examples: + Per page too big: + value: + type: error.list + request_id: ebc33a9a-9163-41a5-8ac3-fde3d8098bf7 + errors: + - code: parameter_invalid + message: Per Page is too big + Page limit reached: + value: + type: error.list + request_id: b739b9c2-ed4a-46f2-9fe9-3e2e7ba028fa + errors: + - code: bad_request + message: page limit reached, please use scroll API + schema: + "$ref": "#/components/schemas/error" '404': description: Company Not Found content: @@ -7907,9 +8097,15 @@ paths: description: | You can update a single company using the Intercom provisioned `id`. + Every custom attribute you send must already exist in your workspace. Sending one that doesn't returns a `400` error. + + You can also send this request with `PATCH`; it behaves the same as `PUT`. + {% admonition type="warning" name="Using `company_id`" %} When updating a company it is not possible to update `company_id`. This can only be set once upon creation of the company. {% /admonition %} + + Requires the `write_users_companies` OAuth scope. requestBody: content: application/json: @@ -7952,8 +8148,35 @@ paths: segments: [] plan: {} custom_attributes: {} + notes: + type: note.list + data: [] + url: "/companies/6762f0841bb69f9f2193baff/notes" + total_count: 0 + has_more: false schema: "$ref": "#/components/schemas/company" + '400': + description: Bad Request + content: + application/json: + examples: + Custom attribute does not exist: + value: + type: error.list + request_id: 7d3b4e58-e092-41c5-e1a3-8c945fb6c1d7 + errors: + - code: parameter_invalid + message: Custom attribute 'plan_tier' does not exist + Custom attribute value is an object: + value: + type: error.list + request_id: 8e4c5f69-f1a3-42d6-f2b4-9da56ac7d2e8 + errors: + - code: nested_custom_attributes + message: Cannot submit an object as a custom attribute value + schema: + "$ref": "#/components/schemas/error" '404': description: Company Not Found content: @@ -7980,6 +8203,27 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 9f5d6a7a-02b4-43e7-a3c5-aeb67bd8e3f9 + errors: + - code: token_unauthorized + message: Not authorized to access resource + schema: + "$ref": "#/components/schemas/error" + '422': + description: Unprocessable Entity + content: + application/json: + examples: + Monthly spend out of range: + value: + type: error.list + request_id: b93c392a-918e-4fdf-bf6a-73554a31106c + errors: + - code: unprocessable_entity + message: monthly_spend has to be in range [-2147483648, 2147483647] schema: "$ref": "#/components/schemas/error" delete: @@ -8002,11 +8246,15 @@ paths: description: | Delete a single company. - The company record is kept in your workspace, but all contacts are detached. The contacts themselves are not deleted. Detaching contacts is permanent and can't be reversed. A `company.deleted` webhook is sent when the company is deleted. These changes may take some time to be reflected in your workspace. + The company record is kept in your workspace, but all contacts are detached. The contacts themselves are not deleted. Detaching contacts is permanent and can't be reversed. These changes may take some time to be reflected in your workspace. + + The response returns `"deleted": true` as soon as the request is accepted; the contacts are detached in the background. A `company.deleted` webhook is sent after that work finishes, so it arrives some time after the response. No webhook is sent for a company that has no contacts attached, because there is nothing to detach. {% admonition type="warning" %} Third-party integrations that sync companies into Intercom (for example, Salesforce or Chargebee) will recreate any company deleted through this endpoint on their next sync. To prevent recreation, remove or filter the company at the source integration before deleting it via the API. {% /admonition %} + + Requires the `write_users_companies` OAuth scope. responses: '200': description: Successful @@ -8046,6 +8294,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: a06e7b8b-13c5-44f8-b4d6-bfc78ce9f40a + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" "/companies/{company_id}/contacts": @@ -8063,11 +8318,36 @@ paths: example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632 schema: type: string + - name: per_page + in: query + required: false + description: How many contacts to return per page. Defaults to 50. + example: 50 + schema: + type: integer + - name: starting_after + in: query + required: false + description: The cursor to fetch the next page of contacts. Use the `starting_after` + value from `pages.next` in the previous response. + schema: + type: string + - name: include_merge_history + in: query + required: false + description: Set to `true` to include each contact's `merge_history`. Any + other value omits it. + example: 'true' + schema: + type: string tags: - Companies - Contacts operationId: ListAttachedContacts - description: You can fetch a list of all contacts that belong to a company. + description: | + You can fetch a list of all contacts that belong to a company. + + Requires the `read_users_companies` OAuth scope. responses: '200': description: Successful @@ -8086,6 +8366,21 @@ paths: total_pages: 0 schema: "$ref": "#/components/schemas/company_attached_contacts" + '400': + description: Bad Request + content: + application/json: + examples: + Invalid starting_after: + value: + type: error.list + request_id: b17f8a9b-139c-4418-b4e6-bfd79cf9040a + errors: + - code: client_error + message: Invalid starting_after param. Please try again using + a starting_after value from a paginated response + schema: + "$ref": "#/components/schemas/error" '404': description: Company Not Found content: @@ -8112,6 +8407,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: c281819c-24d6-4509-c5e7-c0d89adfa51b + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" "/companies/{company_id}/segments": @@ -8132,7 +8434,10 @@ paths: tags: - Companies operationId: ListAttachedSegmentsForCompanies - description: You can fetch a list of all segments that belong to a company. + description: | + You can fetch a list of all segments that belong to a company. + + Requires the `read_users_companies` OAuth scope. responses: '200': description: Successful @@ -8171,6 +8476,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: d392920d-35e7-461a-d6f8-d1e90be0b62c + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" "/companies/{company_id}/notes": @@ -8417,6 +8729,12 @@ paths: ### Sorting Pass an optional `sort` object with a `field` and an `order` (`ascending` or `descending`; defaults to `descending`) to order the results. An invalid `order` returns a `400` error with code `invalid_sort_order`. `tag_id` can be used as a filter but not as a sort field. + + ### Pagination + + Pass an optional `pagination` object with `per_page` and `starting_after`. `per_page` defaults to 15 and must be between 1 and 150; anything else returns a `400` error with code `invalid_per_page`. Take `starting_after` from `pages.next` in the previous response, and send it with the same `sort` you used for that response. A cursor from a sort on a text field such as `name`, sent with a sort on a number or date field (or the other way round), returns a `400` error with code `client_error`. Leaving out `sort` sorts by `last_request_at`, a date. A cursor sent with a different sort of the same kind is accepted, but the page it returns doesn't follow on from the previous one. + + Requires the `read_users_companies` OAuth scope. responses: '200': description: successful @@ -8434,7 +8752,7 @@ paths: per_page: 5 total_pages: 0 schema: - "$ref": "#/components/schemas/company_list" + "$ref": "#/components/schemas/company_search_response" '401': description: Unauthorized content: @@ -8447,6 +8765,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: e4a3a31e-46f8-422b-e709-e2fa1cf1c73d + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" '400': @@ -8461,6 +8786,58 @@ paths: errors: - code: invalid_field message: "segment_id is not a valid search field" + Invalid sort order: + value: + type: error.list + request_id: f5b4b42f-5709-433c-f81a-f30b2da2d84e + errors: + - code: invalid_sort_order + message: "Invalid sort order 'sideways'. Must be one of: ascending, + descending" + Sort is not an object: + value: + type: error.list + request_id: 06c5c530-681a-444d-092b-041c3eb3e95f + errors: + - code: client_error + message: Invalid sort parameter. Expected an object with 'field' + and 'order'. + Pagination is not an object: + value: + type: error.list + request_id: 17d6d641-792b-455e-1a3c-152d4fc4fa60 + errors: + - code: client_error + message: Invalid pagination parameter. Expected an object. + Per page out of range: + value: + type: error.list + request_id: 4a09095a-ac5e-4882-4d6f-485072f72d93 + errors: + - code: invalid_per_page + message: per_page must be an integer between 0 and 150 + Cursor does not match the sort: + value: + type: error.list + request_id: 28e7e752-8a3c-4660-2b4d-263e50d50b71 + errors: + - code: client_error + message: Invalid starting_after param. Please try again using + a starting_after value from a paginated response + schema: + "$ref": "#/components/schemas/error" + '503': + description: Service Unavailable + content: + application/json: + examples: + Search temporarily unavailable: + value: + type: error.list + request_id: 39f8f863-9b4d-4771-3c5e-374f61e61c82 + errors: + - code: service_unavailable + message: Feature temporarily unavailable schema: "$ref": "#/components/schemas/error" requestBody: @@ -8501,18 +8878,24 @@ paths: - name: per_page in: query required: false - description: How many results to return per page. Defaults to 15 + description: How many results to return per page. Defaults to 15. A value + above 60 returns a `400` error with code `parameter_invalid`. example: 15 schema: type: integer + maximum: 60 - name: order in: query required: false description: "`asc` or `desc`. Return the companies in ascending or descending - order. Defaults to desc" + order. Defaults to desc. Any other value returns a `400` error with code + `parameter_invalid`." example: desc schema: type: string + enum: + - asc + - desc tags: - Companies operationId: listAllCompanies @@ -8521,11 +8904,13 @@ paths: Note that the API does not include companies who have no associated users in list responses. - When using the Companies endpoint and the pages object to iterate through the returned companies, there is a limit of 10,000 Companies that can be returned. If you need to list or iterate on more than 10,000 Companies, please use the [Scroll API](https://developers.intercom.com/reference#iterating-over-all-companies). + When using the Companies endpoint and the pages object to iterate through the returned companies, there is a limit of 10,000 Companies that can be returned. If you need to list or iterate on more than 10,000 Companies, please use the [Scroll API](https://developers.intercom.com/reference#iterating-over-all-companies). Going past that limit returns a `400` error with code `bad_request`. {% admonition type="warning" name="Pagination" %} - 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. + This endpoint pages by page number, not by cursor. Use the `page` and `per_page` query parameters, and the `page`, `total_pages` and `next` values in the `pages` object of the response. The default is `15` 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. {% /admonition %} + + Requires the `write_users_companies` OAuth scope. A token with only read scopes cannot call this endpoint. responses: '200': description: Successful @@ -8555,6 +8940,12 @@ paths: segments: [] plan: {} custom_attributes: {} + notes: + type: note.list + data: [] + url: "/companies/6762f0941bb69f9f2193bb25/notes" + total_count: 0 + has_more: false pages: type: pages next: @@ -8564,6 +8955,27 @@ paths: total_count: 1 schema: "$ref": "#/components/schemas/company_list" + '400': + description: Bad Request + content: + application/json: + examples: + Per page too big: + value: + type: error.list + request_id: 5b1a1a6b-bd6f-4993-5e70-5961830833a4 + errors: + - code: parameter_invalid + message: Per Page is too big + Page limit reached: + value: + type: error.list + request_id: 7d3c3c8d-df81-4bb5-7092-7b83a52a55c6 + errors: + - code: bad_request + message: page limit reached, please use scroll API + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -8576,6 +8988,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 8e4d4d9e-e092-4cc6-81a3-8c94b63b66d7 + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" "/companies/scroll": @@ -8589,7 +9008,9 @@ paths: - name: scroll_param in: query required: false - description: '' + description: The `scroll_param` from the previous response. Omit it to start + a new scroll. + example: 69352cd2-ab5b-42ac-b004-a13d4e55e9b0 schema: type: string tags: @@ -8598,9 +9019,11 @@ paths: description: |2 The `list all companies` functionality does not work well for huge datasets, and can result in errors and performance problems when paging deeply. The Scroll API provides an efficient mechanism for iterating over all companies in a dataset. - - Each app can only have 1 scroll open at a time. You'll get an error message if you try to have more than one open per app. - - If the scroll isn't used for 1 minute, it expires and calls with that scroll param will fail - - If the end of the scroll is reached, "companies" will be empty and the scroll parameter will expire + - Each app can only have 1 scroll open at a time. Starting a second one returns a `400` error with code `scroll_exists`. + - If the scroll isn't used for 1 minute, it expires and calls with that scroll param return a `404` error with code `not_found`. + - If the end of the scroll is reached, `data` will be empty and the scroll parameter will expire. + + The response always has `pages` and `total_count` set to `null`. Use `scroll_param` to fetch the next page. {% admonition type="info" name="Scroll Parameter" %} You can get the first page of companies by simply sending a GET request to the scroll endpoint. @@ -8611,6 +9034,8 @@ paths: "Request failed due to an internal network error. Please restart the scroll operation." If this happens, you will need to restart your scroll query: It is not possible to continue from a specific point when using scroll. {% /admonition %} + + Requires the `read_users_companies` OAuth scope. responses: '200': description: Successful @@ -8640,11 +9065,45 @@ paths: segments: [] plan: {} custom_attributes: {} + notes: + type: note.list + data: [] + url: "/companies/6762f0971bb69f9f2193bb2b/notes" + total_count: 0 + has_more: false pages: total_count: scroll_param: 69352cd2-ab5b-42ac-b004-a13d4e55e9b0 schema: "$ref": "#/components/schemas/company_scroll" + '400': + description: Bad Request + content: + application/json: + examples: + Scroll already open: + value: + type: error.list + request_id: 9f5e5eaf-f1a3-4dd7-92b4-9da5c74c77e8 + errors: + - code: scroll_exists + message: scroll already exists for this workspace + schema: + "$ref": "#/components/schemas/error" + '404': + description: Scroll Parameter Not Found + content: + application/json: + examples: + Scroll parameter not found: + value: + type: error.list + request_id: a06f6fb0-02b4-4ee8-a3c5-aeb6d85d88f9 + errors: + - code: not_found + message: scroll parameter not found + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -8657,6 +9116,27 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: b17a7ac1-13c5-4ff9-b4d6-bfc7e96e99fa + errors: + - code: token_unauthorized + message: Not authorized to access resource + schema: + "$ref": "#/components/schemas/error" + '503': + description: Service Unavailable + content: + application/json: + examples: + Scroll temporarily unavailable: + value: + type: error.list + request_id: c28b8bd2-24d6-40aa-c5e7-c0d8fa7faa0b + errors: + - code: service_unavailable + message: Feature temporarily unavailable schema: "$ref": "#/components/schemas/error" "/contacts/{contact_id}/companies": @@ -30323,7 +30803,8 @@ components: example: 531ee472cce572a6ec000006 name: type: string - description: The name of the company. + description: The name of the company. Returned HTML-escaped, for example + `&` as `&`. example: Blue Sun app_id: type: string @@ -30347,7 +30828,8 @@ components: example: Pro company_id: type: string - description: The company id you have defined for the company. + description: The company id you have defined for the company. Returned HTML-escaped, + for example `&` as `&`. example: '6' remote_created_at: type: integer @@ -30418,7 +30900,8 @@ components: "$ref": "#/components/schemas/tag_basic" segments: type: object - description: The list of segments associated with the company + description: Always returned empty. Fetch a company's segments with the + list attached segments endpoint. properties: type: type: string @@ -30438,10 +30921,24 @@ components: description: The type of the object enum: - note.list - notes: + data: type: array + description: The notes on the company, newest first. items: "$ref": "#/components/schemas/company_note" + url: + type: string + description: The relative URL of the company's notes. + example: "/companies/531ee472cce572a6ec000006/notes" + total_count: + type: integer + description: The number of notes in `data`. + example: 1 + has_more: + type: boolean + description: Always `false`. Every note on the company is returned in + `data`. + example: false company_attached_contacts: title: Company Attached Contacts type: object @@ -30485,7 +30982,8 @@ components: type: object x-tags: - Notes - description: Notes allow you to annotate and comment on companies. + description: A note as it appears inside a company's `notes` list. Fetch the + full note with the retrieve note endpoint. properties: type: type: string @@ -30496,28 +30994,10 @@ components: type: string description: The id of the note. example: '17495962' - created_at: - type: integer - format: timestamp - description: The time the note was created. - example: 1674589321 - 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`. - example: company - id: - type: string - description: The id of the company. - example: 6329bd9ffe4e2e91dac76188 - author: - "$ref": "#/components/schemas/admin" - description: Optional. Represents the Admin that created the note. + url: + type: string + description: The relative URL of the note. + example: "/notes/17495962" body: type: string description: The body text of the note. @@ -30525,7 +31005,30 @@ components: company_list: title: Companies type: object - description: This will return a list of companies for the App. + description: This will return a list of companies for the App. On the last page, + `pages.next` is `null`. + properties: + type: + type: string + description: The type of object - `list`. + enum: + - list + example: list + pages: + "$ref": "#/components/schemas/pages_link" + total_count: + type: integer + description: The total number of companies. + example: 100 + data: + type: array + description: An array containing Company Objects. + items: + "$ref": "#/components/schemas/company" + company_search_response: + title: Company Search Response + type: object + description: This will return a list of companies matching a search query. properties: type: type: string @@ -30563,17 +31066,47 @@ components: items: "$ref": "#/components/schemas/company" pages: - "$ref": "#/components/schemas/cursor_pages" + type: object + description: Always `null`. Page through a scroll with `scroll_param` instead. + nullable: true total_count: type: integer - description: The total number of companies + description: Always `null`. The scroll endpoint does not count the companies + it returns. nullable: true - example: 100 scroll_param: type: string description: The scroll parameter to use in the next request to fetch the next page of results. example: 25b649f7-4d33-4ef6-88f5-60e5b8244309 + company_user_list: + title: Company Users + type: object + description: The contacts attached to one company, returned when `type` is `user` + or `users` and the request names a single company. Contacts are in the legacy + user format. On the last page, `pages.next` is `null`. + properties: + type: + type: string + description: The type of object - `user.list`. + enum: + - user.list + example: user.list + users: + type: array + description: The contacts attached to the company, in the legacy user format. + items: + type: object + pages: + "$ref": "#/components/schemas/pages_link" + total_count: + type: integer + description: The total number of contacts attached to the company. + example: 1 + limited: + type: boolean + description: Always `false` for this list. + example: false contact: title: Contact type: object @@ -34821,17 +35354,23 @@ components: create_or_update_company_request: type: object title: Create Or Update Company Request Payload - description: You can create or update a Company + description: You can create or update a Company. Send either `company_id` or + `id`; a request with neither returns a `400` error. nullable: true properties: name: type: string - description: The name of the Company + description: The name of the Company. Leading and trailing whitespace is + removed. example: Intercom company_id: type: string description: The company id you have defined for the company. Can't be updated example: 625e90fc55ab113b6d92175f + id: + type: string + description: An alternative name for `company_id`. Supply this or `company_id`. + example: 625e90fc55ab113b6d92175f plan: type: string description: The name of the plan you have associated with the company. @@ -34875,10 +35414,10 @@ components: example: true monthly_spend: type: integer - description: How much revenue the company generates for your business. Note - that this will truncate floats. i.e. it only allow for whole integers, - 155.98 will be truncated to 155. Note that this has an upper limit of - 2**31-1 or 2147483647.. + description: How much revenue the company generates for your business. Floats + are truncated to whole integers, so 155.98 is stored as 155. A value above + 2147483647 (2**31-1) is stored as 0. 2147483647 itself, or a value of -2147483648 + or below, returns a `422` error. example: 1000 update_company_request: type: object @@ -34888,8 +35427,13 @@ components: properties: name: type: string - description: The name of the Company + description: The name of the Company. Leading and trailing whitespace is + removed. example: Intercom + update_last_request_at: + type: boolean + description: Set to true to update the company's last seen time to now. + example: true plan: type: string description: The name of the plan you have associated with the company. @@ -34929,10 +35473,10 @@ components: example: 1394531169 monthly_spend: type: integer - description: How much revenue the company generates for your business. Note - that this will truncate floats. i.e. it only allow for whole integers, - 155.98 will be truncated to 155. Note that this has an upper limit of - 2**31-1 or 2147483647.. + description: How much revenue the company generates for your business. Floats + are truncated to whole integers, so 155.98 is stored as 155. A value above + 2147483647 (2**31-1) is stored as 0. 2147483647 itself, or a value of -2147483648 + or below, returns a `422` error. example: 1000 create_or_update_custom_object_instance_request: description: Payload to create or update a Custom Object instance @@ -37664,7 +38208,8 @@ components: example: company deleted: type: boolean - description: Whether the company was deleted successfully or not. + description: Always `true`. The contacts are detached after the response + is sent. example: true deleted_object: title: Deleted Object