Customer.io Getting Started: Quickstart Guide (2026)

Getting started overview

Integrating with Customer.io to automate customer communication workflows involves a sequence of steps, from setting up an account and retrieving necessary authentication credentials to executing a foundational API request. This guide outlines the process for establishing a connection with the Customer.io platform, focusing on the initial technical configuration required to begin using its services for personalized messaging and behavioral tracking.

The primary objective of this getting started guide is to enable a developer to successfully send their first piece of customer data to Customer.io, thereby creating a customer profile within the system. This profile acts as the base for all subsequent interactions, including triggering email campaigns, SMS messages, or push notifications based on user behavior or predefined segments. Customer.io's API is designed as a RESTful interface, supporting common HTTP methods for interacting with its resources. SDKs are provided for several popular programming languages, which abstract the underlying HTTP requests and simplify integration tasks.

Before initiating API calls, it is necessary to establish an account and retrieve specific API keys from the Customer.io dashboard. These keys serve as the authentication mechanism, ensuring that requests are authorized. The first working request typically involves the track API, which is used to record customer events or update customer attributes. This initial interaction validates the API setup and confirms that data can be successfully transmitted to Customer.io.

Create an account and get keys

To begin using Customer.io, an account must first be established. Customer.io offers various plans, with pricing based on the number of customer profiles and messages sent per month. Details regarding the available plans and their features can be found on the Customer.io pricing page. After selecting a suitable plan and completing the signup process, access to the Customer.io dashboard will be granted.

The API authentication for Customer.io relies on two primary credentials: a Site ID and an API Key (also referred to as an App Key). These keys are unique to each Customer.io workspace and are essential for authenticating all API requests. To locate these credentials:

1. Log in to your Customer.io account.
2. Navigate to the 'Integrations' section within the dashboard.
3. Select 'API Keys' or 'API Credentials'.
4. The Site ID (sometimes labeled 'Tracking API Key') and the API Key (sometimes labeled 'App API Key' or 'Messaging API Key') will be displayed.

It is crucial to handle these API keys securely, as they grant programmatic access to your Customer.io data and functionality. They should be stored as environment variables or in a secure configuration management system rather than hardcoded directly into application source code. For more comprehensive information on security best practices, consult resources on identity and access management best practices.

Customer.io uses different API endpoints for tracking data (events and customer profiles) and for sending messages (emails, SMS). The Site ID is typically used with the Tracking API, while the API Key is used with the Messaging API. Ensure you use the correct key for the intended API endpoint.

Your first request

After obtaining your Site ID and API Key, the next step is to make your first authenticated request to the Customer.io API. A common initial request involves identifying or updating a customer profile using the Tracking API. This demonstrates successful authentication and data transmission.

The Tracking API endpoint for identifying a customer is typically https://track.customer.io/api/v1/customers/[customer_id] or https://track.customer.io/api/v1/customers for creating/updating by email. For event tracking, it's https://track.customer.io/api/v1/events.

Here's an example using cURL to create or update a customer profile:

curl -X PUT "https://track.customer.io/api/v1/customers/customer_123" \ 
     -H "Authorization: Bearer YOUR_TRACKING_API_KEY" \ 
     -H "Content-Type: application/json" \ 
     -d '{"email": "[email protected]", "first_name": "John", "last_name": "Doe"}'

Replace YOUR_TRACKING_API_KEY with your actual Tracking API Key (Site ID if applicable), and customer_123 with a unique identifier for your customer. The email field is typically required. More details on the customer identification process are available in the Customer.io API reference for identifying customers.

Alternatively, if you prefer using one of the available SDKs, the process would look similar to this Python example for identifying a customer:

import customerio

# Initialize the Customer.io client
site_id = "YOUR_SITE_ID"
api_key = "YOUR_API_KEY"
cio = customerio.CustomerIO(site_id=site_id, api_key=api_key)

# Identify or update a customer
cio.identify(id="customer_123", email="[email protected]", first_name="Jane", last_name="Doe")
print("Customer identified successfully.")

Ensure that you install the appropriate SDK first (e.g., pip install customerio for Python). The Customer.io documentation provides detailed SDK examples for various languages.

Upon successful execution, the API will typically return a 200 OK status code, indicating that the customer profile has been created or updated in your Customer.io workspace. You can verify this by searching for the customer in your Customer.io dashboard under the 'People' section.

