Intercom API Getting Started: Quickstart Guide and First Request (2026)

Getting started overview

Integrating with the Intercom API enables programmatic access to customer data, conversations, and engagement tools within the Intercom platform. This guide provides a structured approach to initiate your development, covering account setup, API key generation, and executing a foundational API request. The Intercom API is designed for developers to extend Intercom's capabilities, automate workflows, and synchronize customer information across various systems Intercom API reference documentation.

Before making your first API call, you will need an active Intercom workspace. While Intercom does not offer a free tier, it provides various paid plans starting at a base rate for the Starter plan Intercom pricing page. Access to the API is generally included with most Intercom subscriptions, allowing developers to interact with features such as managing users, sending messages, and retrieving conversation data.

The following table outlines the key steps to get started with the Intercom API:

Create an account and get keys

To begin using the Intercom API, an active Intercom workspace is required. If you do not already have one, you can sign up for a plan on the Intercom website's pricing page. Intercom offers various plans tailored to different business needs, and API access is a standard feature across these plans.

Generating an API Access Token

Once your Intercom workspace is active, you need to generate an API access token. This token serves as your authentication credential for all API requests. Intercom uses OAuth 2.0 for authentication, providing a secure method to grant applications access to user data without sharing user credentials OAuth 2.0 specification. The access token is a bearer token, meaning it should be included in the Authorization header of your API requests.

1. Log in to your Intercom workspace: Access your Intercom admin panel with appropriate permissions.
2. Navigate to Developer Hub: From the sidebar, go to Settings > Developers > Developer Hub.
3. Create a new app or select an existing one: Within the Developer Hub, you can either create a new custom application or select an existing one to manage its credentials. For initial testing, creating a new private app is often recommended.
4. Generate an Access Token: Inside your app's settings, locate the "Authentication" section. Here, you will find options to generate or manage access tokens. Select "New token" to create a new access token.
5. Copy the token: After generation, Intercom will display your access token. It is crucial to copy and store this token securely, as it will not be shown again for security reasons. Treat your API key like a password; do not expose it in client-side code or public repositories.

The generated token will have specific scopes associated with it, determining what actions your application can perform via the API. For a first request, ensure your token has adequate permissions, such as read access for users or conversations, to retrieve data.

Your first request

With your API access token in hand, you can now make your first authenticated request to the Intercom API. This example demonstrates retrieving a list of users, a common starting point for many integrations.

The Intercom API base URL is https://api.intercom.io. All API endpoints are appended to this base URL.

Using cURL (HTTP Request)

A cURL command is a universal way to test API endpoints directly from your terminal, without requiring any specific programming language or SDK setup.

curl -X GET \
  'https://api.intercom.io/users' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/json'

Replace YOUR_ACCESS_TOKEN with the actual access token you generated in the previous step.

A successful response will return a JSON object containing a list of users in your Intercom workspace, similar to this (truncated for brevity):

{
  "type": "list",
  "data": [
    {
      "type": "user",
      "id": "61011e0c83a1c0001bc2013f",
      "user_id": "user123",
      "email": "[email protected]",
      "name": "Test User"
      // ... more user data
    }
  ],
  "pages": {
    "next": null,
    "page": 1,
    "per_page": 20,
    "total_pages": 1
  }
}

Using Python (with requests library)

If you prefer using a programming language, Python with the requests library is a straightforward option.

import requests
import json

ACCESS_TOKEN = "YOUR_ACCESS_TOKEN"

headers = {
    "Authorization": f"Bearer {ACCESS_TOKEN}",
    "Accept": "application/json"
}

response = requests.get("https://api.intercom.io/users", headers=headers)

if response.status_code == 200:
    users_data = response.json()
    print(json.dumps(users_data, indent=2))
else:
    print(f"Error: {response.status_code} - {response.text}")

Remember to replace YOUR_ACCESS_TOKEN with your actual Intercom API key. This script will print the JSON response containing your user data or an error message if the request fails.

Common next steps

After successfully making your first API call, you can explore various functionalities offered by the Intercom API to enhance your application's customer engagement capabilities:

• User and Contact Management: Create, update, or retrieve user and lead profiles. This is fundamental for keeping your customer data consistent across systems Intercom API Users documentation.
• Conversation Management: Send messages, manage conversations, and retrieve conversation history. This enables programmatic interaction with your customers through Intercom Messenger.
• Event Tracking: Record custom events to track user behavior within your application, which can then be used for segmentation and targeted messaging.
• Webhooks: Set up webhooks to receive real-time notifications about events happening in your Intercom workspace, such as new messages, conversation updates, or user changes Intercom Webhooks guide. This allows for immediate reactions and synchronization.
• SDK Integration: For more complex applications, consider integrating one of Intercom's official SDKs. These SDKs handle authentication, request formatting, and error handling, streamlining development for languages like Python, Ruby, JavaScript, and mobile platforms like iOS and Android Intercom SDKs and Platforms documentation.
• Error Handling: Implement robust error handling in your application to gracefully manage API rate limits, authentication failures, and other potential issues. Consult the Intercom API Error Handling documentation for details on error codes and messages.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips:

• Incorrect API Access Token: Double-check that you have copied the entire access token correctly and that it is placed in the Authorization: Bearer header. A common mistake is a missing character or an extra space.
• Insufficient Permissions (Scopes): Ensure that the API token you generated has the necessary permissions (scopes) for the endpoint you are trying to access. For example, to retrieve users, the token needs read access to users. You can review and adjust token scopes in the Intercom Developer Hub.
• Wrong Endpoint or Method: Verify that the API endpoint URL is correct (e.g., /users) and that you are using the appropriate HTTP method (e.g., GET for retrieving data, POST for creating, PUT for updating). Refer to the Intercom API reference for specific endpoint details.
• Rate Limits: Intercom API has rate limits to prevent abuse and ensure fair usage. If you make too many requests within a short period, you might receive a 429 Too Many Requests error. Implement retry logic with exponential backoff if your application needs to handle high volumes of requests. Details on rate limits are available in the Intercom API Rate Limits documentation.
• Network Issues: Ensure your development environment has a stable internet connection and no firewall rules are blocking outgoing requests to api.intercom.io.
• Malformed Request Body: If you are making a POST or PUT request, ensure that the request body is valid JSON and adheres to the schema required by the specific endpoint. Missing required fields or incorrect data types will result in errors.
• Consult Documentation and Support: The Intercom developer documentation is comprehensive and often provides specific error messages and solutions. If you're still stuck, Intercom's support channels or developer community forums can offer assistance.