Bouwen met BuiltSign

curl -X POST https://api.builtsign.com/v1/documents/upload \
  -H "X-API-Key: bs_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "file=@contract.pdf"

curl -X POST https://api.builtsign.com/v1/signing-requests \
  -H "X-API-Key: bs_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "document_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "signers": [
      { "name": "Jan de Vries", "email": "jan@example.com" }
    ],
    "message": "Graag de offerte ondertekenen.",
    "expires_in_days": 7,
    "auto_send": false
  }'

curl -X POST https://api.builtsign.com/v1/signing-requests/{request_id}/fields \
  -H "X-API-Key: bs_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": [
      {
        "signer_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "field_type": "signature",
        "page_number": 1,
        "x_percent": 60.0,
        "y_percent": 82.0,
        "width_percent": 30.0,
        "height_percent": 8.0
      }
    ]
  }'

import { createServer } from "node:http";
import { writeFile } from "node:fs/promises";
import BuiltSign, { BuiltSignError } from "@builtsign/node";

const builtsign = new BuiltSign({ apiKey: process.env.BUILTSIGN_API_KEY! }); // sandbox key
if (!(await builtsign.me()).sandbox) throw new Error("Use a sandbox key");

// 1. A webhook made with a sandbox key only gets sandbox events. The secret is shown once.
const webhook = await builtsign.webhooks.create({
  name: "Docstream",
  url: "https://your-host.example.com/builtsign",
  events: ["document.signed", "signer.declined", "signing_request.expired"],
});

// 2. Up to 1 GB, in parts straight to storage
const document = await builtsign.documents.uploadLarge("drawing-set.pdf", { concurrency: 4 });

// 3. A draft, tied to your own record, then the fields (percent of the page)
const request = await builtsign.signingRequests.create(
  {
    document_id: document.document_id,
    signers: [{ name: "Jan de Vries", email: "jan@example.com", order: 1 }],
    auto_send: false,
  },
  { idempotencyKey: `docstream-${recordId}` },
);
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. Sandbox: no mail goes out, so sign through the embedded link yourself
await builtsign.signingRequests.send(request.id, { idempotencyKey: `send-${request.id}` });
const { signers } = await builtsign.signingRequests.embeddedUrl(request.id, { allowed_origin: "http://localhost:3000" });
console.log("Sign here:", signers[0].embedded_url);

// 5. Verify every delivery on the raw body, answer 2xx at once, deduplicate on event_id
const handled = new Set<string>();
createServer(async (req, res) => {
  const chunks: Buffer[] = [];
  for await (const chunk of req) chunks.push(chunk);
  let event;
  try {
    event = builtsign.webhooks.verify(Buffer.concat(chunks), req.headers["x-builtsign-webhook-signature"], webhook.secret);
  } catch {
    return res.writeHead(401).end();
  }
  res.writeHead(200).end();
  if (handled.has(event.event_id)) return;
  handled.add(event.event_id);
  if (event.event === "document.signed") await saveResults(event.data.signing_request_id as string);
}).listen(4567);

// 6. Signed PDF and audit certificate; 409 document_not_ready means: wait Retry-After
async function saveResults(id: string) {
  const { download_url } = await whenReady(() => builtsign.signingRequests.download(id));
  await writeFile(`${id}-signed.pdf`, new Uint8Array(await (await fetch(download_url)).arrayBuffer()));
  await writeFile(`${id}-audit-certificate.pdf`, await whenReady(() => builtsign.signingRequests.auditCertificate(id)));
}

async function whenReady<T>(call: () => Promise<T>): Promise<T> {
  for (;;) {
    try {
      return await call();
    } catch (err) {
      if (!(err instanceof BuiltSignError) || err.code !== "document_not_ready") throw err;
      await new Promise((r) => setTimeout(r, (err.retryAfter ?? 5) * 1000));
    }
  }
}

{
  "event_id": "evt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "event": "signing_request.completed",
  "timestamp": "2026-05-21T11:00:00Z",
  "webhook_id": "wh_xxxxxxxxxxxxxxxxxxxx",
  "data": {
    "signing_request_id": "sr_xxxxxxxxxxxxxxxxxxxx",
    "completed_at": "2026-05-21T11:00:00Z",
    "all_signers": [
      { "email": "alice@example.com", "name": "Alice Smith", "signed_at": "2026-05-21T10:30:00Z" },
      { "email": "bob@example.com", "name": "Bob Jones", "signed_at": "2026-05-21T11:00:00Z" }
    ],
    "signed_pdf_s3_key": "orgs/org_xxx/signed/sr_xxx.pdf"
  }
}

