Skip to main content
If your organisation uses Microsoft Entra ID (formerly Azure Active Directory), you can sync your people directly into a Master List. Changes in your directory — new starters, leavers, department changes, and profile photos — flow into CaptrID when you run a sync or on a schedule.
Directory sync requires a Pro or Business plan. Pro plans support 1 sync provider; Business plans support multiple.
Entra connections live under Directory Integrations alongside Airtable. If you keep your roster in Airtable instead, see Airtable Sync.

​
Before you start

You’ll need:

​
API permissions

Set these as Application permissions, not Delegated — and click Grant admin consent afterwards.This is the single most common setup problem, and both ways of getting it wrong fail quietly:
  • Delegated instead of Application — Entra offers Delegated first in the picker, and the names are identical. A delegated permission needs a signed-in user; CaptrID syncs as a background service, so there is no user to act for.
  • Application, but consent never granted — the connection authenticates successfully and reports zero users and zero groups. It looks like an empty directory rather than a permissions problem.
If Test Connection succeeds but finds nobody, it is almost always one of these two.
Grant all three on the app registration, then Grant admin consent for <your organisation>:
The first three are the configuration we test against and the one support will ask you to confirm.Directory.Read.All is optional and fails differently: without it the connection test still passes, but custom extension attributes your organisation defined never appear in the field-mapping list. See Extension attributes.
Ask your IT administrator to create the app registration and grant the required permissions. They’ll need to provide you with the Tenant ID, Clieon and grant the required permissions. They’ll need to provide you with the Tenant ID, Client ID, and Client Secret.

​
Creating the client secret

Copy the Value, not the Secret ID.Entra shows the two side by side and they look equally like credentials. The Secret ID is a GUID and is useless to CaptrID. The Value is roughly 40 characters and usually contains a ~.The Value is shown once, at the moment of creation, and is masked permanently afterwards. There is no way to retrieve it later — if you did not copy it, the only fix is to create a new secret.
In the app registration:
  1. Certificates & secrets → New client secret
  2. Description: something recognisable, e.g. CaptrID Sync
  3. Expiry: 24 months
  4. Add, then immediately copy the Value column
Note the expiry date somewhere. When a client secret expires the sync stops with an authentication error, and it is not obvious from the message that a rotated secret is all that is needed.

​
Step 1: Add a directory connection

  1. Go to Directory Integrations in the sidebar (under Data)
  2. Click Add Connection and choose Microsoft Entra ID as the provider
  3. Enter:
    • Connection Name — a label for your reference (e.g. “School Entra”)
    • Tenant ID — from your Entra app registration
    • Client ID — from your Entra app registration
    • Client Secret — the secret Value, not the Secret ID (see above)
  4. Click Test Connection to verify the credentials
    • Success shows the number of users and groups found in your directory
    • A success reporting 0 users and 0 groups is not a success — that is the permissions symptom described above, not an empty directory
    • AADSTS7000215 means the Secret ID was pasted instead of the Value
  5. Click Save
Add Directory Connection dialog with Microsoft Entra ID selected as the provider and fields for Connection Name, Tenant ID, Client ID, and Client Secret plus Test Connection and Save buttons

The Add Directory Connection dialog with a provider selector and fields for Tenant ID, Client ID, and Client Secret

Your credentials are stored securely and encrypted. You can test, edit, or remove connections at any time. Entra and Airtable connections appear together in the Your Connections list.
Directory Integrations screen with two connections — Microsoft Entra ID and Airtable — each showing a Connected badge

The Directory Integrations screen listing a Microsoft Entra ID connection and an Airtable connection, both showing Connected

​
Step 2: Configure sync on a Master List

You can configure directory sync when creating a new Master List or on an existing one:

​
During list creation

  1. Click Create Master List
  2. Choose Directory (Microsoft Entra ID) as your source
  3. Select your connection from the dropdown
  4. Continue through the wizard (group selection, field mapping)

​
On an existing list

  1. Open your Master List
  2. Go to the Sync tab
  3. Click Configure Sync
  4. Follow the wizard steps below

​
Step 3: Set the scope

Choose which people to sync from your tenant:
  • All users — sync everyone in your Entra tenant
  • Specific group — sync only members of one security group (e.g. “Teaching Staff”, “Year 7 Students”)
When you choose Specific group, search for the group — CaptrID shows the member count next to each so you can verify you’ve picked the right one.
Directory sync scope step showing All users versus Specific group options and a list of Entra groups with member counts

The Scope & Filters step with an All users / Specific group toggle and a searchable list of Entra security groups with member counts

Scoping to a group is recommended for most organisations. It keeps your Master List focused and syncs faster than pulling the entire directory.

​
Step 4: Map fields

