Bouwen met BuiltSign

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

curl -X POST https://api.builtsign.com/v1/signing-requests \
  -H "X-API-Key: bsk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "document_id": "doc_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: bsk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": [
      {
        "signer_id": "sgn_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
      }
    ]
  }'

{
  "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";

// Express middleware example
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.headers["x-webhook-signature"];
  const secret    = process.env.BUILTSIGN_WEBHOOK_SECRET;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(req.body) // raw Buffer, not parsed JSON
    .digest("hex");

  if (expected !== signature) {
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(req.body);
  // TODO: handle event (e.g. event.event === "document.signed")
  res.sendStatus(200);
});

# Build from source
cd packages/mcp-server
npm install && npm run build

{
  "mcpServers": {
    "builtsign": {
      "command": "node",
      "args": ["/path/to/packages/mcp-server/dist/index.js"],
      "env": {
        "BUILTSIGN_API_KEY": "bs_live_xxxxxxxxxxxxxxxxxxxx",
        "BUILTSIGN_API_URL": "https://app.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=3600",
  "expires_in": 3600,
  "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 1 hour)
  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" },
);

// Pass signer.embedded_url to your frontend
const signerUrl = signers[0].embedded_url;

npm install @builtsign/embed