Skip to content

Zapier Trigger Mapping

This document maps WhiteLabelCRO Integration API events to their Zapier trigger representations.

Event to Trigger Mapping

The Integration API emits 10 event types. In Zapier, these appear as triggers with user-friendly names.

API Event Type Zapier Trigger Name Description
client.created New Client Created When a new client is enrolled
client.status_changed Client Status Changed When client moves to different stage
lead.created New Lead Created When a new lead is captured
invoice.created New Invoice Created When invoice is generated
invoice.status_changed Invoice Status Changed When invoice payment status changes
payment.succeeded Payment Succeeded When payment processes successfully
payment.failed Payment Failed When payment is declined
affiliate.created New Affiliate Created When referral partner is added
document.uploaded Document Uploaded When file is attached to record
agreement.signed Agreement Signed When e-signature is completed

Payload Normalization

Event Envelope Structure

The Integration API returns events in this format:

{
  "id": 12345,
  "type": "client.created",
  "createdUtc": "2026-01-28T10:30:00Z",
  "companyId": 92,
  "payload": {
    "client_id": 5678,
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com"
  },
  "metadata": {
    "source": "web_portal",
    "user_id": 42
  }
}

Zapier Flattening

Zapier flattens nested objects using double underscore notation:

API Path Zapier Field Name
id id
type type
createdUtc createdUtc or created_utc
payload.client_id payload__client_id
payload.first_name payload__first_name
metadata.source metadata__source

Why Flattening?

Zapier's field picker requires flat key-value pairs. Nested JSON objects are converted to dotted keys for easy mapping in subsequent Zap steps.

Field Naming Conventions

Standard Fields (All Events)

Present in every event:

  • id - Event ID (long integer)
  • type - Event type string (e.g., client.created)
  • createdUtc - ISO 8601 timestamp
  • companyId - Organization identifier

Payload Fields

Payload structure varies by event type. See the Event Catalog (/03-events/event-catalog.md) for event-specific fields.

Common patterns: - client_id - Client/lead identifier - employee_id - Assigned staff member - affiliate_id - Referring affiliate - status, previous_status, new_status - Status fields - Date fields: created_date, changed_date, signed_date (ISO 8601 strings)

Metadata Fields

Optional context provided with some events:

  • metadata__source - Origin of the event (e.g., web_portal, api, admin)
  • metadata__user_id - User who triggered the action
  • Additional fields vary by event type

Nested Object Handling

Arrays

If the payload contains arrays, Zapier flattens them with numeric indices:

{
  "payload": {
    "tags": ["vip", "high_priority"]
  }
}

Becomes: - payload__tags__0 = "vip" - payload__tags__1 = "high_priority"

Deep Nesting

Deeply nested objects use multiple underscores:

{
  "payload": {
    "address": {
      "street": "123 Main St",
      "city": "Springfield"
    }
  }
}

Becomes: - payload__address__street = "123 Main St" - payload__address__city = "Springfield"

JSON Debug Fields

In addition to flattened fields, Zapier exposes raw JSON for advanced use cases:

  • payload_json - Full payload as JSON string
  • metadata_json - Full metadata as JSON string

Use these fields when: - You need to parse complex nested data in Code steps - You want to pass the entire payload to another API - Flattened fields are insufficient for your use case

Example usage in Code step: 

const payload = JSON.parse(inputData.payload_json);
// Access nested data programmatically

Sample Data

Sample Endpoint

During Zap setup, Zapier calls: 

GET /api/v1/webhooks/subscriptions/{id}/sample?eventType={type}

This returns realistic sample data for field mapping without waiting for a real event.

Sample Structure

Samples match the event envelope structure but use placeholder data: - Realistic field names - Plausible values (e.g., "John Doe", "john@example.com") - Complete field set (all optional fields populated)

Using Samples in Zapier

  1. When you configure a trigger, Zapier loads sample data automatically
  2. Use the sample to map fields to subsequent actions
  3. Sample data appears in the field picker with gray "sample" labels
  4. Real events will replace sample data when your Zap runs

Field Type Handling

Date/Time Fields

  • API returns: ISO 8601 strings (e.g., 2026-01-28T10:30:00Z)
  • Zapier interprets: As datetime objects
  • Use Zapier's Formatter to convert to specific formats if needed

Boolean Fields

  • API returns: true or false (JSON boolean)
  • Zapier interprets: As boolean for conditional logic
  • May appear as "true" / "false" strings in some contexts

Numeric Fields

  • IDs: Always integers (e.g., client_id: 5678)
  • Amounts: May be decimal (e.g., amount: 99.99)
  • Zapier preserves numeric types for math operations

Null/Missing Fields

  • If a field is null or absent, Zapier shows "(empty)"
  • Use Zapier's "Filter" or "Formatter" steps to handle missing values
  • Optional fields may not appear in every event

Version Differences

Current Implementation

The WhiteLabelCRO.com Zapier app uses API v1 (/api/v1/...). All triggers, actions, and searches map to v1 endpoints.

If a v2 API is introduced in the future, migration guidance will be provided in advance.

Backward Compatibility

Event payload structures are stable within v1. New fields may be added (non-breaking), but existing fields will not change type or be removed.