Skip to content
English
Contact Support
  • There are no suggestions because the search field is empty.

Sync Learners with API

Overview

This article explains techniques for keeping your Foundry learners in sync with your system of record using the API Integration. It’s intended for general technologists and developers, but anyone with basic API knowledge should be able to follow along.

This guide complements the Foundry API documentation, which provides detailed reference for each operation. Here, we focus on the overall integration flow and practical considerations.

If you do not have an LMS Integration where all learners are managed in the LMS, you’ll need to add learners as users in Foundry. This allows you to track progress, assign content, and send invitations or reminders.

The key questions are:

  • How do you add learners to Foundry with the right information?
  • How do you keep their profiles updated as changes occur in your system of record?

With the Foundry API, these tasks can be automated. For this article, we assume a one-way sync from your system of record to Foundry (e.g., name changes flow into Foundry, not the other way around).


Glossary

  • Foundry – Everfi’s digital learning platform.
  • HRIS – Human Resources Information System (or similar system of record).
  • Learner – A person who participates in Foundry learning activities. Every learner must be a Foundry user.
  • API – Foundry’s application programming interface for exchanging data with external systems.
  • Foundry User – A learner record in Foundry with attributes like name, email, SSO ID, optional IDs, and custom categories.
  • Integration Platform – The tool or application that connects your HRIS to Foundry’s API.


Scenarios

Your HRIS may support different sync strategies:

  • Delta Sync: Ideal if your HRIS can track changes since the last sync, reducing processing time.
  • Full Sync: If deltas aren’t practical, sync all users each time.

Storing the Foundry User ID in your HRIS simplifies matching. If that’s not possible, use another unique identifier like employee ID, student ID, or SSO ID.


API Capabilities

The Foundry API is a RESTful service supporting CRUD operations (Create, Read, Update, Deactivate).

  • Create/Update: One user per request.
  • Retrieve: Multiple users per request (paged).
  • Delete: Not supported; instead, deactivate users.

Authentication uses OAuth 2.0.


API Sync Techniques

There’s no single “right” way to design your integration. The API is flexible as long as you use the standard operations to retrieve, add, and update users. Below are two common approaches:


Simple User Sync Scenario

If your HRIS can identify adds, changes, and deletions and stores the Foundry User ID:

  • Add: POST new users; store the returned Foundry User ID.
  • Update: PATCH existing users by Foundry ID (send all fields, even unchanged ones).
  • Deactivate: PATCH the user and set active to false.

In this scenario, you don’t need to retrieve users from Foundry because your HRIS already tracks them.


Complex User Sync Scenario

If your HRIS cannot track deltas or store Foundry IDs:

  1. Retrieve all HRIS users who should exist in Foundry.
  2. Retrieve all Foundry users via paged GET requests (100 per page).
  3. Compare both lists using a matching key (SSO ID, employee ID, etc.).
  4. For each HRIS user:
    • If found in Foundry and data differs → PATCH update.
    • If not found → POST new user.
    • If inactive in HRIS → PATCH active=false.
  5. Optionally, handle Foundry users not in HRIS (e.g., deactivate or flag for review).


Example

HRIS User List vs. Foundry User List comparison shows:

  • Name changes → PATCH update.
  • Status changes (active/inactive) → PATCH update.
  • Missing users → POST new user.
  • Extra Foundry users → deactivate or review.

What Happens When You First Turn on the API?

If Foundry already has manually added users, the first sync will add many new users from your HRIS. Subsequent syncs will only add or update changes. To reduce the initial load, you can bulk upload users in Foundry first, then enable the API integration.


Additional Considerations

  • Sync Frequency: Most clients run daily syncs; adjust as needed.
  • Rate Limits: 200 requests per rolling 60 seconds. Use throttling and retry on 429 Too Many Requests.
  • Reactivations: Include inactive users in GET requests so they can be reactivated.
  • Separate Updates: Consider splitting core updates (name, email) from demographic updates (custom categories).
  • Assignments: Assignments are not made via API; use Foundry’s automated assignment rules.
  • Single User Retrieval: Supported but less efficient; may hit rate limits.

Summary

This guide provides a high-level approach to syncing users into Foundry via the API. For detailed API specifications, refer to the Foundry API documentation. Contact us if you need help designing your integration.