Skip to content

n8n Searches

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

How Searches Work

In n8n, searches are implemented using HTTP Request nodes that query the Integration API to find existing records. They enable the "Find or Create" pattern for deduplication and record linking.

Available Searches (2)

Find Client

Locate an existing client in WhiteLabelCRO.

Endpoint: GET /api/v1/integrations/clients/search

Search Criteria (at least one required as query parameter): - email - Client email address - phone - Client phone number - client_id - WhiteLabelCRO client ID - external_id - External system ID

Response Fields: - client_id - Unique client identifier - first_name, last_name, full_name - Client name - email, phone - Contact information - status, status_id, status_name - Current status - employee_id, employee_name - Assigned employee - affiliate_id, affiliate_name - Referring affiliate - created_utc - Enrollment date

Find Lead

Locate an existing lead in WhiteLabelCRO.

Endpoint: GET /api/v1/integrations/leads/search

Search Criteria (at least one required as query parameter): - email - Lead email address - phone - Lead phone number - client_id - WhiteLabelCRO client ID - external_id - External system ID

Response Fields: - client_id - Unique lead identifier - first_name, last_name, full_name - Lead name - email, phone - Contact information - status, status_id, status_name - Current status (Lead% pattern) - employee_id, employee_name - Assigned employee - affiliate_id, affiliate_name - Referring affiliate - created_utc - Capture date

Note: Find Lead only returns records with status matching 'Lead%' pattern. Converted clients are excluded.

Implementing Searches in n8n

Basic Setup

  1. Add HTTP Request node to your workflow
  2. Set Method: GET
  3. Set URL: Full endpoint URL
  4. Add Query Parameters for search criteria
  5. Set Authentication: Select your WhiteLabelCRO credential

Example: Find Client by Email

URL: https://your-api-url.com/api/v1/integrations/clients/search

Query Parameters: - Name: email - Value: {{ $json.email }}

Example: Find Client by External ID

Query Parameters: - Name: external_id - Value: hubspot_{{ $json.id }}

Multiple Search Criteria

Add multiple query parameters to search with AND logic:

Query Parameters: - Name: email, Value: {{ $json.email }} - Name: phone, Value: {{ $json.phone }}

All criteria must match for a result.

Search Behavior

  • Exact match only (no partial matching)
  • Case-insensitive for email
  • Returns the first matching record
  • Returns empty array if no match found

Find or Create Pattern

Implement the "Find or Create" pattern in n8n:

  1. Add HTTP Request node (GET) to search for record
  2. Add IF node to check if result exists
  3. True branch: Record found, use existing data
  4. False branch: Record not found, add HTTP Request node (POST) to create

Check for empty result: 

{{ $json.length > 0 }}

Or check specific field: 

{{ $json[0].client_id !== undefined }}

This pattern is essential for: - Lead capture from multiple sources - Syncing records from external CRMs - Preventing duplicate data entry

Empty Results

When no record is found: - Search returns an empty array [] - {{ $json.length === 0 }} is true - Route to "create" branch in IF node - Handle with error handling or default values

Handling Search Results

Accessing First Result

Search returns an array. Access first result:

{{ $json[0].client_id }}
{{ $json[0].email }}
{{ $json[0].full_name }}

Checking for Results

Use IF node with condition:

{{ $json.length > 0 }}

Handling Multiple Matches

The API returns only the first matching record. If multiple records might match: - Use more specific criteria (email + phone) - Use external_id for guaranteed uniqueness - Review your data for duplicates if unexpected matches occur

Rate Limits

Searches count toward the "read" rate limit bucket: - 60 requests per minute per API key - Shared across all read operations (event polling, searches)

Monitor X-RateLimit-Remaining header in responses.

Error Handling

Common Errors

400 Bad Request - No search criteria provided - Invalid parameter format

401 Unauthorized - Invalid or expired API key

404 Not Found - Endpoint URL incorrect

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

Handling in n8n

  1. Enable Continue On Fail on HTTP Request node
  2. Add IF node to check for errors
  3. Route errors to logging nodes
  4. Implement retry logic for rate limits

Troubleshooting

Search Not Finding Records

  1. Verify the search value matches exactly (check for typos, spaces)
  2. Confirm the record exists in WhiteLabelCRO
  3. For Find Lead, ensure the status matches 'Lead%' pattern
  4. Check that your API key has integrations:read scope
  5. Test search with known values in WhiteLabelCRO

Wrong Record Found

  1. Use more specific search criteria
  2. Verify external_id mapping is correct
  3. Check for duplicate records in WhiteLabelCRO
  4. Add additional query parameters to narrow results

Search Returns Empty When Record Exists

  1. Check for whitespace or special characters in search value
  2. Verify email case (should be case-insensitive but test both)
  3. Confirm external_id format matches exactly
  4. Check if record was deleted or status changed (for Find Lead)

Best Practices

Use External ID for Linking

When syncing with external systems, always use external_id:

{
  "external_id": "hubspot_{{ $json.id }}"
}

Store the external ID when creating records to enable reliable lookups later.

Prefer Email for Person Searches

Email is the most reliable criterion for finding clients/leads: - Less likely to have typos than phone - Unique per person in most systems - Case-insensitive matching

Implement Caching

For workflows that search frequently: 1. Cache search results in workflow data 2. Reduce redundant API calls 3. Respect rate limits

Test with Edge Cases

Test search logic with: - Non-existent records - Multiple matches - Special characters in email/phone - Null or empty search values

Platform Compatibility

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

All platforms use the same endpoints and return the same fields.