Approvals

A live agent key can't send a document. It can only ask. A named person approves the exact draft, and the server holds the line whatever the agent was told.

The flow

1. The agent calls create_document. It gets a draft_hash and a review_url. Nothing is sent.
2. The agent calls send_document with the id and draft_hash.
3. The server compares the hash to the draft. If they differ, it refuses with draft_changed.
4. The document moves to pending_approval. The reply has an approval_url and nothing is sent. The account owner is told by email, and the approval.requested webhook fires.
5. A person signs in, opens the link and reads the draft as the server holds it.
6. They approve, and the server sends it. Or they reject, and it goes back to being a draft.
7. The agent reads the outcome with get_document, or waits for approval.approved.

What the hash covers

The draft_hash covers the PDF bytes, the title, the message, the signing order, the disclosure setting, every signer's name and email, and every field. Change any of them and the hash changes. Approving a hash approves exactly that. If the draft changed after the request, the approval is refused.

Who counts as an agent

A "Sends directly" key is for code you wrote and control. Don't give one to an agent. If you connect it over MCP, it is treated as an agent anyway.

What approval looks like

Approval needs a signed-in person on the account. There is no approve call in the API, so no key can approve its own request. A request lasts 24 hours. The approver's identity and the hash go into the evidence log, next to the key that asked. The record keeps the agent and the person apart.

What this doesn't stop

We prefer plain limits to big claims. An approver can still approve a bad draft, so read it. A person with a "Sends directly" key can hand it to an agent over REST. And an agent with full access to a signer's inbox could open that signer's link. We block signing by credential and make every step show in the record, but we can't reach inside someone's mailbox. For a high-value document, add an access_code and share it outside email.

Test mode

Approval works the same in test mode, so you see the step before going live: the approval page carries a TEST banner. For CI and agent evals, simulate_approval approves a test draft without a person. It never works on a live document. See test mode.

Common questions

Can a person approve from the API?

No. Approval happens only on the signed-in page. If a key could approve, an agent holding that key could approve itself.

What happens if nobody approves in 24 hours?

The request lapses and nothing is sent. It can no longer be approved. A person can open it and reject it, which returns the document to a draft, and then the agent can ask again.

Can I let trusted automation skip approval?

Yes, over REST. Use a key set to "Sends directly" for code you control, such as a server sending a fixed template. Agents and MCP clients can't skip it.