API User

API-first synchronisation strategy for developer user data. This removes manual day-to-day CSV work: run one initial sync, then keep users updated automatically in the background.

Goal

  • One-time initial migration of existing users.
  • Optional ongoing sync for new users and profile changes.
  • Deterministic, idempotent, auditable sync process.

Where to run in Developer area

  1. Open Developer Portal and select your app.
  2. Navigate to Synchronisation.
  3. Use the Import Existing Users block for one-time bootstrap.

Direct entry point: Open Synchronisation import block.

Recommended architecture

  1. Initial bootstrap: send full user dataset once.
  2. Background sync: on every user create/update event in your platform, enqueue and push deltas.
  3. Safety reconcile: run daily/weekly full consistency check (optional but recommended).

Current API endpoint for import sync

POST /api/developer/applications/:appId/import-existing-users/csv

Despite the endpoint name, payload is JSON (users array). It is suitable for API-driven sync jobs.

Payload schema

{
  "sourceName": "Nightly Sync 2026-05-03",
  "users": [
    {
      "externalUserId": "legacy_1001",
      "email": "user.one@example.com",
      "name": "User One",
      "registrationDate": "2024-01-10T09:00:00Z",
      "lastLoginDate": "2026-05-03T07:22:00Z"
    }
  ]
}

Field reference

externalUserId   required  Unique user key from your platform
email            required  Match key to locate LoginSign account
name             optional  Additional validation against LoginSign profile
registrationDate optional  Backfills connection creation metadata
lastLoginDate    optional  Backfills last-session metadata

Idempotency and conflict behavior

  • If user is already connected: status becomes already_connected, connection is refreshed/reactivated if needed.
  • If user is new match: status becomes imported, new connection is created.
  • If no LoginSign account for email: not_found.
  • If name differs from LoginSign profile (when name provided): name_mismatch.
  • If required fields or formats are invalid: invalid_row.

Source tracking, monitoring, rollback

Every run is persisted as a source with counters and row-level results.

GET    /api/developer/applications/:appId/import-existing-users/sources
DELETE /api/developer/applications/:appId/import-existing-users/sources/:sourceId
  • Use GET .../sources to track imports and metrics.
  • Use DELETE .../sources/:sourceId to rollback imported connections from that source.

Automation pattern (smart default)

1) One-time full bootstrap
2) Event-driven delta sync from your backend (new user, email change, activity update)
3) Retry failed batches with exponential backoff
4) Daily reconcile to catch missed events

Operational recommendations

  • Process in batches (for example 500 to 2,000 users per request).
  • Store request/response logs per sync run for audit.
  • Alert on high rates of not_found, name_mismatch, or invalid_row.
  • Normalize emails to lowercase before sending.
  • Use ISO timestamps for date fields.

Related docs