Lookups API¶

This document describes the Lookups API endpoints for retrieving dropdown data.

Overview¶

The Lookups API provides read-only endpoints that return lists of valid values for dropdown fields. These are commonly used in Zapier, Make, and n8n workflows to populate dropdown selections, but can also be used by custom integrations.

Base Path: /api/v1/integrations/lookups
Authentication: API Key with integrations:read scope
Rate Limit Bucket: read (200 requests per minute)

Why Lookups?¶

Lookups serve two purposes:

UI Convenience: Provide dropdown lists in integration builders (Zapier, Make, n8n)
Validation: Ensure IDs used in actions (Create Client, Update Status, etc.) are valid

Available Lookups¶

Endpoint	Returns	Use Case
`/lookups/clients?q=...`	Clients matching search	Select client for actions (typeahead)
`/lookups/employees`	Active employees	Assign employee to client/lead
`/lookups/affiliates`	Approved affiliates	Link client to referring affiliate
`/lookups/client-statuses`	Valid client statuses	Set or update client/lead status

Get Employees¶

Returns list of active employees for a company (excludes affiliates).

Method: GET
Path: /api/v1/integrations/lookups/employees
Scope Required: integrations:read

Request¶

No query parameters required. The API automatically scopes results to the authenticated company based on the API key.

curl -X GET https://api.whitelabelcro.com/api/v1/integrations/lookups/employees \
  -H "X-Api-Key: YOUR_API_KEY"

Response¶

200 OK

{
  "employees": [
    {
      "employee_id": 123,
      "full_name": "John Smith"
    },
    {
      "employee_id": 456,
      "full_name": "Jane Doe"
    }
  ],
  "count": 2
}

Response Fields¶

Field	Type	Description
`employees`	array	List of active employees
`employees[].employee_id`	integer	Employee's unique ID
`employees[].full_name`	string	Employee's display name
`count`	integer	Total number of employees returned

Filtering Rules¶

Only active employees (ActiveEmployee = 1)
Excludes affiliates (TeamRoleId ≠ 6)
Scoped to authenticated company
Ordered alphabetically by full_name

Use Cases¶

In Zapier/Make/n8n: - Populate "Assigned Employee" dropdowns in Create Client action - Populate "Changed By Employee" dropdowns in Update Status actions

In Custom Code: - Validate employee IDs before submitting Create/Update requests - Display employee selection UI in custom forms

Get Affiliates¶

Returns list of approved affiliates for a company.

Method: GET
Path: /api/v1/integrations/lookups/affiliates
Scope Required: integrations:read

Request¶

No query parameters required. The API automatically scopes results to the authenticated company.

curl -X GET https://api.whitelabelcro.com/api/v1/integrations/lookups/affiliates \
  -H "X-Api-Key: YOUR_API_KEY"

Response¶

200 OK

{
  "affiliates": [
    {
      "affiliate_id": 789,
      "full_name": "ABC Referral Partners"
    },
    {
      "affiliate_id": 890,
      "full_name": "XYZ Consulting"
    }
  ],
  "count": 2
}

Response Fields¶

Field	Type	Description
`affiliates`	array	List of approved affiliates
`affiliates[].affiliate_id`	integer	Affiliate's employee ID
`affiliates[].full_name`	string	Affiliate's display name
`count`	integer	Total number of affiliates returned

Filtering Rules¶

Only active affiliates (ActiveEmployee = 1)
Only approved affiliates (IsApprovedAffiliate = 1)
Only affiliate role (TeamRoleId = 6)
Scoped to authenticated company
Ordered alphabetically by full_name

Use Cases¶

In Zapier/Make/n8n: - Populate "Affiliate" dropdowns in Create Client/Lead actions - Populate "Affiliate" dropdowns in Update Client/Lead actions

In Custom Code: - Validate affiliate IDs before submitting requests - Display affiliate selection UI in referral forms

Get Client Statuses¶

Returns list of valid client/lead statuses for a company.

Method: GET
Path: /api/v1/integrations/lookups/client-statuses
Scope Required: integrations:read

