RFID Tag Registry: Commission, Resolve, and Manage EPC Tags

The RfidTagRegistry is the EPC master catalogue for a tenant. Every physical tag that Dragon Guard needs to recognise — whether on a unit, case, pallet, bin, or fixed asset — must have a corresponding registry entry. Entries are tenant-scoped (keyed by CompanyId), and active EPC uniqueness is enforced with a filtered unique index on (CompanyId, NormalizedEpc), so the same EPC cannot be active twice within one tenant. Deactivation is always logical; no hard-delete route exists.

Data model

Object types

Value	Description
`ITEM_UNIT`	A single sellable or stockable unit — `itemId` required
`CASE`	A case or outer containing individual units — `itemId` required
`PACK`	A pack or inner grouping — `itemId` required
`PALLET`	A full pallet — `itemId` required
`BIN`	A warehouse bin — `currentBinId` required
`LOCATION`	A warehouse location — `currentLocationId` required
`ASSET`	A fixed or tracked asset — no item linkage required

Tag statuses

Value	Meaning
`COMMISSIONED`	Tag has been programmed and registered; not yet in active circulation
`AVAILABLE`	Tag is active and ready for warehouse operations
`VOID`	Tag has been deactivated; `IsActive` is set to `false`

Key fields — `RfidTagDto`

Field	Type	Notes
`id`	`guid`	Surrogate key
`epc`	`string`	Normalised EPC — used for uniqueness enforcement
`rawEpc`	`string`	As-read EPC string from the scanner
`objectType`	`string`	One of the object type values above
`quantity`	`decimal`	Must be ≥ 1 for inventory-bearing types; defaults to `1` for `ITEM_UNIT`
`status`	`string`	`COMMISSIONED`, `AVAILABLE`, or `VOID`
`itemId`	`guid?`	Required for `ITEM_UNIT`, `CASE`, `PACK`, `PALLET`
`itemNo`	`string?`	Item number (denormalised snapshot)
`itemDescription`	`string?`	Item description (denormalised snapshot)
`lotNo`	`string?`	Lot number, if applicable
`serialNo`	`string?`	Serial number, if applicable
`currentLocationId`	`guid?`	Required for `LOCATION`; optional for others
`locationCode`	`string?`	Location code (denormalised snapshot)
`currentBinId`	`guid?`	Required for `BIN`; optional for others
`binCode`	`string?`	Bin code (denormalised snapshot)
`lastSeenAtUtc`	`datetime?`	Updated each time the tag is scanned
`isActive`	`bool`	`false` after deactivation
`createdAtUtc`	`datetime`	Audit timestamp
`createdBy`	`string`	Operator e-mail
`updatedAtUtc`	`datetime?`	Audit timestamp
`updatedBy`	`string?`	Operator e-mail

Tag registry endpoints

GET /api/rfid/tags

Returns a paged list of tags scoped to the calling tenant.

Query parameter	Type	Description
`search`	`string`	Free-text search across EPC, item number, lot, and serial
`item`	`string`	Filter by item number
`lot`	`string`	Filter by lot number
`serial`	`string`	Filter by serial number
`objectType`	`string`	Filter by object type
`status`	`string`	Filter by status value
`activeOnly`	`bool`	Default `true`; set `false` to include voided tags
`page`	`int`	Page number (1-based)
`pageSize`	`int`	Records per page

Get tag by ID

GET /api/rfid/tags/{id}

Returns a single RfidTagDto. Returns 404 if the tag does not exist or belongs to a different tenant.

Resolve EPC

GET /api/rfid/tags/resolve/{epc}

Resolves a raw or normalised EPC string to its item context. This is the primary endpoint used by handhelds during Item Inquiry. Returns an RfidTagResolveDto containing the matched item, quantity, location, and bin.

If corrupted or migrated data has left more than one active row for the same EPC within a tenant, resolution returns resolutionStatus: AMBIGUOUS_DUPLICATE rather than silently choosing one match. Resolve the duplicate via the PATCH or deactivate endpoints before scanning.

Response fields (RfidTagResolveDto):

