Create Interactions

Learn more about how to create interactions in Reltio Platform.

Reltio Intelligent 360

The Interactions creates 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.

When you create an interaction, Reltio checks that you have READ access to each member. For a member identified by objectURI or crosswalk, Reltio checks that you have READ access to the member's entity type. For a member resolved through attributeMapping, Reltio checks that you have READ access to the mapped entity attribute.

If you lack READ access to any member, Reltio rejects the interaction. Use the Set Permissions endpoint to grant READ access to the members for the roles that create interactions.

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. Reltio resolves members from an `objectURI`, a crosswalk, or an attribute mapping. List `objectURI` and crosswalk members in this field. Omit `members` when every member type resolves through its attribute mapping, 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"
  }
]

When your request includes a value for the mapped interaction attribute, Reltio searches for an entity whose mapped entity attribute has the same value, and adds it as a member:

One match: Reltio adds that entity as a member.
No match, or more than one: Reltio doesn't create the interaction and returns an error.
Several values on the mapped interaction attribute: Reltio searches for each value separately, and each value must match exactly one entity.

Reltio adds the resolved members to the members you list by objectURI or crosswalk. If a search fails, Reltio rejects the request even when the listed members are valid.

When your request does not include a value for the mapped interaction attribute, Reltio resolves no members for that member type and compares minOccurs with the members you list for it. If minOccurs is 0, Reltio creates the interaction with no resolved members. If you list fewer members than minOccurs requires, Reltio doesn't create the interaction.

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