web sdk entity operations - Genetec/DAP GitHub Wiki

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)

[!IMPORTANT] When using curl for POST requests, include the Content-Length: 0 header since there is no request body. Without this header, curl will fail with HTTP 411 "Length Required" error. Other HTTP clients handle this automatically.

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
Property names are case-insensitive. Custom field names are case-sensitive.
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 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

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*

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

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

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

Delete an entity

DELETE /entity/{guid}

Deletes the entity identified by GUID or LogicalID

[!NOTE] Invalid identifiers return InvalidValue. Non-existent entities return UnableToRetrieveEntity.

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={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 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={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
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": "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.

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