Back to Docs

People & Customers API

Track your customers and their organizations in Simple Product.

Identifying Customers

Simple Product uses these fields to identify customers (in order of priority):

  1. externalId - Your internal user ID (most reliable)
  2. email - Customer's email address

When you submit feedback or call the People API with these identifiers, Simple Product will: create a new customer record if none exists, update the existing record if found, and link feedback to the customer.

JavaScript SDK Pattern

class SimpleProduct {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://simpleproduct.dev/api/v1';
  }

  async identify(user) {
    // Call this when a user logs in or updates their profile
    return fetch(`${this.baseUrl}/people`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        externalId: user.id,
        email: user.email,
        name: user.name,
        properties: {
          plan: user.plan,
          createdAt: user.createdAt,
          // Add any custom properties
        },
      }),
    });
  }

  async feedback(content, options = {}) {
    return fetch(`${this.baseUrl}/feedback`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        title: options.title || 'Feedback',
        content,
        externalId: options.userId,
        email: options.email,
        source: options.source || 'sdk',
        metadata: options.metadata,
      }),
    });
  }
}

// Usage
const sp = new SimpleProduct('your_api_key');

// When user logs in
await sp.identify({
  id: 'user_123',
  email: 'john@example.com',
  name: 'John Doe',
  plan: 'pro',
});

// When user submits feedback
await sp.feedback('Love the new feature!', {
  userId: 'user_123',
  source: 'feedback-modal',
});

People API Reference

POST /api/v1/people

Create or update a customer record.

Request Body

{ "email": "customer@example.com", "name": "John Doe", "externalId": "user_123", "properties": { "plan": "pro", "company": "Acme Inc" } }

GET /api/v1/people?email=customer@example.com

Look up a customer by email.

GET /api/v1/people/:id

Get a customer by ID.

Organizations

Link customers to organizations for B2B use cases. Organizations are automatically linked to people based on email domain.

// Create/update organization
await fetch('https://simpleproduct.dev/api/v1/organizations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Acme Inc',
    domain: 'acme.com',
    properties: {
      plan: 'enterprise',
      seats: 50,
      industry: 'Technology',
    },
  }),
});

POST /api/v1/organizations

Create or update an organization.

Request Body

{ "name": "Acme Inc", "domain": "acme.com", "properties": { "plan": "enterprise", "seats": 50 } }

Best Practices

  • 1.Always include externalId - Email can change, your user ID won't
  • 2.Call identify on login - Keep customer data fresh
  • 3.Use properties for segmentation - Plan, role, company size, etc.
  • 4.Track source on feedback - Know where feedback comes from