Skip to main content
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"
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.vultlocal.com/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Request

​
Authorization
string
required
Bearer olive_live_xxx or Bearer eyJ... (JWT)
​
Content-Type
string
required
multipart/form-data

​
Form Data

​
file
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

ColumnFormatRequired
Serial No.Alphanumeric (e.g., OLIV0001)Yes
MAC Address6-octet (AA:BB:CC:DD:EE:FF) or 7-octetYes
MAC addresses can use colons (:) or hyphens (-) as separators.

​
Response

​
success
boolean
Whether upload succeeded
​
message
string
Summary message
​
total
integer
Total rows in CSV
​
created
integer
Successfully created cards
​
errors
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"
    }
  ]
}

​
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

  • Keep files under 10,000 rows for best performance
  • Split larger imports into batches
  • Review errors array after upload
  • Fix invalid rows and re-upload
  • Valid rows are still created even if some fail
  • 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

StatusCodeDescription
400INVALID_CSVCSV format or structure error
400MISSING_FILENo file uploaded
401UNAUTHORIZEDInvalid API key
403FORBIDDENNot authorized to upload
413FILE_TOO_LARGEFile exceeds size limit
500INTERNAL_ERRORServer error

Authorizations

​
Authorization
string
header
required

API Key for third-party integrations (WhatsApp, Smart PAY, VULT). Format: 'Bearer olive_live_xxxxxxxxxxxxx'

Body

multipart/form-data
​
file
file
required

CSV file with columns: serial_number, mac_address

​
batch_id
string
required

Batch identifier

Response

Upload successful with error log if any

The response is of type object.