# Employee fields

> Every field accepted by POST /employee and returned by GET /employees, with its validation rule.

Send one JSON object per employment to `POST /employee`. A record is rejected unless every required field is present and valid, so check each field here and then the cross-field [business rules](https://developer.paycaptain.com/rules).

Machine-readable: [JSON Schema](https://developer.paycaptain.com/schemas/employee.schema.json) · [OpenAPI](https://developer.paycaptain.com/openapi.json)

## Identity

These three fields decide which record PayCaptain creates or updates. See [Identity and payroll codes](https://developer.paycaptain.com/rules#identity-and-payroll-codes).

### `company`

Company code issued by the PayCaptain team.

- Type: string
- Required
- Rule: Must match your PayCaptain company code exactly.
- Example: `"ABC"`

### `hrEmployeeId`

Your system's identifier for the person. PayCaptain upserts on this value.

- Type: string
- Required
- Rule: Unique per person. Never changes, and is the same across all of that person's employments.
- Example: `"9876543210"`

### `payrollCode`

Identifier for one employment period. HMRC uses this code.

- Type: string
- Required
- Rule: Unique per employment. Never changed once assigned, never reused. A returning employee gets a new code.
- Example: `"123"`

## Personal details

### `firstName`

First name.

- Type: string
- Required
- Rule: Must not be empty.
- Example: `"Jason"`

### `middleName`

Middle name.

- Type: string
- Optional
- Example: `"Z"`

### `lastName`

Last name.

- Type: string
- Required
- Rule: Must not be empty.
- Example: `"Smith"`

### `dateOfBirth`

Date of birth.

- Type: string
- Required
- Rule: A valid date in the past.
- Format: YYYY-MM-DD
- Example: `"2000-01-01"`

### `gender`

Gender as reported to HMRC.

- Type: string
- Required
- Rule: Exactly one of the allowed values. This is an HMRC requirement.
- Allowed values: `"Male"`, `"Female"`
- Example: `"Male"`

### `email`

Home email address.

- Type: string
- Required
- Rule: Valid email format.
- Format: Email address
- Example: `"jason@example.com"`

### `phone`

Phone number. Mobile preferred.

- Type: string
- Optional
- Example: `"08000885262"`

### `photoUrl`

URL of a photo of the employee.

- Type: string
- Optional
- Format: URL
- Example: `"https://example.com/jason.jpg"`

### `niNumber`

National Insurance number.

- Type: string
- Optional
- Rule: A valid UK National Insurance number, no spaces. If unknown, omit the field. Never send a placeholder.
- Pattern: `^(?!BG|GB|KN|NK|NT|TN|ZZ)[A-CEGHJ-PR-TW-Z][A-CEGHJ-NPR-TW-Z][0-9]{6}[A-D]$`
- Example: `"AB123456C"`

## Home address

All five fields are required together and must form a complete UK residential address.

### `mailingStreet`

Street.

- Type: string
- Required
- Rule: Must not be empty.
- Example: `"1 Main Street"`

### `mailingCity`

Town or city.

- Type: string
- Required
- Rule: Must not be empty.
- Example: `"Green City"`

### `mailingStateProvince`

County.

- Type: string
- Required
- Rule: Must not be empty.
- Example: `"Happy County"`

### `mailingPostalCode`

Postcode.

- Type: string
- Required
- Rule: A valid UK postcode, with the single space between outward and inward parts. Trim before testing.
- Pattern: `^(?:[Gg][Ii][Rr] 0[Aa]{2}|(?:[A-Za-z][0-9]{1,2}|[A-Za-z][A-Ha-hJ-Yj-y][0-9]{1,2}|[A-Za-z][0-9][A-Za-z]|[A-Za-z][A-Ha-hJ-Yj-y][0-9]?[A-Za-z]) [0-9][A-Za-z]{2})$`
- Example: `"SW1A 1AA"`

### `mailingCountry`

Country.

- Type: string
- Required
- Rule: Must be exactly "United Kingdom".
- Allowed values: `"United Kingdom"`
- Example: `"United Kingdom"`

## Employment

Date relationships are enforced across fields. See [Date rules](https://developer.paycaptain.com/rules#dates).

### `startDate`

Date this employment started.

- Type: string
- Required
- Rule: Employment periods for the same hrEmployeeId must not overlap.
- Format: YYYY-MM-DD
- Example: `"2023-12-01"`

### `leaveDate`

Date this employment ended. Omit or send null while employed.

- Type: string
- Optional
- Rule: If set, must be on or after startDate.
- Format: YYYY-MM-DD
- Example: `null`

## Pay

Any change to payBasis, salary or rateOfPay must move payEffectiveDate to the date of that change. See [Pay changes](https://developer.paycaptain.com/rules#pay-changes).

### `payBasis`

How the employee is paid.

- Type: string
- Required
- Rule: Exactly one of the allowed values. Decides whether salary or rateOfPay is required.
- Allowed values: `"Hourly"`, `"Salaried"`
- Example: `"Salaried"`

### `salary`

Annual salary.

- Type: number
- Required when payBasis is "Salaried"
- Rule: Annual figure.
- Example: `12000`

### `rateOfPay`

Hourly rate of pay.

- Type: number
- Required when payBasis is "Hourly"
- Rule: Rate per hour.
- Example: `15.25`

### `payEffectiveDate`

Date the current salary or rate took effect.

- Type: string
- Required
- Rule: Between startDate and leaveDate inclusive. Must equal startDate when the employee is first created.
- Format: YYYY-MM-DD
- Example: `"2023-12-01"`

### `payGroup`

Pay Group the employee is paid in.

- Type: string
- Required
- Rule: Must match the name of a Pay Group configured in PayCaptain.
- Example: `"Monthly"`

## Job

### `location`

Work location.

- Type: string
- Optional
- Example: `"Baker Street"`

### `department`

Department.

- Type: string
- Optional
- Example: `"Marketing"`

### `team`

Team.

- Type: string
- Optional
- Example: `"Content"`

### `jobGrade`

Job grade.

- Type: string
- Optional
- Example: `"A1"`

### `jobTitle`

Job title.

- Type: string
- Optional
- Example: `"Content Marketing"`

### `jobEffectiveDate`

Date the job title took effect.

- Type: string
- Optional
- Format: YYYY-MM-DD
- Example: `"2023-12-01"`

### `probationEndDate`

Date the probation period ends.

- Type: string
- Optional
- Format: YYYY-MM-DD
- Example: `"2024-02-01"`

### `contractType`

Contract type.

- Type: string
- Optional
- Allowed values: `"Full Time"`, `"Part Time"`
- Example: `"Full Time"`

## Working pattern

### `normalWeeklyHours`

Normal weekly hours.

- Type: number
- Optional
- Rule: Hours as a whole or decimal number (40 or 37.5). If your source system stores hundredths (4000), divide by 100 first.
- Range: minimum 0
- Example: `40`

### `daysWorkedPerWeek`

Working days per week.

- Type: number
- Optional
- Range: minimum 0, maximum 7
- Example: `5`

### `monday`

Works on a Monday.

- Type: boolean
- Optional
- Example: `true`

### `tuesday`

Works on a Tuesday.

- Type: boolean
- Optional
- Example: `true`

### `wednesday`

Works on a Wednesday.

- Type: boolean
- Optional
- Example: `true`

### `thrursday`

Works on a Thursday.

- Type: boolean
- Optional
- Rule: The field name is spelled this way in API v1.0.1. Send it exactly as shown.
- Example: `true`

### `friday`

Works on a Friday.

- Type: boolean
- Optional
- Example: `true`

### `saturday`

Works on a Saturday.

- Type: boolean
- Optional
- Example: `false`

### `sunday`

Works on a Sunday.

- Type: boolean
- Optional
- Example: `false`

## Bank account

### `bankName`

Name of the bank.

- Type: string
- Optional
- Example: `"Monzo"`

### `bankAccountName`

Name on the account.

- Type: string
- Optional
- Example: `"Jason Smith"`

### `bankAccountNumber`

UK bank account number.

- Type: string
- Optional
- Rule: Exactly 8 digits, sent as a string so leading zeros survive.
- Pattern: `^[0-9]{8}$`
- Example: `"87654321"`

### `bankAccountSortCode`

UK sort code.

- Type: string
- Optional
- Rule: Exactly 6 digits, no hyphens, sent as a string so leading zeros survive.
- Pattern: `^[0-9]{6}$`
- Example: `"123456"`

## HMRC starter details

### `starterDeclaration`

HMRC starter declaration.

- Type: string
- Optional
- Rule: Exactly one of the allowed values, per the HMRC starter checklist.
- Allowed values: `"A"`, `"B"`, `"C"`
- Example: `"A"`

### `studentLoanPlanOne`

Repays Student Loan Plan 1.

- Type: boolean
- Optional
- Default: `false`
- Example: `false`

### `studentLoanPlanTwo`

Repays Student Loan Plan 2.

- Type: boolean
- Optional
- Default: `false`
- Example: `false`

### `studentLoanPlanFour`

Repays Student Loan Plan 4.

- Type: boolean
- Optional
- Default: `false`
- Example: `false`

### `studentLoanPostGraduate`

Repays a Postgraduate Loan.

- Type: boolean
- Optional
- Default: `false`
- Example: `false`


## Minimal valid record

```json
{
  "company": "ABC",
  "hrEmployeeId": "9876543210",
  "payrollCode": "123",
  "firstName": "Jason",
  "lastName": "Smith",
  "dateOfBirth": "2000-01-01",
  "gender": "Male",
  "email": "jason@example.com",
  "mailingStreet": "1 Main Street",
  "mailingCity": "Green City",
  "mailingStateProvince": "Happy County",
  "mailingPostalCode": "SW1A 1AA",
  "mailingCountry": "United Kingdom",
  "startDate": "2023-12-01",
  "payBasis": "Salaried",
  "salary": 12000,
  "payEffectiveDate": "2023-12-01",
  "payGroup": "Monthly"
}
```