Embedded redlining

Redlining lets two parties negotiate revisions to a DOCX contract in turns. You create a redline request on your server, then embed a member-specific redline URL in an iframe so each party can revise on their turn. This walkthrough covers creating a redline request, managing members, embedding redline URLs, and tracking the negotiation until the document is ready to sign.

Redlining edits the underlying document, so the template must have a DOCX source file. Creating a redline request for a template without one returns 404. Most integrations only need embedded signing — use redlining when you need negotiation before signature.

Prerequisites

An API key from Settings
A template uploaded from a DOCX file

Roles

A redline request has members, each with a role. The two core parties are set up front; counsel can be added later.

Role	Description
`DisclosingParty`	Originated the contract.
`ReceivingParty`	Requests changes to the contract.
`DisclosingCounsel`	Helps the disclosing party.
`ReceivingCounsel`	Helps the receiving party.

Server side

1. Create a redline request

Provide the templateId and at least one member. Each member needs an email, displayName, and role.

curl --request POST \
  --url https://api.formabledocs.com/v1/redline-requests \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "templateId": "abc123xyz",
    "members": [
      { "email": "legal@acme.com", "displayName": "Acme Legal", "role": "DisclosingParty" },
      { "email": "counsel@client.com", "displayName": "Client Counsel", "role": "ReceivingParty" }
    ],
    "metadata": { "subject": "Mutual NDA" },
    "testMode": true
  }'

Response

{
  "redlineRequestId": "rr_789ghi",
  "templateId": "def456uvw"
}

The response templateId is a new template created for this negotiation — a copy that receives the redlining changes. Your original template is left untouched.

The optional metadata.subject sets a subject line for the negotiation. Set testMode: true to keep the request out of billing while you integrate. Test mode documents are watermarked and are not legally binding.

2. Manage members

Add or update members at any time — for example, to invite counsel — with Update redline members. This replaces the member list, so send the full set.

curl --request PUT \
  --url https://api.formabledocs.com/v1/redline-requests/rr_789ghi/members \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "members": [
      { "email": "legal@acme.com", "displayName": "Acme Legal", "role": "DisclosingParty" },
      { "email": "counsel@client.com", "displayName": "Client Counsel", "role": "ReceivingParty" },
      { "email": "outside@lawfirm.com", "displayName": "Outside Counsel", "role": "ReceivingCounsel" }
    ]
  }'

3. Generate a redline URL for a member

Each member works on their turn through a member-specific redline URL. Pass the member’s email — they must already be part of the request. Generate the URL just-in-time; it is short-lived.

curl --request POST \
  --url https://api.formabledocs.com/v1/redline-requests/rr_789ghi/url \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{ "memberEmail": "counsel@client.com" }'

Response

{
  "redlineUrl": "https://app.formabledocs.com/redlining/embedded/xyz789abc",
  "expiresAt": "2024-01-16T10:30:00.000Z"
}

Client side

Embed the redlineUrl in an iframe for that member:

<iframe
  src="https://app.formabledocs.com/redlining/embedded/xyz789abc"
  width="100%"
  height="800"
  allow="fullscreen"
  style="border: none;"
></iframe>

Generate the URL on your backend and pass only the URL to the client — the same pattern as embedded signing.

If it isn’t the member’s turn, the URL opens in a read-only “out of turn” view. Regenerate the URL if the member returns after it has expired.

Listen for editor events

The redline editor posts messages to the parent window so you can close the iframe or advance your UI:

window.addEventListener("message", (event) => {
  if (event.origin !== "https://app.formabledocs.com") return;
  if (!event.data || typeof event.data !== "object") return;

  switch (event.data.type) {
    case "onRedlineEditorSaved":
      // Turn submitted or review finished — close the iframe
      break;
    case "onRedlineEditorError":
      // Save failed — show an error or retry
      break;
    case "onRedlineEditorClosed":
      // User confirmed exit without saving
      break;
    case "userRequestedToSign":
      // User chose to proceed to signing without further revisions
      break;
  }
});

Message `type`	When it fires
`onRedlineEditorSaved`	The user submitted their turn or finished review.
`onRedlineEditorError`	The editor could not complete the save/submit.
`onRedlineEditorClosed`	The user closed the editor (for example after confirming exit).
`userRequestedToSign`	The user chose to sign without requesting further changes.

Always check event.origin. Use these for client UX; confirm negotiation state with the API or webhooks.

Track the negotiation

The currentRound field indicates whose turn it is (Disclosing or Receiving), and status tracks progress through the negotiation.

curl --request GET \
  --url https://api.formabledocs.com/v1/redline-requests/rr_789ghi \
  --header "Authorization: Bearer $TOKEN"

Response

{
  "templateId": "def456uvw",
  "status": "ReceivingPartyRequestedReview",
  "currentRound": "Disclosing",
  "testMode": false,
  "members": [
    { "role": "DisclosingParty", "email": "legal@acme.com", "displayName": "Acme Legal" },
    { "role": "ReceivingParty", "email": "counsel@client.com", "displayName": "Client Counsel" }
  ]
}

Status	Meaning
`ReceivingPartyOpened`	The receiving party opened the document.
`ReceivingPartyDraft`	The receiving party is drafting revisions.
`ReceivingPartyRequestedReview`	Revisions sent to the disclosing party for review.
`DisclosingPartyDraft`	The disclosing party is drafting revisions.
`DisclosingPartyRequestedReview`	Revisions sent to the receiving party for review.
`DocumentReadyForSigning`	All changes resolved; ready to sign.

For a full history of turn changes and review requests, read redline request events. To sync many negotiations, use List redline requests with updatedSince. You can also listen for redlining events on your webhook endpoint.

Ready for signing

When the negotiation reaches DocumentReadyForSigning, send the finalized template through the embedded signing flow using the redline request’s templateId.

Getting Started

Walkthroughs

SDKs

Migrations

Webhooks

Prerequisites

Roles

Server side

1. Create a redline request

2. Manage members

3. Generate a redline URL for a member

Client side

Listen for editor events

Track the negotiation

Ready for signing

Next steps

Embedded signing

Webhooks

​Prerequisites

​Roles

​Server side

​1. Create a redline request

​2. Manage members

​3. Generate a redline URL for a member

​Client side

​Listen for editor events

​Track the negotiation

​Ready for signing

​Next steps

Embedded signing

Webhooks

Prerequisites

Roles

Server side

1. Create a redline request

2. Manage members

3. Generate a redline URL for a member

Client side

Listen for editor events

Track the negotiation

Ready for signing

Next steps