web sdk access control

About access control in the Web SDK

Access control in Security Center answers a simple question: can this person access this place at this time?

In Web SDK terms, that question is built from a small set of entities:

• Cardholder and Visitor represent the people.
• Credential is how the person is identified.
• CardholderGroup lets you manage multiple people together.
• Schedule defines when access applies.
• Door, DoorSide, Elevator, Floor, and Area represent where access applies.
• AccessRule ties those pieces together.

One concept is especially important: access is granted or denied to people, not to credentials. A credential is only the way the system identifies the person who is requesting access.

Model

Core model

The access-control model can be summarized like this:

Question	Main entities	Meaning
Who?	Cardholder, Visitor, CardholderGroup	The person or group of people requesting access
How is the person identified?	Credential	The card, PIN, mobile credential, or other format presented to the system
Where?	Door, DoorSide, Elevator, Floor, Area	The place where access is requested
When?	Schedule	The time window when access is allowed or denied
What decides the result?	AccessRule	The configuration that combines people, places, and schedules

Entity relationships

The relationships between the main access-control entities look like this:

classDiagram
    class Cardholder
    class Visitor
    class Credential
    class CardholderGroup
    class AccessRule
    class Schedule
    class Door
    class DoorSide
    class Elevator
    class Floor
    class Area

    Visitor --|> Cardholder
    Cardholder "1" --> "0..*" Credential : identified by
    CardholderGroup "1" --> "0..*" Cardholder : contains
    AccessRule --> Schedule : uses
    AccessRule --> Cardholder : applies to
    AccessRule --> CardholderGroup : applies to
    AccessRule --> Door : applies to
    AccessRule --> Elevator : applies to
    AccessRule --> Area : applies to
    Door "1" --> "2" DoorSide : has
    Elevator "1" --> "0..*" Floor : serves
    Area --> Door : groups
    Area --> Elevator : groups

Loading

This diagram is conceptual. It shows how the main access-control entities relate to each other in Web SDK workflows.

Cardholders and visitors

Cardholder is the standard person profile used for ongoing access.

Visitor represents a person who is managed with the same access-control model, but typically for short-term access. Visitors usually have a shorter lifecycle and are often checked in and checked out explicitly.

In practical terms:

• Cardholders and visitors are the people to whom access is granted or denied.
• Visitors have a shorter lifecycle and visitor-specific fields such as Arrival, VisitDate, Departure, escort assignment, and checkout state.

Cardholders and visitors also have status operations. You can activate or deactivate them through the Status member.

The Configuration section later in this guide covers their main Web SDK properties. The Operations section covers checkout behavior and other live lifecycle actions.

Escorts

An escort is a cardholder who accompanies a visitor.

Escort is part of the access-control model, not just a visitor detail:

• A cardholder can be marked as eligible to escort visitors.
• A visitor can be assigned one or two escorts.
• A visitor can require an escort.
• The system also exposes a maximum number of visitors that one escort can accompany at the same time.

In Web SDK terms, the main escort-related members are:

• Cardholder.CanEscort
• escort assignment
• Visitor.MandatoryEscort
• MaximumVisitorsSingleEscort (read from SystemConfiguration entity 00000000-0000-0000-0000-000000000007; -1 means unlimited)

Escort behavior can also appear in door-related access behavior, because escort requirements may affect whether a visitor is allowed through a controlled access point.

Credentials

Credential is how the system identifies the person requesting access.

Examples include:

• card formats
• PIN credentials
• license plate credentials
• mobile credentials

One person can have multiple credentials. Replacing or adding a credential does not change who the person is or which access rules apply to that person.

The Configuration section later in this guide covers supported credential formats, value ranges, raw-data rules, and common credential lifecycle requests.

Cardholder groups

CardholderGroup lets you manage access for multiple people at once.

Instead of assigning the same access rule to many individuals one by one, you can add cardholders to a group and assign the rule to the group. This is the normal way to manage access at scale.

In Web SDK workflows, cardholder groups are typically used to:

• organize people by role, team, tenant, or department
• apply the same access rule to many people
• change group membership without changing the access rule itself

Built-in cardholder groups

Security Center includes two built-in cardholder groups that are important in access-control workflows:

Group	GUID	Meaning
All cardholders	00000000-0000-0000-0000-000000000008	The built-in group that represents all cardholders
Visitors	00000000-0000-0000-0000-00000000000d	The built-in group used for visitors

These groups already exist in the system. You do not create them yourself.

The Visitors group is a cardholder group with IsVisitorGroup=true.

The All cardholders group is especially important because system-wide access behavior is often expressed through rules that target this built-in group.

Schedules

Schedule defines when access applies.

Schedules are used in two important ways:

• On AccessRule, to define when the rule is active
• On Door and Floor, to define unlock or free-access periods

This distinction matters:

• An access rule schedule controls when a person is allowed or denied by that rule.
• A door or floor unlock schedule controls when the place itself is freely accessible.

This guide treats schedules mainly as entities that you assign to rules, doors, and floors.

Access rules

AccessRule is the main access decision entity.

An access rule combines:

• The people it applies to
• The schedule it uses
• The places where it applies
• Whether it grants or denies access while the rule is active

In Web SDK workflows, access rules are usually:

• Permanent, for normal ongoing access
• Temporary, for time-limited access

Access rules are assigned to places such as doors, elevators, and areas. The rule then applies to the people or groups attached to that rule.

Because access rules apply to people and groups, not to credentials, replacing a credential does not require you to rebuild the person’s access rules.

An access rule can be used in two different ways:

• as a grant rule
• as a deny rule

The Web SDK exposes this through IsDenyingRule.

• IsDenyingRule=false means the rule grants access while it is active.
• IsDenyingRule=true means the rule denies access while it is active.

That distinction is important because the same access-rule structure can be used either to allow normal access or to block access during a scheduled period.

Access rules versus direct access

Access rules and direct access are not the same thing.

Use an access rule when you want a reusable access decision that combines:

• people or groups
• a schedule
• one or more controlled places

Use direct access when you want to grant a specific person or group access on a specific access point without creating a reusable rule.

In practice:

