Core Concepts

Card Credentials

Physical access cards - the most common credential type in 5 minutes

5 mins
Beginner

Related API Endpoints

POST Create credential PUT Update credential

Physical access cards that people scan at card readers. The most common and reliable type of credential in DoorFlow.

What Are Card Credentials?

Physical cards containing embedded chips or magnetic strips that are scanned at card readers to unlock doors.

Technology

•
Proximity cards (125 kHz)
•
Smart cards (13.56 MHz)
•
Wiegand format cards
•
Various card formats (26-bit, 34-bit, etc.)

When to Use Cards

Best for

•
Permanent employees
•
Long-term contractors
•
Anyone needing reliable, always-available access
•
Environments where phones might be prohibited
•
High-traffic doors (fastest credential type)

Not ideal for

•
Short-term visitors (logistics of physical card distribution)
•
Remote employees who rarely visit the office
•
Situations requiring instant credential provisioning

Checking Your Credential Types

Before creating card credentials, verify your account supports them:

Request:

bash 
curl -X GET "https://api.doorflow.com/api/3/credential_types" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

json 
{
  "credential_types": [
    {
      "id": 5,
      "name": "Card",
      "format": "numeric",
      "description": "Physical access card"
    }
  ]
}

Note the id - you'll use this when creating credentials (typically 5 for cards).

Creating Card Credentials

Request:

bash 
curl -X POST "https://api.doorflow.com/api/3/people/12345/credentials" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "person_credential": {
      "credential_type_id": 5,
      "value": "1234567890",
      "enabled": true
    }
  }'

Parameters

•
credential_type_id: ID for "Card" from your credential types (typically 5)
•
value: The card number (facility code + card number combined)
  • Format varies by card type
  • Usually 8-10 digits
  • Must match the physical card number
•
Format varies by card type
•
Usually 8-10 digits
•
Must match the physical card number
•
enabled: Set to true to activate immediately

Response:

json 
{
  "id": "cred_abc123",
  "credential_type_id": 5,
  "value": "1234567890",
  "enabled": true,
  "person_id": 12345,
  "created_at": "2024-01-15T14:25:00Z"
}

Understanding Card Number Formats

Different card technologies use different number formats:

26-bit Wiegand (most common)

•
Format: FFFCCCCC (3-digit facility code + 5-digit card number)
•
Example: Facility 001, Card 12345 → stored as 00112345
•
Range: 0 to 16,777,215

34-bit Wiegand

•
Larger facility codes and card numbers
•
Example: 012345 67890
•
Used for larger organizations

Finding the card number

•
Usually printed on the physical card
•
Can be read with card reader programming tools
•
May need conversion from decimal to facility+card format

Example:

Physical card prints: "001 - 12345"
API value: "00112345" (combined, no spaces)

Managing Card Credentials

Disabling a Card

Temporarily disable without deleting (maintains audit trail):

bash 
curl -X PUT "https://api.doorflow.com/api/3/people/12345/credentials/cred_abc123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "person_credential": {
      "enabled": false
    }
  }'

Use cases

•
Lost card (disable until found or replaced)
•
Suspended employee (temporary access removal)
•
Card malfunction (disable and issue replacement)

Re-enabling a Card

bash 
curl -X PUT "https://api.doorflow.com/api/3/people/12345/credentials/cred_abc123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "person_credential": {
      "enabled": true
    }
  }'

Deleting a Card

Permanently remove:

bash 
curl -X DELETE "https://api.doorflow.com/api/3/people/12345/credentials/cred_abc123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Warning: Deleting removes the credential from audit trail. Prefer disabling unless you have a specific reason to delete.

Listing a Person's Credentials

See all credentials for a person:

bash 
curl -X GET "https://api.doorflow.com/api/3/people/12345/credentials" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

json 
{
  "credentials": [
    {
      "id": "cred_abc123",
      "credential_type_id": 5,
      "credential_type_name": "Card",
      "value": "1234567890",
      "enabled": true,
      "person_id": 12345,
      "created_at": "2024-01-15T14:25:00Z"
    }
  ]
}

Best Practices

Issue backup credentials: Give users both a card AND a PIN in case they forget their card.

bash 
# Issue card
POST /api/3/people/12345/credentials
{
  "credential_type_id": 5,
  "value": "1234567890",
  "enabled": true
}

# Issue backup PIN
POST /api/3/people/12345/credentials
{
  "credential_type_id": 6,
  "value": "******",
  "enabled": true
}

Track physical cards

•
Maintain inventory of which cards are issued
•
Track card serial numbers separate from credential numbers
•
Know which cards are available for new hires

Collect cards on termination

•
Include in offboarding checklist
•
Disable card immediately in DoorFlow
•
Physically collect card from employee

Disable lost cards immediately

•
Set enabled: false instead of deleting
•
Maintains audit trail of when card was active
•
Can re-enable if card is found

Test new cards

•
Always test card at a door before giving to user
•
Verify card number was entered correctly
•
Check that person has proper group memberships

Common Questions

Can I change a card number after creation?

A: No. Credential values are immutable. To change a card number, disable the old credential and create a new one.

What happens if I enter the wrong card number?

A: The card won't work at doors. Disable the incorrect credential and create a new one with the correct number.

Can two people have the same card number?

A: No. DoorFlow prevents duplicate credential values. Each card number must be unique.

What happens if a person has both an enabled and disabled card?

A: The enabled card works normally. The disabled card won't grant access but remains in the system for audit purposes.

How do I replace a lost card?

A: Disable the old card credential, obtain a new physical card with a different number, and create a new credential with the new card number.

Can I reuse a card number after deleting it?

A: Yes, but only after deletion. If disabled, the number is still in use. However, prefer disabling over deletion for audit trail purposes.

Quick Reference

List credential types:

bash 
GET /api/3/credential_types

Create card:

bash 
POST /api/3/people/{person_id}/credentials
Body: {
  "credential_type_id": 5,
  "value": "card_number",
  "enabled": true
}

List person's credentials:

bash 
GET /api/3/people/{person_id}/credentials

Disable card:

bash 
PUT /api/3/people/{person_id}/credentials/{credential_id}
Body: { "enabled": false }

Delete card:

bash 
DELETE /api/3/people/{person_id}/credentials/{credential_id}

Required OAuth scope: account.person (write) or account.person.readonly (read)

Next Steps

Need different credential types?

  • [PIN Credentials] - Keypad codes for backup access
  • [Mobile Credentials] - Smartphone-based access

Choose the right credential

•
[Credential Comparison] - Compare all types and get recommendations

See it in action

•
[Common Workflows] - Complete examples including card issuance
•
[Events and Audit Trail] - Track which cards are being used

On this page