Entities in Security Center are the foundational components that represent physical devices, users, credentials, or abstract concepts like alarms and schedules. The Web SDK provides two primary methods to reference an entity: by its Entity GUID or its Logical ID.

The Entity GUID is a universally unique identifier assigned to every entity in Security Center. GUIDs are automatically generated by the system when the entity is created and are permanent; they cannot be changed or modified.

• Format: A GUID is a 128-bit value represented as a string. Example: 4eaf92b8-2f3c-4d9b-a6d5-3a5b6eebf6a4

• Usage: Use the GUID when you need to ensure absolute accuracy in referencing an entity, regardless of its type.

Example API Query Using GUID:

GET /entity/4eaf92b8-2f3c-4d9b-a6d5-3a5b6eebf6a4

This query retrieves the entity with the GUID 4eaf92b8-2f3c-4d9b-a6d5-3a5b6eebf6a4.

A Logical ID is an optional integer-based identifier that is unique within the scope of a specific entity type. Logical IDs provide a simpler alternative to GUIDs when working with entities of the same type. Unlike GUIDs, Logical IDs can be modified using the Config Tool application or the Web SDK, allowing administrators to assign more meaningful or structured IDs to entities.

• Format:

  LogicalID({entityType},{ID})
  

  • {entityType}: The type of the entity (e.g., Cardholder, Credential, Area).
  • {ID}: The integer-based identifier for that entity type.

Example API Query Using Logical ID:

GET /entity?q=entity=LogicalID(Cardholder,42),Name,FirstName,LastName

This query retrieves the cardholder with Logical ID 42, including the fields Name, FirstName, and LastName.

Practical workflow:

If you already know the entity GUID, the simplest way to discover its logical ID is to read it directly from the entity:

GET /entity?q=entity={entity-guid},Name,LogicalId

The /report/EntityConfiguration endpoint in the Web SDK retrieves entity GUIDs for specific entity types. GUIDs (Globally Unique Identifiers) uniquely and immutably identify entities in Security Center and are one common way to reference entities in API operations. Where entity references are supported, logical IDs can also be used with the LogicalID({entityType},{ID}) syntax.

Endpoint:

GET /report/EntityConfiguration?q=EntityTypes@Cardholder,Page=1,PageSize=2

Parameters:

• EntityTypes@Cardholder: Specifies the type of entities to retrieve (see EntityType Enumeration for all available types). You can specify multiple types with @, such as EntityTypes@Cardholder@Credential.
• Page=1 (optional): Specifies the page number to retrieve. Defaults to 1 if not specified.
• PageSize=2 (optional): Specifies the number of results to include per page. Defaults to 0 if not provided. A value of 0 returns all matching results without pagination.

• Page Size + 1 Rule: If additional pages exist, the response will include one extra result (PageSize + 1). The last result in the current page will also appear as the first result of the next page, ensuring continuity.
• Status field:
  • "TooManyResults": Indicates that more pages are available.
  • "Ok": Indicates that the current page is the last page.
• Last page: The response will contain up to PageSize results without an extra entry when no additional pages exist.

To retrieve GUIDs for Cardholder entities, querying the first page with a page size of 2:

GET /report/EntityConfiguration?q=EntityTypes@Cardholder,Page=1,PageSize=2

This request retrieves the first two GUIDs for entities of type Cardholder. If more results exist beyond the page size, the "TooManyResults" status will indicate this in the response.

{
    "Rsp": {
        "Status": "TooManyResults",
        "Result": [
            { "Guid": "11111111-1111-1111-1111-111111111111" },
            { "Guid": "22222222-2222-2222-2222-222222222222" },
            { "Guid": "33333333-3333-3333-3333-333333333333" }
        ]
    }
}

This response shows that the page size limit (2) was exceeded, and an additional result (33333333-3333-3333-3333-333333333333) is included. This extra result will appear as the first result on the next page.

GET /report/EntityConfiguration?q=EntityTypes@Cardholder,Page=2,PageSize=2

Response:

{
    "Rsp": {
        "Status": "TooManyResults",
        "Result": [
            { "Guid": "33333333-3333-3333-3333-333333333333" },
            { "Guid": "44444444-4444-4444-4444-444444444444" },
            { "Guid": "55555555-5555-5555-5555-555555555555" }
        ]
    }
}

