---
title: "Create upload batch"
method: POST
path: "/api/v1/external/upload-batches"
tags: ["Upload Batches"]
---

# Create upload batch

`POST /api/v1/external/upload-batches`

## Request

- Base URL: `https://api.wove.com`
- URL: `https://api.wove.com/api/v1/external/upload-batches`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/wove/apis/wove-external-api/docs/api/v1/external/upload-batches/post.ts> (a function with typed inputs; its response is checked against the schema)

Upload a group of files (e.g. one shipment's paperwork) and let Wove's object-creation pipeline
create the shipments, shipment events or customs entries they describe.

Processing is asynchronous: the batch is returned with status `pending`, moves to `processing`,
and ends as `completed` or `failed`. Poll `GET /api/v1/external/upload-batches/{batchId}` and read
`createdEntities` once it has completed.

**Required scopes:** `documents:write`, plus the write scope of every type in
`allowedObjectTypes` (`shipment` / `shipment_event` → `shipments:write`,
`customs_entry` → `customs:write`). When `allowedObjectTypes` is omitted the batch is unrestricted
and requires `shipments:write`.

## Request body `multipart/form-data`

- object
  - `files` string[], required: 1-50 files, up to 50 MB each. Zip archives are expanded.
  - `label` string: Display label for the batch
  - `note` string: Free-text context for the pipeline (stands in for an email body)
  - `branchId` string: Branch to assign. Must belong to your organization.
  - `allowedObjectTypes` string[]: Restricts what the batch may create. Send the field repeated or as one comma-separated value. Any other value is rejected with 400. Omit for an unrestricted batch.
  - `entryType` '01' | '11' | 'export' | 'in_bond' | 'ca_b3' | 'ca_clvs' | 'ca_type_f': Customs entry type hint for customs-entry batches. Unrecognized values are ignored.
  - `filingCountry` string: ISO-2 filing country hint for customs-entry batches

## Response `201`

Batch created and queued for processing

- object
  - `success` boolean
  - `data` UploadBatch
    - `id` string, required
    - `label` string, nullable
    - `note` string, nullable: Free-text context supplied with the upload
    - `entryType` '01' | '11' | 'export' | 'in_bond' | 'ca_b3' | 'ca_clvs' | 'ca_type_f' | 'null', nullable: Customs entry type hint. Customs-entry batches only.
    - `filingCountry` string, nullable: ISO-2 filing country hint. Customs-entry batches only.
    - `status` 'pending' | 'processing' | 'completed' | 'failed', required
    - `branchId` string, nullable
    - `documentCount` integer, required: Documents created from the files, after zip expansion and splitting
    - `sourceFileCount` integer: Files received, after zip expansion
    - `duplicateFileCount` integer: Files skipped because identical content was already ingested for this batch
    - `createdEntities` UploadBatchCreatedEntity[], required: Entities the pipeline created or attached to. Empty until the batch completes.
      - `entityType` string, required: Type of entity the batch produced
      - `entityId` string, required
      - `documentIds` string[], required: Documents from the batch attached to this entity
      - `isNew` boolean: False when the documents were attached to an entity that already existed (e.g. a shipment matched on its bill of lading). Absent on older batches.
    - `unusedDocumentIds` string[], required: Documents the pipeline could not tie to any entity
    - `error` string, nullable: Failure reason when status is failed
    - `processedAt` string, date-time, nullable
    - `createdAt` string, date-time, required
    - `externalShipmentRefId` string, nullable: TMS job the documents were imported from. Null for file uploads.
    - `tmsSource` string, nullable: TMS the documents were imported from. Null for file uploads.

## Other responses

- `400`: No files, too many or oversized files, an unsupported allowedObjectTypes value, or an invalid/unknown branchId
- `401`: Authentication required or invalid credentials
- `403`: Missing documents:write or the write scope for a requested object type

---

[API](https://skmtc.dev/wove/apis/wove-external-api.md) - [All operations](https://skmtc.dev/wove/apis/wove-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/wove/apis/wove-external-api/revisions/37290e267e07?raw)