Kenal Stamps Docs

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/submit

Request Body

FieldTypeRequiredDescription
externalReferenceIdstringYesYour unique identifier for this contract
confirmbooleanNoIf true, charges the wallet immediately
originalFileNamestringYesPDF filename. Required on every call, but the file is only stored when the contract is first created; resubmissions keep the original file
fileBase64stringYesBase64-encoded PDF (max 20MB)
contentTypestringYesSend 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
dataobjectYesTenancy data (see below)

Tenancy Data (data)

FieldTypeRequiredDescription
contractDatestringYesYYYY-MM-DD, not in the future
partiesarrayYesAt least one Landlord and one Tenant
propertyAddressstringYesAddress of the let property
monthlyRentnumberYesMonthly rent in RM (0 or more)
leaseDurationMonthsintegerYesLease term in months; selects the rate
leaseStartDatestringYesYYYY-MM-DD
leaseEndDatestringYesYYYY-MM-DD
numberOfDuplicatesintegerYes0 to 10. Must be sent, even when 0
propertyType, securityDeposit, rentPaymentDay, ...NoOptional, 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.

FieldTypeRequiredDescription
namestringYesParty name
roleLandlord | TenantYesExact, case-sensitive
partyTypeindividual | companyYesParty type
addressobjectYesaddressLine1, addressLine2 (each longer than 3 characters), 5-digit postcode, city, Malaysian state, country
contactNumberstringYesPhone number
emailstringNoEmail address
identityTypeNRIC | PASSPORTIndividuals
identityNumberstringIndividuals12-digit NRIC or passport number
passportCountrystringPassport holdersISO-3166 alpha-2, e.g. SG
registrationNumberstringCompaniesBusiness registration number
businessTypesole_proprietor | partnership | cooperative | sdn_bhd | berhad | pltCompanies
companyOriginlocal | foreignCompanies
ownerNamestringSole proprietorsOwner's name
ownerMykadstringSole proprietorsOwner's 12-digit MyKad

Duty

  • Base duty (baseDuty) = units x ratePerUnit, or RM10 if that comes to less, where units = ceil(monthlyRent x 12 / 250). The rent is always annualised, also for leases under a year. So units 5 at ratePerUnit RM1 gives baseDuty RM10.
  • 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

StatusDescription
400Validation error (missing fields, lease dates disagree with leaseDurationMonths, incomplete parties, empty or non-PDF file, confirm blocked)
401Authentication failed
402Insufficient wallet balance (when confirm=true)
403Integration is inactive
409Reference used by another organization or for another kind of contract, or contract no longer editable (past Pending)
404Contract not found (the contract disappeared while the request was being processed)
413File exceeds 20MB
503Tenancy document type not configured