Assignments

Overview

Use POST /assignments/ to schedule work for a person over a date range. This guide covers how assignment creation interacts with contracts, working days, and non-working days when using the API.

For general assignment concepts and non-API workflows, see Assignments and Weekend assignments

Create an assignment across a date range

A single request can cover multiple weeks:

{
  "personId": 123,
  "projectId": 456,
  "roleId": 789,
  "startDate": "2026-09-07",
  "endDate": "2026-09-18",
  "minutesPerDay": 240,
  "isBillable": true
}

This creates one assignment of four hours per working day over the two-week period. You do not need to create an assignment for each individual date.

The endpoint responds with an array of assignments rather than a single object, so parse the first element even when you created one assignment.

You do not need to add the person to the project first. The request creates the project membership and the project rate for the role if they do not already exist.

Optional fields: phaseId, workstreamId, note, and isNonWorkingDay.

Start and end dates must be working days

For a standard assignment, both startDate and endDate must fall on a weekday. A range that starts or ends on a Saturday or Sunday is rejected with 400. Trim the range to the enclosing weekdays — for example, use Monday to Friday rather than Sunday to Saturday.

Weekends inside the range are fine, and are simply not scheduled.

Similarly, a request whose start and end date both land on a full-day public holiday is rejected unless it is created as a non-working-day assignment, described below.

Contracts and assignment effort

A contract defines a person's capacity and rostered working pattern. An assignment independently defines their scheduled project work.

The API requires you to supply minutesPerDay, and never derives it from the contract. It does not copy or cap this value based on the person's capacity — the only constraint is that the value is between 0 and 1440. If scheduled work exceeds the person's capacity, Runn reports the resulting over-allocation rather than reducing the assignment.

The same minutesPerDay applies throughout the assignment, even if contracted hours vary by weekday or the contract changes during the date range.

Working days within the range

Runn excludes weekends and recorded full non-working days when calculating scheduled effort. These include rostered days off generated from the person's contract, public holidays, and full-day scheduled leave.

For example, if a person is rostered Monday to Wednesday, one assignment spanning Monday to Friday contributes scheduled effort on Monday, Tuesday, and Wednesday. Thursday and Friday are excluded as rostered days off.

Partial-day leave is an exception: a half day of leave does not reduce the assignment's scheduled effort for that day.

For more about how these days are represented and retrieved, see Time offs, which exposes public holidays, leave, and rostered days off.

When multiple assignments are required

One API request is sufficient when the same number of minutes should apply to every working day in a continuous date range.

Create separate assignments when the allocation itself must vary. For example, assigning four hours on Monday and Tuesday but two hours on Wednesday requires two assignment ranges. An integration that needs assignments to exactly match contracted capacity should retrieve the applicable contract and calculate those ranges before creating them.

The ranges must not overlap. Creating a second assignment that overlaps an existing one for the same person, project, role, and workstream is rejected with 400.

Assignments on non-working days

To deliberately schedule work on a weekend or a public holiday, create a single-day assignment — startDate and endDate must be the same date. Multi-day non-working-day assignments are not supported.

You do not need to set isNonWorkingDay. When the field is omitted, Runn sets it automatically if the date falls on a weekend or on a full-day public holiday for that person. Set it explicitly only when you want to be unambiguous; setting it to false on such a date is rejected.

See Weekend assignments for the intended use and effects on capacity and availability.

Billable assignments

isBillable defaults to true. Creating a billable assignment on a non-billable project is rejected with 400, so set isBillable to false for those projects.