🔑 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

Resident creates code → Calls POST /access-codes
Guest receives code → SMS/Email sent automatically
Security verifies → Calls POST /access-codes/verify (₦5)
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",
  "guestPhone": "+2348012345678",
  "purpose": "Delivery",
  // Optional fields
  "guestEmail": "jane@example.com",
  "peopleCount": 2,
  "entryMode": "DRIVING",
  "validFrom": "2026-03-23T09:00:00Z",
  "validUntil": "2026-03-23T18:00:00Z",
  "usageLimit": 1
}

Response (201 Created)

{
  "success": true,
  "message": "Access code created 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"
}

💡 Note

The access code (e.g., "ABC123") is NOT in the response. It was sent to the guest's phone via SMS/WhatsApp or email.

Request Fields

Field	Required	Description
`guestName`	Yes	Visitor's full name
`guestPhone`	Yes	Phone number for SMS delivery
`purpose`	Yes	Reason for visit
`guestEmail`	No	Email for additional delivery
`peopleCount`	No	Number of people (default: 1)
`entryMode`	No	`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'
  })
});

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
`access_code.used`	Code verified at gate
`access_code.expired`	Code expired
`access_code.revoked`	Code manually revoked

See Webhooks Guide for setup instructions.