HTTP Request Node

Note: Compose is only available for Beta testing. See Welcome to UKG Compose > Beta Disclosure for more information.

The HTTP Request node is one of the most versatile nodes in Compose. Use it to call REST APIs for any service that doesn't have a dedicated node, including custom UKG APIs, third-party services, and internal applications.

What the HTTP Request Node Is

The HTTP Request node allows you to make HTTP requests (GET, POST, PUT, DELETE, etc.) to any REST API endpoint.

Key characteristics:

• Works with any REST API (no dedicated node required)
• Supports all standard HTTP methods (GET, POST, PUT, PATCH, DELETE, etc.)
• Handles authentication (API keys, OAuth, Basic Auth, etc.)
• Can import cURL commands from API documentation
• Processes JSON, XML, and other response formats
• Useful for calling UKG APIs not covered by dedicated nodes

Think of it as: A universal API client that lets you connect to any web service from your workflow.

When to Use the HTTP Request Node

Calling UKG APIs Without Dedicated Nodes

Use the HTTP Request node to call UKG Pro APIs that don't have dedicated Compose nodes.

Use cases:

• Custom UKG API endpoints not covered by ProHRServicesAPI
• UKG product APIs beyond the standard Compose node set
• Beta or preview UKG APIs
• Custom extensions or configurations

Pattern: Configure the HTTP Request node with UKG API endpoint, authentication, and request body. Process the response in downstream nodes.

Integrating with Third-Party Services

Call external APIs to integrate with benefits vendors, payroll processors, background check providers, or custom applications.

Use cases:

• Send enrollment changes to benefits administrators (insurance, 401k, HSA)
• Submit payroll adjustments to payroll processors
• Initiate background checks or I-9 verification with vendor APIs
• Sync employee data to timekeeping or scheduling systems
• Update external HRIS or talent management platforms

Pattern: Use HTTP Request to call external API. Parse the response. Use the data in downstream workflow logic.

Webhook Responses and API Callbacks

Respond to webhook requests or send data back to calling services.

Use cases:

• Acknowledge webhook receipt
• Send status updates to external systems
• Return data to API callers
• Implement callback patterns

Pattern: Webhook trigger receives request → Process data → HTTP Request node calls back to external system → Workflow continues

Data Enrichment and Lookups

Query external data sources to enrich workflow data.

Use cases:

• Validate SSN or tax ID with verification services
• Look up salary benchmarking data from compensation platforms
• Query background check status from screening vendors
• Fetch job posting data from ATS (Applicant Tracking Systems)
• Validate work authorization with E-Verify or similar services

Pattern: Extract identifier from workflow data → HTTP Request queries external API → Merge response data back into workflow

Common Workflow Patterns

Pattern 1: Call UKG Dimensions API for Labor Data

Scenario: Retrieve timecard or labor data from UKG Dimensions that isn't covered by standard Compose nodes.

Steps:

1. Scheduled Trigger: Runs daily at 6 AM
2. HTTP Request node:
   • Method: POST
   • URL: https://{{tenant}}.mykronos.com/api/v1/commons/data/multi_read
   • Authentication: OAuth2 or API key (configured in credentials)
   • Body (JSON):
     {
     "select": [
     {"key": "PEOPLE>PERSONNUM"},
     {"key": "TIMECARD>TOTALS>ACTUALWORKEDHOURS"}
     ],
     "from": {
     "view": "TIMECARD",
     "employeeSet": {"dateRange": {"symbolicPeriod": {"qualifier": "Yesterday"}}}
     }
     }
3. Code node: Transform timecard data to workflow format
4. Data Tables node: Store daily hours for reporting
5. IF node: Check for overtime hours > threshold
6. Notification node: Alert manager if overtime detected

Why this works: Accesses UKG Dimensions labor data via REST API when dedicated nodes don't cover the specific query needed.

Pattern 2: Update Custom Fields in UKG Pro via Business Integration

Scenario: Update custom employee fields in UKG Pro that aren't exposed through standard API nodes.

Steps:

