Quick Start

From nothing to a verified event in ten minutes

Quick Start

Two calls and a check. By the end you will have a person in your workspace, an event attached to them, and proof it arrived.

Prerequisites: a Flameup account. Sign up at app.flameup.ai if you have not already.

Step 1: Create an API key

Open API Keys

In the dashboard, go to Settings → API Keys and click Create API Key.

Say where the key will be used

Choose On my server for this guide, and tick events:write, people:write and events:read.

If you are integrating a mobile app or a website instead, choose In my app or website — there is nothing to tick, and the key you get is safe to ship in your bundle.

Copy it now

The key is shown once. It looks like ws_live_abc12345_abc123.a1b2c3… — the part before the dot identifies it, the part after is the secret.

Keys carry a live or test label, but the label does not separate your data — both write to the same workspace. There is no sandbox today, so treat anything you send as real.

The workspace is derived from the key, so it never appears in a URL or a body.

Step 2: Identify a person

POST /identify creates or updates one person, keyed on your own user id — whatever your database already calls them.

const API_KEY = 'ws_live_abc12345_abc123.your_secret_here';
const BASE_URL = 'https://api.flameup.ai/api/v1';

const headers = {
  'Content-Type': 'application/json',
  'Authorization': `Bearer ${API_KEY}`
};

await fetch(`${BASE_URL}/identify`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    userId: 'user_12345',
    email: 'jane@example.com',
    traits: { first_name: 'Jane', plan: 'premium' }
  })
});

import requests

API_KEY = 'ws_live_abc12345_abc123.your_secret_here'
BASE_URL = 'https://api.flameup.ai/api/v1'
headers = {'Authorization': f'Bearer {API_KEY}'}

requests.post(f'{BASE_URL}/identify', headers=headers, json={
    'userId': 'user_12345',
    'email': 'jane@example.com',
    'traits': {'first_name': 'Jane', 'plan': 'premium'}
})

curl -X POST https://api.flameup.ai/api/v1/identify \
  -H "Authorization: Bearer ws_live_abc12345_abc123.your_secret_here" \
  -H 'Content-Type: application/json' \
  -d '{
    "userId": "user_12345",
    "email": "jane@example.com",
    "traits": { "first_name": "Jane", "plan": "premium" }
  }'

Traits are merged, not replaced — send only what changed. Call this again whenever a trait changes; journeys re-read traits at every decision point, so an updated trait re-routes a person mid-flight.

Step 3: Track an event

POST /track records something the person did. This is what campaigns trigger on.

await fetch(`${BASE_URL}/track`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    userId: 'user_12345',
    event: 'purchase_completed',
    parameters: { amount: 49.99, currency: 'USD', plan: 'premium' }
  })
});

curl -X POST https://api.flameup.ai/api/v1/track \
  -H "Authorization: Bearer ws_live_abc12345_abc123.your_secret_here" \
  -H 'Content-Type: application/json' \
  -d '{
    "userId": "user_12345",
    "event": "purchase_completed",
    "parameters": { "amount": 49.99, "currency": "USD" }
  }'

You do not have to identify someone before tracking them. /track creates the person if the id is new, and says "person_created": true when it did — which is how you catch a mistyped identifier rather than discovering it weeks later.

Campaign triggers match the event name exactly, so pick names you are willing to keep. object_action in snake_case is the usual convention: purchase_completed, trial_started.

Step 4: Check it arrived

Read the events back for that person:

curl "https://api.flameup.ai/api/v1/people/user_12345/events" \
  -H "Authorization: Bearer ws_live_abc12345_abc123.your_secret_here"

{
  "success": true,
  "person_id": "user_12345",
  "events": [
    {
      "id": "80c2a0d3-dd72-4fde-9dfc-c0b76dd3e42d",
      "type": "purchase_completed",
      "parameters": { "amount": 49.99, "currency": "USD" },
      "created_at": "2026-01-15T10:30:00Z"
    }
  ],
  "total": 1
}

person_id echoes the identifier you asked for — your own id, not a Flameup UUID.

You can also open People in the dashboard and find user_12345 there.

A 403 here means the key is missing events:read — the read scope is separate from the write one on purpose. Add it in Settings → API Keys.

What's next

Send push notifications

Register a device token, then send. Needs your FCM credentials uploaded in Settings → Messaging Channels → Push first.

Track from your app

Copy-paste Node and Python clients, plus the Flutter integration recipe.

People API

Read, search, update and batch-upsert people.

Trigger campaigns

Campaigns are built in the dashboard; the API starts them.

Was this page helpful?