fastify-x-signwell

documents.create

Create a new SignWell document and send it to one or more recipients for signing.

documents.create

Create a new document for signing. Recipients receive an email with a signing link unless draft: true is passed.

Signature

fastify.xsignwell.documents.create(
  params: {
    name: string;
    recipients: Array<{ email: string; name?: string; id?: string; sendEmail?: boolean }>;
    files?: Array<{ name: string; url?: string; base64?: string }>;
    draft?: boolean;
    subject?: string;
    message?: string;
    metadata?: Record<string, unknown>;
    testMode?: boolean;
  }
): Promise<Object>

Params

Name	Type	Required	Description
`name`	`string`	Yes	Document display name.
`recipients`	`array`	Yes	Non-empty array of recipient objects. Each must have `email`.
`recipients[].email`	`string`	Yes	Recipient email address.
`recipients[].name`	`string`	No	Recipient display name.
`recipients[].id`	`string`	No	Recipient ID. Auto-generated if omitted.
`recipients[].sendEmail`	`boolean`	No	Send signing email to this recipient. Default `true`.
`files`	`array`	No	Files to sign. Each item needs `name` plus either `url` or `base64`.
`draft`	`boolean`	No	Create without sending. Default `false`.
`subject`	`string`	No	Email subject line.
`message`	`string`	No	Email message body.
`metadata`	`object`	No	Custom metadata stored with the document.
`testMode`	`boolean`	No	Override plugin-level `testMode` for this document.

Returns

The created document object from the SignWell API, including id, status, recipients[], created_at, and more.

Throws

[xSignwell] documents.create: params object is required — if params is not an object.
[xSignwell] documents.create: name (string) is required — if name is missing or not a string.
[xSignwell] documents.create: recipients (non-empty array) is required — if recipients is empty or not an array.
[xSignwell] documents.create: each recipient must have an email — if a recipient object has no email.
Re-throws SignWell API errors with statusCode and signwellError properties.

Examples

Basic — create and send immediately

const doc = await fastify.xsignwell.documents.create({
  name: "Service Agreement",
  recipients: [
    { email: "alice@example.com", name: "Alice" },
    { email: "bob@example.com", name: "Bob" },
  ],
  files: [
    { name: "agreement.pdf", url: "https://cdn.example.com/agreement.pdf" },
  ],
});

console.log(doc.id); // "doc_abc123"

Create as draft for review before sending

const draft = await fastify.xsignwell.documents.create({
  name: "NDA Draft",
  recipients: [{ email: "partner@example.com", name: "Partner" }],
  files: [{ name: "nda.pdf", url: "https://cdn.example.com/nda.pdf" }],
  draft: true,
  subject: "Please review our NDA",
  message: "Hi, please review and sign the attached NDA at your convenience.",
});

// draft.status === "draft"
// Send it later:
await fastify.xsignwell.documents.send(draft.id);

Realistic — sign-on-completion webhook flow

fastify.post("/contracts", async (request, reply) => {
  const { contractUrl, signerEmail, signerName } = request.body;

  const doc = await fastify.xsignwell.documents.create({
    name: "Contract",
    recipients: [{ email: signerEmail, name: signerName }],
    files: [{ name: "contract.pdf", url: contractUrl }],
    subject: "Please sign your contract",
    message: "Click the link in this email to review and sign.",
    metadata: { userId: request.user.id },
  });

  await db.contracts.create({
    userId: request.user.id,
    documentId: doc.id,
    status: "pending_signature",
  });

  return reply.code(201).send({ documentId: doc.id });
});

AI Context

package: "@xenterprises/fastify-xsignwell"
method: fastify.xsignwell.documents.create(params)
use-when: Create a new SignWell document for signing from files (URLs or base64) with recipients and optional fields
params: name, recipients (array), files (array with name+url or name+base64), subject, message, draft, testMode
returns: document object with id, status, recipients

Edit this pageorReport an issue

bulkSend.*

Send a SignWell template to many recipients at once using bulk-send — create, list, validate CSV, and inspect results.

documents.createFromTemplate

Create a SignWell document from a saved template with pre-placed signature fields.