Upload Cards CSV - OLIVE Payment Platform

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

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-data

Form 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

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

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

Authorization

string

header

required

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

Body

multipart/form-data

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.

Unblock Card

Wallet

​Request

​Form Data

​CSV Format

​Column Requirements

​Response

​Examples

​Validation Rules

Serial Number

MAC Address

​Best Practices

​Permissions

​Errors

Authorizations

Body

Response

Request

Form Data

CSV Format

Column Requirements

Response

Examples

Validation Rules

Best Practices

Permissions

Errors