Staffing & Recruitment E-Signature API: Automate Offer Letters & IR35 Contracts (2026)

interface ContractorPlacementPayload {
  placementId: string;
  agencyLegalName: string;
  agencyComplianceEmail: string;
  contractorDirectorName: string;
  contractorEmail: string;
  pscCompanyName: string;
  pscCompaniesHouseNumber: string;
  endClientName: string;
  projectTitle: string;
  startDate: string;
  endDate: string;
  dayRateGbpExVat: number;
  ir35Status: "OUTSIDE_IR35" | "INSIDE_IR35_FEE_PAYER_DEDUCTS";
  sdsAssessmentReference: string;
  deliverableMilestones: Array<{ milestone: string; targetDate: string; acceptanceCriteria: string }>;
}

export async function dispatchIr35AssignmentSchedule(input: ContractorPlacementPayload) {
  const milestoneRows = input.deliverableMilestones
    .map((m) => `| ${m.milestone} | ${m.targetDate} | ${m.acceptanceCriteria} |`)
    .join("\n");

  const markdownAgreement = `# Contractor Assignment Schedule & IR35 Status Determination Statement

**Placement Reference:** ${input.placementId}
**Employment Business (Agency):** ${input.agencyLegalName}
**Personal Service Company (Contractor):** ${input.pscCompanyName} (Company No: ${input.pscCompaniesHouseNumber})
**Representative / Nominated Director:** ${input.contractorDirectorName}

---

## 1. Assignment Commercial Terms
| Commercial Term | Agreed Specification |
|---|---|
| End-Client Organization | ${input.endClientName} |
| Project & Scope Title | ${input.projectTitle} |
| Commencement Date | ${input.startDate} |
| Scheduled Completion Date | ${input.endDate} |
| Agreed Contract Rate | £${input.dayRateGbpExVat.toFixed(2)} per day (exclusive of VAT) |
| Invoicing & Payment Terms | Weekly timesheet/milestone verification; Net 14 Days via BACS |

## 2. Deliverable Milestones & Statement of Work
| Deliverable Milestone | Target Date | Client Acceptance Criteria |
|---|---|---|
${milestoneRows}

## 3. Statutory Off-Payroll Working (Chapter 10 ITEPA 2003 / IR35) Determination
Pursuant to Section 61NA of the Income Tax (Earnings and Pensions) Act 2003, the End-Client has exercised reasonable care in issuing the following Status Determination Statement (Assessment Ref: **${input.sdsAssessmentReference}**):

* **Tax Status Determination:** **${input.ir35Status}**
* **Right of Substitution:** The Contractor (${input.pscCompanyName}) retains an unfettered contractual and practical right to provide a suitably qualified substitute consultant, subject only to verification of security clearance and technical qualifications.
* **Absence of Supervision, Direction, or Control (SDC):** The Contractor determines the technical methodology, sequence, and tooling required to achieve the Deliverable Milestones specified in Section 2.
* **No Mutuality of Obligation (MOO):** Neither the Agency nor the End-Client is obligated to offer further assignments beyond the Scheduled Completion Date, nor is the Contractor obligated to accept any subsequent work.`;

  const response = await fetch("https://signb.ee/api/v1/send", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.SIGNBEE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      title: `Assignment Schedule & IR35 SDS — ${input.pscCompanyName} (${input.placementId})`,
      markdown: markdownAgreement,
      sender_name: input.agencyLegalName,
      sender_email: input.agencyComplianceEmail,
      recipient_name: input.contractorDirectorName,
      recipient_email: input.contractorEmail,
      expires_in_days: 5,
      webhook_url: "https://ats-bridge.example-staffing.co.uk/api/webhooks/signbee",
    }),
  });

  if (!response.ok) {
    throw new Error(`Signbee IR35 schedule dispatch failed: ${response.status}`);
  }

  return await response.json();
}

import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const event = await req.json();
  const offer = event.payload.offer;
  const candidate = event.payload.candidate;

  const offerMarkdown = `# Offer of Employment — ${offer.job_title}

**Date:** ${new Date().toISOString().split("T")[0]}
**Candidate:** ${candidate.first_name} ${candidate.last_name} (${candidate.email})
**Employing Entity:** Horizon Technologies Inc.

---

## 1. Position, Reporting Line & Start Date
We are delighted to offer you the position of **${offer.job_title}** reporting to **${offer.manager_name}**. Your employment will commence on **${offer.start_date}** at our ${offer.office_location} office (Hybrid Schedule).

## 2. Total Compensation & Equity Package
| Compensation Component | Annualized / Grant Value | Vesting / Payment Schedule |
|---|---|---|
| Base Salary | $${Number(offer.base_salary_usd).toLocaleString()} USD | Paid semi-monthly via direct deposit |
| Target Performance Bonus | ${offer.bonus_target_percent}% of Base Salary | Paid annually based on company & OKR milestones |
| Restricted Stock Units (RSUs) | ${Number(offer.equity_units).toLocaleString()} Units | 4-year vesting; 25% 1-year cliff, monthly thereafter |
| One-Time Sign-On Bonus | $${Number(offer.sign_on_bonus_usd).toLocaleString()} USD | Paid on first regular payroll cycle |

## 3. Proprietary Information, Inventions & At-Will Terms
Your employment with Horizon Technologies Inc. is at-will and contingent upon satisfactory completion of background verification and right-to-work documentation (Form I-9) within three (3) business days of your start date. By signing below, you accept the terms of this offer and agree to abide by the Employee Proprietary Information and Inventions Assignment Agreement (PIIAA).`;

  const signbeeRes = await fetch("https://signb.ee/api/v1/send", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.SIGNBEE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      title: `Employment Offer Letter — ${candidate.first_name} ${candidate.last_name} (${offer.job_title})`,
      markdown: offerMarkdown,
      sender_name: "Horizon People & Talent Operations",
      sender_email: "talent-ops@horizontech.example.com",
      recipient_name: `${candidate.first_name} ${candidate.last_name}`,
      recipient_email: candidate.email,
      expires_in_days: 7,
      webhook_url: `https://hr-automation.horizontech.example.com/api/webhooks/signbee?applicationId=${offer.application_id}`,
    }),
  });

  const result = await signbeeRes.json();
  return NextResponse.json({ dispatched: true, signbeeDocumentId: result.id });
}

import crypto from "crypto";
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const rawBody = await req.text();
  const signature = req.headers.get("x-signbee-signature") || "";
  const applicationId = req.nextUrl.searchParams.get("applicationId");

  const expectedHmac = crypto
    .createHmac("sha256", process.env.SIGNBEE_WEBHOOK_SECRET || "")
    .update(rawBody, "utf8")
    .digest("hex");

  if (signature !== expectedHmac) {
    return NextResponse.json({ error: "Unauthorized webhook signature" }, { status: 401 });
  }

  const event = JSON.parse(rawBody);

  if (event.event === "document.signed" && applicationId) {
    // Attach the signed, SHA-256 sealed PDF to the candidate's ATS record
    await fetch(`https://harvest.greenhouse.io/v1/applications/${applicationId}/attachments`, {
      method: "POST",
      headers: {
        "Authorization": `Basic ${Buffer.from(process.env.GREENHOUSE_API_KEY + ":").toString("base64")}`,
        "On-Behalf-Of": process.env.GREENHOUSE_ADMIN_USER_ID || "",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        filename: `Signed_Offer_${event.document_id}_SHA256_${event.sha256_hash.slice(0, 10)}.pdf`,
        type: "offer_packet",
        url: event.download_url,
      }),
    });
  }

  return NextResponse.json({ ok: true });
}