E043: Find or create contact for entity
POST /api/contacts/find-or-create
Combines lookup-by-name (and optional email) with conditional create and link. Triggered from quick-add flows on Customer or Vendor pages.
Authentication
Standard tenant route. Requires Authorization: Bearer <firebase-id-token> and X-Org-Id: <org-id>. Access: Member.
Request
{
"firstName": "Jane",
"lastName": "Doe",
"email": "jane@example.com",
"entityType": "customer",
"entityId": "uuid",
"role": "billing"
}
Matches an existing contact by (email, entityType, entityId); if found, returns it (created: false). Otherwise creates the contact, its primary email method, and the link (created: true). entityType is "customer" or "vendor". lastName and role are optional.
Response — 200 OK
{ "contact": Contact, "method": ContactMethod, "link": ContactEntityLink, "created": true }
created: false when the call matched an existing contact link.
Errors
| HTTP | code | Condition |
|---|---|---|
| 404 | not_found | Entity does not exist. |
| 422 | validation_failed | Email missing or invalid, or shape invalid. |