Field Mappings - RouteMCP API

Each provider stores data differently — HubSpot calls it firstname, Zoho uses First_Name, Pipedrive uses first_name. On the accounting side, QBO calls an invoice number DocNumber while another provider uses invoiceNumber. 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 /crm/contact?provider=hubspot (or GET /accounting/invoice?provider=quickbooks-online), the API:

Fetches raw data from the provider
Applies field mappings to transform provider fields to the unified schema
Returns the data in the unified format

HubSpot: { "firstname": "Jane", "lastname": "Doe" }
    ↓ field mapping
Unified: { "first_name": "Jane", "last_name": "Doe" }

Viewing Mappings

Retrieve the active field mappings for a provider:

curl https://api.routemcp.io/api/v1/field-mappings?provider=hubspot&resource=contact \
  -H "Authorization: Bearer sk_live_your_api_key"

Response:

{
  "success": true,
  "data": [
    {
      "standardKey": "contacts:v1:first_name",
      "unifiedField": "first_name",
      "providerField": "firstname",
      "direction": "bidirectional",
      "transform": null
    },
    {
      "standardKey": "contacts:v1:email_addresses",
      "unifiedField": "email_addresses",
      "providerField": "email",
      "direction": "bidirectional",
      "transform": null
    },
    {
      "standardKey": "contacts:v1:account",
      "unifiedField": "account",
      "providerField": "company",
      "direction": "read",
      "transform": null
    }
  ]
}

Provider-specific fields via `integration_params`

The unified schema covers the canonical surface — fields that map cleanly across every supported provider. But many providers expose extra fields that only matter in their own ecosystem (QBO’s Type discriminator on Item creates, Zoho’s ignore_auto_number_generation query flag, Zoho’s billing_type + rate on Project, etc.). Those don’t belong in the canonical schema, but you still need a way to set them. integration_params is the escape hatch: a free-form object on any write body that merges directly onto the provider request alongside the field-mapped fields. Provider-specific keys win over any canonically-derived field with the same name.

# Zoho — supply your own invoice number even though the org has auto-numbering on
curl -X POST "https://api.routemcp.io/api/v1/accounting/invoice?provider=zoho-books" \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -H "X-End-User-Id: user-123" \
  -d '{
    "type": "ACCOUNTS_RECEIVABLE",
    "number": "INV-2026-0001",
    "contact": "urn:zoho-books:contact:3827299000000037005",
    "line_items": [{ "description": "Consulting", "quantity": 1, "unit_price": 500 }],
    "integration_params": { "ignore_auto_number_generation": true }
  }'

# QBO — create a Service item (canonical `type` doesn't carry through, so route Type via integration_params)
curl -X POST "https://api.routemcp.io/api/v1/accounting/item?provider=quickbooks-online" \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -H "X-End-User-Id: user-123" \
  -d '{
    "name": "Consulting",
    "unit_price": 100,
    "sales_account": "urn:qbo:account:48",
    "integration_params": { "Type": "Service" }
  }'

Some keys are URL-bound rather than body-bound (Zoho’s ignore_auto_number_generation is a query flag). The adapter lifts those out of integration_params and onto the URL automatically — you pass them the same way regardless. URN-shaped values inside integration_params are stripped down to bare provider ids before the outbound request, so it’s safe to round-trip URNs from list/get responses. See each integration’s provider page for the list of supported integration_params keys.

CRM Unified Schema

Contacts

Unified Field	Type	Description
`id`	string	Provider-specific record ID
`first_name`	string	First name
`last_name`	string	Last name
`account`	string	Associated company/account ID (provider-native)
`owner`	string	Provider-native ID of the record owner
`addresses`	array	List of addresses (`street_1`, `street_2`, `city`, `state`, `postal_code`, `country`, `address_type`)
`email_addresses`	array	List of email addresses (`email_address`, `email_address_type`)
`phone_numbers`	array	List of phone numbers (`phone_number`, `phone_number_type`)

