API Reference: Visitors & Check-Ins

API Reference: Visitors & Check-Ins

This reference documents all API endpoints related to visitors and check-ins in KyberAccess. Use these endpoints to list, create, update, and manage visitor records programmatically.

For authentication setup and general API usage, see API Authentication & Getting Started.

Visitors Endpoints

List Visitors

Retrieve a paginated list of visitors.

GET /api/v1/visitors

Query Parameters:

Example Request:

curl -X GET "https://api.kyberaccess.com/api/v1/visitors?date=today&status=checked_in" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200 OK):

{
  "data": [
    {
      "id": "vis_abc123",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com",
      "phone": "+1-555-0100",
      "company": "Acme Corp",
      "purpose": "Meeting",
      "host": {
        "id": "usr_xyz789",
        "name": "John Doe",
        "email": "john@company.com",
        "department": "Engineering"
      },
      "status": "checked_in",
      "check_in_time": "2025-01-15T09:30:00Z",
      "check_out_time": null,
      "location": {
        "id": "loc_001",
        "name": "Main Office"
      },
      "id_scanned": true,
      "id_type": "drivers_license",
      "nda_signed": true,
      "watchlist_cleared": true,
      "badge_number": "V-0042",
      "photo_url": "https://api.kyberaccess.com/photos/vis_abc123.jpg",
      "custom_fields": {
        "vehicle_plate": "ABC-1234",
        "laptop_serial": "SN-98765"
      },
      "returning_visitor": true,
      "visit_count": 5,
      "created_at": "2025-01-15T09:30:00Z",
      "updated_at": "2025-01-15T09:30:00Z"
    }
  ],
  "meta": {
    "total": 47,
    "page": 1,
    "per_page": 25,
    "total_pages": 2
  }
}

Get Single Visitor

Retrieve details for a specific visitor.

GET /api/v1/visitors/{visitor_id}

Path Parameters:

Example Request:

curl -X GET "https://api.kyberaccess.com/api/v1/visitors/vis_abc123" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200 OK): Returns the full visitor object as shown above, plus additional details:

{
  "data": {
    "id": "vis_abc123",
    "first_name": "Jane",
    "last_name": "Smith",
    "...all standard fields...",
    "id_photo_url": "https://api.kyberaccess.com/photos/vis_abc123_id.jpg",
    "selfie_url": "https://api.kyberaccess.com/photos/vis_abc123_selfie.jpg",
    "photo_match_score": 0.94,
    "nda_document_url": "https://api.kyberaccess.com/docs/vis_abc123_nda.pdf",
    "screening_results": {
      "sex_offender": "clear",
      "custom_watchlist": "clear",
      "bolo": "clear"
    },
    "visit_history": [
      {
        "date": "2025-01-10",
        "host": "John Doe",
        "purpose": "Meeting"
      },
      {
        "date": "2024-12-20",
        "host": "Jane Manager",
        "purpose": "Delivery"
      }
    ]
  }
}

Create a Pre-Registration

Pre-register an expected visitor.

POST /api/v1/visitors/pre-register

Request Body:

Example Request:

curl -X POST "https://api.kyberaccess.com/api/v1/visitors/pre-register" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Alice",
    "last_name": "Johnson",
    "email": "alice@partner.com",
    "company": "Partner Inc",
    "purpose": "Contract Review",
    "host_id": "usr_xyz789",
    "expected_date": "2025-01-20",
    "expected_time": "10:00",
    "send_invite": true,
    "custom_fields": {
      "vehicle_plate": "XYZ-5678"
    }
  }'

Response (201 Created):

{
  "data": {
    "id": "vis_def456",
    "status": "pre_registered",
    "qr_code_url": "https://api.kyberaccess.com/qr/vis_def456.png",
    "invite_sent": true,
    "...all standard fields..."
  }
}

Check In a Visitor

Programmatically check in a visitor.

POST /api/v1/visitors/{visitor_id}/check-in

For pre-registered visitors, use their existing ID. For walk-ins, create a new visitor first:

POST /api/v1/visitors/check-in

Request Body (Walk-In):

Response (201 Created):

