persons

Split distinct_ids off a merged person. Two mutually exclusive modes:

  • distinct_ids_to_split (recommended for surgical edits): moves only the listed distinct_ids off this person onto new single-id persons. The original person keeps every other distinct_id and its properties.
  • main_distinct_id: keeps only the specified distinct_id on this person; moves every other distinct_id off onto its own new person. If omitted, the first distinct_id is kept.

The original person always retains its properties. To clear individual properties afterward, use the delete_property endpoint.

The split runs asynchronously: a 201 response means the task was enqueued. Newly-created split-off persons get a deterministic UUID derived from (team_id, distinct_id), so they can be located client-side without polling. If you need to delete a split-off person after this call, prefer looking it up by that deterministic UUID rather than by distinct_id, since the latter still resolves to the original merged person until the async task completes.

post/api/projects/{project_id}/persons/{id}/split/

Request

  • Base URL: https://us.posthog.com
  • URL: https://us.posthog.com/api/projects/{project_id}/persons/{id}/split/
  • Auth: HTTP bearer

Path parameters

idstring required

A unique value identifying this person. Accepts both numeric ID and UUID.

project_idstring required

Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

format'csv' | 'json'

Request body

main_distinct_idstring nullable

The distinct_id to keep on this person; every other distinct_id is moved to its own new single-id person. If omitted, the first distinct_id on the person is kept. The original person always retains its properties; to clear individual properties afterward, use the delete_property endpoint. To surgically remove one or more distinct_ids while leaving the merge intact, use distinct_ids_to_split instead — these parameters are inverses of each other and cannot be combined.

distinct_ids_to_splitstring[] nullable

List of distinct_ids to move off this person onto new single-id persons. The original person keeps every other distinct_id and its properties. New persons are created with deterministic UUIDs derived from (team_id, distinct_id). Cannot be combined with main_distinct_id.

Response

successboolean required

Always true when the split task was enqueued. The split itself runs asynchronously — a 201 response means the task was accepted, not that the merge state has already been updated.

Changes

No recorded changes to this operation across all 1 revision of this API.