Back to all articlesAPI integration planning

Map record relationships when the two systems structure data differently

Alactic Editorial9 min read

Prepared with AI assistance by Alactic Editorial. Examples identified as hypothetical are illustrative, not customer results.

An enquiry arrives with an organisation object and two contacts nested inside it. The receiving system expects an enquiry record, an organisation reference and separate contact relationships. Mapping the enquiry subject and copying a contact name will not preserve that structure.

Before implementation, define which objects become records, how many relationships are allowed, which keys resolve references, and what happens when a required parent cannot be found. Also agree which transformations may change the shape without changing the meaning. That is the core of API nested object relationship mapping: preserving associations, not just moving values.

The filled worksheet below uses a fictional organisation, contacts and enquiries. It shows how to handle multiple related contacts and an unresolved organisation reference without silently dropping information or inventing a parent.

1. Separate record boundaries from field mappings

A nested object can mean several things: an independent business record, a snapshot of information at submission time, or descriptive data that belongs only to its enclosing record. Its position in a payload does not settle that question.

Start by listing the business objects and deciding what each represents in the destination. For an organisation inside an enquiry, ask whether it identifies an existing organisation, requests creation of a new organisation, or merely supplies a company name for that enquiry. Those interpretations require different behaviour.

Make the same distinction for contacts. A list of people might represent enquiry participants, organisation employees, notification recipients or some combination. Do not infer those relationships merely because the people appear underneath an organisation object.

  • Independent record: Has its own identity and can be referenced by other records.
  • Relationship: Connects records, possibly with attributes such as role or primary-contact status.
  • Snapshot: Preserves a value as it appeared on the enquiry, without necessarily updating a shared record.

A useful first deliverable is a sentence for every nested object: “This object represents X, becomes Y, and is linked through Z.” If the team cannot finish that sentence, field-level mapping is premature.

2. Write cardinality in both directions

“An enquiry has contacts” is not precise enough. Specify minimum and maximum participation on each side, distinguishing business rules from destination capabilities.

In the hypothetical design used here, each accepted enquiry belongs to exactly one organisation. An organisation may have no enquiries or many. An enquiry must have at least one related contact and may have several; a contact may participate in several enquiries. Each enquiry-contact relationship carries that person's role for that enquiry.

Organisation membership is a separate relationship. Being a participant in an enquiry does not automatically establish that someone belongs to its organisation. A consultant could participate without being an employee, for example.

If the destination supports only one contact reference on an enquiry, the source's contact array cannot be mapped faithfully into that field alone. Choose explicitly among these options:

  • Use a supported relationship collection or linking record to preserve every participant.
  • Use one primary-contact field plus another supported structure for additional participants.
  • Reject the unsupported structure for review until a suitable representation exists.
  • Accept a documented loss of structure, such as a readable snapshot, only if the business owner agrees that the lost relationships are unnecessary.

Selecting the first array item is not a neutral transformation. It discards relationships and assumes that array order expresses priority. Neither assumption should be introduced by implementation convenience.

3. Define the reference contract before writing records

A source identifier and a destination record ID are different things. A value such as ORG-104 might identify an organisation in the sending system, but the receiver may require its own internal organisation ID.

Document a reference contract for each entity. It should include the source system, entity type, external key, destination reference field and lookup scope. In this hypothetical design, the reference registry resolves the combination of workspace, source system, entity type and external key to one destination record ID. Including scope prevents unrelated records with similar keys from being treated as interchangeable.

Specify lookup outcomes rather than just the successful path:

  • One authorised match: Use its destination ID.
  • No match: Apply the missing-reference rule for that entity.
  • More than one match: Hold the affected enquiry as a reference-contract error; do not choose arbitrarily.
  • Reference unavailable or access denied: Stop that relationship operation and route it for appropriate review rather than substituting another record.

Reference resolution must not bypass access controls. OWASP's object-level authorisation guidance explains that access must be authorised for the requested object; knowing its ID is not sufficient. This is a design requirement to verify, not evidence about any particular product.

The worked example uses explicit external keys only. Deciding whether two people represent the same person, or whether records should be merged, is outside this mapping exercise.

4. Filled hypothetical relationship-mapping worksheet

Fictional worked example: Every record, identifier and destination capability in this section is hypothetical. The destination contract below is a proposed design, not a description of a specific product's API.

Input and destination assumptions

The source sends an enquiry with a nested organisation reference and an array of participant references. The destination is assumed to support separate organisation, contact and enquiry records, plus enquiry-contact links with role and primary-status attributes.

{
  "enquiryKey": "ENQ-701",
  "subject": "Request for installation planning",
  "organisation": { "organisationKey": "ORG-104" },
  "contacts": [
    { "contactKey": "CON-21", "role": "requester", "primary": true },
    { "contactKey": "CON-22", "role": "technical", "primary": false }
  ]
}

The fictional reference registry already maps ORG-104 to org_810, CON-21 to contact_221 and CON-22 to contact_222. A second enquiry, ENQ-702, refers to ORG-999, which has no registry entry.

