Field Mapping

Field mapping defines how columns from your model map to fields in your destination. It is the bridge between your warehouse data and the destination’s schema, controlling exactly which data goes where.

How Field Mapping Works

When creating or editing a sync, the field mapping step presents two lists side by side:

• Source columns — The columns from your model (e.g., email, first_name, lifetime_value)
• Destination fields — The fields available in the destination object (e.g., Email, FirstName, LTV__c)

You connect source columns to destination fields to create mappings. During each sync run, SignalSmith reads the value from the source column and writes it to the mapped destination field.

Model Columns              Destination Fields
┌──────────────┐           ┌──────────────────┐
│ email        │──────────▶│ Email            │
│ first_name   │──────────▶│ FirstName        │
│ last_name    │──────────▶│ LastName         │
│ phone        │──────────▶│ Phone            │
│ ltv          │──────────▶│ Lifetime_Value__c│
│ segment      │    ╳      │ (not mapped)     │
│ created_at   │    ╳      │ (not mapped)     │
└──────────────┘           └──────────────────┘

Unmapped source columns are ignored — their data is not sent to the destination. Unmapped destination fields retain their current values in the destination (they are not cleared).

Identifier Mapping

At least one model column marked as an identifier must be mapped to the destination’s primary identifier field. This mapping tells SignalSmith how to match source records to destination records.

How Identifier Matching Works

When a sync runs in upsert or mirror mode:

1. SignalSmith reads the identifier value from the source column (e.g., email = "john@example.com")
2. It looks up the matching record in the destination using the mapped identifier field (e.g., Email = "john@example.com")
3. If a match is found, the record is updated with the new attribute values
4. If no match is found, a new record is created

Common Identifier Mappings

External ID Mapping

Many CRM destinations support external ID fields that let you match records by your own identifier (rather than email):

Model: customer_id  →  Salesforce: External_ID__c

This is useful when:

• Multiple records may share the same email
• You want deterministic matching based on your own IDs
• The destination supports external ID upsert operations

Required Fields

Some destinations require certain fields to be mapped for record creation to succeed. Required fields are marked with an asterisk (*) in the mapping interface.

Common required fields by destination:

If a required field is not mapped, the sync will fail during validation when saving.

Default Destination Fields

Some destinations have pre-configured default fields that are automatically available for mapping. These are standard fields defined by the destination platform:

Custom fields (e.g., Salesforce custom fields ending in __c) are also available if they exist in the destination.

Data Type Compatibility

When mapping fields, the data types of the source column and destination field should be compatible:

SignalSmith performs automatic type conversion where possible:

• Numbers to text: 42 becomes "42"
• Booleans to text: true becomes "true"
• Dates to text: 2025-01-15 becomes "2025-01-15"
• Text to numbers: "42" becomes 42 (fails if not a valid number)

If a type conversion fails for a specific row, that row is recorded as an error in the sync run results.

Mapping Strategies

Full Mapping

Map every model column to a destination field. Best when:

• You want to sync all available data
• The destination fields exist for every column
• You need complete data in the destination

Selective Mapping

Map only an access filter of model columns. Best when:

• Not all model columns are relevant to the destination
• You want to minimize API calls (fewer fields = smaller payloads)
• Some columns contain sensitive data that shouldn’t be sent to the destination

Identifier-Only Mapping

Map only identifier columns (no attributes). Useful for:

• Audience syncs where you just need to match records (e.g., Google Ads Customer Match)
• Building destination-side segments without updating record data

Mapping Interface Features

Auto-Mapping

The mapping interface offers an Auto-Map feature that automatically maps source columns to destination fields with matching names. It uses fuzzy matching to handle common naming differences:

Auto-mapping is a starting point — review and adjust the suggestions before saving.

Search and Filter

For destinations with many fields (e.g., Salesforce objects with 100+ fields):

• Use the search bar to filter destination fields by name
• Filter by field type (text, number, date, etc.)
• Toggle between showing all fields or only unmapped fields

Mapping Validation

Before saving, the mapping interface validates:

• At least one identifier is mapped (for upsert and mirror modes)
• All required destination fields are mapped
• Data types are compatible (warnings for potential conversion issues)
• No duplicate mappings (one source column to multiple destination fields is not allowed)

Example Mappings

Salesforce Contact Sync

{
  "field_mappings": [
    {"source": "email", "destination": "Email", "is_identifier": true},
    {"source": "first_name", "destination": "FirstName"},
    {"source": "last_name", "destination": "LastName"},
    {"source": "phone", "destination": "Phone"},
    {"source": "title", "destination": "Title"},
    {"source": "company", "destination": "Account.Name"},
    {"source": "lifetime_value", "destination": "LTV__c"},
    {"source": "segment", "destination": "Segment__c"}
  ]
}

HubSpot Contact Sync

{
  "field_mappings": [
    {"source": "email", "destination": "email", "is_identifier": true},
    {"source": "first_name", "destination": "firstname"},
    {"source": "last_name", "destination": "lastname"},
    {"source": "phone", "destination": "phone"},
    {"source": "company_name", "destination": "company"},
    {"source": "lifecycle_stage", "destination": "lifecyclestage"}
  ]
}

Google Ads Customer Match

{
  "field_mappings": [
    {"source": "email", "destination": "email", "is_identifier": true},
    {"source": "phone", "destination": "phone"},
    {"source": "first_name", "destination": "first_name"},
    {"source": "last_name", "destination": "last_name"},
    {"source": "country", "destination": "country_code"},
    {"source": "zip", "destination": "postal_code"}
  ]
}

Next Steps

• Create a sync with field mapping
• Set a schedule for your sync
• Monitor sync runs to verify mappings work correctly
• Troubleshoot errors from mapping issues