BoxLatviaDevelopers
Get access
Guides

Import from Excel

Prefer a spreadsheet to calls? Fill in an Excel file, send it to the API, and your locations, boxes and pictures are created or updated in one go. The same file can be sent again whenever something changes.

#How it works

  1. #Download the templates

    One file for each kind. Each has the column names, dropdowns, instructions, an example sheet and the lists of codes.

  2. #Fill in the Data sheet

    One row per location, box or picture. Keep the column names in the first row. Leave a cell empty to leave that value as it is. Import in this order: locations, then boxes, then pictures, because a box needs its location and a picture needs its box.

  3. #Check it first

    Send the file with ?validate_only=true. Every check runs, nothing is saved, and the answer lists what would happen to every row and every problem in it.

    Check a file
    curl -X POST "$API/v1/imports/locations?validate_only=true" \
      -u "$CLIENT_ID:$CLIENT_SECRET" \
      -F "file=@boxlatvia-locations.xlsx"
    200 OKX-Validate-Only: true
    {
      "kind": "locations",
      "validate_only": true,
      "summary": {
        "total": 3,
        "created": 1,
        "updated": 1,
        "unchanged": 0,
        "failed": 1
      },
      "rows": [
        {
          "row": 2,
          "external_id": "WH-IMANTA",
          "status": "would_update",
          "id": "9d80d5f4-d17a-4f3e-99f6-4ab43b132bc3"
        },
        {
          "row": 3,
          "external_id": "WH-KENGARAGS",
          "status": "would_create"
        },
        {
          "row": 4,
          "external_id": "WH-NOWHERE",
          "status": "failed",
          "errors": [
            {
              "field": "district",
              "message": "\"atlantis\" is not a known district code (see the Codes sheet)"
            }
          ]
        }
      ]
    }
  4. #Send it

    The same request without ?validate_only=true. Fix the rows that failed, and send the file again: rows that are already right are simply found unchanged.

    Import
    curl -X POST "$API/v1/imports/boxes" \
      -u "$CLIENT_ID:$CLIENT_SECRET" \
      -F "file=@boxlatvia-boxes.xlsx"
    200 OK
    {
      "kind": "boxes",
      "validate_only": false,
      "summary": {
        "total": 3,
        "created": 1,
        "updated": 1,
        "unchanged": 0,
        "failed": 1
      },
      "rows": [
        {
          "row": 2,
          "external_id": "SKU-3M",
          "status": "updated",
          "id": "c4883b4a-4e38-47bf-8a69-ef025917e022"
        },
        {
          "row": 3,
          "external_id": "SKU-8M",
          "status": "created",
          "id": "e8e189c3-3ac4-47d0-8ff1-584221c4e1ae"
        },
        {
          "row": 4,
          "external_id": "SKU-9M",
          "status": "failed",
          "errors": [
            {
              "field": "price_unit",
              "message": "\"gadsimts\" is not a known price unit code (see the Codes sheet)"
            },
            {
              "field": "price",
              "message": "must have at most 2 decimals"
            }
          ]
        }
      ]
    }

#The columns

The column names are the API's own field names, so a column means the same here as in the boxes, locations and pictures reference. Codes come from the reference data and are listed on the template's Codes sheet.

#Locations

ColumnTypeDescription
external_idtextalways. Your own identifier of the location (up to 100 characters). It decides whether a row creates a new location or updates an existing one.
nametextfor a new record. Name of the location, up to 100 characters. Required for a new location.
descriptiontextDescription, up to 250 characters.
addresstextAddress, up to 250 characters.
districttextDistrict code, from the Codes sheet.
latitudenumberLatitude, a number from -90 to 90. Give together with longitude.
longitudenumberLongitude, a number from -180 to 180. Give together with latitude.
featurescodes, separated by commasAmenity codes from the Codes sheet, separated by commas. Replaces the whole set. At least 5 are needed for customers to find the location.

#Boxes

