> ## Documentation Index
> Fetch the complete documentation index at: https://about.sendforsign.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Recipes for agent builders

> Agent recipes with Sendforsign: contract from a template, fill and send; embedded signing links in your own UI without email; one tenant per customer; webhooks when a contract is fully signed.

Each recipe shows the MCP tool calls an agent makes and the equivalent REST requests, for when you'd rather run the
deterministic part in your own code and let the agent only decide *what* to send.

## Template → fill → send

The most common flow: a standard document from the customer's template, the agent fills its fields, a human approves,
the recipients get an email.

**1. Find the template**

`list_templates`, then `get_template` with the chosen `templateKey`. The response lists every field with
`filledBy`. The agent fills `owner` fields; `any_recipient` and `specific_recipient` fields belong to the signers.

**2. Create the draft with fields and recipients**

```json create_contract theme={null}
{
  "name": "NDA — Acme Ltd",
  "templateKey": "TEMPLATE_KEY",
  "fields": [
    { "name": "Company name", "value": "Acme Ltd" },
    { "name": "Effective date", "value": "1 December 2026" }
  ],
  "recipients": [
    { "fullname": "Anna Smith", "email": "anna@acme.example", "action": "sign" }
  ]
}
```

The result has `contractKey`, the recipients with `signingUrl`, and `unfilledFields` — owner fields the agent
still has to fill (use `fill_placeholders`) or ask the user about. Nobody has been emailed.

**3. Show the user and get approval**

The agent shows the contract name, the filled values, each recipient and their role, and asks to send.

**4. Send**

```json send_for_signature theme={null}
{ "contractKey": "CONTRACT_KEY", "confirm": true }
```

Requires `send` mode. Recipients are emailed in signing order.

**5. Track**

