Skip to main content

HttpClient

HTTP Client Node

The HTTP Client node enables your workflow to make web requests to external APIs, websites, and web services. This powerful node can retrieve data, send information, download files, and integrate with virtually any web-based system that accepts HTTP requests.

What This Node Does​

The HTTP Client node acts as a bridge between your TheoBuilder workflow and external web services. It can:

  • Fetch Data: Retrieve information from APIs, databases, or web services
  • Send Information: Submit forms, update records, or trigger actions on external systems
  • Download Files: Save documents, images, or other files from web sources
  • Integrate Systems: Connect your workflow with CRMs, payment processors, social media platforms, and more

Configuration Parameters​

Request Method​

  • Field Name: method
  • Type: Dropdown menu with options:
    • GET: Retrieve data from a server (most common for reading information)
    • POST: Send data to create new records or submit forms
    • PUT: Update existing records with complete replacement
    • PATCH: Update specific fields in existing records
    • DELETE: Remove records or data from the server
    • HEAD: Get response headers without the actual content
    • OPTIONS: Check what methods are allowed by the server
  • Default Value: None selected
  • Simple Description: Choose how you want to interact with the web service
  • When to Change This: Select based on what you're trying to accomplish - GET for reading data, POST for creating new records, PUT/PATCH for updates, DELETE for removal
  • Business Impact: Using the wrong method can cause requests to fail or perform unintended actions

Request URL​

  • Field Name: requestUrl
  • Type: Smart text field (supports dynamic variables)
  • Default Value: Empty
  • Simple Description: The web address where you want to send your request
  • When to Change This: Enter the specific API endpoint or web service URL you need to access
  • Business Impact: This determines which system and specific function your workflow will interact with

Headers Configuration​

Headers provide additional information about your request, such as authentication tokens, content types, and custom parameters required by the target system.

Show Auto-Generated Headers​

  • Field Name: filterStatus
  • Type: Toggle switch (On/Off)
    • On: Display all headers including those automatically added by the system
    • Off: Show only custom headers you've manually added
  • Default Value: Off
  • Simple Description: Controls whether you see system-generated headers in the headers list
  • When to Change This: Turn on when troubleshooting connection issues or when you need to see all headers being sent
  • Business Impact: Helps with debugging but doesn't affect the actual request

Headers Data Grid​

The headers section allows you to add custom headers required by your target API:

  • Key: The header name (e.g., "Authorization", "Content-Type", "X-API-Key")
  • Value: The header value (e.g., "Bearer your-token-here", "application/json")
  • Description: Optional notes about what this header does

Common Header Examples:

  • Authorization: Bearer \{\{apiToken\}\} for API authentication
  • Content-Type: application/json when sending JSON data
  • Accept: application/json to request JSON responses
  • X-API-Key: \{\{yourApiKey\}\} for API key authentication

Request Body​

Raw JSON Body​

  • Field Name: body
  • Type: Multi-line smart text field (supports dynamic variables)
  • Default Value: Empty
  • Simple Description: The data you want to send with your request (typically for POST, PUT, or PATCH methods)
  • When to Change This: Add JSON data when creating or updating records, submitting forms, or sending structured information
  • Business Impact: This is the actual information being transmitted to the external system

Example Body for Creating a Customer:

{
  "name": "{{customerName}}",
  "email": "{{customerEmail}}",
  "phone": "{{customerPhone}}"
}

Advanced Settings​

Enable SSL Certificate Verification​

  • Field Name: sslEnabled
  • Type: Toggle switch (On/Off)
    • On: Verify the security certificate of the target server (recommended)
    • Off: Skip certificate verification (use only for testing or internal systems)
  • Default Value: Off
  • Simple Description: Ensures you're connecting to a legitimate, secure server
  • When to Change This: Enable for production systems and external APIs to maintain security
  • Business Impact: Protects against man-in-the-middle attacks and ensures data security

Automatically Follow Redirects​

  • Field Name: autoFollowRedirects
  • Type: Toggle switch (On/Off)
    • On: Automatically follow redirect responses to the final destination
    • Off: Stop at the first redirect response
  • Default Value: Off
  • Simple Description: Handles when a server tells you to go to a different URL
  • When to Change This: Enable when working with services that commonly redirect requests
  • Business Impact: Ensures you reach the correct endpoint even if URLs change

Follow Original HTTP Method​

  • Field Name: followOgHttpMethod
  • Type: Toggle switch (On/Off)
    • On: Keep the same HTTP method when following redirects
    • Off: May change to GET method on redirects (standard behavior)
  • Default Value: Off
  • Simple Description: Controls whether POST/PUT requests stay as POST/PUT when redirected
  • When to Change This: Enable when the target system requires maintaining the original method through redirects
  • Business Impact: Prevents data loss or method conflicts during redirects

