W043: Find or create contact for entity

Dedupes a contact by email, then creates-and-links on miss. Triggered from quick-add flows on Customer or Vendor pages. entityType is customer or vendor; lastName and role are optional.

Steps

1. Verify the entity exists. Same routing as W039.

2. Try to match an existing contact by email. Look in this org for a contact already linked to the same (entityType, entityId) whose primary email method matches the supplied email. If found, return it with created: false.

3. Otherwise create the contact, its primary email method, and the link. Call Contacts.createContact, Contacts.addMethod for the supplied email (marked primary), then Contacts.linkToEntity. Return the new contact, method, and link with created: true.

Returns

{ contact, method, link, created }.

Business rules

• Email-based dedup. The match is keyed on email scoped to the target entity; no name-based merging.

Errors

• NotFoundError. The target entity was not found.
• ValidationError. The email is missing or invalid, or the request shape is invalid.