Skip to main content
PUT
← Employees API Change a response of an employee: send it whole, as a record of Create Commuting Periods (v2) 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) 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 (operation: update) that calculates what changed. 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.
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) and use it from then on.

​
How it works

  1. The body is checked as a record of Create Commuting Periods (v2) 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

​
string
required
Your API key (see Authentication).
​
string
required
Your organization. The responses of its employees, and of those of the organizations under it that you can write to (its perimeter), can be replaced.
​
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.

​
Path Parameters

​
uuid
required
The response: the entity_id of its create job’s item, or the id that Get Commuting Response (v2) answers.

​
Query Parameters

​
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) but employee_id and client_row_id. A field not listed here is rejected (SCHEMA_INVALID).
​
date
required
First day of the period, tomorrow in UTC at the latest.
​
date
required
Last day of the period, on or after start_date, Dec 31 of the current year at the latest.
​
string
default:"active"
active, inactive (on leave) or terminated. An inactive or terminated response sends no 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). A mode left out is removed.
​
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) 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 has one item, whose entity_id is the response.

​
Errors

Problem details. 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). 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 (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.

Get Commuting Response (v2)

Read the response to change

Create Commuting Periods (v2)

The record’s fields and rules

Delete Commuting Periods (v2)

Delete whole responses

Get Ingest Job

Follow the recalculation