Leads

Unified Field	Type	Description
`id`	string	Provider-specific record ID
`first_name`	string	First name
`last_name`	string	Last name
`title`	string	Lead title / job title
`company`	string	Company name
`lead_source`	string	Lead source
`status`	string	Lead status: `OPEN`, `CLOSED`, `UNQUALIFIED`, `QUALIFIED`
`owner`	string	Provider-native owner ID
`addresses`	array	List of addresses
`email_addresses`	array	List of email addresses
`phone_numbers`	array	List of phone numbers
`converted_date`	string	ISO 8601 date when lead was converted
`converted_contact`	string	Provider-native ID of the converted contact
`converted_account`	string	Provider-native ID of the converted account

Deals

Unified Field	Type	Description
`id`	string	Provider-specific record ID
`name`	string	Deal/opportunity name
`amount`	number	Deal value
`currency`	string	Currency code
`stage`	string	Pipeline stage
`pipeline`	string	Pipeline name or ID
`status`	string	Deal status: `open`, `won`, `lost`
`probability`	number	Win probability (0-100)
`close_date`	string	Expected close date (ISO 8601)
`description`	string	Deal description
`contact`	string	Associated contact ID (provider-native)
`account`	string	Associated company/account ID (provider-native)
`owner`	string	Provider-native owner ID

Meetings

Unified Field	Type	Description
`id`	string	Provider-specific record ID
`title`	string	Meeting title
`description`	string	Meeting notes/description
`start_time`	string	Start time (ISO 8601)
`end_time`	string	End time (ISO 8601)
`location`	string	Meeting location
`meeting_url`	string	Video conference URL
`status`	string	Meeting status: `scheduled`, `completed`, `cancelled`, `rescheduled`
`attendees`	array	List of attendees (`email`, `name`, `status`)
`contacts`	array	Associated contact IDs (provider-native)
`organizer`	string	Organizer name or email
`owner`	string	Provider-native owner ID

Companies

Unified Field	Type	Description
`id`	string	Provider-specific record ID
`name`	string	Company name
`domain`	string	Company website domain
`industry`	string	Industry vertical
`description`	string	Company description
`number_of_employees`	number	Employee count
`phone`	string	Main phone number
`website`	string	Company website URL
`addresses`	array	List of addresses (`street_1`, `street_2`, `city`, `state`, `postal_code`, `country`)
`annual_revenue`	number	Annual revenue
`owner`	string	Provider-native owner ID

Notes

Unified Field	Type	Description
`id`	string	Provider-specific record ID
`content`	string	Note body text
`contact`	string	Associated contact ID (provider-native)
`account`	string	Associated company/account ID (provider-native)
`opportunity`	string	Associated deal/opportunity ID (provider-native)
`owner`	string	Provider-native owner ID

Tasks

Unified Field	Type	Description
`id`	string	Provider-specific record ID
`subject`	string	Task subject line
`content`	string	Task description
`status`	string	Status: `OPEN`, `CLOSED`
`due_date`	string	Due date (ISO 8601)
`completed_date`	string	Completion date (ISO 8601, read-only)
`contact`	string	Associated contact ID (provider-native)
`account`	string	Associated company/account ID (provider-native)
`opportunity`	string	Associated deal/opportunity ID (provider-native)
`owner`	string	Provider-native owner ID

Activities

Unified Field	Type	Description
`id`	string	Provider-specific record ID
`type`	string	Activity type: `call`, `email`, `other`
`subject`	string	Activity subject
`body`	string	Activity description
`status`	string	Status: `scheduled`, `completed`, `cancelled`
`start_time`	string	Start time (ISO 8601)
`end_time`	string	End time (ISO 8601)
`duration`	number	Duration in minutes
`direction`	string	`inbound` or `outbound` (for calls)
`contact`	string	Associated contact ID (provider-native)
`account`	string	Associated company/account ID (provider-native)
`opportunity`	string	Associated deal/opportunity ID (provider-native)
`lead`	string	Associated lead ID (provider-native)
`owner`	string	Provider-native owner ID

