Use the following HTTP method and endpoint path to save a mapping between a Databricks source object and a Reltio interaction type.

POST {platformUrl}/reltio/api/tenants/{tenantId}/zero-copy-interactions/mappings

The following table describes the endpoint path parameters.

Parameter	Type	Required	Description
tenantId	String	Yes	Unique identifier of the tenant where the Databricks connection is defined. Example: ce5627DYnQ6abcD

The following request headers must be included.

Header	Value	Required
Authorization	Bearer <access_token>	Yes
Content-Type	application/json	Yes

Use the request body to define the Databricks source object and the mapping rules used by zero-copy integration from Databricks. The following table describes the main request body parameters.

Parameter	Type	Required	Description	Accepted values / Default
interaction_id	String	No	Unique identifier for the interaction mapping.	If omitted, Reltio generates an identifier and returns it in the response.
interaction_type	String	Yes	Name of an existing Reltio interaction type used for the mapping.	Example: CustomerPurchase
database_name	String	Yes	Name of the Databricks catalog or database containing the source object.	Example: db
schema_name	String	Yes	Name of the Databricks schema containing the source object.	Example: schema
table_name	String	Yes	Name of the Databricks source table or view. Enter the object name only, without the database or schema.	Example: ORDER_TRANSACTIONS
timestamp_column	String	No	Source column containing the interaction timestamp. If provided, the value cannot be empty.	Example: TRANSACTION_DATE
order_by_column	String	Yes	Source column used to sort returned interaction rows.	Example: TRANSACTION_DATE
attributes	Array	Yes	List of Databricks source columns returned as interaction attributes.	—
member_mappings	Array	Yes	Maps Reltio entity types to Databricks columns containing crosswalk identifiers.	—

The attributes array defines the Databricks source columns that Reltio returns as interaction attributes. The following table describes the fields in each attributes object.

Parameter	Type	Required	Description	Accepted values / Default
attribute_name	String	Yes	Name of an attribute defined on the selected Reltio interaction type.	Example: Amount
column_name	String	Yes	Databricks source column mapped to the interaction attribute.	Example: AMOUNT

The member_mappings array defines how Reltio links Databricks rows to Reltio entities. The following table describes the fields in each member_mappings object.

Parameter	Type	Required	Description	Accepted values / Default
member_type	String	Yes	Reltio entity type linked by the mapping.	Example values: Individual, Organization, Location
column_name	String	Yes	Name of the Databricks source column that contains the crosswalk ID for the entity type.	Example: customer_crosswalk_id

Use the following example to map a Databricks source object to a Reltio interaction type.

POST {platformUrl}/reltio/api/tenants/{tenantId}/zero-copy-interactions/mappings
{
  "interaction_type": "CustomerPurchase",
  "database_name": "reltio_interactions",
  "schema_name": "customer_data",
  "table_name": "purchases",
  "timestamp_column": "purchase_timestamp",
  "order_by_column": "purchase_timestamp",
  "attributes": [
    {
      "attribute_name": "Amount",
      "column_name": "amount"
    },
    {
      "attribute_name": "Channel",
      "column_name": "channel"
    }
  ],
  "member_mappings": [
    {
      "member_type": "Individual",
      "column_name": "customer_crosswalk_id"
    }
  ]
}

The following table describes the fields returned in the response body when the request is successful.

Field	Type	Description
successful	Boolean	Indicates whether the mapping operation succeeded.
result	Object	Saved interaction mapping.
result.interaction_id	String	Unique identifier generated for the interaction mapping.
result.interaction_type	String	Reltio interaction type associated with the mapping.
result.database_name	String	Databricks catalog or database containing the source object.
result.schema_name	String	Databricks schema containing the source object.
result.table_name	String	Name of the mapped Databricks table or view.
result.timestamp_column	String	Source column containing the interaction timestamp, if configured.
result.order_by_column	String	Source column used to sort interaction rows.
result.attributes	Array	Saved interaction attribute mappings.
result.attributes[].attribute_name	String	Reltio interaction attribute name.
result.attributes[].column_name	String	Mapped Databricks source column.
result.member_mappings	Array	Saved mappings between Reltio entity types and Databricks crosswalk columns.
result.member_mappings[].member_type	String	Reltio entity type associated with the mapping.
result.member_mappings[].column_name	String	Databricks column containing the entity crosswalk identifier.
result.created_time	String	Date and time when the mapping was created.
result.updated_time	String	Date and time when the mapping was last updated.
error	String	Error message returned when the operation fails.

If the request succeeds, this operation returns HTTP 201 Created with the saved mapping configuration. The response is similar to the following example.

{
  "successful": true,
  "result": {
    "interaction_id": "d444c359-438f-497a-b1a4-ee76d3f82914",
    "interaction_type": "CustomerPurchase",
    "database_name": "db",
    "schema_name": "schema",
    "table_name": "ORDER_TRANSACTIONS",
    "timestamp_column": "TRANSACTION_DATE",
    "order_by_column": "TRANSACTION_DATE",
    "attributes": [
      {
        "attribute_name": "Amount",
        "column_name": "AMOUNT"
      }
    ],
    "member_mappings": [
      {
        "member_type": "Individual",
        "column_name": "CUSTOMER_ID"
      }
    ],
    "created_time": "2026-04-02T10:17:07.609044726",
    "updated_time": "2026-04-02T10:17:07.609044726"
  }
}

If the request fails, the API returns HTTP 400 Bad Request with an error response similar to the following examples. Review the response message, correct the related mapping values, and then submit the request again.

{
  "successful": false,
  "error": "Attribute 'Amounts' is not configured for interaction type 'PurchaseOrder'. Available attributes: [TransactionDate, Amount, MerchantId, StoreId, ProductCategory, CustomerId]"
}

{
  "successful": false,
  "error": "Failed to validate interaction type 'PurchaseOrders' for tenant 'ZeroCopyDataBricks': Code: TYPE_IS_NOT_FOUND; Message parameters: [configuration/interactionTypes/PurchaseOrders, ZeroCopyDataBricks]. Type is not found for URI configuration/interactionTypes/PurchaseOrders and tenant ZeroCopyDataBricks. Type is not found for URI configuration/interactionTypes/PurchaseOrders and tenant ZeroCopyDataBricks"
}