Dex Guide
Dex Dashboard
Companies

Merge companies

Merge up to 50 source companies (`source_ids`) into `target_id`: contacts, roles, tags, custom field values and links, views, favorites, org chart members and saved view filters move to the target, an

POST /v2/companies/merge

Parameters

Header parameters

Idempotency-Key
string required
Required. UUID per logical operation, reused on every retry. See apps/rest-api/src/shared/idempotency.ts for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict.

Request body

Content-Type: application/json

target_id
string (uuid) required
source_ids
array<string (uuid)> required
field_choices
object
confirm_archived_target
boolean

Example

{
  "target_id": "00000000-0000-0000-0000-000000000000",
  "source_ids": [
    "00000000-0000-0000-0000-000000000000"
  ]
}

Responses

200 — Successful response

Content-Type: application/json

data
object required
data.company
object required
data.company.id
string (uuid) required
data.company.user_id
string required
data.company.workspace_id
string (uuid) | null required
data.company.assignee_id
string | null required
data.company.name
string required
data.company.description
string | null required
data.company.linkedin_description
string | null required
data.company.logo_url
string | null required
data.company.logo_source
string enum required
Possible values: "upload", "auto", "dismissed"
data.company.logo_source_domain
string | null required
data.company.website_url
string | null required
data.company.linkedin_slug
string | null required
data.company.facebook_slug
string | null required
data.company.x_slug
string | null required
data.company.instagram_slug
string | null required
data.company.headquarters_location
string | null required
data.company.country_code
string | null required
data.company.email
string | null required
data.company.phone_number
string | null required
data.company.arr_estimate
integer | null required
data.company.number_of_employees
integer | null required
data.company.linkedin_data
object | null required
data.company.linkedin_data.industry
string | null
data.company.linkedin_data.company_type
string | null
data.company.linkedin_data.size_range
string | null
data.company.linkedin_data.specialities
array<string>
data.company.linkedin_data.founded_year
integer | null
data.company.linkedin_data.tagline
string | null
data.company.linkedin_data.linkedin_url
string | null
data.company.linkedin_data.linkedin_internal_id
string | null
data.company.linkedin_data.follower_count
integer | null
data.company.linkedin_data.provider
string | null
data.company.linkedin_data.fetched_at
string | null
data.company.ignore_merge
boolean required
data.company.name_is_placeholder
boolean required
data.company.archived_at
string (date-time) required
data.company.geocode_attempts
integer
data.company.geocode_failed_at
string (date-time)
data.company.created_at
string (date-time) required
data.company.updated_at
string (date-time) required
data.company.companies_custom_fields
array<object> required
data.company.companies_custom_fields[].custom_field_id
string (uuid) required
data.company.companies_custom_fields[].text_value
string | null required
data.company.companies_custom_fields[].array_value
array<string> required
data.company.companies_custom_fields[].date_value
string (date-time) required
data.company.companies_custom_fields[].member_user_id
string | null required
data.company.companies_custom_fields[].number_value
number | null required
data.company.companies_custom_fields[].boolean_value
boolean | null required
data.company.companies_custom_fields_contacts
array<object> required
data.company.companies_custom_fields_contacts[].custom_field_id
string (uuid) required
data.company.companies_custom_fields_contacts[].linked_contact_id
string (uuid) required
data.company.companies_custom_fields_companies
array<object> required
data.company.companies_custom_fields_companies[].custom_field_id
string (uuid) required
data.company.companies_custom_fields_companies[].linked_company_id
string (uuid) required
data.company.tag_ids
array<string (uuid)> required
data.merge_log_id
string (uuid) required

Example

{
  "data": {
    "company": {
      "id": "00000000-0000-0000-0000-000000000000",
      "user_id": "string",
      "workspace_id": "00000000-0000-0000-0000-000000000000",
      "assignee_id": "string",
      "name": "string",
      "description": "string",
      "linkedin_description": "string",
      "logo_url": "string",
      "logo_source": "upload",
      "logo_source_domain": "string",
      "website_url": "string",
      "linkedin_slug": "string",
      "facebook_slug": "string",
      "x_slug": "string",
      "instagram_slug": "string",
      "headquarters_location": "string",
      "country_code": "string",
      "email": "string",
      "phone_number": "string",
      "arr_estimate": 0,
      "number_of_employees": 0,
      "linkedin_data": {
        "industry": "string",
        "company_type": "string"
      },
      "ignore_merge": false,
      "name_is_placeholder": false,
      "archived_at": "2026-11-13T08:29:48.848Z",
      "created_at": "2026-11-13T08:29:48.848Z",
      "updated_at": "2026-11-13T08:29:48.848Z",
      "companies_custom_fields": [
        {
          "custom_field_id": "00000000-0000-0000-0000-000000000000",
          "text_value": "string",
          "array_value": [
            "string"
          ],
          "date_value": "2026-11-13T08:29:48.848Z",
          "member_user_id": "string",
          "number_value": 0,
          "boolean_value": false
        }
      ],
      "companies_custom_fields_contacts": [
        {
          "custom_field_id": "00000000-0000-0000-0000-000000000000",
          "linked_contact_id": "00000000-0000-0000-0000-000000000000"
        }
      ],
      "companies_custom_fields_companies": [
        {
          "custom_field_id": "00000000-0000-0000-0000-000000000000",
          "linked_company_id": "00000000-0000-0000-0000-000000000000"
        }
      ],
      "tag_ids": [
        "00000000-0000-0000-0000-000000000000"
      ]
    },
    "merge_log_id": "00000000-0000-0000-0000-000000000000"
  }
}

400 — Request body failed validation.

Content-Type: application/json

(body)
any

401 — Missing or invalid API key.

Content-Type: application/json

(body)
any

403 — Valid key, insufficient permission.

Content-Type: application/json

(body)
any

404 — Resource does not exist.

Content-Type: application/json

(body)
any

409 — Request conflicts with the current state of the resource.

Content-Type: application/json

(body)
any

429 — Rate limit exceeded.

Content-Type: application/json

(body)
any

500 — Unexpected server error.

Content-Type: application/json

(body)
any

Code samples

curl https://api.prod.getdex.com/v2/companies/merge \
  --request POST \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header "Idempotency-Key: $(uuidgen 2>/dev/null || python3 -c 'import uuid;print(uuid.uuid4())')" \
  --header 'Content-Type: application/json' \
  --data '{
  "target_id": "00000000-0000-0000-0000-000000000000",
  "source_ids": [
    "00000000-0000-0000-0000-000000000000"
  ]
}'

Set one custom field on companies in bulk

Write one value (`custom_field_id` and exactly one value key) to up to 100 companies (`company_ids`) or one page of a frozen selection. A selection page is `{ selection_id, offset, limit? }` from `POS

Dismiss a possible duplicate

Mark a pair "not a duplicate" so it stops being suggested, including when enrichment finds it again. The body is `{ company_ids: [idA, idB] }`, in either order; two equal ids are 400 `validation_error

Copyright © 2026