---
title: "Create a work schedule"
method: POST
path: "/companies/{company}/work-schedules"
tags: ["Work Schedules"]
---

# Create a work schedule

`POST /companies/{company}/work-schedules`

## Request

- Base URL: `https://api.factuarea.com/v1`
- URL: `https://api.factuarea.com/v1/companies/{company}/work-schedules`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Create a weekly work schedule for your company (resolved from the API key).
- `name` and `week_pattern` are required; `mode` defaults to `validated`. `week_pattern` lists ISO weekdays (1..7) with ordered, non-overlapping `HH:MM` ranges (empty `ranges` = rest day).
- Returns the schedule with its `id`; `weekly_hours` is derived.

## Path parameters

- `company` string, uuid, required

## Headers

- `Idempotency-Key` string
- `Factuarea-Version` string, date

## Request body

- CreateWeeklyScheduleRequest
  - `name` string, required: Weekly schedule name.
  - `mode` 'validated' | 'real_clocking', required: Schedule mode: `validated` (assumed fulfilled) or `real_clocking` (computed from real clock entries).
  - `week_pattern` object[], required: Weekly pattern: list of days with their time ranges.
    - `day` integer, required: Day of the week in ISO 8601 format (1 Monday .. 7 Sunday).
    - `ranges` object[], required: Time ranges for the day (empty = rest day).
      - `start` string, required: Range start time (HH:MM, 00:00-23:59).
      - `end` string, required: Range end time (HH:MM; 24:00 is allowed as end of workday).
      - `flexible` boolean
      - `required_minutes` integer, nullable

## Response `201`

Work schedule created. The `Location` header contains the canonical URL of the new work schedule.

- object
  - `data` WeeklySchedule, required: A fixed weekly work schedule for the Control Horario (time tracking) module. Defines, per weekday, the expected time ranges (from which the expected hours and the planned start time are derived). Its `mode` decides how balances are computed downstream: `validated` (the period is assumed fulfilled unless an exception) or `real_clocking` (only real clock-ins count).
    - `id` string, uuid, required: Opaque identifier of the work schedule, a UUID v7 (e.g. `01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a9b`).
    - `object` 'work_schedule', required: Always `work_schedule`.
    - `name` string, required: Human-readable name of the schedule (e.g. `Jornada partida`).
    - `mode` 'validated' | 'real_clocking', required: How the schedule computes balances: `validated` (period assumed fulfilled unless an exception) or `real_clocking` (only real clock-ins count).
    - `week_pattern` object[], required: Weekly pattern: one entry per configured weekday with its ordered, non-overlapping time ranges. A weekday absent from the list (or with an empty `ranges`) is a rest day.
      - `day` integer, required: ISO 8601 weekday (1 = Monday … 7 = Sunday).
      - `ranges` object[], required: Ordered, non-overlapping time ranges worked that day (empty = rest day).
        - `start` string, required: Range start time (HH:MM, 24h).
        - `end` string, required: Range end time (HH:MM, 24h).
    - `weekly_hours` number, float, required: Total weekly hours derived from the sum of all time ranges in the pattern.
    - `status` 'active' | 'archived', required: Lifecycle status: `active` (assignable) or `archived` (retired from use).
    - `created_at` string, date-time, nullable, required: Creation timestamp (ISO 8601).
    - `updated_at` string, date-time, nullable, required: Last-update timestamp (ISO 8601).

## Other responses

- `400`: `parameter_unknown` with `subcode` `retired_active_profile_header`: the retired `X-Active-Profile` header was sent; the company goes in the path. `parameter_invalid_format` on `Factuarea-Version`: the header is not a `YYYY-MM-DD` date. `unsupported_api_version`: the `Factuarea-Version` date is not a supported version.
- `401`: Missing or invalid API key.
- `403`: The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).
- `404`: The requested resource does not exist or belongs to another company. `profile_not_found`: the company in the path does not exist, is not in the API key scope or belongs to the other environment (live or test).
- `409`: The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.
- `422`: Validation failed. The `error.param` field identifies which input is invalid.
- `429`: Rate limit exceeded. Retry after the duration in `Retry-After`.
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/factuarea/apis/factuarea-public-api.md) · [All operations](https://skmtc.dev/factuarea/apis/factuarea-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/factuarea/apis/factuarea-public-api/revisions/718e77934422?raw)