---
title: "Endpoint to create a new retainer for a project."
method: POST
path: "/projects/{projectId}/retainers"
tags: ["retainers"]
---

# Endpoint to create a new retainer for a project.

`POST /projects/{projectId}/retainers`

As soon as a retainer is created for a project, the project will be marked as a retainer project.
            Based on the Start and End dates of the retainer, the retainer budgets will be created automatically.
            Retainers cannot overlap. There can only be one active retainer per project at a time (no end date and/or including the current date).
            
            The user needs to have the ProjectMasterData write permission for the project to access this endpoint.

<Check title="Required Permissions" icon="key">Any authenticated user.</Check>

## Path parameters

- `projectId` string, uuid, required

## Headers

- `Authorization` string, required

## Request body

- RetainerForm
  - `timeBudget` integer — The time budget per retainer period in seconds. The default budget amount for new budgets in this retainer.
  - `timezone` string, nullable — The timezone for when new budgets are created.
  - `rollOverUnderspentBudget` boolean — Whether underspent budgets should be rolled over to the next period.
  - `rollOverOverspentBudget` boolean — Whether overspent budgets should be rolled over to the next period.
  - `startDate` string, date-time — The start of the retainer contract.
  - `endDate` string, date-time, nullable — The end of the retainer contract until new budgets will be created. Optional.
  - `syncProjectDates` boolean — Whether the project start and due dates should be synced to the retainer start and end dates.

## Response `200`

OK

- Retainer
  - `timeBudget` integer — The time budget per retainer period in seconds. The default budget amount for new budgets in this retainer.
  - `timezone` string, nullable — The timezone for when new budgets are created.
  - `rollOverUnderspentBudget` boolean — Whether underspent budgets should be rolled over to the next period.
  - `rollOverOverspentBudget` boolean — Whether overspent budgets should be rolled over to the next period.
  - `startDate` string, date-time — The start of the retainer contract.
  - `endDate` string, date-time, nullable — The end of the retainer contract until new budgets will be created. Optional.
  - `syncProjectDates` boolean — Whether the project start and due dates should be synced to the retainer start and end dates.
  - `id` string, uuid — The id of the retainer.
  - `retainerPeriod` string, nullable — The period for new budgets in this retainer. Currently only 'monthly' is supported.
  - `projectId` string, uuid — The project this retainer is associated with.
  - `isExternal` boolean — Whether the retainer belongs to an external project.
  - `retainerBudgets` RetainerBudget[], nullable — The budgets for this retainer. Each budget period (month) gets its own budget.
    - `id` string, uuid — The id of the retainer budget.
    - `timeBudget` integer — The budget for this retainer period in seconds. Based on the carry over option selected in the retainer settings, the timebudget is adjusted by the carry over from the previous period.
    - `trackedDuration` integer — The sum of tracked time in this retainer period. Contains billable and non-billable hours if the DeductNonBillableHours flag is set to true. Contains only billable hours if the DeductNonBillableHours flag is set to false. Time entries belong to the retainer period if their StartDate is between the StartDate and EndDate of the retainer period.
    - `startDate` string, date-time — The start of the retainer period in UTC.
    - `endDate` string, date-time — The end of the retainer period in UTC.
  - `createdOn` string, date-time — The date this retainer was created.
  - `createdBy` string, uuid — The id of the user who created this retainer.
  - `updatedOn` string, date-time — The date this retainer was last modified.
  - `updatedBy` string, uuid — The id of the user who last modified this retainer.

## Other responses

- `400` — Bad Request
- `404` — Not Found

---

[API](https://skmtc.net/awork-io/apis/api-v1-reference.md) · [All operations](https://skmtc.net/awork-io/apis/api-v1-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/awork-io/api-v1-reference/versions/f784a53f60df/schema)