> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withleaf.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Uploading Boundaries

> Upload field boundaries in bulk using shapefiles, GeoJSON, or KML/KMZ files. Covers supported formats, file requirements, and tracking upload status.

The field upload service creates field boundaries from spatial files. Instead of creating fields one at a time via the API, you can upload a zip file containing shapefiles, GeoJSON, or KML and Leaf creates all the fields at once.

## Supported formats

Upload a `.zip` file containing one or more of:

* **Shapefile** — Must include at least `.shp`, `.dbf`, and `.shx` files.
* **GeoJSON** — Standard GeoJSON with Polygon or MultiPolygon geometries.
* **KML/KMZ** — Google Earth format.

The zip can contain multiple files in different formats. Leaf detects and processes each valid file independently. Nested directory structures inside the zip are fine.

If a file includes a property or column called `name`, Leaf uses it as the field name.

All geometries are projected to WGS 84 (EPSG:4326).

## Limits

* Maximum file size: 3 GB
* Maximum fields per upload: 100

## Uploading a file

`POST /services/uploadservice/api/upload?leafUserId={leafUserId}`

Send the file as `multipart/form-data`. The `leafUserId` parameter is required. You can optionally pass `farmId` to assign all created fields to a specific farm.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST \
      -H 'Authorization: Bearer YOUR_TOKEN' \
      -F 'file=@boundaries.zip' \
      'https://api.withleaf.io/services/uploadservice/api/upload?leafUserId={leafUserId}'
  ```

  ```python Python theme={null}
  import requests

  TOKEN = 'YOUR_TOKEN'
  endpoint = 'https://api.withleaf.io/services/uploadservice/api/upload?leafUserId={leafUserId}'
  headers = {'Authorization': f'Bearer {TOKEN}'}

  files = {'file': open('boundaries.zip', 'rb')}

  response = requests.post(endpoint, headers=headers, files=files)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const axios = require('axios')
  const FormData = require('form-data')
  const fs = require('fs')
  const TOKEN = 'YOUR_TOKEN'

  const endpoint = 'https://api.withleaf.io/services/uploadservice/api/upload?leafUserId={leafUserId}'

  const form = new FormData()
  form.append('file', fs.createReadStream('boundaries.zip'))

  axios.post(endpoint, form, {
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      ...form.getHeaders(),
    },
  })
      .then(res => console.log(res.data))
      .catch(console.error)
  ```
</CodeGroup>

The response includes an upload `id` you use to track progress.

## Tracking upload status

`GET /services/uploadservice/api/upload/{uploadId}`

| Status      | Meaning                                                      |
| ----------- | ------------------------------------------------------------ |
| `RECEIVED`  | Upload accepted, processing not started                      |
| `PROCESSED` | All files processed, at least one field created successfully |
| `FAILED`    | No fields were created                                       |

## Getting created fields

`GET /services/uploadservice/api/upload/{uploadId}/entries`

Returns the processing result for each file in the zip. Each entry includes:

* `fieldId` — Array of field IDs created from that file.
* `converterFormat` — Detected format: `SHAPEFILE`, `GEOJSON`, or `KML`.
* `status` — Per-file status: `PROCESSING`, `CONVERTED`, `FINISHED`, `FAILED`, or `PARTIALLY_FINISHED`.
* `createFieldErrorDetails` — Error messages for any fields that failed to create (e.g., self-intersecting geometry).

Use the field IDs from the entries response to fetch full field details via `GET /services/fields/api/users/{leafUserId}/fields/{fieldId}`.

## What to do next

* [Managing Fields](/fields/managing-fields) — Create and update individual fields via the API.
* [Fields Overview](/fields/overview) — How boundaries fit into the Grower/Farm/Field model.
* [API Reference: Field Upload](/api-reference/field-upload) — Full endpoint reference for the upload service.