Skip to main content
POST
← Transport API Create one or many freight shipments (Scope 3 categories 4 and 9, upstream and downstream transportation). Say when each shipment was made, in which direction, how much it weighed and its legs (sections), each with its transport and either its distance or the places it joins; Dcycle works out the distance when you leave it out, picks the emission factor and calculates the emissions in the background. The shipments are the ones /v1/transports reads and edits. The request checks every record and writes them all at once, then answers 202 Accepted with an ingest job that calculates them (see how bulk ingestion works). Follow it with GET /v2/ingest-jobs/{id} or, for a job submitted with an API key, the ingest_job.finished webhook.
Beta. Part of the bulk ingest API, in beta. The contract may still change before general availability.

​
How it works

  1. Every record is checked: its fields, its weight unit, each section’s transport against the combinations there are emission factors for, and its custom factors. If any is invalid the whole request is rejected with 422 and nothing is written; rejected is the number of invalid records and errors lists them (up to 100). The request looks up no place: an address that cannot be found only shows in the job.
  2. The shipments are written at once, with their sections and status pending, in the x-organization-id organization.
  3. The job calculates them in the background, in chunks. A section sent without distance_km gets the distance between its origin and destination for its transport (road or rail route, sea route for maritime, great-circle for air), and its places are located. A do_not_know section is inferred as for POST /v1/transports: road by truck within a country when there is a road route, air otherwise. Then each section gets the emission factor of its transport, its distance and the shipment’s weight. Each shipment ends active or error. Its job item is then failed with the reason when there is one:
    • DISTANCE_CALCULATION_ERROR: the distance of a section could not be had (an address that cannot be found, no route for that transport between the two places, or the distance provider unavailable). The shipment is not calculated: send it again with the places fixed, or with distance_km.
    • CALCULATION_FAILED: no emission factor for a section, or another calculation error.
  4. When every chunk is done the job is completed (or completed_with_errors). For a job submitted with an API key, ingest_job.finished is sent to the webhook endpoints of the x-organization-id organization.

​
Coming from POST /v1/transports

The record is the shipment v1 takes, with these differences:
  • transport_direction is required (v1 assumes downstream when it is missing).
  • A section gives its distance as distance_km, instead of kms_manual with distance_manual: true. A section without it gives origin and destination.
  • There is no detail: the distance or weight band of the factor is picked from the section’s distance and the shipment’s weight, as v1 does when detail is left out.
  • There is no organization_id, nor any other field not listed below: the shipments belong to the x-organization-id organization.

​
Request

​
Headers

​
string
required
Your API key (see Authentication).
​
string
required
The organization the shipments belong to. A record cannot name another organization: send each organization’s shipments with its own x-organization-id. The job and its ingest_job.finished webhook belong to that organization too, so register a webhook endpoint in each organization you send as.
​
string
required
1 to 255 characters, unique per batch. A retry with the same key and body returns the original job (with Idempotent-Replayed: true) instead of creating the shipments again; the same key with another body is 422 IDEMPOTENCY_KEY_REUSED, and while the first request is still being processed 409 IDEMPOTENCY_KEY_IN_PROGRESS.

​
Query Parameters

​
boolean
default:"false"
Check only: the same 422 for invalid records, nothing written, no job; 200 with {"dry_run": true, "submitted": n, "valid": n} when every record is valid.

​
Body Parameters

​
array[object]
required
The shipments to create, 1 to 5,000. A field not listed here is rejected (SCHEMA_INVALID).

​
Response

202 Accepted with the job (entity_type: transport_routes, operation: create) and a Location header to it. To read the result:

​
Errors

Problem details. Per-record codes in errors[].error_code of a 422 BULK_RECORDS_REJECTED (each invalid record is listed once, with its first error): Request-level errors: 401 for a missing or invalid API key, 403 LOGGED_USER_NOT_MEMBER when the key’s user is not a member of the organization, 422 REQUEST_VALIDATION_FAILED for a malformed body (no records, more than 5,000, no Idempotency-Key), 422 IDEMPOTENCY_KEY_REUSED, 409 IDEMPOTENCY_KEY_IN_PROGRESS, and 429 beyond the rate limits.

​
Limits

Delete Freight Transports (v2)

Delete shipments by id

Transport Combinations

The section transports there are factors for

Get Ingest Job

Follow the calculation

List Job Items

The shipment id and outcome of each record

List Transport Routes

The shipments and their emissions

List Units

The weight units a shipment takes