n8n Integration Guide

Official Node Available

Automate text cleaning
inside your n8n workflows

Clean, format, and transform your data at scale. Connect CleanTextLab to your n8n workflows using our native community node or the HTTP Request node.

Browse n8n Templates API Reference

Data Source

Step 1

CleanTextLab

Step 2

Destination

Step 3

The standard pattern for automated text processing in n8n.

HTTP Request Node

Use the built-in HTTP Request node for zero-dependency integration.

Secure Auth

Store your API key in n8n Credentials or Env vars for enterprise security.

Smart Retries

Enable exponential backoff in n8n to handle rate limits gracefully.

Visualizing the flow

n8n treats CleanTextLab as a powerful transformation engine. Simply map your incoming data fields to our API and get sanitized output in milliseconds.

Native JSON support for all nodes
Zero server-side configuration
Works with self-hosted & Cloud n8n

CleanTextLab

COMMUNITY NODE

ActionProcess Text

ToolCSV to JSON

DelimiterSemicolon (;)

Input TextExpression

data:{{ $json.text }}

Success

8msOUTPUT

Integration Methods

Choose the method that best fits your n8n environment.

Recommended

Method 1: Community Node (Best Experience)

Our dedicated n8n node provides a visual UI for all 35+ tools, including dropdowns for algorithms, delimiters, and configurations.

Install via npm

Run this command in your n8n root directory:

npm install n8n-nodes-cleantextlab

Restart n8n

Restart your n8n instance to load the new node.

Add Node

Search for CleanTextLab in the node list.

View Repository on GitHub

CleanTextLab

COMMUNITY NODE

ActionProcess Text

ToolCSV to JSON

DelimiterSemicolon (;)

Input TextExpression

data:{{ $json.text }}

Success

8msOUTPUT

Alternative Method

Method 2: Manual HTTP Request (Fallback)

Get your API key

Go to Settings → API Keys and generate a new Pro API key. Copy it to your clipboard.

Open n8n Credentials panel

In n8n, click Credentials in the left sidebar, then click + Add Credential

Search for "Header Auth"

Type "header" in the search box and select Header Auth from the list

Configure the credential

Credential Settings

Credential Name: CleanTextLab API Key
Header Name: x-api-key
Header Value: ctl_live_YOUR_API_KEY_HERE

Save the credential

Click Save. You can now use this credential in any workflow.

Pro Tip: This credential is reusable across all your n8n workflows. You only need to set it up once!

Configure HTTP Request Node

Add an HTTP Request node to your workflow and configure it with these exact settings:

Basic Settings

Method: POST
URL: https://cleantextlab.com/api/v1/run
Response Format: JSON

Authentication

Authentication: Predefined Credential Type
Credential Type: Header Auth
Credential: [Select "CleanTextLab API Key"]

Headers

Send Headers: ON

Add Header:
  Name: Content-Type
  Value: application/json

Body

Send Body: ON
Specify Body: JSON
JSON/RAW Parameters: [See Step 3]

Build Your Request Body

The request body uses n8n's expression syntax to dynamically map your data. Here's the pattern:

Basic Example

Static text processing

={{ {
  "input": "Hello World",
  "steps": ["upper-case"]
} }}

↳ Output: {"result": "HELLO WORLD"}

Dynamic Example (Using Previous Node Data)

Reference data from previous nodes

={{ {
  "input": $json.emailBody,
  "steps": [
    "trim-lines",
    "collapse-spaces",
    "remove-accents",
    "title-case-converter"
  ]
} }}

↳ $json.emailBody references the emailBody field from the previous node's output

Multi-Step Pipeline Example

Chain multiple transformations

={{ {
  "input": $json.rawText,
  "steps": [
    "trim-lines",
    "remove-line-breaks",
    "collapse-spaces",
    "lower-case",
    "dedupe-sort"
  ]
} }}

↳ Each step processes the output of the previous step sequentially

Important: The entire body must be wrapped in ={{ ... }} expression syntax. Inside, you can reference variables without quotes: $json.fieldName

