Skip to main content

Profile Mappings

Profile mappings define how event metadata fields are mapped to standardized profile properties for profile scoring. This allows you to score leads based on demographic and firmographic data (company size, industry, role, etc.) rather than just behavioral engagement.

When to Use This​

  • Map event metadata to profile fields: Convert incoming event metadata (like company_size, industry, job_title) to standardized profile properties
  • Enable profile scoring: Profile scoring rules require mapped fields to calculate fit scores
  • Normalize data from multiple sources: Map different field names from various integrations to consistent profile properties

GET /profile-mappings​

List all profile field mappings for the active Organizational Unit.

Authentication​

Required: Yes (HTTP Basic Auth or Bearer token)

Request​

curl -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Accept: application/json" \
  "https://your-api.example.com/profile-mappings"

Response​

Status: 200 OK

{
  "profile_mappings": [
    {
      "id": "mapping-123",
      "metadata_key": "company_size",
      "profile_field": "company_employee_count",
      "created_at": "2025-01-15T10:30:00Z"
    },
    {
      "id": "mapping-456",
      "metadata_key": "industry",
      "profile_field": "company_industry",
      "created_at": "2025-01-15T10:31:00Z"
    }
  ]
}

POST /profile-mappings​

Create a new profile field mapping.

Request​

curl -X POST https://your-api.example.com/profile-mappings \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata_key": "job_title",
    "profile_field": "contact_job_title"
  }'

Request Body:

FieldRequiredTypeDescription
metadata_keyYesstringThe event metadata field name to map
profile_fieldYesstringThe standardized profile property to map to

Response​

Status: 201 Created

{
  "id": "mapping-789",
  "metadata_key": "job_title",
  "profile_field": "contact_job_title",
  "created_at": "2025-01-15T10:35:00Z"
}

Common Profile Fields​

Profile FieldDescriptionExample Values
company_employee_countNumber of employees"1-10", "11-50", "51-200", "201-500", "501+"
company_industryIndustry vertical"Technology", "Healthcare", "Finance"
company_revenueAnnual revenue"<1M", "1M-10M", "10M-50M", "50M+"
contact_job_titleJob title/role"CEO", "VP Sales", "Manager"
contact_senioritySeniority level"C-Level", "VP", "Director", "Manager", "IC"
company_locationGeographic location"US", "EU", "APAC"

Common Errors​

Status CodeErrorSolution
400Bad RequestVerify metadata_key and profile_field are provided
401UnauthorizedCheck your API credentials
409ConflictMapping for this metadata_key already exists

Important Notes​

Profile Scoring Workflow​

  1. Send events with metadata: Include profile data in event metadata
{
  "alias_kind": "email",
  "alias": "jane@example.com",
  "event_type": "form_submit",
  "metadata": {
    "company_size": "51-200",
    "industry": "Technology",
    "job_title": "VP Sales"
  }
}
  1. Create profile mappings: Map metadata keys to profile fields
POST /profile-mappings
{"metadata_key": "company_size", "profile_field": "company_employee_count"}
  1. Create profile scoring rules: Score based on mapped fields
POST /profile-scoring/rulesets/{id}/rules
{"profile_field": "company_employee_count", "value": "51-200", "weight": 20}
  1. Backfill existing leads (optional): Apply mappings to leads that were created before your mappings were configured
POST /backfill/profile-mappings

POST /backfill/profile-mappings​

Apply your current profile mappings to all existing leads in the active Organizational Unit. This is useful when you create or update mappings and want to retroactively populate profile metadata for leads that already exist.

When to use this:

  • You just configured profile mappings and have existing leads that need metadata populated
  • You updated a mapping and want the changes applied to all leads
  • You imported leads before setting up profile mappings

You can also run this from the UI: navigate to Configure > Mapping > Profile and click Backfill Profile Metadata.

Authentication​

Required: Yes (HTTP Basic Auth or Bearer token)

Request​

curl -X POST https://your-api.example.com/backfill/profile-mappings \
  -u "CLIENT_ID:CLIENT_SECRET"

No request body is required. The backfill uses your currently configured profile mappings.

Response​

Status: 200 OK

{
  "leads_processed": 1250,
  "leads_updated": 843
}
FieldTypeDescription
leads_processedintegerTotal number of leads scanned
leads_updatedintegerNumber of leads that had metadata updated

Important Notes​

  • The backfill processes leads in batches, so large datasets are handled efficiently
  • Each mapping's update behavior setting is respected during backfill (e.g., "always overwrite" vs. "only if empty")
  • Running the backfill multiple times is safe -- leads that already have the correct metadata are skipped based on your update behavior settings

See Also​