Request¶

No query parameters required. The API automatically returns statuses relevant to the authenticated company.

curl -X GET https://api.whitelabelcro.com/api/v1/integrations/lookups/client-statuses \
  -H "X-Api-Key: YOUR_API_KEY"

Response¶

200 OK

{
  "statuses": [
    {
      "status_id": 1,
      "status_name": "Lead - New",
      "is_lead": true,
      "is_active": true,
      "color_code": "#3498db"
    },
    {
      "status_id": 5,
      "status_name": "Client - Active",
      "is_lead": false,
      "is_active": true,
      "color_code": "#2ecc71"
    },
    {
      "status_id": 8,
      "status_name": "Client - Completed",
      "is_lead": false,
      "is_active": true,
      "color_code": "#95a5a6"
    }
  ],
  "count": 3
}

Response Fields¶

Field	Type	Description
`statuses`	array	List of valid statuses
`statuses[].status_id`	integer	Status's unique ID
`statuses[].status_name`	string	Status display name
`statuses[].is_lead`	boolean	Whether this is a lead status (starts with "Lead")
`statuses[].is_active`	boolean	Whether status is currently active
`statuses[].color_code`	string	Hex color code for UI display
`count`	integer	Total number of statuses returned

Filtering Rules¶

Only valid statuses (isValidStatus = 1)
Only active statuses (isActiveStatus = 1)
Lead statuses: Returns global canonical statuses (CompanyId = 0)
Non-lead statuses: Returns both company-specific and global statuses
Ordered by: Company-specific first, then alphabetically by status_name

Lead vs Client Statuses¶

The system distinguishes between lead and client statuses:

Lead statuses start with "Lead -" (e.g., "Lead - New", "Lead - Contacted")
Client statuses start with "Client -" (e.g., "Client - Active", "Client - Paused")
Update Lead Status action only accepts lead statuses
Update Client Status action accepts any non-lead status

Use Cases¶

In Zapier/Make/n8n: - Populate "Status" dropdown in Create Client action - Populate "New Status" dropdown in Update Client Status action - Populate "New Status" dropdown in Update Lead Status action

In Custom Code: - Validate status IDs before submitting Update Status requests - Display status selection UI with color-coded options - Filter statuses by is_lead flag for lead vs client forms

Search Clients (Typeahead)¶

Returns a list of clients matching a search query, suitable for typeahead / dynamic dropdown fields. Designed for large datasets — results are searched server-side rather than loading the full client list.

Method: GET
Path: /api/v1/integrations/lookups/clients
Scope Required: integrations:read

Query Parameters¶

Parameter	Type	Required	Default	Description
`q`	string	Yes	—	Search query. If numeric, attempts exact ClientId match. Otherwise searches by name, email, phone, or external ID.
`limit`	integer	No	25	Maximum results to return (1–25).

Search Behavior¶

Query Type	Behavior
Numeric (e.g. `12345`)	Exact match on ClientId. Any length allowed.
Non-numeric, 2+ chars	Searches: name (contains), email (contains), phone (digits ends-with), external_id (starts-with).
Non-numeric, < 2 chars	Returns 400 error.
Empty / missing	Returns empty result set.

Request¶

curl -X GET "https://api.whitelabelcro.com/api/v1/integrations/lookups/clients?q=john&limit=10" \
  -H "X-Api-Key: YOUR_API_KEY"

Response¶

200 OK

{
  "clients": [
    {
      "id": 12345,
      "name": "John Doe — john.doe@example.com"
    },
    {
      "id": 12389,
      "name": "Johnny Smith — 5551234567"
    }
  ],
  "count": 2
}

Response Fields¶

Field	Type	Description
`clients`	array	List of matching clients
`clients[].id`	integer	Client's unique ID
`clients[].name`	string	Human-friendly label (e.g., "Full Name — email" or "Full Name — phone")
`count`	integer	Total number of clients returned

Use Cases¶

