Submit Employment Contracts from your HRMS to Kenal Stamps for stamping. This endpoint uses the Employment Contract schema with employer/employee details and optional wage information.

For the full request/response schema, see the API Reference.

Endpoint

POST /api/integration/employment/submit

Request Body

Field	Type	Required	Description
`externalReferenceId`	string	Yes	Your unique identifier for this contract
`confirm`	boolean	No	If `true`, charges the wallet immediately
`useServiceCreditFallback`	boolean	No	Fall back to service credits
`originalFileName`	string	Yes	PDF filename
`fileBase64`	string	Yes	Base64-encoded PDF (max 20MB)
`contentType`	string	Yes	Must be `application/pdf`
`data`	object	Yes	Employment Contract data (see below)

Contract Data (`data`)

Field	Type	Required	Description
`contractDate`	string	Yes	`YYYY-MM-DD`. Required if `confirm=true`
`employer`	object	Yes	Employer details (company or individual)
`employee`	object	Yes	Employee details
`contractDuration`	object	No	Duration with `commencementDate`, `period`, `unit`
`jobTitle`	string	No	Employee's job title
`wageDetails`	object	Conditional	Required for contracts dated 2026-01-01+

Employer (Company)

Field	Type	Required
`partyType`	`COMPANY`	Yes
`name`	string	Yes
`address`	object	Yes
`phoneNumber`	string	Yes
`registrationNumber`	string	Yes
`companyOrigin`	`LOCAL` \| `FOREIGN`	No

Employer (Individual)

Field	Type	Required
`partyType`	`INDIVIDUAL`	Yes
`name`	string	Yes
`address`	object	Yes
`phoneNumber`	string	Yes
`identityType`	`NRIC` \| `PASSPORT`	No
`icNo`	string	No

Employee

Field	Type	Required
`name`	string	Yes
`address`	object	Yes
`phoneNumber`	string	Yes
`identityType`	`NRIC` \| `PASSPORT`	No
`icNo`	string	No

Wage Details

wageDetails is mandatory for contracts with a contractDate of 2026-01-01 or later. This is required for the wage-based exemption calculation.

Field	Type	Description
`basicWage`	number	Monthly base salary (preferred for exemption calculation)
`totalWage`	number or string	Fallback if `basicWage` is missing
`allowances`	array	List of `{ type, amount }` objects
`paymentFrequency`	string	Payment frequency
`paymentDueDate`	string	Payment due date

Response

Same structure as the Loan Agreement response, including contractId, status, duty breakdown, and wallet balances.

Idempotency

Same as Loan Agreement — re-sending the same (x-service-id, externalReferenceId) updates the contract if it's still in a mutable status.

Error Responses

Status	Description
`400`	Validation error (missing `contractDate`, `employer`, `employee`, or `wageDetails` for 2026+ contracts)
`401`	Authentication failed
`402`	Insufficient wallet balance
`403`	Integration is inactive
`409`	Duplicate reference in immutable status

Employment Contract API