• Access rules are applied to places such as doors, elevators, and areas.
• Direct access is applied to specific access points such as a door side or a floor.
• Access rules are the normal way to manage ongoing access.
• Direct access is better suited to exceptions, special cases, or tightly targeted grants.

This distinction matters because an access rule carries schedule logic, while a direct access grant does not create that same reusable rule structure.

Built-in access rules

Security Center also includes two built-in access rules:

Rule	GUID	Meaning
All open rule	00000000-0000-0000-0000-00000000000a	A built-in grant rule
Lockdown rule	00000000-0000-0000-0000-000000000009	A built-in deny rule

These rules already exist in the system. They are system rules, not ordinary user-created rules.

In the Web SDK:

• All open rule is a permanent rule with IsSystemRule=true and IsDenyingRule=false.
• Lockdown rule is a permanent rule with IsSystemRule=true and IsDenyingRule=true.
• Both use the built-in Always schedule.
• Both target the built-in All cardholders group.

Conceptually:

• All open rule means access is granted to all cardholders while that rule is applied.
• Lockdown rule means access is denied to all cardholders while that rule is applied.

These rules are useful when you need a broad system behavior instead of a custom rule for a smaller set of people.

Doors and door sides

Door is one of the most common access-controlled entities.

A door has two sides:

• DoorSideIn
• DoorSideOut

This matters because access is directional. A person might be allowed on one side of the door but not the other.

In Web SDK requests, you can work with the whole door or with one specific side:

• Use the door when you assign access rules or read door-level state.
• Use a door side when the direction matters.

Each door side can also expose its own nested access points, such as a reader, a request-to-exit device, and an entry sensor. Read DoorSideIn or DoorSideOut when you need that side-specific structure.

The Configuration section later in this guide covers door properties, door templates, hardware mapping, and side-specific rule application.

Elevators and floors

Elevator controls access to elevator usage.

Floor represents an elevator destination that can be attached to an elevator. Floors also have their own schedule-related operations.

Conceptually:

• The elevator is the access-controlled asset.
• Floors are the destinations that belong to that elevator.
• Access can be managed at the elevator level or the floor level, and schedules can also be applied at the floor level.

In practical terms, a floor can carry its own access rules and unlock schedules, even though it belongs to an elevator.

Areas

Area represents a secured space.

Areas are important because they let you model access in terms of spaces instead of only individual doors. An area can group related access-controlled elements and is also used in people-count workflows.

In Web SDK operations, areas distinguish between:

• Perimeter doors, which define the boundary of the area
• Captive doors, which are inside the area but do not define that boundary

The difference is important:

• A perimeter door is a door you cross to enter or exit the area.
• A captive door is a door that belongs to the area, but moving through it does not mean entering or leaving that area.

This distinction matters because perimeter doors are used for area entry and exit, while captive doors are internal to the area. In practical terms, perimeter doors are the doors that matter when you model area crossings, direction, people counting, and similar area-based access behavior.

In the Web SDK, the most useful area members for this are:

• PerimeterDoors
• AllDoors
• CaptiveAccessPoints
• EntryAccessPoints
• ExitAccessPoints

Door sides are also relative to the area. For a perimeter door, the In and Out meaning depends on whether that side enters the area or exits it.

How the pieces work together

A typical access-control workflow looks like this:

1. Create a Cardholder or Visitor.
2. Create or assign one or more Credential entities.
3. Optionally add the person to a CardholderGroup.
4. Create an AccessRule.
5. Assign a Schedule to that access rule.
6. Apply the access rule to a Door, Elevator, Floor, or Area.

That is the core pattern to keep in mind when reading or writing Web SDK access-control requests.

Configuration

Use /entity when you are configuring access control:

• configure people, credentials, groups, rules, schedules, doors, elevators, floors, and areas
• assign credentials, groups, rules, schedules, doors, floors, and areas
• read the current configuration state

The sections below focus on what each entity exposes and how to think about reading or changing it. The later configuration examples show the concrete request shapes.

Cardholders and visitors

The main cardholder and visitor settings fall into three groups:

• identity and contact fields such as FirstName, LastName, EmailAddress, and MobilePhoneNumber
• access-control behavior such as CanEscort, AntipassbackExemption, UseExtendedGrantTime, and TriggerCode
• lifecycle fields under Status, plus visitor-specific timing fields such as Arrival, VisitDate, and Departure

Two details matter when you update these entities:

• Config Tool calls the security-clearance value Security clearance, but the Web SDK member is AccessPermissionLevel
• Status changes are method-based, not simple property assignments

Visitors also have escort-specific settings:

• Escort
• Escort2
• MandatoryEscort
• AssignEscorts({escort-guid},{escort2-guid})

Cardholders and visitors also support picture management:

• Picture
• Thumbnail
• CanSetPicture()

Use CanSetPicture() when you need to know whether the current person entity accepts a picture update. For the actual image-upload mechanics, see Working with entity properties.

The Creating people examples later in this guide show the main read and update shapes for both cardholders and visitors.

Read a cardholder picture:

GET /entity?q=entity={cardholder-guid},CanSetPicture(),Picture,Thumbnail

Update a cardholder picture with multipart form data:

POST /entity?q=entity={cardholder-guid},Picture=$photo

Use the same shape for visitors:

POST /entity?q=entity={visitor-guid},Picture=$photo

The multipart field name must match the name after = in the query. For example, if the query uses Picture=$photo, the multipart body must include a field named $photo containing the Base64 image data.

Credentials

Credential configuration is mainly about three things:

• choosing the right credential format
• supplying the correct field values for that format
• assigning or unassigning the credential from a person

The guide uses these practical rules:

• numeric constructor formats use decimal values unless the request explicitly uses raw or XML-based undecoded Wiegand
• {raw-data} is hexadecimal text without 0x
• PIN values are numeric text and preserve leading zeroes
• custom card formats and FASC-N formats depend on exact field names and field representations

One limitation matters for PIN workflows: the Web SDK exposes the fixed 16-digit maximum, but not the configured minimum PIN length. If the minimum length matters, get it from the system administrator or handle the creation error returned by the server.

For custom formats, look up the definition first and then build the field map from that definition. For more information, see Working with Custom Card Formats.

Credential parameter rules