{
  "data": {
    "id": "vis_ghi789",
    "status": "checked_in",
    "check_in_time": "2025-01-15T14:00:00Z",
    "badge_number": "V-0043",
    "host_notified": true,
    "screening_results": {
      "sex_offender": "clear",
      "custom_watchlist": "clear",
      "bolo": "clear"
    }
  }
}

Note: If watchlist screening returns a hit, the response includes a screening_alert field and the visitor status is set to denied (if auto-deny is enabled) or flagged (if manual review is required).

Check Out a Visitor

POST /api/v1/visitors/{visitor_id}/check-out

Request Body (optional):

Response (200 OK):

{
  "data": {
    "id": "vis_abc123",
    "status": "checked_out",
    "check_out_time": "2025-01-15T17:30:00Z",
    "duration_minutes": 480
  }
}

Bulk Check-Out

Check out multiple visitors at once (useful for end-of-day processing).

POST /api/v1/visitors/bulk-check-out

Request Body:

{
  "visitor_ids": ["vis_abc123", "vis_def456", "vis_ghi789"],
  "notes": "End of day bulk check-out"
}

Alternatively, check out all visitors at a location:

{
  "location_id": "loc_001",
  "check_out_all": true
}

Response (200 OK):

{
  "data": {
    "checked_out": 3,
    "failed": 0,
    "details": [
      { "id": "vis_abc123", "status": "checked_out" },
      { "id": "vis_def456", "status": "checked_out" },
      { "id": "vis_ghi789", "status": "checked_out" }
    ]
  }
}

Update a Visitor Record

PATCH /api/v1/visitors/{visitor_id}

Request Body: Include only the fields you want to update.

{
  "phone": "+1-555-0200",
  "company": "New Company Name",
  "custom_fields": {
    "vehicle_plate": "NEW-1234"
  }
}

Response (200 OK): Returns the updated visitor object.

Delete a Visitor Record

DELETE /api/v1/visitors/{visitor_id}

This permanently deletes the visitor record. For GDPR compliance, this also removes all associated photos, documents, and screening results.

Response (204 No Content)

Warning: Deletion is irreversible. Consider using the archive endpoint instead if you need to retain data for compliance.

Check-In Events Endpoints

List Check-In Events

Retrieve a log of all check-in and check-out events.

GET /api/v1/check-in-events

Query Parameters:

Response (200 OK):

{
  "data": [
    {
      "id": "evt_001",
      "event_type": "check_in",
      "visitor_id": "vis_abc123",
      "visitor_name": "Jane Smith",
      "host_name": "John Doe",
      "location": "Main Office",
      "timestamp": "2025-01-15T09:30:00Z",
      "method": "kiosk",
      "badge_printed": true,
      "id_scanned": true,
      "nda_signed": true
    }
  ],
  "meta": { "total": 156, "page": 1, "per_page": 25 }
}

Host Directory Endpoints

List Hosts

GET /api/v1/hosts

Query Parameters:

Response (200 OK):

{
  "data": [
    {
      "id": "usr_xyz789",
      "name": "John Doe",
      "email": "john@company.com",
      "department": "Engineering",
      "location": "Main Office",
      "visitor_count_today": 3
    }
  ]
}

Active Visitors (Real-Time)

Get all currently checked-in visitors.

GET /api/v1/visitors/active

Query Parameters:

This endpoint is optimized for real-time dashboards and digital signage displays.

Emergency Endpoints

Get Evacuation List

Retrieve all currently checked-in visitors for emergency evacuation purposes.

GET /api/v1/emergency/evacuation-list

Response (200 OK):

{
  "data": {
    "location": "Main Office",
    "generated_at": "2025-01-15T14:00:00Z",
    "total_visitors": 12,
    "visitors": [
      {
        "name": "Jane Smith",
        "company": "Acme Corp",
        "host": "John Doe",
        "checked_in_at": "09:30",
        "badge_number": "V-0042",
        "photo_url": "https://api.kyberaccess.com/photos/vis_abc123_thumb.jpg"
      }
    ]
  }
}

Trigger Lockdown

POST /api/v1/emergency/lockdown

Request Body:

{
  "location_id": "loc_001",
  "reason": "Security threat",
  "notify_all": true
}

Warning: This endpoint triggers immediate lockdown and sends emergency notifications to all staff. Use with caution.

Troubleshooting