Add e-signatures to a React app

Embed e-signatures in a React app with coss.com Sign. Create a request on your server, mount the signing page, and keep the sealed PDF.

Your server creates a signature request and a signing session, a React component shows the signing page with mountSigning from coss/sign, and a webhook says when the sealed PDF is ready. The server code uses Next.js route handlers; any server works. For the overview, see e-signatures.

Allow your app to embed the signing page

Install the SDK (npm install coss) and add your app's origin to the Sign settings, here or in the dashboard. Sandbox environments also accept http://localhost:3000 while you develop.

await ...({ : ["https://app.example.com"] });

Create a signature request on the server

Ask your signed-in user to sign a PDF, inline as base64 or uploaded first with coss.sign.documents.upload(). delivery: "embedded" means they sign in your app instead of from an emailed link, and client_ref (your user id) goes into the audit trail. Anchors like {{signature:signer_1}} in the PDF place fields without coordinates (fields and anchors).

const { : ,  } = await ...({
  : "Services agreement",
  : [{ : "agreement.pdf", :  }],
  : [
    {
      : .,
      : .,
      : "embedded",
      : .,
      : [{ : "signature", : "{{signature:signer_1}}" }],
    },
  ],
  : { : "ctr_123" }, // comes back in every sign_request.* webhook
});
// Keep request.id and request.signers[0].id with your contract.

Create a signing session for the embedded signer

Your app vouches for who the signer is, so create a session only for that signed-in user, when they open the page. Each call makes a new session, valid for an hour by default and at most 24. Sessions are refused for email signers, for requests that aren't sent and for signers who already signed or declined.

// app/api/contracts/[id]/session/route.ts
import {  } from "coss";

const  = new ();

export async function (: , : { : <{ : string }> }) {
  const  = await ();
  const  = await ((await .)., .);
  if (!) return new (null, { : 404 });

  const { ,  } = ;
  const { : ,  } = await ...(, );
  if () return .({ : . }, { : 409 });
  // The token is in the URL's fragment: never log it.
  return .({ : . });
}

Embed the signing page in a React component

mountSigning returns an embed whose destroy() removes the iframe and stops listening, which is the effect's cleanup. The iframe grows with its content, up to the window's height.

"use client";
import { , ,  } from "react";
import { , type  } from "coss/sign";

export function ({  }: { : string }) {
  const  = <>(null);
  const [, ] = <string | null>(null);
  (() => {
    let : { (): void } | undefined;
    let  = false;
    const  = (: ) => {
      if (. === "signed") ("Thanks, you signed.");
      if (. === "declined") ("You declined to sign.");
      if (. === "error") (`This link can't be used (${.}).`);
    };
    (`/api/contracts/${}/session`, { : "POST" })
      .(() => .() as <{ : string }>)
      .(({  }) => {
        if ( || !.) return;
         = ({ , : .,  });
      });
    return () => {
       = true;
      ?.();
    };
  }, []);

  return  ? <>{}</> : < ={} />;
}

Events arrive in order: ready, viewed, then signed or declined, plus error when the link is invalid or expired. signed carries request_status, completed when this signer was the last. They are UI hints: keep your records from webhooks.

Get the sealed PDF from the sign_request.completed webhook

When the last signer signs, coss.com seals the document and sends sign_request.completed. Download the sealed PDF then. An event can arrive more than once, so deduplicate by its id.

// app/api/webhooks/coss/route.ts
import { ,  } from "coss";

const  = new ();

export async function (: ) {
  const  = ..!;
  const  = await (await .(), ., );
  if (. === "sign_request.completed") {
    const { ,  } = .;
    const { :  } = await ...();
    if () await (.contract_id!, );
  }
  return new (null);
}

viewed, signer_signed, declined, canceled and expired events show progress too. See completion and the audit trail.

Use templates for repeat documents

For a contract you send again and again, make a template once, with a role per party (client, company) and merge fields filled from your data. Then replace coss.sign.requests.create() with coss.sign.templates.createRequest(templateId, { signers, merge_fields }), giving each signer a role and delivery: "embedded". Everything after it (sessions, the component, the webhook) stays the same.

Test with a sandbox key

With a coss_test_… key, requests work end to end on the real signing page: it says the signing has no legal effect, the PDF gets a test seal, no emails reach anyone and nothing is billed. coss listen forwards webhooks to your local server and coss trigger sign_request.completed sends a sample one. See testing Sign.

Next steps

Last updated