The placeholders used in credential creation requests are not interchangeable. Each one has a specific meaning and expected value format.

Placeholder	Meaning	Value format
{facility}	The facility code portion of the credential	Decimal integer
{company-id}	The company or facility portion used by that specific card format	Decimal integer
{number}	The card number portion of the credential	Decimal integer
{card-id}	The card identifier portion of the credential	Decimal integer in the constructor forms shown above
{pin}	The keypad PIN	Numeric text
{license-plate}	The plate text	Plain text
{raw-data}	The raw card payload for raw or undecoded Wiegand credentials	Hexadecimal text without 0x
{bit-length}	The number of bits represented by the credential payload	Decimal integer
{format-guid}	The GUID of an existing custom card format definition	GUID
{field-name} / {field-value}	A field from a custom card format or FASC-N field map	Exact field name and value format required by that format

Built-in numeric credential ranges

The constructor forms shown later in this guide use decimal numeric arguments unless the request uses the raw XML-based undecoded Wiegand form.

Format	Fields	Allowed range
Standard 26-bit	{facility}, {number}	{facility}: 0 to 255; {number}: 0 to 65535
HID H10306 34-bit	{facility}, {number}	{facility}: 0 to 65535; {number}: 0 to 65535
HID Corporate 1000 35-bit	{company-id}, {card-id}	{company-id}: 0 to 4095; {card-id}: 0 to 1048575
HID H10302 37-bit	{number}	0 to 34359738367
HID H10304 37-bit	{facility}, {card-id}	{facility}: 0 to 65535; {card-id}: 0 to 524287
HID Corporate 1000 48-bit	{company-id}, {card-id}	{company-id}: 0 to 4194304; {card-id}: 0 to 8388608
CSN 32-bit	{card-id}	Decimal 0 to 4294967295
PIN	{pin}	Up to 16 digits
License plate	{license-plate}	Up to 12 characters after spaces are removed

Raw and undecoded credential values

{raw-data} is hexadecimal text. Do not include a 0x prefix.

Use {bit-length} as the actual size of the credential payload in bits. Common values in the built-in formats are 26, 32, 34, 35, 37, 48, 75, and 200.

For raw-card and undecoded Wiegand formats, the hexadecimal value must fit inside the specified bit length.

For CSN 32-bit credentials, use the constructor form when you have the numeric value of the CSN. Use the undecoded Wiegand XML form when you want to send the raw hexadecimal payload directly.

Advanced credential format helpers

Three additional format helpers exist, but they are only useful in advanced undecoded/custom Wiegand scenarios:

• GetCredentialFormatId()
• ChangeCredentialFormat({format-guid})

Use them with these expectations:

• GetCredentialFormatId() returns the current format GUID for an UndecodedWiegand credential whose internal format is already assigned.
• ChangeCredentialFormat({format-guid}) does not rewrite the credential payload. It asks Security Center to reinterpret the existing bit pattern as another compatible format.

This means:

• these helpers are not part of the normal credential lifecycle
• they matter mainly when you are troubleshooting or correcting undecoded/custom Wiegand credentials
• built-in constructor formats such as WiegandStandardCredentialFormat(...) are still the normal way to create credentials
• when you need a format-guid, read it from an existing credential's Format.FormatId value or from the custom card format definition you want to target

FASC-N and custom field values

FASC-N formats use field-name/value maps instead of a short numeric constructor.

FASC-N 75-bit fields:

Field	Allowed range
Agency Code	0 to 16383
System Code	0 to 16383
Credential Number	0 to 1048575
Exp Data	0 to 33554431

FASC-N 200-bit fields:

Field	Allowed range
Agency Code	0 to 9999
System Code	0 to 9999
Credential Number	0 to 999999
CS	0 to 9
ICI	0 to 9
PI	0 to 9999999999
OC	0 to 9
OI	0 to 9999
POA	0 to 9
LRC	Hexadecimal 0 to 0x10

The Creating and assigning credentials examples later in this guide show the concrete request shapes for the supported credential families.

Cardholder groups

Cardholder-group configuration is mostly about:

• contact fields such as EmailAddress
• visitor availability through IsVisitorGroup
• security clearance through AccessPermissionLevel and InheritAccessPermissionLevel
• membership through Children, Members, and group membership methods

The main naming and support details are:

• Config Tool calls the security-clearance value Security clearance, but the Web SDK member is AccessPermissionLevel
• Bypass antipassback rules is not exposed through the q= member surface for CardholderGroup

The Working with cardholder groups examples later in this guide show the normal request shapes for reading, updating, and changing membership.

Schedules

The Web SDK can create an empty Schedule entity, check whether a time is covered, and reset its coverage.

The important limitation is that creating the schedule entity is not the same thing as building a useful day-and-time definition. For access-control integrations, the practical approach is usually to use schedules that already exist in Security Center and assign them by GUID.

Access rules

Access-rule configuration is mostly about:

• whether the rule grants access or denies access through IsDenyingRule
• which Schedule the rule uses
• which cardholders or groups are attached to it
• which places the rule is applied to

Temporary rules add one more layer of configuration because they also carry their own start and end time window.

For doors, rule application can also be directional:

• apply the rule to the whole door
• apply it to In
• apply it to Out
• apply it to Both

The Creating access rules and Applying access to places examples later in this guide show the main request shapes.

Doors, door templates, and hardware mapping

Door configuration includes:

• door-level state and timing such as IsLocked, IsOpen, StandardGrantTimeInSeconds, ExtendedGrantTimeInSeconds, RelockDelayInSeconds, and AutoUnlockOverride
• nested behavior groups such as DoorForced, DoorHeld, RequestToExit, VisitorEscort, and TwoPersonRule
• free-access and exception schedules through UnlockSchedules and UnlockExceptionSchedules
• reusable door-template configuration through DoorTemplate
• wiring and device mapping through members such as PreferredUnit, PreferredInterface, DoorLockDevice, DoorSideIn, DoorSideOut, and GetConnections({access-point-type})

Two practical distinctions matter:

• side-specific access rules are still access rules, while direct door-side access is a different targeted grant model
• nested side hardware is easy to read, but you manage the mapping through the door’s connection methods rather than a path such as DoorSideIn.Reader.Device={device-guid}

