> ## Documentation Index > Fetch the complete documentation index at: https://code.dcycle.io/llms.txt > Use this file to discover all available pages before exploring further. # Replace Commuting Response (v2) > Write one commuting response again whole; the emissions that change are recalculated asynchronously [← Employees API](https://code.dcycle.io/api-reference/employees/overview.md) Change a response of an employee: send it **whole**, as a record of [Create Commuting Periods (v2)](https://code.dcycle.io/api-reference/employees/commuting-create-v2.md) without `employee_id` (the response keeps its employee). Its dates, its modes and the answers to your own survey questions become what you send: a mode you leave out is removed with its emissions. Read the response first with [Get Commuting Response (v2)](https://code.dcycle.io/api-reference/employees/commuting-response-get-v2.md) and send it back with your changes. The response's periods are rewritten **in place**: each transport keeps its commuting period (its `id` and history), and only the periods whose emissions change are recalculated, so a period you did not touch keeps the emissions it has. The request checks the body and writes it, then answers `202 Accepted` with an [ingest job](https://code.dcycle.io/api-reference/ingest-jobs/get.md) (`operation: update`) that calculates what changed. Follow it with [`GET /v2/ingest-jobs/{id}`](https://code.dcycle.io/api-reference/ingest-jobs/get) or, for a job submitted with an API key, the [`ingest_job.finished`](https://code.dcycle.io/api-reference/webhooks/overview) webhook. > [!WARNING] > > **Beta.** Part of the bulk ingest API, in beta. The contract may still change before general availability. > [!WARNING] > > **The `response_id` can change.** Changing the dates of a response that answers a survey sent to the employee moves > it to the employee's response for the new dates, and that survey is pending again. Read the new id from the job > item's `entity_id` (see [Response](#response)) and use it from then on. ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} # The car on Monday and Tuesday stays; the train on Wednesday becomes a bus. curl -X PUT "https://api.dcycle.io/v2/employees/commuting/responses/9f8e7d6c-5b4a-4392-8f1e-0d9c8b7a6f5e" \ -H "x-api-key: ${DCYCLE_API_KEY}" \ -H "x-organization-id: ${DCYCLE_ORG_ID}" \ -H "Idempotency-Key: 6e5d4c3b-2a1f-4e0d-9c8b-7a6f5e4d3c2b" \ -H "Content-Type: application/json" \ -d '{ "start_date": "2026-01-01", "end_date": "2026-06-30", "modes": [ {"work_model": "in_person", "transport_type": "car", "vehicle_size": "medium", "fuel_type": "petrol", "carpool": true, "days": ["monday", "tuesday"], "distance_km": 18}, {"work_model": "in_person", "transport_type": "bus", "fuel_type": "diesel", "days": ["wednesday"], "distance_km": 32.5}, {"work_model": "telecommuting", "days": ["thursday", "friday"]} ], "custom_responses": {"parking": "company_car_park"} }' ``` ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}} import os import uuid import requests url = "https://api.dcycle.io/v2/employees/commuting/responses/9f8e7d6c-5b4a-4392-8f1e-0d9c8b7a6f5e" headers = {"x-api-key": os.environ["DCYCLE_API_KEY"], "x-organization-id": os.environ["DCYCLE_ORG_ID"]} stored = requests.get(url, headers=headers, timeout=30).json() modes = [ {key: value for key, value in mode.items() if key != "period_id" and value is not None} for mode in stored["modes"] ] modes[1] |= {"transport_type": "bus", "fuel_type": "diesel"} # the train becomes a bus response = requests.put( url, headers={**headers, "Idempotency-Key": str(uuid.uuid4())}, # keep it to retry this same change json={ "start_date": stored["start_date"], "end_date": stored["end_date"], "situation": stored["situation"], "modes": modes, "custom_responses": stored["custom_responses"], }, timeout=60, ) response.raise_for_status() print(response.json()["id"]) ``` ```json 202 theme={"theme":{"light":"github-light","dark":"github-dark"}} { "id": "4a3b2c1d-0e9f-4a8b-b7c6-d5e4f3a2b1c0", "status": "processing", "entity_type": "employee_commuting", "operation": "update", "source": "api_bulk", "counts": { "submitted": 1, "succeeded": 0, "failed": 0 }, "chunks_total": 1, "chunks_done": 0, "created_at": "2026-10-29T09:20:31.877Z", "finished_at": null, "links": { "self": "/v2/ingest-jobs/4a3b2c1d-0e9f-4a8b-b7c6-d5e4f3a2b1c0", "items": "/v2/ingest-jobs/4a3b2c1d-0e9f-4a8b-b7c6-d5e4f3a2b1c0/items" } } ``` ```json 422 theme={"theme":{"light":"github-light","dark":"github-dark"}} { "type": "https://code.dcycle.io/api-reference/errors#BULK_RECORDS_REJECTED", "title": "Unprocessable Entity", "status": 422, "code": "BULK_RECORDS_REJECTED", "detail": "1 of the submitted records are invalid; nothing was written.", "errors": [ { "source_row_index": 0, "client_row_id": null, "error_code": "COMMUTING_RESPONSE_OVERLAP", "error_params": { "field": "start_date", "response_id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "start_date": "2026-07-01", "end_date": "2026-12-31" } } ], "rejected": 1, "request_id": "b2248a31-0f1b-4a7d-83ce-b29bd5977b4c" } ``` ```json 200 (dry_run=true) theme={"theme":{"light":"github-light","dark":"github-dark"}} { "dry_run": true, "submitted": 1, "valid": 1 } ``` ## How it works 1. **The body is checked** as a record of [Create Commuting Periods (v2)](https://code.dcycle.io/api-reference/employees/commuting-create-v2.md#common-mistakes) is: its fields, the rules of its modes and its custom factors. New dates must not overlap another response of the employee; dates you keep are not checked again. If anything is wrong the answer is `422` and nothing is written. 2. **The response is rewritten in place.** Each mode keeps the period of its transport (the car stays the car's period); a mode left over takes a period no mode kept, and the periods still left over are removed with their emissions. The days at home go on the first transport's period, as on create, and `custom_responses` are merged into the response's answers by key. A period whose transport, days, distance, vehicle or custom factor changed loses its emissions; a period whose `origin` or `destination` alone changed, or that you sent as it was, keeps them. 3. **The job calculates the periods left without emissions**, as on create: an `in_person` mode sent without `distance_km` gets the distance between its `origin` and `destination` again. Send the `distance_km` you read to keep it. Its item is `failed` with `DISTANCE_CALCULATION_ERROR` or `CALCULATION_FAILED` as on create, naming the `period_id`. 4. **When the chunk is done** the job is `completed` (or `completed_with_errors`). For a job submitted with an API key, `ingest_job.finished` is sent with `"operation": "update"`. The job's item has the response's `entity_id` after the rewrite. It is the same `response_id` unless you changed the dates of a response that answers a survey sent to the employee: the response then moves to the employee's response for its new dates, and the survey it answered is pending again. Use the item's `entity_id` from then on. ## Request ### Headers **x-api-key** `string` *required* Your API key (see [Authentication](https://code.dcycle.io/api-reference/introduction.md#authentication)). **x-organization-id** `string` *required* Your organization. The responses of its employees, and of those of the organizations under it that you can write to (its [perimeter](https://code.dcycle.io/api-reference/ingest-jobs/overview.md#perimeter)), can be replaced. **Idempotency-Key** `string` *required* 1 to 255 characters, one per change. Within 24 hours, the same key with the same route and body returns the original job (with `Idempotent-Replayed: true`), also when that rewrite moved the response to another id; the same key with another body or on another route is `422 IDEMPOTENCY_KEY_REUSED`. See [The Idempotency-Key](https://code.dcycle.io/api-reference/ingest-jobs/overview.md#the-idempotency-key). ### Path Parameters **response\_id** `uuid` *required* The response: the `entity_id` of its create job's item, or the `id` that [Get Commuting Response (v2)](https://code.dcycle.io/api-reference/employees/commuting-response-get-v2.md) answers. ### Query Parameters **dry\_run** `boolean` (default: false) Check only: the same `422`, nothing written, no job; `200` with `{"dry_run": true, "submitted": 1, "valid": 1}` when the body is valid. The `Idempotency-Key` header is still required, but a dry run does not check or store it. ### Body Parameters The fields of a record of [Create Commuting Periods (v2)](https://code.dcycle.io/api-reference/employees/commuting-create-v2.md#body-parameters) but `employee_id` and `client_row_id`. A field not listed here is rejected (`SCHEMA_INVALID`). **start\_date** `date` *required* First day of the period, [tomorrow in UTC at the latest](https://code.dcycle.io/api-reference/ingest-jobs/overview.md#activity-dates). **end\_date** `date` *required* Last day of the period, on or after `start_date`, Dec 31 of the current year at the latest. **situation** `string` (default: active) `active`, `inactive` (on leave) or `terminated`. An `inactive` or `terminated` response sends no `modes`. **modes** `array[object]` Every mode of the response, 1 to 8, required when `active`: the `in_person` and `telecommuting` modes of [Create Commuting Periods (v2)](https://code.dcycle.io/api-reference/employees/commuting-create-v2.md#body-parameters). A mode left out is removed. **custom\_responses** `object` Answers to your organization's own survey questions, by question key, **merged** into the stored ones: a key you send replaces its answer, `null` clears it, and a key you leave out keeps its answer (the whole object left out keeps them all). A formula column's key is ignored (its value is computed), so the `custom_responses` that [Get Commuting Response (v2)](https://code.dcycle.io/api-reference/employees/commuting-response-get-v2.md) reads can be sent back as they are; a key that is not one of your questions is refused (`CUSTOM_RESPONSE_INVALID`). ## Response `202 Accepted` with the job (`entity_type: employee_commuting`, `operation: update`) and a `Location` header to it. [`GET /v2/ingest-jobs/{id}/items`](https://code.dcycle.io/api-reference/ingest-jobs/list-items) has one item, whose `entity_id` is the response. ## Errors [Problem details](https://code.dcycle.io/api-reference/errors.md). The body's codes in `errors[].error_code` of a `422 BULK_RECORDS_REJECTED`, with `source_row_index` 0: `SCHEMA_INVALID`, `MULTIDB_CUSTOM_RECORD_NOT_FOUND_OR_DISABLED`, `MULTIDB_CUSTOM_RECORD_INCOMPATIBLE_CATEGORY`, `COMMUTING_RESPONSE_OVERLAP` (new dates overlap another response of the employee, which `error_params` names) and `CUSTOM_RESPONSE_INVALID`, as described in [Create Commuting Periods (v2)](https://code.dcycle.io/api-reference/employees/commuting-create-v2.md#errors). Request-level errors: `404 NOT_FOUND` when the response does not exist, has no period left, or its employee is outside your organization's [perimeter](https://code.dcycle.io/api-reference/ingest-jobs/overview.md#perimeter) (all answer the same); `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` without `Idempotency-Key`, `422 IDEMPOTENCY_KEY_REUSED`, `409 IDEMPOTENCY_KEY_IN_PROGRESS`, and `429` beyond the [rate limits](https://code.dcycle.io/api-reference/rate-limits.md). ## Related Endpoints > [card] [Get Commuting Response (v2)](https://code.dcycle.io/api-reference/employees/commuting-response-get-v2.md) > > Read the response to change > [card] [Create Commuting Periods (v2)](https://code.dcycle.io/api-reference/employees/commuting-create-v2.md) > > The record's fields and rules > [card] [Delete Commuting Periods (v2)](https://code.dcycle.io/api-reference/employees/commuting-delete-v2.md) > > Delete whole responses > [card] [Get Ingest Job](https://code.dcycle.io/api-reference/ingest-jobs/get.md) > > Follow the recalculation This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.