The Intercom API provides programmatic access to the Intercom customer service platform. Build apps on the complete AI customer service platform and create seamless customized experiences in the Intercom Help Desk and Messenger using APIs and SDKs.
openapi: 3.1.0
info:
title: Intercom API
description: >-
The Intercom API provides programmatic access to the Intercom AI-powered
customer service platform. It enables developers to manage contacts,
companies, conversations, articles, segments, messages, and data events,
and to build seamless integrations with the Intercom Help Desk and
Messenger.
version: '2.15'
contact:
name: Intercom Developer Support
url: https://developers.intercom.com/
externalDocs:
description: Intercom Developer Documentation
url: https://developers.intercom.com/docs/
servers:
- url: https://api.intercom.io
description: Production (US)
- url: https://api.eu.intercom.io
description: Europe
- url: https://api.au.intercom.io
description: Australia
tags:
- name: Admins
description: Workspace teammates and admin information.
- name: Contacts
description: Manage users and leads in your Intercom workspace.
- name: Companies
description: Manage company records associated with contacts.
- name: Conversations
description: Manage conversations between contacts and admins.
- name: Articles
description: Manage Help Center articles.
- name: Segments
description: Access user and company segments.
- name: Messages
description: Send outbound messages from Intercom to contacts.
- name: Data Events
description: Submit and retrieve user activity events.
- name: News
description: Manage news items in the Help Desk.
paths:
/me:
get:
operationId: getMe
summary: Identify an admin
description: >-
Returns information about the admin user authenticated by the access
token used in the request.
tags:
- Admins
responses:
'200':
description: Admin record returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Admin'
/admins:
get:
operationId: listAdmins
summary: List admins
description: >-
Retrieves a paginated list of admins in your Intercom workspace.
tags:
- Admins
responses:
'200':
description: Admin list returned successfully.
content:
application/json:
schema:
type: object
properties:
type:
type: string
admins:
type: array
items:
$ref: '#/components/schemas/Admin'
/contacts:
get:
operationId: listContacts
summary: List contacts
description: Retrieves a paginated list of contacts.
tags:
- Contacts
parameters:
- name: per_page
in: query
schema:
type: integer
- name: starting_after
in: query
schema:
type: string
responses:
'200':
description: Contacts list returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ContactList'
post:
operationId: createContact
summary: Create a contact
description: Creates a new contact (user or lead) in your Intercom workspace.
tags:
- Contacts
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
responses:
'200':
description: Contact created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
/contacts/{contact_id}:
get:
operationId: getContact
summary: Retrieve a contact
description: Retrieves a single contact by ID.
tags:
- Contacts
parameters:
- name: contact_id
in: path
required: true
schema:
type: string
responses:
'200':
description: Contact returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
/companies:
get:
operationId: listCompanies
summary: List companies
description: Retrieves a paginated list of companies.
tags:
- Companies
responses:
'200':
description: Companies list returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyList'
post:
operationId: createOrUpdateCompany
summary: Create or update a company
description: Creates or updates a company record by company_id.
tags:
- Companies
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Company'
responses:
'200':
description: Company created or updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Company'
/conversations:
get:
operationId: listConversations
summary: List conversations
description: Retrieves a paginated list of conversations.
tags:
- Conversations
responses:
'200':
description: Conversations list returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationList'
post:
operationId: createConversation
summary: Create a conversation
description: Creates a new user-initiated conversation.
tags:
- Conversations
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
from:
type: object
body:
type: string
responses:
'200':
description: Conversation created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Conversation'
/conversations/{conversation_id}:
get:
operationId: getConversation
summary: Retrieve a conversation
tags:
- Conversations
parameters:
- name: conversation_id
in: path
required: true
schema:
type: string
responses:
'200':
description: Conversation returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Conversation'
/articles:
get:
operationId: listArticles
summary: List articles
tags:
- Articles
responses:
'200':
description: Articles list returned successfully.
content:
application/json:
schema:
type: object
properties:
type:
type: string
data:
type: array
items:
$ref: '#/components/schemas/Article'
post:
operationId: createArticle
summary: Create an article
tags:
- Articles
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Article'
responses:
'200':
description: Article created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Article'
/segments:
get:
operationId: listSegments
summary: List segments
tags:
- Segments
responses:
'200':
description: Segments list returned successfully.
content:
application/json:
schema:
type: object
properties:
type:
type: string
segments:
type: array
items:
$ref: '#/components/schemas/Segment'
/messages:
post:
operationId: createMessage
summary: Create a message
description: Sends an outbound message to a contact.
tags:
- Messages
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
message_type:
type: string
subject:
type: string
body:
type: string
template:
type: string
from:
type: object
to:
type: object
responses:
'200':
description: Message dispatched successfully.
/events:
post:
operationId: submitEvent
summary: Submit a data event
description: Submits a custom data event tracking user activity.
tags:
- Data Events
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
event_name:
type: string
created_at:
type: integer
user_id:
type: string
email:
type: string
metadata:
type: object
responses:
'202':
description: Event accepted.
get:
operationId: listEvents
summary: List data events
tags:
- Data Events
parameters:
- name: type
in: query
schema:
type: string
- name: user_id
in: query
schema:
type: string
responses:
'200':
description: Events list returned successfully.
/news/news_items:
get:
operationId: listNewsItems
summary: List news items
tags:
- News
responses:
'200':
description: News items list returned successfully.
post:
operationId: createNewsItem
summary: Create a news item
tags:
- News
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
title:
type: string
body:
type: string
sender_id:
type: integer
state:
type: string
responses:
'200':
description: News item created successfully.
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
Admin:
type: object
properties:
type:
type: string
id:
type: string
name:
type: string
email:
type: string
away_mode_enabled:
type: boolean
away_mode_reassign:
type: boolean
Contact:
type: object
properties:
type:
type: string
id:
type: string
external_id:
type: string
role:
type: string
email:
type: string
name:
type: string
phone:
type: string
created_at:
type: integer
updated_at:
type: integer
ContactList:
type: object
properties:
type:
type: string
data:
type: array
items:
$ref: '#/components/schemas/Contact'
total_count:
type: integer
Company:
type: object
properties:
type:
type: string
id:
type: string
company_id:
type: string
name:
type: string
plan:
type: object
size:
type: integer
industry:
type: string
created_at:
type: integer
CompanyList:
type: object
properties:
type:
type: string
data:
type: array
items:
$ref: '#/components/schemas/Company'
Conversation:
type: object
properties:
type:
type: string
id:
type: string
title:
type: string
created_at:
type: integer
updated_at:
type: integer
state:
type: string
open:
type: boolean
priority:
type: string
ConversationList:
type: object
properties:
type:
type: string
conversations:
type: array
items:
$ref: '#/components/schemas/Conversation'
total_count:
type: integer
Article:
type: object
properties:
type:
type: string
id:
type: string
title:
type: string
description:
type: string
body:
type: string
author_id:
type: integer
state:
type: string
created_at:
type: integer
updated_at:
type: integer
Segment:
type: object
properties:
type:
type: string
id:
type: string
name:
type: string
created_at:
type: integer
updated_at:
type: integer
person_type:
type: string
security:
- bearerAuth: []