Create connector field mapping
POST/integrations/connectors/{id}/field-mappings
Creates a field mapping between a CRM source field and an external target field for the given connector. If an identical source/target combination already exists for the binding key, it is upserted (updated). Provide an optional transform_rule expression for data type or format conversion.
Request
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | ID of the connector to add this mapping to. Example: |
Request body
Content type application/json (required).
| Field | Type | Required | Description |
|---|---|---|---|
binding_key | string | No | Logical grouping key for related mappings (e.g. "contacts", "deals"). Defaults to "default". Default: |
source_field | string | Yes | CRM-side field path (e.g. "customer.email" or "deal.value"). Max length: 120 |
target_field | string | Yes | External system field name (e.g. "Email" or "Amount__c"). Max length: 120 |
direction | string | No | Sync direction. 'push' = CRM → external; 'pull' = external → CRM; 'bidirectional' = both directions. One of: |
transform_rule | string, nullable | No | Optional transformation expression applied during sync (e.g. "uppercase", "date_format:Y-m-d", or a simple mapping table). Max length: 2000 |
sample_value | string, nullable | No | Example value for documentation and testing purposes. Max length: 255 |
is_required | boolean | No | Whether this field is mandatory during sync validation. Default: |
status | string | No | Whether this mapping is applied during sync runs. One of: |
Example
{
"binding_key": "contacts",
"source_field": "customer.email",
"target_field": "Email",
"direction": "bidirectional",
"sample_value": "customer@example.test",
"is_required": true,
"status": "active"
}Responses
302 Redirect to field mappings page after save
422 Validation error — source_field and target_field are required
Example request
curl -X POST "https://{tenant}.faciotech.net/api/v1/integrations/connectors/{id}/field-mappings" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"binding_key": "contacts", "source_field": "customer.email", "target_field": "Email", "direction": "bidirectional", "sample_value": "customer@example.test", "is_required": true, "status": "active"}'