curl -X POST "https://demo.api.vultlocal.com/api/v1/cards/upload-csv" \
-H "Authorization: Bearer olive_live_xxx" \
-F "file=@cards.csv"
{
"success": true,
"message": "Cards uploaded successfully",
"total": 100,
"created": 98,
"errors": [
{
"row": 15,
"serial": "OLIV0015",
"error": "Duplicate serial number"
},
{
"row": 42,
"serial": "OLIV0042",
"error": "Invalid MAC address format"
}
]
}
{
"error": "Invalid CSV format",
"code": "INVALID_CSV",
"details": "Missing required column: MAC Address"
}
Cards
Upload Cards CSV
Bulk upload NFC cards via CSV file
POST
/
cards
/
upload-csv
curl -X POST "https://demo.api.vultlocal.com/api/v1/cards/upload-csv" \
-H "Authorization: Bearer olive_live_xxx" \
-F "file=@cards.csv"
{
"success": true,
"message": "Cards uploaded successfully",
"total": 100,
"created": 98,
"errors": [
{
"row": 15,
"serial": "OLIV0015",
"error": "Duplicate serial number"
},
{
"row": 42,
"serial": "OLIV0042",
"error": "Invalid MAC address format"
}
]
}
{
"error": "Invalid CSV format",
"code": "INVALID_CSV",
"details": "Missing required column: MAC Address"
}
Admin endpoint for bulk importing NFC cards into the system. Cards are created with status “Unassigned”.
Request
string
required
Bearer olive_live_xxx or Bearer eyJ... (JWT)string
required
multipart/form-dataForm Data
file
required
CSV file with card data
CSV Format
Serial No.,MAC Address
OLIV0001,AA:BB:CC:DD:EE:01
OLIV0002,AA:BB:CC:DD:EE:02
OLIV0003,AA:BB:CC:DD:EE:03
Column Requirements
| Column | Format | Required |
|---|---|---|
| Serial No. | Alphanumeric (e.g., OLIV0001) | Yes |
| MAC Address | 6-octet (AA:BB:CC:DD:EE:FF) or 7-octet | Yes |
MAC addresses can use colons (
:) or hyphens (-) as separators.Response
boolean
Whether upload succeeded
string
Summary message
integer
Total rows in CSV
integer
Successfully created cards
array
List of rows with errors
Examples
curl -X POST "https://demo.api.vultlocal.com/api/v1/cards/upload-csv" \
-H "Authorization: Bearer olive_live_xxx" \
-F "file=@cards.csv"
{
"success": true,
"message": "Cards uploaded successfully",
"total": 100,
"created": 98,
"errors": [
{
"row": 15,
"serial": "OLIV0015",
"error": "Duplicate serial number"
},
{
"row": 42,
"serial": "OLIV0042",
"error": "Invalid MAC address format"
}
]
}
{
"error": "Invalid CSV format",
"code": "INVALID_CSV",
"details": "Missing required column: MAC Address"
}
Validation Rules
Serial Number
- Must be unique in system
- Alphanumeric characters
- No special characters
MAC Address
- Valid hex octets
- 6 or 7 octets supported
- Colons or hyphens allowed
Best Practices
File Size
File Size
- Keep files under 10,000 rows for best performance
- Split larger imports into batches
Error Handling
Error Handling
- Review errors array after upload
- Fix invalid rows and re-upload
- Valid rows are still created even if some fail
Duplicate Detection
Duplicate Detection
- Serial numbers must be unique
- Duplicates in CSV are rejected
- Existing cards in system are skipped
Permissions
Only users with
system_admin role can upload cards.Errors
| Status | Code | Description |
|---|---|---|
| 400 | INVALID_CSV | CSV format or structure error |
| 400 | MISSING_FILE | No file uploaded |
| 401 | UNAUTHORIZED | Invalid API key |
| 403 | FORBIDDEN | Not authorized to upload |
| 413 | FILE_TOO_LARGE | File exceeds size limit |
| 500 | INTERNAL_ERROR | Server error |
Authorizations
ApiKeyAuthBearerAuth
API Key for third-party integrations (WhatsApp, Smart PAY, VULT). Format: 'Bearer olive_live_xxxxxxxxxxxxx'
Body
multipart/form-data
Response
Upload successful with error log if any
The response is of type object.
⌘I