Skip to main content

​
Understanding Whitelist Architecture

The Arqqin Parking Management API uses a reference-based architecture for managing vehicle whitelists:

Reference-Based Design

Group multiple vehicles under any external entity using generic reference IDs.

Location-Scoped

Each whitelist entry is specific to a particular parking location.

No PII Required

Reference IDs can represent any external entity without exposing personal information.

Flexible Grouping

Group vehicles under residents, contracts, units, or fleet accounts.

​
Reference ID Examples

Reference IDs can represent various external entities:
  • RESIDENT_001 - Individual resident
  • UNIT_4B - Apartment unit
  • TENANT_ABC123 - Tenant account

​
Vehicle Plate Format

The API supports flexible vehicle plate formats with specific validation rules:

​
Plate Components

​
plateType
string
required
Issuing authority or region code (e.g., DXB, KSA, AUH)
​
plateCode
string
required
Either “White” or 1-3 alphanumeric characters (e.g., A, AB, 123)
​
plateNumber
string
required
Digits-only license number (e.g., 12345)

​
Validation Rules

  • Format: Uppercase letters only
  • Length: 2-4 characters recommended
  • Examples: DXB, AUH, KSA, SHJ
  • Pattern: ^[A-Z]{2,4}$
  • Format: Either “White” or 1-3 alphanumeric characters
  • Examples: White, A, AB, 123, ABC
  • Pattern: ^(White|[A-Za-z0-9]{1,3})$
  • Format: Digits only
  • Examples: 12345, 123, 67890
  • Pattern: ^\d+$

​
Plate Format Examples

  • DXB White 12345
  • DXB A 12345
  • DXB ABC 12345

​
Managing Whitelist Entries

​
Adding Vehicles

Add vehicles to the whitelist with all required information: 
curl -X POST "https://apistg.arqq.in/api/locations/location_123/whitelist" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "referenceId": "RESIDENT_001",
    "plateType": "DXB",
    "plateCode": "White",
    "plateNumber": "12345",
    "vehicleType": "Sedan",
    "note": "Primary vehicle for apartment 4B"
  }'

​
Listing Vehicles

Retrieve vehicles from the whitelist with optional filtering: 
curl -X GET "https://apistg.arqq.in/api/locations/location_123/whitelist" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

​
Updating Vehicles

Update existing whitelist entries: 
curl -X PUT "https://apistg.arqq.in/api/locations/location_123/whitelist/whitelist_789" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "referenceId": "RESIDENT_001",
    "plateType": "DXB",
    "plateCode": "A",
    "plateNumber": "67890",
    "vehicleType": "SUV",
    "note": "Updated vehicle information"
  }'

​
Removing Vehicles

Remove vehicles from the whitelist: 
curl -X DELETE "https://apistg.arqq.in/api/locations/location_123/whitelist/whitelist_789" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

​
Best Practices

​
Reference ID Management

1

Use Consistent Formats

Establish a consistent format for your reference IDs (e.g., RESIDENT_001, UNIT_4B, CONTRACT_2024_001).
2

Avoid PII

Don’t include personal information in reference IDs. Use system-generated identifiers instead.
3

Document Your Schema

Document your reference ID format for your team and future maintenance.

​
Error Handling

When adding vehicles, handle potential duplicates:
async function addVehicleSafely(locationId, vehicleData) {
  try {
    return await addVehicle(locationId, vehicleData);
  } catch (error) {
    if (error.response?.status === 409) {
      console.log('Vehicle already exists in whitelist');
      // Handle duplicate - maybe update instead
    } else {
      throw error;
    }
  }
}
Always validate plate data before making API calls:
function validatePlateData(plateData) {
  const { plateType, plateCode, plateNumber } = plateData;
  
  // Validate plate type
  if (!/^[A-Z]{2,4}$/.test(plateType)) {
    throw new Error('Invalid plate type format');
  }
  
  // Validate plate code
  if (!/^(White|[A-Za-z0-9]{1,3})$/.test(plateCode)) {
    throw new Error('Invalid plate code format');
  }
  
  // Validate plate number
  if (!/^\d+$/.test(plateNumber)) {
    throw new Error('Invalid plate number format');
  }
  
  return true;
}

​
Bulk Operations

For bulk operations, consider implementing client-side batching and rate limit management to avoid hitting API limits.
async function bulkAddVehicles(locationId, vehicles) {
  const batchSize = 10; // Process 10 vehicles at a time
  const results = [];
  
  for (let i = 0; i < vehicles.length; i += batchSize) {
    const batch = vehicles.slice(i, i + batchSize);
    
    const promises = batch.map(vehicle => 
      addVehicle(locationId, vehicle).catch(error => ({ error, vehicle }))
    );
    
    const batchResults = await Promise.all(promises);
    results.push(...batchResults);
    
    // Wait between batches to respect rate limits
    if (i + batchSize < vehicles.length) {
      await new Promise(resolve => setTimeout(resolve, 1000));
    }
  }
  
  return results;
}

​
Common Use Cases

​
Residential Property Management

Resident Vehicle Management

Manage vehicles for residents in apartment complexes:
  • Group vehicles by apartment unit (UNIT_4B)
  • Track primary and secondary vehicles
  • Handle temporary visitor passes
  • Manage parking permits and renewals

​
Commercial Fleet Management

Fleet Vehicle Tracking

Track commercial fleet vehicles:
  • Group vehicles by service contracts (CONTRACT_2024_001)
  • Manage delivery vehicle access
  • Track vendor and supplier vehicles
  • Monitor employee parking privileges

​
Event and Visitor Management

Temporary Access

Handle temporary vehicle access:
  • Create temporary visitor passes (VISITOR_PASS_001)
  • Manage event parking
  • Track contractor access
  • Handle emergency vehicle access