Intercom Getting Started: Account, Keys, and First API Call 2026

Getting started overview

Getting started with Intercom primarily involves setting up your workspace, configuring the Messenger, and integrating with Intercom's API or SDKs to manage customer interactions. The platform is designed to facilitate in-app messaging, customer support automation, and proactive customer engagement, often used for user onboarding and sales qualification. This guide focuses on the technical steps required to establish a connection and perform an initial API operation.

Intercom offers a comprehensive API for integrating with other systems and extending functionality, alongside SDKs for common web and mobile platforms. The documentation provides examples for various programming languages, including Ruby, Python, Node.js, PHP, Go, and Java, to assist developers in their integration efforts. Intercom's compliance includes SOC 2 Type II, GDPR, CCPA, and ISO 27001, which addresses data security and privacy requirements.

The core products, such as Intercom Messenger, Inbox, Product Tours, and Automation, are built upon this integration capability. A direct integration allows data exchange, enabling features like targeted messages, support ticket management, and user behavior tracking. The initial steps outlined here will enable basic communication with the Intercom platform.

Quick reference table

Create an account and get keys

Intercom does not offer a free tier, so access to the platform and its API requires a paid subscription. You can begin by visiting the Intercom pricing page to choose a suitable plan. After selecting a plan and completing the signup process, you will gain access to your Intercom workspace.

To interact with the Intercom API, you will need an Access Token. This token acts as a credential for authenticating your requests. Follow these steps to obtain your token:

1. Log in to your Intercom workspace.
2. Navigate to Settings > Developers > Developer Hub.
3. Select Your apps and then choose the app you want to configure, or create a new one.
4. Under the Authentication section, you will find your Access Token. This token is a long alphanumeric string that should be kept confidential.

This Access Token is a bearer token, meaning it should be included in the Authorization header of your API requests, prefixed with Bearer. For example, Authorization: Bearer YOUR_ACCESS_TOKEN. More details on authentication methods are available in the Intercom API authentication documentation.

Your first request

After obtaining your Access Token, you can make your first API request to confirm your setup is correct. A common first request is to retrieve a list of users or to create a new user. The Intercom API is RESTful and uses JSON for request and response bodies. For this example, we will use curl to add a new user to your workspace.

According to the Intercom API reference for creating users, a basic user creation request requires an email or user ID. For this example, we'll use an email address.

Example: Create a new user

This curl command sends a POST request to the /contacts endpoint to create a new contact (user) in your Intercom workspace. Replace YOUR_ACCESS_TOKEN with your actual token.

curl -X POST \
  https://api.intercom.io/contacts \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "role": "user",
    "email": "[email protected]",
    "name": "John Doe"
  }'

A successful response will return a 200 OK status code and a JSON object representing the newly created contact, including their Intercom ID. For instance:

{
  "type": "contact",
  "id": "65c329d601b631d3e1645e54",
  "workspace_id": "abcdefgh",
  "email": "[email protected]",
  "name": "John Doe",
  "role": "user",
  "created_at": 1678886400,
  "updated_at": 1678886400,
  "custom_attributes": {},
  "tags": {
    "type": "list",
    "data": []
  },
  "segments": {
    "type": "list",
    "data": []
  },
  "avatar": null,
  "owner_id": null,
  "social_profiles": {
    "type": "list",
    "data": []
  },
  "has_hard_bounced": false
}

If you encounter an error, check the HTTP status code and the error message in the response body. Common issues include an invalid Access Token or incorrect JSON formatting.

Common next steps

After successfully making your first API call, you can proceed with further integration to leverage Intercom's full capabilities:

• Install the Messenger: For web applications, integrate the Intercom Messenger JavaScript SDK to enable in-app chat, product tours, and proactive messages directly within your product. Mobile applications can use the iOS SDK or Android SDK.
• User and Company Management: Synchronize your user and company data with Intercom using the API. This allows for targeted messaging and segmentation. Refer to the Intercom API documentation for company creation.
• Event Tracking: Implement event tracking to record user actions within your application. This data can be used to trigger automated messages, segment users, and analyze engagement. The Intercom API supports submitting events.
• Webhooks: Set up webhooks to receive real-time notifications from Intercom about significant events, such as new conversations or user updates. This enables you to build reactive integrations. Consult the Intercom Webhooks guide for setup instructions.
• Automated Workflows: Utilize Intercom's automation features by integrating with your internal systems or other third-party services. This can involve triggering emails, sending data to a CRM, or updating user profiles based on specific events. Platforms like Tray.io offer Intercom integrations for workflow automation.
• Explore SDKs: If developing for specific platforms, explore the dedicated SDKs for JavaScript, React Native, iOS, and Android for easier client-side integration.

Troubleshooting the first call

When making your first API call to Intercom, you might encounter issues. Here are common problems and their solutions:

• 401 Unauthorized: This error typically means your Access Token is invalid or missing. Double-check that:

  • The token is correctly copied from your Intercom Developer Hub.
  • The Authorization header is present and correctly formatted as Bearer YOUR_ACCESS_TOKEN.
  • The token has not expired or been revoked.

  Refer to the Intercom API authentication documentation for correct token usage.

• 400 Bad Request: This indicates an issue with your request body or parameters. Common causes include:

  • Incorrect JSON format: Ensure your JSON payload is valid. Use a JSON linter if unsure.
  • Missing required fields: Some API endpoints require specific fields (e.g., email or user_id for creating a contact). Check the Intercom API reference for the specific endpoint you are calling.
  • Invalid data types: Ensure fields like numbers, booleans, or dates are in the expected format.

• 403 Forbidden: This error suggests that your Access Token does not have the necessary permissions to perform the requested action. Verify that:

  • The app associated with your token has the correct scopes enabled in the Developer Hub.
  • Your Intercom plan includes the features you are trying to access via the API.

• Network Issues: Ensure your development environment has a stable internet connection and no firewall rules are blocking outgoing requests to api.intercom.io.

• Rate Limiting (429 Too Many Requests): Intercom, like many API providers, enforces rate limits to prevent abuse. If you make too many requests in a short period, you might receive a 429 error. Implement exponential backoff or ensure your application adheres to the documented Intercom API rate limits.

For more detailed error codes and troubleshooting, consult the Intercom API error documentation.