Remove Referer Header on Redirect​

  • Field Name: removeRefererHeader
  • Type: Toggle switch (On/Off)
    • On: Remove the referer header when following redirects
    • Off: Keep the referer header through redirects
  • Default Value: Off
  • Simple Description: Controls whether the target server knows where the request originally came from
  • When to Change This: Enable for privacy or when target systems reject requests with referer headers
  • Business Impact: May be required for certain security-conscious APIs

Encode URL Automatically​

  • Field Name: autoEncodeUrl
  • Type: Toggle switch (On/Off)
    • On: Automatically convert special characters in URLs to web-safe format
    • Off: Send URLs exactly as entered
  • Default Value: Off
  • Simple Description: Handles special characters like spaces and symbols in URLs
  • When to Change This: Enable when your URLs contain spaces, international characters, or special symbols
  • Business Impact: Prevents URL formatting errors that cause request failures
  • Field Name: disableCookieJar
  • Type: Toggle switch (On/Off)
    • On: Don't store or send cookies between requests
    • Off: Automatically handle cookies like a web browser
  • Default Value: Off
  • Simple Description: Controls whether the node remembers cookies from previous requests
  • When to Change This: Enable when you don't want session persistence or when cookies cause issues
  • Business Impact: May be required for stateless API interactions or to avoid authentication conflicts

Use Server Cipher Suite During Handshake​

  • Field Name: useServerCipher
  • Type: Toggle switch (On/Off)
    • On: Let the server choose the encryption method
    • Off: Use client-preferred encryption methods
  • Default Value: Off
  • Simple Description: Controls how encryption is negotiated with secure servers
  • When to Change This: Enable when connecting to servers with specific encryption requirements
  • Business Impact: May be required for compatibility with certain secure systems

Response Configuration​

Response Type​

  • Field Name: responseType
  • Type: Dropdown menu with options:
    • JSON: Expect structured data that can be parsed and used in subsequent nodes
    • File Download: Save the response as a file to your system
    • Text: Treat the response as plain text content
  • Default Value: JSON
  • Simple Description: Tells the node how to handle the data it receives back
  • When to Change This: Choose based on what the API returns - JSON for data, File Download for documents/images, Text for simple content
  • Business Impact: Incorrect type selection can cause data processing errors in subsequent nodes

File Download Settings (when Response Type is "File Download")​

File Output Folder​

  • Field Name: responseFileOutFolder
  • Type: Smart text field with location picker
  • Default Value: Empty
  • Simple Description: Where downloaded files should be saved on your system
  • When to Change This: Specify the folder path where you want files stored
  • Business Impact: Determines file organization and accessibility for other workflow nodes

Unzip if Response is ZIP​

  • Field Name: responseUnzipIfZip
  • Type: Toggle switch (On/Off)
    • On: Automatically extract ZIP files after download
    • Off: Keep ZIP files as-is
  • Default Value: Off
  • Simple Description: Automatically extracts compressed files for easier access
  • When to Change This: Enable when you need to process individual files within ZIP archives
  • Business Impact: Saves manual extraction steps and enables processing of archive contents

Keep ZIP File (when unzipping is enabled)​

  • Field Name: responseZipKeepFile
  • Type: Toggle switch (On/Off)
    • On: Keep the original ZIP file after extraction
    • Off: Delete the ZIP file after extracting contents
  • Default Value: Off
  • Simple Description: Controls whether to preserve the original archive
  • When to Change This: Enable when you need both the archive and extracted files
  • Business Impact: Affects storage space usage and file management

Convert Images to Base64 (when unzipping is enabled)​

  • Field Name: responseZipImgToBase64
  • Type: Toggle switch (On/Off)
    • On: Convert image files to base64 text format for easy embedding
    • Off: Keep image files in their original format
  • Default Value: Off
  • Simple Description: Converts images to text format that can be embedded in emails or web pages
  • When to Change This: Enable when you need to embed images directly in other content
  • Business Impact: Enables direct image usage in emails and web content without separate file hosting

Output Configuration​

Output Transformation​

  • Field Name: outTransformId
  • Type: Dropdown menu with options:
    • Original with appended result column: Keeps all input data and adds the HTTP response as a new column
    • Return result column only: Returns only the HTTP response data, discarding input data
    • Spread by attachments: Creates separate rows for each file (only for File Download response type)
  • Default Value: Original with appended result column
  • Simple Description: Controls how the HTTP response is combined with your existing workflow data
  • When to Change This: Choose based on whether you need to preserve input data or focus only on the response
  • Business Impact: Affects data structure and what information is available to subsequent nodes

Result Property Name​

  • Field Name: outColumnName
  • Type: Text field
  • Default Value: "http_response"
  • Simple Description: The name of the column that will contain the HTTP response data
  • When to Change This: Use descriptive names like "customer_data", "api_result", or "downloaded_file" for clarity
  • Business Impact: Makes it easier to reference the response data in subsequent workflow nodes