This query retrieves the second page of results. The first result (33333333-3333-3333-3333-333333333333) matches the last extra result from the previous page, ensuring continuity.

{
    "Rsp": {
        "Status": "Ok",
        "Result": [
            { "Guid": "55555555-5555-5555-5555-555555555555" },
            { "Guid": "66666666-6666-6666-6666-666666666666" }
        ]
    }
}

This response shows that there are no additional pages. The status "Ok" indicates that this is the last page of results.

To retrieve all results, iterate through pages until the status changes from "TooManyResults" to "Ok".

Important notes:

• When Status is "TooManyResults", the last result is duplicated on the next page
• Remove the last result when processing pages (except the final page)
• Maximum recommended PageSize is 1000 for performance
• Default PageSize is 0 (all matching results) if not specified

Available in: Security Center 5.13.3 and later

By default, entity configuration queries return only entity GUIDs. You can use the ReturnFields parameter to include specific entity properties in the response.

Syntax:

GET /report/EntityConfiguration?q=EntityTypes@Cardholder,PageSize=3,ReturnFields@Name@FirstName@LastName

Parameters:

• ReturnFields@Property1@Property2@... - List of property names separated by @
• Works with both standard properties and custom fields
• Property names are case-insensitive

ReturnFields accepts direct property names and custom field names only. Nested paths such as Status.State are not supported.

Example request:

GET /report/EntityConfiguration?q=EntityTypes@Cardholder,PageSize=2,ReturnFields@Name@FirstName@LastName@EmailAddress

Response:

{
  "Rsp": {
    "Status": "Ok",
    "Result": [
      {
        "Guid": "11111111-1111-1111-1111-111111111111",
        "Name": "John Doe",
        "FirstName": "John",
        "LastName": "Doe",
        "EmailAddress": "[email protected]"
      },
      {
        "Guid": "22222222-2222-2222-2222-222222222222",
        "Name": "Jane Smith",
        "FirstName": "Jane",
        "LastName": "Smith",
        "EmailAddress": "[email protected]"
      }
    ]
  }
}

Retrieving custom fields:

You can include custom field values in the response by specifying the custom field name:

GET /report/EntityConfiguration?q=EntityTypes@Cardholder,PageSize=3,ReturnFields@Name@DepartmentCode@BadgeNumber

Response:

{
  "Rsp": {
    "Status": "Ok",
    "Result": [
      {
        "Guid": "11111111-1111-1111-1111-111111111111",
        "Name": "John Doe",
        "DepartmentCode": "IT",
        "BadgeNumber": 12345
      }
    ]
  }
}

Supported report types:

ReturnFields works with all configuration report types:

• EntityConfiguration - General entity queries
• CardholderConfiguration - Cardholder-specific queries
• CredentialConfiguration - Credential-specific queries
• UserReport - User-specific queries
• UserGroupReport - User group-specific queries
• AccessRuleConfiguration - Access rule-specific queries
• CustomEntityConfiguration - Custom entity queries
• And other entity-specific configuration report types

Example with CardholderConfiguration:

GET /report/CardholderConfiguration?q=FirstName=John,PageSize=3,ReturnFields@Name@EmailAddress@MobilePhoneNumber

Important notes:

• The Guid field is always included in the response automatically
• Do NOT explicitly request Guid in ReturnFields, it will cause an error
• Property names are case-insensitive
• Custom field names must match exactly (case-sensitive)
• If a requested property doesn't exist on an entity type, an error will be returned
• When querying multiple entity types, all requested properties must exist on ALL entity types in the results

Mixed entity type queries:

When using EntityConfiguration with multiple entity types, ensure all requested properties exist on all entity types:

This will fail:

GET /report/EntityConfiguration?q=EntityTypes@Cardholder@Camera,ReturnFields@Name@FirstName

The query above will fail because Camera entities don't have a FirstName property. Only request properties that are common to all entity types in the query:

This will succeed:

GET /report/EntityConfiguration?q=EntityTypes@Cardholder@Camera,ReturnFields@Name@Description

Both Cardholder and Camera entities have Name and Description properties, so this query will work correctly.

Use /report/EntityConfiguration when you need a general-purpose entity search.

Use a specialized query when you need filters that only make sense for a specific access-control entity type.

Two practical rules are worth remembering:

• The configuration queries use Page and PageSize.
• /report/Visitor uses MaximumResultCount instead of Page and PageSize.