import crypto from "crypto";

const TOLERANCE_SECONDS = 300;

function verifyBuiltSign(rawBody, header, secret) {
  let t;
  const signatures = [];
  for (const part of String(header ?? "").split(",")) {
    const [key, value] = part.split("=", 2);
    if (key === "t") t = Number(value);
    if (key === "v1") signatures.push(value);
  }
  if (!Number.isInteger(t) || signatures.length === 0) return false;
  // Refuse old timestamps, so a captured request cannot be replayed.
  if (Math.abs(Date.now() / 1000 - t) > TOLERANCE_SECONDS) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(t + ".")
    .update(rawBody) // raw Buffer, not parsed JSON
    .digest();
  // Constant-time compare; after a secret rotation there are two v1 values.
  return signatures.some((sig) => {
    const given = Buffer.from(sig, "hex");
    return given.length === expected.length && crypto.timingSafeEqual(given, expected);
  });
}

// Express middleware example
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const valid = verifyBuiltSign(
    req.body,
    req.headers["x-builtsign-webhook-signature"],
    process.env.BUILTSIGN_WEBHOOK_SECRET,
  );
  if (!valid) {
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(req.body);
  // Retries repeat event.event_id: skip an event you already handled.
  // TODO: handle event (e.g. event.event === "document.signed")
  res.sendStatus(200);
});

# Claude Code
claude mcp add builtsign \
  -e BUILTSIGN_API_KEY=bs_xxxxxxxxxxxxxxxxxxxxxxxx \
  -e BUILTSIGN_API_URL=https://api.builtsign.com \
  -- npx -y @builtsign/mcp

{
  "mcpServers": {
    "builtsign": {
      "command": "npx",
      "args": ["-y", "@builtsign/mcp"],
      "env": {
        "BUILTSIGN_API_KEY": "bs_xxxxxxxxxxxxxxxxxxxxxxxx",
        "BUILTSIGN_API_URL": "https://api.builtsign.com"
      }
    }
  }
}

{
  "event": "document.signed",
  "signing_request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "document_name": "Koopcontract 2026.pdf",
  "completed_at": "2026-06-16T10:30:00Z",
  "signed_pdf_url": "https://s3.amazonaws.com/builtsign/signed/...?X-Amz-Expires=900",
  "expires_in": 900,
  "signers": [
    {
      "name": "Jan de Vries",
      "email": "jan@example.com",
      "signed_at": "2026-06-16T10:28:00Z"
    },
    {
      "name": "Lisa Smit",
      "email": "lisa@example.com",
      "signed_at": "2026-06-16T10:30:00Z"
    }
  ]
}

import crypto from "crypto";
import express from "express";

app.post("/ai-webhook", express.raw({ type: "application/json" }), async (req, res) => {
  // 1. Verify the signature
  const signature = req.headers["x-builtsign-signature"];
  const secret    = process.env.BUILTSIGN_AI_SECRET;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(req.body)          // raw Buffer: do NOT parse first
    .digest("hex");

  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
    return res.status(401).send("Invalid signature");
  }

  const payload = JSON.parse(req.body);

  // 2. Download the signed PDF (URL valid 15 minutes)
  const pdfResponse = await fetch(payload.signed_pdf_url);
  const pdfBuffer   = await pdfResponse.arrayBuffer();

  // 3. Send to your AI pipeline
  await yourAiPipeline.process({
    documentName: payload.document_name,
    pdf:          Buffer.from(pdfBuffer),
    signers:      payload.signers,
    completedAt:  payload.completed_at,
  });

  res.sendStatus(200);
});

const { signers } = await builtsign.signingRequests.embeddedUrl(
  request.id,
  {
    allowed_origin: "https://yourapp.com",
    // Optional: where the iframe goes after signing or declining
    return_url: "https://yourapp.com/contracts/123/done",
  },
);

// One URL per signer, valid for 60 minutes
const signerUrl = signers[0].embedded_url;

npm install @builtsign/embed

HTTP/1.1 200 OK
Deprecation: @1793577600
Sunset: Mon, 01 Feb 2027 00:00:00 GMT
Link: <https://builtsign.com/developers/changelog>; rel="deprecation"; type="text/html",
      <https://builtsign.com/developers/changelog>; rel="sunset"; type="text/html"