web sdk entity operations

The /entity endpoint

The /entity endpoint supports retrieving, updating, creating, deleting, and executing actions on entities.

GET /entity and POST /entity use the q= query parameter to describe which entities and what operations are involved. DELETE /entity/{id} deletes a single entity by GUID or logical ID passed as a path variable.

Supported operations

• Retrieving specific fields (e.g., Name, Description, BuildingCode)
• Updating field values (e.g., Name=Front Lobby, IsEnabled=true)
• Modifying multi-value fields (e.g., UnlockSchedules@{guid})
• Executing methods (e.g., SetBuzzerState(true))
• Creating new entities (e.g., NewEntity(Credential))
• Deleting entities using DELETE /entity/{guid})
• Combining multiple operations (create, read, update) across multiple entities in a single POST request

HTTP method usage

• Use GET to retrieve field values
• Use POST for property writes
• Use POST for collection mutations
• Use POST for entity creation
• When combining multiple operations in a single q= request, use POST if the request includes any property write, collection mutation, or entity creation
• Use DELETE to delete an entity
• The operations are encoded in the q= parameter (no JSON body)

Retrieving properties

Use these patterns when you want to read entity data without changing it.

Retrieve a specific entity by GUID or logical ID

GET /entity?q=entity={entityGuid},Name,Description

or using a logical identifier:

GET /entity?q=entity=LogicalId(Cardholder,1),Name

Note

GUIDs are universal. Logical IDs are user-assigned and may be unset, so do not assume every entity can be addressed by logical ID.

• Retrieves entities by GUID or LogicalId(...)
• The LogicalId syntax takes two parameters: the entity type and the logical number

Field projection syntax

A projection defines which fields to return in the response. You must specify them explicitly otherwise, no data will be returned.

GET /entity?q=entity={entityGuid},EntityType,ModifiedOn,CustomField1

• Fields must be listed explicitly after the entity=... portion
• Property names are case-insensitive. Custom field names are case-sensitive.
• If you omit projection fields, the request succeeds but returns no data

Multiple entities in single request

Multiple entity= segments must be combined under a single q= parameter. Each entity= entry must be followed by one or more fields to retrieve.

GET /entity?q=entity={guid1},Name,entity={guid2},Name,Description

GET /entity?q=entity=LogicalId(Cardholder,12),Name,MobilePhoneNumber

GET /entity?q=entity={guid1},Name,entity={guid2},Name

• Each entity= entry must specify at least one projected field
• Responses include one result per entity
• You must include at least one field to retrieve

Access custom fields

GET /entity?q=entity={guid},BuildingCode

• Custom fields must be referenced using their exact configured name
• Custom field names containing spaces or special characters are not supported in the q= syntax. The /customField/ endpoints support these names.

For comprehensive custom field documentation including creation, deletion, filtering, and data types, see Working with Custom Fields.

Update operations

Use POST when the request changes one or more properties on an existing entity.

Update fields (requires POST)

POST /entity?q=entity={guid},Name=New Name,Description=Updated description

• Updates must use the POST method
• All changes are encoded in the q= query string
• No request body is used

Modifying multi-value fields

Multi-value fields use special syntax because the same request can add, remove, clear, or read multiple values.

What are multi-value fields?

Multi-value fields are lists, collections, one-to-many relations, etc. They can contain any data type and represent fields that can hold multiple values rather than a single value.

Examples of multi-value fields:

• UnlockSchedules - list of schedule GUIDs
• Collections of strings, numbers, or other data types
• One-to-many entity relationships

Field behavior and limitations

• Not all multi-value fields support set operations - some only support add/remove
• Some multi-value fields are read-only - just as some single-value fields are read-only
• Read-only multi-value fields may provide specific methods for modifications

Example of method-based modification for read-only multi-value field:

POST /entity?q=entity={elevator},AddCamera({camera})
POST /entity?q=entity={elevator},RemoveCamera({camera})
GET /entity?q=entity={elevator},Cameras

Alternative syntax for multi-value operations

Some multi-value field operations support both symbolic syntax and method-based syntax:

Add operations:

POST /entity?q=entity={door},UnlockSchedules@{scheduleId}
POST /entity?q=entity={door},UnlockSchedules.Add({scheduleId})

Remove operations:

POST /entity?q=entity={door},UnlockSchedules-{scheduleId}
POST /entity?q=entity={door},UnlockSchedules.Remove({scheduleId})

Clear operations:

POST /entity?q=entity={door},UnlockSchedules*
POST /entity?q=entity={door},UnlockSchedules.Clear()

Important limitation: The symbolic syntax supports multiple values in one operation, but the method syntax does NOT support chaining:

Supported (symbolic syntax):

POST /entity?q=entity={door},UnlockSchedules@{scheduleId1}@{scheduleId2}@{scheduleId3}

NOT supported (method chaining):