Field	Type	Notes
`requestedEpc`	`string`	The EPC value supplied in the request
`epc`	`string`	The normalised EPC from the matched registry row
`tagId`	`guid?`	ID of the matched `RfidTagRegistry` row
`assignmentId`	`guid?`	ID of the active tag assignment, if resolved via assignment
`objectType`	`string?`	Object type of the matched tag
`status`	`string?`	Status of the matched tag
`resolutionStatus`	`string`	`RESOLVED`, `NOT_FOUND`, `AMBIGUOUS_DUPLICATE`, or `INACTIVE`
`resolutionSource`	`string`	How the tag was resolved (e.g. `TAG_REGISTRY`, `TAG_ASSIGNMENT`)
`itemId`	`guid?`	Resolved item ID
`itemNo`	`string?`	Resolved item number
`itemDescription`	`string?`	Resolved item description
`quantity`	`decimal?`	Quantity associated with the tag
`currentLocationId`	`guid?`	Current location ID
`locationCode`	`string?`	Current location code
`currentBinId`	`guid?`	Current bin ID
`binCode`	`string?`	Current bin code
`isActive`	`bool`	Whether the matched tag is active
`isResolved`	`bool`	`true` when a matching registry row was found
`message`	`string?`	Human-readable explanation when resolution fails

Create a tag

POST /api/rfid/tags

Commissions a single new EPC tag.

normalizedEpc

string

required

The canonical EPC value used for uniqueness checks. Must be unique among active tags in the tenant.

rawEpc

string

The raw as-read EPC string. Defaults to normalizedEpc if omitted.

objectType

string

required

Object type of the physical entity bearing this tag. One of ITEM_UNIT, CASE, PACK, PALLET, BIN, LOCATION, ASSET.

itemId

guid

Required when objectType is ITEM_UNIT, CASE, PACK, or PALLET. Must reference an item that belongs to the calling tenant.

quantity

decimal

Quantity of the item represented by this tag. Defaults to 1 for ITEM_UNIT. Must be ≥ 1 for all inventory-bearing types.

status

string

Initial status. Defaults to COMMISSIONED if omitted. Accepted values: COMMISSIONED, AVAILABLE.

currentLocationId

guid

ID of the warehouse location where the tag currently resides. Required when objectType is LOCATION.

currentBinId

guid

ID of the bin where the tag currently resides. Required when objectType is BIN.

lastSeenAtUtc

datetime

Optional timestamp of the last known physical read. Omit to let the system set this on the first scan event.

Returns 201 Created with the full RfidTagDto. Returns 409 Conflict if an active tag with the same EPC already exists for the tenant.

Bulk import

POST /api/rfid/tags/bulk

Imports a batch of tags in a single request. Accepts an RfidBulkImportDto body and returns an RfidBulkImportResultDto with per-line create, update, and error counts. Useful when commissioning large tag batches printed from ZPL label jobs.

Body field	Type	Description
`batchReferenceNo`	`string?`	Optional reference label for this import batch
`remarks`	`string?`	Free-text notes
`continueOnError`	`bool`	Default `true` — skip failing rows rather than aborting the entire batch
`allowUpdates`	`bool`	When `true`, update existing active tags instead of returning a conflict
`items`	`array`	Array of `RfidBulkImportLineDto` tag records (see fields below)

Each element in items mirrors CreateRfidTagDto with an additional optional index field for error reporting.

Update a tag (partial)

PATCH /api/rfid/tags/{id}

Applies a partial update to a tag using UpdateRfidTagDto. Supports changes to EPC, status, quantity, item linkage, location, bin, and lastSeenAtUtc. Setting status to VOID automatically sets IsActive = false; any other valid status reactivates the tag. UpdateRfidTagDto also exposes explicit clear flags — set the corresponding bool to true to null-out optional fields:

Clear flag	Clears field
`clearItemId`	Sets `ItemId` to `null`
`clearCurrentLocationId`	Sets `CurrentLocationId` to `null`
`clearCurrentBinId`	Sets `CurrentBinId` to `null`
`clearLastSeenAtUtc`	Sets `LastSeenAtUtc` to `null`

Update a tag (full)

PUT /api/rfid/tags/{id}

Alias of PATCH using the same UpdateRfidTagDto payload. Provided for client compatibility.

Deactivate a tag

PUT /api/rfid/tags/{id}/deactivate

Logically deactivates a tag by setting Status = VOID and IsActive = false. The tag record is retained for audit and re-commissioning review. Returns 404 if the tag does not exist in the tenant.

Tag assignment endpoints

