Skip to main content
POST
Upload Transport File

Upload Transport File

Upload a spreadsheet file containing transport routes. The file is processed asynchronously — rows are parsed, geocoded, and emission factors are resolved in the background after the upload returns.
For files larger than a few MB, use the Presigned URL approach instead. It uploads the file directly to S3 without routing the bytes through the API server.

Request

Headers

string
required
Your API key for authenticationExample: sk_live_1234567890abcdef
string
required
Your organization UUID.Example: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Body (multipart/form-data)

string
required
The GHG Protocol scope 3 direction of these transport routes.
  • downstream — transport paid by your organization after the sale (Category 9)
  • upstream — inbound transport paid by your organization (Category 4)
file
required
The spreadsheet file to upload. Accepted formats: .csv, .xls, .xlsx.

Response

string
Human-readable confirmation message.Example: "Transport route file uploaded"
string
UUID that identifies this upload batch. Use it to filter routes via GET /v1/transports?file_id=<file_id> or to track processing progress.Example: "b3d7c1e2-4a5f-48d9-b6e8-1234567890ab"

Example

Successful Response

Asynchronous Processing

The endpoint returns immediately with status 201. The actual processing happens in the background:
  1. Rows are parsed from the uploaded file.
  2. Origin and destination addresses are geocoded (Google Maps Distance Matrix API for road/rail, haversine for air, sea-distance tables for maritime).
  3. Emission factors are resolved and CO2e values are calculated.
You can poll the processing status by listing routes filtered by the returned file_id:
Route statuses move through pendingactive (success) or error as processing completes.

Common Errors

401 Unauthorized

Cause: Missing or invalid API key / Bearer token.

422 Unprocessable Entity

Cause: transport_direction is missing or not one of the accepted values.
Solution: Set transport_direction to downstream or upstream.

400 Bad Request

Cause: Unsupported file format (not .csv, .xls, or .xlsx).

Presigned URL Upload

Upload large files directly to S3 via a presigned URL

List Transport Routes

Retrieve transport routes, filter by file_id to track batch processing

Transport Combinations

Explore valid transport type and method combinations before creating routes

Transport Overview

Learn the full Transport API data model and workflow