# Send an envelope with an uploaded document

Send a one-off document that is not set up as a template, such as a bespoke contract, NDA, or custom agreement. This method allows you to upload a document directly or provide a URL to a hosted file.

## Prerequisites

Ensure you have:

- Completed the [Authentication guide](/authentication)
- API credentials configured
- A document prepared with Signable tags (see below)


## Workflow overview

1. Prepare your document with Signable tags.
2. Convert your document to base64 or host it at a public URL.
3. Create an envelope with the document.


## Prepare your document

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

### Tag format

Tags follow this structure:


```
{Type:Who:Name}
```

| Component | Description |
|  --- | --- |
| `Type` | The kind of field to place. Supported values: `signature`, `text`, `date`, `check`, `upload` |
| `Who` | The `party_role` this field belongs to, such as `signer1` or `signer2`. Each party in your API request must match the roles used in your tags. |
| `Name` | The label for the field. This is how the field appears to the signer. Use `+` for spaces. |


### Example tag


```
{text:signer1:Full+Name}
```

This creates a text field assigned to `signer1` with the label "Full Name".

For more details on tag syntax, see [Use Signable tags](/tags).

## Provide your document content

Include one or more of your documents in the request, using one of the following methods:

| Field | Description |
|  --- | --- |
| `document_file_content` | The document encoded as a base64 string |
| `document_url` | A URL to a publicly accessible document |


## Create the envelope request

Send a POST request to create the envelope:


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

**Example request body:**


```json
{
  "envelope_title": "Singer Road 23/06/25",
  "envelope_parties": [
    {
      "party_name": "Alex Mitchell",
      "party_email": "alex@example.co.uk",
      "party_role": "signer1"
    }
  ],
  "envelope_documents": [
    {
      "document_url": "https://example.com/documents/Tenancy-Contract-2025.pdf",
      "document_title": "Test Agreement"
    },
    {
      "document_title": "Validation Contract",
      "document_file_name": "ValidationContract.pdf",
      "document_file_content": "JVBERi0xLjQKJdPr6...Zgo2MDE3MwolJUVPRgo="
    }
  ]
}
```

### Understand the request

This request creates an envelope with two documents:

- The first document is retrieved from a URL
- The second document is provided as a base64-encoded string


The `party_role: signer1` maps to any tags in the documents that specify `signer1`. For example, `{signature:signer1:Please+Sign+Here}` creates a signature field for Alex Mitchell.

For full endpoint details, see [Send an envelope](/openapi/envelopes/sendenvelope).

## After you send the request

A successful request returns an envelope fingerprint in the response. Signable sends each signer an email with their signing link.

To track envelope progress programmatically, subscribe to webhooks for status updates.

## Related guides

- [Send an envelope using a template](/guides/send-envelope/send-envelope-template) — Use a pre-configured template instead of uploading a document
- [Tags](/tags) — Full reference for Signable tag syntax and field types
- [Webhooks](/webhooks) — Configure notifications to track when signers complete documents