Pipelines (read-only)

Unified Field	Type	Description
`id`	string	Provider-specific pipeline ID
`name`	string	Pipeline name
`is_active`	boolean	Whether pipeline is active
`display_order`	number	Display sort order
`stages`	array	List of pipeline stages (`id`, `name`, `display_order`, `probability`, `is_closed`)

Owners (read-only)

Unified Field	Type	Description
`id`	string	Provider-specific owner ID
`first_name`	string	First name
`last_name`	string	Last name
`name`	string	Full name
`email`	string	Email address
`is_active`	boolean	Whether owner is active

Appointments

Unified Field	Type	Description
`id`	string	Provider-specific record ID
`title`	string	Appointment name or meeting subject
`description`	string	Notes or additional information
`start_time`	string (ISO 8601)	Scheduled start date and time
`end_time`	string (ISO 8601)	Scheduled end date and time
`duration`	number	Duration in minutes
`location`	string	Physical address or location description
`meeting_url`	string	Video conference link (Zoom, Google Meet, etc.)
`meeting_location_type`	string	Location type: `custom`, `zoom`, `google_meet`, `microsoft_teams`, `phone`, `in_person`
`status`	string	Appointment status: `scheduled`, `confirmed`, `cancelled`, `completed`, `no_show`
`calendar_id`	string	Scheduling page or calendar ID
`calendar_name`	string	Human-readable calendar/scheduling page name
`contact`	string	Associated contact ID (provider-native)
`contact_name`	string	Contact display name (enriched)
`contact_email`	string	Contact email (enriched)
`owner`	string	Provider-native owner ID
`owner_name`	string	Owner display name (enriched)
`owner_email`	string	Owner email (enriched)
`is_recurring`	boolean	Whether the appointment recurs
`recurrence_rule`	string	RRULE (RFC 5545) for recurring appointments
`remote_created_at`	string (ISO 8601)	Record creation timestamp
`remote_updated_at`	string (ISO 8601)	Last modification timestamp
`remote_id`	string	Provider-native record ID

Note: The appointment resource also has a special GET /crm/appointment/slots endpoint for fetching available time slots from scheduling pages. See the API Reference for details.

Accounting Unified Schema

Every accounting resource carries a standard envelope (id, remote_id, created_at, modified_at, remote_was_deleted) plus its resource-specific fields. Embedded sub-types like Address and Phone Number drop the envelope when nested.

Invoice

Unified Field	Type	Description
`type`	string	`ACCOUNTS_RECEIVABLE` (invoice) or `ACCOUNTS_PAYABLE` (bill)
`contact`	string	UUID of customer (AR) or vendor (AP)
`number`	string	Invoice number (e.g. `INV-2026-0001`)
`issue_date`	string	ISO date the invoice was issued
`due_date`	string	ISO date payment is due
`paid_on_date`	string	ISO date the invoice was paid
`memo`	string	Free-form memo
`status`	string	`PAID`, `DRAFT`, `SUBMITTED`, `PARTIALLY_PAID`, `OPEN`, `VOID`
`currency`	string	ISO 4217 currency code
`total_amount`	number	Total including tax
`sub_total`	number	Subtotal before tax
`total_tax_amount`	number	Tax portion
`balance`	number	Outstanding balance
`line_items`	array	Invoice lines (`description`, `unit_price`, `quantity`, `account`, `item`, `tax_rate`, etc.)
`payment_term`	string	UUID of associated payment term
`tracking_categories`	array	UUIDs of tracking categories
`accounting_period`	string	UUID of accounting period
`inclusive_of_tax`	boolean	Whether `line_items` amounts include tax
`integration_params`	object	Provider-specific passthrough fields

Contact (Accounting)

