Map a BigQuery table or view to a Reltio interaction type

Learn more about mapping a BigQuery table or view to a Reltio interaction type.

The Interaction mapping maps the BigQuery source object containing the interaction data to a Reltio interaction type. The source object can be a table that stores the data or a view that exposes data through a saved query. Reltio queries the selected source and returns the selected columns as interaction attributes. The crosswalk column for each member type links each BigQuery row to the related Reltio profile.

Reltio Intelligent 360™ displays the matching interactions in the profile's interaction timeline.

HTTP method and endpoint

Use the following HTTP method and endpoint path to save a mapping between a BigQuery table or view 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	Identifier of the tenant where the BigQuery connection is defined. Example: `ce5627DYnQ6abcD`

Request headers

The following request headers must be included.


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

Request body

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


Parameter	Type	Required	Description	Accepted values / Default
`interaction_type`	String	Yes	Name of the existing Reltio interaction type used for the mapping.	Example: `UsageEvent`
`interaction_id`	String	No	Identifier of the mapping. Reltio generates an identifier when this field is omitted.	Generated UUID
`database_name`	String	Yes	Google Cloud project containing the BigQuery source.	Example: `idev-01`
`schema_name`	String	Yes	BigQuery dataset containing the table or view.	Example: `telco_sim`
`table_name`	String	Yes	Name of the BigQuery table or view.	Example: `USAGE_EVENT`
`timestamp_column`	String	No	Source column containing the interaction timestamp. If omitted, Reltio sorts interactions by`order_by_column`.	Example: `EVENT_TS`
`order_by_column`	String	Yes	Source column used to sort the returned interaction rows.	Example: `EVENT_TS`
`attributes`	Array	No	BigQuery source columns returned as interaction attributes.	—
`member_mappings`	Array	Yes	Maps Reltio entity types to BigQuery columns containing crosswalk IDs. Provide at least one member mapping to associate BigQuery rows with profiles.	—

The attributes array defines the BigQuery columns returned as interaction attributes.


Parameter	Type	Required	Description	Accepted values / Default
`attribute_name`	String	Yes	Name of the existing Reltio interaction attribute.	Example: `Amount`
`column_name`	String	Yes	Name of the BigQuery source column for the attribute.	Example: `amount`

The member_mappings array defines how Reltio links BigQuery rows to Reltio entities.


Parameter	Type	Required	Description	Accepted values / Default
`member_type`	String	Yes	Member type of the interaction type that the mapping links to profiles.	Example: `Individual`, `Organization`
`column_name`	String	Yes	BigQuery source column containing the crosswalk ID for the entity type.	Example: `customer_crosswalk_id`

Example request

Use the following example to map a BigQuery table to a Reltio interaction type.

POST {platformUrl}/reltio/api/tenants/{tenantId}/zero-copy-interactions/mappings/
{
  "interaction_type": "UsageEvent",
  "database_name": "idev-01",
  "schema_name": "telco_sim",
  "table_name": "USAGE_EVENT",
  "timestamp_column": "EVENT_TS",
  "order_by_column": "EVENT_TS",
  "attributes": [
    {
      "attribute_name": "PaymentID",
      "column_name": "PAYMENT_ID"
    }
  ],
  "member_mappings": [
    {
      "member_type": "Individual",
      "column_name": "XW_INDIVIDUAL_ID"
    }
  ]
}}

Response body

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


Field	Type	Description
`successful`	Boolean	Indicates whether Reltio saved the interaction mapping.
`result`	Object	Contains the saved interaction mapping.
`result.interaction_id`	String	Identifier of the saved interaction mapping.
`result.interaction_type`	String	Reltio interaction type associated with the mapping.
`result.table_name`	String	Name of the mapped BigQuery table or view.
`result.database_name`	String	Google Cloud project containing the mapped source.
`result.schema_name`	String	BigQuery dataset containing the mapped source.
`result.timestamp_column`	String	Column containing the interaction timestamp.
`result.timestamp_column_type`	String	Resolved BigQuery data type of the interaction timestamp column.
`result.order_by_column`	String	Column used to sort the returned interaction rows.
`result.order_by_column_type`	String	Resolved BigQuery data type of the sort column.
`result.attributes`	Array	Saved interaction attribute mappings.
`result.attributes[].attribute_name`	String	Name of the mapped Reltio interaction attribute.
`result.attributes[].column_name`	String	BigQuery column mapped to the interaction attribute.
`result.attributes[].data_type`	String	Normalized BigQuery data type of the mapped attribute column.
`result.attributes[].data_type_raw`	String	Original BigQuery data type of the mapped attribute column.
`result.member_mappings`	Array	Saved entity-to-crosswalk-column mappings.
`result.member_mappings[].member_type`	String	Reltio entity type linked by the mapping.
`result.member_mappings[].column_name`	String	BigQuery source column containing the crosswalk ID.
`result.member_mappings[].data_type`	String	Normalized BigQuery data type of the mapped crosswalk column.
`result.member_mappings[].data_type_raw`	String	Original BigQuery data type of the mapped crosswalk column.
`result.schema_status`	String	Schema validation status of the saved mapping. A successfully created mapping has the value `VALID`.
`result.schema_error`	String	Error message from schema validation. Omitted when validation succeeds.
`result.created_time`	String	Timestamp when the mapping was created.
`result.updated_time`	String	Timestamp when the mapping was last updated.

Example response

If the request succeeds, the response is similar to the following example.

{
  "successful": true,
  "result": {
    "interaction_id": "d444c359-438f-497a-b1a4-ee76d3f82914",
    "interaction_type": "UsageEvent",
    "table_name": "USAGE_EVENT",
    "database_name": "idev-01",
    "schema_name": "telco_sim",
    "timestamp_column": "EVENT_TS",
    "timestamp_column_type": "TIMESTAMP",
    "order_by_column": "EVENT_TS",
    "order_by_column_type": "TIMESTAMP",
    "attributes": [
      {
        "attribute_name": "PaymentID",
        "column_name": "PAYMENT_ID",
        "data_type": "STRING",
        "data_type_raw": "STRING"
      }
    ],
    "member_mappings": [
      {
        "member_type": "Individual",
        "column_name": "XW_INDIVIDUAL_ID",
        "data_type": "STRING",
        "data_type_raw": "STRING"
      }
    ],
    "schema_status": "VALID",
    "created_time": "2026-10-09T10:00:00",
    "updated_time": "2026-10-09T10:00:00"
  }
}

Error codes and recommended actions

The following table lists the possible error responses returned by this API.


HTTP status	Error code	Description	Recommended action
`400 Bad Request`	—	A mapped attribute does not exist in the selected Reltio interaction type.	Use an attribute configured for the interaction type.
	`TYPE_IS_NOT_FOUND`	The specified interaction type does not exist in the tenant.	Correct the interaction type name or create the type before saving the mapping.
	—	A mapped member type does not exist in the selected Reltio interaction type.	Use a member type configured for the interaction type.
	—	The mapped table or a referenced column does not exist or cannot be read.	Correct the source names and confirm that the service account in the BigQuery connection can read the table metadata.
	—	A mapped BigQuery column type is unsupported or incompatible with the Reltio interaction attribute type.	Map a compatible column or update the Reltio interaction attribute type.
`503 Service Unavailable`	—	Reltio cannot read the BigQuery table metadata.	Confirm BigQuery and IAM availability, and then retry the request.

Unify and manage your data