The Working with doors and Working with door templates and hardware mapping examples later in this guide show the request shapes for these settings.

Elevators, floors, and areas

Elevator, floor, and area configuration is mostly about how access applies to places:

• Elevator exposes the Floors that belong to it
• Floor carries its own AccessRules, UnlockSchedules, and UnlockExceptionSchedules
• Area carries perimeter and captive-door relationships, plus area-level access rules

Two practical distinctions matter here:

• AccessRules define who is allowed or denied
• UnlockSchedules define when the place itself is freely accessible

For floors, use the floor GUID returned by the parent elevator when you want to read or configure one specific floor.

Floors are not created with NewEntity(Floor). In practice, create or obtain them through elevator configuration, then work with the floor entity by GUID.

For areas, distinguish clearly between:

• perimeter doors added with AddDoor({door-guid})
• captive doors added with AddCaptiveDoor({door-guid})

The Applying access to places and Working with floors and unlock schedules examples later in this guide show the normal request shapes.

Finding entities

Use /entity when you already know the entity GUID.

Use report endpoints when you need to search by name, status, format, or other criteria first.

The main search routes for access-control integrations are:

What you want to find	Route	Typical filters
Cardholders	/report/CardholderConfiguration	FirstName, LastName, FullName, Email, MobilePhoneNumber, CardholderGroupIds, AccessStatus
Visitors	/report/Visitor	VisitorStates, FirstName, LastName, FullName, Email, MobilePhoneNumber
Credentials	/report/CredentialConfiguration	UniqueIds, UnassignedOnly, FormatType, MobileCredentialOnly
Access rules	/report/AccessRuleConfiguration	Name, AccessRuleType
Cardholder groups, schedules, doors, elevators, floors, and areas	/report/EntityConfiguration	EntityTypes, Name, Description, ReturnFields (EntityTypes@AccessPoint for floors)

A few practical search rules are worth keeping in mind:

• Use /report/Visitor when you need visitor lifecycle search, especially active versus archived visitors.
• Search Door first, then read DoorSideIn or DoorSideOut from the door entity.
• For floors, either search the elevator first and read Floors, or search /report/EntityConfiguration with EntityTypes@AccessPoint when you already know the floor name.
• For a more complete guide to report endpoints, filters, ReturnFields, and specialized configuration queries, see Referencing entities.

Configuration examples

The examples in this section show common Web SDK request shapes for access-control tasks.

Searching

Search cardholders by first and last name:

GET /report/CardholderConfiguration?q=FirstName={first-name},LastName={last-name},PageSize=10

Search cardholders by email address:

GET /report/CardholderConfiguration?q=Email={email},PageSize=10

Search credentials by unique value:

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

Note

This PIN example is not guaranteed to return a single match. Multiple credentials can share the same PIN, and the response can return Rsp.Status: "TooManyResults".

Find unassigned credentials:

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

Search access rules by name:

GET /report/AccessRuleConfiguration?q=Name={rule-name},PageSize=10

Search schedules by name:

GET /report/EntityConfiguration?q=EntityTypes@Schedule,Name={schedule-name},PageSize=10,ReturnFields@Name

Search cardholder groups by name:

GET /report/EntityConfiguration?q=EntityTypes@CardholderGroup,Name={group-name},PageSize=10,ReturnFields@Name

Search doors by entity type:

GET /report/EntityConfiguration?q=EntityTypes@Door,PageSize=10,ReturnFields@Name

Search areas by entity type:

GET /report/EntityConfiguration?q=EntityTypes@Area,PageSize=10,ReturnFields@Name

Creating people

Create a cardholder:

POST /entity?q=entity=NewEntity(Cardholder),Name={name},FirstName={first-name},LastName={last-name},EmailAddress={email},MobilePhoneNumber={mobile-phone},Guid

Read the main cardholder properties:

GET /entity?q=entity={cardholder-guid},FirstName,LastName,EmailAddress,MobilePhoneNumber,UseExtendedGrantTime,CanEscort,AntipassbackExemption,TriggerCode,AccessPermissionLevel,InheritAccessPermissionLevel,OfflineToggleFunction,OfflineRevalidationPeriod,Status.State,Status.ActivationDate,Status.ExpirationDate,Status.ExpirationType

Update the basic contact properties:

POST /entity?q=entity={cardholder-guid},FirstName={first-name},LastName={last-name},EmailAddress={email},MobilePhoneNumber={mobile-phone}

Update the boolean access-control properties:

POST /entity?q=entity={cardholder-guid},UseExtendedGrantTime=true,CanEscort=true,AntipassbackExemption=true,OfflineToggleFunction=true,OfflineRevalidationPeriod=14

Set the trigger code:

POST /entity?q=entity={cardholder-guid},TriggerCode=5

Set the security clearance:

POST /entity?q=entity={cardholder-guid},SetAccessPermissionLevel({level})

level is the security-clearance value you want to apply to that cardholder.

Make the cardholder inherit the security clearance from its group:

POST /entity?q=entity={cardholder-guid},SetInheritAccessPermissionLevel(true)

Stop inheriting the security clearance from the group:

POST /entity?q=entity={cardholder-guid},SetInheritAccessPermissionLevel(false)

Read the current status:

GET /entity?q=entity={cardholder-guid},Status.State,Status.ActivationDate,Status.ExpirationDate,Status.ExpirationType

Deactivate a cardholder now:

POST /entity?q=entity={cardholder-guid},Status.Deactivate()

Set a cardholder expiration date:

POST /entity?q=entity={cardholder-guid},Status.Deactivate({expiration-date-time})

expiration-date-time is when the cardholder should expire.

Activate a cardholder:

POST /entity?q=entity={cardholder-guid},Status.Activate()

Create a visitor:

POST /entity?q=entity=NewEntity(Visitor),Name={name},FirstName={first-name},LastName={last-name},EmailAddress={email},MobilePhoneNumber={mobile-phone},Guid

Read the main visitor properties:

GET /entity?q=entity={visitor-guid},FirstName,LastName,EmailAddress,MobilePhoneNumber,Arrival,VisitDate,Departure,CheckinDate,Escort,Escort2,MandatoryEscort,Status.State,Status.ActivationDate,Status.ExpirationDate

