> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.hellosign.com/llms.txt.
> For full documentation content, see https://developers.hellosign.com/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.hellosign.com/_mcp/server.

# Update Template Files

POST https://api.hellosign.com/v3/template/update_files/{template_id}
Content-Type: application/json

Overlays a new file with the overlay of an existing template. The new file(s) must:

1. have the same or higher page count
2. the same orientation as the file(s) being replaced.

This will not overwrite or in any way affect the existing template. Both the existing template and new template will be available for use after executing this endpoint. Also note that this will decrement your template quota.

Overlaying new files is asynchronous and a successful call to this endpoint will return 200 OK response if the request passes initial validation checks.

It is recommended that a callback be implemented to listen for the callback event. A `template_created` event will be sent when the files are updated or a `template_error` event will be sent if there was a problem while updating the files. If a callback handler has been configured and the event has not been received within 60 minutes of making the call, check the status of the request in the API dashboard and retry the request if necessary.

If the page orientation or page count is different from the original template document, we will notify you with a `template_error` [callback event](https://app.hellosign.com/api/eventsAndCallbacksWalkthrough).

Reference: https://developers.hellosign.com/api/template/update-files

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: Dropbox Sign API
  version: 1.0.0
paths:
  /template/update_files/{template_id}:
    post:
      operationId: update-files
      summary: Update Template Files
      description: >-
        Overlays a new file with the overlay of an existing template. The new
        file(s) must:


        1. have the same or higher page count

        2. the same orientation as the file(s) being replaced.


        This will not overwrite or in any way affect the existing template. Both
        the existing template and new template will be available for use after
        executing this endpoint. Also note that this will decrement your
        template quota.


        Overlaying new files is asynchronous and a successful call to this
        endpoint will return 200 OK response if the request passes initial
        validation checks.


        It is recommended that a callback be implemented to listen for the
        callback event. A `template_created` event will be sent when the files
        are updated or a `template_error` event will be sent if there was a
        problem while updating the files. If a callback handler has been
        configured and the event has not been received within 60 minutes of
        making the call, check the status of the request in the API dashboard
        and retry the request if necessary.


        If the page orientation or page count is different from the original
        template document, we will notify you with a `template_error` [callback
        event](https://app.hellosign.com/api/eventsAndCallbacksWalkthrough).
      tags:
        - subpackage_template
      parameters:
        - name: template_id
          in: path
          description: The ID of the template whose files to update.
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Basic authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateUpdateFilesResponse'
        '400':
          description: failed_operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TemplateUpdateFilesRequest'
servers:
  - url: https://api.hellosign.com/v3
components:
  schemas:
    TemplateUpdateFilesRequest:
      type: object
      properties:
        client_id:
          type: string
          description: Client id of the app you're using to update this template.
        files:
          type: array
          items:
            type: string
            format: binary
          description: >-
            Use `files[]` to indicate the uploaded file(s) to use for the
            template.


            This endpoint requires either **files** or **file_urls[]**, but not
            both.
        file_urls:
          type: array
          items:
            type: string
          description: >-
            Use `file_urls[]` to have Dropbox Sign download the file(s) to use
            for the template.


            This endpoint requires either **files** or **file_urls[]**, but not
            both.
        message:
          type: string
          description: The new default template email message.
        subject:
          type: string
          description: The new default template email subject.
        test_mode:
          type: boolean
          default: false
          description: >-
            Whether this is a test, the signature request created from this
            draft will not be legally binding if set to `true`. Defaults to
            `false`.
      title: TemplateUpdateFilesRequest
    WarningResponse:
      type: object
      properties:
        warning_msg:
          type: string
          description: Warning message
        warning_name:
          type: string
          description: Warning name
      required:
        - warning_msg
        - warning_name
      description: A list of warnings.
      title: WarningResponse
    TemplateUpdateFilesResponseTemplate:
      type: object
      properties:
        template_id:
          type: string
          description: The id of the Template.
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/WarningResponse'
          description: A list of warnings.
      description: Contains template id
      title: TemplateUpdateFilesResponseTemplate
    TemplateUpdateFilesResponse:
      type: object
      properties:
        template:
          $ref: '#/components/schemas/TemplateUpdateFilesResponseTemplate'
      required:
        - template
      title: TemplateUpdateFilesResponse
    ErrorResponseError:
      type: object
      properties:
        error_msg:
          type: string
          description: Message describing an error.
        error_path:
          type: string
          description: Path at which an error occurred.
        error_name:
          type: string
          description: Name of the error.
      required:
        - error_msg
        - error_name
      description: Contains information about an error that occurred.
      title: ErrorResponseError
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorResponseError'
      required:
        - error
      title: ErrorResponse
  securitySchemes:
    Basic:
      type: http
      scheme: basic
    Bearer:
      type: http
      scheme: bearer

```

## SDK Code Examples

```php PHP
<?php

namespace Dropbox\SignSandbox;

require_once __DIR__ . '/../vendor/autoload.php';

use SplFileObject;
use Dropbox;

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();
$config->setUsername("YOUR_API_KEY");
// $config->setAccessToken("YOUR_ACCESS_TOKEN");

$template_update_files_request = (new Dropbox\Sign\Model\TemplateUpdateFilesRequest())
    ->setFiles([
    ]);

try {
    $response = (new Dropbox\Sign\Api\TemplateApi(config: $config))->templateUpdateFiles(
        template_id: "f57db65d3f933b5316d398057a36176831451a35",
        template_update_files_request: $template_update_files_request,
    );

    print_r($response);
} catch (Dropbox\Sign\ApiException $e) {
    echo "Exception when calling TemplateApi#templateUpdateFiles: {$e->getMessage()}";
}

```

```csharp C#
using System;
using System.Collections.Generic;
using System.IO;
using System.Text.Json;

using Dropbox.Sign.Api;
using Dropbox.Sign.Client;
using Dropbox.Sign.Model;

namespace Dropbox.SignSandbox;

public class TemplateUpdateFilesExample
{
    public static void Run()
    {
        var config = new Configuration();
        config.Username = "YOUR_API_KEY";
        // config.AccessToken = "YOUR_ACCESS_TOKEN";

        var templateUpdateFilesRequest = new TemplateUpdateFilesRequest(
            files: new List<Stream>
            {
                new FileStream(
                    path: "./example_signature_request.pdf",
                    mode: FileMode.Open
                ),
            }
        );

        try
        {
            var response = new TemplateApi(config).TemplateUpdateFiles(
                templateId: "f57db65d3f933b5316d398057a36176831451a35",
                templateUpdateFilesRequest: templateUpdateFilesRequest
            );

            Console.WriteLine(response);
        }
        catch (ApiException e)
        {
            Console.WriteLine("Exception when calling TemplateApi#TemplateUpdateFiles: " + e.Message);
            Console.WriteLine("Status Code: " + e.ErrorCode);
            Console.WriteLine(e.StackTrace);
        }
    }
}

```

```typescript TypeScript
import * as fs from 'fs';
import api from "@dropbox/sign"
import models from "@dropbox/sign"

const apiCaller = new api.TemplateApi();
apiCaller.username = "YOUR_API_KEY";
// apiCaller.accessToken = "YOUR_ACCESS_TOKEN";

const templateUpdateFilesRequest: models.TemplateUpdateFilesRequest = {
  files: [
    fs.createReadStream("./example_signature_request.pdf"),
  ],
};

apiCaller.templateUpdateFiles(
  "f57db65d3f933b5316d398057a36176831451a35", // templateId
  templateUpdateFilesRequest,
).then(response => {
  console.log(response.body);
}).catch(error => {
  console.log("Exception when calling TemplateApi#templateUpdateFiles:");
  console.log(error.body);
});

```

```java Java
package com.dropbox.sign_sandbox;

import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.JSON;
import com.dropbox.sign.model.*;

import java.io.File;
import java.math.BigDecimal;
import java.time.LocalDate;
import java.time.OffsetDateTime;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;

public class TemplateUpdateFilesExample
{
    public static void main(String[] args)
    {
        var config = Configuration.getDefaultApiClient();
        ((HttpBasicAuth) config.getAuthentication("api_key")).setUsername("YOUR_API_KEY");
        // ((HttpBearerAuth) config.getAuthentication("oauth2")).setBearerToken("YOUR_ACCESS_TOKEN");

        var templateUpdateFilesRequest = new TemplateUpdateFilesRequest();
        templateUpdateFilesRequest.files(List.of (
            new File("./example_signature_request.pdf")
        ));

        try
        {
            var response = new TemplateApi(config).templateUpdateFiles(
                "f57db65d3f933b5316d398057a36176831451a35", // templateId
                templateUpdateFilesRequest
            );

            System.out.println(response);
        } catch (ApiException e) {
            System.err.println("Exception when calling TemplateApi#templateUpdateFiles");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

```

```ruby Ruby
require "json"
require "dropbox-sign"

Dropbox::Sign.configure do |config|
    config.username = "YOUR_API_KEY"
    # config.access_token = "YOUR_ACCESS_TOKEN"
end

template_update_files_request = Dropbox::Sign::TemplateUpdateFilesRequest.new
template_update_files_request.files = [
    File.new("./example_signature_request.pdf", "r"),
]

begin
    response = Dropbox::Sign::TemplateApi.new.template_update_files(
        "f57db65d3f933b5316d398057a36176831451a35", # template_id
        template_update_files_request,
    )

    p response
rescue Dropbox::Sign::ApiError => e
    puts "Exception when calling TemplateApi#template_update_files: #{e}"
end

```

```python Python
import json
from datetime import date, datetime
from pprint import pprint

from dropbox_sign import ApiClient, ApiException, Configuration, api, models

configuration = Configuration(
    username="YOUR_API_KEY",
    # access_token="YOUR_ACCESS_TOKEN",
)

with ApiClient(configuration) as api_client:
    template_update_files_request = models.TemplateUpdateFilesRequest(
        files=[
            open("./example_signature_request.pdf", "rb").read(),
        ],
    )

    try:
        response = api.TemplateApi(api_client).template_update_files(
            template_id="f57db65d3f933b5316d398057a36176831451a35",
            template_update_files_request=template_update_files_request,
        )

        pprint(response)
    except ApiException as e:
        print("Exception when calling TemplateApi#template_update_files: %s\n" % e)

```

```go Update Template Files
package main

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

func main() {

	url := "https://api.hellosign.com/v3/template/update_files/f57db65d3f933b5316d398057a36176831451a35"

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

	req.SetBasicAuth("<apiKey>", "")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```swift Update Template Files
import Foundation

let credentials = Data("<apiKey>:".utf8).base64EncodedString()

let headers = [
  "Authorization": "Basic \(credentials)",
  "Content-Type": "application/json"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.hellosign.com/v3/template/update_files/f57db65d3f933b5316d398057a36176831451a35")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```php PHP
<?php

namespace Dropbox\SignSandbox;

require_once __DIR__ . '/../vendor/autoload.php';

use SplFileObject;
use Dropbox;

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();
$config->setUsername("YOUR_API_KEY");
// $config->setAccessToken("YOUR_ACCESS_TOKEN");

$template_update_files_request = (new Dropbox\Sign\Model\TemplateUpdateFilesRequest())
    ->setFiles([
    ]);

try {
    $response = (new Dropbox\Sign\Api\TemplateApi(config: $config))->templateUpdateFiles(
        template_id: "f57db65d3f933b5316d398057a36176831451a35",
        template_update_files_request: $template_update_files_request,
    );

    print_r($response);
} catch (Dropbox\Sign\ApiException $e) {
    echo "Exception when calling TemplateApi#templateUpdateFiles: {$e->getMessage()}";
}

```

```csharp C#
using System;
using System.Collections.Generic;
using System.IO;
using System.Text.Json;

using Dropbox.Sign.Api;
using Dropbox.Sign.Client;
using Dropbox.Sign.Model;

namespace Dropbox.SignSandbox;

public class TemplateUpdateFilesExample
{
    public static void Run()
    {
        var config = new Configuration();
        config.Username = "YOUR_API_KEY";
        // config.AccessToken = "YOUR_ACCESS_TOKEN";

        var templateUpdateFilesRequest = new TemplateUpdateFilesRequest(
            files: new List<Stream>
            {
                new FileStream(
                    path: "./example_signature_request.pdf",
                    mode: FileMode.Open
                ),
            }
        );

        try
        {
            var response = new TemplateApi(config).TemplateUpdateFiles(
                templateId: "f57db65d3f933b5316d398057a36176831451a35",
                templateUpdateFilesRequest: templateUpdateFilesRequest
            );

            Console.WriteLine(response);
        }
        catch (ApiException e)
        {
            Console.WriteLine("Exception when calling TemplateApi#TemplateUpdateFiles: " + e.Message);
            Console.WriteLine("Status Code: " + e.ErrorCode);
            Console.WriteLine(e.StackTrace);
        }
    }
}

```

```typescript TypeScript
import * as fs from 'fs';
import api from "@dropbox/sign"
import models from "@dropbox/sign"

const apiCaller = new api.TemplateApi();
apiCaller.username = "YOUR_API_KEY";
// apiCaller.accessToken = "YOUR_ACCESS_TOKEN";

const templateUpdateFilesRequest: models.TemplateUpdateFilesRequest = {
  files: [
    fs.createReadStream("./example_signature_request.pdf"),
  ],
};

apiCaller.templateUpdateFiles(
  "f57db65d3f933b5316d398057a36176831451a35", // templateId
  templateUpdateFilesRequest,
).then(response => {
  console.log(response.body);
}).catch(error => {
  console.log("Exception when calling TemplateApi#templateUpdateFiles:");
  console.log(error.body);
});

```

```java Java
package com.dropbox.sign_sandbox;

import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.JSON;
import com.dropbox.sign.model.*;

import java.io.File;
import java.math.BigDecimal;
import java.time.LocalDate;
import java.time.OffsetDateTime;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;

public class TemplateUpdateFilesExample
{
    public static void main(String[] args)
    {
        var config = Configuration.getDefaultApiClient();
        ((HttpBasicAuth) config.getAuthentication("api_key")).setUsername("YOUR_API_KEY");
        // ((HttpBearerAuth) config.getAuthentication("oauth2")).setBearerToken("YOUR_ACCESS_TOKEN");

        var templateUpdateFilesRequest = new TemplateUpdateFilesRequest();
        templateUpdateFilesRequest.files(List.of (
            new File("./example_signature_request.pdf")
        ));

        try
        {
            var response = new TemplateApi(config).templateUpdateFiles(
                "f57db65d3f933b5316d398057a36176831451a35", // templateId
                templateUpdateFilesRequest
            );

            System.out.println(response);
        } catch (ApiException e) {
            System.err.println("Exception when calling TemplateApi#templateUpdateFiles");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

```

```ruby Ruby
require "json"
require "dropbox-sign"

Dropbox::Sign.configure do |config|
    config.username = "YOUR_API_KEY"
    # config.access_token = "YOUR_ACCESS_TOKEN"
end

template_update_files_request = Dropbox::Sign::TemplateUpdateFilesRequest.new
template_update_files_request.files = [
    File.new("./example_signature_request.pdf", "r"),
]

begin
    response = Dropbox::Sign::TemplateApi.new.template_update_files(
        "f57db65d3f933b5316d398057a36176831451a35", # template_id
        template_update_files_request,
    )

    p response
rescue Dropbox::Sign::ApiError => e
    puts "Exception when calling TemplateApi#template_update_files: #{e}"
end

```

```python Python
import json
from datetime import date, datetime
from pprint import pprint

from dropbox_sign import ApiClient, ApiException, Configuration, api, models

configuration = Configuration(
    username="YOUR_API_KEY",
    # access_token="YOUR_ACCESS_TOKEN",
)

with ApiClient(configuration) as api_client:
    template_update_files_request = models.TemplateUpdateFilesRequest(
        files=[
            open("./example_signature_request.pdf", "rb").read(),
        ],
    )

    try:
        response = api.TemplateApi(api_client).template_update_files(
            template_id="f57db65d3f933b5316d398057a36176831451a35",
            template_update_files_request=template_update_files_request,
        )

        pprint(response)
    except ApiException as e:
        print("Exception when calling TemplateApi#template_update_files: %s\n" % e)

```

```go Default Example
package main

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

func main() {

	url := "https://api.hellosign.com/v3/template/update_files/f57db65d3f933b5316d398057a36176831451a35"

	payload := strings.NewReader("{\n  \"file_urls\": [\n    \"https://www.dropbox.com/s/ad9qnhbrjjn64tu/mutual-NDA-example.pdf?dl=1\"\n  ]\n}")

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

	req.SetBasicAuth("<apiKey>", "")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```swift Default Example
import Foundation

let credentials = Data("<apiKey>:".utf8).base64EncodedString()

let headers = [
  "Authorization": "Basic \(credentials)",
  "Content-Type": "application/json"
]
let parameters = ["file_urls": ["https://www.dropbox.com/s/ad9qnhbrjjn64tu/mutual-NDA-example.pdf?dl=1"]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.hellosign.com/v3/template/update_files/f57db65d3f933b5316d398057a36176831451a35")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```