# Send an Envelope with an Uploaded Document

Use this method when sending a **one-off document** that is not set up as a Template — e.g. a bespoke contract, NDA, or custom agreement.

## 📥 Workflow overview

A typical flow looks like this:

1. Prepare your document (PDF, Word, etc.)
2. Add Signable text tags to mark where fields should appear
3. Convert your document to Base64 **or** host it and provide a URL
4. Create an envelope via [POST /v1/envelopes](/openapi/envelopes/sendenvelope)


> 💡 **Already authenticated?**
If not, follow the [Authentication guide](/authentication).


## Step 1 — Prepare your document

Your document should include **Signable Tags**. These tags tell Signable where each field should appear and which signer it belongs to.

### Tag format

{Type:Who:Name}

#### Type

Specifies the kind of field you want to place.

Supported values: `signature`, `text`, `date`, `check`, `upload`

#### Who

The `party_role` this field belongs to (e.g. `signer1`, `signer2`).
Each party in your API request should match the roles used in your tags.

#### Name

The label you want to assign to the field. This is how the field will appear to the signer.

### Example

{text:signer1:Full+Name}

This creates a text field, assigned to `signer1`, labelled “Full Name”.

> 💡 For more details, see the full [Signable Tags reference](https://help.signable.app/article/160-what-are-signable-tags).


## Step 2 — Provide your document content

You can use **one** of:

- `document_file_content` (Base64)
- `document_url` (URL to a publicly accessible document)


> ⚠️ You must choose **one method only**. Including both will return an error.


## Step 3 — Create your POST request

**Endpoint**


```http
POST https://api.signable.co.uk/v1/envelopes
```

**Example request body**


```
{
  "envelope_title": "Singer Road 23/06/25",
  "envelope_parties": [
    {
      "party_name": "Alex Mitchell",
      "party_email": "abby+alex@signable.co.uk",
      "party_role": "signer1"
    }
  ],
  "envelope_documents": [
    {
      "document_url": "https://yellow-della-30.tiiny.site/Tenancy-Contract-2025-v2.pdf",
      "document_title": "Test Agreement"
    },
    {
      "document_title": "Validation Contract",
      "document_file_name": "ValidationContract.pdf",
      "document_file_content": "JVBERi0xLjQKJdPr6...Zgo2MDE3MwolJUVPRgo=" // abbreviated for brevity
    }
  ]
}
```

Fields correspond to the tags you added earlier.

For example, `{signature:signer1:Please+Sign+Here}` maps to party with `party_role: signer1`.

> 🪧 For full endpoint details, see [POST Send an envelope](https://developers.signable.app/openapi/envelopes/sendenvelope).


## What happens next

Once the envelope is created:

- Signers receive an email with their signing link
- You receive an envelope fingerprint in API response
- You can subscribe to webhooks for status updates (optional)