Core APIsPeople

People API

Create, update, and manage user profiles with the Flameup People API

Overview

The People API allows you to manage user profiles in Flameup. Each person represents a user in your system with their contact information, attributes, and engagement history.

Required Permission: people:read for GET requests, people:write for POST/PUT requests, people:delete for DELETE requests. Note: API keys automatically target the workspace they were created in.

Person Object

A person in Flameup has the following structure:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "workspace_id": "ws_abc123",
  "userId": "user_12345",
  "email": "jane@example.com",
  "traits": {
    "first_name": "Jane",
    "last_name": "Doe",
    "plan": "premium",
    "company": "Acme Inc"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:45:00Z"
}

Field Reference

FieldTypeDescription
idUUIDFlameup's internal identifier (read-only)
workspace_idstringWorkspace identifier (read-only)
userIdstringYour unique identifier for this user (required, max 255 chars)
emailstringUser's email address (optional, max 254 chars)
phonestringUser's phone number (optional, max 50 chars)
anonymousIdstringAnonymous identifier for merging anonymous activity (transient, not persisted)
traitsobjectCustom user attributes (see validation rules)
created_attimestampWhen the person was created (read-only)
updated_attimestampWhen the person was last updated (read-only)

Create a Person

Create a new person profile.

Endpoint: POST /api/v1/people

const response = await fetch(
  `https://api.flameup.ai/api/v1/people`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${API_KEY}`
    },
    body: JSON.stringify({
      userId: 'user_12345',           // Required: your unique ID
      email: 'jane@example.com',       // Optional but recommended
      phone: '+15551234567',           // Optional
      traits: {
        first_name: 'Jane',
        last_name: 'Doe',
        plan: 'premium',
        company: 'Acme Inc'
      }
    })
  }
);

const person = await response.json();
Use a stable, unique identifier from your system as the userId. Database primary keys or UUIDs work well.
The identifier can be sent as userId, user_id, or external_id — these are aliases for the same value.

Get a Person

Retrieve a person by their userId — the external identifier you provided when creating them.

Endpoint: GET /api/v1/people/{id}

The {id} path parameter is your external userId, not the Flameup id UUID returned in the response body.
const response = await fetch(
  `https://api.flameup.ai/api/v1/people/${userId}`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
);

const person = await response.json();

Update a Person

Update an existing person's attributes.

Endpoint: PUT /api/v1/people/{id}

The {id} path parameter is your external userId, not the Flameup id UUID.
const response = await fetch(
  `https://api.flameup.ai/api/v1/people/${userId}`,
  {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${API_KEY}`
    },
    body: JSON.stringify({
      traits: {
        plan: 'enterprise',           // Update existing
        renewal_date: '2025-01-15'    // Add new attribute
      }
    })
  }
);

const result = await response.json();
// { "message": "Person updated successfully" }

A successful update returns 200 OK with a confirmation message, not the updated person object:

{
  "message": "Person updated successfully"
}
Updates are merged with existing trait data. Setting a trait to null stores a null value for that key — it does not remove the key.

Upsert a Person

Create a person if they don't exist, or update them if they do. This is the recommended approach for most integrations.

Endpoint: POST /api/v1/people/upsert

const response = await fetch(
  `https://api.flameup.ai/api/v1/people/upsert`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${API_KEY}`
    },
    body: JSON.stringify({
      userId: 'user_12345',
      email: 'jane@example.com',
      traits: {
        first_name: 'Jane',
        last_name: 'Doe',
        last_login: new Date().toISOString()
      }
    })
  }
);

const person = await response.json();

Upsert returns 201 Created with the same person object as Create a Person, whether the person was newly created or updated.

List People

Retrieve a paginated list of people.

Endpoint: GET /api/v1/people

Query Parameters

ParameterTypeDefaultDescription
limitinteger50Number of results (max 500)
offsetinteger0Pagination offset
const params = new URLSearchParams({
  limit: '50',
  offset: '0'
});

const response = await fetch(
  `https://api.flameup.ai/api/v1/people?${params}`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
);

const { people, total, limit, offset } = await response.json();

Response:

{
  "people": [...],
  "total": 1250,
  "limit": 50,
  "offset": 0
}

Search People

Programmatic search and filtering are not yet available. The GET /api/v1/people/search endpoint currently ignores all query parameters and returns the same paginated people list as List People. To look up a specific person, use Get a Person with their userId.

Batch Upsert

Create or update multiple people in a single request.

Endpoint: POST /api/v1/people/batch

const response = await fetch(
  `https://api.flameup.ai/api/v1/people/batch`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${API_KEY}`
    },
    body: JSON.stringify({
      identify: [
        {
          userId: 'user_001',
          email: 'alice@example.com',
          traits: { first_name: 'Alice', plan: 'basic' }
        },
        {
          userId: 'user_002',
          email: 'bob@example.com',
          traits: { first_name: 'Bob', plan: 'premium' }
        }
      ]
    })
  }
);

const { results, total } = await response.json();

The response contains a results array with one entry per submitted record, plus a total count:

{
  "results": [
    {
      "type": "identify",
      "index": 0,
      "success": true,
      "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "userId": "user_001" }
    },
    {
      "type": "identify",
      "index": 1,
      "success": false,
      "error": "validation error message"
    }
  ],
  "total": 2
}
FieldTypeDescription
typestringOperation type (identify)
indexintegerPosition of the record in the submitted identify array
successbooleanWhether this record was processed successfully
errorstringError message (present only when success is false)
dataobjectThe resulting person object (present only when success is true)

Delete a Person

Delete a person and all associated data.

Endpoint: DELETE /api/v1/people/{id}

The {id} path parameter is your external userId, not the Flameup id UUID.
const response = await fetch(
  `https://api.flameup.ai/api/v1/people/${userId}`,
  {
    method: 'DELETE',
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
);

if (response.ok) {
  console.log('Person deleted');
}

A successful delete returns 200 OK:

{
  "message": "Person deleted successfully"
}
This action is irreversible. All associated events and device tokens will also be deleted.

Get Person Events

Retrieve events for a specific person. See the Events API for how events are tracked.

Endpoint: GET /api/v1/people/{id}/events

The {id} path parameter is your external userId. This endpoint requires the API key's events:write permission.

Query Parameters

ParameterTypeDefaultDescription
limitinteger50Number of events to return (max 500)
const response = await fetch(
  `https://api.flameup.ai/api/v1/people/${userId}/events?limit=50`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
);

const { events, total } = await response.json();

Response:

{
  "events": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "purchase_completed",
      "parameters": { "amount": 49.99, "currency": "USD" },
      "created_at": "2024-01-20T14:45:00Z"
    }
  ],
  "total": 1
}

Each event object contains the event name in the type field, along with its parameters and created_at timestamp.

Workspace-level people statistics are available in the Flameup dashboard.

Best Practices

The upsert endpoint is ideal for most use cases. It handles both creation and updates in a single call, making your integration simpler and more resilient.

Was this page helpful?