---
title: Track
description: This guide demonstrates how to interact with the OpenPanel API using cURL. These examples provide a low-level understanding of the API endpoints and can be useful for testing or for integrations where a full SDK isn't available.
---

## Good to know

- If you want to track **geo location** you'll need to pass the `ip` property as a header `x-client-ip`
- If you want to track **device information** you'll need to pass the `user-agent` property as a header `user-agent`

## Authentication

All requests to the OpenPanel API require authentication. You'll need to include your `clientId` and `clientSecret` in the headers of each request.

```bash
-H "openpanel-client-id: YOUR_CLIENT_ID" \
-H "openpanel-client-secret: YOUR_CLIENT_SECRET"
```

## Usage

### Base URL

All API requests should be made to:

```
https://api.openpanel.dev
```

### Tracking Events

To track an event:

```bash
curl -X POST https://api.openpanel.dev/track \
-H "Content-Type: application/json" \
-H "openpanel-client-id: YOUR_CLIENT_ID" \
-H "openpanel-client-secret: YOUR_CLIENT_SECRET" \
-d '{
  "type": "track",
  "payload": {
    "name": "my_event",
    "properties": {
      "foo": "bar"
    }
  }
}'
```

### Identifying Users

To identify a user:

```bash
curl -X POST https://api.openpanel.dev/track \
-H "Content-Type: application/json" \
-H "openpanel-client-id: YOUR_CLIENT_ID" \
-H "openpanel-client-secret: YOUR_CLIENT_SECRET" \
-d '{
  "type": "identify",
  "payload": {
    "profileId": "123",
    "firstName": "Joe",
    "lastName": "Doe",
    "email": "joe@doe.com",
    "properties": {
      "tier": "premium"
    }
  }
}'
```

### Creating Aliases
To create an alias for a user:

```bash
curl -X POST https://api.openpanel.dev/track \
-H "Content-Type: application/json" \
-H "openpanel-client-id: YOUR_CLIENT_ID" \
-H "openpanel-client-secret: YOUR_CLIENT_SECRET" \
-d '{
  "type": "alias",
  "payload": {
    "profileId": "1",
    "alias": "a1"
  }
}'
```

### Incrementing Properties
To increment a numeric property:

```bash
curl -X POST https://api.openpanel.dev/track \
-H "Content-Type: application/json" \
-H "openpanel-client-id: YOUR_CLIENT_ID" \
-H "openpanel-client-secret: YOUR_CLIENT_SECRET" \
-d '{
  "type": "increment",
  "payload": {
    "profileId": "1",
    "property": "visits",
    "value": 1
  }
}'
```

### Decrementing Properties
To decrement a numeric property:

```bash
curl -X POST https://api.openpanel.dev/track \
-H "Content-Type: application/json" \
-H "openpanel-client-id: YOUR_CLIENT_ID" \
-H "openpanel-client-secret: YOUR_CLIENT_SECRET" \
-d '{
  "type": "decrement",
  "payload": {
    "profileId": "1",
    "property": "visits",
    "value": 1
  }
}'
```

### Error Handling
The API uses standard HTTP response codes to indicate the success or failure of requests. In case of an error, the response body will contain more information about the error.
Example error response:

```json
{
  "error": "Invalid client credentials",
  "status": 401
}
```

### Rate Limiting

The API implements rate limiting to prevent abuse. If you exceed the rate limit, you'll receive a 429 (Too Many Requests) response. The response will include headers indicating your rate limit status.

Best Practices
	1.	Always use HTTPS to ensure secure communication.
	2.	Store your clientId and clientSecret securely and never expose them in client-side code.
	3.	Implement proper error handling in your applications.
	4.	Respect rate limits and implement exponential backoff for retries.