Upload Cards CSV

POST/cards/upload-csvOpen in the API playground →

Info

Admin endpoint for bulk importing NFC cards into the system. Cards are created with status "Unassigned".

Request

Authorizationstringheaderrequired

Bearer olive_live_xxx or Bearer eyJ... (JWT)

Content-Typestringheaderrequired

multipart/form-data

Form Data

filefilebodyrequired

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

Info

MAC addresses can use colons (:) or hyphens (-) as separators.

---

Response

successboolean

Whether upload succeeded

messagestring

Summary message

totalinteger

Total rows in CSV

createdinteger

Successfully created cards

errorsarray

List of rows with errors

---

Examples

Request

cURL

curl -X POST "https://demo.api.vultlocal.com/api/v1/cards/upload-csv" \
  -H "Authorization: Bearer olive_live_xxx" \
  -F "file=@cards.csv"

Response

200 Success

{
  "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"
    }
  ]
}

400 Invalid File

{
  "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

• Keep files under 10,000 rows for best performance
• Split larger imports into batches

Error Handling

• Review errors array after upload
• Fix invalid rows and re-upload
• Valid rows are still created even if some fail

Duplicate Detection

• Serial numbers must be unique
• Duplicates in CSV are rejected
• Existing cards in system are skipped

---

Permissions

Warning

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