Getting Started

This guide walks you through signing up, creating a project, sending your first event, and verifying it in the customer timeline. By the end, you will have a working segment and an automated workflow.

Prerequisites — a running Timonier instance at http://localhost:3010 (platform UI) and http://localhost:3030 (CDP API), plus an authenticator app such as Google Authenticator or Authy on your phone.

1. Sign Up and Create Your First Project

Create your account

1. Open http://localhost:3010/signup in your browser.
2. Fill in your email, first name, and last name, then click Sign Up.
3. Check your inbox for a verification email and click the link it contains. The link brings you to a page that displays a QR code.
4. Scan the QR code with your authenticator app to register Timonier as a TOTP source. The page also shows the base32 secret in case you prefer to enter it manually.
5. Enter the 6-digit code displayed by your authenticator app and click Verify. You are now logged in and redirected to the project selector.

Create an organization

1. On the project selector page (/), click Create Organization.
2. Enter an Organization Name (for example Acme Corp) and a Slug (lowercase letters, numbers, and hyphens — for example acme-corp).
3. Click Create Organization.

Create a project

1. Back on the project selector, find your new organization and click New Project inside it.
2. Enter a Project Name (for example My App) and a Slug (for example my-app).
3. Click Create Project. You are redirected to the project dashboard.

2. Get Your API Key

1. In the sidebar, click API Keys.
2. Click New API Key (top-right corner of the page).
3. Enter a descriptive Key Name (for example Backend Server) and click Create API Key.
4. The next page displays your key once. Copy it now and store it somewhere safe (for example in an environment variable or a secrets manager). You will not be able to see it again.

Export the key so the cURL commands below can reference it:

export TIMONIER_API_KEY="<paste-your-key-here>"

3. Send Your First Event

The CDP API runs on port 3030 and accepts JSON payloads authenticated with a Bearer token.

Identify a customer

Use POST /v1/identify to create or update a customer profile. Traits are merged with any existing data.

curl -X POST http://localhost:3030/v1/identify \
  -H "Authorization: Bearer $TIMONIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "user_001",
    "traits": {
      "email": "jane@example.com",
      "name": "Jane Doe",
      "plan": "pro"
    }
  }'

A successful response returns 202 Accepted with a command ID:

{
  "success": true,
  "command_id": "550e8400-e29b-41d4-a716-446655440000"
}

The command_id is a unique identifier for the queued operation. A 202 status means the request has been accepted for asynchronous processing.

Track an event

Use POST /v1/track to record a custom event for the customer you just identified.

curl -X POST http://localhost:3030/v1/track \
  -H "Authorization: Bearer $TIMONIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "user_001",
    "event": "purchase",
    "properties": {
      "item": "T-Shirt",
      "amount": 29.99,
      "currency": "USD"
    }
  }'

The response format is the same as for identify:

{
  "success": true,
  "command_id": "661f9511-f33a-42e5-b817-557766551111"
}

Field reference

Error responses

Errors follow a consistent shape:

{
  "error": "bad_request",
  "message": "customer_id: exceeds maximum length of 255 characters"
}

Common HTTP status codes:

4. Verify It Worked

1. Go back to the platform UI at http://localhost:3010.
2. In the sidebar, click Customers.
3. The customer list shows Jane Doe with the external ID user_001.
4. Click the customer row to open the detail page.
5. The Attributes section displays the traits you sent (email, name, plan).
6. Scroll down to the Events timeline. The purchase event appears with its properties (item, amount, currency).

5. Create Your First Segment

Segments group customers that match a condition. Membership is evaluated automatically and kept up to date as traits and events change.

1. In the sidebar, click Segments, then click New Segment.
2. Fill in the form:
   • Name: Pro Users
   • Description: Customers on the pro plan
   • Condition (JSON):

     {
       "type": "trait",
       "name": "plan",
       "op": "equals",
       "value": "pro"
     }
     

3. Click Create Segment.
4. Open the segment detail page. Jane Doe appears as a member because her plan trait equals pro.

Condition operators

Trait conditions support these operators:

Conditions can be composed with and, or, and not wrappers:

{
  "type": "and",
  "conditions": [
    { "type": "trait", "name": "plan", "op": "equals", "value": "pro" },
    { "type": "event", "event_name": "purchase" }
  ]
}

6. Create Your First Workflow

Workflows automate actions in response to triggers. In this section you create a workflow that sends a welcome email when the purchase event is tracked.

Create an email template

Before creating the workflow you need an email template.

1. In the sidebar, click Email Templates, then click New Email Template.
2. Enter a Name (for example Purchase Thank You) and click Create.
3. On the next page, click Open Designer to open the visual email editor.
4. Design your email using the drag-and-drop editor. At a minimum add a text block with a short thank-you message.
5. Click Save in the designer, then go back to the template detail page and click Publish. Only published templates can be used in workflows.

Create the workflow

1. In the sidebar, click Workflows, then click New Workflow.
2. Fill in the form:
   • Name: Purchase Follow-Up
   • Description: Send a thank-you email after a purchase
   • Trigger Type: select Event Occurred
   • Event Name: purchase
   • Frequency: select Once per customer
3. Click Create Workflow.

Add an email step

1. On the workflow detail page, click Builder to open the visual canvas.
2. Click Add Step and choose Email.
3. In the step configuration panel, select the Purchase Thank You template you published earlier.
4. Click Save on the step configuration.

Activate the workflow

1. Go back to the workflow detail page.
2. Click Activate. The workflow is now live.

From this point, any customer who triggers a purchase event for the first time will receive the thank-you email.

7. Next Steps

You now have a working project with customer data flowing in, a segment that groups customers, and an automated workflow.

Here are a few directions to explore:

• API Integration Guide — deeper coverage of all CDP endpoints including page, merge, batch, and customer queries. See API Integration Guide.
• OpenAPI specification — the full API contract lives in domains/cdp/openapi.yaml in the repository.
• Segments — combine trait and event conditions with and / or / not logic, add time windows, and use count-based event conditions.
• Workflows — add time delays, branching (true/false or multi-split), random cohorts for A/B testing, attribute updates, webhooks, and wait-until conditions.
• Email Templates — use the visual designer with MJML to build responsive emails, configure UTM tracking, and manage open/click tracking.