Integrating eContract
Add e-signature to your own software (ERP, HR, case management) with drafts, internal approval, signature positions by anchor or coordinates, signing links you deliver yourself, external references and verified webhooks.
This guide is for software that sends its own documents for signature: an HR system sending employment contracts, an ERP sending purchase orders, a case-management tool sending agreements. Your users stay in your software; eContract prepares the PDF, collects the signatures (PAdES with an RFC 3161 timestamp and an audit trail) and tells you when it is done.
Node.js projects can use the official SDK (npm install @econtract/sdk) and Laravel projects the Composer package (composer require contractlayer/econtract-laravel). A complete runnable Node.js example is at
github.com/contractlayer/econtract-integration-demo.
The flow
Your system eContract
─────────── ─────────
1 POST /contracts/send ───────────────▶ 2 stores the file, DOCX → PDF,
submit: false, externalRef, places signature boxes
requestedBy, signers[…] (status: draft)
◀─────────────── 3 webhook contract.processing.completed
{ status: "draft", contract.externalRef }
4 (optional) review, move boxes:
GET/PUT /contracts/{id}/signature-positions
5 internal approval in your system
6 POST /contracts/{id}/submit ────────▶ 7 invites the signers by email, or
delivery: "email" | "link" POST /contracts/{id}/signing-links
gives you links to send yourself
◀─────────────── 8 signer.viewed / signer.completed …
◀─────────────── 9 contract.completed
{ document.sha256, downloadPath }
10 GET /contracts/{id}/document?version=signed
compare SHA-256, store the PDF1. Authenticate
Create an API key in Settings → API keys with only the scopes you need
(contracts:read, contracts:write, signing:read, webhooks:write…). Send it as
Authorization: Bearer <key>. Store it encrypted, never in source code. See Authentication.
If your software acts for many eContract workspaces (a SaaS product), use OAuth 2.1 instead so each customer connects their own workspace.
2. Register a webhook
curl -X POST https://api.econtract.online/api/v1/webhooks \
-H "Authorization: Bearer $ECONTRACT_API_KEY" -H "Content-Type: application/json" \
-d '{"url":"https://your-app.example.com/webhooks/econtract","events":["contract.processing.completed","contract.processing.failed","signer.completed","signer.declined","contract.completed","contract.voided","contract.expired"]}'Keep the returned secret: every delivery is signed with it. See Webhooks for the
signature check; de-duplicate on X-Econtract-Event-Id.
3. Send a draft
curl -X POST https://api.econtract.online/api/v1/contracts/send \
-H "Authorization: Bearer $ECONTRACT_API_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: hr-2026-0042-v1" \
-d '{
"title": "Employment contract — Tran Thi B",
"submit": false,
"externalRef": "HR-2026-0042",
"requestedBy": { "name": "Nguyen Van A", "email": "[email protected]", "externalId": "u-1024" },
"files": [{ "filename": "contract.docx", "url": "https://files.company.vn/hr/2026-0042.docx" }],
"signers": [
{ "email": "[email protected]", "name": "Le Van C", "signOrder": 1,
"signatureAnchor": { "text": "ĐẠI DIỆN BÊN A" } },
{ "email": "[email protected]", "name": "Tran Thi B", "signOrder": 2,
"signaturePositions": [{ "page": 3, "x": 330, "y": 640, "width": 200, "height": 60 }] }
]
}'| Field | Meaning |
|---|---|
submit: false | Process the document (DOCX → PDF, signature boxes) and stop at draft. Nobody is invited until you call submit. Default true sends right away. |
externalRef | Your id for this contract (max 128 characters). Returned on every contract and webhook; find contracts with GET /contracts?externalRef=HR-2026-0042. Not unique: you may send the same record again. |
requestedBy | The person in your system who sent it (the API key belongs to your system, not to a person). |
Idempotency-Key | Retrying with the same key and body returns the first contract instead of creating a second one. See Idempotency. |
The answer is 202 with the contract (processingStatus: "processing"). Wait for
contract.processing.completed (or poll GET /contracts/{id}) before the next step.
4. Signature positions
Three ways, per signer, from most to least automatic:
- Anchor text:
signatureAnchor.textis a label in the document ("ĐẠI DIỆN BÊN A","The Employee"). The box goesbelowit (orabove,right,over). Best when you generate the document from your own template: put the label in the template once. - Coordinates:
signaturePositionswith boxes in PDF points, origin at the top-left corner of the page, pages from 1 (what pdf.js gives at scale 1). A signer may have up to 20 boxes. Coordinates win over an anchor. - Nothing: the signer gets a default box at the end of the document.
On a draft you can read and change them:
# Read
curl https://api.econtract.online/api/v1/contracts/$ID/signature-positions -H "Authorization: Bearer $ECONTRACT_API_KEY"
# Replace the boxes of one signer (others keep theirs); "positions": [] = back to the default box
curl -X PUT https://api.econtract.online/api/v1/contracts/$ID/signature-positions \
-H "Authorization: Bearer $ECONTRACT_API_KEY" -H "Content-Type: application/json" \
-d '{"signers":[{"email":"[email protected]","positions":[{"page":3,"x":330,"y":600}]}]}'To let your users drag boxes in your own UI, render the PDF from
GET /contracts/{id}/document with pdf.js, convert the drop point to PDF points
(x = left / scale, y = top / scale, page from 1) and PUT them. 409 CONTRACT_NOT_DRAFT once submitted.
On a contract with several files, give fileId (from GET /contracts/{id} → files[].id).
5. Submit
After your internal approval:
curl -X POST https://api.econtract.online/api/v1/contracts/$ID/submit \
-H "Authorization: Bearer $ECONTRACT_API_KEY" -H "Content-Type: application/json" \
-d '{"delivery":"link"}'delivery: "email"(default): eContract emails each signer (in signing order).delivery: "link": no email at all, for this and every later step. Get the links withPOST /contracts/{id}/signing-linksand send them yourself (Zalo, SMS, your own email, your portal).
Signers open the link, confirm a one-time code sent by email and sign. They see the boxes where you put them.
6. Completion
contract.completed carries contract.externalRef and document:
{
"event": "contract.completed",
"apiVersion": "2026-11",
"data": {
"contractId": "8c1e…",
"contract": { "id": "8c1e…", "status": "completed", "externalRef": "HR-2026-0042", "requestedBy": { "externalId": "u-1024" }, "metadata": null },
"document": { "fileName": "contract-signed.pdf", "sha256": "9f2c…", "sizeBytes": 184213, "downloadPath": "/api/v1/contracts/8c1e…/document?version=signed" }
}
}- Check the signature header, skip event ids you have already handled, answer
2xxfast. - In a background job, download
downloadPathwith your API key. - Compare the SHA-256 of the bytes with
document.sha256(also in theX-Document-Sha256header). - Store the PDF with your record (
externalRef), and the audit trail fromGET /contracts/{id}/audit-trailif you need it.
Test keys (sandbox)
Create a key with Environment: Test (API keys page, or "mode": "test" on
POST /workspaces/{id}/api-keys). It starts with cl_test_. Everything it creates is a test contract:
livemode: falseon the contract and on every webhook envelope ("livemode": false), a TEST badge in the app.- No email is ever sent (invitations, reminders, OTP, completion);
deliveryis forced tolink. - The signer's one-time code is always
000000(the signing page says so). - Nothing counts toward your plan.
- The signed PDF carries a large TEST watermark on every page.
- Test contracts and their files are deleted 30 days after creation.
Build and run your whole integration against a test key, then switch the key. Test and live contracts
live in the same workspace; filter on livemode if your system stores both.
Service keys
A personal key acts as the member who created it and stops working when that member leaves the
workspace. For a server integration create a service key ("type": "service"): it acts as the
workspace owner, so it keeps working through staff changes. Contracts it sends show the owner as the
sender; put the person who clicked "send" in your system in requestedBy.
Your ids for signers, and redirects
"signers": [
{ "name": "Nguyễn An", "email": "[email protected]", "externalId": "emp-1024",
"redirectUrl": "https://hr.example.com/onboarding/1024/done" }
],
"redirectUrl": "https://hr.example.com/contracts/done"signers[].externalId(up to 128 characters): your id of the person. Returned on the contract, onPOST /contracts/{id}/signing-linksand in every webhooksignerobject.redirectUrl(contract) andsigners[].redirectUrl(wins for that signer): where the signing page sends the signer after signing or declining, with?contractId=…&signerId=…&status=signed|declined&externalRef=…&externalId=…added. The host must be listed under API keys → Integration → Redirect hosts, otherwise the request fails with400 REDIRECT_HOST_NOT_ALLOWED. Treat the query string as a hint only: confirm the status with the webhook orGET /contracts/{id}.
Embedding signing in your app
- Add your app's origin (for example
https://hr.example.com) under API keys → Integration → Origins allowed to embed. Pages are only framed by those origins (CSPframe-ancestors). - Get the links:
POST /contracts/{id}/signing-linksreturnsembedUrlnext tosigningUrlfor each external signer (/embed/sign/<token>, same token). - Show it in an iframe and listen to its messages:
<iframe id="econtract" src="EMBED_URL?lang=vi" style="width:100%;height:720px;border:0"
allow="clipboard-write"></iframe>
<script>
const ECONTRACT = 'https://econtract.online';
window.addEventListener('message', (event) => {
if (event.origin !== ECONTRACT || event.data?.source !== 'econtract') return;
switch (event.data.type) {
case 'econtract:ready': break; // { contractId, signerId, externalId, status, testMode }
case 'econtract:resize': document.getElementById('econtract').style.height = event.data.height + 'px'; break;
case 'econtract:signed': break; // { contractId, signerId, externalId, redirectUrl? }
case 'econtract:declined': break; // same fields
case 'econtract:error': break; // { code: LINK_INVALID | LOAD_FAILED, status }
}
});
</script>Messages are posted to your page's origin only, never *. Inside the iframe the page never navigates
by itself: redirectUrl is passed in the message for you to use. A signed message tells your UI to
move on; the legal state is still the signer.signed / contract.completed webhook.
?lang= picks the language (vi, en, ja, …); without it the browser's language is used.
Embedding signature placement
Let your user drag the signature boxes on a draft without an eContract account:
curl -X POST https://api.econtract.online/api/v1/contracts/$ID/placement-sessions \
-H "Authorization: Bearer $ECONTRACT_API_KEY" -H "Content-Type: application/json" \
-d '{"submitOnSave":true,"delivery":"link"}'
# → { "url": "https://econtract.online/embed/placement/…", "token": "…", "expiresAt": "…" }- Draft only (
409 CONTRACT_NOT_DRAFTotherwise); the link works for 15 minutes from the embed origins. - The page posts
econtract:ready,econtract:placement_saved({ contractId, externalRef, submitted }),econtract:submitted(withsubmitOnSave) andecontract:error(SESSION_INVALID,CONTRACT_NOT_DRAFT,SAVE_FAILED). - Your server learns about the save from the
contract.placement.savedwebhook; the postMessage only tells your page. - Without
submitOnSave, callPOST /contracts/{id}/submityourself after your approval step.
Checklist
- Built and tested with a
cl_test_key; a service key in production - API key with narrow scopes, stored encrypted
- Webhook signature verified, event ids de-duplicated, handler answers within 10 s
-
Idempotency-KeyonPOST /contracts/sendandsubmit -
externalRefon every contract,externalIdon every signer; reconcile withGET /contracts?externalRef=if a webhook was missed - Signed PDF checked against
document.sha256before storing -
contract.processing.failed,signer.declined,contract.voidedandcontract.expiredhandled
Core Concepts
Core concepts of the eContract API, from workspaces and roles to the contract lifecycle, async document processing, signers, signing order and templates.
SDKs
Official eContract client for Node.js (@econtract/sdk on npm) with typed contracts, signature placement, embedded signing and webhook verification. The Laravel package is on Packagist; other languages use the OpenAPI document.