Common next steps

Once you have successfully made your first API request and verified that customer data is flowing into Customer.io, several common next steps can be pursued to further integrate and leverage the platform's capabilities:

1. Track Events: Implement event tracking to record user actions within your application or website. Events are crucial for triggering automated campaigns and segmenting users based on behavior. Examples include product_viewed, item_added_to_cart, or subscription_renewed. The Customer.io API reference for tracking events provides specific guidance.

2. Create Segments: Based on the customer attributes and events you're tracking, create segments to group users with similar characteristics or behaviors. Segments are dynamic and automatically update as customer data changes, enabling targeted messaging. Information on creating segments in Customer.io is available in the documentation.

3. Build Journeys: Design and deploy automated customer journeys. These are multi-step workflows that send personalized messages (email, SMS, push notifications, in-app messages) based on specific triggers, delays, and conditions. Journeys are the core of Customer.io's automation capabilities. Explore the Customer.io Journeys documentation for detailed instructions.

4. Integrate Messaging: Configure and send various types of messages. This includes setting up email senders, SMS numbers, and push notification services. The Messaging API allows for programmatic sending of messages outside of a journey, useful for transactional communications. Refer to the Customer.io Messaging API documentation for more information.

5. Utilize Webhooks: Customer.io supports webhooks for sending data to external systems when specific events occur within a journey or when certain actions are performed. This allows for custom integrations and real-time data synchronization with other platforms. Consult the Customer.io webhooks guide for setup details. For general webhook implementation strategies, the AWS documentation on API Gateway and Lambda integration offers a broader perspective on handling incoming webhooks.

6. Explore Developer Tools: Leverage Customer.io's developer tools, including the API Playground, to test API calls directly within the dashboard without writing code. This can accelerate development and debugging cycles. The Customer.io API documentation often highlights these tools.

Troubleshooting the first call

When making your initial API call to Customer.io, several common issues can arise. Here's a guide to diagnosing and resolving them:

• Incorrect API Keys or Site ID:

  • Symptom: Authentication errors (e.g., 401 Unauthorized).
  • Resolution: Double-check that you are using the correct Site ID for the Tracking API and the correct API Key for the Messaging API. Ensure there are no leading or trailing spaces in the keys. Confirm that the key used corresponds to the environment (e.g., development vs. production) you intend to hit. Remember that these keys are environment-specific.

• Incorrect Endpoint:

  • Symptom: 404 Not Found or unexpected behavior.
  • Resolution: Verify that the URL for your API request matches the Customer.io API documentation for the specific action you are trying to perform. The Tracking API and Messaging API have distinct base URLs and paths. For instance, customer identification uses a different path than event tracking. Refer to the Customer.io API reference for precise endpoint URLs.

• Missing or Malformed Request Body:

  • Symptom: 400 Bad Request errors or data not appearing as expected.
  • Resolution: Ensure your request body is valid JSON and includes all required fields as specified by the Customer.io API for the particular endpoint. For identifying customers, an email field is typically mandatory. Check for correct data types (e.g., numbers for numeric fields, strings for text). Pay attention to nested objects if present.

• Content-Type Header:

  • Symptom: Requests are rejected or parsed incorrectly.
  • Resolution: For requests with a JSON body, ensure the Content-Type header is set to application/json. Without this, the API server may not correctly interpret your request payload. This is a common requirement for HTTP POST and PUT requests with JSON payloads.

• Network or Firewall Issues:

  • Symptom: Connection timeouts or inability to reach the Customer.io API domains.
  • Resolution: Confirm that your network environment allows outbound connections to track.customer.io and api.customer.io on standard HTTPS port 443. If you are behind a corporate firewall, you may need to whitelist these domains.

• Rate Limiting:

  • Symptom: 429 Too Many Requests after multiple successful calls.
  • Resolution: Customer.io implements rate limits to prevent abuse and ensure service stability. If you encounter this, implement exponential backoff or ensure your application adheres to the documented rate limits. Details on specific rate limits are available in the Customer.io API documentation on rate limits.

• SDK-specific Issues:

  • Symptom: Errors originating from the SDK library itself.
  • Resolution: Ensure you are using the latest version of the SDK. Consult the SDK's documentation and GitHub repository for common issues or known bugs. SDKs often provide more verbose error messages than raw API responses, which can aid in debugging.