Document workflow

This example uses curl and jq. The key needs documents:read, documents:write, and documents:send. Use a test recipient you control when you exercise the send step.

Create a draft

The integration’s team is the default team. The response includes the document ID and current version.

draft=$(curl --fail-with-body -sS \
  https://api.cloudraker.com/v1/signing/documents \
  -H "Authorization: Bearer $RAKESIGN_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: contract-order-1042' \
  -d '{
    "title": "Services agreement",
    "placement": "page",
    "signingMode": "manual",
    "message": "Please review and sign this agreement.",
    "stages": [{
      "id": "signers",
      "role": "signer",
      "mode": "all",
      "recipients": [{
        "id": "customer",
        "name": "Jordan Lee",
        "email": "jordan@example.com"
      }]
    }]
  }')
document_id=$(printf '%s' "$draft" | jq -r '.id')

Use one creation key for one logical document request. Repeat the same body with that key after a lost response. Reusing the key with a different body returns 409.

Add the PDF

document=$(curl --fail-with-body -sS \
  "https://api.cloudraker.com/v1/signing/documents/$document_id/upload" \
  -H "Authorization: Bearer $RAKESIGN_API_KEY" \
  -F 'file=@agreement.pdf')

Uploads accept PDF, Word, PowerPoint, or Excel files smaller than 20 MB. Use /documents/:id/attachments to add files to a package, up to ten documents. RakeSign prepares Office files as a PDF before signing.

Retrieve /documents/:id/pdf to review the prepared document. With placement: "page", RakeSign appends a signature page. Tag placement uses existing signing markers. Visual field placement requires valid fields for every signing recipient.

Signing markers

With placement: "tags", RakeSign writes into markers already in the document text. Each marker takes a number. signers[0] signs [Signature 1], signers[1] signs [Signature 2], matched by position and never by name.

Markers are not case-sensitive. The space after the full word is optional, so [Signature 1] and [Signature1] are the same field. The short forms take no space, so [S 1] is text, not a marker.

A marker sets where the output goes, not how big it is.

A signature seal is anchored on its marker and takes the free space around it: above and to the right by default, below or to the left when that side is blocked. A full-size seal is about 210 x 86pt. A marker with less room gets a smaller seal, down to a floor of about 120 x 49pt. Every seal in one document prints at the same size, the smallest that any of them fits.

Signature seals step around each other: a seal shrinks or takes another corner rather than print across one already placed. What it cannot step around is an initials or date, which print wider than their own marker. Give each marker its own line, or check overlaps_field before sending.

Initials and dates are written as text at the marker and never move. They shrink to clear whatever is to their right, so leave space on that side. Below a readable floor they stop shrinking and print over their neighbour instead. A date needs more room than its marker suggests, because it is written in full.

Read GET /signing/inspect/document/{id} to see where every marker will print before you send. Each one returns the box its output will take and a status of ok, shrunk, overlaps_text, overlaps_field or off_page. Two things stop a send: a marker with no room on the page, and two signatures that print over each other, which no arrangement can fix. overlapsSignature is true on each signature of such a pair. Every other overlap still prints, and whether that is acceptable is yours to decide.

Edit with the current version

Every draft update must include the latest version. An outdated version returns 409 without replacing the newer draft.

version=$(printf '%s' "$document" | jq -r '.version')
curl --fail-with-body -sS -X PATCH \
  "https://api.cloudraker.com/v1/signing/documents/$document_id" \
  -H "Authorization: Bearer $RAKESIGN_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"version\":$version,\"preparationReviewed\":true}"

Send and track

Sending starts recipient invitations and can complete signing under an active delegation. It does not wait for human recipients to finish.

curl --fail-with-body -sS -X POST \
  "https://api.cloudraker.com/v1/signing/documents/$document_id/send" \
  -H "Authorization: Bearer $RAKESIGN_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{}'

Read GET /documents/:id or subscribe to webhooks. Document statuses include draft, waiting, completed, declined, expired, cancelled, and failed. Recipients can also show awaiting_consent during delegated signing.

After a lost send response, read the document before retrying. A sent document is no longer an editable draft. Use /documents/:id/duplicate when you need a separate editable copy.

Download the result

curl --fail-with-body -sS \
  "https://api.cloudraker.com/v1/signing/documents/$document_id/pdf" \
  -H "Authorization: Bearer $RAKESIGN_API_KEY" \
  -o signed-agreement.pdf
curl --fail-with-body -sS \
  "https://api.cloudraker.com/v1/signing/documents/$document_id/audit" \
  -H "Authorization: Bearer $RAKESIGN_API_KEY" \
  -o agreement-audit.json

Wait for status: "completed" before treating the PDF as the signed result. The same PDF endpoint serves the prepared document before completion.

Start from a template

Use GET /templates to find a team template and its current version. Instantiate it with the roles and values for this document:

{
  "version": 3,
  "title": "Services agreement for Jordan Lee",
  "recipients": [{
    "slot": 1,
    "name": "Jordan Lee",
    "email": "jordan@example.com"
  }]
}

Send this body to POST /templates/:id/instantiate. The response is a new draft with a server-assigned templateOrigin. Standing delegation requires that origin and the matching template revision. Saved rich-text and Word sources preserve this origin when you render changed values or recipient details. Changes to the source content or supporting files remove eligibility. See delegation limits before rendering from a Compose template or external style.

The server assigns source, integrationId, integrationName, and templateOrigin. Do not send those fields in draft updates.