Field Mappings

Overview

Field Mappings define how your custom schema fields translate to gu1’s unified entity model. Each mapping can include transformations to format, calculate, or conditionally process data during import.

Mappings bridge the gap between your data structure and gu1’s entity model, enabling seamless data ingestion from any source.

Create Field Mapping

Create a mapping configuration for your custom schema.

curl -X POST http://api.gu1.ai/custom-schemas/mappings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "KYB Company Mapping",
    "description": "Maps company data to gu1 entity model",
    "sourceSchemaId": "550e8400-e29b-41d4-a716-446655440000",
    "targetSchemaType": "gueno_entity",
    "mappingData": {
      "mappings": [
        {
          "id": "1",
          "sourceField": "company_name",
          "targetField": "name",
          "transformation": {
            "type": "direct"
          },
          "required": true,
          "dataType": "string"
        },
        {
          "id": "2",
          "sourceField": "tax_id",
          "targetField": "external_id",
          "transformation": {
            "type": "format",
            "expression": "value.trim().toUpperCase()"
          },
          "required": true,
          "dataType": "string"
        },
        {
          "id": "3",
          "sourceField": "annual_revenue",
          "targetField": "entityData.revenue",
          "transformation": {
            "type": "calculate",
            "expression": "value * 1000"
          },
          "required": false,
          "dataType": "number"
        }
      ],
      "validation": {
        "strictMode": true,
        "allowExtraFields": false,
        "requiredFields": ["name", "external_id"]
      }
    }
  }'

const response = await fetch('http://api.gu1.ai/custom-schemas/mappings', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'KYB Company Mapping',
    description: 'Maps company data to gu1 entity model',
    sourceSchemaId: '550e8400-e29b-41d4-a716-446655440000',
    targetSchemaType: 'gueno_entity',
    mappingData: {
      mappings: [
        {
          id: '1',
          sourceField: 'company_name',
          targetField: 'name',
          transformation: { type: 'direct' },
          required: true,
          dataType: 'string'
        }
      ],
      validation: {
        strictMode: true,
        allowExtraFields: false,
        requiredFields: ['name', 'external_id']
      }
    }
  })
});

Request Body

Field	Type	Required	Description
`name`	string	Yes	Mapping configuration name
`description`	string	No	Mapping description
`sourceSchemaId`	uuid	No	Source custom schema ID
`targetSchemaType`	string	No	Target schema type (e.g., “gueno_entity”)
`sourceSchemaName`	string	No	Alternative to sourceSchemaId
`targetSchemaName`	string	No	Alternative to targetSchemaType
`mappingData`	object	Yes	Mapping configuration
`industry`	string	No	Industry context
`collaborators`	array	No	User IDs with access

Mapping Data Object

Field	Type	Required	Description
`mappings`	array	Yes	Array of field mappings
`templates`	array	No	Template IDs to apply
`validation`	object	No	Validation rules
`transformationSettings`	object	No	Processing settings

Field Mapping Object

Field	Type	Required	Description
`id`	string	Yes	Unique mapping identifier
`sourceField`	string	Yes	Source field name
`targetField`	string	Yes	Target field name (supports dot notation)
`transformation`	object	No	Transformation to apply
`required`	boolean	Yes	Is field required
`dataType`	string	Yes	Expected data type
`defaultValue`	any	No	Default if source is null/missing
`validationRule`	string	No	Custom validation expression

Response

{
  "success": true,
  "mapping": {
    "id": "map_abc123",
    "name": "KYB Company Mapping",
    "description": "Maps company data to gu1 entity model",
    "sourceSchemaId": "550e8400-e29b-41d4-a716-446655440000",
    "targetSchemaType": "gueno_entity",
    "organizationId": "org_xyz",
    "createdBy": "user_123",
    "createdAt": "2025-10-03T12:00:00Z",
    "updatedAt": "2025-10-03T12:00:00Z",
    "mappingData": {
      "mappings": [...],
      "validation": {...}
    }
  }
}

Transformation Types

Direct Mapping

Copy value as-is with no changes:

{
  "transformation": {
    "type": "direct"
  }
}

Format Transformation

Apply string, date, or number formatting:

{
  "transformation": {
    "type": "format",
    "expression": "value.trim().toUpperCase()",
    "parameters": {
      "dateFormat": "ISO8601",
      "decimalPlaces": 2
    }
  }
}

Common Format Examples:

// Trim and uppercase
"value.trim().toUpperCase()"