Update the visitor timing and escort requirement:

POST /entity?q=entity={visitor-guid},Arrival={arrival-date-time},VisitDate={visit-date-time},Departure={departure-date-time},MandatoryEscort=true

Check in a visitor:

POST /entity?q=entity={visitor-guid},Status.Activate()

Note

After Status.Activate(), do not assume the planned timing values remain unchanged. The active-visitor lifecycle can replace Arrival and Status.ActivationDate with the actual check-in time, and Departure / Status.ExpirationDate may no longer keep the planned end time.

Check out a visitor:

POST /entity?q=entity={visitor-guid},Checkout()

Allow a cardholder to escort visitors:

POST /entity?q=entity={cardholder-guid},CanEscort=true

Require an escort for a visitor:

POST /entity?q=entity={visitor-guid},MandatoryEscort=true

Assign escorts to a visitor:

POST /entity?q=entity={visitor-guid},AssignEscorts({escort-guid},{escort2-guid})

Note

The selected escort cardholder must already have CanEscort=true. Otherwise AssignEscorts(...) fails.

Find active visitors by name:

GET /report/Visitor?q=VisitorStates@Active,FirstName={first-name},LastName={last-name}

Find archived visitors by name:

GET /report/Visitor?q=VisitorStates@Archived,FirstName={first-name},LastName={last-name}

Find archived visitors by full name:

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

Find archived visitors by email address:

GET /report/Visitor?q=VisitorStates@Archived,Email={email}

Creating and assigning credentials

Create a PIN credential:

POST /entity?q=entity=NewEntity(Credential),Name={name},Format=KeypadCredentialFormat({pin}),Guid

Create a standard 26-bit credential:

POST /entity?q=entity=NewEntity(Credential),Name={name},Format=WiegandStandardCredentialFormat({facility},{number}),Guid

Create an HID H10302 37-bit credential:

POST /entity?q=entity=NewEntity(Credential),Name={name},Format=WiegandH10302CredentialFormat({number}),Guid

Create an HID H10306 34-bit credential:

POST /entity?q=entity=NewEntity(Credential),Name={name},Format=WiegandH10306CredentialFormat({facility},{number}),Guid

Create an HID H10304 37-bit credential:

POST /entity?q=entity=NewEntity(Credential),Name={name},Format=WiegandH10304CredentialFormat({facility},{card-id}),Guid

Create a Corporate 1000 35-bit credential:

POST /entity?q=entity=NewEntity(Credential),Name={name},Format=WiegandCorporate1000CredentialFormat({company-id},{card-id}),Guid

Create a Corporate 1000 48-bit credential:

POST /entity?q=entity=NewEntity(Credential),Name={name},Format=Wiegand48BitCorporate1000CredentialFormat({company-id},{card-id}),Guid

Create a CSN 32-bit credential:

POST /entity?q=entity=NewEntity(Credential),Name={name},Format=WiegandCsn32CredentialFormat({number}),Guid

Create a license plate credential:

POST /entity?q=entity=NewEntity(Credential),Name={name},Format=LicensePlateCredentialFormat({license-plate}),Guid

Create a raw card credential:

POST /entity?q=entity=NewEntity(Credential),Name={name},Format=RawCardCredentialFormat({raw-data},{bit-length}),Guid

Create a credential using a custom card format:

POST /entity?q=entity=NewEntity(Credential),Name={name},Format=CustomCredentialFormat({format-guid},{{field-name,value}}),Guid

The {format-guid} is the custom card format GUID (see Custom Card Formats). The field names and values must match the format definition exactly.

Create a FASC-N 75-bit credential:

POST /entity?q=entity=NewEntity(Credential),Name={name},Format=FascN75BitCardCredentialFormat({{Agency%20Code,{agency}},{System%20Code,{system}},{Credential%20Number,{number}},{Exp%20Date,{expiration}}}),Guid

Create a FASC-N 200-bit credential:

POST /entity?q=entity=NewEntity(Credential),Name={name},Format=FascN200BitCardCredentialFormat({{Agency%20Code,{agency}},{System%20Code,{system}},{Credential%20Number,{number}},{CS,{cs}},{ICI,{ici}},{PI,{pi}},{OC,{oc}},{OI,{oi}},{POA,{poa}},{LRC,{lrc}}}),Guid

Note

FASC-N field names contain spaces and must be URL-encoded (e.g., Agency%20Code). See Built-in credential ranges for allowed field values.

Create a credential request:

POST /entity?q=entity=NewEntity(Credential),Name={name},Format=CardRequestCredentialFormat(),Guid

Read the current credential request:

GET /entity?q=entity={credential-guid},GetCredentialRequest()

If no request exists for that credential, the call can still return Ok without a GetCredentialRequest object in the result.

Cancel the current credential request:

POST /entity?q=entity={credential-guid},CancelCredentialRequest()

Read the credential format that was stored:

GET /entity?q=entity={credential-guid},Format

Read the current credential format GUID for an undecoded/custom Wiegand credential:

GET /entity?q=entity={credential-guid},GetCredentialFormatId()

This helper is only useful when the credential is already stored as UndecodedWiegand.

Try to reinterpret an undecoded/custom Wiegand credential as another compatible format:

POST /entity?q=entity={credential-guid},ChangeCredentialFormat({format-guid})

format-guid is the GUID of a compatible card format. The call returns true only when Security Center can interpret the existing raw bit pattern as that format.

Assign a credential to a cardholder:

POST /entity?q=entity={credential-guid},Cardholder={cardholder-guid}

Unassign a credential from a cardholder:

POST /entity?q=entity={credential-guid},CardholderGuid=00000000-0000-0000-0000-000000000000

The property name changes on purpose. The assign example uses Cardholder={cardholder-guid} because it reads naturally as a relationship update. The unassign example uses CardholderGuid=00000000-0000-0000-0000-000000000000 because clearing the GUID is the clearest way to remove the assignment.

Deactivate a credential:

POST /entity?q=entity={credential-guid},Status.Deactivate()

Activate a credential:

POST /entity?q=entity={credential-guid},Status.Activate()

