Contracts | YunoJuno API Documentation

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:

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

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.