Flameup Developer
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.

Get a Person

Retrieve a person by their Flameup ID.

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

const response = await fetch(
  `https://api.flameup.ai/api/v1/people/${personId}`,
  {
    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}

const response = await fetch(
  `https://api.flameup.ai/api/v1/people/${personId}`,
  {
    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 person = await response.json();
Updates are merged with existing data. To remove an attribute, set it to null.

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 result = await response.json();
console.log('Was created:', result.was_created);  // true if new, false if updated

The response includes a was_created boolean indicating 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
statusstring-Filter by status: active, unsubscribed, bounced
searchstring-Search by name or email
created_sincetimestamp-Filter by creation date
updated_sincetimestamp-Filter by last update date
const params = new URLSearchParams({
  limit: '50',
  status: 'active',
  search: 'acme'
});

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

Search for people by specific criteria.

Endpoint: GET /api/v1/people/search

Query Parameters

ParameterTypeDescription
qstringGeneral search query
emailstringExact email match
userIdstringExact userId match
limitintegerNumber of results (default 10)
// Search by email
const response = await fetch(
  `https://api.flameup.ai/api/v1/people/search?email=jane@example.com`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
);

const { people } = await response.json();
const person = people[0];  // First match

Batch Upsert

Create or update multiple people in a single request (max 100).

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({
      people: [
        {
          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' }
        },
        // ... up to 100 people
      ]
    })
  }
);

const { people, created_count, updated_count } = await response.json();
Maximum 100 people per batch request. For larger imports, split into multiple requests.

Delete a Person

Delete a person and all associated data.

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

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

if (response.ok) {
  console.log('Person deleted');
}
This action is irreversible. All associated events and device tokens will also be deleted.

Get Person Events

Retrieve events for a specific person.

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

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

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

Get People Statistics

Get aggregate statistics for your workspace.

Endpoint: GET /api/v1/people/stats

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

const stats = await response.json();
console.log(`Total: ${stats.total}, Active: ${stats.active}`);

Response:

{
  "total": 15420,
  "active": 14200,
  "unsubscribed": 850,
  "bounced": 370,
  "recent": 245
}

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?

Last updated Mar 1, 2026

Built with Documentation.AI