POST /entity?q=entity={door},UnlockSchedules.Add({scheduleId1}).Add({scheduleId2})

Therefore:

• For single operations: Choose either syntax based on preference
• For multiple values: Must use symbolic syntax (@{id1}@{id2}@{id3})

Modify multi-value fields

Add:

POST /entity?q=entity={doorGuid},UnlockSchedules@{scheduleGuid}

Remove:

POST /entity?q=entity={doorGuid},UnlockSchedules-{scheduleGuid}

Clear All:

POST /entity?q=entity={doorGuid},UnlockSchedules*

Add Multiple:

POST /entity?q=entity={doorGuid},UnlockSchedules@{scheduleGuid1}@{scheduleGuid2}

Remove Multiple:

POST /entity?q=entity={doorGuid},UnlockSchedules-{scheduleGuid1}-{scheduleGuid2}

• Multiple values are separated by the '@' character for adding
• Multiple values are separated by the '-' character for removing
• The '*' character clears all values
• This syntax applies to any supported multi-value field

Method execution

Use method calls when the entity exposes behavior that is not expressed as a simple property write.

Execute a method on an entity

POST /entity?q=entity={doorGuid},SetBuzzerState(true)

• Method name is followed by arguments in parentheses
• Only entity-supported methods are allowed

Create operations

Creation requests start with NewEntity(...) and can initialize properties in the same query.

Create a new entity

POST /entity?q=entity=NewEntity(Cardholder),Name=John Smith,FirstName=John,LastName=Smith,Guid

• Use NewEntity(EntityType) to create a new entity
• Additional attributes can be initialized inline
• If no Name is specified, an auto-generated name will be assigned

Creatable entity types: AccessRule, Alarm, AnalogMonitor, AnalogMonitorGroup, Area, Asset, Camera, Cardholder, CardholderGroup, CashRegister, Credential, CustomEntity, Door, DoorTemplate, Elevator, HotlistRule, IntrusionUnit, LprUnit, Macro, Partition, ParkingRule, ParkingZone, Patroller, Permit, Role, Schedule, ScheduledTask, ThreatLevel, TileLayout, TilePlugin, TransferGroup, Unit, User, UserGroup, Visitor, Zone

Some types require additional parameters. See Special Entity Creation below.

Special entity creation

Creating an AccessRule:

POST /entity?q=entity=NewEntity(AccessRule),Name=My Access Rule,Guid
POST /entity?q=entity=NewEntity(AccessRule,Temporary),Name=Temporary Rule,Guid

• AccessRule supports an optional second parameter for AccessRuleType
• Accepted values: Permanent (default), Temporary

Creating a Role:

POST /entity?q=entity=NewEntity(Role),Name=My Archiver,Type=Archiver,Guid

• Role requires the Type property to be set in the same request
• See RoleType Enumeration for all accepted values

Creating a CustomEntity:

POST /entity?q=entity=NewEntity(CustomEntity,{descriptorGuid}),Name=My Custom Entity,Guid

• CustomEntity requires a descriptor GUID as the second parameter
• The descriptor GUID defines the custom entity type

Delete operations

Use the DELETE route when you want to remove a single entity by identifier.

Delete an entity

DELETE /entity/{guid}

• Deletes the entity identified by GUID or LogicalId(...)

To delete by logical ID, use the logical-ID expression as the path value:

DELETE /entity/LogicalId(Cardholder,42)

Note

Invalid identifiers return InvalidValue. Non-existent entities return UnableToRetrieveEntity.

Combined operations

You can combine multiple targets and operations in one POST request when you need a single transaction.

Mixed request: create, update, and retrieve multiple entities

POST /entity?q=entity=NewEntity(Cardholder),Name=Alice Smith,FirstName=Alice,LastName=Smith,Guid,entity=LogicalId(Credential,42),Name=My Credential,entity={entityGuid},Name,Description

• This request creates a cardholder, updates a credential, and retrieves fields from another entity
• You can combine creation, updates, and field projections for multiple entities, including different entity types in a single POST request
• It is valid to create one entity, update another, and retrieve fields from others, all in the same request

Important

One /entity?q=... request is all-or-nothing. If any operation in the request fails, the whole request fails and the earlier changes from that same request are rolled back. This also applies when the request switches targets with multiple entity= segments or creates a new entity and then initializes it.

Performance tip: For optimization guidance on batch and multi-entity requests, see Optimizing Web SDK performance.

Examples

Retrieve fields from a single entity:

GET /entity?q=entity={entityGuid},Name,Description

Retrieve fields from multiple entities:

GET /entity?q=entity={entityGuid1},Name,entity={entityGuid2},Name,ModifiedOn

Retrieve a custom field:

GET /entity?q=entity={entityGuid},BuildingCode

BuildingCode is the custom field name.

Update multiple fields:

POST /entity?q=entity={entityGuid},Name=South Door,Description=Exit near loading dock

Call a method:

POST /entity?q=entity={doorGuid},SetBuzzerState(true)

Create a cardholder:

POST /entity?q=entity=NewEntity(Cardholder),FirstName=John,LastName=Doe

Delete an entity:

DELETE /entity/{entityGuid}

Character escaping

Certain characters must be backslash-escaped when used in property values or method arguments to prevent interference with query parsing.

Characters requiring escaping

1. Commas (,)

Commas must always be backslashed in values:

POST /entity?q=entity={guid},Description=fun\,crazy\,cool\,wonderful
POST /entity?q=entity={guid},MethodName(param1,value with\, comma)

2. Collection Operators (@, -, *)

These characters must be backslashed when used in values:

POST /entity?q=entity={guid},Emails@user\@example.com@admin\@example.com
POST /entity?q=entity={guid},Description=Price is 10\@50% off

3. Parentheses ((, ))

Opening and closing parentheses must be backslashed in values:

POST /entity?q=entity={guid},Description=Check this smiley :\)
POST /entity?q=entity={guid},Note=Formula: \(a+b\)*c

URL encoding for special characters

Non-ASCII characters should be percent-encoded using their UTF-8 byte sequence:

POST /entity?q=entity={guid},Description=Temperature: 25%C2%B0C

• %C2%B0 represents the degree symbol (°)
• Use standard URL encoding for characters like +, &, #
• An unencoded # in a URL causes everything after it to be silently dropped. Always encode # as %23

Images and byte arrays

Binary data must be Base64-encoded:

POST /entity?q=entity={guid},Picture=iVBORw0KGgoAAAANSUhEUgAAAAUA...

Limitations

• Property names are case-insensitive, but custom field names are case-sensitive. Values preserve their original casing
• Custom field names with spaces or special characters are not supported
• The endpoint supports GET for reading field values and POST for applying updates
• Use GET when retrieving entity data only
• Use POST when modifying one or more fields or multi-value fields
• A single POST can include both queries and updates
• Multiple entity types may be included in the same request
• GET requests are limited by maximum URL length. If the request exceeds this limit, the server will return HTTP status code 414 URI Too Long

Response formats

Note

These examples assume Accept: text/json. If you request a different media type, the Web SDK can return a different response format such as XML.

Successful operations

Single Entity Query:

{
  "Rsp": {
    "Status": "Ok",
    "Result": {
      "Name": "cxvsdfg",
      "Description": "",
      "EntityType": "Door"
    }
  }
}

Multiple Entity Query:

{
  "Rsp": {
    "Status": "Ok",
    "Result": [
      { "Name": "Entity 1", "Description": "First entity" },
      { "Name": "Entity 2", "Description": "Second entity" }
    ]
  }
}

Entity Creation:

{
  "Rsp": {
    "Status": "Ok",
    "Result": {
      "Guid": "12345678-1234-1234-1234-123456789abc"
    }
  }
}

Update or Method Call (No Return Value):

{
  "Rsp": {
    "Status": "Ok"
  }
}

Error responses

Entity Not Found:

{
  "Rsp": {
    "Status": "Fail",
    "Result": {
      "SdkErrorCode": "UnableToRetrieveEntity",
      "Message": "Could not get the entity, does it exists? Guid: 12345678-1234-1234-1234-123456789999"
    }
  }
}

Invalid Operation:

{
  "Rsp": {
    "Status": "Fail",
    "Result": {
      "SdkErrorCode": "InvalidOperation",
      "Message": "Must supply entity query."
    }
  }
}

Transaction Failed:

{
  "Rsp": {
    "Status": "Fail",
    "Result": {
      "SdkErrorCode": "InvalidOperation",
      "Message": "Could not find property 'InvalidProperty' from filter: 'InvalidProperty=boom'"
    }
  }
}

Alternative entity endpoints

The ?q= syntax is the primary operational interface for entity management. It's the only way to create, update, execute methods, and modify multi-value fields.

These endpoints provide read-only convenience access:

GET /entity/{id}

• Returns ALL properties (base + type-specific) of a single entity
• Base properties: Name, Description, LogicalId, Guid, EntityType, CreatedOn, etc.
• Type-specific properties: FirstName, LastName (Cardholder), IsLocked (Door), etc.
• Supports both GUID and LogicalId format: LogicalId(EntityType,ID)
• Returns the full entity payload; if you only need a few fields, prefer GET /entity?q=entity={id},Field1,Field2 to reduce response size

GET /entity/basic/{id}

• Returns only basic properties (Name, Description, LogicalId, Guid, EntityType, CreatedOn, etc.)
• No type-specific properties included

GET /entity/exists/{id}

• Validates that an entity exists
• Returns: {"Rsp": {"Status": "Ok", "Result": {"Value": true}}}

See also

• Referencing entities: Entity discovery, search, and GUID formats
• Understanding Web SDK internals: Advanced query behavior and route limitations