The /report/EntityConfiguration endpoint supports advanced querying capabilities, allowing you to search for entities using various filters. When multiple filters are specified in a single query, they are combined using a logical AND, meaning all conditions must be met for an entity to match.

1. Name filter

   • Search for entities by their name using Name. The NameSearchMode parameter is optional and defaults to StartsWith if not specified.
   • The following search modes are available: StartsWith, Contains, EndsWith, Is, DoesNotStartWith, DoesNotEndWith, DoesNotContain, IsNot.
   • Example queries:

     GET /report/EntityConfiguration?q=EntityTypes@Cardholder,Name=John
     GET /report/EntityConfiguration?q=Name=John,NameSearchMode=Contains

   • The first query searches for Cardholder entities whose names start with "John" (default behavior). The second query searches across all entity types for names containing "John".

2. Description filter

   • Search for entities by their description using Description. The DescriptionSearchMode parameter is optional and defaults to StartsWith if not specified.
   • The following search modes are available: StartsWith, Contains, EndsWith, Is, DoesNotStartWith, DoesNotEndWith, DoesNotContain, IsNot.
   • Example queries:

     GET /report/EntityConfiguration?q=EntityTypes@Cardholder,Description=Access
     GET /report/EntityConfiguration?q=Description=Access,DescriptionSearchMode=EndsWith

   • The first query retrieves Cardholder entities with descriptions starting with "Access" (default behavior). The second query retrieves entities of any type with descriptions ending with "Access".

3. Custom fields filter

   • Search for entities using custom fields by providing the custom field GUID and the corresponding value. Multiple custom field values can be specified, separated by @. When multiple values are specified, all conditions must be met (logical AND).
   • Example queries:

     GET /report/EntityConfiguration?q=CustomFields@CustomField(12345678-1234-1234-1234-1234567890ab,Active)
     GET /report/EntityConfiguration?q=EntityTypes@Cardholder,CustomFields@CustomField(12345678-1234-1234-1234-1234567890ab,Active)@CustomField(87654321-4321-4321-4321-0987654321ab,Enabled)

   • The first query retrieves entities with the custom field 12345678-1234-1234-1234-1234567890ab set to "Active." The second query retrieves Cardholder entities where both custom field conditions are met (logical AND).

You can combine multiple filters in a single query to narrow down the results. All filters are combined using a logical AND, meaning an entity must satisfy every condition to be included in the results. For example:

GET /report/EntityConfiguration?q=EntityTypes@Cardholder,Name=John,NameSearchMode=StartsWith,Description=Manager,DescriptionSearchMode=Contains,CustomFields@CustomField(12345678-1234-1234-1234-1234567890ab,Active)@CustomField(87654321-4321-4321-4321-0987654321ab,Enabled)

This query retrieves Cardholder entities with the name John (starting with "John"), descriptions containing "Manager," and custom fields with the GUIDs 12345678-1234-1234-1234-1234567890ab set to Active and 87654321-4321-4321-4321-0987654321ab set to Enabled. By combining filters, you can create highly specific searches to target relevant entities.

The Web SDK uses different logical operators depending on the context:

Between different filter types (AND logic):

When you specify multiple different filters, they are combined with AND logic, all conditions must be met:

GET /report/EntityConfiguration?q=EntityTypes@Cardholder,Name=John,Description=Manager

This returns entities that are Cardholders AND have Name starting with "John" AND have Description starting with "Manager".

Within a single multi-value filter (OR logic):

When you specify multiple values for the same filter using @, they are combined with OR logic. Any condition can be met:

GET /report/EntityConfiguration?q=EntityTypes@Cardholder@Camera

This returns entities that are EITHER Cardholder OR Camera.

CustomFields is the exception. When you specify multiple @CustomField(...) values, they are combined with AND logic because each value adds another custom field condition that must be met.

Examples of OR logic within filters:

• EntityTypes - Multiple entity types:

  GET /report/EntityConfiguration?q=EntityTypes@Cardholder@Camera@Door

  Returns entities that are Cardholder OR Camera OR Door.

• CardholderGroupIds - Multiple cardholder groups:

  GET /report/CardholderConfiguration?q=CardholderGroupIds@{group1}@{group2}

  Returns cardholders who are members of group1 OR group2.

• AccessStatus - Multiple status values:

  GET /report/CardholderConfiguration?q=AccessStatus@Active@Expired

  Returns cardholders with status Active OR Expired.

