Create Interactions

Learn more about how to create interactions in Reltio Platform.

Reltio Intelligent 360

Use Interactions to create interactions in Reltio Platform. Specify interaction members by objectURI, crosswalk, or attributeMapping. Review the Interactions API overview to understand the interaction object structure before making requests.

HTTP method and endpoint

Use the following HTTP method and endpoint path to create interactions.

POST /services/reltio/api/{tenantId}/interactions

Access the API specification in the Create Interactions.

The following table describes the endpoint path parameters.


Parameter	Type	Required	Description
`tenantId`	String	Yes	The unique identifier of the tenant. Specifies the tenant context for the request. Example: `ce5627DYnQ6abcD`

Query parameters

The following table describes the query parameters and their values.


Parameter	Type	Required	Description	Accepted values / Default
`crosswalkValue`	String	No	The identifier of the interaction object in the source system. Use this parameter when the request body does not include a crosswalk.	Any valid source system identifier. Example: `INT_001`. Default: not set
`returnObjects`	Boolean	No	Specifies whether the response includes the full created interaction objects. Set to `false` to return only the object URIs.	`true` or `false`. Default: `true`
`options`	String	No	Includes or excludes hidden attributes in the response using the `sendHidden` option. Hidden attributes are excluded by default.	`sendHidden`. Default: disabled

Request headers

The following request headers must be included.


Header	Value	Required
`Authorization`	`Bearer <access_token>`	Yes
`Source-System`	The source system this request represents. For example, `configuration/sources/Reltio` indicates data created directly in Reltio Platform.	No
`Content-Type`	`application/json`	Yes

Request body

The following table describes the request body parameters required to create interactions. Each object must include the type property. Reltio generates the URI and crosswalks properties if they are not included in the request.


Parameter	Type	Required	Description	Accepted values / Default
`type`	String	Yes	The interaction type URI.	Valid interaction type URI configured in the tenant. Example: `configuration/interactionTypes/Lunch`
`timestamp`	Number	No	The timestamp of when the interaction occurred, in epoch milliseconds.	Any valid epoch milliseconds value. Example: `1338580800000`. Default: not set
`attributes`	Object	No	Interaction-level attributes grouped by attribute configuration. Structure varies by interaction type.	Key-value pairs where each key is an attribute name and the value is an array of attribute objects. Default: not set
`members`	Object	No	The entities involved in the interaction, grouped by member type. Specify members by `objectURI` or crosswalk. Omit this field when `attributeMapping` is configured on the member type, or when `minOccurs` is `0` for all member types.	Object containing member type keys with nested `members` arrays. Default: not set

Note: Interactions must have unique crosswalk values across all uploads. Uploading interactions with duplicate crosswalkValue entries results in indexing errors and unexpected behavior in search results.

Example request

The following examples show how to structure requests for creating interactions using different member specification methods. The response structure remains the same across methods, with the members field reflecting the resolved entities.

Create an interaction using objectURI:

POST /services/reltio/api/{tenantId}/interactions
[
  {
    "type": "configuration/interactionTypes/Lunch",
    "timestamp": 1338580800000,
    "attributes": {
      "Place": [ { "value": "Shire, Bag End in Hobbiton" } ],
      "Notes": [ { "value": "All participants eat Lembas" } ]
    },
    "members": {
      "Organizers": {
        "type": "configuration/interactionTypes/Meeting/memberTypes/Organizers",
        "members": [ { "objectURI": "entities/30000" } ]
      },
      "Chefs": {
        "type": "configuration/interactionTypes/Lunch/memberTypes/Chefs",
        "members": [ { "objectURI": "entities/40000" } ]
      },
      "Participants": {
        "type": "configuration/interactionTypes/Meeting/memberTypes/Participants",
        "members": [
          { "objectURI": "entities/10000" },
          { "objectURI": "entities/10001" },
          { "objectURI": "entities/10003" }
        ]
      }
    }
  }
]

Create an interaction using crosswalks:

POST /services/reltio/api/{tenantId}/interactions
[
  {
    "type": "configuration/interactionTypes/Lunch",
    "timestamp": 1338580800000,
    "attributes": {
      "Place": [ { "value": "Shire, Bag End in Hobbiton" } ],
      "Notes": [ { "value": "All participants eat Lembas" } ]
    },
    "members": {
      "Organizers": {
        "type": "configuration/entityTypes/Organizers",
        "members": [
          { "crosswalks": [ { "type": "configuration/sources/Salesforce", "value": "EMP_600000" } ] }
        ]
      },
      "Chefs": {
        "type": "configuration/entityTypes/Chefs",
        "members": [
          { "crosswalks": [ { "type": "configuration/sources/Salesforce", "value": "EMP_1000072" } ] }
        ]
      }
    }
  }
]

Creating an interaction with an existing crosswalk returns an error. Interactions are immutable. To update an interaction, delete the existing one and create a new one. For error details and the error response structure, see Error codes and recommended actions.

Create an interaction using attributeMapping. Reltio resolves the HCO member automatically by matching the EXHBT_NAME attribute value against the Name attribute of the HCO entity type, based on the attributeMapping configured in the interaction type definition:

POST /services/reltio/api/{tenantId}/interactions
[
  {
    "type": "configuration/interactionTypes/ExhibitionEvent",
    "timestamp": 1780576191519,
    "attributes": {
      "EXHBT_NAME": [
        {
          "type": "configuration/interactionTypes/ExhibitionEvent/attributes/EXHBT_NAME",
          "value": "ForAttributeInteraction"
        }
      ]
    }
  }
]

Response body

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


