Create Link Between Parent and Child Record

Overview

Creates a new link association between a parent record and a child record, or updates an existing link if one already exists for the same parent/child pair. Returns the link ID and resolved record IDs upon success.

Record Identification

Parent and child records can be identified in two ways:

1. By primary key (preferred): Provide ParentRecordID or ChildRecordID.
2. By match field: Provide both a key value and a field name (e.g., ParentRecordKey=POL-2026-001 + ParentRecordMatchField=PolicyNumber). Only text or numeric fields are accepted. Association fields are not allowed.

If both a primary key and a match field are provided for the same side, the primary key takes priority and the match field is ignored.

For Upsert, you must identify one parent record AND one child record

Preconditions

• The authenticated user must have the appropriate permission on the parent domain (Attach Contacts for Contact links, Attach Files for File links, Edit for all others).
• ChildDomain must be "Contact" or "File".
• Either ParentRecordID or both ParentRecordKey and ParentRecordMatchField must be provided.
• Either ChildRecordID or both ChildRecordKey and ChildRecordMatchField must be provided.

Notes

• If a link already exists between the specified parent and child, the existing link is updated rather than creating a duplicate.
• Relationship and NewRelationship are only applicable when ChildDomain is Contact. These fields are ignored for File links.

Relationship Behavior

Because this endpoint is overload to support both insert and update (id, upsert operations), the role of Relationship and NewRelationship depends on whether the operation results in an insert or an update:

Examples

Scenario 1: Link a contact to a claim by primary keys:

POST /api/Link/Upsert
Content-Type: application/json

{
  "ParentDomain": "Claim",
  "ParentRecordID": 5001,
  "ChildDomain": "Contact",
  "ChildRecordID": 2001,
  "Relationship": "Adjuster"
}

200 OK
{
  "IsSuccessful": true,
  "RecordID": 101,
  "Message": "Inserted link with id 101 successfully.",
  "ParentID": 5001,
  "ChildID": 2001,
  "RelationshipID": 3
}

Scenario 2: Upsert using match fields (update existing link's relationship):

POST /api/Link/Upsert
Content-Type: application/json

{
  "ParentDomain": "Policy",
  "ParentRecordKey": "POL-2026-001",
  "ParentRecordMatchField": "PolicyNumber",
  "ChildDomain": "Contact",
  "ChildRecordID": 2001,
  "Relationship": "Adjuster",
  "NewRelationship": "Underwriter"
}

200 OK
{
  "IsSuccessful": true,
  "RecordID": 101,
  "Message": "Updated link with id 101 successfully.",
  "ParentID": 67890,
  "ChildID": 2001,
  "RelationshipID": 3
}

Scenario 3: Parent record cannot be found:

POST /api/Link/Upsert
Content-Type: application/json

{
  "ParentDomain": "Claim",
  "ParentRecordKey": "NONEXISTENT",
  "ParentRecordMatchField": "ClaimNumber",
  "ChildDomain": "Contact",
  "ChildRecordID": 2001
}

500 Internal Server Error
"Unable to execute. Unable to identify the parent record based on the information provided."