This guide walks you through the essential steps to start submitting contracts via the Kenal Stamps Partner Integration API.

Prerequisites

A Kenal Stamps organization with API Integrations enabled
An integration instance created in the dashboard (provides your credentials)

Step 1: Get Your Credentials

An org admin creates an integration instance at /dashboard/admin/integrations. This gives you:

Credential	Purpose
`integrationId` (UUID)	Sent as `x-service-id` header on every request
`apiSecret`	Used to sign your API requests (HMAC-SHA256)
`webhookSecret`	Used to verify webhook deliveries to your endpoint

Treat apiSecret and webhookSecret as passwords. They cannot be recovered — only rotated.

Step 2: Sign Your Request

All API requests must be signed with HMAC-SHA256. See the Authentication guide for full details.

sign-request.ts

import crypto from "crypto";

function signRequest(method: string, path: string, body: string, apiSecret: string) {
  const timestamp = new Date().toISOString();
  const bodyHash = crypto.createHash("sha256").update(body).digest("hex");
  const stringToSign = `${method}\n${path}\n${timestamp}\n${bodyHash}`;
  const signature = crypto.createHmac("sha256", apiSecret).update(stringToSign).digest("hex");

  return { timestamp, signature };
}

Step 3: Submit a Contract

Choose the endpoint for your contract type:

Loan Agreement → POST /api/integration/loan/submit — Guide
Employment Contract → POST /api/integration/employment/submit — Guide

Example: Submit a Loan Agreement

curl -X POST https://stamps.kenal.io/api/integration/loan/submit \
  -H "Content-Type: application/json" \
  -H "x-service-id: YOUR_INTEGRATION_ID" \
  -H "x-timestamp: 2026-03-15T10:00:00.000Z" \
  -H "x-signature: COMPUTED_HMAC_SIGNATURE" \
  -d '{
    "externalReferenceId": "LOAN-001",
    "loanAmount": 50000,
    "duration": 12,
    "durationUnit": "MONTHS",
    "confirm": false,
    "originalFileName": "loan-agreement.pdf",
    "fileBase64": "BASE64_ENCODED_PDF",
    "contentType": "application/pdf",
    "data": {
      "title": "Loan Agreement - RM50,000",
      "parties": [
        {
          "name": "ABC Finance Sdn Bhd",
          "partyType": "company",
          "role": "Lender",
          "address": { "addressLine1": "123 Jalan Merdeka", "addressLine2": "KL", "postcode": "50000", "city": "Kuala Lumpur", "state": "WP", "country": "MY" },
          "contactNumber": "+60123456789",
          "registrationNumber": "202001012345"
        },
        {
          "name": "Ali bin Abu",
          "partyType": "individual",
          "role": "Borrower",
          "address": { "addressLine1": "456 Jalan Damai", "addressLine2": "PJ", "postcode": "47301", "city": "Petaling Jaya", "state": "Selangor", "country": "MY" },
          "contactNumber": "+60198765432"
        }
      ]
    }
  }'

Step 4: Track Status

Poll contract status or set up webhooks for real-time updates.

Check status by your reference ID

curl https://stamps.kenal.io/api/integration/contracts/status?externalReferenceId=LOAN-001 \
  -H "x-service-id: YOUR_INTEGRATION_ID" \
  -H "x-timestamp: 2026-03-15T10:05:00.000Z" \
  -H "x-signature: COMPUTED_HMAC_SIGNATURE"

Step 5: Download Certificate

Once the contract status is Completed, download the stamp certificate:

Download certificate

curl https://stamps.kenal.io/api/integration/contracts/CONTRACT_ID/certificate \
  -H "x-service-id: YOUR_INTEGRATION_ID" \
  -H "x-timestamp: 2026-03-15T12:00:00.000Z" \
  -H "x-signature: COMPUTED_HMAC_SIGNATURE" \
  -o certificate.pdf

Next Steps

Authentication deep-dive — Signing algorithm, timestamp tolerance, error handling
Webhooks — Set up real-time status notifications
API Reference — Full interactive endpoint reference

Integration Quickstart