Worksheet entry: organisation parent

  • Source path: organisation.organisationKey.
  • Meaning: Reference to the organisation responsible for the enquiry; not a request to create an organisation.
  • Destination: Enquiry's organisation reference.
  • Cardinality: Exactly one organisation per accepted enquiry; zero or many enquiries per organisation.
  • Reference requirement: Exactly one authorised organisation match within the agreed workspace and source scope.
  • Permitted transformation: Translate ORG-104 into org_810. Do not alter the external key's case or remove characters unless the key contract explicitly permits it.
  • Missing-parent rule: Hold the entire enquiry outside accepted destination records. Do not create a placeholder organisation or attach a default organisation.
  • Filled outcome: ENQ-701 can use org_810. ENQ-702 is held because ORG-999 is unresolved.

Worksheet entry: related contacts

  • Source path: Every entry in contacts[].
  • Meaning: People participating in this enquiry; no automatic assertion of organisation membership.
  • Destination: One enquiry-contact link per distinct supplied contact key.
  • Cardinality: One or many contacts per accepted enquiry; zero or many enquiries per contact.
  • Reference requirement: Each contact key must resolve to exactly one authorised contact record.
  • Relationship attributes: Preserve role and primary on the link, not on the shared contact record.
  • Permitted transformation: Expand the array into separate links. Require exactly one primary participant under this fictional business rule.
  • Failure rule: Hold the enquiry if a contact is unresolved, a role is unsupported, primary status is invalid or a contact key repeats. Repeated keys require clarification rather than silent consolidation.
  • Filled outcome: Link ENQ-701 to contact_221 as requester and primary, and to contact_222 as technical and non-primary.

Worksheet entry: enquiry identity and acceptance

  • Source key: enquiryKey, scoped to the source and workspace.
  • Destination: A separate enquiry record, with its external key retained through a supported field or registry.
  • Acceptance condition: Parent and participant references validate, required attributes are valid, and the complete intended relationship set is confirmed.
  • Repeat handling: Use the same enquiry identity and relationship identities on retry; do not treat the same event as a new enquiry.
  • Filled outcome: ENQ-701 is accepted only after its organisation reference and both contact links are confirmed. ENQ-702 remains held with reason UNRESOLVED_ORGANISATION.

5. Agree which transformations preserve meaning

Expanding a nested array into linking records changes structure without necessarily changing meaning. Flattening several contacts into one text field changes what the destination can do with the data. The worksheet should distinguish those outcomes.

For the fictional contract, external-key translation and array expansion are allowed. Role translation is allowed only through an agreed value map. An unrecognised role is held for review rather than converted to a convenient default.

Also define update semantics. An omitted field, an explicit null and an empty array should not acquire meaning accidentally. One hypothetical contract could specify:

  • Omitted contacts on an update: Leave existing participant links unchanged.
  • Empty contacts array: Reject because an accepted enquiry requires a participant.
  • Null organisation: Reject because the parent is required.
  • Non-empty contacts array: Treat as the complete intended participant set, with removal of absent links permitted only through the authorised update workflow.

That last choice has consequences: a partial participant list could remove valid relationships. If the source cannot reliably provide complete sets, use an explicitly incremental contract instead. Do not mix complete-set and incremental behaviour without a clear operation indicator.

6. Make held records recoverable, not invisible

Holding an enquiry protects relationship integrity but delays availability. Allowing an unlinked enquiry may improve immediate visibility while creating incomplete reporting or routing. Neither choice is universally correct; the business owner must decide whether an organisation reference is essential to acceptance.

For ENQ-702, the chosen rule is strict. Retain the source enquiry key, unresolved reference, intended relationship set, mapping version and a clear reason in an authorised review mechanism. Keep only the data needed for diagnosis and recovery.

The reviewer should determine whether the external key is incorrect, its reference registration is missing, or the organisation must be established through a separate authorised process. The mapping should not guess from a similar organisation name. Once the reference is corrected, revalidate the held enquiry before attempting the write.

Partial destination writes need a separate recovery rule. If the enquiry record exists but only one participant link was created, mark the operation incomplete. On retry, inspect the existing enquiry and links, then apply only the missing intended changes. Where the destination cannot support an all-or-nothing write, use a durable operation record and reconciliation process. Do not report acceptance merely because the enquiry record exists.

7. Test the relationship outcomes before implementation sign-off

Use the worksheet to create a small acceptance fixture rather than testing only successful field copies. The following cases are hypothetical test inputs, not performance results:

  1. Resolved parent and multiple contacts: Confirm one enquiry, the correct organisation reference, both participant links and exactly one primary participant.
  2. Unresolved parent: Confirm the enquiry is held, the missing key is visible to an authorised reviewer, and no placeholder organisation is created.
  3. Unresolved secondary contact: Confirm the enquiry is not accepted with that participant silently omitted.
  4. Invalid participant structure: Test repeated contact keys, unsupported roles and conflicting primary flags; confirm each produces an understandable reason.
  5. Repeated submission and interrupted write: Confirm recovery produces the intended enquiry and links without creating additional copies.
  6. Omitted, null and empty update values: Confirm each follows its documented rule rather than the implementation's default behaviour.
  7. Out-of-scope reference: Confirm a known but unauthorised record ID cannot be used to establish a relationship.

For the next mapping review, bring one representative payload and complete the worksheet for every relationship it contains. Record the expected destination references, links and hold reasons before any implementation work begins. Sign off when every test case has an explicit expected outcome and an owner for unresolved references—not when every source field merely has a destination column.

API integrationData mappingCRM operationsRelationship design

Put the next conversation to work.

Explore Alactic Communications for WhatsApp conversations, campaigns and AI-assisted workflows. Choose the product and plan that fit your team.

Explore Communications