Detecting User Changes

Users are the most commonly-polled resource in Volunteer integrations. Almost every partner integration that syncs data to an external system needs to detect “which users were created or modified since last time” — for sync to a CRM, for triggering follow-up workflows, for keeping reporting databases current. This page covers the User-specific polling pattern in production-grade detail. It builds on the foundation in Polling Overview with User-specific filters, edge cases, and the central caveat: participation changes don’t advance updated_at, so polling Users alone misses a significant class of “user activity” events. If you haven’t yet, skim the Polling Overview for the core polling pattern.

When to use this workflow

Scenario	This workflow fits
Sync user records to an external CRM	✓ Primary use case
Mirror VOMO users into a data warehouse	✓
Trigger follow-up workflows on new user signup	✓ With the new-user detection pattern
Detect users who recently updated their profile	✓
Detect when a user participated in a shift	✗ Doesn’t work via User polling — see the participation caveat
Detect when a user earned a certificate	✗ Same caveat — track via separate polling or admin UI
One-time full user sync	✗ Use the initial-sync pattern instead

The baseline pattern

The simplest user-change polling worker:

JavaScript

async function pollUserChanges(customerId) {
  const lastSync = await getCheckpoint(customerId, 'user_sync');

  const params = new URLSearchParams({
    updated_after: lastSync.toISOString(),
  });

  let url = `https://api.vomo.org/v1/users?${params}`;
  let latestSeen = lastSync;
  let processedCount = 0;

  while (url) {
    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.VOMO_API_TOKEN}` },
    });
    if (!response.ok) throw new Error(`Poll failed: ${response.status}`);

    const page = await response.json();

    for (const user of page.data) {
      await processUserChange(customerId, user);

      const userUpdated = new Date(user.updated_at);
      if (userUpdated > latestSeen) latestSeen = userUpdated;
      processedCount++;
    }

    url = page.links.next;
  }

  await setCheckpoint(customerId, 'user_sync', latestSeen);

  return { processedCount, newCheckpoint: latestSeen };
}

// Schedule every 15 minutes
setInterval(() => pollUserChanges(customerId).catch(console.error), 15 * 60 * 1000);

This is the canonical shape. Most of this page adds layers on top.

Distinguishing new from modified users

updated_after returns both newly-created and modified users. Sometimes you want to treat them differently — fire a welcome email on creation, fire an update event on modification. The distinction: for newly-created users, created_at equals updated_at (or is very close). For updates, updated_at > created_at.

JavaScript

async function processUserChange(customerId, user) {
  const created = new Date(user.created_at);
  const updated = new Date(user.updated_at);
  const isNewlyCreated = updated.getTime() - created.getTime() < 1000; // <1 second apart

  if (isNewlyCreated) {
    await processNewUser(customerId, user);
  } else {
    await processUserUpdate(customerId, user);
  }
}

async function processNewUser(customerId, user) {
  // First-time-seeing-this-user logic
  await externalSystem.createUser(user);
  await sendWelcomeEmail(user);
}

async function processUserUpdate(customerId, user) {
  // Update-existing-user logic
  await externalSystem.updateUser(user);
}

Why this works (and why it’s approximate)

The heuristic assumes that creating a user produces created_at and updated_at simultaneously (with sub-second resolution). For most cases this is correct. Edge cases:

A user created and then immediately modified within the same poll window — both created_at and updated_at are recent, but they’re not equal. The heuristic might miss the “created” event and treat it as an update.
Bulk imports where many users are created in batch — they may all share the same created_at but have slightly different updated_at.

For more robust detection, track previously-seen User IDs:

JavaScript

async function processUserChange(customerId, user) {
  const previouslyKnown = await externalDb.userExists(customerId, user.id);

  if (!previouslyKnown) {
    await processNewUser(customerId, user);
    await externalDb.recordUserKnown(customerId, user.id);
  } else {
    await processUserUpdate(customerId, user);
  }
}

The cost: a per-user database lookup. The benefit: definitive new-vs-update detection. For most production integrations, the database approach is more reliable.

The participation caveat

The most important thing to understand about User polling: new participations do not advance the User’s updated_at.

Scenario	Does User’s `updated_at` advance?
User updates their email, phone, address	✓ Yes
User’s membership status changes	✓ Yes (likely)
User signs up for a Project Date	✗ No — the Participation is a separate record
User checks in to a shift	✗ No
User’s hours are recorded	✗ No
User is awarded a Certificate	✗ Likely no

This is the central polling caveat. Polling /users?updated_after=X will not detect new volunteer activity.

Why this matters

A partner integration that promises “we’ll detect when your volunteers serve” cannot deliver on that promise via User polling alone. The integration architecture needs to account for this gap.

What to do instead

For detecting new participations, three options:

Option A: Poll `GET /users/{id}` for each user

After detecting a user change via the list endpoint, fetch detail to see their full participation list:

JavaScript

async function pollWithParticipations(customerId) {
  const changedUsers = await pollUserChanges(customerId);

  for (const userSummary of changedUsers) {
    const userDetail = await fetch(
      `https://api.vomo.org/v1/users/${userSummary.id}`,
      { headers: { Authorization: `Bearer ${token}` } }
    ).then((r) => r.json());

    const lastKnownParticipations = await externalDb.getParticipationIds(
      customerId,
      userSummary.id
    );
    const newParticipations = (userDetail.data.participations ?? []).filter(
      (p) => !lastKnownParticipations.has(p.project_date_id)
    );

    for (const participation of newParticipations) {
      await processNewParticipation(customerId, userDetail.data, participation);
      await externalDb.recordParticipation(customerId, userSummary.id, participation);
    }
  }
}