Parameter	Type	Description
`index`	Number	The index of the interaction object in the request array. This is a required property in the response.
`URI`	String	URI of the created interaction. Returned only if the object was created successfully.
`error`	Object	Error details if the object could not be created. Contains the details of the problem and is returned only when creation fails.
`warning`	String	Indicates the object was created but with issues.
`status`	String	Result of the API request. Possible values: `OK`, `failed`.

Example response

The response structure is consistent across all creation methods. The members field reflects the entities resolved based on the approach used.

Response for objectURI and crosswalks:

[
  {
    "index": 0,
    "URI": "interactions/01BThVh",
    "object": {
      "URI": "interactions/01BThVh",
      "type": "configuration/interactionTypes/Lunch",
      "createdBy": "User",
      "createdTime": 1354626947723,
      "updatedTime": 1354626947723,
      "timestamp": 1338580800000,
      "attributes": {
        "Place": [
          {
            "type": "configuration/interactionTypes/Meeting/attributes/Place",
            "value": "Shire, Bag End in Hobbiton",
            "URI": "interactions/01BThVh/attributes/Place/6"
          }
        ],
        "Notes": [
          {
            "type": "configuration/interactionTypes/Meeting/attributes/Notes",
            "value": "All participants eat Lembas",
            "URI": "interactions/01BThVh/attributes/Notes/7"
          }
        ]
      },
      "crosswalks": [
        {
          "URI": "interactions/01BThVh/crosswalks/8",
          "type": "configuration/sources/MDM",
          "value": "",
          "attributes": [
            "interactions/01BThVh/attributes/Notes/7",
            "interactions/01BThVh/attributes/Place/6"
          ]
        }
      ],
      "members": {
        "Organizers": {
          "URI": "interactions/01BThVh/members/Organizers",
          "type": "configuration/interactionTypes/Meeting/memberTypes/Organizers",
          "members": [
            { "objectURI": "entities/30000", "type": "configuration/entityTypes/Individual", "label": "John Smith" }
          ]
        },
        "Chefs": {
          "URI": "interactions/01BThVh/members/Chefs",
          "type": "configuration/interactionTypes/Lunch/memberTypes/Chefs",
          "members": [
            { "objectURI": "entities/40000", "type": "configuration/entityTypes/Individual", "label": "Ann Roman" }
          ]
        },
        "Participants": {
          "URI": "interactions/01BThVh/members/Participants",
          "type": "configuration/interactionTypes/Meeting/memberTypes/Participants",
          "members": [
            { "objectURI": "entities/10000", "type": "configuration/entityTypes/Individual", "label": "San Dunn" },
            { "objectURI": "entities/10001", "type": "configuration/entityTypes/Individual", "label": "Josh May" },
            { "objectURI": "entities/10003", "type": "configuration/entityTypes/Individual", "label": "Marc Jack" }
          ]
        }
      }
    },
    "status": "OK"
  }
]

Response for an interaction created using attributeMapping. Reltio populates the members block based on the resolved attribute value:

[
  {
    "index": 0,
    "URI": "interactions/0OLT9CG",
    "object": {
      "URI": "interactions/0OLT9CG",
      "type": "configuration/interactionTypes/ExhibitionEvent",
      "createdBy": "User",
      "createdTime": 1780576191495,
      "updatedTime": 1780576191495,
      "timestamp": 1780576191519,
      "attributes": {
        "EXHBT_NAME": [
          {
            "type": "configuration/interactionTypes/ExhibitionEvent/attributes/EXHBT_NAME",
            "value": "ForAttributeInteraction",
            "URI": "interactions/0OLT9CG/attributes/EXHBT_NAME/0"
          }
        ]
      },
      "members": {
        "HCO": {
          "URI": "interactions/0OLT9CG/members/HCO",
          "type": "configuration/interactionTypes/ExhibitionEvent/memberTypes/HCO",
          "members": [
            {
              "objectURI": "entities/0UYXYk4",
              "type": "configuration/entityTypes/HCO",
              "label": "ForAttributeInteraction"
            }
          ]
        }
      }
    },
    "status": "OK"
  }
]

Reltio resolves members only when the mapped interaction attribute is present in the request body. If the attribute is absent, no members are resolved for that member type. In that case, the minOccurs property on the member type determines the outcome. The minOccurs property specifies the minimum number of members required for a member type and is configured in the interaction types. If minOccurs is 0, Reltio creates the interaction with zero resolved members. If minOccurs is greater than 0, the interaction load fails.

Error codes and recommended actions


HTTP status	Description	Recommended action
`200` with `successful: false`, error code `536`	An interaction with the specified crosswalk already exists.	Delete the existing interaction and create a new one. Interactions are immutable. For more information, see Delete Interaction.
`200` with `successful: false`, error code `38010`	The mapped interaction attribute value did not match any entity of the configured type.	Verify that the attribute value in the request body matches at least one entity. Check the `attributeMapping` configuration in the interaction type.
`200` with `successful: false`, error code `38011`	The mapped interaction attribute value matched more than one entity.	Ensure the attribute value in the request body uniquely identifies a single entity. Each attribute value must resolve to exactly one entity.

The following example shows the error response returned when an interaction with an existing crosswalk is submitted.

[
  {
    "index": 0,
    "errors": {
      "severity": "Error",
      "errorMessage": "Interaction with specified system configuration/sources/AMA and value TEST already exists.",
      "errorCode": 536,
      "errorDetailMessage": "Failed to create interaction, because such crosswalk already exists. System and value parameters pair should be unique."
    },
    "successful": false
  }
]

Unify and manage your data