@builtsign/node

Official Node.js SDK for the BuiltSign e-signature API.

Requirements: Node.js ≥ 18 (uses native fetch and crypto)

Installation

npm install @builtsign/node

Quick start

import BuiltSign from "@builtsign/node";

const builtsign = new BuiltSign({ apiKey: "bs_live_xxxxxxxxxxxxxxxxxxxx" });

// 1. Upload a PDF
const { document_id } = await builtsign.documents.upload(
  await fs.readFile("contract.pdf"),
  "contract.pdf",
);

// 2. Create a signing request
const request = await builtsign.signingRequests.create({
  document_id,
  signers: [
    { name: "Jan de Vries", email: "[email protected]", order: 1 },
    { name: "Lisa Smit",    email: "[email protected]", order: 2 },
  ],
  signing_order: "sequential",
  expires_in_days: 7,
  auto_send: false,
});

// 3. Place signature fields
await builtsign.signingRequests.addFields(request.id, [
  {
    signer_id: request.signers[0].id,
    field_type: "signature",
    page_number: 1,
    x_percent: 60,
    y_percent: 82,
    width_percent: 30,
    height_percent: 8,
  },
]);

// 4. Send
await builtsign.signingRequests.send(request.id);

Sandbox mode

Create a sandbox API key in your dashboard (Settings → API Keys) to test without sending real emails or consuming quota. Responses from sandbox requests include the X-BuiltSign-Mode: sandbox header.

const builtsign = new BuiltSign({ apiKey: "bs_sandbox_xxxxxxxxxxxxxxxxxxxx" });

Templates

// Send from a template — map signers to roles by name
const request = await builtsign.templates.send("tpl_...", {
  signers: [
    { email: "[email protected]", name: "Jan de Vries", role: "Buyer" },
    { email: "[email protected]", name: "Ali Yilmaz", role: "Seller" },
  ],
  variables: {
    contract_date: "2026-05-19",
    amount: "€4.500",
  },
});

Webhook verification

import express from "express";
import BuiltSign from "@builtsign/node";
import { BuiltSignError } from "@builtsign/node";

const builtsign = new BuiltSign({ apiKey: process.env.BUILTSIGN_API_KEY! });

app.post("/webhook", express.text({ type: "application/json" }), (req, res) => {
  try {
    const event = builtsign.webhooks.verify(
      req.body,                                    // raw string body
      req.headers["x-webhook-signature"] as string,
      process.env.BUILTSIGN_WEBHOOK_SECRET!,
    );

    if (event.event === "signing_request.completed") {
      console.log("Completed:", event.data.signing_request_id);
    }

    res.sendStatus(200);
  } catch (err) {
    if (err instanceof BuiltSignError && err.code === "invalid_signature") {
      return res.status(401).send("Invalid signature");
    }
    throw err;
  }
});

Error handling

import { BuiltSignError, BuiltSignRateLimitError } from "@builtsign/node";

try {
  await builtsign.signingRequests.get("non-existent-id");
} catch (err) {
  if (err instanceof BuiltSignRateLimitError) {
    console.log(`Rate limited — retry after ${err.retryAfter}s`);
  } else if (err instanceof BuiltSignError) {
    console.error(`${err.status} ${err.code}: ${err.message}`);
    console.error(`Request ID: ${err.requestId}`); // include in support tickets
  }
}

API reference

builtsign.documents

| Method | Description | |---|---| | upload(file, filename) | Upload a PDF. Returns document_id. | | list(params?) | List uploaded documents. |

builtsign.signingRequests

| Method | Description | |---|---| | create(params) | Create a new signing request. | | list(params?) | List signing requests. Filter by status. | | get(id) | Get a signing request by ID. | | send(id) | Send a draft request to its signers. | | cancel(id) | Cancel a pending request. | | addFields(id, fields) | Place signature fields on a request. | | download(id) | Get a presigned URL for the completed PDF. | | remind(id) | Send a reminder email to pending signers. | | reactivate(id, params?) | Reactivate an expired signing request. | | embeddedUrl(id, params) | Generate embedded signing URLs for iframe/popup flows. |

builtsign.templates

| Method | Description | |---|---| | list(params?) | List templates. | | create(params) | Create a template. | | get(id) | Get a template by ID. | | update(id, params) | Update a template. | | delete(id) | Delete a template. | | send(id, params) | Create a signing request from a template. |

builtsign.contacts

| Method | Description | |---|---| | list(params?) | List saved contacts. Filter by search (name/email). | | create(params) | Create or update a contact (upserts on email). | | delete(id) | Delete a contact. |

builtsign.usage

| Method | Description | |---------|----------------------------------------------------------| | get() | Get quota and usage metrics for the current organization. |

builtsign.webhooks

| Method | Description | |---|---| | verify(rawBody, signature, secret) | Verify and parse an incoming webhook. |