Real-World Use Cases​

Customer Data Synchronization​

Business Situation: A retail company needs to sync customer information between their e-commerce platform and CRM system every hour.

What You'll Configure:

  • Set method to "GET" to retrieve customer data
  • Enter your e-commerce API endpoint in the Request URL field
  • Add "Authorization" header with your API key
  • Choose "JSON" as the response type
  • Set output transformation to "Original with appended result column"
  • Name the result column "customer_updates"

What Happens: The node fetches the latest customer data from your e-commerce platform and makes it available for processing by subsequent nodes that update your CRM.

Business Value: Eliminates manual data entry, reduces errors by 95%, and ensures customer information stays synchronized across all systems.

Automated Invoice Generation​

Business Situation: An accounting firm wants to automatically generate invoices by sending client data to their billing system API.

What You'll Configure:

  • Set method to "POST" to create new invoices
  • Enter your billing system's invoice creation endpoint
  • Add "Content-Type: application/json" header
  • Include client data in the JSON body using variables from previous nodes
  • Choose "JSON" response type to capture the generated invoice details
  • Enable SSL certificate verification for security

What Happens: The node sends client information to your billing system, which creates an invoice and returns the invoice number and details.

Business Value: Reduces invoice creation time from 15 minutes to 30 seconds per client, eliminates data entry errors, and improves cash flow with faster billing.

Document Download Automation​

Business Situation: A legal firm needs to automatically download contracts and legal documents from a client portal for case management.

What You'll Configure:

  • Set method to "GET" to download files
  • Use dynamic URLs with case numbers: https://clientportal.com/documents/\{\{caseNumber\}\}
  • Add authentication headers for the client portal
  • Choose "File Download" as response type
  • Set output folder to your case management directory
  • Enable "Unzip if response is ZIP" for document packages
  • Use "Spread by attachments" output transformation

What Happens: The node downloads all documents for each case and organizes them in your file system, creating separate workflow rows for each document.

Business Value: Saves 2 hours per case on manual document retrieval, ensures no documents are missed, and maintains organized case files automatically.

Social Media Integration​

Business Situation: A marketing agency wants to automatically post client content to multiple social media platforms when campaigns go live.

What You'll Configure:

  • Set method to "POST" for creating social media posts
  • Use platform-specific API endpoints (Facebook, Twitter, LinkedIn)
  • Add OAuth authentication headers for each platform
  • Include post content and media in the JSON body
  • Choose "JSON" response type to capture post IDs and engagement metrics
  • Enable automatic redirect following for platform-specific routing

What Happens: The node publishes content across all configured social media platforms and returns post performance data for tracking.

Business Value: Reduces campaign launch time by 75%, ensures consistent messaging across platforms, and provides immediate performance tracking data.

Step-by-Step Configuration​

Setting Up a Basic API Request​

  1. Adding the Node:

    • Drag the HTTP Client node from the left panel onto your workflow canvas
    • Connect it to the previous node using the arrow connector

  2. Configuring the Request:

    • Click on the HTTP Client node to open the settings panel
    • Select your desired method from the "Method" dropdown (GET for reading data, POST for sending data)
    • Enter the API endpoint URL in the "Request URL" field
    • Use dynamic variables like \{\{customerID\}\} to personalize requests

  3. Setting Up Authentication:

    • Expand the "Headers" section
    • Click "Add Header" to create authentication headers
    • For API key authentication: Set Key to "X-API-Key" and Value to your API key
    • For bearer token authentication: Set Key to "Authorization" and Value to "Bearer your-token-here"

  4. Configuring the Request Body (for POST/PUT requests):

    • Expand the "Body" section
    • Enter your JSON data in the "Raw JSON" field
    • Use variables from previous nodes: \{\{customerName\}\}, \{\{orderAmount\}\}, etc.

  5. Setting Response Handling:

    • Expand the "Response" section
    • Choose "JSON" for API data, "File Download" for documents, or "Text" for simple content
    • If downloading files, specify the output folder path

  6. Configuring Output:

    • Expand the "Output" section
    • Choose how to combine the response with your existing data
    • Give your result column a descriptive name like "api_response" or "customer_data"

  7. Testing Your Configuration:

    • Click the "Test Configuration" button
    • Enter sample data in the test panel
    • Verify the request succeeds and returns expected data
    • Save your configuration

Advanced Configuration for File Downloads​

  1. Setting Up File Downloads:

    • Follow steps 1-3 from basic configuration
    • In the "Response" section, select "File Download" from the Response Type dropdown
    • Enter your desired file storage location in the "File Output Folder" field

  2. Handling ZIP Files:

    • Check "Unzip if response is ZIP" to automatically extract archives
    • Optionally check "Keep ZIP file" to preserve the original archive
    • Check "Convert images to base64"