Understanding how identifiers work in the Scan2Evolve API is crucial for successful integration.
The Scan2Evolve API uses external IDs to identify resources from your system. These IDs are provided by you and are used to create or update records in Scan2Evolve.
External IDs must be unique within your organization. They are used for upsert operations — if a record with the same external ID exists, it will be updated; otherwise, a new record will be created.
Use externalEmployeeId to identify employees in your system. This ID is required for all employee sync operations.
{
"externalEmployeeId": "EMP-001",
"status": "ACTIVE",
"firstName": "John",
"lastName": "Doe"
}Best practices:Use stable, unique identifiers that won't change over time. Avoid using email addresses or names as external IDs, as these can change.
Use externalAssetId to identify assets in your system. This ID is required for all asset sync operations.
{
"externalAssetId": "ASSET-001",
"code": "PUMP-001",
"name": "Main Water Pump",
"status": "ACTIVE"
}Note: The code field is optional and can be different fromexternalAssetId. The externalAssetId is used for upsert operations, whilecode is a human-readable identifier.
When assigning employees to sites, you can use either siteCode orexternalSiteId to reference the site.
{
"externalEmployeeId": "EMP-001",
"sites": [
{
"siteCode": "HQ-SITE"
},
{
"externalSiteId": "SITE-002"
}
]
}Note: Sites must exist in Scan2Evolve before you can assign employees to them. The site identifier (siteCode or externalSiteId) must match an existing site.