• FormatType - Multiple credential formats:

  GET /report/CredentialConfiguration?q=FormatType@{format1}@{format2}

  Returns credentials with format1 OR format2.

Combining AND and OR logic:

You can combine both types of logic in a single query:

GET /report/EntityConfiguration?q=EntityTypes@Cardholder@Visitor,Name=John,CustomFields@CustomField(guid1,IT)

This returns entities that are:

• (Cardholder OR Visitor) AND
• Name starts with "John" AND
• CustomField with guid1 equals "IT"

This endpoint allows searching for cardholders with specific filters.

1. FirstName

GET /report/CardholderConfiguration?q=FirstName={value},FirstNameSearchMode={mode}

• Filters cardholders by first name.
• FirstNameSearchMode values:
  • StartsWith (default)
  • Contains
  • EndsWith
  • Is
  • DoesNotStartWith
  • DoesNotContain
  • DoesNotEndWith
  • IsNot

2. LastName

GET /report/CardholderConfiguration?q=LastName={value},LastNameSearchMode={mode}

• Filters by last name.
• LastNameSearchMode values:
  • StartsWith (default)
  • Contains
  • EndsWith
  • Is
  • DoesNotStartWith
  • DoesNotContain
  • DoesNotEndWith
  • IsNot

3. Email

GET /report/CardholderConfiguration?q=Email={value},EmailSearchMode={mode}

• Filters by email address.
• EmailSearchMode values:
  • StartsWith (default)
  • Contains
  • EndsWith
  • Is
  • DoesNotStartWith
  • DoesNotContain
  • DoesNotEndWith
  • IsNot

4. MobilePhoneNumber

GET /report/CardholderConfiguration?q=MobilePhoneNumber={value},MobilePhoneNumberSearchMode={mode}

• Filters by mobile phone number.
• MobilePhoneNumberSearchMode values:
  • StartsWith (default)
  • Contains
  • EndsWith
  • Is
  • DoesNotStartWith
  • DoesNotContain
  • DoesNotEndWith
  • IsNot

5. CardholderGroupIds

GET /report/CardholderConfiguration?q=CardholderGroupIds@{group1}@{group2}

• Filters by membership in specified cardholder groups.
• Accepts multiple GUIDs separated by @.
• Supports both GUIDs and logical IDs.

6. AccessStatus

GET /report/CardholderConfiguration?q=AccessStatus@Active

• Filters by access status.
• Accepted values:
  • Active
  • Inactive
  • Expired

7. FullName

GET /report/CardholderConfiguration?q=FullName={value},FullNameSearchMode={mode}

• Filters by combined first and last name.
• FullNameSearchMode values:
  • StartsWith (default)
  • Contains
  • EndsWith
  • Is
  • DoesNotStartWith
  • DoesNotContain
  • DoesNotEndWith
  • IsNot

8. ActivationTimeRange

GET /report/CardholderConfiguration?q=ActivationTimeRange.SetTimeRange({iso8601Start},{iso8601End})

• Filters by activation date.
• Both start and end must be specified in ISO 8601 format.
• Example:

GET /report/CardholderConfiguration?q=ActivationTimeRange.SetTimeRange(2023-01-01T00:00:00Z,2023-12-31T23:59:59Z)

9. ExpirationTimeRange

GET /report/CardholderConfiguration?q=ExpirationTimeRange.SetTimeRange({iso8601Start},{iso8601End})

• Filters by expiration date.
• Both start and end must be specified in ISO 8601 format.
• Example:

GET /report/CardholderConfiguration?q=ExpirationTimeRange.SetTimeRange(2025-01-01T00:00:00Z,2025-06-30T23:59:59Z)

10. VisitorsOnly

GET /report/CardholderConfiguration?q=VisitorsOnly=true

• If true, returns visitors only.
• If false, returns cardholders only.
• If omitted, returns cardholders only.

11. FirstNameOrder / LastNameOrder

GET /report/CardholderConfiguration?q=FirstNameOrder=Ascending,LastNameOrder=Descending

• Sorts results by name.
• Accepted values:
  • Ascending
  • Descending

Find cardholders by email address:

GET /report/CardholderConfiguration?q=Email={email},EmailSearchMode=Is,PageSize=10,ReturnFields@Name@EmailAddress

Find cardholders in one or more cardholder groups:

