The Zluri SDK is a set of APIs that allows you to push data from custom applications to Zluri when no native connector is available. Use it for:

• Internal/proprietary applications
• Legacy systems without modern APIs
• Custom data sources that need aggregation
• Applications not in Zluri's connector catalog

This is a fundamental concept in the SDK:

Snapshot Data (State Data):

• Represents the current state of entities
• Like taking a photograph - shows how things are "right now"
• Examples: Current users list, current license assignments, current groups
• Each sync replaces the previous state
• Used for: Users, Applications, Licenses, Roles, Groups

Fact Data (Event Data):

• Represents events that happened over time
• Like recording a video - shows what happened and when
• Examples: Login events, purchase transactions, contract changes
• Each sync adds to the historical record
• Used for: User Activity, Transactions, Contracts

Think of it this way:

• Snapshot: "John is currently an active employee in Engineering."
• Fact: "John logged into Slack at 2:30 PM on Monday"

Here's how Zluri process Snapshot and Fact data:

• Snapshot Data: Zluri compares the new snapshot with the previous state to identify changes (new users, deactivated users, role changes, etc.)
• Fact Data: Zluri appends the new events to the historical timeline for analytics and compliance tracking

Yes, you can upload both types in the same sync session, but you must use the appropriate endpoint:

• Use /syncs/{syncId}/data/snapshots for snapshot entities
• Use /syncs/{syncId}/data/facts for fact entities

The upload will fail schema validation because fact and snapshot entities have different required fields and structures. Always use the correct endpoint for your data type.

No, the current SDK only supports one-directional data push from your systems to Zluri.

Here's the difference between SDK and Native integrations:

• Native Integrations: Zluri manages the connection and data sync automatically. Should be used when the native integration is available on Zluri
• SDK: You control when and what data to sync, giving you more flexibility but requiring more setup. Should be used for Apps which don’t have a native integration on Zluri. It is particularly helpful for any of your custom and on-premise applications.

No rate limits.

No sync frequency, the customer can seync the data multiple times in a day.

If a previous sync is running, and you deploy another sync, there can be any of these cases:

• If the data upload is in progress, Zluri doesn’t let you push/upload another concurrent sync.
• If the data upload is done and data processing is ongoing, Zluri will let you do another sync and the data processing will be queued to the previous sync.
• After finish sync is called in the initial sync, you can trigger another sync

Yes, but each instance must have a unique name within your organization. You cannot create multiple instances with the same name for the same application.

Use the Update Instance API endpoint:

PUT https://api-ext.zluri.com/v2/integrations-sync/instances/{instance_id}

With the new email list in the request body.

If you're syncing data for an application that doesn't exist in Zluri, you'll need to use an existing orgAppId or work with Zluri support to set up the corresponding application first.

Yes, you can:

• Disconnect: Stops future syncs but retains historical data
• Delete: Removes the instance and all associated data permanently
• How:
  • Custom Integrations>Identify the instance> More Options> Disconnect.
  • Once disconnected then you can delete the instance.

No, once a sync is marked as "finished," it cannot be restarted or modified. You must create a new sync to upload additional data. This is by design to maintain data integrity.

You'll need to:

1. Initialize a new sync
2. Upload the corrected data
3. Finish the new sync The system will process the latest data based on your new sync.

Yes, within a single sync you can upload data for multiple entities. For example:

1. Initialize sync once
2. Upload users (pages 1-5)
3. Upload applications (pages 1-3)
4. Upload user activities (pages 1-10)
5. Finish sync once

The maximum is 1000 records per page. If you have more data, split it into multiple pages.

Yes, you can re-upload a page with the same page number during an active sync. The system will overwrite the previous data for that page.

If you’re uploading data with same page number then the data will be overwritten.

Yes, you can re-upload a page with the same page number during an active sync. The system will overwrite the previous data for that page. If you’re uploading data with same page number then the data will be overwritten.

Sync can remain active as long as you want. Although, there are some consequences to long remaining active syncs:

• Zluri expects you to finish the syncs within a reasonable timeframe. We don’t cancel the syncs automatically.
• As there’s no automatic timeout or cancellation for the syncs, unfinished syncs block new syncs for the same instance. You’ll not be able to trigger another sync if the previous sync is unfinished.
• You'll receive a notification if a sync is active for more than 12 hours without any uploads. Reminder repetitions: 12 hours, 24 hours and 48 hours.

No, only one sync can be active at a time per instance. You must finish or cancel the current sync before starting a new one.

When schema validation fails:

1. The upload for that page is rejected
2. You receive detailed error messages showing:
   • Exact field paths (e.g., $.users[0].email)
   • The issue (e.g., "must be string", "must NOT have more than 200 characters")
3. No data from the failed page is stored
4. You can fix the issues and re-upload the same page

Example error response:

{
  "status": 422,
  "message": "Schema validation failed",
  "errors": [
    { "path": "$.users[0].email", "rawValue": null, "message": "must be string" },
    { "path": "$.users[0].isActive", "message": "must be boolean" }
  ]
}

Here's the difference between hard errors and soft errors.

• Hard Errors: Critical issues that prevent sync completion (e.g., missing user references, invalid cross-entity relationships). These must be fixed.
• Soft Errors: Warnings about suspicious but non-blocking issues (e.g., sudden drop in record count). You can force finish the sync despite these.

Cross-entity errors occur when:

• A user references a non-existent department
• An activity references a non-existent user
• Manager email doesn't exist in uploaded users

Solution: Ensure all referenced entities are included in your sync or exist from previous syncs.

Yes, when you receive soft errors (like data volume drops), you can use the forceFinish parameter in the finish sync API to proceed despite warnings.

Use the Get Sync Details API, which provides:

• raw_file_link: Your original uploaded data (for failed pages)
• schema_validation_error_link: Schema validation errors
• data_validation_error_link: Cross-entity validation errors

Rate limits are defined in these ways:

1. Sync Frequency: Next sync is allowed once the previous sync is completed, aka, when finish sync API is called for the previous sync.
2. API Calls: Standard rate limits apply for upload-data endpoints
3. Page Size: Maximum 1000 records per upload

You'll receive a 429 error with a Retry-At header indicating when you can retry:

{
  "errors": [
    {
      "msg": "You have exceeded the allowed number of requests. Please retry after the time specified in the 'retry-at' header"
    }
  ],
  "code": "RATE_LIMIT_EXCEEDED"
}

You can optimise large data uploads by following the below best practices:

1. Use concurrent page uploads (different page numbers)
2. Batch records efficiently (close to 1000 per page)
3. Implement retry logic with exponential backoff
4. Upload during off-peak hours if possible

Your data is stored in S3 with the following structure:

orgid/integrationid/year/month/date/instanceid/syncId/

Historical sync data is retained according to Zluri's data retention policies. Each new sync creates new data files rather than overwriting old ones.

Yes, you can choose which entities to sync. However, note:

• Some entities have dependencies (e.g., user activities need users)
• Groups, roles, and activities require users to be synced
• Users, applications, contracts, and transactions can be synced independently

The SDK always performs full syncs for each entity. Each sync represents the complete current state of your data. Zluri's processing engine handles the comparison with previous data.

Only ISO 8601 format is accepted for all date/time fields:

• Example: 2023-06-10T08:45:00Z
• Always include timezone (Z for UTC)

This means you have an active sync that hasn't been finished or cancelled. Solutions:

1. Check sync status using Get Sync Details API
2. Finish the current sync if data upload is complete
3. Cancel the sync using the DELETE endpoint if needed

Check sync status through:

1. Get Sync Details API - shows processing status
2. Email notifications (if configured)
3. Zluri dashboard sync logs
4. Final status will show "processing completed" when done

If a sync is stuck:

1. Check if you've called the finish sync API
2. Verify no validation errors are blocking processing
3. Contact support if sync shows "started" for over 6 hours
4. You can cancel and restart if needed

Follow this checklist:

1. Verify sync finished successfully
2. Check for validation errors in sync details
3. Ensure data processing completed (not just upload)
4. Verify you're looking at the correct time period in Zluri
5. Check if data meets Zluri's processing criteria

Follow this checklist:

1. Verify sync finished successfully
2. Check for validation errors in sync details
3. Ensure data processing completed (not just upload)
4. Verify you're looking at the correct time period in Zluri
5. Check if data meets Zluri's processing criteria

Contact Zluri support for sandbox access. Testing in production with small data sets is also acceptable.

The SLAs are mentioned below:

• Average sync processing: Within 2 hours after finish sync
• Large syncs: May take up to 4 hours
• You'll receive alerts if processing exceeds these times

You can monitor SDKs by:

1. Configure notification emails during instance creation
2. Use List Syncs API to check sync history
3. Monitor sync logs in Zluri dashboard (when available)
4. Set up automated monitoring using the Get Sync Details API

Always provide:

• Instance ID
• Sync ID (if applicable)
• Error messages and timestamps
• Sample data that's causing issues
• API responses with full error details

Yes, use the customFields object in applicable entities. Limitations:

• Maximum 100 custom properties
• Property names max 255 characters
• Values max 255 characters
• Supported types: string, number, boolean, null

Use the employeeType field with allowed values:

• employee
• external
• service
• group
• contractor

If applications are merged in Zluri after you've created SDK instances, the data will be consolidated according to Zluri's merge rules. Your instance continues to work with the original appId.

Yes, you can:

1. Include department information in your user data
2. Create separate instances for different subsidiaries if needed
3. Use custom fields to add additional organizational metadata

Yes, you can validate the data:

1. Use the Get Entity Schemas API to retrieve current schemas
2. Implement client-side validation using the schema
3. Test with small data sets first
4. Use JSON schema validators in your programming language