---
title: "Merge contacts"
method: POST
path: "/contacts/merge"
tags: ["contacts"]
---

# Merge contacts

`POST /contacts/merge`

## Request

- Base URL: `https://api.usepylon.com`
- URL: `https://api.usepylon.com/contacts/merge`
- Auth: HTTP bearer

Merges a contact into a surviving contact. Both contacts must belong to the same account, unless the merged contact has no account, in which case it is first moved to the surviving contact's account. Issues, emails, phone numbers, survey responses, and other associated data are then transferred to the surviving contact, and the merged contact is permanently deleted. This cannot be undone.

**Rate limit:** 30 requests per minute

## Request body

- MergeContactsRequest
  - `merge_contact_id` string, required: The ID of the contact to merge into the surviving contact. This contact is permanently deleted after its data is transferred.
  - `merge_into_contact_id` string, required: The ID of the contact that will survive the merge and receive the merged data. If the merged contact belongs to an account, this contact must belong to the same account.

## Response `200`

- MergeContactsResponseBody
  - `data` Contact, required
    - `account` MiniAccount
      - `external_ids` ExternalID[], nullable: External IDs associated with the account.
        - `external_id` string: The external ID. Must be unique per object type (ex. account).
        - `label` string: The label of the external ID. Must be unique per object.
      - `id` string, required: The ID of the account.
    - `avatar_url` string, required: Avatar URL of the contact.
    - `custom_fields` object, nullable: Custom field values associated with the contact.
    - `email` string: The primary email of the contact, if it exists.
    - `emails` string[], nullable: The list of all emails of the contact.
    - `external_ids` ExternalID[], nullable: External IDs associated with the contact.
      - `external_id` string: The external ID. Must be unique per object type (ex. account).
      - `label` string: The label of the external ID. Must be unique per object.
    - `id` string, required: The ID of the contact.
    - `integration_user_ids` IntegrationUserID[], nullable: Integration user IDs linking this contact to external systems.
      - `id` string, required: The user ID in the external system.
      - `source` string, required: The integration source (e.g., "slack", "intercom", "hubspot").
    - `name` string, required: The name of the contact.
    - `phone_numbers` string[], nullable: The list of all phone numbers of the contact.
    - `portal_role` string, required: Portal role slug assigned to the contact. For backwards compatibility. Known values: `no_access`, `member`, `admin`. This list is not exhaustive.
    - `portal_role_id` string: The ID of the custom portal role assigned to the contact.
    - `primary_phone_number` string: The primary phone number of the contact, if it exists.
  - `request_id` string, required: The request ID for tracking.

## Other responses

- `400`: The request was invalid or could not be completed.
- `401`: The request could not be authenticated for this API.
- `403`: The authenticated caller or organization is not allowed to access this endpoint or operation.
- `404`
- `429`: The request exceeded the applicable rate limit.
- `500`: An unexpected internal error occurred.

## Changes

- **2026-10-27** `554844ef05a1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/usepylon/apis/pylon-api/changes/contacts/merge/post.md)

---

[API](https://skmtc.dev/usepylon/apis/pylon-api.md) - [All operations](https://skmtc.dev/usepylon/apis/pylon-api/llms.txt) - [OpenAPI document](https://skmtc.dev/usepylon/apis/pylon-api/revisions/7d018a2a6265?raw)