1. Partner API v2
  2. Resources
  3. Sync

Sync

Directory sync status for Microsoft 365 and Google Workspace.
7 endpointsScope readSyncStatusSyncInvite
GET/v2/clients/{client_id}/sync
RequiresreadscopeReturns SyncStatus

Which directory the client is connected to, when it last synced, and whether the last run failed.

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

curl "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/sync" \
  -H "X-API-Key: $INFIMA_API_KEY"
Response objectSyncStatus
client_idstring
configuredboolean
providerstringNullable
One ofmicrosoftgoogle
enabledboolean
last_run_atstring (date-time)Nullable

When the last successful sync finished. Null if no sync has succeeded yet; a failed run has no recorded time, so check last_run_status and last_error.

last_run_statusstringNullable
One ofsucceededfailed
last_errorstringNullable
groups_syncedinteger
users_syncedinteger
POST/v2/clients/{client_id}/sync/runs
Requireswritescope

Queues a directory sync outside the schedule, the dashboard's "Sync now": for example right after you add users in Microsoft Entra or Google Workspace. The run joins the throttled sync queue, and GET /clients/{client_id}/sync shows its result once it has finished. Limited to one per client per hour: 429 with Retry-After. A client without a connected directory, with sync turned off, or with a directory the API cannot run, returns 409.

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

curl -X POST "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/sync/runs" \
  -H "X-API-Key: $INFIMA_API_KEY"
Response objectObject
statusstring
One ofqueued
queued_atstring (date-time)
Errors409Sync is not configured for this client429Too many requestsError envelope →
GET/v2/clients/{client_id}/sync/invites
Requiresreadscope

The client's sync invite links, newest first, the dashboard's People › Directory sync › invites. Used, expired and revoked invites are listed too, so you can tell whether the client's IT has finished connecting: status is pending, used, expired or revoked. The list is short and always returned whole.

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

curl "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/sync/invites" \
  -H "X-API-Key: $INFIMA_API_KEY"
Response objectObject
dataarray of SyncInvite
Show item properties(8)
idstring
providerstring
One ofmicrosoftgoogle
urlstring (uri)

The link for the client's IT admin. Treat it like a password until it is used.

statusstring
One ofpendingusedexpiredrevoked
created_atstring (date-time)
expires_atstring (date-time)
used_atstring (date-time)Nullable
revoked_atstring (date-time)Nullable
POST/v2/clients/{client_id}/sync/invites
RequireswritescopeReturns SyncInvite

Creates a link the client's IT admin opens to connect Microsoft 365 or Google Workspace to INFIMA, the dashboard's "Invite IT to connect". Connecting needs the client's own admin consent, the one step of onboarding the API can't do for you; send them url. The link needs no INFIMA login, works once, and expires after 30 days (expires_at). Anyone holding it can connect a directory to this client, so send it only to the client's IT and revoke it if it goes astray. Once it is used, GET /clients/{client_id}/sync shows the connection; then choose groups and turn sync on.

Send an Idempotency-Key: a retried request replays the original 201 instead of creating a second link. A client can have at most 10 open (pending) links; an 11th returns 409 until one is used, expires or is revoked.

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

Request bodyapplication/json

providerstringRequired
One ofmicrosoftgoogle
curl -X POST "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/sync/invites" \
  -H "X-API-Key: $INFIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "microsoft"
  }'
Response objectSyncInvite
idstring
providerstring
One ofmicrosoftgoogle
urlstring (uri)

The link for the client's IT admin. Treat it like a password until it is used.

statusstring
One ofpendingusedexpiredrevoked
created_atstring (date-time)
expires_atstring (date-time)
used_atstring (date-time)Nullable
revoked_atstring (date-time)Nullable
Errors400Invalid request409The object already existsError envelope →
DELETE/v2/clients/{client_id}/sync/invites/{invite_id}
RequireswritescopeReturns SyncInvite

Stops an invite link from working, the dashboard's Revoke. Revoking a revoked or expired invite changes nothing and returns it. An invite already used returns 409: the directory is connected, and revoking the link would not undo that. An unknown id returns 404.

Returns 200: Revoked

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

invite_idstringRequired
curl -X DELETE "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/sync/invites/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10" \
  -H "X-API-Key: $INFIMA_API_KEY"
Response objectSyncInvite
idstring
providerstring
One ofmicrosoftgoogle
urlstring (uri)

The link for the client's IT admin. Treat it like a password until it is used.

statusstring
One ofpendingusedexpiredrevoked
created_atstring (date-time)
expires_atstring (date-time)
used_atstring (date-time)Nullable
revoked_atstring (date-time)Nullable
Errors404Not found within the key's access409The object already existsError envelope →
PUT/v2/clients/{client_id}/sync/groups
Requireswritescope

Replaces which of the connected directory's users the client gets, the dashboard's Save on People › Directory sync › Groups. Send one of:

  • groups: directory groups by id (Microsoft 365: the group's object id; Google Workspace: the group's email address). Each becomes a group of users in INFIMA, named name (the id when left out).
  • org_units: Google Workspace organizational units by path (/Sales), with or without the units below them.
  • an empty list ("groups": []): every user in the directory.

A body with neither groups nor org_units returns 400, so a misspelled field never switches the client to its whole directory.

Ids are not checked against the directory here. An id the directory does not know makes the next sync fail, and GET /clients/{client_id}/sync shows why. When sync is on, a sync is queued (sync_queued) unless one was already run for this client in the past hour; the schedule picks the change up otherwise. A client without a connected directory returns 409; org_units on a Microsoft 365 client returns 400.

Returns 200: Saved

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

Request bodyapplication/json

groupsarray of object

max 500 items

Show item properties(2)
idstringRequired
namestring
org_unitsarray of object

max 500 items

Show item properties(3)
pathstringRequired
namestring
include_sub_unitsboolean

Default true

curl -X PUT "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/sync/groups" \
  -H "X-API-Key: $INFIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "groups": [
      {
        "id": "0b6e7c1a-3f8e-4d2a-9c11-5a7e2b4d9f03",
        "name": "All Staff"
      }
    ],
    "org_units": [
      {
        "path": "/Sales",
        "name": "Sales",
        "include_sub_units": true
      }
    ]
  }'
Response objectObject
modestring
One ofall_usersgroupsorg_units
sync_queuedboolean
Errors400Invalid request409The object already existsError envelope →
POST/v2/clients/{client_id}/sync/enable
Requireswritescope

Turns the client's directory sync on, the dashboard's "Turn on". INFIMA first checks the connection the sync will use; if it fails, sync stays off and the 409 says why and how to fix it (for example, Google Workspace domain-wide delegation not set up). When it passes, sync is turned on, the last error is cleared, and a sync is queued unless one was already run for this client in the past hour (sync_queued says which; the schedule picks it up otherwise). Turning on a client whose sync is already on returns 200 with sync_queued: false.

There is no way to turn sync off through the API or the dashboard; contact INFIMA support. A client without a connected directory returns 409.

Returns 200: Sync is on

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

curl -X POST "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/sync/enable" \
  -H "X-API-Key: $INFIMA_API_KEY"
Response objectObject
statusstring
One ofenabled
sync_queuedboolean
Errors409The object already existsError envelope →