Cost: This only catches new participations for users whose User record was modified for some other reason — which is unlikely to coincide with new participations. So this option mostly doesn’t work for the stated purpose.

Option B: Periodic full participation scan

On a slower cadence (daily, weekly), iterate all users and check their participations:

JavaScript

async function dailyParticipationScan(customerId) {
  const allUsers = await listAllUsers();

  for (const userSummary of allUsers) {
    const userDetail = await getUserDetail(userSummary.id);
    const lastKnown = await externalDb.getParticipationIds(customerId, userSummary.id);

    const newParticipations = (userDetail.participations ?? []).filter(
      (p) => !lastKnown.has(p.project_date_id)
    );

    for (const p of newParticipations) {
      await processNewParticipation(customerId, userDetail, p);
      await externalDb.recordParticipation(customerId, userSummary.id, p);
    }
  }
}

Cost: N+1 — one User list + one User detail per User. For an account with 5,000 users, this is 5,001 requests every scan. Throttle aggressively and schedule for off-peak.

Option C: Poll Project Dates instead

If your integration mainly needs participation data for specific Projects, poll the Project Dates and pull participants from there:

JavaScript

async function pollProjectDateParticipations(customerId, projectId) {
  const project = await getProjectDetail(projectId);
  const recentDates = (project.all_dates ?? []).filter((d) => {
    const dEnd = new Date(d.ends_at);
    const lookback = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
    return dEnd > lookback;
  });

  for (const date of recentDates) {
    const detail = await getProjectDate(date.id);
    const participants = detail.data.participants ?? [];

    for (const p of participants) {
      const known = await externalDb.participationKnown(customerId, date.id, p.id);
      if (!known) {
        await processNewParticipation(customerId, p);
        await externalDb.recordParticipationKnown(customerId, date.id, p.id);
      }
    }
  }
}

Cost: Bounded by recent Project Dates rather than all users. For active customers with predictable Project schedules, this scales better than Option B. The right choice depends on your integration’s specific needs. See Reconciliation Patterns for the structural approach.

Combining `updated_after` with other filters

The polling pattern can be narrowed with additional filters when not all users need processing:

Poll only verified users

JavaScript

