Field Mappings

Field Mappings API

Get Field Mappings

GET /api/v1/integration/field-mappings

Returns the current field mapping configuration for this integration.

Required scope: integration:sync:read

Response

{
  "fieldMappings": {
    "suppliers": {
      "name": "displayName",
      "code": "vendorNumber",
      "country": "countryCode",
      "address": "address1"
    },
    "products": {
      "name": "itemDescription",
      "category": "itemCategory",
      "hsCode": "tariffNumber"
    },
    "batches": {
      "batchNumber": "lotNumber",
      "quantity": "qty",
      "unit": "uom"
    }
  }
}

How Field Mappings Work

Field mappings tell the platform how to translate your external system’s field names to the platform’s internal field names.

Format

{
  "ourField": "yourField"
}

The key is the platform field name, and the value is your system’s field name.

Example

If your ERP sends vendor data like this:

{
  "externalId": "V-001",
  "displayName": "Timber Corp",
  "vendorNumber": "TC-001",
  "countryCode": "BR",
  "address1": "Rua Example 123"
}

You would configure mappings as:

{
  "suppliers": {
    "name": "displayName",
    "code": "vendorNumber",
    "country": "countryCode",
    "address": "address1"
  }
}

Default Mappings

If no custom mappings are configured, the platform uses these defaults:

Suppliers:

Platform Field	Default External Field
`name`	`name`
`code`	`code`
`country`	`country`
`address`	`address`
`contactPerson`	`contactPerson`
`email`	`email`
`phone`	`phone`

Products:

Platform Field	Default External Field
`name`	`name`
`category`	`category`
`country`	`country`
`hsCode`	`hsCode`
`unit`	`unit`
`supplierProductCode`	`code`

Batches:

Platform Field	Default External Field
`batchNumber`	`batchNumber`
`quantity`	`quantity`
`unit`	`unit`
`receivedDate`	`receivedDate`
`expiryDate`	`expiryDate`

Update Field Mappings

Field mappings are configured through the platform UI under Integrations → Sync Config, or via the management API (session-authenticated).