Field Mappings API

The fieldMapping router manages the mapping between source system fields (e.g., Salesforce object fields) and GTM Clarity's canonical schema. Field mappings determine how synced data is transformed and stored.

Router namespace: fieldMapping

Source: src/server/trpc/routers/field-mappings.ts

Procedures

Procedure	Type	Access	Description
listSourceFields	query	admin	List available fields from the source system
listTargetFields	query	tenant	List canonical target fields for an entity type
getMappings	query	tenant	Get current mappings for a connector + entity type
saveMappings	mutation	admin	Save custom field mappings
resetToDefaults	mutation	admin	Reset mappings to connector defaults

Entity Types

Field mappings support four entity types:

Entity Type	Description	Example Source Object
person	Contacts and leads	Salesforce Contact / Lead
account	Company accounts	Salesforce Account
opportunity	Sales opportunities	Salesforce Opportunity
activity	Engagement events	Salesforce Task / Event

---

listSourceFields

Lists available fields from the source system (e.g., Salesforce object metadata via the Describe API). Requires an active connector connection.

fieldMapping.listSourceFields.queryOptions(input)

Access: Admin only

Input

Field	Type	Required	Description
connectorId	string	Yes	Database ID of the connector
entityType	"person" | "account" | "opportunity" | "activity"	Yes	Entity type to describe

Response

Returns an array of source field descriptors:

[
  { "name": "Id", "label": "Record ID", "type": "id", "required": true },
  { "name": "Name", "label": "Account Name", "type": "string", "required": true },
  { "name": "Industry", "label": "Industry", "type": "picklist", "required": false }
]

warning

Throws NOT_FOUND if the connector is not connected. Throws BAD_REQUEST for unsupported entity types.

---

listTargetFields

Returns the canonical target fields for an entity type. These are the fields in GTM Clarity's internal schema that source fields can map to.

fieldMapping.listTargetFields.queryOptions(input)

Input

Field	Type	Required	Description
entityType	"person" | "account" | "opportunity" | "activity"	Yes	Entity type

Response

[
  { "field": "externalId", "required": true },
  { "field": "name", "required": true },
  { "field": "domain", "required": false },
  { "field": "industry", "required": false },
  { "field": "employeeCount", "required": false },
  { "field": "annualRevenue", "required": false }
]

Canonical Fields by Entity Type

Person: externalId (required), email, firstName, lastName, title, phone, accountExternalId

Account: externalId (required), name (required), domain, industry, employeeCount, annualRevenue

Opportunity: externalId (required), name (required), stage, amount, closeDate, accountExternalId

Activity: externalId (required), type (required), channel, occurredAt (required), personExternalId, accountExternalId, properties

---

getMappings

Retrieves current field mappings for a connector and entity type combination. Returns null if no custom mappings have been saved (default mappings are used).

fieldMapping.getMappings.queryOptions(input)

Input

Field	Type	Required	Description
connectorId	string	Yes	Database ID of the connector
entityType	string	Yes	Entity type

Response

Returns the mappings array or null:

[
  {
    "sourceField": "Name",
    "targetField": "name",
    "transform": "trim",
    "required": true
  },
  {
    "sourceField": "Industry",
    "targetField": "industry",
    "transform": "none",
    "required": false
  }
]

---

saveMappings

Saves custom field mappings for a connector and entity type. Uses upsert semantics -- creates a new record or updates the existing one. Validates that all required target fields have mappings.

fieldMapping.saveMappings.mutationOptions(options)

Access: Admin only

Input

Field	Type	Required	Description
connectorId	string	Yes	Database ID of the connector
entityType	string	Yes	Entity type
mappings	FieldMappingEntry[]	Yes	Array of field mapping entries

FieldMappingEntry schema:

Field	Type	Required	Default	Description
sourceField	string	Yes	--	Source system field name
targetField	string	Yes	--	Canonical target field name
transform	"none" | "lowercase" | "uppercase" | "trim" | "custom"	No	"none"	Transform to apply
customTransform	string	No	--	Custom transform expression (when transform is "custom")
required	boolean	No	--	Whether the mapping is required

Response

{
  "success": true
}

Validation

Mappings are validated before saving. If required canonical fields are missing, the call throws BAD_REQUEST with details about the missing fields.

Example

const trpc = useTRPC();

const mutation = useMutation(
  trpc.fieldMapping.saveMappings.mutationOptions()
);

mutation.mutate({
  connectorId: "conn_456",
  entityType: "account",
  mappings: [
    { sourceField: "Id", targetField: "externalId", transform: "none", required: true },
    { sourceField: "Name", targetField: "name", transform: "trim", required: true },
    { sourceField: "Industry", targetField: "industry", transform: "none" },
    { sourceField: "NumberOfEmployees", targetField: "employeeCount", transform: "none" },
  ],
});

---

resetToDefaults

Removes custom field mappings, reverting to the connector's default mappings.

fieldMapping.resetToDefaults.mutationOptions(options)

Access: Admin only

Input

Field	Type	Required	Description
connectorId	string	Yes	Database ID of the connector
entityType	string	Yes	Entity type

Response

{
  "success": true
}

Related Pages

• Connector API -- Manage connector connections and sync
• Writeback API -- Configure score field mappings for writeback
• tRPC Overview -- Client setup and procedure types