GET /report/CardholderConfiguration?q=CardholderGroupIds@{group-guid-1}@{group-guid-2},PageSize=10,ReturnFields@Name

Find visitors through the cardholder configuration query:

GET /report/CardholderConfiguration?q=VisitorsOnly=true,PageSize=10,ReturnFields@Name@FirstName@LastName

Use CardholderConfiguration with VisitorsOnly=true when you want visitor entities as people records. Use /report/Visitor when you need active or archived visitor lifecycle records.

This endpoint allows searching for credentials with specific filters.

1. FormatType

GET /report/CredentialConfiguration?q=FormatType@{guid1}@{guid2}

• Filters credentials by credential format type.
• Accepts one or more GUIDs separated by @.

2. UnassignedOnly

GET /report/CredentialConfiguration?q=UnassignedOnly=true

• If true, only returns credentials not assigned to any cardholder.
• If false or omitted, all credentials are included.

3. UniqueIds

GET /report/CredentialConfiguration?q=UniqueIds@CredentialFormat(...)

Filters credentials by formatted or encoded identifier. Use this to search for credentials by card number, facility code, or other credential identifiers.

Accepted formats:

• WiegandStandardCredentialFormat({facility},{cardId}) - Standard 26-bit Wiegand

  GET /report/CredentialConfiguration?q=UniqueIds@WiegandStandardCredentialFormat(100,12345)

  Searches for credential with facility code 100 and card number 12345.

• WiegandH10306CredentialFormat({facility},{cardId}) - HID H10306 format

  GET /report/CredentialConfiguration?q=UniqueIds@WiegandH10306CredentialFormat(255,65535)

• WiegandCorporate1000CredentialFormat({companyId},{cardId}) - Corporate 1000 35-bit

  GET /report/CredentialConfiguration?q=UniqueIds@WiegandCorporate1000CredentialFormat(4095,524287)

• WiegandH10302CredentialFormat({cardId}) - HID H10302 (card number only)

  GET /report/CredentialConfiguration?q=UniqueIds@WiegandH10302CredentialFormat(12345)

• WiegandH10304CredentialFormat({facility},{cardId}) - HID H10304 37-bit

• Wiegand48BitCorporate1000CredentialFormat({companyId},{cardId}) - 48-bit Corporate 1000

• WiegandCsn32CredentialFormat({cardId}) - 32-bit CSN

• LicensePlateCredentialFormat({plate}) - License plate number

  GET /report/CredentialConfiguration?q=UniqueIds@LicensePlateCredentialFormat(ABC123)

• KeypadCredentialFormat({credentialCode}) - PIN/keypad code

  GET /report/CredentialConfiguration?q=UniqueIds@KeypadCredentialFormat(1234)

Important notes:

• Values are decimal numbers, not hexadecimal
• All parameters must be specified for the format
• Use ReturnFields to get additional credential details in the response

4. MobileCredentialOnly

GET /report/CredentialConfiguration?q=MobileCredentialOnly=true

• If true, only mobile credentials are returned.
• If false, excludes mobile credentials.
• If omitted, all types are included.

Find credentials by a standard 26-bit card number:

GET /report/CredentialConfiguration?q=UniqueIds@WiegandStandardCredentialFormat({facility},{card-id}),PageSize=10,ReturnFields@Name

Find credentials by PIN:

GET /report/CredentialConfiguration?q=UniqueIds@KeypadCredentialFormat({pin}),PageSize=10,ReturnFields@Name

Find unassigned credentials:

GET /report/CredentialConfiguration?q=UnassignedOnly=true,PageSize=10,ReturnFields@Name

This endpoint allows searching for access rules with specific filters.

1. Name

GET /report/AccessRuleConfiguration?q=Name={value},NameSearchMode={mode}

• Filters access rules by name.
• NameSearchMode values:
  • StartsWith (default)
  • Contains
  • EndsWith
  • Is
  • DoesNotStartWith
  • DoesNotContain
  • DoesNotEndWith
  • IsNot

AccessRuleConfiguration keeps the common entity filters such as Name, Description, and ReturnFields, and also adds access-rule-specific filters.

2. AccessRuleType

GET /report/AccessRuleConfiguration?q=AccessRuleType={value}

• Filters access rules by type.
• Accepted values:
  • Permanent
  • Temporary

Find an access rule by its exact name:

GET /report/AccessRuleConfiguration?q=Name={rule-name},NameSearchMode=Is,ReturnFields@Name@AccessRuleType

