Replace granted companies for a contact (Preview)

Request

Replace the full set of companies a contact has been granted access to.

This is a replacement, not an append. The company_ids you send become the contact's entire granted set — any company id you leave out is dropped. To add a company, send the existing ids plus the new one; to remove one, send the existing ids minus that one; to drop every grant, send an empty array.

Identify companies by the company_id you set on them, the same values GET /contacts/{contact_id}/granted_companies returns. Duplicates in the request are collapsed. A contact can be granted at most 100 companies.

The response echoes the stored set, so a 200 is confirmation of exactly what the contact can now read.

Requires granted companies to be enabled

This endpoint returns 404 with the code granted_companies_not_enabled unless granted companies are enabled for the workspace. Contact Intercom Support to enable it.

Requires the write_users_companies OAuth scope. Set Intercom-Version: preview.

Security

bearerAuth

Path

contact_idstringrequired

The unique identifier for the contact which is given by Intercom

Example:63a07ddf05a32042dffac965

Intercom-Versionstring(intercom_version_preview)

Preview Intercom API version. Used for closed beta endpoints or other features under managed availability.

Default:"preview"

Value:"preview"

Example:preview

Bodyapplication/jsonrequired

company_idsArray of strings, <= 100 itemsrequired

The company_id values of the companies to grant the contact access to. Send an empty array to drop every grant. Maximum of 100 ids.

Example:

[
  "acme-corp",
  "1234"
]

curl -i -X PUT \
  https://api.intercom.io/contacts/63a07ddf05a32042dffac965/granted_companies \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: preview' \
  -d '{
    "company_ids": [
      "acme-corp",
      "1234",
      "globex"
    ]
  }'

Responses

Successful

Bodyapplication/json

typestring

The type of object

Value:"list"

Example:"list"

company_idsArray of strings

The company_id values of the companies the contact has been granted access to.

Example:

[
  "acme-corp"
]

pagesobject or null(Pagination Object)

Pagination details. Null on the replace response, which returns the whole stored set.

total_countinteger

The total number of companies the contact has been granted access to.

Example:2

Response

{
  "type": "list",
  "company_ids": [
    "acme-corp",
    "1234",
    "globex"
  ],
  "pages": null,
  "total_count": 3
}