---
title: "Create an upload"
description: "Upload a PDF, DOCX, or PNG file to SignatureAPI and get back a URL to use as a document source."
canonical: "https://signatureapi.com/docs/api/resources/uploads/create"
source: "https://signatureapi.com/docs/api/resources/uploads/create.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T11:48:11Z"
---

# Create an upload

Upload a PDF, DOCX, or PNG file to SignatureAPI and get back a URL to use as a document source.

_Last verified against API version 1.18.0._

Upload a file to SignatureAPI for use as a document source in an envelope. Send the raw file bytes in the request body with the appropriate `Content-Type` header.

The response includes a `url` property. Pass this value as the `url` property of a [document](https://signatureapi.com/docs/api/resources/documents/object) when creating an envelope:

```json Document in the create envelope request
{
  "url": "https://api.signatureapi.com/v1/uploads/upl_3JJz6t1o8A5YjX5VpnX27Z",
  "format": "pdf"
}
```

> **Note:** Uploads created through this endpoint are temporary and expire 24 hours after creation. To store a file permanently for reuse across multiple envelopes, use the [Store Upload](https://signatureapi.com/docs/api/resources/uploads/store) endpoint or upload it to your [Library](https://dashboard.signatureapi.com/library) in the dashboard.

> **Info:** The Create Upload endpoint replaces the [Create File endpoint](https://signatureapi.com/docs/api/resources/files/create). The File resource is soft-deprecated but remains available for backward compatibility.

## Request

Send the raw file bytes as the request body. Set the `Content-Type` header to match the file format.

| Content-Type                                                              | Format |
| ------------------------------------------------------------------------- | ------ |
| `application/pdf`                                                         | `pdf`  |
| `application/vnd.openxmlformats-officedocument.wordprocessingml.document` | `docx` |
| `image/png`                                                               | `png`  |

> **Warning:** Maximum file size: 4.5 MB.
>
> For a larger file, up to the 10 MB [document limit](https://signatureapi.com/docs/api/resources/documents/object#limits), put it on a [supported host](https://signatureapi.com/docs/api/resources/documents/url#external-store) such as Amazon S3 and pass its URL as the document's `url`. Storing an upload with [Store Upload](https://signatureapi.com/docs/api/resources/uploads/store) makes it permanent but does not raise the 4.5 MB limit.

#### cURL

```bash
curl -X POST https://api.signatureapi.com/v1/uploads \
  --data-binary "@/path/to/file.pdf" \
  -H "Content-Type: application/pdf" \
  -H "X-API-Key: $SIGNATUREAPI_KEY"
```

#### TypeScript

```typescript
import axios from "axios";
import * as fs from "fs";

async function uploadPdf() {
  const fileStream = fs.createReadStream("/path/to/file.pdf");

  const response = await axios.post(
    "https://api.signatureapi.com/v1/uploads",
    fileStream,
    {
      headers: {
        "Content-Type": "application/pdf",
        "X-API-Key": process.env.SIGNATUREAPI_KEY,
      },
    }
  );

  console.log("Upload successful:", response.data);
}

uploadPdf();
```

#### Python

```python
import os

import requests

with open("/path/to/file.pdf", "rb") as f:
    response = requests.post(
        "https://api.signatureapi.com/v1/uploads",
        headers={
            "Content-Type": "application/pdf",
            "X-API-Key": os.environ["SIGNATUREAPI_KEY"]
        },
        data=f
    )

print(response.json())
```

#### Ruby

```ruby
require "net/http"
require "uri"

uri = URI("https://api.signatureapi.com/v1/uploads")

File.open("/path/to/file.pdf", "rb") do |file|
  request = Net::HTTP::Post.new(uri)
  request["Content-Type"] = "application/pdf"
  request["X-API-Key"] = ENV["SIGNATUREAPI_KEY"]
  request.body = file.read

  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
    http.request(request)
  end

  puts response.body
end
```

#### C#

```csharp
using System.Net.Http;
using System.Net.Http.Headers;

using var client = new HttpClient();
using var fileStream = File.OpenRead("/path/to/file.pdf");

var request = new HttpRequestMessage(HttpMethod.Post, "https://api.signatureapi.com/v1/uploads")
{
    Content = new StreamContent(fileStream)
};
request.Content.Headers.ContentType = new MediaTypeHeaderValue("application/pdf");
request.Headers.Add("X-API-Key", Environment.GetEnvironmentVariable("SIGNATUREAPI_KEY"));

var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

#### Java

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Path;

var client = HttpClient.newHttpClient();

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.signatureapi.com/v1/uploads"))
    .header("Content-Type", "application/pdf")
    .header("X-API-Key", System.getenv("SIGNATUREAPI_KEY"))
    .POST(HttpRequest.BodyPublishers.ofFile(Path.of("/path/to/file.pdf")))
    .build();

var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```

#### Go

```go
package main

import (
  "bytes"
  "fmt"
  "io"
  "net/http"
  "os"
)

func main() {
  file, err := os.Open("/path/to/file.pdf")
  if err != nil {
    panic(err)
  }
  defer file.Close()

  data, err := io.ReadAll(file)
  if err != nil {
    panic(err)
  }

  req, err := http.NewRequest("POST", "https://api.signatureapi.com/v1/uploads", bytes.NewReader(data))
  if err != nil {
    panic(err)
  }
  req.Header.Set("Content-Type", "application/pdf")
  req.Header.Set("X-API-Key", os.Getenv("SIGNATUREAPI_KEY"))

  client := &http.Client{}
  resp, err := client.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()

  body, _ := io.ReadAll(resp.Body)
  fmt.Println(string(body))
}
```

> **Warning:** File uploads must be made from your server, not from the browser. The API requires your API key in the request header, which must never be exposed to the client. If you need to accept files from users in the browser, upload the file to your own server first, then forward it to the SignatureAPI uploads endpoint.

## Returns

Returns a `201 Created` status code and [an upload object](https://signatureapi.com/docs/api/resources/uploads/object) on success, or an [error](https://signatureapi.com/docs/api/errors) otherwise.

### Example: PDF upload

Send the raw bytes of the file as the request body.

```http
POST /v1/uploads HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/pdf

<binary PDF content>
```

Response 201 Created:

```json
{
  "id": "upl_3JJz6t1o8A5YjX5VpnX27Z",
  "retention": "temporary",
  "url": "https://api.signatureapi.com/v1/uploads/upl_3JJz6t1o8A5YjX5VpnX27Z",
  "sha_256": "4f1c8a7e92b3d05a6e8c1f4b7d2a9053c6e8b1d4f7a20935c8e1b4d7a0f36c92",
  "size": 102400,
  "format": "pdf",
  "created_at": "2026-11-02T14:00:00.000Z",
  "expires_at": "2026-11-03T14:00:00.000Z"
}
```

Response 422 Unprocessable Content:

```json
{
  "type": "https://signatureapi.com/docs/v1/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "errors": [
    "The file must be a valid PDF, DOCX, or PNG"
  ]
}
```

### Example: DOCX upload

```http
POST /v1/uploads HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document

<binary DOCX content>
```

Response 201 Created:

```json
{
  "id": "upl_1sAAaVfabdt0esVjmSTmLA",
  "retention": "temporary",
  "url": "https://api.signatureapi.com/v1/uploads/upl_1sAAaVfabdt0esVjmSTmLA",
  "sha_256": "a8d3f06b19c2e4750d6b8a1f3c9e27d45b0a6f8e1c3d92b7405e6a8f1d3c7b09",
  "size": 234567,
  "format": "docx",
  "created_at": "2026-11-02T14:00:00.000Z",
  "expires_at": "2026-11-03T14:00:00.000Z"
}
```

### Example: PNG upload

```http
POST /v1/uploads HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: image/png

<binary PNG content>
```

Response 201 Created:

```json
{
  "id": "upl_42NTdNnkg6dGLx8jR1X1wm",
  "retention": "temporary",
  "url": "https://api.signatureapi.com/v1/uploads/upl_42NTdNnkg6dGLx8jR1X1wm",
  "sha_256": "17b2e9d40c8a5f631e7d9b2a4c06f8e35d1a7b9c2e4f60813a5d7c9e1b3f4a26",
  "size": 51200,
  "format": "png",
  "created_at": "2026-11-02T14:00:00.000Z",
  "expires_at": "2026-11-03T14:00:00.000Z"
}
```

Errors that any request can return (authentication, rate limits, server errors) are on the [Errors](https://signatureapi.com/docs/api/errors) and [Authentication](https://signatureapi.com/docs/api/authentication) pages.
