Skip to main content
PUT
Create Job Edition

Authorizations

Authorization
string
header
required

Get token from Auth0 and paste it here

Headers

If-Match
string | null
X-Acting-User
string | null

The person acting through the access credential, recorded as created_by of what the request writes. Audit only: access is checked on the credential.

Required string length: 1 - 255

Path Parameters

organization_id
string
required
employee_id
string
required

Body

application/json
valid_from
string<date>
required
valid_to
string<date>
required
start_date
string<date> | null

Employment start date

contracted_weekly_hours
integer | null
default:40

Contracted weekly hours

department
string | null

Department

contracted_weekdays
enum<string>[] | null

Contracted working days of the week

Required array length: 1 - 7 elements

Days of the week.

Available options:
Monday,
Tuesday,
Wednesday,
Thursday,
Friday,
Saturday,
Sunday
worker_type
enum<string>
default:EMPLOYEE

UK employment status (employee, worker, director)

Available options:
EMPLOYEE,
DIRECTOR
director_since
string<date> | null

Date appointed as director (None if not a director)

pay_basis
enum<string>
default:SALARIED

How pay and hours are determined

Available options:
SALARIED,
HOURLY
apprenticeship
Apprenticeship · object | null

Apprenticeship details (None = not an apprentice)

p45_issued
boolean
default:false

True once a P45 has been issued for this employment (post-cessation). Drives the weekly NIC earnings period for post-P45 payments. Distinct from the inbound-starter p45_gross_pay/p45_tax_amount in tax, which carry a new joiner's prior-employer figures.

irregular_payment_pattern
boolean
default:false

The employee is not paid every pay period (casual, seasonal, annual director pay). Reported to HMRC as IrrEmp so the employment is not treated as ceased after a run of periods without payment.

ordinarily_works_in_uk
boolean
default:true

Whether the worker's ordinary place of work under their contract is in the UK (per TPR Detailed Guidance No. 1). If False, the employer has no statutory auto-enrolment duties for this worker. Employees on temporary overseas secondment who remain on UK payroll and whose ordinary place of work is the UK stay True: this flag reflects the contractual base, not the employee's current physical location.

proration_basis
ProrationBasis · object | null

Employee-level override of the inherited proration basis

Response

Successful Response

edition
integer
required
read-only
valid_from
string<date>
required
valid_to
string<date>
required
created_at
string<date-time>
required
read-only
created_by
string
required
read-only

Who wrote the edition: the acting user (X-Acting-User, else the access credential), system for our own writes, or <authority>:<notice> for a write on an authority's behalf, e.g. hmrc:P6.

start_date
string<date> | null

Employment start date

contracted_weekly_hours
integer | null
default:40

Contracted weekly hours

department
string | null

Department

contracted_weekdays
enum<string>[] | null

Contracted working days of the week

Required array length: 1 - 7 elements

Days of the week.

Available options:
Monday,
Tuesday,
Wednesday,
Thursday,
Friday,
Saturday,
Sunday
worker_type
enum<string>
default:EMPLOYEE

UK employment status (employee, worker, director)

Available options:
EMPLOYEE,
DIRECTOR
director_since
string<date> | null

Date appointed as director (None if not a director)

pay_basis
enum<string>
default:SALARIED

How pay and hours are determined

Available options:
SALARIED,
HOURLY
apprenticeship
Apprenticeship · object | null

Apprenticeship details (None = not an apprentice)

p45_issued
boolean
default:false

True once a P45 has been issued for this employment (post-cessation). Drives the weekly NIC earnings period for post-P45 payments. Distinct from the inbound-starter p45_gross_pay/p45_tax_amount in tax, which carry a new joiner's prior-employer figures.

irregular_payment_pattern
boolean
default:false

The employee is not paid every pay period (casual, seasonal, annual director pay). Reported to HMRC as IrrEmp so the employment is not treated as ceased after a run of periods without payment.

ordinarily_works_in_uk
boolean
default:true

Whether the worker's ordinary place of work under their contract is in the UK (per TPR Detailed Guidance No. 1). If False, the employer has no statutory auto-enrolment duties for this worker. Employees on temporary overseas secondment who remain on UK payroll and whose ordinary place of work is the UK stay True: this flag reflects the contractual base, not the employee's current physical location.

proration_basis
ProrationBasis · object | null

Employee-level override of the inherited proration basis

end_date
string<date> | null

Last day of employment