Find all temporary access rules:

GET /report/AccessRuleConfiguration?q=AccessRuleType=Temporary,PageSize=10,ReturnFields@Name

This endpoint allows listing and searching custom entities.

Use it when you need the entities created from custom entity types, not the custom entity type descriptors themselves. Type descriptors are covered in Managing custom entity types.

1. CustomEntityTypes

GET /report/CustomEntityConfiguration?q=CustomEntityTypes@{custom-entity-type-guid},Page=1,PageSize=10

• Filters the results to one or more custom entity types.
• Accepts one or more custom entity type GUIDs separated by @.

2. Owner

GET /report/CustomEntityConfiguration?q=Owner={owner-guid},Page=1,PageSize=10

• Filters by the owner GUID of the custom entity.
• Use this when ownership matters in your custom-entity deployment.

CustomEntityConfiguration also supports the same paging and projection patterns as the other configuration queries:

• Page
• PageSize
• ReturnFields

List custom entities:

GET /report/CustomEntityConfiguration?q=Page=1,PageSize=10

List custom entities with projected fields:

GET /report/CustomEntityConfiguration?q=Page=1,PageSize=10,ReturnFields@Name@Description

List custom entities of a specific custom entity type:

GET /report/CustomEntityConfiguration?q=CustomEntityTypes@{custom-entity-type-guid},Page=1,PageSize=10,ReturnFields@Name@Description

This endpoint allows searching for visitor lifecycle records.

Unlike the configuration queries, /report/Visitor uses MaximumResultCount instead of Page and PageSize.

By default, the visitor report returns full visitor records. For active-visitor queries, ReturnFields can be used to project a smaller set of fields when that is more convenient.

1. VisitorStates

GET /report/Visitor?q=VisitorStates@Active

• Filters visitor records by state.
• Accepted values:
  • Active
  • Archived

2. FirstName

GET /report/Visitor?q=VisitorStates@Archived,FirstName={value},FirstNameSearchMode={mode}

• Filters by first name.
• FirstNameSearchMode values:
  • StartsWith (default)
  • Contains
  • EndsWith
  • Is
  • DoesNotStartWith
  • DoesNotContain
  • DoesNotEndWith
  • IsNot

3. LastName

GET /report/Visitor?q=VisitorStates@Archived,LastName={value},LastNameSearchMode={mode}

• Filters by last name.
• LastNameSearchMode uses the same values as FirstNameSearchMode.

4. FullName

GET /report/Visitor?q=VisitorStates@Archived,FullName={value},FullNameSearchMode={mode}

• Filters by combined first and last name.
• FullNameSearchMode uses the same values as FirstNameSearchMode.

5. Email

GET /report/Visitor?q=VisitorStates@Archived,Email={value},EmailSearchMode={mode}

• Filters by email address.
• EmailSearchMode uses the same values as FirstNameSearchMode.

6. MobilePhoneNumber

GET /report/Visitor?q=VisitorStates@Archived,MobilePhoneNumber={value},MobilePhoneNumberSearchMode={mode}

• Filters by mobile phone number.
• MobilePhoneNumberSearchMode uses the same values as FirstNameSearchMode.

7. EntityGuids

GET /report/Visitor?q=EntityGuids@{visitor-guid}

• Filters by one or more specific visitor GUIDs.

8. ActivationTimeRange

GET /report/Visitor?q=ActivationTimeRange.SetTimeRange({iso8601Start},{iso8601End})

• Filters by activation date and time.

9. ArrivalTimeRange

GET /report/Visitor?q=ArrivalTimeRange.SetTimeRange({iso8601Start},{iso8601End})

• Filters by visitor arrival time.

10. DepartureTimeRange

GET /report/Visitor?q=DepartureTimeRange.SetTimeRange({iso8601Start},{iso8601End})

• Filters by visitor departure time.

11. ExpirationTimeRange

GET /report/Visitor?q=ExpirationTimeRange.SetTimeRange({iso8601Start},{iso8601End})

• Filters by expiration date and time.

12. MaximumResultCount

GET /report/Visitor?q=VisitorStates@Archived,MaximumResultCount=25

• Limits the number of visitor report rows returned.

13. LastConfiguration

GET /report/Visitor?q=VisitorStates@Archived,FullName={value},FullNameSearchMode=Is,LastConfiguration=true