Unified Field	Type	Description
`name`	string	Display name
`is_customer`	boolean	True for customer (AR side)
`is_supplier`	boolean	True for supplier / vendor (AP side)
`email_address`	string	Primary email
`tax_number`	string	Tax ID / EIN / VAT number
`status`	string	`ACTIVE` or `ARCHIVED`
`currency`	string	Default currency for transactions
`addresses`	array	List of addresses (billing, shipping)
`phone_numbers`	array	List of phone numbers

Account

Unified Field	Type	Description
`name`	string	Account display name
`description`	string	Account description
`classification`	string	`ASSET`, `EQUITY`, `EXPENSE`, `LIABILITY`, `REVENUE`
`account_type`	string	Canonical type: `BANK`, `CREDIT_CARD`, `ACCOUNTS_PAYABLE`, `ACCOUNTS_RECEIVABLE`, `FIXED_ASSET`, `COST_OF_GOODS_SOLD`, etc.
`status`	string	`ACTIVE`, `PENDING`, `INACTIVE`
`current_balance`	number	Current account balance
`currency`	string	Account currency
`account_number`	string	Account number / code
`parent_account`	string	UUID of parent (for sub-accounts)

Payment

Unified Field	Type	Description
`transaction_date`	string	ISO date the payment was made
`contact`	string	UUID of payer (AR) or payee (AP)
`account`	string	UUID of the deposit-to / draw-from account
`payment_method`	string	UUID of payment method
`total_amount`	number	Payment amount
`type`	string	`ACCOUNTS_RECEIVABLE` or `ACCOUNTS_PAYABLE`
`currency`	string	Payment currency
`applied_to_lines`	array	Lines linking the payment to invoices / credit notes (`applied_amount`, `applied_date`, `related_object_id`, `related_object_type`)

Item

Unified Field	Type	Description
`name`	string	Item name
`type`	string	`INVENTORY`, `NON_INVENTORY`, `SERVICE`, `UNKNOWN`
`status`	string	`ACTIVE` or `ARCHIVED`
`unit_price`	number	Sales unit price
`purchase_price`	number	Default purchase cost
`sales_account`	string	UUID of income account credited on sale
`purchase_account`	string	UUID of expense account debited on purchase
`sales_tax_rate`	string	UUID of default sales tax rate
`purchase_tax_rate`	string	UUID of default purchase tax rate

Journal Entry

Unified Field	Type	Description
`transaction_date`	string	ISO date of the entry
`journal_number`	string	Reference number
`memo`	string	Free-form memo
`currency`	string	Entry currency
`posting_status`	string	`POSTED` or `UNPOSTED`
`lines`	array	Debit + credit legs (`account`, `net_amount` — positive = debit, negative = credit, `description`, `tracking_categories`, `contact`, `project`)

Expense

Unified Field	Type	Description
`transaction_date`	string	ISO date the expense was incurred
`account`	string	UUID of bank / credit-card account that paid
`contact`	string	UUID of vendor (if applicable)
`total_amount`	number	Total including tax
`sub_total`	number	Subtotal before tax
`total_tax_amount`	number	Tax portion
`currency`	string	Expense currency
`memo`	string	Description
`lines`	array	Expense lines (`account`, `net_amount`, `description`, etc.)

Purchase Order

Unified Field	Type	Description
`purchase_order_number`	string	PO number (e.g. `PO-2026-0001`)
`issue_date`	string	ISO date the PO was issued
`delivery_date`	string	Expected delivery date
`delivery_address`	string	Shipping address (free-text)
`vendor`	string	UUID of the vendor
`total_amount`	number	Total including tax
`currency`	string	PO currency
`status`	string	`DRAFT`, `SUBMITTED`, `AUTHORIZED`, `BILLED`, `DELETED`
`accounts_payable_account`	string	UUID of A/P account where the resulting liability is tracked. Required by some providers (e.g. QBO).
`line_items`	array	PO lines (`description`, `unit_price`, `quantity`, `item`, `account`)
`payment_term`	string	UUID of associated payment term

