Add a Card Format

Overview

Card formats define how the system interprets the data encoded on access cards. They specify the bit structure, facility codes, card number positions, and parity bits that allow controllers to decode and validate credentials. Without proper card format configuration, cards cannot be recognized by the access control system.

Key Concepts

Concept Description
Bit Length Total number of bits in the card data (e.g., 26-bit, 34-bit, 37-bit)
Facility Code Site identifier that can be used to filter valid cards
Card Number Unique identifier for the individual card
Parity Bits Error-checking bits used to validate card data integrity
Issue Code Optional additional identifier for card versions

Common Card Format Standards

Format Bits Facility Code Bits Card Number Bits Description
Standard 26-bit 26 8 16 Most common format
34-bit 34 16 16 Extended facility code range
37-bit HID 37 13 20 HID Corporate 1000 format
37-bit with FC 37 16 19 Higher card number capacity
Corporate 1000 35 12 20 HID proprietary format

Prerequisites

Before creating card formats, ensure you have:

  • ✅ Valid API credentials with administrative permissions
  • ✅ Understanding of your physical card specifications from the card vendor
  • ✅ At least one controller to assign the format to

Card Format Properties

Property Type Description
NumberOfBits int Total bit length of the card format
FacilityCodeStartingAt int Bit position where facility code begins (0-based)
FacilityCodeLength int Number of bits for facility code
FacilityCode int? Expected facility code value (null to accept any)
CardNumberStartingAt int Bit position where card number begins
CardNumberLength int Number of bits for card number
IssueCodeStartingAt int Bit position where issue code begins
IssueCodeLength int Number of bits for issue code
EvenParityBitsStartingAt int Start position for even parity check
EvenParityBitsLength int Number of bits covered by even parity
OddParityBitsStartingAt int Start position for odd parity check
OddParityBitsLength int Number of bits covered by odd parity
Offset int Bit offset for card data
MagneticFormat bool True if format is for magnetic stripe cards
ReverseBitStream bool Reverse the bit order of card data
ReverseBytes bool Reverse the byte order of card data

C# Examples

Create a Standard 26-Bit Wiegand Format

using Feenics.Keep.WebApi.Wrapper;
using Feenics.Keep.WebApi.Model;

// Create a standard 26-bit Wiegand card format
var cardFormat = await client.AddCardFormatAsync(currentInstance, new CardFormatInfo
{
    CommonName = "Standard 26-Bit Wiegand",
    
    // Total bits
    NumberOfBits = 26,
    
    // Facility code: bits 1-8 (8 bits = 256 possible values)
    FacilityCodeStartingAt = 1,
    FacilityCodeLength = 8,
    FacilityCode = 45,  // Only accept cards with facility code 45
    
    // Card number: bits 9-24 (16 bits = 65,536 possible values)
    CardNumberStartingAt = 9,
    CardNumberLength = 16,
    
    // Parity bits for error checking
    // Even parity covers first half (bits 0-12)
    EvenParityBitsStartingAt = 0,
    EvenParityBitsLength = 13,
    // Odd parity covers second half (bits 13-25)
    OddParityBitsStartingAt = 13,
    OddParityBitsLength = 13,
    
    // No issue code
    IssueCodeStartingAt = 0,
    IssueCodeLength = 0,
    
    // Standard settings
    Offset = 0,
    MagneticFormat = false,
    ReverseBitStream = false,
    ReverseBytes = false
});

Console.WriteLine($"Created card format: {cardFormat.CommonName} (Key: {cardFormat.Key})");

Create a 34-Bit Format (Extended Facility Code)

// 34-bit format with extended facility code range
var extendedFormat = await client.AddCardFormatAsync(currentInstance, new CardFormatInfo
{
    CommonName = "34-Bit Extended Format",
    NumberOfBits = 34,
    
    // Extended facility code: 16 bits
    FacilityCodeStartingAt = 1,
    FacilityCodeLength = 16,
    FacilityCode = null,  // Accept any facility code
    
    // Card number: 16 bits
    CardNumberStartingAt = 17,
    CardNumberLength = 16,
    
    // Parity
    EvenParityBitsStartingAt = 0,
    EvenParityBitsLength = 17,
    OddParityBitsStartingAt = 17,
    OddParityBitsLength = 17,
    
    IssueCodeStartingAt = 0,
    IssueCodeLength = 0,
    Offset = 0,
    MagneticFormat = false
});

