Tenancy Agreement API
Submit tenancy agreements via the Partner Integration API.
Submit Tenancy Agreements to Kenal Stamps for stamping. This endpoint handles contract creation, PDF upload, and optional immediate confirmation (wallet charging). There is no documentType field: the platform's single tenancy document type is used.
For the full request/response schema, see the API Reference.
Endpoint
POST /api/integration/tenancy/submitRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
externalReferenceId | string | Yes | Your unique identifier for this contract |
confirm | boolean | No | If true, charges the wallet immediately |
originalFileName | string | Yes | PDF filename. Required on every call, but the file is only stored when the contract is first created; resubmissions keep the original file |
fileBase64 | string | Yes | Base64-encoded PDF (max 20MB) |
contentType | string | Yes | Send application/pdf. Any content type containing pdf (case-insensitive) requires the decoded file to start with the %PDF- header, else 400; the value is not otherwise checked |
data | object | Yes | Tenancy data (see below) |
Tenancy Data (data)
| Field | Type | Required | Description |
|---|---|---|---|
contractDate | string | Yes | YYYY-MM-DD, not in the future |
parties | array | Yes | At least one Landlord and one Tenant |
propertyAddress | string | Yes | Address of the let property |
monthlyRent | number | Yes | Monthly rent in RM (0 or more) |
leaseDurationMonths | integer | Yes | Lease term in months; selects the rate |
leaseStartDate | string | Yes | YYYY-MM-DD |
leaseEndDate | string | Yes | YYYY-MM-DD |
numberOfDuplicates | integer | Yes | 0 to 10. Must be sent, even when 0 |
propertyType, securityDeposit, rentPaymentDay, ... | No | Optional, see the API Reference |
leaseDurationMonths must agree with the dates, or the request is rejected with 400. Accepted: the inclusive count (whole months from the start date to the day after the end date, any leftover days counting as a further month), e.g. 2026-01-01 to 2026-12-31 = 12 and 2026-01-01 to 2027-01-15 = 13; or, when the end date is exactly N months after the start (2026-01-01 to 2027-01-01), N.
Party Object
Every party needs full details.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Party name |
role | Landlord | Tenant | Yes | Exact, case-sensitive |
partyType | individual | company | Yes | Party type |
address | object | Yes | addressLine1, addressLine2 (each longer than 3 characters), 5-digit postcode, city, Malaysian state, country |
contactNumber | string | Yes | Phone number |
email | string | No | Email address |
identityType | NRIC | PASSPORT | Individuals | |
identityNumber | string | Individuals | 12-digit NRIC or passport number |
passportCountry | string | Passport holders | ISO-3166 alpha-2, e.g. SG |
registrationNumber | string | Companies | Business registration number |
businessType | sole_proprietor | partnership | cooperative | sdn_bhd | berhad | plt | Companies | |
companyOrigin | local | foreign | Companies | |
ownerName | string | Sole proprietors | Owner's name |
ownerMykad | string | Sole proprietors | Owner's 12-digit MyKad |
Duty
- Base duty (
baseDuty) =unitsxratePerUnit, or RM10 if that comes to less, whereunits= ceil(monthlyRentx 12 / 250). The rent is always annualised, also for leases under a year. Sounits5 atratePerUnitRM1 givesbaseDutyRM10. - Rate by
leaseDurationMonths: RM1 up to 12 months, RM3 up to 36, RM5 up to 60, RM7 above. - Plus RM10 per duplicate.
- Plus a late-stamping penalty when submitted more than 30 days after
contractDate: 31 to 90 days late, 10% of the base duty or RM50, whichever is higher; over 90 days, 20% of the base duty or RM100, whichever is higher. - Under LHDN's PKPS 2026 programme, the late penalty is 0 for contracts dated 2023 to 2025 when submitted on or before 31 Dec 2026 (Malaysia time). From 1 Jan 2027 the normal penalty applies again.
Response
{
"contractId": "a1b2c3d4-...",
"status": "Confirmed",
"organizationId": "...",
"partnerId": "...",
"externalReferenceId": "TEN-001",
"documentType": "Tenancy Agreement",
"dutyType": "ad_valorem",
"confirmed": true,
"dutyAmount": 49,
"dutyBreakdown": {
"annualRent": 9600,
"units": 39,
"ratePerUnit": 1,
"baseDuty": 39,
"duplicateFees": 10,
"latePenalty": 0
},
"message": "Contract confirmed. ...",
"balances": {
"serviceCreditBalance": 50,
"exemptionCreditBalance": 0,
"dutyWalletBalance": 1000.00
}
}dutyAmount is the amount charged when confirmed is true; otherwise it is the estimate if stamped today.
Idempotency
Re-sending the same (x-service-id, externalReferenceId) updates the existing contract's data while it is Queued or Pending. Send confirm: true on a later call to confirm it.
If the contract has already been confirmed, or the reference was used for another kind of contract, the request returns 409 Conflict.
Error Responses
| Status | Description |
|---|---|
400 | Validation error (missing fields, lease dates disagree with leaseDurationMonths, incomplete parties, empty or non-PDF file, confirm blocked) |
401 | Authentication failed |
402 | Insufficient wallet balance (when confirm=true) |
403 | Integration is inactive |
409 | Reference used by another organization or for another kind of contract, or contract no longer editable (past Pending) |
404 | Contract not found (the contract disappeared while the request was being processed) |
413 | File exceeds 20MB |
503 | Tenancy document type not configured |