1. Form Trigger: Employee submits preference form

2. HTTP Request node:

   • Method: POST
   • URL: https://service.ultipro.com/services/BiDataService
   • Authentication: UKG credentials
   • Headers: SOAPAction, Content-Type: text/xml
   • Body (XML/SOAP):
   XML

    <soapenv:Envelope>
      <soapenv:Body>
        <ExecuteReport>
          <reportPath>/Custom/UpdateEmployeePreferences</reportPath>
          <parameters>
            <parameter>
              <name>EmployeeId</name>
              <value>{{ $json.employee_id }}</value>
            </parameter>
            <parameter>
              <name>PreferenceValue</name>
              <value>{{ $json.preference }}</value>
            </parameter>
          </parameters>
        </ExecuteReport>
      </soapenv:Body>
    </soapenv:Envelope>
   

3. IF node: Check response status

4. Notification node: Confirm update to employee

Why this works: Uses UKG Pro's Business Integration (BI) service to update custom fields not available through standard HR Services API.

Pattern 3: Query UKG Reporting API for Custom Analytics

Scenario: Retrieve custom report data from UKG Pro for analytics or dashboards.

Steps:

1. Scheduled Trigger: Runs weekly on Monday
2. HTTP Request node:
   • Method: GET
   • URL: https://service.ultipro.com/services/ReportService/GetReportList
   • Authentication: UKG API credentials
   • Headers: US-API-Key, US-Application-ID
3. HTTP Request node (loop through reports):
   • Method: POST
   • URL: https://service.ultipro.com/services/ReportService/ExecuteReport
   • Body: Report ID and parameters
4. Code node: Parse and transform report XML/JSON
5. HTTP Request node: Send data to external analytics platform
   • Method: POST
   • URL: https://your-analytics-platform.com/api/data-import
   • Body: Transformed employee data

Why this works: Extracts custom UKG Pro reports and sends to external systems (Power BI, Tableau, custom dashboards) that don't have direct UKG connectors.

Pattern 4: Integrate with Benefits Vendor API

Scenario: Send employee enrollment changes to external benefits administrator.

Steps:

1. Webhook Trigger: Receives UKG Pro benefits enrollment event
2. Data Query node: Get employee details from UKG Pro
3. HTTP Request node:
   • Method: POST
   • URL: https://benefits-vendor.com/api/v2/enrollments
   • Authentication: API Key (benefits vendor provided)
   • Body (JSON):
     {
     "employee_ssn": "{{ $json.employee.ssn }}",
     "enrollment_type": "{{ $json.benefit_type }}",
     "coverage_level": "{{ $json.coverage }}",
     "effective_date": "{{ $json.effective_date }}"
     }
4. IF node: Check vendor response status
   • Success: Log enrollment confirmation
   • Failure: Create Data Tables entry for manual review
5. Notification node: Notify HR of enrollment sync status

Why this works: Synchronizes UKG Pro benefits elections with external benefits administrators (insurance carriers, 401k providers, HSA administrators) who provide REST APIs but don't have dedicated Compose nodes.

Setting Up the HTTP Request Node

Two Ways to Configure

Option 1: Configure Node Parameters Manually

• Set Method, URL, Authentication, Headers, Body, and Options directly in the node
• Best for custom integrations or when you understand the API

Option 2: Import cURL Command

• Copy cURL example from API documentation
• Paste into "Import cURL" option in the node
• Compose automatically populates Method, URL, Headers, and Body
• Best for quickly getting started with a new API

Key Configuration Fields

Method:

• GET - Retrieve data
• POST - Create new data
• PUT - Update existing data (full replacement)
• PATCH - Update existing data (partial update)
• DELETE - Remove data
• HEAD, OPTIONS - Less common, used for metadata or preflight requests

URL:

• The API endpoint to call
• Can include expressions: https://api.service.com/employees/{{ $json.employee_id }}

Authentication:

• Predefined Credential Type - Use for services with existing n8n credentials (recommended when available)
• Generic Credential Type - Use for custom integrations:
  • API Key - Common for simple API authentication (Header Auth or Query Auth)
  • OAuth2 - For services requiring OAuth authorization flow
  • Basic Auth - Username/password authentication
  • Bearer Token - Token-based authentication (Header Auth with Bearer prefix)
  • Custom Auth - For non-standard authentication methods

Send Query Parameters:

• Add URL query parameters (e.g., ?filter=active&limit=100)
• Use "Using Fields Below" for simple parameters or "Using JSON" for complex parameters

Send Headers:

• Add HTTP headers (e.g., Content-Type: application/json)
• Authentication headers often set automatically by credential type

Send Body:

• Include request body for POST, PUT, PATCH requests
• Choose format: JSON, Form Data, Form URLencoded, Raw, or Binary File
• Use "Using Fields Below" for simple bodies or "Using JSON" for complex structures

Working with JSON Responses

Most modern APIs return JSON. The HTTP Request node automatically parses JSON responses into workflow data.

Example:

API Response:

{
  "employee": {
    "id": "12345",
    "first_name": "Jane",
    "last_name": "Doe",
    "department": "Engineering",
    "manager_id": "67890"
  }
}

Accessing response data in downstream nodes:

{{ $json.employee.first_name }}  // Returns "Jane"
{{ $json.employee.manager_id }}  // Returns "67890"

If the API returns an array:

[
  { "id": "1", "name": "Alice" },
  { "id": "2", "name": "Bob" }
]

Access items using array index or loop through them:

{{ $json[0].name }}  // Returns "Alice"

Or use a Loop node to process each item.

Working with XML Responses

Some APIs return XML instead of JSON. Configure the HTTP Request node to handle XML:

Steps:

1. Add Option: Response → Response Format → Select Text
2. Parse XML in a downstream Code node or use an XML node (if available)

Alternative: Use the XML node after the HTTP Request to convert XML to JSON.

Import cURL Command

Many API documentation sites provide cURL examples. You can copy these directly into Compose.

How to import cURL:

1. Find the cURL example in the API documentation
2. Copy the cURL command (example below)
3. Open the HTTP Request node
4. Select Import cURL button
5. Paste the cURL command
6. Select Import

Example cURL command:

curl -X POST https://api.service.com/employees \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "first_name": "Jane",
    "last_name": "Doe",
    "department": "HR"
  }'

Compose automatically extracts:

• Method: POST
• URL: https://api.service.com/employees
• Headers: Content-Type and Authorization
• Body: The JSON payload

Note: After importing, replace placeholder values (like YOUR_API_KEY) with actual credentials or expressions referencing workflow data.

Authentication Patterns

API Key Authentication (Header Auth)

Most common for modern APIs.

Configuration:

• Authentication: Generic Credential Type → Header Auth
• Credential:
  • Name: Authorization (or API-specific header name like X-API-Key)
  • Value: Bearer YOUR_API_KEY (or just the key, depending on API)

Example:

• Header Name: Authorization
• Header Value: Bearer sk_live_1234567890abcdef

OAuth2 Authentication

Used by services like Google, Microsoft, Salesforce.

Configuration:

• Authentication: Generic Credential Type → OAuth2 API
• Credential:
  • Authorization URL: (from API documentation)
  • Access Token URL: (from API documentation)
  • Client ID: (from service provider)
  • Client Secret: (from service provider)
  • Scope: (API permissions needed)

Best practice: Set up OAuth2 credentials once, reuse across multiple HTTP Request nodes.

Basic Auth

Username/password authentication (less secure, avoid for sensitive APIs).

Configuration:

• Authentication: Generic Credential Type → Basic Auth
• Credential:
  • User: API username
  • Password: API password or token

No Authentication

For public APIs or when authentication is handled via query parameters.

Configuration:

• Authentication: None
• (Optional) Add API key as a query parameter or header manually

Common HTTP Request Options

Pagination

When APIs return large datasets split across multiple pages:

Option 1: Update a Parameter in Each Request

