Web SDK Entity Operations

The /entity Endpoint

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

The request must use the q= query parameter to describe which entities and what actions are involved.

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 updating, creating and executing actions
• Use DELETE to delete an entity
• The operations are encoded in the q= parameter (no JSON body)

Retrieving properties

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

• 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
• Field names are case-insensitive, but values preserve casing
• You must specify at least one field to retrieve

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

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

Update Operations

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

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*

Clear and Add:

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

Add Multiple:

POST /entity?q=entity=201c7625-97b6-4ea6-a4d6-ff5cf279cdb4,UnlockSchedules@fdc60e2e-5c02-41fc-9ea2-5aa57f30cfb1@a8a69df6-2ba5-4434-bf7f-4a4d911d56b2

Remove Multiple:

POST /entity?q=entity=201c7625-97b6-4ea6-a4d6-ff5cf279cdb4,UnlockSchedules-fdc60e2e-5c02-41fc-9ea2-5aa57f30cfb1

Set single (when supported):

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

Set multiple (when supported):

POST /entity?q=entity=201c7625-97b6-4ea6-a4d6-ff5cf279cdb4,UnlockSchedules={guid1}@{guid2}@{guid3}

• Multiple values are separated by the '@' character for adding
• Multiple values are separated by the '-' character for removing
• The '*' character clears all values
• You can combine clear with add: *@{value} clears all then adds specified values
• The '=' character sets all values (when supported by the field)
• This syntax applies to any supported multi-value field

Method Execution

Execute a Method on an Entity

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

• Must use the POST method
• Method name is followed by arguments in parentheses
• Only entity-supported methods are allowed

Create Operations

Create a New Entity

POST /entity?q=entity=NewEntity(Credential),Name=Test Card,Guid

• Use NewEntity(EntityType) to create a new entity (see EntityType Enumeration for all available types)
• Additional attributes can be initialized inline
• Creatable entity types: Cardholder, Credential, CardholderGroup, Alarm, Schedule, Visitor, AccessRule, CustomEntity
• If no Name is specified, an auto-generated name will be assigned

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 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

Delete an Entity

DELETE /entity/{guid}

• Deletes the entity identified by GUID or LogicalID

Combined Operations

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=ba98dc20-dc61-48ec-b70f-71c987777401,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

Performance tip: For best practices on batch operations and optimizing multi-entity requests, see the Performance Guide.

Examples

Retrieve fields from a single entity:

GET /entity?q=entity=ba98dc20-dc61-48ec-b70f-71c987777401,Name,Description

Retrieve fields from multiple entities:

GET /entity?q=entity=ba98dc20-dc61-48ec-b70f-71c987777401,Name,entity=fcbbe59a-7036-4dc7-ae5a-2e4a23011e0c,Name,ModifiedOn

Retrieve a custom field:

GET /entity?q=entity=1c9ae058-d65e-44b6-8a03-8ae663e15963,BuildingCode

BuildingCode is the custom field name.

Update multiple fields:

POST /entity?q=entity=1c9ae058-d65e-44b6-8a03-8ae663e15963,Name=South Door,Description=Exit near loading dock

Call a method:

POST /entity?q=entity=cb7cd9c5-44ef-447e-b35e-bb2cd8cdee41,SetBuzzerState(true)

Create a cardholder:

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

Delete an entity:

DELETE /entity/63e17dc2-0c51-4667-b8e3-1894d652558f

Set multiple value field

POST /entity?q=entity=201c7625-97b6-4ea6-a4d6-ff5cf279cdb4,UnlockSchedules={guid1}@{guid2}@{guid3}

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-basic Latin characters or URL special characters should be replaced with their percent-encoded decimal Unicode value:

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

• %C2%B0 represents the degree symbol (°)
• Use standard URL encoding for characters like +, &, #

Images and Byte Arrays

Binary data must be Base64-encoded:

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

Limitations

• Field names are case-insensitive, but values preserve their original casing
• Custom field names with spaces or special characters are not supported
• You must specify at least one field to retrieve
• 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

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 exist? 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": "TransactionFailed",
      "Message": "Transaction Failed: Property 'InvalidProperty' not found on entity."
    }
  }
}

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.

The following 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)

GET /entity/basic/{id}

• Returns only base class 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
• Custom Fields - Working with custom entity properties
• Performance Guide - Optimization tips for entity operations
• Under the Hood - Technical architecture and reflection-based endpoints