> ## Documentation Index
> Fetch the complete documentation index at: https://signatureapi-daf4ee54.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an upload

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

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](/docs/api/resources/documents/object) when creating an envelope:

```json theme={null}
// POST https://api.signatureapi.com/v1/envelopes
// X-API-Key: key_test_...
// Content-Type: application/json

{
  "documents": [
    {
      "url": "https://api.signatureapi.com/v1/uploads/upl_1sAAaVfabdt0esVjmSTmLA",
      //...
    }
  ],
  //...
}
```

<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](/docs/api/resources/uploads/store) endpoint or upload it to your [Library](https://dashboard.signatureapi.com/library) in the dashboard.
</Note>

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

## 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`  |

Maximum file size: 5 MB (5,242,880 bytes).

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.signatureapi.com/v1/uploads \
    --data-binary "@/path/to/file.pdf" \
    -H "Content-Type: application/pdf" \
    -H "X-API-Key: key_test_..."
  ```

  ```typescript TypeScript theme={null}
  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": "key_test_..."
        },
      }
    );

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

  uploadPdf();
  ```

  ```python Python theme={null}
  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": "key_test_..."
          },
          data=f
      )

  print(response.json())
  ```

  ```ruby Ruby theme={null}
  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"] = "key_test_..."
    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
  ```

  ```csharp C# theme={null}
  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", "key_test_...");

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

  ```java Java theme={null}
  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", "key_test_...")
      .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 theme={null}
  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", "key_test_...")

    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))
  }
  ```
</CodeGroup>

<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.
</Warning>

## Returns

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

<RequestExample>
  ```bash Request theme={null}
  // POST https://api.signatureapi.com/v1/uploads
  // X-API-Key: key_test_...
  // Content-Type: application/pdf
  // <raw binary file content>
  ```
</RequestExample>

<ResponseExample>
  ```json PDF upload theme={null}
  // HTTP Status 201

  {
    "id": "upl_1sAAaVfabdt0esVjmSTmLA",
    "retention": "temporary",
    "url": "https://api.signatureapi.com/v1/uploads/upl_1sAAaVfabdt0esVjmSTmLA",
    "format": "pdf",
    "sha_256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "size": 102400,
    "created_at": "2025-12-30T12:00:00.000Z",
    "expires_at": "2025-12-31T12:00:00.000Z"
  }
  ```

  ```json DOCX upload theme={null}
  // HTTP Status 201

  {
    "id": "upl_3joO7lxE8HVhOZmkCHFCxK",
    "retention": "temporary",
    "url": "https://api.signatureapi.com/v1/uploads/upl_3joO7lxE8HVhOZmkCHFCxK",
    "format": "docx",
    "sha_256": "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789",
    "size": 234567,
    "created_at": "2025-12-30T12:00:00.000Z",
    "expires_at": "2025-12-31T12:00:00.000Z"
  }
  ```

  ```json PNG upload theme={null}
  // HTTP Status 201

  {
    "id": "upl_7kBBcD2eF3gHiJkLmNoPqR",
    "retention": "temporary",
    "url": "https://api.signatureapi.com/v1/uploads/upl_7kBBcD2eF3gHiJkLmNoPqR",
    "format": "png",
    "sha_256": "fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210",
    "size": 51200,
    "created_at": "2025-12-30T12:00:00.000Z",
    "expires_at": "2025-12-31T12:00:00.000Z"
  }
  ```
</ResponseExample>