{ "openapi": "3.0.3", "info": { "title": "PayCaptain API", "version": "1.0.1", "description": "Primary REST API for PayCaptain. Field rules: https://developer.paycaptain.com", "termsOfService": "https://www.paycaptain.com/legal/", "contact": { "email": "developer@paycaptain.com" } }, "externalDocs": { "description": "PayCaptain developer documentation", "url": "https://developer.paycaptain.com" }, "servers": [ { "url": "https://api.paycaptain.com" } ], "security": [ { "APIKeyHeader": [] } ], "paths": { "/employee": { "post": { "operationId": "upsertEmployee", "tags": [ "Employees" ], "summary": "Create or update an employee", "responses": { "200": { "description": "Success" }, "400": { "description": "Error. Fix the record; do not retry unchanged." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/employee" } } } } } }, "/employees": { "get": { "operationId": "getEmployees", "tags": [ "Employees" ], "summary": "Get employees, 50 per page", "responses": { "200": { "description": "A page of employees", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/employee" } } } } }, "204": { "description": "No more pages" }, "400": { "description": "Error" } }, "parameters": [ { "in": "query", "name": "company", "required": true, "description": "Your PayCaptain company code.", "schema": { "type": "string" } }, { "in": "query", "name": "lastModifiedDate", "required": false, "description": "Only employees modified after this date (YYYY-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "in": "query", "name": "includeFormer", "required": false, "description": "Include former employees.", "schema": { "type": "boolean", "default": false } }, { "in": "query", "name": "page", "required": false, "description": "Page number.", "schema": { "type": "integer" } } ] } }, "/shift": { "post": { "operationId": "upsertShift", "tags": [ "Shifts" ], "summary": "Create, update or archive a shift", "responses": { "200": { "description": "Success" }, "400": { "description": "Error. Fix the record; do not retry unchanged." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shift" } } } } } }, "/payment": { "post": { "operationId": "upsertPayment", "tags": [ "Payments" ], "summary": "Create, update or archive a pay element", "responses": { "200": { "description": "Success" }, "400": { "description": "Error. Fix the record; do not retry unchanged." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payment" } } } } } }, "/payslips": { "get": { "operationId": "getPayslips", "tags": [ "Payslips" ], "summary": "Get payslips and their lines for a pay period, 50 per page", "responses": { "200": { "description": "A page of payslips", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/payslip" } } } } }, "204": { "description": "No more pages" }, "400": { "description": "Error" } }, "parameters": [ { "in": "query", "name": "company", "required": true, "description": "Your PayCaptain company code.", "schema": { "type": "string" } }, { "in": "query", "name": "payPeriod", "required": true, "description": "Pay Period reference, as shown in the PayCaptain app.", "schema": { "type": "string" } }, { "in": "query", "name": "page", "required": false, "description": "Page number.", "schema": { "type": "integer" } } ] } } }, "components": { "securitySchemes": { "APIKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "schemas": { "employee": { "type": "object", "properties": { "company": { "type": "string", "description": "Company code issued by the PayCaptain team. Must match your PayCaptain company code exactly.", "example": "ABC" }, "hrEmployeeId": { "type": "string", "description": "Your system's identifier for the person. PayCaptain upserts on this value. Unique per person. Never changes, and is the same across all of that person's employments.", "example": "9876543210" }, "payrollCode": { "type": "string", "description": "Identifier for one employment period. HMRC uses this code. Unique per employment. Never changed once assigned, never reused. A returning employee gets a new code.", "example": "123" }, "firstName": { "type": "string", "minLength": 1, "description": "First name. Must not be empty.", "example": "Jason" }, "middleName": { "type": "string", "description": "Middle name.", "example": "Z" }, "lastName": { "type": "string", "minLength": 1, "description": "Last name. Must not be empty.", "example": "Smith" }, "dateOfBirth": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Date of birth. A valid date in the past.", "example": "2000-01-01" }, "gender": { "type": "string", "enum": [ "Male", "Female" ], "description": "Gender as reported to HMRC. Exactly one of the allowed values. This is an HMRC requirement.", "example": "Male" }, "email": { "type": "string", "format": "email", "description": "Home email address. Valid email format.", "example": "jason@example.com" }, "phone": { "type": "string", "description": "Phone number. Mobile preferred.", "example": "08000885262" }, "photoUrl": { "type": "string", "format": "uri", "description": "URL of a photo of the employee.", "example": "https://example.com/jason.jpg" }, "niNumber": { "type": "string", "pattern": "^(?!BG|GB|KN|NK|NT|TN|ZZ)[A-CEGHJ-PR-TW-Z][A-CEGHJ-NPR-TW-Z][0-9]{6}[A-D]$", "description": "National Insurance number. A valid UK National Insurance number, no spaces. If unknown, omit the field. Never send a placeholder.", "example": "AB123456C" }, "mailingStreet": { "type": "string", "minLength": 1, "description": "Street. Must not be empty.", "example": "1 Main Street" }, "mailingCity": { "type": "string", "minLength": 1, "description": "Town or city. Must not be empty.", "example": "Green City" }, "mailingStateProvince": { "type": "string", "minLength": 1, "description": "County. Must not be empty.", "example": "Happy County" }, "mailingPostalCode": { "type": "string", "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})$", "description": "Postcode. A valid UK postcode, with the single space between outward and inward parts. Trim before testing.", "example": "SW1A 1AA" }, "mailingCountry": { "type": "string", "enum": [ "United Kingdom" ], "description": "Country. Must be exactly \"United Kingdom\".", "example": "United Kingdom" }, "startDate": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Date this employment started. Employment periods for the same hrEmployeeId must not overlap.", "example": "2023-12-01" }, "leaveDate": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Date this employment ended. Omit or send null while employed. If set, must be on or after startDate.", "nullable": true }, "payBasis": { "type": "string", "enum": [ "Hourly", "Salaried" ], "description": "How the employee is paid. Exactly one of the allowed values. Decides whether salary or rateOfPay is required.", "example": "Salaried" }, "salary": { "type": "number", "description": "Annual salary. Annual figure.", "example": 12000 }, "rateOfPay": { "type": "number", "description": "Hourly rate of pay. Rate per hour.", "example": 15.25 }, "payEffectiveDate": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Date the current salary or rate took effect. Between startDate and leaveDate inclusive. Must equal startDate when the employee is first created.", "example": "2023-12-01" }, "payGroup": { "type": "string", "description": "Pay Group the employee is paid in. Must match the name of a Pay Group configured in PayCaptain.", "example": "Monthly" }, "location": { "type": "string", "description": "Work location.", "example": "Baker Street" }, "department": { "type": "string", "description": "Department.", "example": "Marketing" }, "team": { "type": "string", "description": "Team.", "example": "Content" }, "jobGrade": { "type": "string", "description": "Job grade.", "example": "A1" }, "jobTitle": { "type": "string", "description": "Job title.", "example": "Content Marketing" }, "jobEffectiveDate": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Date the job title took effect.", "example": "2023-12-01" }, "probationEndDate": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Date the probation period ends.", "example": "2024-02-01" }, "contractType": { "type": "string", "enum": [ "Full Time", "Part Time" ], "description": "Contract type.", "example": "Full Time" }, "normalWeeklyHours": { "type": "number", "minimum": 0, "description": "Normal weekly hours. Hours as a whole or decimal number (40 or 37.5). If your source system stores hundredths (4000), divide by 100 first.", "example": 40 }, "daysWorkedPerWeek": { "type": "number", "minimum": 0, "maximum": 7, "description": "Working days per week.", "example": 5 }, "monday": { "type": "boolean", "description": "Works on a Monday.", "example": true }, "tuesday": { "type": "boolean", "description": "Works on a Tuesday.", "example": true }, "wednesday": { "type": "boolean", "description": "Works on a Wednesday.", "example": true }, "thrursday": { "type": "boolean", "description": "Works on a Thursday. The field name is spelled this way in API v1.0.1. Send it exactly as shown.", "example": true }, "friday": { "type": "boolean", "description": "Works on a Friday.", "example": true }, "saturday": { "type": "boolean", "description": "Works on a Saturday.", "example": false }, "sunday": { "type": "boolean", "description": "Works on a Sunday.", "example": false }, "bankName": { "type": "string", "description": "Name of the bank.", "example": "Monzo" }, "bankAccountName": { "type": "string", "description": "Name on the account.", "example": "Jason Smith" }, "bankAccountNumber": { "type": "string", "pattern": "^[0-9]{8}$", "description": "UK bank account number. Exactly 8 digits, sent as a string so leading zeros survive.", "example": "87654321" }, "bankAccountSortCode": { "type": "string", "pattern": "^[0-9]{6}$", "description": "UK sort code. Exactly 6 digits, no hyphens, sent as a string so leading zeros survive.", "example": "123456" }, "starterDeclaration": { "type": "string", "enum": [ "A", "B", "C" ], "description": "HMRC starter declaration. Exactly one of the allowed values, per the HMRC starter checklist.", "example": "A" }, "studentLoanPlanOne": { "type": "boolean", "default": false, "description": "Repays Student Loan Plan 1.", "example": false }, "studentLoanPlanTwo": { "type": "boolean", "default": false, "description": "Repays Student Loan Plan 2.", "example": false }, "studentLoanPlanFour": { "type": "boolean", "default": false, "description": "Repays Student Loan Plan 4.", "example": false }, "studentLoanPostGraduate": { "type": "boolean", "default": false, "description": "Repays a Postgraduate Loan.", "example": false } }, "required": [ "company", "hrEmployeeId", "payrollCode", "firstName", "lastName", "dateOfBirth", "gender", "email", "mailingStreet", "mailingCity", "mailingStateProvince", "mailingPostalCode", "mailingCountry", "startDate", "payBasis", "payEffectiveDate", "payGroup" ], "description": "salary: Required when payBasis is \"Salaried\". rateOfPay: Required when payBasis is \"Hourly\"." }, "shift": { "type": "object", "properties": { "shiftId": { "type": "string", "minLength": 1, "description": "Your identifier for the shift record. Unique in your system. Resubmitting the same shiftId updates the record.", "example": "SH-000481" }, "company": { "type": "string", "description": "Company code issued by the PayCaptain team. Must match your PayCaptain company code exactly.", "example": "ABC" }, "hrEmployeeId": { "type": "string", "description": "The person who worked the shift. Must match an employee already sent to PayCaptain.", "example": "9876543210" }, "payrollCode": { "type": "string", "description": "The employment the shift belongs to. Must match that person's active employment.", "example": "123" }, "date": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Date of the shift.", "example": "2026-11-02" }, "type": { "type": "string", "enum": [ "Working", "Holiday", "Sickness", "Unpaid Leave" ], "description": "What the record represents. Exactly one of the allowed values.", "example": "Working" }, "payBasis": { "type": "string", "enum": [ "Hourly", "Daily" ], "description": "How the shift is paid. Exactly one of the allowed values. Decides whether units are hours or days.", "example": "Hourly" }, "units": { "type": "number", "minimum": 0, "description": "Quantity worked. Hours when payBasis is \"Hourly\", days when \"Daily\".", "example": 7.5 }, "rate": { "type": "number", "minimum": 0, "description": "Rate of pay for this shift. Per hour or per day, matching payBasis.", "example": 15.25 }, "sicknessDayType": { "type": "string", "enum": [ "Qualifying", "Q", "Y", "Non Qualifying", "N" ], "description": "Whether a sickness day is a qualifying day. Only meaningful when type is \"Sickness\". \"Qualifying\", \"Q\" and \"Y\" mean a qualifying day; \"Non Qualifying\" and \"N\" mean it is not.", "example": "Qualifying" }, "reason": { "type": "string", "description": "Reason for an absence, mainly for sickness records.", "example": "Flu" }, "archived": { "type": "boolean", "default": false, "description": "Archive the shift so it is not paid. Send true with the same shiftId to remove the shift from payroll. Records are archived, never deleted.", "example": false }, "location": { "type": "string", "description": "Location worked.", "example": "Baker Street" }, "department": { "type": "string", "description": "Department worked.", "example": "Marketing" }, "team": { "type": "string", "description": "Team worked.", "example": "Content" }, "job": { "type": "string", "description": "Job worked.", "example": "Content Marketing" } }, "required": [ "shiftId", "company", "hrEmployeeId", "payrollCode", "date", "type", "payBasis", "units", "rate" ] }, "payment": { "type": "object", "properties": { "paymentId": { "type": "string", "minLength": 1, "description": "Your identifier for the payment record. Unique in your system. Resubmitting the same paymentId updates the record.", "example": "PM-000912" }, "company": { "type": "string", "description": "Company code issued by the PayCaptain team. Must match your PayCaptain company code exactly.", "example": "ABC" }, "hrEmployeeId": { "type": "string", "description": "The person being paid. Must match an employee already sent to PayCaptain.", "example": "9876543210" }, "payrollCode": { "type": "string", "description": "The employment the payment belongs to. Must match that person's active employment.", "example": "123" }, "payCode": { "type": "string", "minLength": 1, "description": "Pay Code for this pay element. Must match a Pay Code Name configured in PayCaptain.", "example": "Bonus" }, "date": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Date of the payment.", "example": "2026-11-28" }, "units": { "type": "number", "description": "Quantity, for example hours.", "example": 1 }, "rate": { "type": "number", "description": "Rate per unit.", "example": 250 }, "description": { "type": "string", "description": "Text shown on the payslip.", "example": "Quarterly bonus" }, "information": { "type": "string", "description": "Extra detail shown behind the help icon on the payslip.", "example": "Q3 performance bonus" }, "archived": { "type": "boolean", "default": false, "description": "Archive the payment so it is not paid. Send true with the same paymentId to remove the payment from payroll. Records are archived, never deleted.", "example": false }, "location": { "type": "string", "description": "Location worked.", "example": "Baker Street" }, "department": { "type": "string", "description": "Department worked.", "example": "Marketing" }, "team": { "type": "string", "description": "Team worked.", "example": "Content" }, "job": { "type": "string", "description": "Job worked.", "example": "Content Marketing" } }, "required": [ "paymentId", "company", "hrEmployeeId", "payrollCode", "payCode", "date", "units", "rate" ] }, "payslip": { "type": "object", "properties": { "payslip": { "type": "object", "properties": { "id": { "type": "string", "description": "Payslip identifier." }, "payeReference": { "type": "string", "description": "Employer PAYE reference." }, "companyName": { "type": "string", "description": "Company name." }, "payPeriod": { "type": "string", "description": "Pay Period reference." }, "published": { "type": "boolean", "description": "Whether the payslip is published to the employee." }, "payPeriodStatus": { "type": "string", "description": "Status of the pay period." }, "payGroup": { "type": "string", "description": "Pay Group name." }, "taxCode": { "type": "string", "description": "Tax code applied." }, "w1m1": { "type": "boolean", "description": "Tax calculated on a week 1 / month 1 basis." }, "niCategory": { "type": "string", "description": "National Insurance category letter." }, "date": { "type": "string", "description": "Pay date." }, "periodNumber": { "type": "integer", "description": "Tax period number." }, "pensionNotice": { "type": "string", "description": "Pension notice text." }, "message": { "type": "string", "description": "Message shown on the payslip." }, "taxYear": { "type": "string", "description": "Tax year." }, "url": { "type": "string", "description": "Link to the payslip." } } }, "employee": { "type": "object", "properties": { "hrEmployee_Id": { "type": "string", "description": "Your identifier for the person. Note the spelling differs from hrEmployeeId on requests." }, "payrollCode": { "type": "string", "description": "Payroll code of the employment." }, "firstName": { "type": "string", "description": "First name." }, "middleName": { "type": "string", "description": "Middle name." }, "lastName": { "type": "string", "description": "Last name." }, "email": { "type": "string", "description": "Email address." }, "mailingStreet": { "type": "string", "description": "Home address: street." }, "mailingCity": { "type": "string", "description": "Home address: town or city." }, "mailingState": { "type": "string", "description": "Home address: county." }, "mailingPostalCode": { "type": "string", "description": "Home address: postcode." }, "MailingCountry": { "type": "string", "description": "Home address: country. Note the capital M." }, "phone": { "type": "string", "description": "Phone number." }, "niNumber": { "type": "string", "description": "National Insurance number." } } }, "totals": { "type": "object", "properties": { "gross": { "type": "number", "description": "Gross pay this period." }, "taxable": { "type": "number", "description": "Taxable pay this period." }, "net": { "type": "number", "description": "Net pay this period." }, "benefits": { "type": "number", "description": "Benefits this period." }, "tax": { "type": "number", "description": "Income tax this period." }, "employerNationalInsurance": { "type": "number", "description": "Employer National Insurance this period." }, "employeeNationalInsurance": { "type": "number", "description": "Employee National Insurance this period." }, "employeePensoin": { "type": "number", "description": "Employee pension this period. Spelled this way in API v1.0.1." }, "employerPensoin": { "type": "number", "description": "Employer pension this period. Spelled this way in API v1.0.1." } } }, "ytd": { "type": "object", "properties": { "gross": { "type": "number", "description": "Gross pay, year to date." }, "taxable": { "type": "number", "description": "Taxable pay, year to date." }, "net": { "type": "number", "description": "Net pay, year to date." }, "benefits": { "type": "number", "description": "Benefits, year to date." }, "tax": { "type": "number", "description": "Income tax, year to date." }, "employeePension": { "type": "number", "description": "Employee pension, year to date." }, "employerPension": { "type": "number", "description": "Employer pension, year to date." } } }, "previousEmployment": { "type": "object", "properties": { "taxable": { "type": "number", "description": "Taxable pay from previous employment this tax year." }, "tax": { "type": "number", "description": "Tax paid in previous employment this tax year." } } }, "thisEmployment": { "type": "object", "properties": { "taxable": { "type": "number", "description": "Taxable pay in this employment this tax year." }, "tax": { "type": "number", "description": "Tax paid in this employment this tax year." } } }, "payslipLines": { "type": "array", "items": { "type": "object", "properties": { "payslipLineId": { "type": "string", "description": "Line identifier." }, "payslipId": { "type": "string", "description": "Parent payslip identifier." }, "units": { "type": "integer", "description": "Units." }, "amount": { "type": "number", "description": "Amount per unit." }, "total": { "type": "number", "description": "Line total." }, "code": { "type": "string", "description": "Pay Code." }, "description": { "type": "string", "description": "Text shown on the payslip." }, "locationCode": { "type": "string", "description": "Location." }, "departmentCode": { "type": "string", "description": "Department." }, "teamCode": { "type": "string", "description": "Team." }, "jobCode": { "type": "string", "description": "Job." }, "isDeduction": { "type": "boolean", "description": "Line is a deduction." }, "isBenefit": { "type": "boolean", "description": "Line is a benefit." }, "excludedfromPayslip": { "type": "boolean", "description": "Line is hidden on the employee's payslip." }, "information": { "type": "string", "description": "Extra detail shown behind the help icon." } } } } } } } } }