`get_contract_timeline` for events, `download_contract_pdf` once the status is `Fully signed`. In production,
listen to the [webhook](#react-when-a-contract-is-fully-signed) instead of polling.

The same in REST:

```bash cURL theme={null}
# 1. Draft from template (no recipients here: that would send email immediately)
curl -X POST 'https://api.sendforsign.com/api/contract' \
  -H "X-Sendforsign-Key: $SFS_KEY" -H 'Content-Type: application/json' \
  -d '{"data":{"action":"create","clientKey":"CLIENT_KEY",
       "contract":{"name":"NDA — Acme Ltd","templateKey":"TEMPLATE_KEY"}}}'

# 2. Fill fields: list the contract's fields (they have new keys, not the template's), then update each by key
curl -X POST 'https://api.sendforsign.com/api/placeholder' \
  -H "X-Sendforsign-Key: $SFS_KEY" -H 'Content-Type: application/json' \
  -d '{"data":{"action":"list","clientKey":"CLIENT_KEY","contractKey":"CONTRACT_KEY"}}'
curl -X POST 'https://api.sendforsign.com/api/placeholder' \
  -H "X-Sendforsign-Key: $SFS_KEY" -H 'Content-Type: application/json' \
  -d '{"data":{"action":"update","clientKey":"CLIENT_KEY","contractKey":"CONTRACT_KEY",
       "placeholder":{"placeholderKey":"CONTRACT_PLACEHOLDER_KEY","value":"Acme Ltd"}}}'

# 3. Add recipients without emailing them
curl -X POST 'https://api.sendforsign.com/api/recipient' \
  -H "X-Sendforsign-Key: $SFS_KEY" -H 'Content-Type: application/json' \
  -d '{"data":{"action":"create","clientKey":"CLIENT_KEY","contractKey":"CONTRACT_KEY",
       "recipients":[{"fullname":"Anna Smith","email":"anna@acme.example","action":"sign","position":1}]}}'

# 4. After approval: send (emails the recipients); include position for every recipient
curl -X POST 'https://api.sendforsign.com/api/recipient' \
  -H "X-Sendforsign-Key: $SFS_KEY" -H 'Content-Type: application/json' \
  -d '{"data":{"action":"send","clientKey":"CLIENT_KEY","contractKey":"CONTRACT_KEY",
       "recipients":[{"recipientKey":"RECIPIENT_KEY","fullname":"Anna Smith","email":"anna@acme.example","action":"sign","position":1}]}}'
```

> [!WARNING]
>
> In REST, `contract` `create` **with** a `recipients` array [creates and sends](https://about.sendforsign.com/api-reference/contract/create-send.md)
> in one call: the recipients are emailed immediately. `recipient` `create` adds recipients **without** email;
> `recipient` `send` emails them. The MCP `create_contract` tool always takes the safe path.

> [!TIP]
>
> A contract made from a template gets its own field keys. Match template fields to contract fields by name (from
> [placeholder `list`](https://about.sendforsign.com/api-reference/placeholder/list) on the contract), then fill them by the contract's
> `placeholderKey`. Filling by `name` inside `contract` `create` is not reliable. In `recipient` `send`, give every
> recipient a `position`.

## Embedded signing without email

Your product already talks to the signer (in your app, a chat, a portal). Show the signing link there and never send a
Sendforsign email.

1. Create the draft and add recipients (`create_contract` with `recipients`, or `add_recipients`). Both return each
   recipient's `signingUrl`:

   ```bash theme={null}
   https://app.sendforsign.com/sharing/{recipientKey}
   ```

   With a [recipient custom domain](https://about.sendforsign.com/usecase/recipientdomain.md) the links can be on your own domain.

2. Give each signer **their own** link in your UI: a button, a message, or an iframe/new tab. The link identifies the
   recipient, so treat it like a password reset link: show it only to that person.

3. Don't call `send_for_signature`. The agent can run in `draft` mode for this flow.

4. Learn about the signature from the [webhook](#react-when-a-contract-is-fully-signed).

In REST, the `recipientKey` comes from [recipient `list`](https://about.sendforsign.com/api-reference/recipient/list).

For a fully embedded editor and contract list (review and edit what the agent drafted), use the
[React components](https://about.sendforsign.com/sdk/introsdk.md), and set your [branding](https://about.sendforsign.com/api-reference/settings/branding.md) for any emails you do send.

## One tenant per customer

A product with many customers keeps each customer's templates and contracts apart. The tenant is chosen by **your**
code through headers, so an agent working for customer A cannot see customer B's contracts.

| Level | Key | Use it for |
| - | - | - |
| Client | `clientKey` | A customer business. Strongest separation: own templates, contracts, [webhooks](https://about.sendforsign.com/api-reference/webhook/concept.md) and branding. [Create](https://about.sendforsign.com/api-reference/client/create.md) |
| User | `userKey` | An end user or team inside a client. [Create](https://about.sendforsign.com/api-reference/user/create.md), or `create_user` over MCP |

Setup, once per customer (from your backend):

```bash cURL theme={null}
curl -X POST 'https://api.sendforsign.com/api/client' \
  -H "X-Sendforsign-Key: $SFS_KEY" -H 'Content-Type: application/json' \
  -d '{"data":{"action":"create","client":{"fullname":"Jane Doe","email":"jane@customer.example","organization":"Customer Inc.","customKey":"your-customer-id"}}}'
```

Store the returned `clientKey` with the customer. When a user of that customer starts an agent session, open the MCP
connection with:

```bash theme={null}
X-Sendforsign-Client-Key: CLIENT_KEY_OF_THAT_CUSTOMER
X-Sendforsign-User-Key: USER_KEY_OF_THAT_USER        # optional
X-Sendforsign-On-Behalf-Of: jane@customer.example
```

## React when a contract is fully signed

Webhooks are per `clientKey`. Register one per client:

```bash cURL theme={null}
curl -X POST 'https://api.sendforsign.com/api/webhook' \
  -H "X-Sendforsign-Key: $SFS_KEY" -H 'Content-Type: application/json' \
  -d '{"data":{"action":"create","clientKey":"CLIENT_KEY",
       "webhooks":[{"url":"https://your-app.example/hooks/sendforsign","signed":true,"fullySigned":true}]}}'
```

When the last recipient signs, your endpoint receives:

```json theme={null}
{
  "clientKey": "CLIENT_KEY",
  "contractKey": "CONTRACT_KEY",
  "createTime": "2026-12-01T16:06:56.000Z",
  "status": "contract.fully_signed",
  "contractName": "NDA — Acme Ltd"
}
```

Then download the signed PDF ([`GET /api/download_pdf`](https://about.sendforsign.com/api-reference/pdf/download)), store it, and tell the agent or
the user. To resume an agent conversation, pass it the `contractKey`; it can call `get_contract` and
`get_contract_timeline`. All events: [webhooks concept](https://about.sendforsign.com/api-reference/webhook/concept.md).

## Upload a finished text and get it signed

For legal-AI products that draft elsewhere: pass the final text as `content` (Markdown by default, or
`contentFormat: "html"`) to `create_contract`, add signers, send. For a PDF, use [PDF upload](https://about.sendforsign.com/api-reference/pdf/upload.md)
and [PDF placeholders](https://about.sendforsign.com/api-reference/placeholder/pdfbasic.md) in REST.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.