🔑 Access Codes

Generate and verify visitor access codes for gated communities. Perfect for property management systems and security applications.

Pricing

Operation Cost
Create access code ₦5 per code
Verify access code ₦5 per verification
List / Get access codes Free
Revoke access code Free
⚠️ Security Note

The access code is NOT returned in the API response. It is automatically sent to the guest via SMS, email, or WhatsApp. This prevents interception.

How It Works

  1. Resident creates code → Calls POST /v1/access-codes
  2. Guest receives code → SMS/Email sent automatically
  3. Security verifies → Calls POST /v1/access-codes/verify (₦5)
  4. Entry granted → Guest details returned for verification

Create Access Code

Create a code for a visitor. The code is sent directly to the guest - you will NOT receive it in the response.

POST /v1/access-codes
// Request
 {
   "guestName": "Jane Smith",
   "deliveryMethod": "sms",        // "email" | "sms" | "whatsapp"
   "guestPhone": "+2348012345678", // required for sms/whatsapp
   "purpose": "Delivery",
   "peopleCount": 2,
   "entryMode": "DRIVING",
   // Optional fields
   "guestEmail": "jane@example.com", // required when deliveryMethod = "email"
   "validFrom": "2026-03-23T09:00:00Z",
   "validUntil": "2026-03-23T18:00:00Z",
   "usageLimit": 1,
   "deliveryMessageTemplate": "Your code for {purpose} is {code}, valid until {validUntil}."
 }
Response (201 Created)
{
   "success": true,
   "message": "Access code created and delivered successfully",
   "id": "ac_xyz123",
   "createdAt": "2026-03-23T10:30:00Z",
   "validFrom": "2026-03-23T09:00:00Z",
   "validUntil": "2026-03-23T18:00:00Z",
   "usageLimit": 1,
   "status": "ACTIVE",
   "deliveryMethod": "sms",
   "deliveredAt": "2026-03-23T10:30:00Z"
 }
💡 Note

The access code (e.g., "ABC123") is NOT in the response — we deliver it directly to the guest over the channel you choose. You are only charged when delivery succeeds; if it fails, the code is not created, you are not charged, and an access_code.delivery_failed webhook fires. Pricing per channel: email ₦5, WhatsApp ₦8, SMS ₦10.

Request Fields

Field Required Description
guestName Yes Visitor's full name
deliveryMethod Yes email, sms, or whatsapp
guestPhone Conditional Required for sms/whatsapp delivery
purpose Yes Reason for visit
guestEmail Conditional Required for email delivery
deliveryMessageTemplate No Custom email/SMS copy with {code} {purpose} {guestName} {validUntil} placeholders (WhatsApp uses the approved template)
peopleCount Yes Number of people expected (1-50)
entryMode Yes DRIVING, WALK_IN, or DISPATCH
validFrom No When code becomes valid (default: now)
validUntil No When code expires (default: 24 hours)
usageLimit No Max uses (null = unlimited)

Verify Access Code

Verify a code at the security gate. Costs ₦5 per verification. Returns guest details for security to confirm identity.

POST /v1/access-codes/verify
{
  "code": "ABC123",
  "markAsUsed": true  // Increment usage count
}
Response (Valid Code)
{
  "success": true,
  "valid": true,
  "message": "Access code is valid",
  "guestName": "Jane Smith",
  "guestPhone": "+2348012345678",
  "purpose": "Delivery",
  "entryMode": "DRIVING",
  "peopleCount": 2,
  "usageCount": 1,
  "usageLimit": null,
  "validFrom": "2026-03-23T09:00:00Z",
  "validUntil": "2026-03-23T18:00:00Z"
}
💡 Security

The access code itself is NOT returned in the verify response. Only the guest details needed for security verification.

Response (Invalid/Expired Code)
{
  "success": true,
  "valid": false,
  "message": "Access code has expired",
  "reason": "EXPIRED"
}

Invalid Reasons

Reason Description
Code not found The code doesn't exist
EXPIRED Past validUntil time
USED Usage limit reached
REVOKED Code was manually revoked
NOT_YET_VALID validFrom is in the future

Code Example

Node.js / JavaScript
// Create an access code
const response = await fetch('https://api-developers.venshack.io/v1/access-codes', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vk_prod_xxxxxxxxxxxxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    guestName: 'Jane Smith',
    guestPhone: '+2348012345678',
    purpose: 'Delivery',
    peopleCount: 1,
    entryMode: 'WALK_IN'
  })
});

const result = await response.json();
console.log(`Access code created: ${result.id}`);
console.log(`Code sent to guest via SMS`);
Verify at security gate
// Verify code when guest arrives
const verify = await fetch('https://api-developers.venshack.io/v1/access-codes/verify', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vk_prod_xxxxxxxxxxxxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    code: 'ABC123',
    markAsUsed: true
  })
});

const guest = await verify.json();

if (guest.valid) {
  console.log(`Welcome ${guest.guestName}!`);
  console.log(`Purpose: ${guest.purpose}`);
  console.log(`People: ${guest.peopleCount}`);
} else {
  console.log(`Access denied: ${guest.reason}`);
}

Webhooks

Receive notifications when access code events happen:

Event Description
access_code.created New code generated (fires with access_code.delivered)
access_code.delivered Code delivered to the guest
access_code.delivery_failed Delivery failed (code not created, not charged)
access_code.used Code verified at gate
access_code.revoked Code manually revoked

See Webhooks Guide for how to receive and verify webhook events.