Find Object

title: “Find Object by Moniker”

Find and return an object using its unique moniker identifier. Monikers provide a stable, human-readable way to reference system objects like event types and schedules.

Method Signature

Task<T> GetByMonikerAsync<T>(
    string namespace,
    string nickname
) where T : BaseInfo

Parameters

Parameter Type Description
namespace string The moniker namespace (e.g., MercuryServiceEvents)
nickname string The moniker nickname (e.g., mercury:access-granted)

What is a Moniker?

A moniker is a two-part identifier consisting of:

  • Namespace: Groups related objects (e.g., MercuryServiceEvents, MercuryServiceCommands)
  • Nickname: Unique identifier within the namespace (e.g., mercury:access-granted)

Monikers are stable across environments, unlike object keys which differ between systems.

Examples

C# Wrapper

// Get an event type by moniker
var eventType = await client.GetByMonikerAsync<EventTypeInfo>(
    "MercuryServiceEvents",
    "mercury:access-granted"
);

// Get "Always" schedule
var alwaysSchedule = await client.GetByMonikerAsync<ScheduleInfo>(
    "MercuryServiceEvents",
    "mercury:always-schedule"
);

// Get a service command event type
var pulseCommand = await client.GetByMonikerAsync<EventTypeInfo>(
    "MercuryServiceCommands",
    "mercury:command-pulse"
);

Common Monikers

Namespace Nickname Object Type
MercuryServiceEvents mercury:access-granted EventTypeInfo
MercuryServiceEvents mercury:access-denied EventTypeInfo
MercuryServiceEvents mercury:always-schedule ScheduleInfo
MercuryServiceCommands mercury:command-pulse EventTypeInfo
MercuryServiceCommands mercury:command-lock EventTypeInfo
MercuryServiceCommands mercury:command-unlock EventTypeInfo

Get By Href Async

Example in C#

// Returns: T
var item = await client.GetByHrefAsync<T>(String href);

title: “GetByHrefAsync”

Retrieve an object by its API href path. Useful when you have an object link or URL reference to an object.

Method Signature

Task<T> GetByHrefAsync<T>(
    string href
) where T : BaseInfo

Parameters

Parameter Type Description
href string The API path to the object

Returns

The object at the specified href, cast to type T.

Href Format

/api/f/{folder-key}/{endpoint}/{object-key}

Examples:

  • /api/f/507f1f77bcf86cd799439011/people/507f1f77bcf86cd799439012
  • /api/f/507f1f77bcf86cd799439011/controllers/507f1f77bcf86cd799439013
  • /api/f/507f1f77bcf86cd799439011/accesslevels/507f1f77bcf86cd799439014

Examples

C# Wrapper

// Get object from an ObjectLink
var person = await client.GetPeopleAsync(instance, 0, 1).First();
var accessLevelLink = person.ObjectLinks
    .FirstOrDefault(l => l.Relation == "AccessLevel");

if (accessLevelLink != null)
{
    var accessLevel = await client.GetByHrefAsync<AccessLevelInfo>(
        accessLevelLink.Href
    );
    Console.WriteLine($"Access Level: {accessLevel.CommonName}");
}

// Get controller from href
var controller = await client.GetByHrefAsync<ControllerInfo>(
    "/api/f/507f1f77bcf86cd799439011/controllers/507f1f77bcf86cd799439013"
);

cURL

curl -X GET \
  "https://api.acresecurity.cloud/api/f/{folder-key}/people/{person-key}" \
  -H "Authorization: Bearer TOKEN_GOES_HERE"

Use Cases

Use Case Description
Object links Resolve href from ObjectLinkItem
Event data Get objects referenced in events
URL navigation Navigate to known API paths
Deep linking Access objects from stored references

Get By Ids Async

Example in C#

// Returns: IEnumerable<BaseInfo>
var baseInfo = await client.GetByIdsAsync(String keys);

title: “GetByIdsAsync”

Retrieve multiple objects by their unique keys in a single API call. Efficient for batch operations when you know the object IDs.

Method Signature

