PayCaptain Developers
llms.txtOpenAPISupport

Field validation

Employee fields

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

View as Markdown

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.

Machine-readable: JSON Schema · OpenAPI

Identity#

These three fields decide which record PayCaptain creates or updates. See Identity and payroll codes.

companystringRequired

Company code issued by the PayCaptain team.

Rule
Must match your PayCaptain company code exactly.
Example
"ABC"
hrEmployeeIdstringRequired

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

Rule
Unique per person. Never changes, and is the same across all of that person's employments.
Example
"9876543210"
payrollCodestringRequired

Identifier for one employment period. HMRC uses this code.

Rule
Unique per employment. Never changed once assigned, never reused. A returning employee gets a new code.
Example
"123"

Personal details#

firstNamestringRequired

First name.

Rule
Must not be empty.
Example
"Jason"
middleNamestringOptional

Middle name.

Example
"Z"
lastNamestringRequired

Last name.

Rule
Must not be empty.
Example
"Smith"
dateOfBirthstringRequired

Date of birth.

Rule
A valid date in the past.
Format
YYYY-MM-DD
Example
"2000-01-01"
genderstringRequired

Gender as reported to HMRC.

Rule
Exactly one of the allowed values. This is an HMRC requirement.
Allowed values
"Male" "Female"
Example
"Male"
emailstringRequired

Home email address.

Rule
Valid email format.
Format
Email address
Example
"jason@example.com"
phonestringOptional

Phone number. Mobile preferred.

Example
"08000885262"
photoUrlstringOptional

URL of a photo of the employee.

Format
URL
Example
"https://example.com/jason.jpg"
niNumberstringOptional

National Insurance number.

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.

mailingStreetstringRequired

Street.

Rule
Must not be empty.
Example
"1 Main Street"
mailingCitystringRequired

Town or city.

Rule
Must not be empty.
Example
"Green City"
mailingPostalCodestringRequired

Postcode.

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"
mailingCountrystringRequired

Country.

Rule
Must be exactly "United Kingdom".
Allowed values
"United Kingdom"
Example
"United Kingdom"

Employment#

Date relationships are enforced across fields. See Date rules.

startDatestringRequired

Date this employment started.

Rule
Employment periods for the same hrEmployeeId must not overlap.
Format
YYYY-MM-DD
Example
"2023-12-01"
leaveDatestringOptional

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

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.

payBasisstringRequired

How the employee is paid.

Rule
Exactly one of the allowed values. Decides whether salary or rateOfPay is required.
Allowed values
"Hourly" "Salaried"
Example
"Salaried"
salarynumberRequired when payBasis is "Salaried"

Annual salary.

Rule
Annual figure.
Example
12000
rateOfPaynumberRequired when payBasis is "Hourly"

Hourly rate of pay.

Rule
Rate per hour.
Example
15.25
payEffectiveDatestringRequired

Date the current salary or rate took effect.

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

Pay Group the employee is paid in.

Rule
Must match the name of a Pay Group configured in PayCaptain.
Example
"Monthly"

Job#

locationstringOptional

Work location.

Example
"Baker Street"
departmentstringOptional

Department.

Example
"Marketing"
teamstringOptional

Team.

Example
"Content"
jobGradestringOptional

Job grade.

Example
"A1"
jobTitlestringOptional

Job title.

Example
"Content Marketing"
jobEffectiveDatestringOptional

Date the job title took effect.

Format
YYYY-MM-DD
Example
"2023-12-01"
probationEndDatestringOptional

Date the probation period ends.

Format
YYYY-MM-DD
Example
"2024-02-01"
contractTypestringOptional

Contract type.

Allowed values
"Full Time" "Part Time"
Example
"Full Time"

Working pattern#

normalWeeklyHoursnumberOptional

Normal weekly hours.

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
daysWorkedPerWeeknumberOptional

Working days per week.

Range
minimum 0, maximum 7
Example
5
mondaybooleanOptional

Works on a Monday.

Example
true
tuesdaybooleanOptional

Works on a Tuesday.

Example
true
wednesdaybooleanOptional

Works on a Wednesday.

Example
true
thrursdaybooleanOptional

Works on a Thursday.

Rule
The field name is spelled this way in API v1.0.1. Send it exactly as shown.
Example
true
fridaybooleanOptional

Works on a Friday.

Example
true
saturdaybooleanOptional

Works on a Saturday.

Example
false
sundaybooleanOptional

Works on a Sunday.

Example
false

Bank account#

bankNamestringOptional

Name of the bank.

Example
"Monzo"
bankAccountNumberstringOptional

UK bank account number.

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

UK sort code.

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

HMRC starter details#

starterDeclarationstringOptional

HMRC starter declaration.

Rule
Exactly one of the allowed values, per the HMRC starter checklist.
Allowed values
"A" "B" "C"
Example
"A"

Minimal valid record#

{
  "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"
}