Create a Format Without Facility Code

// Some systems don't use facility codes
var noFacilityFormat = await client.AddCardFormatAsync(currentInstance, new CardFormatInfo
{
    CommonName = "Card Number Only Format",
    NumberOfBits = 26,
    
    // No facility code
    FacilityCodeStartingAt = 0,
    FacilityCodeLength = 0,
    FacilityCode = null,
    
    // Full card number field
    CardNumberStartingAt = 1,
    CardNumberLength = 24,
    
    // Standard parity
    EvenParityBitsStartingAt = 0,
    EvenParityBitsLength = 13,
    OddParityBitsStartingAt = 13,
    OddParityBitsLength = 13,
    
    IssueCodeStartingAt = 0,
    IssueCodeLength = 0
});

Assign Card Format to a Controller

// Card formats must be assigned to controllers to be active
// First, get the controller
var controller = (await client.GetControllersAsync(currentInstance))
    .OfType<MercuryControllerInfo>()
    .First();

// Assign the card format to the controller
await client.AddCardFormatToControllerAsync(controller, cardFormat);
Console.WriteLine($"Assigned '{cardFormat.CommonName}' to controller '{controller.CommonName}'");

List Card Formats on a Controller

// Get all card formats assigned to a specific controller
var formats = await client.GetCardFormatsForControllerAsync(controller);

Console.WriteLine($"Card formats on {controller.CommonName}:");
foreach (var format in formats)
{
    Console.WriteLine($"  - {format.CommonName}: {format.NumberOfBits}-bit, FC: {format.FacilityCode ?? 0}");
}

cURL Examples

Create a Card Format

ACCESS_TOKEN="your-access-token"
INSTANCE_KEY="your-instance-key"

curl -X POST \
  "https://api.us.acresecurity.cloud/api/f/${INSTANCE_KEY}/cardformats" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "$type": "Feenics.Keep.WebApi.Model.CardFormatInfo, Feenics.Keep.WebApi.Model",
    "CommonName": "Standard 26-Bit Wiegand",
    "NumberOfBits": 26,
    "FacilityCodeStartingAt": 1,
    "FacilityCodeLength": 8,
    "FacilityCode": 45,
    "CardNumberStartingAt": 9,
    "CardNumberLength": 16,
    "IssueCodeStartingAt": 0,
    "IssueCodeLength": 0,
    "EvenParityBitsStartingAt": 0,
    "EvenParityBitsLength": 13,
    "OddParityBitsStartingAt": 13,
    "OddParityBitsLength": 13,
    "Offset": 0,
    "MagneticFormat": false,
    "ReverseBitStream": false,
    "ReverseBytes": false
  }'

Assign Card Format to Controller

CONTROLLER_KEY="your-controller-key"
CARDFORMAT_KEY="your-cardformat-key"

curl -X PUT \
  "https://api.us.acresecurity.cloud/api/f/${INSTANCE_KEY}/controllers/${CONTROLLER_KEY}/cardformats/${CARDFORMAT_KEY}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json"

List Card Formats in Instance

curl -X GET \
  "https://api.us.acresecurity.cloud/api/f/${INSTANCE_KEY}/cardformats" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Troubleshooting

Issue Possible Cause Solution
Cards not recognized Wrong bit length Verify card specifications from vendor
Wrong card number displayed Incorrect CardNumberStartingAt Check bit position documentation
All cards rejected Parity bit misconfiguration Verify even/odd parity positions and lengths
Only some cards work Facility code mismatch Set FacilityCode to null or correct value
Format won’t save Invalid bit configuration Ensure bit positions don’t exceed NumberOfBits
Controller won’t accept format Too many formats on controller Remove unused formats from controller

Updating CardFormats may require a Controller DB Push.