Skip to main content
POST
← Employees API Delete commuting periods of your employees by id, or whole responses: every period a record of Create Commuting Periods (v2) wrote, one per transport. The request checks every id and answers 202 Accepted with an ingest job that deletes them in the background (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. Send one of the two:
  • response_ids: the entity_ids of the job items of Create Commuting Periods (v2). Each deletes every period of that response, whichever request or app form wrote it.
  • ids: the ids of List Commuting Periods, one period each: one transport of a response. The first transport’s period also holds the response’s days at home and the answers to your own survey questions, which go with it. To change a response, rewrite it with Replace Commuting Response (v2) instead: its periods keep their ids and only what changed is calculated again.
The employees stay: to delete an employee with all their periods, use Delete Employees (v2).
Permanent. Deleted periods cannot be recovered. Use dry_run=true first if you are not sure.
Beta. Part of the bulk ingest API, in beta. The contract may still change before general availability.

How it works

  1. The request checks every id. One that does not exist, is deleted, belongs to a disabled employee or to an employee outside your organization’s perimeter, or is repeated rejects the whole request with 422, and nothing is deleted.
  2. The job deletes the periods in the background (every period of a response), with their emissions, calculation data and custom column values. A response left with no period is deleted too, and each employee’s emissions are summed again from the periods they keep.
  3. 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 with "operation": "delete" to the webhook endpoints of the x-organization-id organization.

Request

Headers

string
required
Your API key (see Authentication).
string
required
The organization the periods are deleted for. The periods of its employees, and of those of the organizations under it that you can write to (its perimeter), can be deleted.
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); 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 bad ids, nothing deleted, no job; 200 with {"dry_run": true, "submitted": n, "valid": n} when every id is valid. The Idempotency-Key header is still required, but a dry run does not check or store it.

Body Parameters

array[uuid]
Response ids, the entity_id of a create job’s items, 1 to 5,000, each once: every period of each response is deleted. Send response_ids or ids, not both.
array[uuid]
Commuting period ids, 1 to 5,000, each once: one transport each (the first one with the response’s days at home). Send ids or response_ids, not both.

Response

202 Accepted with the job (entity_type: employee_commuting, operation: delete) and a Location header to it. GET /v2/ingest-jobs/{id}/items has one item per id, in the order sent; an item is failed with DELETE_FAILED when its period (or every period of its response) was already gone by the time the job reached it. It also ends DELETE_FAILED when it could not be deleted: List Ingest Job Items says what to do.

Errors

Problem details. Per-id codes in errors[].error_code of a 422 BULK_RECORDS_REJECTED (source_row_index is the position in ids or response_ids, which error_params.field names): 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 (neither ids nor response_ids, or both, a field the body does not declare, more than 5,000, no Idempotency-Key), 422 IDEMPOTENCY_KEY_REUSED (also for the same key sent with the other of ids and response_ids), 409 IDEMPOTENCY_KEY_IN_PROGRESS, and 429 beyond the rate limits.

Limits

Create Commuting Periods (v2)

Say how employees got to work, and get the response ids

List Commuting Periods

Find the ids to delete

Delete Employees (v2)

Delete employees with all their periods

Get Ingest Job

Follow the deletion