// Format date
"new Date(value).toISOString()"

// Format currency
"parseFloat(value).toFixed(2)"

// Clean phone number
"value.replace(/[^0-9]/g, '')"

Calculate Transformation

Perform mathematical calculations:

{
  "transformation": {
    "type": "calculate",
    "expression": "value * 1000",
    "parameters": {
      "operator": "multiply",
      "operand": 1000
    }
  }
}

Common Calculate Examples:

// Convert thousands to actual value
"value * 1000"

// Calculate percentage
"(value / total) * 100"

// Sum multiple fields
"sourceData.field1 + sourceData.field2"

// Average calculation
"(field1 + field2 + field3) / 3"

Conditional Transformation

Apply if/then logic:

{
  "transformation": {
    "type": "conditional",
    "expression": "value > 1000000 ? 'high' : value > 100000 ? 'medium' : 'low'",
    "parameters": {
      "conditions": [
        {"if": "value > 1000000", "then": "high"},
        {"if": "value > 100000", "then": "medium"},
        {"else": "low"}
      ]
    }
  }
}

Lookup Transformation

Look up values from reference tables:

{
  "transformation": {
    "type": "lookup",
    "expression": "lookupTable[value] || 'unknown'",
    "parameters": {
      "lookupTable": {
        "US": "United States",
        "UK": "United Kingdom",
        "CA": "Canada"
      },
      "defaultValue": "unknown"
    }
  }
}

Custom Transformation

Execute custom JavaScript:

{
  "transformation": {
    "type": "custom",
    "expression": "const parts = value.split('-'); return parts[0].toUpperCase();",
    "parameters": {
      "allowedFunctions": ["split", "toUpperCase", "trim"]
    }
  }
}

Custom transformations have security restrictions. Only whitelisted JavaScript functions are allowed.

Validation Rules

Configure validation behavior:

{
  "validation": {
    "strictMode": true,
    "allowExtraFields": false,
    "requiredFields": ["name", "external_id", "country"]
  }
}

Setting	Type	Description
`strictMode`	boolean	Fail on any validation error
`allowExtraFields`	boolean	Allow unmapped source fields
`requiredFields`	array	Fields that must have values

Transformation Settings

Configure processing behavior:

{
  "transformationSettings": {
    "errorHandling": "default",
    "batchSize": 100,
    "timeout": 30000
  }
}

Setting	Type	Description
`errorHandling`	enum	`skip`, `fail`, or `default`
`batchSize`	number	Records per batch (1-1000)
`timeout`	number	Timeout in milliseconds

List Mappings

Get all mapping configurations for your organization:

GET /custom-schemas/mappings

Response

{
  "success": true,
  "mappings": [
    {
      "id": "map_abc123",
      "name": "KYB Company Mapping",
      "sourceSchemaId": "550e8400-e29b-41d4-a716-446655440000",
      "targetSchemaType": "gueno_entity",
      "createdAt": "2025-10-03T12:00:00Z"
    }
  ]
}

Get Mapping

Retrieve a specific mapping configuration:

GET /custom-schemas/mappings/:id

Response

{
  "success": true,
  "mapping": {
    "id": "map_abc123",
    "name": "KYB Company Mapping",
    "description": "Maps company data to gu1 entity model",
    "mappingData": {
      "mappings": [...],
      "validation": {...}
    }
  }
}

Update Mapping

Update an existing mapping configuration:

PATCH /custom-schemas/mappings/:id

Request Body

{
  "description": "Updated description",
  "mappingData": {
    "mappings": [
      {
        "id": "4",
        "sourceField": "new_field",
        "targetField": "entityData.newField",
        "transformation": { "type": "direct" },
        "required": false,
        "dataType": "string"
      }
    ]
  }
}

Delete Mapping

Delete a mapping configuration:

DELETE /custom-schemas/mappings/:id

Complete Example: Banking Customer Mapping

