Create an upload

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

POST /v1/uploads

Request

// POST https://api.signatureapi.com/v1/uploads
// X-API-Key: key_test_...
// Content-Type: application/pdf
// <raw binary file content>

PDF upload

// 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"
}

// 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"
}

// 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"
}

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 when creating an envelope:

// 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",
      //...
    }
  ],
  //...
}

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 endpoint or upload it to your Library in the dashboard.

The Create Upload endpoint replaces the Create File endpoint. 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

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

cURL

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_..."

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();

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())

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

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());

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());

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))
}

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 on success, or an error otherwise.

Request

// POST https://api.signatureapi.com/v1/uploads
// X-API-Key: key_test_...
// Content-Type: application/pdf
// <raw binary file content>

PDF upload

// 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"
}

// 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"
}

// 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"
}