Add a document to a template

curl --request POST \
  --url https://api.firma.dev/functions/v1/signing-request-api/templates/{id}/documents \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "document_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "position": 2,
  "label": "<string>",
  "original_filename": "<string>"
}
'

import requests

url = "https://api.firma.dev/functions/v1/signing-request-api/templates/{id}/documents"

payload = {
    "document_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "position": 2,
    "label": "<string>",
    "original_filename": "<string>"
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    document_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    position: 2,
    label: '<string>',
    original_filename: '<string>'
  })
};

fetch('https://api.firma.dev/functions/v1/signing-request-api/templates/{id}/documents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.firma.dev/functions/v1/signing-request-api/templates/{id}/documents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'document_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'position' => 2,
    'label' => '<string>',
    'original_filename' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.firma.dev/functions/v1/signing-request-api/templates/{id}/documents"

	payload := strings.NewReader("{\n  \"document_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"position\": 2,\n  \"label\": \"<string>\",\n  \"original_filename\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.firma.dev/functions/v1/signing-request-api/templates/{id}/documents")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"document_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"position\": 2,\n  \"label\": \"<string>\",\n  \"original_filename\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.firma.dev/functions/v1/signing-request-api/templates/{id}/documents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"document_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"position\": 2,\n  \"label\": \"<string>\",\n  \"original_filename\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "documents": [
    {
      "document_id": null,
      "position": 1,
      "label": null,
      "original_filename": null,
      "page_count": 3,
      "document_url": "https://api.firma.dev/storage/v1/object/sign/signing-request-documents/example.pdf?token=example",
      "document_url_kind": "stored",
      "document_only_hash": null
    }
  ],
  "documents_version": 123,
  "documents_layout_version": 123
}

{
  "error": "<string>",
  "code": "ALREADY_CANCELLED",
  "errors": [
    {
      "message": "<string>"
    }
  ],
  "message": "<string>",
  "details": {}
}

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

{
  "error": "<string>",
  "code": "ALREADY_CANCELLED",
  "errors": [
    {
      "message": "<string>"
    }
  ],
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "code": "ALREADY_CANCELLED",
  "errors": [
    {
      "message": "<string>"
    }
  ],
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "code": "ALREADY_CANCELLED",
  "errors": [
    {
      "message": "<string>"
    }
  ],
  "message": "<string>",
  "details": {}
}

{
  "error": "Rate Limit Exceeded",
  "message": "Too many requests. Please wait before retrying.",
  "details": {
    "retry_after": 45
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "errors": [
    {
      "message": "<string>"
    }
  ],
  "message": "<string>",
  "details": {}
}

Templates

Add a document to a template

Adds a document (a temporary upload from POST /documents) to the template’s document set, at position or last. Documents at that position and after it move up by one. At most 20 documents and 100 MB per template.

Available to every company. This operation is part of the multi-document contract (API 01.39.00). For a signing request or template the API key cannot see, it answers 404 with code NOT_FOUND (“Endpoint not found”), exactly as an unknown endpoint does. While multi-document editing is suspended, this operation returns 409 MULTI_DOCUMENT_READ_ONLY for parents on the multi-document read-only path and 404 NOT_FOUND for parents on the single-document path.

POST

templates

{id}

documents

Add a document to a template

curl --request POST \
  --url https://api.firma.dev/functions/v1/signing-request-api/templates/{id}/documents \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "document_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "position": 2,
  "label": "<string>",
  "original_filename": "<string>"
}
'

import requests

url = "https://api.firma.dev/functions/v1/signing-request-api/templates/{id}/documents"

payload = {
    "document_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "position": 2,
    "label": "<string>",
    "original_filename": "<string>"
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    document_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    position: 2,
    label: '<string>',
    original_filename: '<string>'
  })
};

fetch('https://api.firma.dev/functions/v1/signing-request-api/templates/{id}/documents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.firma.dev/functions/v1/signing-request-api/templates/{id}/documents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'document_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'position' => 2,
    'label' => '<string>',
    'original_filename' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.firma.dev/functions/v1/signing-request-api/templates/{id}/documents"

	payload := strings.NewReader("{\n  \"document_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"position\": 2,\n  \"label\": \"<string>\",\n  \"original_filename\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.firma.dev/functions/v1/signing-request-api/templates/{id}/documents")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"document_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"position\": 2,\n  \"label\": \"<string>\",\n  \"original_filename\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.firma.dev/functions/v1/signing-request-api/templates/{id}/documents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"document_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"position\": 2,\n  \"label\": \"<string>\",\n  \"original_filename\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "documents": [
    {
      "document_id": null,
      "position": 1,
      "label": null,
      "original_filename": null,
      "page_count": 3,
      "document_url": "https://api.firma.dev/storage/v1/object/sign/signing-request-documents/example.pdf?token=example",
      "document_url_kind": "stored",
      "document_only_hash": null
    }
  ],
  "documents_version": 123,
  "documents_layout_version": 123
}

{
  "error": "<string>",
  "code": "ALREADY_CANCELLED",
  "errors": [
    {
      "message": "<string>"
    }
  ],
  "message": "<string>",
  "details": {}
}

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

{
  "error": "<string>",
  "code": "ALREADY_CANCELLED",
  "errors": [
    {
      "message": "<string>"
    }
  ],
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "code": "ALREADY_CANCELLED",
  "errors": [
    {
      "message": "<string>"
    }
  ],
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "code": "ALREADY_CANCELLED",
  "errors": [
    {
      "message": "<string>"
    }
  ],
  "message": "<string>",
  "details": {}
}

{
  "error": "Rate Limit Exceeded",
  "message": "Too many requests. Please wait before retrying.",
  "details": {
    "retry_after": 45
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "errors": [
    {
      "message": "<string>"
    }
  ],
  "message": "<string>",
  "details": {}
}

Authorizations

Authorization

string

header

required

API key for authentication. Use your API key directly without any prefix (e.g., 'your-api-key'). Bearer prefix is optional but not required.

Path Parameters

string<uuid>

required

Template ID

Body

application/json

document_id

string<uuid>

required

Temporary upload id from POST /documents (a PDF). Consumed once the document is added.

position

integer

1-based position of the new document; at most the current count + 1. Defaults to last.

Required range: x >= 1

label

string | null

Display name of the document (no control characters).

Maximum string length: 200

original_filename

string | null

File name to record for the document (no control characters).

Maximum string length: 255

Response

Document added; the full document set after the change

Answer of every /documents mutation: the full document set after the change and its two versions.

documents

object[]

required

Show child attributes

documents_version

integer

required

documents_layout_version

integer

required