Merge contacts
Combine duplicate contacts, preserve their identities and history, and use a verified connection to link an agent conversation to an email contact.
Use a contact merge when the same person has separate records, such as a WhatsApp contact and an email contact. Choose which contact to keep, then merge the other contact into it. Both contacts must belong to the same organization and namespace.
Merge known contacts
import { createClient } from "samva";
const samva = createClient({ apiKey: process.env.SAMVA_API_KEY! });
const contact = await samva.contacts.merge({
id: "contact_kept",
from: "contact_duplicate",
});The CLI exposes the same operation:
samva contacts merge contact_kept --from contact_duplicate --yesThe kept contact receives the other contact's identities and activity. Its populated profile and metadata values win conflicts; missing values fill from the other contact. Existing unsubscribes remain effective. When both contacts have an active run in the same journey, the older run continues. Runs for different Shopify orders continue separately. For conflicting connections, a working connection wins over an expired or revoked one; otherwise the newer connection wins.
The absorbed contact remains part of the history. Fetching its id resolves to the kept contact with a merge marker. Agent memory searches include facts remembered under either contact. A merge cannot be undone.
See the merge API reference for the request, response, and errors.
Link an agent conversation through a verified connection
A hosted agent calls merge_verified_contact with the integrationId shown for its connected contact integration. Samva resolves that conversation's active account and supplies the current turn's signed admission. The agent never chooses a contact id or supplies an email address.
Samva verifies that the connection belongs to the conversation's contact and has a verified email address, then finds the contact holding that address in the same organization and namespace. An unverified email, another contact's connection, or a connection outside the organization is refused. If no contact holds the verified address, Samva attaches the identity to the conversation's contact.
The API exposes this proof operation separately as POST /v1/contacts/{id}/merge-by-connection with { connection }. In the Promise SDK, call samva.contacts.mergeByConnection({ id, connection }) with the current conversation admission in the x-samva-conversation-agent-admission header. The server derives the other contact from the verified connection; the request never supplies an email address. See the verified connection merge reference.
The hosted MCP tool is contacts_merge. Supply id and from to merge known contacts. OAuth calls require the owner's approval before the merge runs.