Writeback API

The writeback router manages pushing computed scores back to external systems (e.g., Salesforce custom fields). Admins configure which score fields map to target fields, then trigger writeback operations that run as asynchronous Temporal workflows.

Router namespace: writeback

Source: src/server/trpc/routers/writeback.ts

Access: All procedures require admin role.

Procedures

Procedure	Type	Access	Description
getConfig	query	admin	Get writeback configurations for a connector
saveConfig	mutation	admin	Save or update writeback field mappings
triggerWriteback	mutation	admin	Trigger an asynchronous writeback operation
getWritebackStatus	query	admin	Get writeback status for a connector
listWriteableFields	query	admin	List writeable fields in the target system

Canonical Score Fields

Writeback supports mapping these canonical score fields to target system fields:

Canonical Field	Type	Description
fitScore	number	ICP match score (0-100)
engagementScore	number	Behavioral engagement score (0-100)
combinedScore	number	Weighted combination of fit + engagement
tier	string	Score tier (hot, warm, cool, cold)
scoredAt	datetime	Timestamp of last scoring run

---

getConfig

Retrieves all writeback configurations for a connector, including field mappings and status.

writeback.getConfig.queryOptions(input)

Input

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

Response

[
  {
    "entityType": "account",
    "fieldMap": [
      { "canonicalField": "combinedScore", "targetField": "GTM_Score__c" },
      { "canonicalField": "tier", "targetField": "GTM_Tier__c" },
      { "canonicalField": "scoredAt", "targetField": "GTM_Scored_At__c" }
    ],
    "enabled": true,
    "lastWritebackAt": "2026-03-05T09:00:00.000Z",
    "lastWritebackError": null
  }
]

---

saveConfig

Saves or updates writeback configuration for a specific entity type. Uses upsert semantics -- creates a new config or updates the existing one.

writeback.saveConfig.mutationOptions(options)

Input

Field	Type	Required	Description
connectorId	string	Yes	Database ID of the connector
entityType	string	Yes	Entity type (e.g., "account", "person")
fieldMap	WritebackFieldMap[]	Yes	Score-to-target field mappings
enabled	boolean	Yes	Whether writeback is active for this entity type

WritebackFieldMap schema:

Field	Type	Required	Description
canonicalField	"fitScore" | "engagementScore" | "combinedScore" | "tier" | "scoredAt"	Yes	Score field to write
targetField	string	Yes	Target system field name (e.g., Salesforce custom field API name)

Response

{
  "success": true
}

Connector Validation

Throws NOT_FOUND if the specified connector does not exist or does not belong to the current tenant.

Example

const trpc = useTRPC();

const mutation = useMutation(
  trpc.writeback.saveConfig.mutationOptions()
);

mutation.mutate({
  connectorId: "conn_456",
  entityType: "account",
  fieldMap: [
    { canonicalField: "combinedScore", targetField: "GTM_Score__c" },
    { canonicalField: "tier", targetField: "GTM_Tier__c" },
    { canonicalField: "scoredAt", targetField: "GTM_Scored_At__c" },
  ],
  enabled: true,
});

---

triggerWriteback

Triggers an asynchronous writeback operation via Temporal workflows. Scores are pushed to the target system for the configured entity types.

writeback.triggerWriteback.mutationOptions(options)

Input

Field	Type	Required	Default	Description
connectorId	string	Yes	--	Database ID of the connector
entityTypes	string[]	No	all configured types	Limit writeback to specific entity types

Response

{
  "workflowId": "writeback-tenant_789-conn_456-1709625600000",
  "queued": true
}

Asynchronous Operation

Writeback runs as a Temporal workflow. The response confirms the operation is queued. Use getWritebackStatus to monitor progress.

---

getWritebackStatus

Returns the current writeback status for all entity types configured on a connector.

writeback.getWritebackStatus.queryOptions(input)

Input

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

Response

[
  {
    "entityType": "account",
    "lastWritebackAt": "2026-03-05T09:00:00.000Z",
    "lastWritebackError": null,
    "enabled": true
  },
  {
    "entityType": "person",
    "lastWritebackAt": null,
    "lastWritebackError": "FIELD_NOT_WRITABLE: GTM_Score__c",
    "enabled": true
  }
]

---

listWriteableFields

Lists fields in the target system that can be written to for a given entity type. Requires an active connector connection.

writeback.listWriteableFields.queryOptions(input)

Input

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

Response

[
  { "name": "GTM_Score__c", "label": "GTM Score", "type": "number", "custom": true },
  { "name": "GTM_Tier__c", "label": "GTM Tier", "type": "picklist", "custom": true },
  { "name": "Description", "label": "Description", "type": "textarea", "custom": false }
]

warning

Throws NOT_FOUND if the connector is not connected. An active connection to the target system is required to describe available fields.

Related Pages

• Connector API -- Manage connector connections
• Field Mappings API -- Configure inbound field mappings
• Scoring API -- Execute scoring runs before writeback