Task<IEnumerable<BaseInfo>> GetByIdsAsync(
    IEnumerable<string> keys
)

Parameters

Parameter Type Description
keys IEnumerable<string> Collection of object keys to retrieve

Returns

IEnumerable<BaseInfo> - Collection of objects. Use .OfType<T>() to filter to specific types.

Examples

C# Wrapper

// Get multiple objects by ID
var keys = new[] { "507f1f77bcf86cd799439011", "507f1f77bcf86cd799439012" };
var objects = await client.GetByIdsAsync(keys);

// Filter to specific type
var people = objects.OfType<PersonInfo>().ToList();
var controllers = objects.OfType<ControllerInfo>().ToList();

// Process object links
var person = await client.GetPeopleAsync(instance, 0, 1).FirstOrDefault();
var accessLevelIds = person.ObjectLinks
    .Where(l => l.Relation == "AccessLevel")
    .Select(l => l.LinkedObjectKey);

var accessLevels = (await client.GetByIdsAsync(accessLevelIds))
    .OfType<AccessLevelInfo>()
    .ToList();

cURL

curl -X POST \
  "https://api.acresecurity.cloud/api/objectsbyids" \
  -H "Authorization: Bearer TOKEN_GOES_HERE" \
  -H "Content-Type: application/json" \
  -d '["507f1f77bcf86cd799439011", "507f1f77bcf86cd799439012"]'

Use Cases

Use Case Description
Resolve object links Get full objects from ObjectLink references
Batch processing Retrieve multiple objects efficiently
Cache warming Pre-load objects by known keys
Event processing Get linked objects from event data

Performance Tip

Batch requests are more efficient than individual GetByHrefAsync calls. When you have multiple IDs, always use GetByIdsAsync.

Get By Moniker Async

Example in C#

// Returns: T
var item = await client.GetByMonikerAsync<T>(String namespace, String nickname);

title: “GetByMonikerAsync”

Retrieve an object by its unique moniker (namespace + nickname). Monikers provide stable, human-readable identifiers that remain consistent across environments.

Method Signature

Task<T> GetByMonikerAsync<T>(
    string namespace,
    string nickname
) where T : BaseInfo

Parameters

Parameter Type Description
namespace string The moniker namespace
nickname string The moniker nickname

Returns

The object matching the moniker, cast to type T.

Examples

C# Wrapper

// Get event type by moniker
var accessGranted = await client.GetByMonikerAsync<EventTypeInfo>(
    "MercuryServiceEvents",
    "mercury:access-granted"
);

// Get the "Always" schedule
var alwaysSchedule = await client.GetByMonikerAsync<ScheduleInfo>(
    "MercuryServiceEvents",
    "mercury:always-schedule"
);

// Get a service command
var pulseCommand = await client.GetByMonikerAsync<EventTypeInfo>(
    "MercuryServiceCommands",
    "mercury:command-pulse"
);

cURL

curl -X GET \
  "https://api.acresecurity.cloud/api/objectbymoniker?namespace=MercuryServiceEvents&nickname=mercury:access-granted" \
  -H "Authorization: Bearer TOKEN_GOES_HERE"

Common Monikers

Event Types

Namespace Nickname Description
MercuryServiceEvents mercury:access-granted Access granted event
MercuryServiceEvents mercury:access-denied Access denied event
MercuryServiceEvents mercury:door-forced Door forced open
MercuryServiceEvents mercury:door-held Door held open

Schedules

Namespace Nickname Description
MercuryServiceEvents mercury:always-schedule 24/7 schedule
MercuryServiceEvents mercury:never-schedule Never active

Service Commands

Namespace Nickname Description
MercuryServiceCommands mercury:command-pulse Momentary unlock
MercuryServiceCommands mercury:command-lock Lock door
MercuryServiceCommands mercury:command-unlock Unlock door

Why Use Monikers?

Benefit Description
Stable IDs Same moniker works across dev/staging/prod
Human-readable Easier to understand than ObjectIds
System objects Built-in objects have predefined monikers
Version-safe Monikers persist across upgrades