Guides

Document handoffs guide

Create tamper-proof records of document transfers — loan disbursements, legal handoffs, contract signings.

When to use this pattern

Any time a physical or digital document changes hands and you need to prove who received what, when, and where. Common use cases:

Loan agreement signed and collected by borrower
Legal documents served to a named party
Equipment released from warehouse to field agent
Cheque or cash collected by authorised recipient

Integration pattern

document-handoff.js
const chain = await sp.chains.create({
  title: `Loan agreement — \${borrower.name} — \${loan.id}`,
  metadata: {
    loanId: loan.id,
    borrowerId: borrower.id,
    documentRef: 'LA-2026-4821',
    amount: loan.amount,
  },
  actors: [
    { event: 'issued',    actor: 'Loan Officer — Branch' },
    { event: 'received',  actor: borrower.name },
  ],
});

// Officer confirms they issued the document
await sendEmail(officer.email,
  `Confirm document issued: \${chain.handoffs[0].confirmation_url}`);

// Borrower confirms receipt
await sendSMS(borrower.phone,
  `Confirm you received your loan agreement: \${chain.handoffs[1].confirmation_url}`);

The GPS captured when the borrower confirms is proof of where they were when they acknowledged receipt. Combined with the timestamp, this is strong evidence in any subsequent dispute about whether documents were properly served.