Intercom API (2.9)

The intercom API reference.

Download OpenAPI description
Languages
Servers
The production API server
https://api.intercom.io/
The european API server
https://api.eu.intercom.io/
The australian API server
https://api.au.intercom.io/

Admins

Everything about your Admins

Operations

Admin

Admins are teammate accounts that have access to a workspace.

typestring

String representing the object's type. Always has the value admin.

Example: "admin"
idstring

The id representing the admin.

Example: "1295"
namestring

The name of the admin.

Example: "Hoban Washburne"
emailstring

The email of the admin.

Example: "wash@serenity.io"
job_titlestring

The job title of the admin.

Example: "Philosopher"
away_mode_enabledboolean

Identifies if this admin is currently set in away mode.

Example: false
away_mode_reassignboolean

Identifies if this admin is set to automatically reassign new conversations to the apps default inbox.

Example: false
has_inbox_seatboolean

Identifies if this admin has a paid inbox seat to restrict/allow features that require them.

Example: true
team_idsArray of integers

This object represents the avatar associated with the admin.

Example: [814865]
avatarstring or null(uri)

Image for the associated team or teammate

Example: "https://picsum.photos/200/300"
team_priority_levelobject or null(Team Priority Level)

Admin priority levels for teams

{ "type": "admin", "id": "1295", "name": "Hoban Washburne", "email": "wash@serenity.io", "job_title": "Philosopher", "away_mode_enabled": false, "away_mode_reassign": false, "has_inbox_seat": true, "team_ids": [ 814865 ], "avatar": "https://picsum.photos/200/300", "team_priority_level": { "primary_team_ids": [ … ], "secondary_team_ids": [ … ] } }

Identify an admin

Request

You can view the currently authorised admin along with the embedded app object (a "workspace" in legacy terminology).

🚧 Single Sign On

If you are building a custom "Log in with Intercom" flow for your site, and you call the /me endpoint to identify the logged-in user, you should not accept any sign-ins from users with unverified email addresses as it poses a potential impersonation security risk.

Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default 2.9
Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example: 2.9
curl -i -X GET \
  https://api.intercom.io/me \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.9'

Responses

Successful response

Bodyapplication/json
typestring

String representing the object's type. Always has the value admin.

Example: "admin"
idstring

The id representing the admin.

Example: "1295"
namestring

The name of the admin.

Example: "Hoban Washburne"
emailstring

The email of the admin.

Example: "wash@serenity.io"
job_titlestring

The job title of the admin.

Example: "Philosopher"
away_mode_enabledboolean

Identifies if this admin is currently set in away mode.

Example: false
away_mode_reassignboolean

Identifies if this admin is set to automatically reassign new conversations to the apps default inbox.

Example: false
has_inbox_seatboolean

Identifies if this admin has a paid inbox seat to restrict/allow features that require them.

Example: true
team_idsArray of integers

This is a list of ids of the teams that this admin is part of.

Example: [814865]
avatarobject

This object represents the avatar associated with the admin.

email_verifiedboolean or null

Identifies if this admin's email is verified.

Example: true
appobject or null(App)

App is a workspace on Intercom

Response
application/json
{ "type": "admin", "id": "991267242", "email": "admin1@email.com", "name": "Ciaran1 Lee", "email_verified": true, "app": { "type": "app", "id_code": "this_is_an_id1_that_should_be_at_least_40", "name": "MyApp 1", "created_at": 1717021328, "secure": false, "identity_verification": false, "timezone": "America/Los_Angeles", "region": "US" }, "avatar": { "type": "avatar", "image_url": "https://static.intercomassets.com/assets/default-avatars/admins/128.png" }, "has_inbox_seat": true }

Set an admin to away

Request

You can set an Admin as away for the Inbox.

Path
idintegerrequired

The unique identifier of a given admin

Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default 2.9
Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example: 2.9
Bodyapplication/json
away_mode_enabledbooleanrequired

Set to "true" to change the status of the admin to away.

Default true
Example: true
away_mode_reassignbooleanrequired

Set to "true" to assign any new conversation replies to your default inbox.

Default false
Example: false
curl -i -X PUT \
  'https://api.intercom.io/admins/{id}/away' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: 2.9' \
  -d '{
    "away_mode_enabled": true,
    "away_mode_reassign": true
  }'

Responses

Successful response

Bodyapplication/json
typestring

String representing the object's type. Always has the value admin.

Example: "admin"
idstring

The id representing the admin.

Example: "1295"
namestring

The name of the admin.

Example: "Hoban Washburne"
emailstring

The email of the admin.

Example: "wash@serenity.io"
job_titlestring

The job title of the admin.

Example: "Philosopher"
away_mode_enabledboolean

Identifies if this admin is currently set in away mode.

Example: false
away_mode_reassignboolean

Identifies if this admin is set to automatically reassign new conversations to the apps default inbox.

Example: false
has_inbox_seatboolean

Identifies if this admin has a paid inbox seat to restrict/allow features that require them.

Example: true
team_idsArray of integers

This object represents the avatar associated with the admin.

Example: [814865]
avatarstring or null(uri)

Image for the associated team or teammate

Example: "https://picsum.photos/200/300"
team_priority_levelobject or null(Team Priority Level)

Admin priority levels for teams

Response
application/json
{ "type": "admin", "id": "991267243", "name": "Ciaran2 Lee", "email": "admin2@email.com", "away_mode_enabled": true, "away_mode_reassign": true, "has_inbox_seat": true, "team_ids": [] }

List all activity logs

Request

You can get a log of activities by all admins in an app.

Query
created_at_afterstringrequired

The start date that you request data for. It must be formatted as a UNIX timestamp.

Example: created_at_after=1677253093
created_at_beforestring

The end date that you request data for. It must be formatted as a UNIX timestamp.

Example: created_at_before=1677861493
Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default 2.9
Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example: 2.9
curl -i -X GET \
  'https://api.intercom.io/admins/activity_logs?created_at_after=string&created_at_before=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.9'

Responses

Successful response

Bodyapplication/json
typestring

String representing the object's type. Always has the value activity_log.list.

Example: "activity_log.list"
pagesobject or null(Cursor based pages)

Cursor-based pagination is a technique used in the Intercom API to navigate through large amounts of data. A "cursor" or pointer is used to keep track of the current position in the result set, allowing the API to return the data in small chunks or "pages" as needed.

activity_logsArray of objects or null(Activity Log)

An array of activity logs

Response
application/json
{ "type": "activity_log.list", "pages": { "type": "pages", "next": null, "page": 1, "per_page": 20, "total_pages": 1 }, "activity_logs": [ { … }, { … } ] }

List all admins

Request

You can fetch a list of admins for a given workspace.

Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default 2.9
Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example: 2.9
curl -i -X GET \
  https://api.intercom.io/admins \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.9'

Responses

Successful response

Bodyapplication/json