HL Sign API

Create an envelope. Set send: true to send it straight away. Supply the PDF as one of:

• document.base64: inline, up to 3 MB.
• document.url: a public HTTPS URL we download.
• document.upload_id: for files up to 50 MB. See POST /uploads.

Fields reference a recipient by 0-based index, email, or the ref you gave it.

curl https://sign.hlc.sh/api/v1/envelopes \
  -H "Authorization: Bearer $HLSIGN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Subcontract agreement",
    "message": "Please sign by Friday.",
    "document": { "name": "contract.pdf", "base64": "'"$(base64 -i contract.pdf)"'" },
    "recipients": [
      { "ref": "sub", "name": "Jane Builder", "email": "jane@example.com" },
      { "name": "Accounts", "email": "accounts@example.com", "role": "cc" }
    ],
    "fields": [
      { "recipient": "sub", "type": "signature", "page": 3, "x": 72, "y": 600, "width": 180, "height": 40 },
      { "recipient": "sub", "type": "date",      "page": 3, "x": 300, "y": 615 },
      { "recipient": "sub", "type": "text",      "page": 1, "x": 72, "y": 140, "label": "ABN", "required": true }
    ],
    "webhook_url": "https://example.com/hooks/hlsign",
    "send": true
  }'

Returns 201 with { envelope, signing_links }. signing_links holds each invited signer's private URL, so you can embed signing in your own app or send links yourself.

For large PDFs. Returns a presigned URL that is valid for 15 minutes. PUT the raw bytes to it, then create the envelope with document.upload_id.

UPLOAD=$(curl -s -X POST https://sign.hlc.sh/api/v1/uploads -H "Authorization: Bearer $HLSIGN_KEY")
curl -X PUT "$(echo $UPLOAD | jq -r .upload_url)" -H "Content-Type: application/pdf" --data-binary @big.pdf
# then: "document": { "upload_id": "<upload_id>", "name": "big.pdf" }

Lists envelopes, newest first. Query: status, q (title search), batch (bulk send id), limit (max 100), before (pass next_before from the previous page).

Full envelope with recipients, their statuses and the fields.

Update a draft. Accepts the same keys as create (except send). recipients and fields replace the existing lists, so send both together.

Send a draft. Every signer must have at least one signature field. Returns signing_links.

Send a separate copy of a draft to each person on a list, for example a policy everyone has to acknowledge. The draft acts as the template. One signer is the placeholder, and each copy replaces it with a person from the list. Other recipients (countersigners, CCs) are copied onto every envelope unchanged.

The placeholder is the signer with email bulk-recipient@placeholder.invalid, or the first signer. You can also name it with placeholder (recipient id, email or index). Up to 200 people per call. Duplicate emails are dropped. Once every copy is sent, the draft is deleted unless you pass keep_draft: true.

curl https://sign.hlc.sh/api/v1/envelopes/$DRAFT_ID/bulk-send   -H "Authorization: Bearer $HLSIGN_KEY" -H "Content-Type: application/json"   -d '{ "recipients": [
         { "name": "Dana Driver", "email": "dana@example.com" },
         { "name": "Eli Driver",  "email": "eli@example.com" }
       ] }'

# → 201 { "batch_id": "…", "total": 2,
#         "sent":   [{ "envelope_id": "…", "email": "dana@example.com", "signing_url": "…", "emailed": true }, …],
#         "failed": [] }

Progress of a bulk send: counts by status (sent, completed, declined, voided) and each envelope with its recipient. You can also list a batch's envelopes with GET /api/v1/envelopes?batch=:id.

Emails signers who haven't finished again. Each reminder issues a new link, and the earlier link stops working.

Cancel an in-progress envelope. Body: { "reason": "Wrong version attached" }.

Redirects to a short-lived download URL. ?type=completed (the default once complete) returns the signed PDF with its certificate of completion. ?type=original returns the PDF as uploaded. Add &redirect=false to get { url } as JSON instead.

The audit trail: who did what, and when, including IP address and user agent.

Delete a draft.