Check whether a credential has access on a specific door side at a specific time:

GET /entity?q=entity={credential-guid},HasAccess({door-side-guid},{date-time-utc})

date-time-utc is the UTC time you want to evaluate, for example 2026-03-10T12:00:00Z.

Working with cardholder groups

Create a cardholder group:

POST /entity?q=entity=NewEntity(CardholderGroup),Name={name},Guid

Read the main group properties:

GET /entity?q=entity={cardholder-group-guid},EmailAddress,IsVisitorGroup,AccessPermissionLevel,InheritAccessPermissionLevel,Children,Members,Parents,AccessRules

Read the built-in All cardholders group:

GET /entity?q=entity=00000000-0000-0000-0000-000000000008,Name,IsVisitorGroup,Children,AccessRules

Read the built-in Visitors group:

GET /entity?q=entity=00000000-0000-0000-0000-00000000000d,Name,EmailAddress,IsVisitorGroup,AccessPermissionLevel,InheritAccessPermissionLevel

Set the group email address:

POST /entity?q=entity={cardholder-group-guid},EmailAddress={email}

Make a group available to visitors:

POST /entity?q=entity={cardholder-group-guid},IsVisitorGroup=true

Set the group security clearance:

POST /entity?q=entity={cardholder-group-guid},SetAccessPermissionLevel({level})

Make the group inherit its security clearance:

POST /entity?q=entity={cardholder-group-guid},SetInheritAccessPermissionLevel(true)

Add a cardholder to a group:

POST /entity?q=entity={cardholder-group-guid},AddCardholderIntoGroup({cardholder-guid})

Remove a cardholder from a group:

POST /entity?q=entity={cardholder-group-guid},RemoveCardholderFromGroup({cardholder-guid})

Creating access rules

Create a permanent access rule:

POST /entity?q=entity=NewEntity(AccessRule),Name={name},Guid

Create a deny access rule:

POST /entity?q=entity=NewEntity(AccessRule),Name={name},IsDenyingRule=true,Guid

Create a temporary access rule:

POST /entity?q=entity=NewEntity(AccessRule,Temporary),Name={name},StartTime={start-time},EndTime={end-time},Guid

Assign a schedule to an access rule:

POST /entity?q=entity={access-rule-guid},Schedule={schedule-guid}

Add a cardholder to an access rule:

POST /entity?q=entity={access-rule-guid},AddCardholders({cardholder-guid})

Add a cardholder group to an access rule:

POST /entity?q=entity={access-rule-guid},AddCardholders({cardholder-group-guid})

Check whether a cardholder or group is already assigned to an access rule:

GET /entity?q=entity={access-rule-guid},IsMember({entity-guid})

Remove one or more cardholders or groups from an access rule:

POST /entity?q=entity={access-rule-guid},RemoveCardholders({entity-guid-1,entity-guid-2})

Clear all cardholders and groups from an access rule:

POST /entity?q=entity={access-rule-guid},ClearCardholders()

Read the schedule currently assigned to an access rule:

GET /entity?q=entity={access-rule-guid},Schedule

Read whether an access rule is currently a grant rule or a deny rule:

GET /entity?q=entity={access-rule-guid},IsDenyingRule

Read the built-in All open rule:

GET /entity?q=entity=00000000-0000-0000-0000-00000000000a,Name,IsSystemRule,IsDenyingRule,AccessRuleType,ScheduleGuid,Cardholders

Read the built-in Lockdown rule:

GET /entity?q=entity=00000000-0000-0000-0000-000000000009,Name,IsSystemRule,IsDenyingRule,AccessRuleType,ScheduleGuid,Cardholders

Turn an existing access rule into a deny rule:

POST /entity?q=entity={access-rule-guid},IsDenyingRule=true

Working with doors

Read common door properties:

GET /entity?q=entity={door-guid},Name,DoorType,IsLocked,IsOpen,StandardGrantTimeInSeconds,ExtendedGrantTimeInSeconds,StandardEntryTimeInSeconds,ExtendedEntryTimeInSeconds,RelockDelayInSeconds,RelockOnClose,UnlockSchedules,UnlockExceptionSchedules

Read the door-forced settings:

GET /entity?q=entity={door-guid},DoorForced.IsActive,DoorForced.BuzzerBehavior

Read the door-held settings:

GET /entity?q=entity={door-guid},DoorHeld.IsActive,DoorHeld.TriggerTime,DoorHeld.BuzzerBehavior

Read the request-to-exit settings:

GET /entity?q=entity={door-guid},RequestToExit.UnlockOnRex,RequestToExit.IgnoreRexEventsWhenDoorOpen,RequestToExit.HoldoffAfterClosedDelayInSeconds,RequestToExit.HoldoffAfterGrantedDelayInSeconds

Read both door sides and their side-specific access points:

GET /entity?q=entity={door-guid},DoorSideIn,DoorSideOut

Update the standard and extended grant times:

POST /entity?q=entity={door-guid},StandardGrantTimeInSeconds={standard-seconds},ExtendedGrantTimeInSeconds={extended-seconds}

Update the relock delay:

POST /entity?q=entity={door-guid},RelockDelayInSeconds={seconds}

Ignore access events while the door is unlocked by schedule:

POST /entity?q=entity={door-guid},IgnoreAccessEventsWhenUnlockedBySchedule=true

Update the request-to-exit delay after the door closes:

POST /entity?q=entity={door-guid},RequestToExit.HoldoffAfterClosedDelayInSeconds={seconds}

Update the maximum delay allowed between a visitor and an escort presentation:

POST /entity?q=entity={door-guid},VisitorEscort.MaximumDelayBetweenCardPresentations={seconds}

Update the door-held trigger time:

POST /entity?q=entity={door-guid},DoorHeld.TriggerTime={seconds}

DoorHeld.IsActive must already be true before you change DoorHeld.TriggerTime.

Note

Door timing constraints:

• StandardGrantTimeInSeconds and ExtendedGrantTimeInSeconds: 1 to 1000. Standard must be less than or equal to extended.
• StandardEntryTimeInSeconds and ExtendedEntryTimeInSeconds: 1 to 1000. Extended requires an entry sensor.
• RelockDelayInSeconds: 0 to 86439.
• DoorHeld.TriggerTime: 0 to 3699.