Tag assignments link a registry entry to a specific document, item, lot, serial, package, location, or bin for a defined time window. The RfidTagAssignmentsController exposes the following routes under api/rfid/tag-assignments.

List assignments

GET /api/rfid/tag-assignments

Returns a paged list of assignments scoped to the calling tenant.

Query parameter	Type	Description
`rfidTagRegistryId`	`guid`	Filter by registry tag ID
`assignmentType`	`string`	Filter by assignment type
`itemId`	`guid`	Filter by item ID
`documentType`	`string`	Filter by document type
`documentNo`	`string`	Filter by document number
`isActive`	`bool`	Filter by active/inactive status
`effectiveAtUtc`	`datetime`	Return only assignments effective at this point in time
`page`	`int`	Page number (1-based)
`pageSize`	`int`	Records per page

Get assignment by ID

GET /api/rfid/tag-assignments/{id}

Returns a single RfidTagAssignmentDto. Returns 404 if not found or belonging to a different tenant.

Create assignment

POST /api/rfid/tag-assignments

Creates a new tag assignment. Returns 201 Created with the saved RfidTagAssignmentDto, or 409 Conflict if an active conflicting assignment already exists. Key request fields (CreateRfidTagAssignmentDto):

Field	Type	Required	Description
`rfidTagRegistryId`	`guid`	✓	The registry tag being assigned
`assignmentType`	`string`	✓	Type of assignment (e.g. `DOCUMENT`, `LOCATION`, `ITEM`)
`itemId`	`guid?`		Item linked to this assignment
`lotNo`	`string?`		Lot number
`serialNo`	`string?`		Serial number
`packageCode`	`string?`		Package code
`documentType`	`string?`		Document type (e.g. `RECEIPT`)
`documentNo`	`string?`		Document number
`documentLineNo`	`string?`		Document line number
`locationId`	`guid?`		Warehouse location ID
`binId`	`guid?`		Bin ID
`quantity`	`decimal`	✓	Quantity for this assignment
`source`	`string`	✓	How the assignment was created (e.g. `MANUAL`, `SYSTEM`)
`effectiveFromUtc`	`datetime?`		Start of effective window; defaults to now if omitted
`effectiveToUtc`	`datetime?`		End of effective window; `null` means open-ended
`notes`	`string?`		Free-text notes

Update assignment

PUT /api/rfid/tag-assignments/{id}

Replaces the mutable fields of an existing assignment with an UpdateRfidTagAssignmentDto body. Returns 404 if the assignment is not found.

Deactivate assignment

PUT /api/rfid/tag-assignments/{id}/deactivate

Logically deactivates an assignment. Returns 204 No Content on success, 404 if not found.

Label print endpoint

Dragon Guard can generate a ZPL label string for a Zebra RFID printer. The ZPL includes ^RFW commands to program the RFID chip during the print pass, so the print and encode steps happen in a single pass through the Zebra printer.

POST /api/rfid/print/label

epc

string

EPC to encode. Provide either epc or tagId.

tagId

guid

ID of the RfidTagRegistry row to look up the EPC from. Provide either tagId or epc.

copies

int

Number of label copies embedded in the ZPL (^PQ). Range 1–99. Defaults to 1.

darkness

int

Print darkness (^MD). Range 0–30. Defaults to 15.

Response (PrintRfidLabelResponseDto):

Field	Type	Description
`success`	`bool`	Whether the ZPL was generated successfully
`message`	`string`	Human-readable outcome message
`zplString`	`string`	Complete ZPL string — send to the Zebra printer via TCP port 9100
`epc`	`string?`	The EPC encoded in the label
`itemId`	`string?`	Item ID snapshot
`objectType`	`string?`	Object type snapshot
`copies`	`int`	Copy count embedded in the ZPL
`generatedAtUtc`	`datetime`	UTC timestamp of generation

Business rules

itemId is required for object types ITEM_UNIT, CASE, PACK, and PALLET. Creating any of these without an item reference will return 400 Bad Request.

BIN tags must include a currentBinId. LOCATION tags must include a currentLocationId. Submitting without the matching reference will return 400 Bad Request.

