> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formabledocs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Embedded redlining
> Run a turn-based contract negotiation between two parties inside your product.
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](/walkthroughs/embedded-signing) — use redlining when you need negotiation before signature.
## Prerequisites
1. An [API key](/authentication) from [Settings](https://app.formabledocs.com/settings)
2. A [template](/walkthroughs/embedded-templates) 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`.
```bash theme={null}
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
}'
```
```json Response theme={null}
{
"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](/api-reference/endpoint/put-redline-members). This replaces the member list, so send the full set.
```bash theme={null}
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.
```bash theme={null}
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" }'
```
```json Response theme={null}
{
"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:
```html theme={null}
```
Generate the URL on your backend and pass only the URL to the client — the same pattern as [embedded signing](/walkthroughs/embedded-signing#client-side).
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:
```javascript theme={null}
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](/webhooks/overview).
## Track the negotiation
The `currentRound` field indicates whose turn it is (`Disclosing` or `Receiving`), and `status` tracks progress through the negotiation.
```bash theme={null}
curl --request GET \
--url https://api.formabledocs.com/v1/redline-requests/rr_789ghi \
--header "Authorization: Bearer $TOKEN"
```
```json Response theme={null}
{
"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](/api-reference/endpoint/get-redline-request-events). To sync many negotiations, use [List redline requests](/api-reference/endpoint/list-redline-requests) with `updatedSince`.
You can also listen for redlining events on your [webhook endpoint](/webhooks/overview).
## Ready for signing
When the negotiation reaches `DocumentReadyForSigning`, send the finalized template through the [embedded signing](/walkthroughs/embedded-signing) flow using the redline request's `templateId`.
## Next steps
Collect signatures on the finalized template.
Get notified as negotiation status changes.