> ## Documentation Index
> Fetch the complete documentation index at: https://visaflo.ca/knowledge-base/llms.txt
> Use this file to discover all available pages before exploring further.

# Agreements API

> Create an agreement from a template, send it for e-signature, follow its status and download the signed PDF, all from your own system.

From a lead or a case, one call makes the agreement from a template and sends it for e-signature. Your system can follow it to the end: who opened it, who signed, and the signed PDF. [Webhooks](/knowledge-base/knowledge-base/developers/webhooks) tell you when each step happens.

All calls go to `https://api.vflo.app/api/public` with your `X-API-Key` header.

| Step | Call |
| - | - |
| Find a template | `GET /template/list` |
| Make it, and send it | `POST /agreement/create` with `"send": true` |
| Make a draft only | `POST /agreement/create`, then `POST /agreement/{agreementId}/send` |
| Check where it stands | `GET /agreement/{agreementId}` |
| List a record's agreements | `GET /agreement/list?leadId=…` |
| Download the PDF | `GET /agreement/{agreementId}/document/{documentId}` |
| Download the certificate | `GET /agreement/{agreementId}/certificate` |
| Remind the signers | `POST /agreement/{agreementId}/remind` |

## Before you start

1. Create the lead (or use a case): [Create a lead](/knowledge-base/knowledge-base/developers/endpoints/create-lead).
2. Open the template (**Settings** > **Templates** > **Agreements**), then its **Settings** tab, and open **API** for the template ID and a request with the template's own field names.
3. For the API to send a template, it needs sign areas. A Word template with sign-here placeholders (`client_signature`, `client_sign_date`, `rcic_signature` and so on) has them. `GET /template/list` says `sendable: true` for those that do.

## Make it and send it

```bash theme={null}
curl -X POST "https://api.vflo.app/api/public/agreement/create" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "leadId": "VFLO_LEAD_ID",
    "templateName": "Initial Consultation Agreement",
    "send": true,
    "values": { "consultation_duration": "60 minutes", "consultation_fee": "$150.00" },
    "metadata": { "booking_id": "savvycal-8842" }
  }'
```

* The client signs first; the firm signs after, in VisaFlo. Until then the status is `awaiting_countersign`.
* `values` sets the template's variables by exact name. Whatever you leave out fills from the record, the lead's `customFields` of the same name, or the template's default. Money and dates are written the way your workspace writes them.
* `signers` is optional: without it, the record's own contact signs. For more people, send `"signers": [{ "role": "Client", "name": "Jane Doe", "email": "jane@example.com" }, { "role": "Spouse", "email": "sam@example.com" }]`.
* `subject` and `message` change the invitation email.
* `metadata` is your own reference. It comes back on every read and in every webhook event.
* The same call within 24 hours returns the first agreement with `"duplicate": true` and sends nothing twice, so retries are safe.
* Everything is checked before anything is sent. If it can't go, you get a `422` with a `code` (`missing_fields`, `no_sign_areas`, `no_signer_email` and so on) and the list of problems in `data.issues`.

Sending renders the PDF, so it takes a few seconds.

## Follow it

```bash theme={null}
curl "https://api.vflo.app/api/public/agreement/VFLO_AGREEMENT_ID" -H "X-API-Key: YOUR_API_KEY"
```

`status` is `draft`, `sent`, `awaiting_countersign` or `completed`. Each signer is `pending`, `viewed` or `signed`, with `viewedAt` and `signedAt`. `documents[].downloadUrl` and `certificateUrl` need your API key.

Rather than asking again and again, set up a [webhook](/knowledge-base/knowledge-base/developers/webhooks).

## Download the signed PDF

```bash theme={null}
curl -o signed.pdf "https://api.vflo.app/api/public/agreement/VFLO_AGREEMENT_ID/document/DOCUMENT_ID?version=signed" -H "X-API-Key: YOUR_API_KEY"
```

`version=original` (the default) is the document as sent. `version=signed` is the copy everyone has signed so far, and answers `409 not_signed` until someone has.

## Zapier and Make

* Send `"send": "true"` as text if your tool only sends text.
* Map fields to `values__consultation_fee`, `signers__Spouse__email` and `metadata__booking_id` when the tool can't build nested JSON.
* Numbers and booleans can be sent as text.

## Limits

* No cancel or delete through the API yet. Do that in VisaFlo.
* 50 `values` keys, 20 `metadata` keys, 6 signers.


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