This is where you tell CaptrID which directory fields should populate which Master List fields. The wizard helps you:
  • Suggests mappings for fields with matching names — accept them individually or Apply all
  • Groups source fields by category (Identity, Contact, Organisation, Account, On-Premises, Extension Attributes, Custom) with an Unmapped only filter to focus
  • Shows sample data from your directory so you can verify each mapping
  • Lets you create new Master List fields on the fly, or bulk Import all fields into your schema
  • Requires you to select a UID field — the directory field that uniquely identifies each person (a stable HR/SIS identifier like employeeId is the best choice)

​
Extension attributes

Schools and larger organisations often keep the field that actually matters — a student number, an employee ID, a house or campus code — in an extension attribute rather than a standard Entra field. CaptrID can map either kind, but they behave differently and it is worth knowing which you have. Both appear under Extension Attributes in the mapping wizard once they are visible, and both work as a UID.
extensionAttribute1–15 are the classic place a student or employee number lives in a school that syncs from on-premises Active Directory. If your standard fields have nothing stable to key on, look there before giving up and using mail.
Field mapping wizard with directory fields on the left mapped to Master List fields on the right, showing sample values

The field mapping wizard showing directory fields mapped to Master List fields with sample data preview

Choose your UID field carefully — it should be a stable, unique identifier like employeeId or mail. This field is used to match people on every subsequent sync. If someone’s UID changes in the directory, they’ll appear as a new person in CaptrID.

​
Step 5: Run the first sync

After saving your configuration:
  1. Go to the Sync tab on your Master List
  2. Click Sync Now to run the first backfill
  3. Wait for the sync to complete (typically under a minute for most organisations)
  4. Review the results: people created, updated, photos imported, and any errors

​
Keeping the list up to date

After the first sync, you can keep your Master List current in two ways:

​
Manual sync

Click Sync Now on the Sync tab whenever you want to pull the latest from Entra. Each run re-fetches the scoped users and reconciles all records — creating new people, updating changed data, and deactivating anyone who’s left the group or directory.

​
Scheduled sync

Turn on a schedule so CaptrID syncs automatically on an interval — no need to remember to click Sync Now. Set or change the interval from the Schedule section of the Sync card.
A schedule is the best way to keep large rosters accurate. Set it to match how often your directory changes — daily is plenty for most organisations.

​
Removing a connection

If you delete a directory connection that a Master List is still syncing from, CaptrID warns you first and names what depends on it. Deleting stops those lists syncing. The people already imported stay exactly where they are — removing the connection does not remove anyone from your roster.

​
Sync results

After each sync, the Sync tab shows:
Master List sync tab showing sync status, schedule, configuration with connection details, and a field mappings summary

The Sync tab showing sync status, schedule, connection configuration, and a field mappings summary

  • Sync Status — last sync result and a Sync Now button
  • Schedule — the automatic-sync interval, with Change to adjust it
  • Configuration — connection, scope, and filter, with Edit and Disconnect
  • Field Mappings — a summary of mapped fields, with Edit to reopen mapping

​
What happens to existing data

Directory sync never deletes people permanently — it deactivates them. You can still see deactivated people by switching the status filter to “Inactive”, and reactivate them if needed.

​
Fields that aren’t synced

  • Unmapped fields — directory fields you didn’t map are ignored
  • Local-only fields — fields you added manually to the Master List schema (not mapped to any directory field) are preserved and never overwritten by sync

​
Photos

Directory sync pulls each person’s profile photo from Entra when one is set, so headshots populate automatically alongside their data. Choose what happens when someone already has a photo:
A photo uploaded by hand is never overwritten by sync — not even on “Always”.This is deliberate. A manual upload exists to fill a gap the directory could not, and a scheduled sync quietly undoing that work would be the wrong outcome. If you want the directory to take that person back over, remove the manual photo and the next sync will supply one.It is worth knowing, because otherwise “Always” looks broken on exactly the people someone took the trouble to fix.
Photos approved in a capture session are pushed to the Master List separately — see Save to Master List.

​
Editing synced people

People synced from a directory have their directory-managed fields locked in the Master List. This prevents manual edits from being overwritten on the next sync. You can still:
  • Edit fields that aren’t mapped to the directory
  • View all field data
  • Use synced people in sessions (where edits are made on the session copy, not the master)
  • Push approved photos back from sessions via Save to Master List

​
Disconnecting

To stop syncing a Master List from the directory:
  1. Open the Master List → Sync tab
  2. Click Disconnect
  3. Confirm the action
What happens:
  • Sync stops — no further updates from the directory
  • All existing people remain in the Master List
  • Previously locked fields become editable
  • You can reconnect and re-enable syncing later

​
Troubleshooting