Skip to main content
POST
← Employees API Say how your employees got to work (Scope 3 category 7, employee commuting): one record per employee and period, with the transport, the days of the week they commuted or worked from home, and how far, or between which places. Dcycle works out the distance when you leave it out and calculates the emissions in the background. The periods are the ones List Commuting Periods reads, in the vocabulary of POST /v1/employee-historic and with its rules. 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. Like the rest of the bulk ingest API, this route never sends an email.
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 and the transport rules, its employee, its custom factors, and that the employee has no period with the same start_date and end_date, stored or in the request. If any record 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 never measures a distance.
  2. The periods are written at once, each in the organization of its employee: the x-organization-id organization or one of its perimeter.
  3. The job calculates them in the background, in chunks. A period sent without total_km gets the distance of the road or rail route (by its transport) between its origin and destination, and is marked total_km_estimated. Then its commute is calculated under employee commuting, and its days at home under telecommuting where there is a factor for them. An employee with a calculated period is uploaded. A job item is failed when:
    • DISTANCE_CALCULATION_ERROR: a place could not be found or no route joins them. The period is kept without a distance and is not calculated: delete it and send it again with total_km or other places.
    • CALCULATION_FAILED: the period produced no emission at all (no factor for its commute or its days at home).
  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 period is counted

A period is the same commute repeated on the weekly_travels days between start_date and end_date, without the public holidays of the organization’s country: daily_trips trips each of those days, over total_km. A shared car (carpool: true) divides the emissions. The weekly_telecommuting days count as days worked from home. A change of address or transport is a new period, with its own dates.

​
Request

​
Headers

​
string
required
Your API key (see Authentication).
​
string
required
The organization you send as. Its employees, and those of the organizations under it that you can write to (its perimeter), can be given periods. The job and its ingest_job.finished webhook belong to this organization.
​
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 periods 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. It does not check or store the Idempotency-Key.

​
Body Parameters

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

​
Transport rules

The rules of POST /v1/employee-historic. A field a transport does not take is left out (or null); sending it is SCHEMA_INVALID, except for walking and telecommuting, which ignore any vehicle detail.

​
Response

202 Accepted with the job (entity_type: employee_commuting, 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 periods are already stored (and would answer COMMUTING_PERIOD_ALREADY_EXISTS).

​
Errors

Problem details. Per-record codes in errors[].error_code of a 422 BULK_RECORDS_REJECTED: After the 202, a job item can end failed with DISTANCE_CALCULATION_ERROR or CALCULATION_FAILED (see How it works). 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

Create Employees (v2)

The employees, and their employee_id

Delete Commuting Periods (v2)

Delete periods by id

List Job Items

The period id and outcome of each record

List Custom Factor Records

The ids for custom_ef_record_id