eContract Developers

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 PDF

1. 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 }] }
    ]
  }'
FieldMeaning
submit: falseProcess the document (DOCX → PDF, signature boxes) and stop at draft. Nobody is invited until you call submit. Default true sends right away.
externalRefYour 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.
requestedByThe person in your system who sent it (the API key belongs to your system, not to a person).
Idempotency-KeyRetrying 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:

  1. Anchor text: signatureAnchor.text is a label in the document ("ĐẠI DIỆN BÊN A", "The Employee"). The box goes below it (or above, right, over). Best when you generate the document from your own template: put the label in the template once.
  2. Coordinates: signaturePositions with 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.
  3. 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 with POST /contracts/{id}/signing-links and 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" }
  }
}
  1. Check the signature header, skip event ids you have already handled, answer 2xx fast.
  2. In a background job, download downloadPath with your API key.
  3. Compare the SHA-256 of the bytes with document.sha256 (also in the X-Document-Sha256 header).
  4. Store the PDF with your record (externalRef), and the audit trail from GET /contracts/{id}/audit-trail if 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: false on the contract and on every webhook envelope ("livemode": false), a TEST badge in the app.
  • No email is ever sent (invitations, reminders, OTP, completion); delivery is forced to link.
  • 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, on POST /contracts/{id}/signing-links and in every webhook signer object.
  • redirectUrl (contract) and signers[].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 with 400 REDIRECT_HOST_NOT_ALLOWED. Treat the query string as a hint only: confirm the status with the webhook or GET /contracts/{id}.

Embedding signing in your app

  1. 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 (CSP frame-ancestors).
  2. Get the links: POST /contracts/{id}/signing-links returns embedUrl next to signingUrl for each external signer (/embed/sign/<token>, same token).
  3. 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_DRAFT otherwise); the link works for 15 minutes from the embed origins.
  • The page posts econtract:ready, econtract:placement_saved ({ contractId, externalRef, submitted }), econtract:submitted (with submitOnSave) and econtract:error (SESSION_INVALID, CONTRACT_NOT_DRAFT, SAVE_FAILED).
  • Your server learns about the save from the contract.placement.saved webhook; the postMessage only tells your page.
  • Without submitOnSave, call POST /contracts/{id}/submit yourself 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-Key on POST /contracts/send and submit
  • externalRef on every contract, externalId on every signer; reconcile with GET /contracts?externalRef= if a webhook was missed
  • Signed PDF checked against document.sha256 before storing
  • contract.processing.failed, signer.declined, contract.voided and contract.expired handled

On this page