Skip to main content

​
Field Mappings

Each CRM provider stores data differently — HubSpot calls it firstname, Zoho uses First_Name, Pipedrive uses first_name. The RouteMCP API normalizes all of these into a unified schema so you always get consistent field names regardless of the provider.

​
How It Works

When you call GET /contact?provider=hubspot, the API:
  1. Fetches raw data from HubSpot
  2. Applies field mappings to transform HubSpot fields to the unified schema
  3. Returns the data in the unified format
HubSpot: { "firstname": "Jane", "lastname": "Doe" }
    ↓ field mapping
Unified: { "firstName": "Jane", "lastName": "Doe" }

​
Viewing Mappings

Retrieve the active field mappings for a provider: 
curl http://localhost:5001/api/v1/field-mappings?provider=hubspot&resource=contact \
  -H "Authorization: Bearer sk_live_your_api_key"
Response: 
{
  "success": true,
  "data": [
    {
      "standardKey": "contacts:v1:firstName",
      "unifiedField": "firstName",
      "providerField": "firstname",
      "direction": "bidirectional",
      "transform": null
    },
    {
      "standardKey": "contacts:v1:email",
      "unifiedField": "email",
      "providerField": "email",
      "direction": "bidirectional",
      "transform": null
    },
    {
      "standardKey": "contacts:v1:company",
      "unifiedField": "company",
      "providerField": "company",
      "direction": "read",
      "transform": null
    }
  ]
}

​
Unified Schema

​
Contacts

Unified FieldTypeDescription
idstringProvider-specific record ID
firstNamestringFirst name
lastNamestringLast name
emailstringPrimary email address
phonestringPrimary phone number
companystringCompany/organization name
titlestringJob title
addressobjectMailing address
lifecycleStagestringCustomer lifecycle stage

​
Leads

Unified FieldTypeDescription
idstringProvider-specific record ID
firstNamestringFirst name
lastNamestringLast name
emailstringEmail address
phonestringPhone number
companystringCompany name
sourcestringLead source
statusstringLead status
valuenumberEstimated lead value
currencystringCurrency code (ISO 4217)

​
Deals

Unified FieldTypeDescription
idstringProvider-specific record ID
namestringDeal/opportunity name
valuenumberDeal value
currencystringCurrency code
stagestringPipeline stage
probabilitynumberWin probability (0-100)
contactIdstringAssociated contact ID
companyIdstringAssociated company ID
closeDatestringExpected close date (ISO 8601)

​
Meetings

Unified FieldTypeDescription
idstringProvider-specific record ID
titlestringMeeting title
startTimestringStart time (ISO 8601)
endTimestringEnd time (ISO 8601)
attendeesarrayList of attendee emails
locationstringMeeting location
meetingUrlstringVideo conference URL
descriptionstringMeeting notes/description

​
Mapping Direction

Each mapping has a direction that determines how data flows:
DirectionRead (GET)Write (POST/PUT/PATCH)
bidirectionalProvider → UnifiedUnified → Provider
readProvider → UnifiedIgnored
writeIgnoredUnified → Provider

​
Custom Overrides

Organization admins can customize field mappings from the dashboard — changing which provider field maps to which unified field, adding custom mappings, or disabling specific fields. These overrides are automatically applied when you call the API. Use the GET /field-mappings endpoint to see the effective mappings (with your org’s overrides applied).