ColumnTypeDescription
external_idtextalways. Your own identifier of the box (up to 100 characters). It decides whether a row creates a new box or updates an existing one.
nametextfor a new record. Name of the box, up to 255 characters. Required for a new box.
location_external_idtextfor a new record. The external_id of the location the box is in. Required for a new box. The location must exist already (import locations first).
descriptiontextDescription, up to 255 characters.
pricenumberPrice per period, more than 0, at most 2 decimals.
promotional_pricenumberDiscounted price. Must be lower than price.
price_period_1numberOptional fixed total for renting 1 period.
price_period_3numberOptional fixed total for renting 3 periods.
price_period_6numberOptional fixed total for renting 6 periods.
price_period_12numberOptional fixed total for renting 12 periods.
price_unittextPrice unit code from the Codes sheet (per month, per week).
sizenumberFloor area in m², more than 0.
size_lengthnumberInner length in metres.
size_widthnumberInner width in metres.
size_heightnumberInner height in metres.
door_widthnumberDoor width in metres.
door_heightnumberDoor height in metres.
total_unitswhole numberHow many identical boxes you have, a whole number, 0 or more.
available_unitswhole numberHow many are free to rent right now. Cannot exceed total_units.
max_advance_dayswhole numberHow many days ahead a customer may book, 1 to 730.
featurescodes, separated by commasAmenity codes from the Codes sheet, separated by commas. Replaces the whole set.

#Pictures

ColumnTypeDescription
ownertextalways. What the picture belongs to: box or location.
external_idtextalways. The external_id of that box or location. It must exist already.
picture_urltextalways. Public address (https) of the picture file: JPEG, PNG, WebP or GIF, up to 5 MB. BoxLatvia fetches it and stores its own copy.

#Rules to know

#Pictures

A picture row names the owner (box or location), its external_id and the address (https) of the picture. BoxLatvia fetches the picture and keeps its own copy, so your own file does not need to stay online.

Pictures by address
curl -X POST "$API/v1/imports/pictures" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -F "file=@boxlatvia-pictures.xlsx"
200 OK
{
  "kind": "pictures",
  "validate_only": false,
  "summary": {
    "total": 3,
    "created": 2,
    "updated": 0,
    "unchanged": 0,
    "failed": 1
  },
  "rows": [
    {
      "row": 2,
      "external_id": "WH-IMANTA",
      "status": "created",
      "id": "734e0d86-9a60-4107-9997-c9f0bcf77610"
    },
    {
      "row": 3,
      "external_id": "SKU-3M",
      "status": "created",
      "id": "d504c7e6-8458-456a-884d-0b4ba02be2d3"
    },
    {
      "row": 4,
      "external_id": "SKU-3M",
      "status": "failed",
      "errors": [
        {
          "field": "picture_url",
          "message": "the address answered HTTP 404"
        }
      ]
    }
  ]
}

#Reading the answer

The answer is 200 whenever the file could be read, even if some rows failed. Look at summary for the totals and at each entry of rows:

StatusMeaning
createdA new record was created (for pictures: the picture was added).
updatedAn existing record was changed.
unchangedNothing to change: the row had no values, or the picture was already there.
failedThe row was not saved; errors lists every problem as { field, message }.
would_create / would_updateOnly with validate_only: what would happen.

row is the row number as Excel shows it (the header is row 1), so you can go straight to the cell. A problem with the whole file is a 422 instead:

A file that cannot be used
curl -X POST "$API/v1/imports/boxes" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -F "file=@boxlatvia-boxes.xlsx"
422 Unprocessable Content
{
  "type": "https://api.boxlatvia.lv/problems/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "request_id": "88b1f62d-3509-4d1f-b542-ff67a35787ae",
  "errors": [
    {
      "field": "columns",
      "message": "unknown column(s): nane, colour. The columns of this file are: external_id, name, location_external_id, description, price, promotional_price, price_period_1, price_period_3, price_period_6, price_period_12, price_unit, size, size_length, size_width, size_height, door_width, door_height, total_units, available_units, max_advance_days, features"
    }
  ]
}
Tip
Send the file again after fixing: rows that went through before are found unchanged, so repeating an import is safe. Use an Idempotency-Key if a request might have timed out.

#Limits

LimitValue
Rows per file500 for locations and boxes, 50 for pictures
File size10 MB
Columns60
Text in a cell5000 characters (the field limits are lower)

You need the scope imports:write, which lets the credentials create and change locations, boxes and pictures through files. BoxLatvia grants it on request: request access.