Skip to content

n8n Actions

This document describes how to use the WhiteLabelCRO Integration API actions in n8n workflows.

How Actions Work

In n8n, actions are implemented using HTTP Request nodes that call the Integration API to create or modify records. Each action maps to a specific API endpoint and supports idempotency for safe retries.

Available Actions (9)

Lead Actions

Create Lead - Creates a new lead with status "Lead - New" - Endpoint: POST /api/v1/integrations/leads - Required: first_name, last_name, email - Optional: phone, city, state, zip, package_keyword, affiliate_id, external_id - Returns: client_id, status, created_utc

Update Lead - Modifies an existing lead's information - Endpoint: PATCH /api/v1/integrations/leads/{client_id} - Required: client_id - Optional: first_name, last_name, email, phone, city, state, zip, employee_id, affiliate_id, external_id - Returns: success, updated_utc, client_id

Update Lead Status - Changes a lead's status (must remain a Lead status) - Endpoint: PATCH /api/v1/integrations/leads/{client_id}/status - Required: client_id, new_status or new_status_id - Optional: changed_by_employee_id, status_note - Returns: previous_status, new_status, updated_utc

Client Actions

Create Client - Enrolls a new client in the system - Endpoint: POST /api/v1/integrations/clients - Required: first_name, last_name, email - Optional: phone, status, employee_id, city, state, zip, affiliate_id, external_id - Returns: client_id, status, created_utc

Update Client - Modifies an existing client's information - Endpoint: PATCH /api/v1/integrations/clients/{client_id} - Required: client_id - Optional: first_name, last_name, email, phone, city, state, zip, employee_id, affiliate_id, external_id - Returns: success, updated_utc, client_id

Update Client Status - Changes a client's lifecycle stage - Endpoint: PATCH /api/v1/integrations/clients/{client_id}/status - Required: client_id, new_status or new_status_id - Optional: changed_by_employee_id, status_note - Returns: previous_status, new_status, updated_utc

Add Client Note - Attaches a note or comment to a client record - Endpoint: POST /api/v1/integrations/clients/{client_id}/notes - Required: client_id, text - Optional: note_type, visibility, external_id - Returns: client_note_id, created_utc

Affiliate Actions

Create Affiliate - Adds a new referral partner - Endpoint: POST /api/v1/integrations/affiliates - Required: email, first_name, last_name - Optional: phone, affiliate_code, commission_rate, affiliate_company_name, external_id - Returns: employee_id, affiliate_code, is_approved, created_utc - Note: Created affiliates are not automatically approved

Update Affiliate - Modifies an existing affiliate's information - Endpoint: PATCH /api/v1/integrations/affiliates/{employee_id} - Required: employee_id - Optional: first_name, last_name, email, phone, affiliate_company_name, commission_rate, is_active, is_approved, external_id - Returns: success, updated_utc, employee_id

Implementing Actions in n8n

Basic Setup

  1. Add HTTP Request node to your workflow
  2. Set Method: POST, PATCH, or DELETE (per action)
  3. Set URL: Full endpoint URL (e.g., https://your-api-url.com/api/v1/integrations/leads)
  4. Set Authentication: Select your WhiteLabelCRO credential
  5. Configure Body with required and optional fields

Request Body Configuration

Use Body Content Type: JSON

Example: Create Lead 

{
  "first_name": "{{ $json.first_name }}",
  "last_name": "{{ $json.last_name }}",
  "email": "{{ $json.email }}",
  "phone": "{{ $json.phone }}",
  "external_id": "hubspot_{{ $json.id }}"
}

Field Types

  • String fields: Use expressions like {{ $json.field_name }}
  • ID fields: Use numeric values (e.g., client_id: 12345)
  • Status fields: Accept either ID (new_status_id: 231) or name (new_status: "Client - Active")
  • Boolean fields: Use true/false (no quotes in JSON)

Dynamic URLs

For update operations with ID in URL:

https://your-api-url.com/api/v1/integrations/clients/{{ $json.client_id }}

Idempotency

Actions support idempotency via the external_id field: - If you provide an external_id, the system checks for existing records - Duplicate submissions update existing records rather than creating duplicates - Use external_id to link WhiteLabelCRO records to external systems (HubSpot, Salesforce, etc.)

Example: 

{
  "email": "john@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "external_id": "hubspot_12345"
}

Error Handling

Common Errors

400 Bad Request - Missing required field - Invalid field value - Request validation failed

401 Unauthorized - Invalid or expired API key - Missing X-Api-Key header

404 Not Found - Record not found (for update actions) - Invalid client_id or employee_id

429 Too Many Requests - Rate limit exceeded - Wait and retry per Retry-After header

Handling Errors in n8n

  1. Add IF node after HTTP Request
  2. Check {{ $json.error }} existence
  3. Route errors to logging or notification nodes
  4. Use Error Trigger node to catch workflow failures

Example condition: 

{{ $json.error !== undefined }}

Rate Limits

Actions count toward the "write" rate limit bucket: - 100 requests per minute per API key - Shared across all write operations

Monitor X-RateLimit-Remaining header in HTTP Request node responses.

Response Handling

Success Response

Most actions return JSON with created/updated record details:

{
  "client_id": 12345,
  "status": "Lead - New",
  "created_utc": "2026-01-28T10:30:00Z"
}

Access in subsequent nodes: 

{{ $json.client_id }}
{{ $json.status }}

Checking Success

Check HTTP status code: 

{{ $statusCode === 200 || $statusCode === 201 }}

Best Practices

Null Handling

Check for null values before sending:

{
  "phone": "{{ $json.phone || null }}",
  "city": "{{ $json.city !== undefined ? $json.city : null }}"
}

Batch Operations

For bulk creates/updates: 1. Use Split In Batches node 2. Limit to 100 requests/minute 3. Add Wait node between batches if needed

Error Recovery

  1. Enable Continue On Fail on HTTP Request node
  2. Add error handling branches
  3. Log failures for manual review
  4. Implement retry logic for transient errors (429, 503)

Platform Compatibility

These same actions are available via: - Zapier - Using native app actions - Make - Using HTTP modules - Custom code - Direct API calls

All platforms use the same endpoints and field names.