• When true, returns only the last checkout record for a visitor.
• When false, returns all matching visitor records.

Find active visitors:

GET /report/Visitor?q=VisitorStates@Active

Find archived visitors by full name:

GET /report/Visitor?q=VisitorStates@Archived,FullName={full-name},FullNameSearchMode=Is

Find a specific visitor record by GUID:

GET /report/Visitor?q=EntityGuids@{visitor-guid}

Find visitor records in an arrival time range:

GET /report/Visitor?q=ArrivalTimeRange.SetTimeRange({iso8601Start},{iso8601End}),MaximumResultCount=25

Project only the first name from active visitor records:

GET /report/Visitor?q=VisitorStates@Active,ReturnFields@FirstName

This endpoint allows searching for users with specific filters.

Endpoint:

GET /report/UserReport?q={filters}

1. FirstName

GET /report/UserReport?q=FirstName={value},FirstNameSearchMode={mode}

• Filters users by first name.
• FirstNameSearchMode values:
  • StartsWith (default)
  • Contains
  • EndsWith
  • Is
  • DoesNotStartWith
  • DoesNotContain
  • DoesNotEndWith
  • IsNot

2. LastName

GET /report/UserReport?q=LastName={value},LastNameSearchMode={mode}

• Filters users by last name.
• LastNameSearchMode values:
  • StartsWith (default)
  • Contains
  • EndsWith
  • Is
  • DoesNotStartWith
  • DoesNotContain
  • DoesNotEndWith
  • IsNot

3. Email

GET /report/UserReport?q=Email={value},EmailSearchMode={mode}

• Filters users by email address.
• EmailSearchMode values:
  • StartsWith (default)
  • Contains
  • EndsWith
  • Is
  • DoesNotStartWith
  • DoesNotContain
  • DoesNotEndWith
  • IsNot

4. UserGroupIds

GET /report/UserReport?q=UserGroupIds@{group1}@{group2}

• Filters by assigned user group(s).
• Accepts multiple GUIDs separated by @.

5. Status

GET /report/UserReport?q=Status@Activated@Deactivated

• Filters users by status.
• Accepted values:
  • Activated: User account is enabled.
  • Deactivated: User account is disabled.

6. GroupRecursive

GET /report/UserReport?q=GroupRecursive=true

• If true, includes users from subgroups recursively.

7. FirstNameOrder / LastNameOrder

GET /report/UserReport?q=FirstNameOrder=Ascending,LastNameOrder=Descending

• Sorts users by name.
• Accepted values:
  • Ascending
  • Descending

8. SecurityLevelLowerBound / UpperBound

GET /report/UserReport?q=SecurityLevelLowerBound=3,SecurityLevelLowerBoundOperator=Greaterequal,SecurityLevelUpperBound=5,SecurityLevelUpperBoundOperator=Lower

• Filters users by security level range.
• SecurityLevelLowerBoundOperator and SecurityLevelUpperBoundOperator accepted values:
  • Equal
  • Lowerequal (less than or equal)
  • Greaterequal (greater than or equal)
  • Lower (less than)
  • Greater (greater than)
  • Different (not equal)
• Values must be integer-based levels.

This endpoint allows searching for user groups with specific filters.

Endpoint:

GET /report/UserGroupReport?q={filters}

1. Status

GET /report/UserGroupReport?q=Status@Activated@Deactivated

• Filters user groups based on their current status.
• Accepted values:
  • Activated: The group is enabled and available for use.
  • Deactivated: The group is inactive and not assignable.

2. UserGroupIds

GET /report/UserGroupReport?q=UserGroupIds@{group1}@{group2}

• Filters by group GUIDs.
• Accepts multiple IDs separated by @.

3. Email

GET /report/UserGroupReport?q=Email={value},EmailSearchMode={mode}

• Filters groups by associated email.
• EmailSearchMode values:
  • StartsWith (default)
  • Contains
  • EndsWith
  • Is
  • DoesNotStartWith
  • DoesNotContain
  • DoesNotEndWith
  • IsNot

4. GroupRecursive

GET /report/UserGroupReport?q=GroupRecursive=true

• If true, includes members of nested subgroups.

5. SecurityLevelLowerBound / UpperBound

GET /report/UserGroupReport?q=SecurityLevelLowerBound=2,SecurityLevelLowerBoundOperator=Greaterequal,SecurityLevelUpperBound=4,SecurityLevelUpperBoundOperator=Lower