async function pollVerifiedUserChanges(customerId) {
  const lastSync = await getCheckpoint(customerId, 'verified_user_sync');

  const params = new URLSearchParams({
    updated_after: lastSync.toISOString(),
    // Note: the API doesn't expose user_status as a filter; we'd filter client-side
  });

  let url = `https://api.vomo.org/v1/users?${params}`;
  let latestSeen = lastSync;

  while (url) {
    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${token}` },
    });
    const page = await response.json();

    const verified = page.data.filter((u) => u.user_status === 'VERIFIED');
    for (const user of verified) {
      await processUserChange(customerId, user);
      const userUpdated = new Date(user.updated_at);
      if (userUpdated > latestSeen) latestSeen = userUpdated;
    }

    url = page.links.next;
  }

  await setCheckpoint(customerId, 'verified_user_sync', latestSeen);
}

Note: the API doesn’t expose user_status as a server-side filter, so this is client-side filtering — the API returns all updated users, and your code filters in memory. The poll still consumes rate budget for all changed users, but downstream processing is narrowed.

Poll only users with email matches

JavaScript

async function pollUsersInDomain(customerId, domain) {
  const lastSync = await getCheckpoint(customerId, `user_sync_${domain}`);

  const params = new URLSearchParams({
    updated_after: lastSync.toISOString(),
    email_like: `@${domain}`,
  });

  // ... rest as before
}

This narrows server-side — useful for partner integrations scoped to a specific email domain (e.g., a corporate volunteer program’s employees).

Detecting deletions

Polling has a fundamental gap: deleted records don’t appear in queries. If a user is deleted in VOMO, polling /users?updated_after=X won’t show them — they’re just gone. For partner integrations that need to mirror deletions to external systems, the only path is reconciliation:

JavaScript

async function detectDeletedUsers(customerId) {
  // 1. Get all current VOMO users
  const currentUsers = await listAllUsers();
  const currentIds = new Set(currentUsers.map((u) => u.id));

  // 2. Compare to what your external system thinks exists
  const externalKnownIds = await externalDb.knownVomoUserIds(customerId);

  // 3. Find IDs in external but not in current
  const deletedIds = [...externalKnownIds].filter((id) => !currentIds.has(id));

  // 4. Mark deletions in external system
  for (const id of deletedIds) {
    await externalSystem.markUserDeleted(id);
    await externalDb.removeUserKnown(customerId, id);
  }

  return { deletedCount: deletedIds.length };
}

This is a slow reconciliation pattern — run daily or weekly because it’s a full-dataset operation. See Reconciliation Patterns.

A subtle gotcha: “deletion” vs. “not accessible”

A user may “disappear” from /users results for reasons other than deletion:

The user was moved to a different organization within the family
The token’s permissions changed
The user was banned or soft-deleted but still exists

Don’t assume “not in list” means “deleted.” Treat it as “not currently visible” and surface for review rather than immediately propagating as a deletion to the external system.

Reading user detail during the poll

The list endpoint returns abbreviated UserResource objects. If your integration needs the full UserDetailResource (with participations and profile_field_values), fetch detail per user:

JavaScript

async function pollUserChangesWithDetail(customerId) {
  const changedUsers = await pollUserChanges(customerId);

  for (const summary of changedUsers) {
    const detail = await getUserDetail(summary.id);
    await processUserFullDetail(customerId, detail);
  }
}

Cost: One additional request per changed user. For a poll cycle that detects 50 changes, that’s 51 requests instead of (roughly) 4 pages of 15.

When to fetch detail vs. when to skip

Workflow	Fetch detail?
Sync basic profile to external CRM	No — list shape is sufficient
Mirror participation history	Yes — detail’s `participations` array is the data
Display Form responses	Yes — detail’s `profile_field_values` is the data
Just track “was modified” without specific fields	No
Update external system with new email/phone	No — list shape has those

The list-shape vs. detail-shape decision matters for poll cost. Most integrations can use list shape for the change detection itself, fetching detail only for the subset of users where the additional fields matter.

Throttling and resource limits

Per-poll-cycle request cost on /users:

Pages required = ceil(changedUsers / 15)

A poll cycle that detects 150 changes pages 10 times. Multiplied across customers and resources, this is the bulk of the integration’s API traffic. A reference throttled polling worker:

JavaScript

const client = new ThrottledVomoClient({ token, requestsPerSecond: 3 });

async function pollUserChangesThrottled(customerId) {
  const lastSync = await getCheckpoint(customerId, 'user_sync');

  const params = new URLSearchParams({ updated_after: lastSync.toISOString() });
  let url = `https://api.vomo.org/v1/users?${params}`;
  let latestSeen = lastSync;

  while (url) {
    const response = await client.fetch(url);
    if (!response.ok) throw new Error(`Poll failed: ${response.status}`);

    const page = await response.json();
    for (const user of page.data) {
      await processUserChange(customerId, user);
      const u = new Date(user.updated_at);
      if (u > latestSeen) latestSeen = u;
    }

    url = page.links.next;
  }

  await setCheckpoint(customerId, 'user_sync', latestSeen);
}

A 3-req/sec rate is conservative; tune based on your overall integration’s budget across customers. See Rate Limits.

A reference user-change poller

A complete reference implementation incorporating the patterns above:

JavaScript

class UserChangePoller {
  constructor({ token, customerId, externalDb, checkpointStore }) {
    this.token = token;
    this.customerId = customerId;
    this.externalDb = externalDb;
    this.checkpoints = checkpointStore;
    this.client = new ThrottledVomoClient({ token, requestsPerSecond: 3 });
  }

  async poll() {
    const lastSync = await this.checkpoints.get(this.customerId, 'user_sync');

    const params = new URLSearchParams({
      updated_after: lastSync.toISOString(),
    });

    let url = `https://api.vomo.org/v1/users?${params}`;
    let latestSeen = lastSync;
    const failures = [];
    let processedCount = 0;

    while (url) {
      const response = await this.client.fetch(url);
      if (!response.ok) {
        throw new Error(`Poll failed: ${response.status}`);
      }

      const page = await response.json();

      for (const user of page.data) {
        try {
          await this._processUser(user);
          processedCount++;

          const u = new Date(user.updated_at);
          if (u > latestSeen) latestSeen = u;
        } catch (err) {
          failures.push({ user, error: err });
        }
      }

      url = page.links.next;
    }

    if (failures.length > 0) {
      await this._queueFailures(failures);
    }

    await this.checkpoints.set(this.customerId, 'user_sync', latestSeen);

    return {
      processedCount,
      failureCount: failures.length,
      newCheckpoint: latestSeen,
    };
  }

  async _processUser(user) {
    const previouslyKnown = await this.externalDb.userExists(this.customerId, user.id);

    if (!previouslyKnown) {
      await this._processNewUser(user);
      await this.externalDb.recordUserKnown(this.customerId, user.id);
    } else {
      await this._processUserUpdate(user);
    }
  }

  async _processNewUser(user) {
    // Customer-specific new-user logic
    await externalSystem.createUser({
      vomoId: user.id,
      firstName: user.first_name,
      lastName: user.last_name,
      email: user.email,
    });
  }

  async _processUserUpdate(user) {
    await externalSystem.updateUser({
      vomoId: user.id,
      firstName: user.first_name,
      lastName: user.last_name,
      email: user.email,
    });
  }

  async _queueFailures(failures) {
    for (const failure of failures) {
      await deadLetterQueue.publish({
        type: 'user_sync_failure',
        customerId: this.customerId,
        user: failure.user,
        error: failure.error.message,
      });
    }
  }
}

// Usage
const poller = new UserChangePoller({ token, customerId, externalDb, checkpointStore });
const result = await poller.poll();
console.log(`Processed ${result.processedCount} users (${result.failureCount} failed)`);

This handles the production-grade concerns: throttling, new-vs-update detection via persistent state, per-record failure isolation, dead-letter queueing, and correct checkpoint advancement.

Monitoring

Track these metrics per customer:

Metric	What it tells you
Processed-users per poll cycle	Sync activity rate; sudden spike or drop is worth investigating
Latest checkpoint timestamp	Confirms polling is actually running
Lag time (`now - latest_checkpoint`)	How fresh is the data? Sustained increase = polling issue
Dead-letter queue depth	Failures accumulating — needs investigation
Poll cycle duration	Sustained increase may indicate large batches or rate-limit slowdown
`4xx`/`5xx` error rates	Auth issues, rate limits, server problems

A simple “is polling healthy?” alert checks that now - latest_checkpoint < 2 * poll_interval. Beyond that, no recent activity means polling has stalled.

Production checklist

For a User-change polling worker:

Checkpoint persisted per-customer in durable storage
Checkpoint advanced to the latest updated_at actually seen (not wall-clock time)
Per-user failures isolated; don’t fail whole batch on one bad record
Failed records go to a dead-letter queue
Rate-limit-aware throttling in place
Distinct paths for new-user vs. updated-user processing (where business logic differs)
Deletion detection runs as a separate (slower) reconciliation
Participation-related workflows use a different polling strategy (Project Dates, full scans, etc.)
Per-customer monitoring dashboards exist
Alerts on stalled checkpoints and growing DLQ

Where to go next

Detecting Project Changes

The Project-specific polling pattern with schedule-change considerations.

Reconciliation Patterns

The slow-scan patterns for deletion detection and gap recovery.

Change Detection Best Practices

The cross-cutting patterns — checkpointing, idempotency, drift.

Users

The reference page for User fields and the upsert behavior.

Getting Started

Core Concepts

Workflows

Polling and Sync

Recipes

Best Practices

When to use this workflow

The baseline pattern

Distinguishing new from modified users

Why this works (and why it’s approximate)

The participation caveat

Why this matters

What to do instead

Option A: Poll `GET /users/{id}` for each user

Option B: Periodic full participation scan

Option C: Poll Project Dates instead

Combining `updated_after` with other filters

Poll only verified users

Poll only users with email matches

Detecting deletions

A subtle gotcha: “deletion” vs. “not accessible”

Reading user detail during the poll

When to fetch detail vs. when to skip

Throttling and resource limits

A reference user-change poller

Monitoring

Production checklist

Where to go next

Detecting Project Changes

Reconciliation Patterns

Change Detection Best Practices

Users

​When to use this workflow

​The baseline pattern

​Distinguishing new from modified users

​Why this works (and why it’s approximate)

​The participation caveat

​Why this matters

​What to do instead

​Option A: Poll GET /users/{id} for each user

​Option B: Periodic full participation scan

​Option C: Poll Project Dates instead

​Combining updated_after with other filters

​Poll only verified users

​Poll only users with email matches

​Detecting deletions

​A subtle gotcha: “deletion” vs. “not accessible”

​Reading user detail during the poll

​When to fetch detail vs. when to skip

​Throttling and resource limits

​A reference user-change poller

​Monitoring

​Production checklist

​Where to go next

Detecting Project Changes

Reconciliation Patterns

Change Detection Best Practices

Users

When to use this workflow

The baseline pattern

Distinguishing new from modified users

Why this works (and why it’s approximate)

The participation caveat

Why this matters

What to do instead

Option A: Poll `GET /users/{id}` for each user

Option B: Periodic full participation scan

Option C: Poll Project Dates instead

Combining `updated_after` with other filters

Poll only verified users

Poll only users with email matches

Detecting deletions

A subtle gotcha: “deletion” vs. “not accessible”

Reading user detail during the poll

When to fetch detail vs. when to skip

Throttling and resource limits

A reference user-change poller

Monitoring

Production checklist

Where to go next