Sales Order

Unified Field	Type	Description
`customer`	string	UUID of the customer
`transaction_number`	string	SO number
`issue_date`	string	ISO date
`status`	string	`DRAFT`, `PENDING_APPROVAL`, `OPEN`, `PARTIALLY_COMPLETED`, `COMPLETED`, `CLOSED`
`total`	number	Total amount
`currency`	string	SO currency
`lines`	array	SO lines (`description`, `unit_price`, `quantity`, `item`)

Credit Note

Unified Field	Type	Description
`number`	string	Credit note number
`transaction_date`	string	ISO date
`status`	string	`SUBMITTED`, `AUTHORIZED`, `PAID`
`contact`	string	UUID of the customer being credited
`total_amount`	number	Total credit amount
`remaining_credit`	number	Unapplied credit available to future invoices
`currency`	string	Currency
`line_items`	array	Credit lines

Vendor Credit

Unified Field	Type	Description
`number`	string	Vendor credit number
`transaction_date`	string	ISO date
`vendor`	string	UUID of the vendor issuing the credit
`total_amount`	number	Total credit amount
`currency`	string	Currency
`accounts_payable_account`	string	UUID of A/P account where the credit reduces a liability
`lines`	array	Credit lines (`net_amount`, `account`, `description`)

Tax Rate

Unified Field	Type	Description
`name`	string	Tax rate display name
`code`	string	Tax rate code (e.g. `CA-SALES-08`)
`description`	string	Description
`status`	string	`ACTIVE` or `ARCHIVED`
`country`	string	ISO 3166-1 alpha-2 country code
`total_tax_rate`	number	Total effective rate (%)
`effective_tax_rate`	number	Effective rate (%)
`tax_components`	array	Component rates (`name`, `rate`, `is_compound`, `component_type`)

Tracking Category

Unified Field	Type	Description
`name`	string	Category name (e.g. `US-West`, `Product Line A`)
`status`	string	`ACTIVE` or `ARCHIVED`
`category_type`	string	`CLASS` or `DEPARTMENT` — the tracking dimension
`parent_category`	string	UUID of parent category (for hierarchical)

Accounting Period

Unified Field	Type	Description
`name`	string	Period name (e.g. `FY2026 Q1`)
`status`	string	`ACTIVE` or `INACTIVE`
`start_date`	string	ISO period start
`end_date`	string	ISO period end

Payment Method

Unified Field	Type	Description
`name`	string	Method name (e.g. `Cash`, `Bank ACH`)
`method_type`	string	`CREDIT_CARD`, `DEBIT_CARD`, `ACH`, `CASH`, `CHECK`
`is_active`	boolean	Whether the method is currently active

Payment Term

Unified Field	Type	Description
`name`	string	Term name (e.g. `Net 30`)
`is_active`	boolean	Whether the term is currently active
`days_until_due`	number	Days from issue to due date (Standard mode)
`discount_days`	number	Days within which an early-payment discount applies

Company Info

Unified Field	Type	Description
`name`	string	Trade name
`legal_name`	string	Legal entity name
`tax_number`	string	Company tax ID
`fiscal_year_end_month`	number	Month (1-12) when fiscal year ends
`fiscal_year_end_day`	number	Day (1-31) when fiscal year ends
`currency`	string	Base currency
`urls`	array	Company website URLs
`addresses`	array	Company addresses
`phone_numbers`	array	Company phone numbers

Employee

Unified Field	Type	Description
`first_name`	string	First name
`last_name`	string	Last name
`email_address`	string	Primary email
`employee_number`	string	Internal employee ID
`is_contractor`	boolean	True for 1099 contractors, false for W-2
`status`	string	`ACTIVE` or `INACTIVE`

Project

Unified Field	Type	Description
`name`	string	Project name
`is_active`	boolean	Whether the project is currently active
`contact`	string	UUID of customer or supplier involved