In Zapier: - Powers the client_id dynamic dropdown with typeahead search - Users can select a client from search results or map an ID from a previous step

In Custom Code: - Implement client search/autocomplete UI - Validate client IDs before submitting action requests

Error Responses¶

All lookup endpoints use standard Integration API error responses.

401 Unauthorized¶

API key missing, invalid, or lacks required scope.

{
  "error_code": "unauthorized",
  "message": "Invalid or missing API key"
}

Solution: Check that X-Api-Key header is present and has integrations:read scope.

429 Too Many Requests¶

Rate limit exceeded (200 requests per minute for read operations).

{
  "error_code": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Retry after 30 seconds.",
  "retry_after_seconds": 30
}

Solution: Implement exponential backoff and respect the retry_after_seconds value.

500 Internal Server Error¶

Unexpected server error.

{
  "error_code": "internal_error",
  "message": "An unexpected error occurred"
}

Solution: Retry with exponential backoff. If error persists, contact support.

Best Practices¶

Caching¶

Lookup data changes infrequently. Consider caching responses:

Employees/Affiliates: Cache for 5-15 minutes
Client Statuses: Cache for 1 hour or more

This reduces API calls and improves performance.

When to Call Lookups¶

Do: - Call once when user opens a form/dropdown - Refresh on user request (e.g., "Reload" button) - Cache results for session duration

Don't: - Call on every keystroke in search fields - Call repeatedly for the same action execution - Call during automated workflows (use raw IDs instead)

Using IDs in Actions¶

Lookups provide IDs for dropdown UIs, but actions accept raw IDs directly:

// You can pass the ID directly without calling lookups first
{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "employee_id": 123,  // No lookup required
  "status_id": 5       // No lookup required
}

Lookups are for convenience, not requirements. If you already have valid IDs from triggers or databases, use them directly.

Integration Examples¶

Zapier Dynamic Dropdowns¶

The Zapier integration uses these lookup endpoints to populate dynamic dropdowns for the corresponding fields:

employee_id → Uses /lookups/employees
affiliate_id → Uses /lookups/affiliates
new_status_id → Uses /lookups/client-statuses

Each field is a single dynamic dropdown. Users can either select a value from the dropdown or map an ID from a previous Zap step — no separate "Or Select …" fields are used.

n8n HTTP Request¶

{
  "method": "GET",
  "url": "https://api.whitelabelcro.com/api/v1/integrations/lookups/employees",
  "authentication": "predefinedCredentialType",
  "nodeCredentialType": "whitelabelcroApi",
  "options": {}
}

Map the response employees array to a dropdown in a Set node.

Make HTTP Module¶

Add HTTP module to scenario
Set Method: GET
Set URL: https://api.whitelabelcro.com/api/v1/integrations/lookups/employees
Add Header: X-Api-Key = (from connection)
Parse JSON response in next module

Authentication - API key setup and scopes
Error Handling - HTTP status codes and error responses
Rate Limits - Rate limiting details
Zapier Actions - Using lookups in Zapier
Make Actions - Using lookups in Make
n8n Actions - Using lookups in n8n

Lookups API¶

Overview¶

Why Lookups?¶

Available Lookups¶

Get Employees¶

Request¶

Response¶

Response Fields¶

Filtering Rules¶

Use Cases¶

Get Affiliates¶

Request¶

Response¶

Response Fields¶

Filtering Rules¶

Use Cases¶

Get Client Statuses¶

Request¶

Response¶

Response Fields¶

Filtering Rules¶

Lead vs Client Statuses¶

Use Cases¶

Search Clients (Typeahead)¶

Query Parameters¶

Search Behavior¶

Request¶

Response¶

Response Fields¶

Use Cases¶

Error Responses¶

401 Unauthorized¶

429 Too Many Requests¶

500 Internal Server Error¶

Best Practices¶

Caching¶

When to Call Lookups¶

Using IDs in Actions¶

Integration Examples¶

Zapier Dynamic Dropdowns¶

n8n HTTP Request¶

Make HTTP Module¶

Related Documentation¶