Understanding the Response

The API returns a JSON object with your cleaned text and metadata:

Response Structure

{
  "result": "Cleaned And Formatted Text",
  "meta": {
    "stepsExecuted": 4,
    "inputLength": 150,
    "outputLength": 28,
    "processingTimeMs": 18
  }
}

result

Your processed text

meta.stepsExecuted

Number of transformations applied

meta.processingTimeMs

Processing time in milliseconds

Common Use Cases

Clean Email Lists

Trim, lowercase, and dedupe email addresses

={{ {
  "input": $json.emails,
  "steps": [
    "trim-lines",
    "lower-case",
    "dedupe-sort"
  ]
} }}

Format API Responses

Pretty-print minified JSON data

={{ {
  "input": $json.apiResponse,
  "steps": [
    "json-formatter"
  ]
} }}

Sanitize URLs

Remove tracking parameters from links

={{ {
  "input": $json.url,
  "steps": [
    "sanitize-url"
  ]
} }}

Clean CSV Data

Remove extra whitespace and normalize

={{ {
  "input": $json.csvContent,
  "steps": [
    "trim-lines",
    "collapse-spaces"
  ]
} }}

Extract Emails

Pull all email addresses from text

={{ {
  "input": $json.pageContent,
  "steps": [
    "email-extractor"
  ]
} }}

Title Case Names

Properly format person names

={{ {
  "input": $json.customerName,
  "steps": [
    "trim-lines",
    "title-case-converter"
  ]
} }}

Advanced Configuration

Some tools accept configuration options to customize their behavior. Pass a config object for fine-grained control.

CSV with Semicolon Delimiter

Convert semicolon-delimited CSV to JSON

={{ {
  "input": $json.csvData,
  "steps": [
    {
      "toolSlug": "csv-json-converter",
      "config": {
        "delimiter": ";",
        "hasHeaders": true
      }
    }
  ]
} }}

SHA-512 Hash in Base64

Generate SHA-512 hash in base64 format

={{ {
  "input": $json.password,
  "steps": [
    {
      "toolSlug": "hash-generator",
      "config": {
        "algorithm": "SHA-512",
        "format": "base64"
      }
    }
  ]
} }}

Explicit Base64 Encoding

Force encode direction (no auto-detect)

={{ {
  "input": $json.apiKey,
  "steps": [
    {
      "toolSlug": "base64-encode-decode",
      "config": {
        "direction": "encode"
      }
    }
  ]
} }}

Hex to String Conversion

Force decode hex to readable text

={{ {
  "input": $json.hexData,
  "steps": [
    {
      "toolSlug": "hex-converter",
      "config": {
        "direction": "decode"
      }
    }
  ]
} }}

Available Configuration Options

csv-json-converter

delimiter: "," | ";" | "\t"
hasHeaders: true | false

hash-generator

algorithm: "SHA-256" | "SHA-512" | "SHA-1"
format: "hex" | "base64"

base64-encode-decode

direction: "auto" | "encode" | "decode"

hex-converter

direction: "auto" | "encode" | "decode"

Available Tool IDs

Use these tool IDs in your steps array. View all 35+ tools at /automation

Text Formatting

trim-linescollapse-spacesupper-caselower-casetitle-case-converterremove-line-breaksdedupe-sortremove-accents

Data Processing

json-formattercsv-json-converteryaml-json-converterbase64-encode-decodehash-generatorhex-converter

Developer Tools

uuid-generatorunix-timestamp-convertersanitize-urlemail-extractorcron-generatorascii-tree-generator

Troubleshooting Common Issues

Error: "Invalid API key"

The API key is missing or incorrect.

Solutions:

Verify your API key is correct (copy from Settings)
Ensure you're using a Pro API key (not Free tier)
Check that the credential is properly selected in the HTTP Request node
Header name must be exactly x-api-key (lowercase)

Error: "Origin not allowed"

Your n8n instance origin isn't whitelisted (browser testing only).

Solutions:

Go to Settings → Development Key Origins
Add your n8n URL (e.g., http://localhost:5678)
Note: This only affects browser testing, not actual workflow execution

Error: "Unknown tool: [tool-name]"

The tool ID doesn't exist or is misspelled.

Solutions:

Check the tool ID spelling (see Available Tool IDs above)
Use hyphens, not underscores: trim-lines not trim_lines
Some tools have aliases: dedupe-sort or sort-remove-duplicates

Expression syntax error

The JSON body expression is malformed.

Solutions:

Entire body must start with =={{ and end with }}
Inside the expression, use variables directly: $json.field (no quotes needed)
Don't use JSON.stringify() - just reference the field
Example: ={{ { "input": $json.text, "steps": [...] } }}

High-Volume Automation

Processing thousands of records? CleanTextLab is optimized for batching. Instead of calling the API for every single row, join your data and process in bulk.

Efficient Batching

Use the Aggregate node in n8n to combine up to 50KB of text into a single API call.

Rate Management

Set the Wait node to 50ms between batches to stay comfortably within Pro limits.

View enterprise rate limits

Frequently Asked Questions

How do I use CleanTextLab with n8n?

Install our Community Node via npm, or use the HTTP Request node in n8n. Configure Header Auth with your CleanTextLab API key (from Settings → API Keys), then send POST requests to https://cleantextlab.com/api/v1/run. We provide 5 ready-to-use workflow templates to get started in under 5 minutes.

Can I process CSV files with semicolon delimiters in n8n?

Yes! CleanTextLab is the only text API that supports configurable delimiters for n8n. In the Community Node, simply select "Semicolon" from the dropdown. In the HTTP Request node, use the config object: { "toolSlug": "csv-json-converter", "config": { "delimiter": ";" } }. This works with commas, semicolons, tabs, or any custom delimiter.

Do I need a CleanTextLab Pro account to use n8n workflows?

Yes, the API requires a Pro plan ($5/month launch pricing) which includes 5,000 API calls per day. Free accounts are limited to 10 calls/day for testing. Pro users also get MCP server access, priority support, and all 35+ tools with advanced configuration options.

What makes CleanTextLab different from other n8n HTTP nodes?

Unlike generic HTTP APIs, CleanTextLab supports tool configuration (CSV delimiters, hash algorithms, encoding direction) directly in your workflow. Most text APIs force you into rigid defaults - ours adapts to your data. Plus, all processing is deterministic (no AI hallucinations) and privacy-focused (no data logging).

Can I chain multiple text transformations in one n8n node?

Absolutely! That's the power of our workflow engine. In a single HTTP Request node, you can trim whitespace, remove duplicates, convert to title case, and format as JSON - all in sequence. Each step processes the output of the previous step. Example: "steps": ["trim-lines", "dedupe-sort", "title-case-converter"]

Are CleanTextLab n8n workflows self-hosted?

The n8n workflows run wherever you host n8n (cloud, self-hosted, desktop), but the text processing API calls are made to CleanTextLab's servers. All network traffic uses HTTPS, and we never log your processed text. For fully offline processing, use our browser-based tools.

How do I troubleshoot "Invalid API key" errors in n8n?

This usually means: (1) The API key wasn't copied correctly from Settings → API Keys, (2) You're using a Free tier key (API requires Pro), (3) The credential isn't selected in the HTTP Request node's Authentication dropdown, or (4) The header name is wrong (must be exactly x-api-key in lowercase).

Can I use CleanTextLab API in Make, Zapier, or other automation platforms?

Yes! The API works with any platform that supports HTTP POST requests with header authentication. We provide specific documentation and templates for n8n, but the same /api/v1/run endpoint works in Make, Zapier, Pipedream, or custom scripts. See /docs/api for language-specific examples.

Error handling

Robust workflows always anticipate failures. Map these status codes to n8n logic:

401Invalid API Key

Stop & Alert

403Pro Feature Locked

Upgrade Account

429Rate Limit Exceeded

Retry with Wait

Ready to deploy?

Get started with our reference implementation.

Get API Access Now