• Filters by minimum and maximum security level.
• SecurityLevelLowerBoundOperator and SecurityLevelUpperBoundOperator accepted values:
  • Equal
  • Lowerequal (less than or equal)
  • Greaterequal (greater than or equal)
  • Lower (less than)
  • Greater (greater than)
  • Different (not equal)
• All values must be integers.

When providing parameter values, use the Property=Value format. Below are the supported types and their proper formats:

• Format: A standard string of text.
• Example: Name=JohnDoe

• Format: Standard GUID with flexible formatting
• Accepted formats:
  • With hyphens: 12345678-1234-1234-1234-123456789abc
  • With braces: {12345678-1234-1234-1234-123456789abc}
  • Without hyphens: 123456781234123412341234567890ab
• Example: EntityId=12345678-1234-1234-1234-123456789abc

• Format: LogicalId(EntityType,ID)
• Example: EntityId=LogicalId(Area,1)

• Format: ISO 8601 format or server regional format
• Supported formats:
  • yyyy-MM-ddTHH:mm:ss (ISO 8601, time portion required)
  • yyyy-MM-ddTHH:mm:ss.fff (with milliseconds)
  • yyyy-MM-ddTHH:mm:ss±hh:mm (with time zone offset)
  • yyyy-MM-ddTHH:mm:ssZ (UTC with Z suffix)
  • Server regional formats (e.g., MM/dd/yyyy HH:mm:ss)
• Important: Time-only values (e.g., 10:30:00) are rejected to prevent TimeSpan confusion
• Time Zone Handling:
  • DateTime values with explicit timezone (Z or ±hh:mm) are converted to UTC
  • DateTime values without timezone are treated as UTC
  • All stored DateTime values are in UTC
• Best Practice: Always use ISO 8601 format with explicit UTC (Z suffix) for consistency
• Examples:
  • 2023-01-15T12:00:00Z (recommended, explicit UTC)
  • 2023-01-15T12:00:00 (treated as UTC)
  • 2023-01-15T12:00:00+01:00 (Paris time, converted to UTC: 11:00)
  • 2023-01-15T12:00:00-05:00 (New York time, converted to UTC: 17:00)

• Format: hh:mm:ss or d.hh:mm:ss (days.hours:minutes:seconds)
• Examples:
  • 00:05:00 (5 minutes)
  • 02:30:00 (2 hours 30 minutes)
  • 1.00:00:00 (1 day)
  • 1.12:30:45 (1 day, 12 hours, 30 minutes, 45 seconds)

• Format: A;R;G;B, where:
  • A: Alpha (transparency)
  • R: Red
  • G: Green
  • B: Blue
• Example: Color=255;128;0;0 (opaque red)

• Format: Standard IPv4 or IPv6 address.
• Example: IPAddress=192.168.1.1

• Format: A MAC address as a hexadecimal string.
• Example: MACAddress=00-14-22-01-23-45

• Format: true or false (case-insensitive)
• Accepted values: true, True, TRUE, false, False, FALSE
• Example: IsActive=true
• Note: Numeric values (1, 0) or text values (yes, no) are NOT accepted

• Format: A Base64-encoded string.
• Example: Image=SGVsbG8sIHdvcmxkIQ==

• Format: An XML string.
• Example: Configuration=<Root><Element>Value</Element></Root>

• Format: {Item1,Item2,Item3}
• Examples:
  • String list: Tags={security,main,entrance}
  • Integer list: Ports={80,443,8080}
  • GUID list: Entities={guid1,guid2,guid3}
  • Empty list: Items={}

• Format: {{Key1,Value1},{Key2,Value2}}
• Examples:
  • String dictionary: Metadata={{name,John},{city,Montreal}}
  • Integer dictionary: Counters={{key1,100},{key2,200}}
  • Empty dictionary: Data={}

• Format: Use the serialized timezone value expected by Security Center.
• Do not use standard timezone identifiers such as America/New_York.
• If you need to send a TimeZoneInfo value, copy the exact timezone value from a Security Center source instead of typing an identifier by hand.

• Format: Base64-encoded image data.
• Example: ProfileImage=iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB...

• Entity Operations - Creating, reading, updating entities
• Reports - Activity reports and entity configuration queries
• Custom Fields - Working with custom entity properties
• Under the Hood - Technical architecture and query reflection