Working with door templates and hardware mapping

These are advanced configuration operations. Use them only when you have the required units, interface modules, and devices, and when it is safe to change the door's hardware mapping.

Query door templates:

GET /report/EntityConfiguration?q=EntityTypes@DoorTemplate,Page=1,PageSize=10,ReturnFields@Name

Create a door template:

POST /entity?q=entity=NewEntity(DoorTemplate),Name={name},Guid

Read the main door-template flags:

GET /entity?q=entity={door-template-guid},Name,IsHardwareMappingEnabled,IsHardwareSettingsEnabled,IsDoorPropertiesEnabled,IsAccessRulesEnabled

Read the current door-template selectors and assignments:

GET /entity?q=entity={door-template-guid},GetCurrentAccessPointSelectors(),GetCurrentAccessRuleDescriptors(),GetCurrentCardAndPinSettings(),GetAppliedDoors()

Apply a door template to a door:

POST /entity?q=entity={door-template-guid},Apply({door-guid},{unit-guid},{interface-guid})

door-guid is the door that should receive the template. unit-guid is the preferred access control unit, and interface-guid is the preferred interface module to use when applying the template.

Read the door's current hardware mapping:

GET /entity?q=entity={door-guid},PreferredUnit,PreferredInterface,DoorLockDevice

Read the side-specific reader, request-to-exit device, and entry sensor:

GET /entity?q=entity={door-guid},DoorSideIn.Reader,DoorSideIn.Rex,DoorSideIn.EntrySensor,DoorSideOut.Reader,DoorSideOut.Rex,DoorSideOut.EntrySensor

Read the mapped door lock and door sensor connections:

GET /entity?q=entity={door-guid},GetConnections(DoorLock),GetConnections(DoorSensor)

In GetConnections({access-point-type}), the argument is an AccessPointType such as DoorLock, DoorSensor, Rex, PullStation, Buzzer, or LockSensor.

Set the preferred unit:

POST /entity?q=entity={door-guid},SetPreferredUnit({unit-guid})

Set the preferred interface:

POST /entity?q=entity={door-guid},SetPreferredInterface({interface-guid})

Remove the preferred unit:

POST /entity?q=entity={door-guid},RemovePreferredUnit()

Remove the preferred interface:

POST /entity?q=entity={door-guid},RemovePreferredInterface()

Set the door lock device:

POST /entity?q=entity={door-guid},DoorLockDevice={device-guid}

Add a mapped connection:

POST /entity?q=entity={door-guid},AddConnection({device-guid},{access-point-type})

Here, device-guid is the hardware device you want to connect, and access-point-type is the connection role that device should play on the door, such as DoorLock, DoorSensor, Rex, PullStation, Buzzer, or LockSensor.

Update a mapped connection:

POST /entity?q=entity={door-guid},UpdateConnection({access-point-guid},{device-guid})

access-point-guid is the existing mapped access point on the door. device-guid is the replacement hardware device.

Note

A hardware device can only be assigned to one access point at a time. If the target device is already mapped elsewhere, remove the existing connection first.

Remove a mapped connection:

POST /entity?q=entity={door-guid},RemoveConnection({access-point-guid})

Use the access-point-guid returned by the current door mapping when you want to remove one specific mapped connection.

Remove a mapped connection by hardware device:

POST /entity?q=entity={door-guid},RemoveConnectionByDevice({device-guid})

Use this form when you know the underlying hardware device GUID but not the mapped access-point GUID.

Applying access to places

Apply an access rule to a door:

POST /entity?q=entity={door-guid},AddAccessRule({access-rule-guid})

Apply an access rule to both sides of a door explicitly:

POST /entity?q=entity={door-guid},AddAccessRule({access-rule-guid},Both)

Apply an access rule to the In side of a door only:

POST /entity?q=entity={door-guid},AddAccessRule({access-rule-guid},In)

Apply an access rule to the Out side of a door only:

POST /entity?q=entity={door-guid},AddAccessRule({access-rule-guid},Out)

Read the access rules assigned to the In side of a door:

GET /entity?q=entity={door-guid},FetchAccessRulesForSide(In)

Apply an access rule to an area:

POST /entity?q=entity={area-guid},AddAccessRule({access-rule-guid})

Apply an access rule to an elevator:

POST /entity?q=entity={elevator-guid},AddAccessRule({access-rule-guid})

Remove an access rule from a door:

POST /entity?q=entity={door-guid},RemoveAccessRule({access-rule-guid})

Remove an access rule from the In side of a door only:

POST /entity?q=entity={door-guid},RemoveAccessRule({access-rule-guid},In)

Remove an access rule from the Out side of a door only:

POST /entity?q=entity={door-guid},RemoveAccessRule({access-rule-guid},Out)

Remove an access rule from an area:

POST /entity?q=entity={area-guid},RemoveAccessRule({access-rule-guid})

Remove an access rule from an elevator:

POST /entity?q=entity={elevator-guid},RemoveAccessRule({access-rule-guid})

Add a perimeter door to an area:

POST /entity?q=entity={area-guid},AddDoor({door-guid}),PerimeterDoors

Add a captive door to an area:

POST /entity?q=entity={area-guid},AddCaptiveDoor({door-guid}),CaptiveAccessPoints

Remove a perimeter door from an area:

POST /entity?q=entity={area-guid},RemoveDoor({door-guid})

Grant direct access on one door side:

POST /entity?q=entity={door-side-in-guid},AddCardholderOrGroup({cardholder-guid})

Grant direct access to a cardholder group on one door side:

POST /entity?q=entity={door-side-in-guid},AddCardholderOrGroup({cardholder-group-guid})

Remove a direct cardholder or group grant from one door side:

POST /entity?q=entity={door-side-in-guid},RemoveCardholderOrGroup({cardholder-or-group-guid})

Read the floor GUIDs attached to an elevator:

GET /entity?q=entity={elevator-guid},Floors

Read a floor directly:

GET /entity?q=entity={floor-guid},Name,Elevator,LogicalOrder,UnlockSchedules,UnlockExceptionSchedules,AccessRules

