> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.yunojuno.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.yunojuno.com/_mcp/server.
# Contracts
## What is a Contract?
On the YunoJuno platform, a **contract** is the formal agreement that governs a single engagement between a **hirer** (a person at a client organisation making a booking) and a **contractor**. It captures the commercial terms of the work — start and end dates, rate, payment frequency, work location — and tracks the engagement from initial draft through to completion.
Every piece of work on the platform flows through a contract. Timesheets are submitted against it, invoices are raised from it, and post-engagement reviews are recorded on it once the work ends.
---
## Actors
Four parties interact with a contract over its lifetime:
| Actor | Who they are | What they do |
| -------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Hirer** | A person at the client organisation making the booking | Creates the contract, configures its terms, and manages its lifecycle — offering it, confirming end dates, and leaving post-contract reviews. |
| **Contractor** | The independent worker being engaged | Receives the offer and accepts or declines it. |
| **Approver** | Another hirer at the same organisation, designated as a sign-off authority | Reviews draft contracts before they can be offered to the contractor. Only relevant when the client has configured internal approval workflows. |
| **Platform** | Automated YunoJuno system processes | Handles time-based transitions — for example, automatically finalising contracts once their end date has passed. |
---
## Lifecycle Overview
A contract moves through four broad phases:
```mermaid
flowchart LR
D["DRAFT PHASE
Contract is being
prepared by the hirer"]
O["OFFER PHASE
Offer has been sent;
contractor is deciding"]
A["ACTIVE PHASE
Contractor is actively
working under the contract"]
C["ENDED
Work has ended"]
D --> O --> A --> C
```
Within each phase there are specific states that capture exactly where the contract sits and what action (if any) is needed next.
---
## States
### Draft Phase
This state represents a contract that is still being prepared and has not yet been seen by the contractor.
| State | What it means |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `DRAFT` | The hirer has created or saved a draft. The contract is fully editable. No offer has been sent; the contractor is not yet aware of it. |
### Offer Phase
This state represents a contract that the contractor has been shown and is deciding on.
| State | What it means |
| --------- | ----------------------------------------------------------------------------------------------- |
| `OFFERED` | The offer has been sent to the contractor and is awaiting their response. The hirer is waiting. |
### Active Phase
These states represent a contract where the contractor has signed and work is underway.
| State | What it means |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `ACCEPTED` | The contractor has accepted the offer and work has begun. |
| `NOTICE_SERVED` | A confirmed end date has been set and both parties know when the engagement will close. The contractor is still working. |
### Ended States
These states are terminal — once a contract reaches one of these states, it does not move again (with one exception noted below).
| State | What it means | How it gets there |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `COMPLETED` | The contract's end date is known and the engagement is closed out. Note that `COMPLETED` does not mean the contractor has stopped working — it means the contract is settled and will no longer change. | Hirer confirms the end date, or the platform completes the contract automatically once the end date has passed. |
| `CANCELLED` | The hirer cancelled the contract after the contractor accepted but before the start date. | Hirer action on an accepted contract. |
| `DECLINED` | The contractor declined the offer. | Contractor action. |
| `REVOKED` | The hirer withdrew the offer before it was accepted. Unlike the other ended states, `REVOKED` is not permanently terminal — the hirer can re-offer the contract, returning it to `OFFERED`. | Hirer action on an offered contract. |
---
## How States Change
### Hirer-initiated transitions
| What the hirer does | Transition |
| ------------------------------------- | ---------------------------------------------- |
| Saves a new draft | New contract → `DRAFT` |
| Offers the contract | `DRAFT` → `OFFERED` |
| Revokes the offer | `OFFERED` → `REVOKED` (can then be re-offered) |
| Hirer serves notice to the contractor | `ACCEPTED` → `NOTICE_SERVED` |
| Cancels the contract | `ACCEPTED` / `NOTICE_SERVED` → `CANCELLED` |
### Contractor-initiated transitions
| What the contractor does | Transition |
| ------------------------ | ---------------------- |
| Accepts the offer | `OFFERED` → `ACCEPTED` |
| Declines the offer | `OFFERED` → `DECLINED` |
### Platform-automated transitions
| Trigger | Transition |
| ------------------------ | ------------------------------------------ |
| Contract end date passes | `ACCEPTED` / `NOTICE_SERVED` → `COMPLETED` |
---
## Contractor Acceptance Through Integrated Experiences
Most clients use YunoJuno's own contractor-facing experience for reviewing and accepting contract offers. In that model, the contractor reads the contract and accepts it directly in YunoJuno.
Some enterprise clients run a more integrated model, where the contractor-facing experience lives in the client's own systems and YunoJuno acts as the underlying system of record for the contract lifecycle. When that operating model has been agreed with YunoJuno, the API can be used to progress the contract after the client has already captured the contractor's explicit acceptance in their own experience.
That is a specialist integration pattern rather than the default platform behaviour. If you are using it, you should treat the contract acceptance checklist as the source of truth for whether the contract is ready to be accepted.
---
## Pre-Offer Approval
Some client organisations require internal sign-off before a contract can be offered to a contractor. This is an optional configuration — if your organisation does not use approval workflows, contracts move directly from draft to offered.
When approval is enabled, the hirer must submit the draft contract to their internal approvers before sending the offer. The approval process runs alongside the contract's `DRAFT` state and does not change the main contract state until it completes.
### Approval States
| State | What it means |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `NOT_APPLICABLE` | This client does not require approval, or the contract has not been submitted yet. The hirer can offer the contract directly. |
| `PENDING` | The contract is ready to be submitted for approval but has not yet been submitted. |
| `APPROVAL_REQUESTED` | The contract has been submitted and is with the approvers. The hirer is waiting for a decision. |
| `APPROVED` | All required approvers have approved. The hirer can now offer the contract to the contractor. |
| `REJECTED` | An approver rejected the request. The hirer must edit the contract and resubmit for approval. |
### How Approval Flows Work
```mermaid
flowchart TD
Draft["Draft contract saved"]
Pending["Approval: PENDING"]
Requested["APPROVAL_REQUESTED"]
Approved["APPROVED"]
Rejected["REJECTED"]
Offer["Hirer can now offer the contract"]
Draft -->|"Hirer selects an approval route and submits"| Pending
Pending --> Requested
Requested --> Approved
Requested --> Rejected
Approved --> Offer
Rejected -->|"Hirer edits contract
and resubmits (PENDING)"| Requested
```
Approvals can require **multiple approvers in sequence** — for example, a line manager approves first, then a finance team member. Each approver's step must be completed before the next person is notified.
If a hirer changes the approval route while a contract is already in the approval process, the existing approvals are cancelled and a new approval chain begins with the new approvers.
---
## Contract Renewals
When a contract is renewed, YunoJuno creates a new contract record for the new period and links it to the original. The new contract inherits the key terms (contractor, IR35 classification, business unit) but can have updated dates and rates.
The new contract begins its own lifecycle from `DRAFT`. All renewal contracts in a chain are linked together, so the full engagement history is preserved across multiple renewal periods.
Renewals may also trigger a fresh approval flow if the client requires approval on renewals.