Active EPC uniqueness — only one active row may exist per (CompanyId, NormalizedEpc). Attempting to create a duplicate returns 409 Conflict.
Quantity floor — quantity must be ≥ 1 for all inventory-bearing types (ITEM_UNIT, CASE, PACK, PALLET).
No hard delete — deactivation is the only way to retire a tag. Historical (inactive) rows remain for audit.
Tenant isolation — CompanyId is resolved from the JWT; request bodies cannot override it.

Examples

Commission a tag

curl -X POST https://api.dragonguard.io/api/rfid/tags \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "normalizedEpc": "3034257BF400B80000000001",
    "rawEpc": "3034257BF400B80000000001",
    "objectType": "ITEM_UNIT",
    "itemId": "a1b2c3d4-0000-0000-0000-000000000001",
    "quantity": 1,
    "status": "AVAILABLE",
    "currentLocationId": "f0e1d2c3-0000-0000-0000-000000000010"
  }'

{
  "id": "9e8f7a6b-0000-0000-0000-000000000099",
  "epc": "3034257BF400B80000000001",
  "rawEpc": "3034257BF400B80000000001",
  "objectType": "ITEM_UNIT",
  "itemId": "a1b2c3d4-0000-0000-0000-000000000001",
  "itemNo": "ITEM-001",
  "itemDescription": "Widget A",
  "quantity": 1.0,
  "status": "AVAILABLE",
  "currentLocationId": "f0e1d2c3-0000-0000-0000-000000000010",
  "locationCode": "ZONE-A",
  "currentBinId": null,
  "binCode": null,
  "lastSeenAtUtc": null,
  "isActive": true,
  "createdAtUtc": "2025-01-15T09:00:00Z",
  "createdBy": "[email protected]"
}

Resolve an EPC

curl https://api.dragonguard.io/api/rfid/tags/resolve/3034257BF400B80000000001 \
  -H "Authorization: Bearer <token>"

{
  "requestedEpc": "3034257BF400B80000000001",
  "epc": "3034257BF400B80000000001",
  "tagId": "9e8f7a6b-0000-0000-0000-000000000099",
  "assignmentId": null,
  "objectType": "ITEM_UNIT",
  "status": "AVAILABLE",
  "resolutionStatus": "RESOLVED",
  "resolutionSource": "TAG_REGISTRY",
  "itemId": "a1b2c3d4-0000-0000-0000-000000000001",
  "itemNo": "ITEM-001",
  "itemDescription": "Widget A",
  "quantity": 1.0,
  "currentLocationId": "f0e1d2c3-0000-0000-0000-000000000010",
  "locationCode": "ZONE-A",
  "currentBinId": null,
  "binCode": null,
  "isActive": true,
  "isResolved": true,
  "message": null
}

Get Started

Authentication

Core Modules

RFID

ERP Integration

Supreme Admin

Platform

RFID Tag Registry: Commission, Resolve, and Manage EPC Tags

Data model

Object types

Tag statuses

Key fields — `RfidTagDto`

Tag registry endpoints

Get tag by ID

Resolve EPC

Create a tag

Bulk import

Update a tag (partial)

Update a tag (full)

Deactivate a tag

Tag assignment endpoints

List assignments

Get assignment by ID

Create assignment

Update assignment

Deactivate assignment

Label print endpoint

Business rules

Examples

Commission a tag

Resolve an EPC

Build docs developers (and LLMs) love

Get Started

Authentication

Core Modules

RFID

ERP Integration

Supreme Admin

Platform

Documentation Index

​Data model

​Object types

​Tag statuses

​Key fields — RfidTagDto

​Tag registry endpoints

​List tags

​Get tag by ID

​Resolve EPC

​Create a tag

​Bulk import

​Update a tag (partial)

​Update a tag (full)

​Deactivate a tag

​Tag assignment endpoints

​List assignments

​Get assignment by ID

​Create assignment

​Update assignment

​Deactivate assignment

​Label print endpoint

​Business rules

​Examples

​Commission a tag

​Resolve an EPC

Build docs developers (and LLMs) love

Data model

Object types

Tag statuses

Key fields — `RfidTagDto`

Tag registry endpoints

List tags

Get tag by ID

Resolve EPC

Create a tag

Bulk import

Update a tag (partial)

Update a tag (full)

Deactivate a tag

Tag assignment endpoints

List assignments

Get assignment by ID

Create assignment

Update assignment

Deactivate assignment

Label print endpoint

Business rules

Examples

Commission a tag

Resolve an EPC