Got a lot to sell? List dozens of items at once with a single CSV. This page is a plain-language guide for sellers and a REST reference for developers and partners — same API, same account as the app and website.
One row per item with the columns below. Start from our template so the headers are exact.
Send the CSV to the API. You get back a validated preview — which rows are ready and which have errors — plus a publish token.
Confirm with the publish token and every valid row goes live on your account, geocoded onto the map.
A plain UTF-8 .csv file with a header row. One item per line. Required columns must be present and non-empty.
| Column | Required | Notes |
|---|---|---|
| title | Required | Item name buyers see. Keep it short and specific. |
| price | Required | A number (€ optional), e.g. 750 or 750 €. Must be > 0. |
| category | Optional | One of the marketplace categories below. If blank, it's auto-suggested from the title/description (or set a default in the upload UI). |
| subcategory | Optional | Optional subcategory within the category (see each category's list). Validated against the chosen category. |
| description | Optional | Free text. Condition, details, what's included. |
| address | Optional | Full address — street, postcode, city (geocoded to the exact spot). Wrap it in "quotes" if it contains a comma. |
| photos | Optional | Image filenames and/or https:// URLs, separated by ; (first = cover). See Photos below. |
title,price,category,subcategory,description,address,photos
iPhone 14 Pro 256GB,750,Electronics,Phones,Boxed,"Hauptstraße 5, 10115 Berlin",iphone-front.jpg;iphone-back.jpg
IKEA Desk (white),45,Home & Garden,Furniture,120x60cm,"Musterweg 12, 20095 Hamburg",https://example.com/desk.jpg
Mountain bike (27.5 inch),320,Sports & Outdoors,Cycling,Aluminium frame,80331 Munich,bike-1.jpg;bike-2.jpgNeed structured details (brand, size, colour…)? Add spec_<key> columns — e.g. spec_brand, spec_color— and the values appear on the listing's spec sheet. The template designer builds these for any category automatically.
Standard CSVs separate columns with a comma. But Excel and Numbers in Germany (and some other locales) export with a semicolon (;) — open the wrong one and every row collapses into a single cell. So we auto-detectthe separator from your file's header line, and you can always override it:
delimiter form field (,, ;, or a tab) — omit it to auto-detect.The photos column normally separates images with ;. If your file itself is semicolon-delimited, separate photos with a comma instead — we handle the swap (and | always works as a photo separator too).
The optional photos column holds one or more images, separated by ; — the first is the cover. Each entry is either:
desk-1.jpg. On the web uploader you then pick those files (or a whole folder) and we match them by name, compress them (high quality, much smaller), and upload. You can even paste a full path like C:\pics\desk-1.jpg — only the filename is used to match.A browser can't read files straight off your disk by path (for security), so for local photos the uploader needs you to select the files — that's why the photos column uses filenames, not raw paths.
Use one of these exact labels in the category column so your item lands in the right place:
For developers and partners integrating programmatically. Two calls: upload to get a validated preview + a publish_token, then publish.
Every request needs your account access token (a Supabase JWT) in the header. The server derives your identity from the token — items are always created on your own account.
Authorization: Bearer <YOUR_ACCESS_TOKEN>Base URL shown as https://api.listitfast.app for illustration — partners receive the API host and credentials on request.
POST/api/v1/listings/bulk
Upload a CSV (multipart/form-data, field file). Returns a validated preview (first 10 rows) and a publish_token. Nothing is published yet. Optional form fields: default_category / default_subcategory (for rows that omit one) and delimiter (, / ; / tab — omit to auto-detect).
curl -X POST https://api.listitfast.app/api/v1/listings/bulk \
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
-F "file=@my-items.csv"{
"status": "preview",
"total_rows": 24,
"valid_items": 22,
"errors": [
{ "row": 5, "field": "price", "error": "Invalid price format" }
],
"preview_items": [
{
"title": "iPhone 14 Pro 256GB",
"price": "750",
"category": "Electronics",
"subcategory": "Phones",
"description": "Excellent condition - boxed",
"address": "10115 Berlin",
"status": "ready_to_publish"
}
],
"publish_token": "b1c2d3e4-5f6a-7b8c-9d0e-1f2a3b4c5d6e"
}POST/api/v1/listings/bulk/publish
Publish the valid rows from a preview session. Pass the publish_token from step one. Each item gets an ITEM-XXXXXXXX id and (if an address was given) is geocoded onto the map.
curl -X POST https://api.listitfast.app/api/v1/listings/bulk/publish \
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{ "publish_token": "b1c2d3e4-5f6a-7b8c-9d0e-1f2a3b4c5d6e", "user_id": "<YOUR_USER_ID>" }'{
"status": "published",
"items_created": 22,
"items_failed": 0,
"listing_ids": ["ITEM-A1B2C3D4", "ITEM-E5F6G7H8"]
}400 — not a .csv file.401 — missing or invalid access token.404 — publish token not found (or already published).422 — malformed request body.errors array so you can fix and re-upload.All errors use the shape { "detail": "<reason>" }.