External NFC Visit

Overview

The External NFC Visit API enables third-party applications to integrate with the Buzzin access control system. This API allows residents to gain entry and exit from their property by scanning NFC tags and submitting their credentials through your application.

Entry Flow

Stage 1: NFC Tag Scan

When a resident scans an NFC tag at the entrance gate, they receive the following data:

{
  "visitType": "nfc",
  "deviceSecret": "abc123xyz789..."
}

The deviceSecret is a unique identifier that associates the visit with the specific entrance device.

Stage 2: Prepare Entry Request

Your application must collect the following information from the resident and construct the API request:

Required Fields:

documentId - The resident's document ID (e.g., Emirates ID)

Either phone OR email - At least one contact method is required

Request Payload Structure:

{
  "visitType": "externalNfc",
  "deviceSecret": "abc123xyz789...",
  "documentId": "784-1234-5678901-2",
  "phone": "+971501234567"
}

{
  "visitType": "externalNfc",
  "deviceSecret": "abc123xyz789...",
  "documentId": "784-1234-5678901-2",
  "email": "resident@example.com"
}

Stage 3: Submit Entry Request

Send the prepared payload to the Buzzin API endpoint:

Endpoint: POST https://api.buzz-in.co/visits

Headers:

Content-Type: application/json

Example Request:

Success Response:

{
  "responseCode": "entryEventCreated"
}

Upon successful validation, the entrance gate will automatically open, granting the resident access to the property.

Exit Flow

Stage 1: NFC Tag Scan

When a resident scans an NFC tag at the exit gate, they receive the same data structure:

{
  "visitType": "nfc",
  "deviceSecret": "def456uvw123..."
}

Stage 2: Prepare Exit Request

Construct the exit request using the same structure as the entry request:

Request Payload Structure:

{
  "visitType": "externalNfc",
  "deviceSecret": "def456uvw123...",
  "documentId": "784-1234-5678901-2",
  "phone": "+971501234567"
}

Stage 3: Submit Exit Request

Send the prepared payload to the same API endpoint:

Endpoint: POST https://api.buzz-in.co/visits

Example Request:

Success Response:

{
  "responseCode": "leaveEventCreated",
  "leaveEvent": {
    "duration": 7200000,
    ...
  }
}

The system automatically detects that the resident has an active entry event and processes this as an exit, opening the gate to allow departure.

Field Specifications

Required Fields

Field	Type	Description
`visitType`	string	Must be set to `"externalNfc"`
`deviceSecret`	string	Obtained from the NFC tag scan
`documentId`	string	Resident's document ID (Emirates ID, passport, etc.)

Conditional Fields (At least one required)

Field	Type	Description
`phone`	string	Resident's phone number (international format recommended)
`email`	string	Resident's email address

Response Codes

Response Code	Description
`entryEventCreated`	Entry access granted - gate will open
`leaveEventCreated`	Exit access granted - gate will open

Error Handling

Common Error Responses

Missing Document ID:

{
  "name": "BadRequest",
  "message": "Document ID is required",
  "code": 400
}

Missing Contact Information:

{
  "name": "BadRequest",
  "message": "Email or phone is required",
  "code": 400
}

User Not Found:

{
  "name": "BadRequest",
  "message": "User doesn't exists",
  "code": 400
}

No Unit Association:

{
  "name": "BadRequest",
  "message": "User doesn't have unit in the building",
  "code": 400
}

Implementation Notes

Automatic Entry/Exit Detection: The system automatically determines whether the request is for entry or exit based on the resident's current status in the building.

Same Credentials: Use the same documentId and contact information (phone or email) for both entry and exit requests.

Device Secret: The deviceSecret obtained from the NFC scan must be included in the API request to validate the physical presence at the gate.

Contact Method Consistency: For best results, use the same contact method (phone or email) that was used during the resident's registration.

International Phone Format: When using phone numbers, include the country code (e.g., +971501234567).

Quick Integration Checklist

Implement NFC scanning capability in your application

Extract deviceSecret from scanned NFC tag

Collect documentId from the resident

Collect either phone or email from the resident

Construct request payload with visitType: "externalNfc"

Send POST request to https://api.buzz-in.co/visits

Handle success response to confirm gate operation

Implement error handling for all error scenarios

Test both entry and exit flows

Support

For technical support or additional information, please contact the Buzzin integration team.

Overview#

Entry Flow#

Stage 1: NFC Tag Scan#

Stage 2: Prepare Entry Request#

Stage 3: Submit Entry Request#

Exit Flow#

Stage 1: NFC Tag Scan#

Stage 2: Prepare Exit Request#

Stage 3: Submit Exit Request#

Field Specifications#

Required Fields#

Conditional Fields (At least one required)#

Response Codes#

Error Handling#

Common Error Responses#

Implementation Notes#

Quick Integration Checklist#

Support#

Overview

Entry Flow

Stage 1: NFC Tag Scan

Stage 2: Prepare Entry Request

Stage 3: Submit Entry Request

Exit Flow

Stage 1: NFC Tag Scan

Stage 2: Prepare Exit Request

Stage 3: Submit Exit Request

Field Specifications

Required Fields

Conditional Fields (At least one required)

Response Codes

Error Handling

Common Error Responses

Implementation Notes

Quick Integration Checklist

Support