People API

The People API (also called User API) allows you to identify users and update their attributes from your client application. This enables user tracking and targeted surveys.

User identification is an Enterprise feature. Free and Pro plans will receive a 403 Forbidden response when attempting to identify users.

Identify a User

Identify a user and optionally set or update their attributes.

POST /api/v1/client/{environmentId}/user

curl -X POST https://app.formbricks.com/api/v1/client/{environmentId}/user \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "attributes": {
      "email": "user@example.com",
      "name": "John Doe",
      "plan": "enterprise",
      "signupDate": "2024-01-15"
    }
  }'

Path Parameters

environmentId

string

required

Your Formbricks environment ID

Body Parameters

userId

string

required

Your unique identifier for this user (must be consistent across your application)

attributes

object

Contact attributes to set or update (all values must be strings)

Response

Returns the created or updated contact object:

{
  "id": "con_...",
  "createdAt": "2021-01-01T00:00:00.000Z",
  "updatedAt": "2021-01-01T00:00:00.000Z",
  "environmentId": "env_...",
  "userId": "user_123",
  "attributes": {
    "email": "user@example.com",
    "name": "John Doe",
    "plan": "enterprise",
    "signupDate": "2024-01-15"
  }
}

string

Formbricks contact ID

createdAt

string

ISO 8601 timestamp of when the contact was created

updatedAt

string

ISO 8601 timestamp of when the contact was last updated

environmentId

string

The environment this contact belongs to

userId

string

Your unique identifier for this user

attributes

object

All attributes associated with this contact

Use Cases

Identify users when they log in to your application:

// After successful login
async function handleLogin(user) {
  // Your login logic...
  
  // Identify user in Formbricks
  await fetch('https://app.formbricks.com/api/v1/client/env_123/user', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      userId: user.id,
      attributes: {
        email: user.email,
        name: user.name,
        plan: user.subscription.plan,
        accountType: user.accountType
      }
    })
  });
}

Update Attributes on Change

Update user attributes when they change in your application:

// When user upgrades their plan
async function handlePlanUpgrade(userId, newPlan) {
  // Update in your database...
  
  // Update in Formbricks
  await fetch('https://app.formbricks.com/api/v1/client/env_123/user', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      userId: userId,
      attributes: {
        plan: newPlan,
        upgradedAt: new Date().toISOString()
      }
    })
  });
}

Progressive Attribute Building

Build up user attributes over time as you learn more:

// Initial identification
await identifyUser({
  userId: 'user_123',
  attributes: {
    email: 'user@example.com'
  }
});

// Later, add more attributes
await identifyUser({
  userId: 'user_123',
  attributes: {
    company: 'Acme Corp',
    role: 'Product Manager'
  }
});

// Attributes are merged, not replaced

Attribute Management

Attribute Merging

When you identify a user multiple times, attributes are merged:

// First call
await identifyUser({
  userId: 'user_123',
  attributes: {
    email: 'user@example.com',
    name: 'John Doe'
  }
});
// Result: { email, name }

// Second call
await identifyUser({
  userId: 'user_123',
  attributes: {
    plan: 'pro',
    name: 'John Smith' // Updated
  }
});
// Result: { email, name: 'John Smith', plan }

Attribute Types

All attribute values must be strings:

// ✅ Correct
await identifyUser({
  userId: 'user_123',
  attributes: {
    plan: 'pro',
    accountAge: '30',
    isActive: 'true'
  }
});

// ❌ Incorrect - numbers and booleans not allowed
await identifyUser({
  userId: 'user_123',
  attributes: {
    accountAge: 30, // Should be '30'
    isActive: true  // Should be 'true'
  }
});

Common Attributes

Recommended attributes for most applications:

email - User’s email address
name - User’s full name
firstName - User’s first name
lastName - User’s last name
plan - Subscription plan
role - User role
company - Company name
department - Department
signupDate - When the user signed up
lastSeenAt - When the user was last active

Targeting Surveys by Attributes

Once you’ve identified users and set attributes, you can target surveys to specific segments:

In Formbricks Dashboard

Create audience segments based on attributes:

Show survey only to users where plan = 'enterprise'
Target users where role = 'admin'
Exclude users where lastSeenAt > 30 days ago

Attribute-Based Survey Logic