Attachment

Unified Field	Type	Description
`file_name`	string	Attachment filename
`file_url`	string	Download URL (may be permanent or signed depending on provider)

Expense Report

Unified Field	Type	Description
`report_date`	string	ISO date the report was issued
`report_identifier`	string	Human-readable identifier
`employee`	string	UUID of submitter
`status`	string	`DRAFT`, `SUBMITTED`, `APPROVED`, `REJECTED`
`total_amount`	number	Total report amount
`currency`	string	Currency
`description`	string	Report description
`lines`	array	Expense lines (`account`, `description`, `expense_date`, `amount`, `tax_amount`, `is_billable`, `non_reimbursable`)

Item Fulfillment

Unified Field	Type	Description
`sales_order`	string	UUID of the originating sales order
`fulfillment_date`	string	ISO date of fulfillment
`customer`	string	UUID of customer
`status`	string	`DRAFT`, `IN_PROGRESS`, `SHIPPED`, `CANCELLED`
`memo`	string	Free-form memo
`lines`	array	Fulfillment lines (`item`, `sales_order_line`, `quantity`)

Financial reports (read-only)

The three financial-report resources are generated on-demand from the provider — they are read-only and do not have stored records. Pass created_after / created_before query params to drive the report’s start/end dates.

Balance Sheet

Unified Field	Type	Description
`name`	string	Report name
`date`	string	Snapshot as-of date (single point in time)
`currency`	string	Report currency
`net_assets`	number	Total assets − total liabilities
`assets`	array	Asset line items (recursive `name`, `value`, `sub_items`)
`liabilities`	array	Liability line items
`equity`	array	Equity line items
`remote_generated_at`	string	ISO timestamp when the source system rendered the report

Income Statement

Unified Field	Type	Description
`name`	string	Report name (e.g. `Profit and Loss`)
`start_period`	string	ISO period start
`end_period`	string	ISO period end
`currency`	string	Report currency
`income`	array	Revenue line items
`cost_of_sales`	array	COGS line items
`gross_profit`	number	Income − cost of sales
`operating_expenses`	array	Operating expense line items
`net_operating_income`	number	Gross profit − operating expenses
`non_operating_expenses`	array	Non-operating expense line items
`net_income`	number	Final bottom line

Cash Flow Statement

Unified Field	Type	Description
`name`	string	Report name
`start_period`	string	ISO period start
`end_period`	string	ISO period end
`currency`	string	Report currency
`cash_at_beginning_of_period`	number	Opening cash balance
`cash_at_end_of_period`	number	Closing cash balance
`operating_activities`	array	Net cash from operations
`investing_activities`	array	Net cash from investing
`financing_activities`	array	Net cash from financing

Mapping Direction

Each mapping has a direction that determines how data flows:

Direction	Read (GET)	Write (POST/PUT/PATCH)
`bidirectional`	Provider → Unified	Unified → Provider
`read`	Provider → Unified	Ignored
`write`	Ignored	Unified → 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).

​How It Works

​Viewing Mappings

​Provider-specific fields via integration_params

​CRM Unified Schema

​Contacts

​Leads

​Deals

​Meetings

​Companies

​Notes

​Tasks

​Activities

​Pipelines (read-only)

​Owners (read-only)

​Appointments

​Accounting Unified Schema

​Invoice

​Contact (Accounting)

​Account

​Payment

​Item

​Journal Entry

​Expense

​Purchase Order

​Sales Order

​Credit Note

​Vendor Credit

​Tax Rate

​Tracking Category

​Accounting Period

​Payment Method

​Payment Term

​Company Info

​Employee

​Project

​Attachment

​Expense Report

​Item Fulfillment

​Financial reports (read-only)

​Balance Sheet

​Income Statement

​Cash Flow Statement

​Other read-only accounting resources

​Mapping Direction

​Custom Overrides