What is the best practice for populating a reference attribute?

Question

Can a reference attribute be created and populated in a single API call, or is it necessary to first create the referenced entity and then create a relation using two separate calls?

Answer

Yes, you can populate a reference attribute in a single request. Instead of making two separate API calls—one to create the entity and another to create the relation—you can create the main entity and define the reference attribute inline within the same payload.

Use the following endpoint:

POST /entities

This allows you to:

• Create the main entity
• Include the referenced entity via the refEntity field
• Define the relation using the refRelation field

The display and handling of reference attributes depend on the attribute configuration in the tenant’s L3 configuration.

Example Payload

[
  {
    "type": "configuration/entityTypes/HCP",
    "attributes": {
      "Salary": [{ "value": "10000" }],
      "Department": [{ "value": "sales" }],
      "Address": [
        {
          "value": {
            "Zip": [
              {
                "value": {
                  "Zip4": [{ "value": "641662" }],
                  "Zip5": [{ "value": "Zip" }]
                }
              }
            ],
            "AddressLine1": [{ "value": "101 BOB WALLACE AVE SW" }],
            "StateProvince": [{