Grant access to a floor through an access rule:

POST /entity?q=entity={floor-guid},AccessRules@{access-rule-guid}

Read both door sides and their current side-specific access configuration:

GET /entity?q=entity={door-guid},DoorSideIn,DoorSideOut

door-side-in-guid is the card-reader access point GUID. Read it from DoorSideIn.Reader.Guid or DoorSideOut.Reader.Guid on the parent door.

Working with floors and unlock schedules

Create an empty schedule record:

POST /entity?q=entity=NewEntity(Schedule),Name={name},Guid

This creates the schedule entity itself, but not a full working coverage definition. For most access-control workflows, use an existing schedule.

Attach a floor to an elevator:

POST /entity?q=entity={elevator-guid},AddFloor({floor-guid})

Add an unlock schedule to a door:

POST /entity?q=entity={door-guid},UnlockSchedules@{schedule-guid}

Add an unlock schedule to a floor:

POST /entity?q=entity={floor-guid},UnlockSchedules@{schedule-guid}

Search a floor by name when you already know the floor name:

GET /report/EntityConfiguration?q=EntityTypes@AccessPoint,Name={floor-name},NameSearchMode=Is,PageSize=10,ReturnFields@Name@EntityType@EntitySubType

Check whether a schedule covers a specific time:

GET /entity?q=entity={schedule-guid},IsTimeCovered({date-time})

date-time is the exact instant you want to test against the schedule.

Read the current coverage and twilight support of a schedule:

GET /entity?q=entity={schedule-guid},Coverage,SupportTwilightCoverage

Reset a schedule to an empty coverage:

POST /entity?q=entity={schedule-guid},Reset()

Operations

This section groups live runtime behavior. Some of these operations use /entity, and some use /action, but they all affect how the running system behaves rather than how the long-term access-control model is configured.

Visitor checkout

Checkout() changes how the visitor is accessed through the Web SDK.

After a visitor checks out:

• the active visitor no longer resolves through /entity
• the visitor no longer appears in active /report/Visitor results
• the visitor becomes searchable in archived /report/Visitor results
• credentials assigned to the visitor are unassigned but remain active. The credential's CardholderGuid is set to the empty GUID and the credential's State stays Active. If you need to deactivate or delete the credential after checkout, do it in a separate request.

Archived visitors are searched through /report/Visitor, not through /entity.

Note

The archived visitor record uses a different GUID than the original active visitor. After checkout, search archived visitors again instead of reusing the original active visitor GUID.

Search archived visitors with the same visitor-report fields you use for active visitors, such as FirstName, LastName, FullName, Email, and MobilePhoneNumber.

Archived visitor results include lifecycle details that matter to visitor-management integrations, such as CheckinDate, CheckoutDate, VisitorState, escort fields, and contact information.

Deleting archived visitors is not supported through Web SDK q= requests.

Live actions versus configuration

Use /action when you want to perform a live operational command such as:

• momentarily unlock a door
• override a door or floor locking schedule for a time window
• turn a door buzzer on or off
• forgive antipassback
• correct area people-count state

Some live door operations also use /entity, especially when they change the door's current runtime state rather than the long-term access-control model.

By contrast, Configuration uses /entity to define or change the long-term access-control model.

Antipassback and people counting

Antipassback and people counting are runtime concepts, not just configuration concepts.

People counting keeps track of whether a person is considered inside or outside an area. Antipassback uses that same movement state to prevent impossible or repeated movements, such as entering twice in a row without a matching exit.

For Web SDK integrations, the practical consequence is:

• use access rules, areas, and doors to model normal movement
• use /action when you need to correct runtime state after an exception, operator intervention, or data mismatch

The most important runtime correction actions are:

• ForgiveAntipassback({cardholder-guid})
• ModifyPeopleCount({area-guid},{cardholder-guid},true|false)
• ResetPeopleCount({area-guid})

Working with live access-control actions

Set a temporary auto-unlock override on a door:

POST /entity?q=entity={door-guid},SetAutoUnlockOverride({unlock},{start-time},{end-time})

unlock=true means the override unlocks the door during the time window. start-time and end-time are UTC timestamps.

Remove the current auto-unlock override from a door:

POST /entity?q=entity={door-guid},RemoveAutoUnlockOverride()

Read whether maintenance mode is currently active on a door:

GET /entity?q=entity={door-guid},MaintenanceModeActive

Enable maintenance mode on a door:

POST /entity?q=entity={door-guid},SetMaintenanceMode(true)

Disable maintenance mode on a door:

POST /entity?q=entity={door-guid},SetMaintenanceMode(false)

Momentarily unlock a door:

POST /action?q=UnlockDoor({door-guid})

Perform the same momentary unlock using the alternate action name:

POST /action?q=Open({door-guid})

These two actions have the same behavior. Use whichever name is clearer for your integration. This guide prefers UnlockDoor({door-guid}).

Turn the buzzer off on a door:

POST /action?q=SetBuzzerState({door-guid},false)

Forgive antipassback for a cardholder:

POST /action?q=ForgiveAntipassback({cardholder-guid})

Raise a lock-state event from a door:

POST /entity?q=entity={door-guid},SetIsLockedAndRaiseEvent(true)

Raise an open-state event from a door:

POST /entity?q=entity={door-guid},SetIsOpenAndRaiseEvent(true)

Enable the door-held trigger and set its threshold:

POST /entity?q=entity={door-guid},DoorHeld.IsActive=true,DoorHeld.TriggerTime={seconds}

Other operational access-control actions that are often relevant in integrations include:

• OverrideLockingScheduleOnDoor({door-guid},{unlock},{start-time},{end-time})
• OverrideLockingScheduleOnFloor({elevator-guid},{floor-guid},{unlock},{all-floors},{start-time},{end-time})
• ModifyPeopleCount({area-guid},{cardholder-guid},true|false)
• ResetPeopleCount({area-guid})

In those action shapes, unlock=true unlocks during the override period and unlock=false locks during the override period. start-time and end-time are the UTC bounds of the override. For floor overrides, all-floors=true applies the override to every floor on the elevator. In ModifyPeopleCount({area-guid},{cardholder-guid},true|false), true simulates an in access and false simulates an out access.