Skip to Content

Merge contacts

Merges `from` into the contact in the path, within one organization and namespace.

POST
/v1/contacts/{id}/merge

Merges from into the contact in the path, within one organization and namespace. The kept contact wins profile and metadata conflicts, blank fields fill, and an explicit topic unsubscribe wins. The absorbed contact remains a record pointing to the kept contact; duplicate campaign recipients and other conflict history stay available. A merge cannot be undone. Agents use the merge-by-connection operation with their own verified connection instead of choosing a source contact.

Authorization

apiKey
headerx-api-key<token>

Path Parameters

id*string
Match^contact_[0-9a-hjkmnp-tv-z]{16,24}$

Header Parameters

x-samva-conversation-agent-admission?string

Request Body

application/json
  1. body
from*ContactId
Match^contact_[0-9a-hjkmnp-tv-z]{16,24}$

Response Body

Contact

application/json
  1. response
id*ContactId
Match^contact_[0-9a-hjkmnp-tv-z]{16,24}$
mergedInto?|null
namespaceId*|null
name*string
displayName*string|null
avatar*string|null
status*string
Value in"active""paused""blocked""archived"
statusReason*string|null
externalId*string|null
identities*array<>
profile*|null
preferences*|null
tags*array<string>
metadata*|null
importProvenance*|null
addedAt*string|null
createdAt*string
updatedAt*string
Example Request
import { createClient } from "samva";

const samva = createClient({ apiKey: process.env.SAMVA_API_KEY! });

const result = await samva.contacts.merge({
  "id": "example",
  "from": "example"
});
Example Response
{
  "id": "string",
  "mergedInto": "string",
  "namespaceId": "string",
  "name": "string",
  "displayName": "string",
  "avatar": "string",
  "status": "active",
  "statusReason": "string",
  "externalId": "string",
  "identities": [
    {
      "id": "string",
      "type": "email",
      "identifier": "string",
      "verified": true,
      "channels": [
        {
          "channel": "sms",
          "reachability": "unknown",
          "consent": {
            "status": "opted_in",
            "source": "string",
            "capturedAt": "string",
            "proof": {
              "property1": "string",
              "property2": "string"
            }
          }
        }
      ]
    }
  ],
  "profile": {
    "firstName": "string",
    "lastName": "string",
    "company": "string",
    "jobTitle": "string",
    "location": {
      "country": "string",
      "state": "string",
      "city": "string",
      "timezone": "string"
    },
    "customFields": {
      "property1": "string",
      "property2": "string"
    },
    "source": "api"
  },
  "preferences": {
    "preferredChannels": [
      "sms"
    ],
    "language": "string",
    "timezone": "string",
    "notifications": {
      "email": true,
      "sms": true,
      "whatsapp": true,
      "quiet_hours": {
        "start": "string",
        "end": "string"
      }
    }
  },
  "tags": [
    "string"
  ],
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "importProvenance": {
    "first": {
      "jobId": "string",
      "topicId": "string",
      "preset": "beehiiv",
      "importedAt": "string",
      "summary": {
        "permissionAssumed": true,
        "signupAt": {
          "value": "string",
          "kind": "time"
        },
        "sources": [
          "string"
        ],
        "omittedSources": 0
      },
      "evidence": [
        {
          "file": "string",
          "row": -9007199254740991,
          "declared": {
            "kind": "status_column"
          },
          "suppressionFree": true,
          "permissionBasis": "assumed",
          "sourceStatus": "string",
          "signupAt": "string",
          "source": "string"
        }
      ]
    },
    "latest": {
      "jobId": "string",
      "topicId": "string",
      "preset": "beehiiv",
      "importedAt": "string",
      "summary": {
        "permissionAssumed": true,
        "signupAt": {
          "value": "string",
          "kind": "time"
        },
        "sources": [
          "string"
        ],
        "omittedSources": 0
      },
      "evidence": [
        {
          "file": "string",
          "row": -9007199254740991,
          "declared": {
            "kind": "status_column"
          },
          "suppressionFree": true,
          "permissionBasis": "assumed",
          "sourceStatus": "string",
          "signupAt": "string",
          "source": "string"
        }
      ]
    }
  },
  "addedAt": "string",
  "createdAt": "string",
  "updatedAt": "string"
}

Related documentation