// Identify user
await identifyUser({
  userId: 'user_123',
  attributes: {
    plan: 'free',
    trialDaysLeft: '3'
  }
});

// Formbricks can now show surveys targeting:
// - Free plan users
// - Users with trial ending soon
// - etc.

Integration with Response API

When a user submits a response, their attributes are automatically included:

// 1. Identify user
await identifyUser({
  userId: 'user_123',
  attributes: {
    email: 'user@example.com',
    plan: 'pro'
  }
});

// 2. Submit response with userId
await fetch('https://app.formbricks.com/api/v1/client/env_123/responses', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    surveyId: 'srv_456',
    userId: 'user_123',
    finished: true,
    data: { qst_1: 'answer' }
  })
});

// 3. Response includes contact attributes
// Response object will have:
// {
//   "contactId": "con_...",
//   "contactAttributes": {
//     "email": "user@example.com",
//     "plan": "pro"
//   },
//   ...
// }

CORS Support

The People API supports CORS for browser-based applications:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST, OPTIONS
Access-Control-Allow-Headers: Content-Type

Preflight OPTIONS requests are cached for 1 hour.

Error Responses

Enterprise Feature Required

Non-Enterprise plans receive:

{
  "message": "User identification is only available for enterprise users."
}

Invalid Request

{
  "message": "Fields are missing or incorrectly formatted",
  "details": {
    "userId": "Required field"
  }
}

Invalid Environment

{
  "message": "Environment not found"
}

Best Practices

Consistent User IDs: Always use the same userId for a user across your application
Identify Early: Identify users as soon as they log in
Keep Attributes Updated: Update attributes when they change in your system
Minimal Attributes: Only store attributes you’ll actually use
String Values: Always convert attribute values to strings
Privacy Compliance: Ensure you have permission to track and store user data
Handle Errors: Gracefully handle cases where user identification fails

Privacy Considerations

Always ensure you have proper consent and comply with privacy regulations (GDPR, CCPA, etc.) when identifying users and storing their attributes.

Only store attributes you need
Provide users with ability to opt-out
Honor data deletion requests
Don’t store sensitive information (passwords, credit cards, etc.)
Be transparent about what data you’re collecting

Integration with Formbricks SDK

If you’re using the Formbricks JavaScript SDK, user identification is simplified:

import formbricks from '@formbricks/js';

formbricks.init({
  environmentId: 'env_123',
  apiHost: 'https://app.formbricks.com',
  userId: 'user_123',
  attributes: {
    email: 'user@example.com',
    plan: 'pro'
  }
});

// Update attributes later
formbricks.setUserId('user_123');
formbricks.setAttribute('plan', 'enterprise');

The SDK handles the API calls for you and manages the user state.

Getting Started

Management API

Client API

Identify a User

Path Parameters

Body Parameters

Response

Use Cases

Update Attributes on Change

Progressive Attribute Building

Attribute Management

Attribute Merging

Attribute Types

Common Attributes

Targeting Surveys by Attributes

In Formbricks Dashboard

Attribute-Based Survey Logic

Integration with Response API

CORS Support

Error Responses

Enterprise Feature Required

Invalid Request

Invalid Environment

Best Practices

Privacy Considerations

Integration with Formbricks SDK

Getting Started

Management API

Client API

Documentation Index

​Identify a User

​Path Parameters

​Body Parameters

​Response

​Use Cases

​Identify Users at Login

​Update Attributes on Change

​Progressive Attribute Building

​Attribute Management

​Attribute Merging

​Attribute Types

​Common Attributes

​Targeting Surveys by Attributes

​In Formbricks Dashboard

​Attribute-Based Survey Logic

​Integration with Response API

​CORS Support

​Error Responses

​Enterprise Feature Required

​Invalid Request

​Invalid Environment

​Best Practices

​Privacy Considerations

​Integration with Formbricks SDK

Identify a User

Path Parameters

Body Parameters

Response

Use Cases

Identify Users at Login

Update Attributes on Change

Progressive Attribute Building

Attribute Management

Attribute Merging

Attribute Types

Common Attributes

Targeting Surveys by Attributes

In Formbricks Dashboard

Attribute-Based Survey Logic

Integration with Response API

CORS Support

Error Responses

Enterprise Feature Required

Invalid Request

Invalid Environment

Best Practices

Privacy Considerations

Integration with Formbricks SDK