Skip to main content
POST
← Business Travels API Create one or many business travels (Scope 3 category 6). Say how each trip was made, when, how often and how far, or between which places; Dcycle works out the distance when you leave it out, picks the emission factor and calculates the emissions in the background. Or say what it cost instead of the distance and places, and it is calculated from its spend. The travels are the ones /v1/business-travels 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. 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).
  2. The travels are written at once, with status pending, in the x-organization-id organization.
  3. The job calculates them in the background, in chunks. A travel sent without distance_km gets the distance between its origin and destination for its transport (road or rail route, great-circle for a flight, sea route for a ferry), and its places are located. Then the emission factor of its transport, fuel and country is applied. A travel that carries what it cost and whose places cannot be measured, or whose distance has no factor, is priced by its spend instead of failing (unless its custom_ef_record_id is not per currency). Each travel ends active or error. Its job item is then failed with the reason when there is one:
    • TRANSPORT_MODE_INVALID_FOR_ROUTE: a road or rail trip with no route for its transport between the two places (e.g. a car between continents), or one of them cannot be found. Check the transport and the places.
    • DISTANCE_CALCULATION_ERROR: a flight or a ferry whose distance could not be calculated, because one of its places cannot be found or the distance service did not answer; rarely, a road or rail trip the distance service answered with an error. Check the places; if they are right, send it with distance_km.
    • EXCHANGE_RATE_NOT_FOUND: a travel priced by what it cost, in a currency whose rate to EUR could not be had for its start_date (error_params.field is currency_unit_id).
    • CALCULATION_FAILED: no emission factor for the trip, the road or rail distance service did not answer, or a ferry has no sea route between the two places. If the distance service did not answer, send it again later; else send it with distance_km, or with what it cost. If it still fails, no factor applies to its transport, fuel and country (nor, with a spend, an EXIOBASE factor to its transport in your organization’s country).
    Either way the travel stays stored, in error, under the item’s entity_id: delete it with Delete Business Travels (v2) before sending it again, with the places fixed or with distance_km, or the trip will be listed twice.
  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.

How a trip is counted

A record is a trip made travel_number times in its period: its emissions are those of distance_km (twice for travel_type: round) for each trip. Whether passenger_number multiplies them depends on the unit of the emission factor:
  • Per passenger-km (public transport, flights, ferries, cars before 2024, most motorbikes): each passenger counts.
  • Per vehicle-km (most cars from 2024, hybrid cars, electric motorbikes from 2024): the vehicle counts, and it emits the same with any number of passengers.
Send the people who travelled together in one record with their passenger_number either way: the factor’s unit decides. A trip over several days is one record with its start_date and end_date; recurring trips (a commute to a client) are one record with their count.

What a trip cost

A record can also say what it cost: spend_amount in currency_unit_id, the total of the record (all its trips and passengers). It is optional and, unlike an invoice’s total_spend, which is only kept, it can price the travel. With it distance_km, origin and destination become optional; the rest of the record is checked as for any trip (a car still takes its vehicle_size and fuel_type). The distance keeps the priority, as in freight transports: a travel with a distance_km, or with an origin and a destination to measure it from, is calculated from its distance. Its spend prices it only when its distance cannot:
  • it has no distance and no places (a distance of 0 km counts as none);
  • its places cannot be measured (a place that cannot be found, no route for its transport). When the road or rail distance service does not answer, the travel fails as without a spend: send it again later. For a flight, a service that does not answer cannot be told from a place it cannot find, so the spend prices it;
  • no emission factor applies to its distance (its transport, fuel and country).
Then the travel is its spend in EUR (at the rate of its start_date) times the EXIOBASE spend factor (kgCO2e per EUR) of its transport in your organization’s country. Its travel_number, passenger_number, places and distance do not change the result. A spend in a currency whose rate to EUR cannot be had fails the travel with EXCHANGE_RATE_NOT_FOUND only when the spend prices it. A custom_ef_record_id sent with it still decides the factor: one per unit of currency prices the spend, and one per passenger-km or km prices the distance. Such a factor needs a distance: a record with a spend, no distance_km and no places is rejected with UNIT_NOT_ALLOWED_FOR_CUSTOM_EMISSION_FACTOR, and a travel whose places cannot be measured fails with the reason of its distance (see How it works) instead of being priced at 0 km.

Request

Headers

string
required
Your API key (see Authentication).
string
required
The organization the travels belong to. A record cannot name another organization: send each organization’s travels 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, one per batch, looked up per organization across every v2 bulk route. Within 24 hours, the same key with the same route and body returns the original job (with Idempotent-Replayed: true) instead of creating the travels again; the same key with another body or on another route is 422 IDEMPOTENCY_KEY_REUSED, and while the first request is still being processed 409 IDEMPOTENCY_KEY_IN_PROGRESS. After 24 hours the key is free, and a request with it is a new one. See The Idempotency-Key.

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. The Idempotency-Key header is still required, but a dry run does not check or store it.

Body Parameters

array[object]
required
The business travels to create, 1 to 5,000. A field not listed here is rejected (SCHEMA_INVALID).
The file import template writes some of these values differently: car_small is transport_type: car + vehicle_size: small here, return_trip is travel_type: round, and electric_renewable / electric_not_renewable is fuel_type: electric + renewable_energy: yes / no.

Response

202 Accepted with the job (entity_type: business_travels, operation: create) and a Location header to it. To read the result:
If chunks_done stops moving, see A job that does not finish: never resend the batch with a new Idempotency-Key, because its business travels are already stored.

Errors

Problem details. Per-record codes in errors[].error_code of a 422 BULK_RECORDS_REJECTED: 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 Business Travels (v2)

Delete travels by id

Get Ingest Job

Follow the calculation

List Job Items

The travel id and outcome of each record

List Business Travels

The travels and their emissions