---
title: "SignatureAPI for n8n"
description: "Send documents for signature from n8n with the HTTP Request node and one Header Auth credential, store templates, and receive signed PDFs by webhook."
canonical: "https://signatureapi.com/docs/integrations/n8n"
source: "https://signatureapi.com/docs/integrations/n8n.md"
last_verified_api_version: "1.18.0"
---

# SignatureAPI for n8n

Send documents for signature from n8n with the HTTP Request node and one Header Auth credential, store templates, and receive signed PDFs by webhook.

_Last verified against API version 1.18.0._

n8n calls the SignatureAPI REST API through its built-in **HTTP Request** node. You need one credential and no community node. Every workflow on these pages ran end to end on n8n 2.43.4 in test mode.

## What you can build

- [Employment contract](https://signatureapi.com/docs/integrations/n8n/employment-contract): your HR system posts a new hire, HR approves, then the employer and the employee sign.
- [Signed PDF on completion](https://signatureapi.com/docs/integrations/n8n/deliverable-on-completion): receive `deliverable.generated`, verify the signature, download the signed PDF.
- [NDA batch](https://signatureapi.com/docs/integrations/n8n/nda-batch): one mutual NDA per row, paced to stay inside the rate limit.
- [Lease renewal](https://signatureapi.com/docs/integrations/n8n/lease-renewal): every morning, send a renewal for each lease that ends in the next 60 days.
- [Invoice approval](https://signatureapi.com/docs/integrations/n8n/invoice-approval): a manager approves an invoice PDF, then finance signs it off.
- [Form to envelope](https://signatureapi.com/docs/integrations/n8n/form-to-envelope): an n8n form that sends an offer letter to sign.

Import the finished workflows from GitHub: [`no-code/n8n`](https://github.com/signatureapi/examples/tree/main/no-code/n8n).

**Video: Running the NDA batch workflow**

Selecting Execute in the n8n editor runs the NDA batch workflow, and Create envelope sends three test envelopes.

[Watch the video](https://signatureapi.com/videos/n8n-nda-batch.mp4)
[Captions (WebVTT)](https://signatureapi.com/videos/n8n-nda-batch.vtt)

## Create the credential

Every request to SignatureAPI carries your API key in the `X-API-Key` header. In n8n, keep the key in a Header Auth credential, not in the node.

1. **Add a Header Auth credential**

   In n8n, create a credential of type **Header Auth**. Name it `SignatureAPI test key`.

2. **Fill in the header**

   Set **Name** to `X-API-Key` and **Value** to your test API key from the [Dashboard](https://dashboard.signatureapi.com). Save.

![The n8n Header Auth credential named SignatureAPI test key, with Name set to X-API-Key and the Value masked](https://signatureapi.com/docs/images/captured/n8n/credential-header-auth.webp)

*The Header Auth credential*

The key decides the mode. A test key creates [test envelopes](https://signatureapi.com/docs/api/test-mode): free, not legally binding, and no email reaches your recipients. Change the credential's value to a live key when you are ready to send real documents. The workflows stay the same.

## Call the API from an HTTP Request node

Point an HTTP Request node at the endpoint, select the credential, and send the request body as JSON. These settings create an envelope:

HTTP Request node settings for the "Minimal" request:

1. **Method**: POST
2. **URL**: `https://api.signatureapi.com/v1/envelopes`
3. **Authentication**: Generic Credential Type, Generic Auth Type: Header Auth

   Create a Header Auth credential with Name `X-API-Key` and your API key as the Value. Keep the key in the credential, not in the node.
4. **Send Body**: On
5. **Body Content Type**: JSON
6. **Specify Body**: Using JSON
7. **JSON**:

   ```json
   {
     "title": "Service Agreement",
     "message": "Please review the agreement and provide your signature.",
     "routing": "parallel",
     "documents": [
       {
         "key": "service_agreement",
         "title": "Service Agreement",
         "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/acme-service-agreement.pdf",
         "format": "pdf",
         "places": [
           {
             "key": "client_signs_here",
             "type": "signature",
             "recipient_key": "client"
           },
           {
             "key": "provider_signs_here",
             "type": "signature",
             "recipient_key": "provider"
           }
         ]
       }
     ],
     "recipients": [
       {
         "type": "signer",
         "key": "client",
         "name": "Jane Doe",
         "email": "jane.doe@example.com"
       },
       {
         "type": "signer",
         "key": "provider",
         "name": "John Smith",
         "email": "john.smith@example.com"
       }
     ]
   }
   ```

Setting names as in the [n8n documentation](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.httprequest/).

![The Create envelope HTTP Request node parameters: method POST, the envelopes URL, Header Auth with the SignatureAPI test key credential, and a JSON body](https://signatureapi.com/docs/images/captured/n8n/http-request-node.webp)

*The Create envelope node*

The workflows on these pages build the body in a Code node first and send it with **JSON** set to `{{ JSON.stringify($json.envelope) }}`. A Code node handles nested objects and arrays more clearly than an expression in the JSON field.

To pass the API's error back to the caller instead of stopping the workflow, change the node's response options. In **Options** > **Response**, turn on **Include Response Headers and Status** and **Never Error**, and set **Response Format** to **JSON**. API errors use the `application/problem+json` content type, which n8n otherwise returns as plain text. The [employment contract](https://signatureapi.com/docs/integrations/n8n/employment-contract) workflow uses these options.

## Store your templates once

The template workflows merge data into a DOCX file that SignatureAPI already stores. An [upload](https://signatureapi.com/docs/api/resources/uploads/create) expires after 24 hours unless you [store it](https://signatureapi.com/docs/api/resources/uploads/store). Upload each template once and keep its URL.

You can upload a file in the Dashboard [Library](https://signatureapi.com/docs/dashboard/library), or let n8n do it with one manual workflow:

1. **Manual Trigger**.
2. **Code** node that returns one item per template, each with a `key` (a unique name, such as `employment-contract`) and a `source_url` to download the file from.
3. **HTTP Request** node, `GET` `{{ $json.source_url }}`, with **Options** > **Response** > **Response Format** set to **File**.
4. **HTTP Request** node, `POST` `https://api.signatureapi.com/v1/uploads` with the credential. Turn on **Send Headers** with `Content-Type` set to `application/vnd.openxmlformats-officedocument.wordprocessingml.document`. Turn on **Send Body**, set **Body Content Type** to **n8n Binary File** and **Input Data Field Name** to `data`.
5. **HTTP Request** node, `POST` `https://api.signatureapi.com/v1/uploads/{{ $json.id }}/store` with the credential and the JSON body `{{ JSON.stringify({ key: $('Templates').item.json.key }) }}`. Here `Templates` is the name of the Code node in step 2.

The last node returns each stored upload with `retention: "permanent"` and its `url`, such as `https://api.signatureapi.com/v1/uploads/upl_3JJz6t1o8A5YjX5VpnX27Z`. Use that URL as the document `url` in your envelopes.

![The Store templates workflow in n8n: Run once, Templates, Download template, Create upload and Store upload nodes, with a note explaining the workflow](https://signatureapi.com/docs/images/captured/n8n/canvas-store-templates.webp)

*The Store templates workflow*

## Receive events

Add a **Webhook** node to react when an envelope changes. Register its production URL as a webhook endpoint in the [Dashboard](https://signatureapi.com/docs/dashboard/webhooks). Verify every delivery's signature before you act on it. The [signed PDF workflow](https://signatureapi.com/docs/integrations/n8n/deliverable-on-completion) shows a Code node that checks the signature and the n8n settings it needs.

## Troubleshooting

- **The webhook answers `502` with a `422` body.** The API refused the envelope. The body's `errors` or `detail` says which field. A document `url` that SignatureAPI cannot fetch returns an error that links to the [supported hosts](https://signatureapi.com/docs/api/resources/documents/url#external-store); use an upload URL instead.
- **`access to env vars denied` in a Code node.** The instance blocks `$env`. See [Signed PDF on completion](https://signatureapi.com/docs/integrations/n8n/deliverable-on-completion#configure-n8n).
- **A production webhook URL answers `404`.** The workflow is not active. Activate (publish) it, then call the production URL again.
