Skip to main content
POST
CSV Upload
← Employees API
Deprecated. Use POST /v2/employees/commuting: the commuting periods as JSON records in the request, all or nothing, idempotent, with no file to upload. This endpoint keeps working; its responses carry Deprecation and Link: </v2/employees/commuting>; rel="successor-version" headers. Its responses also carry Sunset: Fri, 30 Apr 2027 00:00:00 GMT: the endpoint is retired on April 30, 2027 (see the changelog).
Generate a presigned S3 URL for bulk importing employee commuting periods via CSV. After uploading the file, the system processes each row to create commuting period records and trigger emission calculations.

Request

Headers

string
required
Your API key for authenticationExample: sk_live_1234567890abcdef
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Body Parameters

string
required
Name of the CSV file to uploadExample: commuting-data-2025.csv

CSV Format

The CSV file should contain the following columns:

One response per employee and period

The in_itinere rows of an employee with the same start_date and end_date are one commuting response, one row per transport, written whole or not at all. Ana goes by car on Monday and Tuesday, by bus on Wednesday and Thursday, and works from home on Friday:
A response is written when:
  • Each weekday, in weekly_travels or weekly_telecommuting, is in one of its rows. A trip with several legs (for example, walking to the bus stop and then the bus) goes in its main transport only.
  • The time at home (weekly_telecommuting, total_telecommuting_hours or a telecommuting row) is in one row.
  • It shares no day with another response of the employee, in the file or already stored. A stored response is not updated by the upload: to change it, edit or delete its periods (Update Commuting Period, Delete Commuting Period) or do it in the app. Uploading the same file again refuses every response already stored.
  • None of its rows fails.
Otherwise every row of the response is reported as failed, with the reason, and nothing of it is written. The other responses of the file are written. An in_labore row is not part of a response: it is written as a period of its own and is not checked against the employee’s responses. Uploading it again (same employee, dates and commuting_type) updates that period, unless the period is a survey answer, which is never overwritten: the row fails.

Large files

A file of more than 4,000 rows is processed in parts of about 4,000 rows. A part is not cut between two rows of a response that are next to each other and have the same organization_id, employee_email, employee_name, start_date and end_date cells: it runs up to 16 rows past its size to keep them together. So write the rows of a response together and identify the employee the same way on each. A response whose rows are far apart can still fall in two parts: the later part completes it (a telecommuting row in the earlier part stays a period of its own instead of going on the first transport), but if the later part’s rows are refused, the earlier part’s rows stay written. To change such a response, edit or delete its periods.

Response

string
Presigned S3 URL — upload your CSV via PUT to this URL
string
File name as stored
string
UUID of the created file record
string
S3 object key where the file will be stored
string
Confirmation message
string
UUID of the organization the file belongs to

Example

Successful Response

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

403 Forbidden

Cause: The authenticated user is not a member of the organization

422 Unprocessable Entity

Cause: Missing required field (file_name)

List Commuting Periods

Browse imported commuting periods

Create Commuting Period

Create a single commuting period manually