POST/external/stampNsign/new-agreement
Create New Agreement
Creates a new Stamp & Sign transaction. There is no status-read API — keep document status on your side from responses and webhooks.
Signature: Required
Request Headers
auth
Integration JWT we issue; send it as-is on every partner call
x-payload-signature
HMAC-SHA256(payload form-field string, ownership HMAC secret)
Content-Type
multipart/form-data
Multipart Form Fields
| Key | Type | Description |
|---|---|---|
| payload | string | JSON string of the request body. Sign this exact string value for x-payload-signature |
| txn-file | file | Agreement document — PDF / DOC / DOCX, max 5 MB |
Mandatory Body (payload JSON)
| Key | Type | Description |
|---|---|---|
| externalRef | string | Unique external reference for this agreement. Duplicate values are rejected |
| documentType | string | Document category. Allowed values include: "rentalagm", "mouforsale", "serviceagm", "agmforsale", "saleagm", "misc", "templatedAgm", and other TxnDocType values |
| services | object | At least one of services.estamp or services.esign must be true |
| firstParties | Array | Non-empty. Each party requires countryCode, phone, firstName, lastName. email required only when esignMethod is "email" |
| secondParties | Array | Non-empty. Same fields as firstParties |
| billingAddress | Object | Requires addressLine1, city, state, pincode. addressLine2 / addressLine3 / country optional (country defaults to "IND") |
| considerationAmount | number | Non-negative. Used for Karnataka rental stamp suggestion (min(500, consideration × 0.005)) |
| paymentBy | string | Required. Phone of the payer (digits, or countryCode+phone). Must match a first or second party phone. Same role as the website “Who will pay?” picker — stored as that party’s _id |
Conditional Body (payload JSON)
Required when the corresponding service is enabled in services.
| Key | Type | Description |
|---|---|---|
| stampState | string | Required when services.estamp is true. Stamp state code (e.g. "KA") |
| eStampAmount | number | Required when services.estamp is true. Must be between 20 and 500. Special rules apply for KA rental / service and MOU for sale (₹500) |
| esignMethod | "email" | "aadhaar" | Required when services.esign is true. Mapped internally to email-only or aadhaar. For "email", every party (including stakeholders) must have a valid email. For "aadhaar", email is optional |
Optional Body (payload JSON)
| Key | Type | Description |
|---|---|---|
| title | string | Optional. Custom document title. Non-empty if provided |
| stakeholders | Array | Same party shape as first/second parties. Must not reuse a first/second party phone (or email, if provided) |
| propertyAddress | Object | Same shape as billingAddress. Requires addressLine1, city, state, pincode when included |
| startDate | string | ISO 8601 date / timestamp |
| periodInMonths | number | Positive integer |
| escrowOwnershipToken | string | Escrow ownership JWT ({ accountNum }, same as escrow API ownership-token). On create, links this Stamp & Sign into that escrow's stampNSignTxnIds. Omit = no link, no fail |
Form File (mandatory)
| Key | Type | Description |
|---|---|---|
| txn-file | file | Agreement PDF/DOC/DOCX, max 5 MB |
Behavior Notes
- If "escrowOwnershipToken" is sent on create, this Stamp & Sign id is linked into that escrow's stampNSignTxnIds. If omitted, create still succeeds with no escrow link.
- Provided party emails and phones must be unique across firstParties, secondParties, and stakeholders. Stakeholders cannot be the same person as a first or second party.
- paymentBy is required and must match a first or second party phone.
- Create fails if externalRef already exists.
- Create response includes "agreementOwnershipToken" — store it and send on further API calls (keep auth as the integration JWT) send_for_estamp and estamp-recovery expect it as agreement-ownership-token.
- There is no status-read endpoint — maintain document status on your side from HTTP responses and webhooks (payment_order_created, payment_captured, doc_updated, status_updated).
- After create, call send_for_estamp to start the next step. If stamp is needed, we send a payment link first, then stamp (and sign if you asked for it).
- Do not send "agreementOwnershipToken" on create — the request will be rejected. Use update instead.
- On success, review WhatsApp + email notifications are sent to the API user.
- Partner integrations: use the integration JWT in auth on every call.
Sample Request
// multipart/form-data
// Form field: payload (string — sign this exact string)
{
"externalRef": "CRM-SNS-1001",
"documentType": "rentalagm",
"title": "Rental Agreement — Brigade Metropolis",
"services": {
"estamp": true,
"esign": true
},
"stampState": "KA",
"eStampAmount": 500,
"considerationAmount": 100000,
"esignMethod": "aadhaar",
"paymentBy": "9999999999",
"firstParties": [
{
"countryCode": "91",
"phone": "9999999999",
"email": "owner@example.com",
"firstName": "Mayank",
"lastName": "Jain"
}
],
"secondParties": [
{
"countryCode": "91",
"phone": "8888888888",
"email": "tenant@example.com",
"firstName": "Priya",
"lastName": "Sharma"
}
],
"stakeholders": [
{
"countryCode": "91",
"phone": "7777777777",
"email": "witness@example.com",
"firstName": "Arjun",
"lastName": "Mehta"
}
],
"billingAddress": {
"addressLine1": "Tower A, Brigade Metropolis",
"addressLine2": "Whitefield",
"addressLine3": "Mahadevapura",
"city": "Bengaluru",
"state": "Karnataka",
"pincode": "560097",
"country": "IND"
},
"propertyAddress": {
"addressLine1": "Flat 5107, UKN Esperanza",
"addressLine2": "Devanahalli Road",
"addressLine3": "Bagalur",
"city": "Bengaluru",
"state": "Karnataka",
"pincode": "560066",
"country": "IND"
},
"startDate": "2026-08-01",
"periodInMonths": 11,
"escrowOwnershipToken": "<escrow ownership JWT from escrow API>"
}
// Form field: txn-file
agreement.pdfHeaders: auth, x-payload-signature, Content-Type: multipart/form-data
Sample Responses
Success Response
{
"result": "success",
"status": 200,
"message": "Transaction created successfully",
"agreementOwnershipToken": "<token — store and send on further API calls>"
}Duplicate externalRef
{
"result": "badrequest",
"status": 400,
"message": "externalRef 'CRM-SNS-1001' is already being used with another transaction"
}