{
  "name": "Banking Customer to Entity Mapping",
  "description": "Complete mapping for retail banking customers",
  "sourceSchemaId": "schema_banking_001",
  "targetSchemaType": "gueno_entity",
  "mappingData": {
    "mappings": [
      {
        "id": "1",
        "sourceField": "customer_id",
        "targetField": "external_id",
        "transformation": {
          "type": "format",
          "expression": "value.trim().toUpperCase()"
        },
        "required": true,
        "dataType": "string"
      },
      {
        "id": "2",
        "sourceField": "full_name",
        "targetField": "name",
        "transformation": { "type": "direct" },
        "required": true,
        "dataType": "string"
      },
      {
        "id": "3",
        "sourceField": "email",
        "targetField": "entityData.contact.email",
        "transformation": {
          "type": "format",
          "expression": "value.toLowerCase().trim()"
        },
        "required": true,
        "dataType": "string",
        "validationRule": "/^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(value)"
      },
      {
        "id": "4",
        "sourceField": "account_balance",
        "targetField": "entityData.financial.balance",
        "transformation": {
          "type": "calculate",
          "expression": "Math.round(value * 100) / 100"
        },
        "required": false,
        "dataType": "number",
        "defaultValue": 0
      },
      {
        "id": "5",
        "sourceField": "account_balance",
        "targetField": "entityData.financial.balanceTier",
        "transformation": {
          "type": "conditional",
          "expression": "value > 100000 ? 'premium' : value > 10000 ? 'standard' : 'basic'"
        },
        "required": false,
        "dataType": "string"
      },
      {
        "id": "6",
        "sourceField": "country_code",
        "targetField": "country",
        "transformation": {
          "type": "lookup",
          "parameters": {
            "lookupTable": {
              "US": "United States",
              "UK": "United Kingdom",
              "CA": "Canada",
              "MX": "Mexico"
            },
            "defaultValue": "Unknown"
          }
        },
        "required": true,
        "dataType": "string"
      },
      {
        "id": "7",
        "sourceField": "risk_score",
        "targetField": "riskScore",
        "transformation": {
          "type": "calculate",
          "expression": "Math.min(Math.max(value, 0), 100)"
        },
        "required": false,
        "dataType": "number",
        "defaultValue": 0
      }
    ],
    "validation": {
      "strictMode": true,
      "allowExtraFields": false,
      "requiredFields": ["external_id", "name", "country"]
    },
    "transformationSettings": {
      "errorHandling": "default",
      "batchSize": 500,
      "timeout": 60000
    }
  }
}

Error Responses

Validation Error

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Mapping validation failed",
    "details": [
      {
        "mappingId": "3",
        "field": "email",
        "error": "Invalid email format"
      }
    ]
  }
}

Transformation Error

{
  "success": false,
  "error": {
    "code": "TRANSFORMATION_ERROR",
    "message": "Error applying transformation",
    "details": {
      "mappingId": "4",
      "sourceField": "account_balance",
      "error": "Cannot multiply undefined by 1000"
    }
  }
}

Best Practices

Start Simple

Begin with direct mappings for most fields
Add transformations only when necessary
Test each transformation individually
Gradually increase complexity

Testing

Test mappings with sample data before production
Validate edge cases (null, empty, invalid values)
Monitor transformation errors in logs
Use strictMode in production environments

Data Quality

Set appropriate defaultValue for optional fields
Use validationRule for complex validations
Apply format transformations for consistency
Handle missing/null values explicitly

Performance

Avoid complex custom transformations in hot paths
Use batch processing for large datasets
Set reasonable timeout values
Monitor transformation execution times

Next Steps

Smart Field Detection

Auto-generate mappings from sample data

Import Entities

Use mappings to import entity data

Data Mapping Guide

Complete workflow guide

Transformations Guide

Advanced transformation patterns

​Overview

​Create Field Mapping

​Request Body

​Mapping Data Object

​Field Mapping Object

​Response

​Transformation Types

​Direct Mapping

​Format Transformation

​Calculate Transformation

​Conditional Transformation

​Lookup Transformation

​Custom Transformation

​Validation Rules

​Transformation Settings

​List Mappings

​Response

​Get Mapping

​Response

​Update Mapping

​Request Body

​Delete Mapping

​Complete Example: Banking Customer Mapping

​Error Responses

​Validation Error

​Transformation Error

​Best Practices

​Next Steps

Smart Field Detection

Import Entities

Data Mapping Guide

Transformations Guide

Overview

Create Field Mapping

Request Body

Mapping Data Object

Field Mapping Object

Response

Transformation Types

Direct Mapping

Format Transformation

Calculate Transformation

Conditional Transformation

Lookup Transformation

Custom Transformation

Validation Rules

Transformation Settings

List Mappings

Response

Get Mapping

Response

Update Mapping

Request Body

Delete Mapping

Complete Example: Banking Customer Mapping

Error Responses

Validation Error

Transformation Error

Best Practices

Next Steps