• Use pagination variables: {{ $pageCount }}, {{ $request.length }}, {{ $response.length }}
• Configure "Pagination Complete When" expression
• Common pattern: Increment page number until response is empty

Option 2: Response Contains Next URL

• API returns next page URL in response
• Extract URL using expression: {{ $json.next_url }}

Example

• Pagination Mode: Update a Parameter in Each Request
• Query Parameter: page = {{ $pageCount }}
• Pagination Complete When: {{ $response.length === 0 }}

Response Options

Include Response Headers and Status:

• Turn on to access response headers and HTTP status code
• Useful for debugging or when response headers contain important data

Response Format:

• Autodetect (default) - Compose detects JSON, text, or binary
• JSON - Force JSON parsing
• File - Save response as a file (useful for PDFs, images, etc.)
• Text - Treat response as plain text

Never Error:

• By default, HTTP Request fails workflow if API returns non-2xx status code
• Turn on to continue workflow even if API returns error (handle errors manually in workflow logic)

Timeout

Set how long to wait for API response before failing:

• Default: 120 seconds (2 minutes)
• Adjust based on API performance (slow APIs may need longer timeout)

Batching

When sending multiple requests, control rate limiting:

• Items per Batch - How many requests to send in each batch
• Batch Interval - Milliseconds to wait between batches

Use case: Avoid hitting API rate limits when processing large datasets.

Error Handling

APIs can fail for many reasons. Plan for errors in your workflow.

Common API errors:

• 400 Bad Request - Invalid request data
• 401 Unauthorized - Authentication failed
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource doesn't exist
• 429 Too Many Requests - Rate limit exceeded
• 500 Internal Server Error - API server error

Error handling pattern:

1. HTTP Request node (with "Continue On Fail" enabled in node settings)
2. IF node: Check if request succeeded
   • Check: {{ $json.error }} does not exist
   • True: Process successful response
   • False: Handle error (log, notify, retry, etc.)

Alternative: Use Error Trigger node to catch all HTTP Request errors and route to error handling workflow.

Best Practices

Use Credentials, Not Hard-Coded Secrets

Don't do this:

• Header: Authorization
• Value: Bearer sk_live_1234567890abcdef

Do this:

• Set up credentials using Authentication option
• Reference credentials in the node
• Credentials are encrypted and managed securely

Test API Calls Outside Workflows First

Before building complex workflows:

1. Test the API call manually (using Postman, cURL, or browser)
2. Verify request/response format
3. Confirm authentication works
4. Then configure the HTTP Request node

Handle Rate Limits

Many APIs limit request frequency:

• Use Batching option to control request rate
• Add delay between requests if needed
• Check API documentation for rate limits
• Monitor for 429 errors and add retry logic

Validate Response Data

Don't assume API responses are always valid:

• Check that expected fields exist before using them
• Use IF nodes to validate response structure
• Handle missing or null values gracefully

Monitor API Changes

External APIs can change without notice:

• Test workflows after API updates
• Set up alerts for failed HTTP Request executions
• Have fallback logic for critical integrations

UKG API Integration Tips

Finding UKG API Documentation

UKG API documentation is typically available through:

• UKG Pro API documentation portal (contact UKG support for access)
• Developer resources in UKG Community
• Your UKG implementation team

Common UKG API Authentication

Most UKG APIs use:

• OAuth2 with client credentials or authorization code flow
• API keys provided by UKG
• Service account credentials

Check with your UKG administrator for correct authentication method and credentials.

UKG API Response Formats

UKG APIs typically return JSON. Structure may include:

• Metadata fields (pagination, status, timestamps)
• Data arrays or objects
• Error objects for failed requests

Always review the specific API documentation for response format.

Related Pages

Other integration nodes:

• API Integration Nodes - Dedicated UKG API nodes
• Data Query Nodes - UKG data retrieval nodes
• Webhook Triggers - Receiving HTTP requests

Workflow building:

• Build Workflows in UKG Compose
• Common Use Cases and Design Patterns

Security:

• Security and Governance
• Connectors and Connections