Send an agreement with approval

This guide follows one agreement, a mutual NDA for Acme, from template to signed copy. It uses an agent key, so a person approves the send. The calls are the same through the REST API and the MCP server. Each step shows both.

You need a workspace on any plan, a template with a signing role (here client), and an agent key with the read, documents and send permissions. The key and the template must be in the same workspace: get_workspace says which one the key is in.

No template yet? Save one from the library with Save as template, or have the agent make one with create_template, from text or a library entry. See Create a template. The steps below assume a template that signs as client, with the fill-ins client_name and effective_date. With another one, use the roles and fill_ins that get_template returns: a request needs a recipient for each role. The library's Mutual NDA, for example, signs as company and counterparty.

1. Find the template

REST

curl https://tryjustdocs.com/api/v1/templates \
  -H "Authorization: Bearer $JUSTDOCS_AGENT_KEY"

MCP

list_templates {}

Pick the template by title, then fetch it for its fill-ins and the questions that answer them:

REST

curl https://tryjustdocs.com/api/v1/templates/5d0f8c3a-6b1e-4f2a-9c7d-3e8b1a2f4c6d \
  -H "Authorization: Bearer $JUSTDOCS_AGENT_KEY"

MCP

get_template { "template_id": "5d0f8c3a-6b1e-4f2a-9c7d-3e8b1a2f4c6d" }

fill_ins lists each blank by key, such as client_name and effective_date. roles lists who signs, such as client: the request needs a recipient for each. form holds the template's questions, if it has them.

2. Start the document

Give the fill-in values by key with merge_values, or answer the template's questions with answers and let JustDocs fill the blanks. Use one or the other, not both.

REST

curl -X POST https://tryjustdocs.com/api/v1/documents \
  -H "Authorization: Bearer $JUSTDOCS_AGENT_KEY" \
  -H "Idempotency-Key: deal-4821-nda-doc" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "5d0f8c3a-6b1e-4f2a-9c7d-3e8b1a2f4c6d",
    "title": "Mutual NDA — Acme",
    "merge_values": { "client_name": "Acme Inc.", "effective_date": "November 3, 2026" }
  }'

MCP

start_document {
  "template_id": "5d0f8c3a-6b1e-4f2a-9c7d-3e8b1a2f4c6d",
  "title": "Mutual NDA — Acme",
  "merge_values": { "client_name": "Acme Inc.", "effective_date": "November 3, 2026" },
  "idempotency_key": "deal-4821-nda-doc"
}

The response is the new document, with its id.

3. Ask to send it

Create the signing request with a recipient for each role in the document, and send: true:

REST

curl -X POST https://tryjustdocs.com/api/v1/signing-requests \
  -H "Authorization: Bearer $JUSTDOCS_AGENT_KEY" \
  -H "Idempotency-Key: deal-4821-nda-send" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Mutual NDA — Acme",
    "message": "Please review and sign.",
    "documents": [{ "document_id": "8a1f5c2e-3b4d-4e6f-9a7b-1c2d3e4f5a6b" }],
    "recipients": [{ "role_key": "client", "name": "Ada Lovelace", "email": "ada@example.com" }],
    "send": true
  }'

MCP

create_signing_request {
  "title": "Mutual NDA — Acme",
  "message": "Please review and sign.",
  "documents": [{ "document_id": "8a1f5c2e-3b4d-4e6f-9a7b-1c2d3e4f5a6b" }],
  "recipients": [{ "role_key": "client", "name": "Ada Lovelace", "email": "ada@example.com" }],
  "send": true,
  "idempotency_key": "deal-4821-nda-send"
}

Because the key is an agent key, nothing is emailed yet. The REST API answers 202 Accepted. The request is a draft, and its approval is pending:

{
  "id": "c3e9a7b1-2d4f-4a6c-8e1b-5f7d9a2c4e6b",
  "status": "draft",
  "approval": {
    "id": "a4c6e8b2-1d3f-4b5a-8c7e-9f1b3d5a7c2e",
    "kind": "signing.send",
    "status": "pending",
    "addresses": ["ada@example.com"],
    "expires_at": "2026-11-10T16:20:01.000Z"
  }
}

The MCP tool returns the same, after a line telling the agent that nothing has been sent and that it should check get_approval.

With more than one signer, routing decides the order. sequential (the default) emails each routing_order in turn. parallel emails everyone at once.

4. A person approves

The workspace's owner, or a team's owners and admins, see the request on the workspace's Approvals page, with its title, every address, and the key that asked. Home lists it too, with a link there. Approve sends it at once, in the name of the person who made the key. The key and its limits are checked again first. Decline sends nothing.

On Teams & Platform, a webhook for approval.requested can alert the approvers in your own tools, such as chat or a ticket.

5. Follow it

Poll the approval or, on Teams & Platform, listen for webhooks:

REST

curl https://tryjustdocs.com/api/v1/approvals/a4c6e8b2-1d3f-4b5a-8c7e-9f1b3d5a7c2e \
  -H "Authorization: Bearer $JUSTDOCS_AGENT_KEY"

MCP

get_approval { "approval_id": "a4c6e8b2-1d3f-4b5a-8c7e-9f1b3d5a7c2e" }

Event	Means
approval.decided with status: "approved"	Approved, and the request was sent.
request.sent	The request is sent, and the first recipients' invitations are on their way.
request.viewed, request.signed	Each recipient's progress.
request.completed	Everyone signed. The completed copy is ready.
approval.decided with declined, expired or failed	Nothing was sent through the approval. reason says why it failed, or that it expired because someone sent the request from the app.

get_signing_request shows each recipient's status and the latest email delivery. When the request is completed, each document has completed_copy: true, and the signed copies are in JustDocs.

If something changes

• Wrong recipient? Void it with void_signing_request and a reason. Voiding takes effect at once, without approval, and recipients who were invited are told. Then create a new one.
• Still a draft? A request created with send: false can be sent later with send_signing_request, which also waits for approval.
• Retrying after a timeout? Use the same idempotency key. You get the first result, and no second request or approval is made.