> ## Documentation Index
> Fetch the complete documentation index at: https://docs.routemcp.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Field Mappings

> Understand how CRM and Accounting provider data maps to the unified schema

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:

1. Fetches raw data from the provider
2. Applies **field mappings** to transform provider fields to the unified schema
3. 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:

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

Response:

```json theme={null}
{
  "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.

```bash theme={null}
# 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](/integrations/overview) 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  |

### Other read-only accounting resources

`general_ledger_transaction`, `transaction`, `bank_feed_account`, `bank_feed_transaction`, `address`, `phone_number` — see the [API Reference](/api-reference/overview) for full field details. These are list/get-only.

## 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).
