From 6197c51601c0afe5e86f4d105ea7aebf8c475034 Mon Sep 17 00:00:00 2001 From: pwseg Date: Thu, 6 Nov 2025 20:53:55 -0600 Subject: [PATCH 01/15] init --- .../identity-resolution/delete-profile-identifier-api.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 src/unify/identity-resolution/delete-profile-identifier-api.md diff --git a/src/unify/identity-resolution/delete-profile-identifier-api.md b/src/unify/identity-resolution/delete-profile-identifier-api.md new file mode 100644 index 0000000000..936208c252 --- /dev/null +++ b/src/unify/identity-resolution/delete-profile-identifier-api.md @@ -0,0 +1,5 @@ +--- +title: Delete Profile Identifier API +plan: unify +hidden: true +--- \ No newline at end of file From 68ebf29eeb2bd9e14e912191bd97acbed599bd91 Mon Sep 17 00:00:00 2001 From: pwseg Date: Thu, 6 Nov 2025 21:01:36 -0600 Subject: [PATCH 02/15] add prerequisites section --- .../delete-profile-identifier-api.md | 38 ++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/src/unify/identity-resolution/delete-profile-identifier-api.md b/src/unify/identity-resolution/delete-profile-identifier-api.md index 936208c252..428112f396 100644 --- a/src/unify/identity-resolution/delete-profile-identifier-api.md +++ b/src/unify/identity-resolution/delete-profile-identifier-api.md @@ -2,4 +2,40 @@ title: Delete Profile Identifier API plan: unify hidden: true ---- \ No newline at end of file +--- + +The Delete Profile Identifier API removes identifiers from a profile while preserving the profile's history, including traits, events, and merge history. + +Use this API to clean up outdated or incorrectly added identifiers without deleting entire profiles and replaying events. + +## Use cases + +Remove identifiers that shouldn't be associated with a profile: + +- Remove mistakenly imported identifiers, like incorrect email addresses, to prevent inaccurate targeting in downstream tools. +- Clean up obsolete identifiers after database migrations or system changes. +- Transfer identifiers with a short lifespan between profiles. For example, when a user changes phone numbers or when a prepaid service expires, you can remove the phone number from one profile and add it to another. +- Fix profiles that violate [ID Resolution limits](). Remove old identifiers to bring profiles into compliance with your configured limits. +- Revert misconfigured identity resolution settings. For example, if you reduced the `user_id` limit from 3 to 1, remove extra `user_id` values to resolve discrepancies between Segment and downstream tools like Braze or Amplitude. + +## Before you begin + +During private beta, the Delete Profile Identifier API is available to Unify and Engage. + +You must have one of the following role permissions to delete identifiers: + +- Workspace Owner +- Identity Admin +- Unify and Engage Admin + +For more information, see [the Roles documentation](/docs/segment-app/iam/roles/). + +### Profiles Sync configuration + +If you use [Profiles Sync](/docs/unify/profiles-sync/overview/), complete these steps before using the Delete Profile Identifier API: + +1. Add the `__operation` column to the `external_id_mapping_updates` table schema in your data warehouse: + - Default value: `CREATED` + - Deleted value: `REMOVED` +2. Verify that your analytics workloads (BI tools, data pipelines, ML models) can handle deleted identifiers. Make sure these systems remain operational and account for the `REMOVED` flag. + From 0f32c0b775dd0eca39d1d4a28e49bee72c4f02a4 Mon Sep 17 00:00:00 2001 From: pwseg Date: Thu, 6 Nov 2025 21:04:13 -0600 Subject: [PATCH 03/15] explain deletion process --- .../delete-profile-identifier-api.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/src/unify/identity-resolution/delete-profile-identifier-api.md b/src/unify/identity-resolution/delete-profile-identifier-api.md index 428112f396..322569fbf4 100644 --- a/src/unify/identity-resolution/delete-profile-identifier-api.md +++ b/src/unify/identity-resolution/delete-profile-identifier-api.md @@ -39,3 +39,16 @@ If you use [Profiles Sync](/docs/unify/profiles-sync/overview/), complete these - Deleted value: `REMOVED` 2. Verify that your analytics workloads (BI tools, data pipelines, ML models) can handle deleted identifiers. Make sure these systems remain operational and account for the `REMOVED` flag. + + +## How deletion works + +When you delete an identifier, Segment removes it from [Identity Resolution](/docs/unify/identity-resolution/) and propagates the change through connected systems. + +The Delete Profile Identifier API confirms that Segment deleted the identifier from the Real-Time Identity Graph. Deletion then propagates to other systems: + +1. Real-time Profile storage**: The Profile API and Profile explorer delete the identifier in near real time. +2. Batch Profile Data lakehouse: Segment soft-deletes the identifier (flags it as deleted) in the append-only table within minutes. The identifier filters out from the materialized view within 24 hours. +3. Customer data warehouse: Profile Sync sends a deletion notification to your warehouse. The `external_id_mapping_updates` table shows the identifier with `__operation` set to `REMOVED`. The `user_identifiers` materialized view filters out removed identifiers. + + \ No newline at end of file From 140762ddaae440e35d79ee958f3d6b9acfe58124 Mon Sep 17 00:00:00 2001 From: pwseg Date: Thu, 6 Nov 2025 21:07:55 -0600 Subject: [PATCH 04/15] add responses --- .../delete-profile-identifier-api.md | 83 ++++++++++++++++++- 1 file changed, 82 insertions(+), 1 deletion(-) diff --git a/src/unify/identity-resolution/delete-profile-identifier-api.md b/src/unify/identity-resolution/delete-profile-identifier-api.md index 322569fbf4..44bf9a867a 100644 --- a/src/unify/identity-resolution/delete-profile-identifier-api.md +++ b/src/unify/identity-resolution/delete-profile-identifier-api.md @@ -51,4 +51,85 @@ The Delete Profile Identifier API confirms that Segment deleted the identifier f 2. Batch Profile Data lakehouse: Segment soft-deletes the identifier (flags it as deleted) in the append-only table within minutes. The identifier filters out from the materialized view within 24 hours. 3. Customer data warehouse: Profile Sync sends a deletion notification to your warehouse. The `external_id_mapping_updates` table shows the identifier with `__operation` set to `REMOVED`. The `user_identifiers` materialized view filters out removed identifiers. - \ No newline at end of file + + +## Delete an identifier + +You can only delete identifiers from known profiles. The API requires a valid `user_id` to locate the profile. + +The API returns an error if you try to delete: + +- All `user_id` values from a profile. Profiles must have at least one `user_id`. +- A `group_id` identifier. The API only supports individual profiles. + +### API request format + +The API accepts one identifier per request. + +**Endpoint**: +``` +POST https://{HOST_NAME}/v1/spaces/{SPACE_ID}/collections/users/profiles/user_id:{USER_ID_VALUE}/external_ids/delete +``` + +**Parameters**: + +| Parameter | Description | +| ----------------- | ---------------------------------------------------------------------------------------------------- | +| **HOST_NAME** | `profiles.segment.com` for North America workspaces or `profiles.euw1.segment.com` for EU workspaces | +| **SPACE_ID** | Your space ID. Find this in **Unify > Settings > API access** | +| **USER_ID_VALUE** | The `user_id` value that identifies the profile | +| **AUTH_TOKEN** | Your access token. Generate this in **Unify > Settings > API access** | + +**Request body**: + +| Field | Description | +| ----------------------- | ------------------------------------------------------------------------------ | +| **delete_external_ids** | Array containing the identifier to delete. Limit: 1 identifier per request | +| **id** | Value of the identifier to delete (for example, `hello@gmail.com`) | +| **type** | Type of identifier to delete (for example, `email`, `anonymous_id`, `user_id`) | + + + +### Example request + +First, base64-encode your access token with a trailing colon: + +```bash +echo -n 'your_token:' | base64 +``` + +Then send the delete request: + +```bash +curl --location --request POST 'https://profiles.segment.com/v1/spaces/spa_abc123/collections/users/profiles/user_id:user_001/external_ids/delete' \ +--header 'Authorization: Basic ' \ +--header 'Content-Type: application/json' \ +--data '{ + "delete_external_ids": [ + { + "id": "example@gmail.com", + "type": "email" + } + ] +}' +``` +## Responses and error codes + +## HTTP responses + +| HTTP Code | Code | Message | +| --------- | -------------------- | --------------------------------------------------------------------- | +| 200 | success | external identifier has been deleted | +| 400 | unsupported_eid_type | unsupported external id type | +| 400 | bad_request | missing required parameters in URL | +| 400 | bad_request | invalid URL: valid `user_id` is required. unsupported `` | +| 400 | bad_request | only one external_id can be deleted at a time | +| 400 | bad_request | invalid collection: `` | +| 400 | bad_request | external id specification must differ from lookup id | +| 401 | unauthorized | the specified token is invalid | +| 403 | forbidden | Deleted identifier not activated for space_id `` | +| 404 | not_found | the resource was not found | +| 404 | eid_not_found | external identifier not found | +| 404 | source_id_not_found | no source attached to space_id `` | +| 429 | rate_limit_error | Attempted to delete more than 100 IDs per second for a single profile | + From 4cfa6429b77281f7b341240b8af373a103fbf38d Mon Sep 17 00:00:00 2001 From: pwseg Date: Thu, 6 Nov 2025 21:08:29 -0600 Subject: [PATCH 05/15] change header [netlify-build] --- src/unify/identity-resolution/delete-profile-identifier-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/unify/identity-resolution/delete-profile-identifier-api.md b/src/unify/identity-resolution/delete-profile-identifier-api.md index 44bf9a867a..acf909bb75 100644 --- a/src/unify/identity-resolution/delete-profile-identifier-api.md +++ b/src/unify/identity-resolution/delete-profile-identifier-api.md @@ -115,7 +115,7 @@ curl --location --request POST 'https://profiles.segment.com/v1/spaces/spa_abc12 ``` ## Responses and error codes -## HTTP responses + | HTTP Code | Code | Message | | --------- | -------------------- | --------------------------------------------------------------------- | From e9086b8bd51650083a807defc916c6204f68c072 Mon Sep 17 00:00:00 2001 From: pwseg Date: Thu, 6 Nov 2025 21:23:29 -0600 Subject: [PATCH 06/15] some cleanup --- .../delete-profile-identifier-api.md | 40 ++++++++++++++++++- 1 file changed, 38 insertions(+), 2 deletions(-) diff --git a/src/unify/identity-resolution/delete-profile-identifier-api.md b/src/unify/identity-resolution/delete-profile-identifier-api.md index acf909bb75..2a2f5a8d80 100644 --- a/src/unify/identity-resolution/delete-profile-identifier-api.md +++ b/src/unify/identity-resolution/delete-profile-identifier-api.md @@ -45,7 +45,7 @@ If you use [Profiles Sync](/docs/unify/profiles-sync/overview/), complete these When you delete an identifier, Segment removes it from [Identity Resolution](/docs/unify/identity-resolution/) and propagates the change through connected systems. -The Delete Profile Identifier API confirms that Segment deleted the identifier from the Real-Time Identity Graph. Deletion then propagates to other systems: +After you send the request, the Delete Profile Identifier API confirms that Segment deleted the identifier from the Real-Time Identity Graph. Deletion then propagates to other systems: 1. Real-time Profile storage**: The Profile API and Profile explorer delete the identifier in near real time. 2. Batch Profile Data lakehouse: Segment soft-deletes the identifier (flags it as deleted) in the append-only table within minutes. The identifier filters out from the materialized view within 24 hours. @@ -53,7 +53,7 @@ The Delete Profile Identifier API confirms that Segment deleted the identifier f -## Delete an identifier +## Delete an identifier You can only delete identifiers from known profiles. The API requires a valid `user_id` to locate the profile. @@ -133,3 +133,39 @@ curl --location --request POST 'https://profiles.segment.com/v1/spaces/spa_abc12 | 404 | source_id_not_found | no source attached to space_id `` | | 429 | rate_limit_error | Attempted to delete more than 100 IDs per second for a single profile | +## Limitations and considerations + + + +### Deletion scope + +The Delete Profile Identifier API removes identifiers from Unify systems, including Identity Resolution, Profile Storage, and Profile Sync to your data warehouse. However, deletion doesn't extend to all Segment systems. Identifiers remain in the Event Archive and are soft-deleted in the Batch Profile Data Lakehouse. + +Segment doesn't delete identifiers from downstream destinations like Braze, Amplitude, Facebook, Engage Audiences, Journeys, Linked Audiences, or Consent settings. You must update these systems separately. + +### Rate limits + +Segment allows up to 100 deletion requests per second per space and 100 deletions per second for identifiers on a single profile. + +### Response time + +Most deletion requests complete in under 3 seconds. Deletions on profiles with more than 15 merges or 50 identifier mappings may take longer. + +Deletion propagates to connected systems at different speeds: +- **Real-Time Profile Storage**: seconds to 5 minutes +- **Profile Sync**: depends on your sync schedule + +### Space rebuilds and replays + +If you rebuild a space from Segment Archives, deletions don't replay automatically. You must rerun deletions after the replay completes. + +### Identifier reintroduction + +Segment may reintroduce deleted identifiers in the following cases: + +1. **Event replays**: Replaying events from the Event Archive that reference deleted identifiers adds them back to the profile. +2. **Engage or Journey sync timing**: Deleting an identifier within 5 minutes of sending an event that references it may result in the identifier being reintroduced through Engage-generated events. + +### Profile API source + +When you first use the Delete Profile Identifier API, Segment creates a `profile-api-source` for internal tracking. This source may appear in your workspace. From 01e4399249e33e8bae04fb1dd28607ef8f7ba493 Mon Sep 17 00:00:00 2001 From: pwseg Date: Thu, 6 Nov 2025 21:28:27 -0600 Subject: [PATCH 07/15] some more cleanup --- src/unify/identity-resolution/delete-profile-identifier-api.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/unify/identity-resolution/delete-profile-identifier-api.md b/src/unify/identity-resolution/delete-profile-identifier-api.md index 2a2f5a8d80..b040053bee 100644 --- a/src/unify/identity-resolution/delete-profile-identifier-api.md +++ b/src/unify/identity-resolution/delete-profile-identifier-api.md @@ -76,7 +76,7 @@ POST https://{HOST_NAME}/v1/spaces/{SPACE_ID}/collections/users/profiles/user_id | Parameter | Description | | ----------------- | ---------------------------------------------------------------------------------------------------- | | **HOST_NAME** | `profiles.segment.com` for North America workspaces or `profiles.euw1.segment.com` for EU workspaces | -| **SPACE_ID** | Your space ID. Find this in **Unify > Settings > API access** | +| **SPACE_ID** | Your space ID. Find this in **Unify > Unify settings > API access** | | **USER_ID_VALUE** | The `user_id` value that identifies the profile | | **AUTH_TOKEN** | Your access token. Generate this in **Unify > Settings > API access** | @@ -152,6 +152,7 @@ Segment allows up to 100 deletion requests per second per space and 100 deletion Most deletion requests complete in under 3 seconds. Deletions on profiles with more than 15 merges or 50 identifier mappings may take longer. Deletion propagates to connected systems at different speeds: + - **Real-Time Profile Storage**: seconds to 5 minutes - **Profile Sync**: depends on your sync schedule From f4818968fa9217d22208f398691bd89223084141 Mon Sep 17 00:00:00 2001 From: pwseg Date: Thu, 6 Nov 2025 21:38:49 -0600 Subject: [PATCH 08/15] reword use cases --- .../delete-profile-identifier-api.md | 20 ++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/src/unify/identity-resolution/delete-profile-identifier-api.md b/src/unify/identity-resolution/delete-profile-identifier-api.md index b040053bee..c092a7e206 100644 --- a/src/unify/identity-resolution/delete-profile-identifier-api.md +++ b/src/unify/identity-resolution/delete-profile-identifier-api.md @@ -10,13 +10,13 @@ Use this API to clean up outdated or incorrectly added identifiers without delet ## Use cases -Remove identifiers that shouldn't be associated with a profile: +The Delete Profile Identifier API helps you clean up identifiers that shouldn't be associated with a profile, including: -- Remove mistakenly imported identifiers, like incorrect email addresses, to prevent inaccurate targeting in downstream tools. -- Clean up obsolete identifiers after database migrations or system changes. -- Transfer identifiers with a short lifespan between profiles. For example, when a user changes phone numbers or when a prepaid service expires, you can remove the phone number from one profile and add it to another. -- Fix profiles that violate [ID Resolution limits](). Remove old identifiers to bring profiles into compliance with your configured limits. -- Revert misconfigured identity resolution settings. For example, if you reduced the `user_id` limit from 3 to 1, remove extra `user_id` values to resolve discrepancies between Segment and downstream tools like Braze or Amplitude. +- Mistakenly imported identifiers, like incorrect email addresses, that prevent accurate targeting in downstream tools +- Obsolete identifiers left over from database migrations or system changes +- Identifiers with a short lifespan that need to transfer between profiles. For example, when a user changes phone numbers or when a prepaid service expires, you can remove the phone number from one profile and add it to another. +- Old identifiers that cause profiles to violate [ID Resolution limits]() +- Extra identifiers from misconfigured identity resolution settings. For example, if you reduced the `user_id` limit from 3 to 1, remove extra `user_id` values to resolve discrepancies between Segment and downstream tools like Braze or Amplitude. ## Before you begin @@ -67,10 +67,16 @@ The API returns an error if you try to delete: The API accepts one identifier per request. **Endpoint**: -``` +```sh POST https://{HOST_NAME}/v1/spaces/{SPACE_ID}/collections/users/profiles/user_id:{USER_ID_VALUE}/external_ids/delete ``` +```sh +https://{HOST_NAME}/v1/spaces/{SPACE_ID}/collections/users/profiles/user_id:{USER_ID_VALUE}/external_ids/delete +``` + +`POST https://{HOST_NAME}/v1/spaces/{SPACE_ID}/collections/users/profiles/user_id:{USER_ID_VALUE}/external_ids/delete` + **Parameters**: | Parameter | Description | From c79fb27db992e337bee0ed71d58cbd612182d82d Mon Sep 17 00:00:00 2001 From: pwseg Date: Thu, 6 Nov 2025 21:41:58 -0600 Subject: [PATCH 09/15] reword before you begin section --- .../delete-profile-identifier-api.md | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/src/unify/identity-resolution/delete-profile-identifier-api.md b/src/unify/identity-resolution/delete-profile-identifier-api.md index c092a7e206..f74d8b850d 100644 --- a/src/unify/identity-resolution/delete-profile-identifier-api.md +++ b/src/unify/identity-resolution/delete-profile-identifier-api.md @@ -20,26 +20,22 @@ The Delete Profile Identifier API helps you clean up identifiers that shouldn't ## Before you begin -During private beta, the Delete Profile Identifier API is available to Unify and Engage. +The Delete Profile Identifier API is available to Unify and Engage customers during private beta. -You must have one of the following role permissions to delete identifiers: +You need one of these roles to delete identifiers: - Workspace Owner - Identity Admin - Unify and Engage Admin -For more information, see [the Roles documentation](/docs/segment-app/iam/roles/). +See [the Roles documentation](/docs/segment-app/iam/roles/) for more details. -### Profiles Sync configuration - -If you use [Profiles Sync](/docs/unify/profiles-sync/overview/), complete these steps before using the Delete Profile Identifier API: +If you use [Profiles Sync](/docs/unify/profiles-sync/overview/), you must also: 1. Add the `__operation` column to the `external_id_mapping_updates` table schema in your data warehouse: - Default value: `CREATED` - Deleted value: `REMOVED` -2. Verify that your analytics workloads (BI tools, data pipelines, ML models) can handle deleted identifiers. Make sure these systems remain operational and account for the `REMOVED` flag. - - +2. Verify that your analytics workloads (BI tools, data pipelines, ML models) can handle deleted identifiers. Make sure these systems stay operational and account for the `REMOVED` flag. ## How deletion works From a6957324dc31eb9d3e87f81ab63f0beecaa5331a Mon Sep 17 00:00:00 2001 From: pwseg Date: Fri, 7 Nov 2025 00:02:26 -0600 Subject: [PATCH 10/15] explain request better --- .../delete-profile-identifier-api.md | 54 +++++++++---------- 1 file changed, 24 insertions(+), 30 deletions(-) diff --git a/src/unify/identity-resolution/delete-profile-identifier-api.md b/src/unify/identity-resolution/delete-profile-identifier-api.md index f74d8b850d..d9867cc15f 100644 --- a/src/unify/identity-resolution/delete-profile-identifier-api.md +++ b/src/unify/identity-resolution/delete-profile-identifier-api.md @@ -39,17 +39,18 @@ If you use [Profiles Sync](/docs/unify/profiles-sync/overview/), you must also: ## How deletion works -When you delete an identifier, Segment removes it from [Identity Resolution](/docs/unify/identity-resolution/) and propagates the change through connected systems. +When you delete an identifier, Segment removes it from [Identity Resolution](/docs/unify/identity-resolution/) and syncs the change to connected systems. -After you send the request, the Delete Profile Identifier API confirms that Segment deleted the identifier from the Real-Time Identity Graph. Deletion then propagates to other systems: +The API confirms that Segment deleted the identifier from the Real-Time Identity Graph. The deletion then flows through these systems: -1. Real-time Profile storage**: The Profile API and Profile explorer delete the identifier in near real time. -2. Batch Profile Data lakehouse: Segment soft-deletes the identifier (flags it as deleted) in the append-only table within minutes. The identifier filters out from the materialized view within 24 hours. -3. Customer data warehouse: Profile Sync sends a deletion notification to your warehouse. The `external_id_mapping_updates` table shows the identifier with `__operation` set to `REMOVED`. The `user_identifiers` materialized view filters out removed identifiers. +| System | What happens | +| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Real-time Profile storage | The Profile API and Profile explorer delete the identifier in near real time | +| Batch Profile Data lakehouse | Segment soft-deletes the identifier in the append-only table within minutes and filters it from the materialized view within 24 hours | +| Customer data warehouse | Profiles Sync adds a row to `external_id_mapping_updates` with `__operation` set to `REMOVED`. The `user_identifiers` view filters out removed identifiers | - -## Delete an identifier +## Send a deletion request You can only delete identifiers from known profiles. The API requires a valid `user_id` to locate the profile. @@ -62,35 +63,28 @@ The API returns an error if you try to delete: The API accepts one identifier per request. -**Endpoint**: -```sh -POST https://{HOST_NAME}/v1/spaces/{SPACE_ID}/collections/users/profiles/user_id:{USER_ID_VALUE}/external_ids/delete -``` +Send requests to this endpoint: -```sh -https://{HOST_NAME}/v1/spaces/{SPACE_ID}/collections/users/profiles/user_id:{USER_ID_VALUE}/external_ids/delete +``` +POST https://{HOST_NAME}/v1/spaces/{SPACE_ID}/collections/users/profiles/user_id:{USER_ID_VALUE}/external_ids/delete ``` -`POST https://{HOST_NAME}/v1/spaces/{SPACE_ID}/collections/users/profiles/user_id:{USER_ID_VALUE}/external_ids/delete` - -**Parameters**: - -| Parameter | Description | -| ----------------- | ---------------------------------------------------------------------------------------------------- | -| **HOST_NAME** | `profiles.segment.com` for North America workspaces or `profiles.euw1.segment.com` for EU workspaces | -| **SPACE_ID** | Your space ID. Find this in **Unify > Unify settings > API access** | -| **USER_ID_VALUE** | The `user_id` value that identifies the profile | -| **AUTH_TOKEN** | Your access token. Generate this in **Unify > Settings > API access** | +Replace the following parameters in the URL: -**Request body**: +| Parameter | Description | +| --------------- | ---------------------------------------------------------------------------------------------------- | +| `HOST_NAME` | `profiles.segment.com` for North America workspaces or `profiles.euw1.segment.com` for EU workspaces | +| `SPACE_ID` | Your space ID. Find this in **Unify > Unify settings > API access**. | +| `USER_ID_VALUE` | The `user_id` value that identifies the profile. | +| `AUTH_TOKEN` | Your access token. Generate this in **Unify > Unify settings > API access**. | -| Field | Description | -| ----------------------- | ------------------------------------------------------------------------------ | -| **delete_external_ids** | Array containing the identifier to delete. Limit: 1 identifier per request | -| **id** | Value of the identifier to delete (for example, `hello@gmail.com`) | -| **type** | Type of identifier to delete (for example, `email`, `anonymous_id`, `user_id`) | +Include these fields in the request body: - +| Field | Description | +| --------------------- | ------------------------------------------------------------------------------ | +| `delete_external_ids` | Array containing the identifier to delete. Limit: 1 identifier per request | +| `id` | Value of the identifier to delete (for example, `hello@gmail.com`) | +| `type` | Type of identifier to delete (for example, `email`, `anonymous_id`, `user_id`) | ### Example request From e9ac63f5515384d69bfcaed087589ed56d592892 Mon Sep 17 00:00:00 2001 From: pwseg Date: Fri, 7 Nov 2025 08:49:47 -0600 Subject: [PATCH 11/15] remove auth from parameters table --- .../delete-profile-identifier-api.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/src/unify/identity-resolution/delete-profile-identifier-api.md b/src/unify/identity-resolution/delete-profile-identifier-api.md index d9867cc15f..63c70d5a0e 100644 --- a/src/unify/identity-resolution/delete-profile-identifier-api.md +++ b/src/unify/identity-resolution/delete-profile-identifier-api.md @@ -59,7 +59,17 @@ The API returns an error if you try to delete: - All `user_id` values from a profile. Profiles must have at least one `user_id`. - A `group_id` identifier. The API only supports individual profiles. -### API request format +### Authentication + +The API uses HTTP Basic Authentication. Base64-encode your access token with a trailing colon (the colon represents an empty password): + +```bash +echo -n 'your_token:' | base64 +``` + +Use the encoded value in the `Authorization` header of your requests. Generate your access token in **Unify > Unify settings > API access**. + +### Request format The API accepts one identifier per request. @@ -75,20 +85,19 @@ Replace the following parameters in the URL: | --------------- | ---------------------------------------------------------------------------------------------------- | | `HOST_NAME` | `profiles.segment.com` for North America workspaces or `profiles.euw1.segment.com` for EU workspaces | | `SPACE_ID` | Your space ID. Find this in **Unify > Unify settings > API access**. | -| `USER_ID_VALUE` | The `user_id` value that identifies the profile. | -| `AUTH_TOKEN` | Your access token. Generate this in **Unify > Unify settings > API access**. | +| `USER_ID_VALUE` | The `user_id` value that identifies the profile. | Include these fields in the request body: | Field | Description | | --------------------- | ------------------------------------------------------------------------------ | | `delete_external_ids` | Array containing the identifier to delete. Limit: 1 identifier per request | -| `id` | Value of the identifier to delete (for example, `hello@gmail.com`) | +| `id` | Value of the identifier to delete (for example, `hello@example.com`) | | `type` | Type of identifier to delete (for example, `email`, `anonymous_id`, `user_id`) | ### Example request -First, base64-encode your access token with a trailing colon: +The API uses HTTP Basic Authentication. Base64-encode your access token with a trailing colon (the colon represents an empty password): ```bash echo -n 'your_token:' | base64 From 792c936465b903e28d3aed54398950c4fd3261b2 Mon Sep 17 00:00:00 2001 From: pwseg Date: Fri, 7 Nov 2025 08:52:34 -0600 Subject: [PATCH 12/15] clean up status codes table --- .../delete-profile-identifier-api.md | 36 +++++++++---------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/src/unify/identity-resolution/delete-profile-identifier-api.md b/src/unify/identity-resolution/delete-profile-identifier-api.md index 63c70d5a0e..ebe0862c41 100644 --- a/src/unify/identity-resolution/delete-profile-identifier-api.md +++ b/src/unify/identity-resolution/delete-profile-identifier-api.md @@ -75,7 +75,7 @@ The API accepts one identifier per request. Send requests to this endpoint: -``` +```bash POST https://{HOST_NAME}/v1/spaces/{SPACE_ID}/collections/users/profiles/user_id:{USER_ID_VALUE}/external_ids/delete ``` @@ -120,23 +120,23 @@ curl --location --request POST 'https://profiles.segment.com/v1/spaces/spa_abc12 ``` ## Responses and error codes - - -| HTTP Code | Code | Message | -| --------- | -------------------- | --------------------------------------------------------------------- | -| 200 | success | external identifier has been deleted | -| 400 | unsupported_eid_type | unsupported external id type | -| 400 | bad_request | missing required parameters in URL | -| 400 | bad_request | invalid URL: valid `user_id` is required. unsupported `` | -| 400 | bad_request | only one external_id can be deleted at a time | -| 400 | bad_request | invalid collection: `` | -| 400 | bad_request | external id specification must differ from lookup id | -| 401 | unauthorized | the specified token is invalid | -| 403 | forbidden | Deleted identifier not activated for space_id `` | -| 404 | not_found | the resource was not found | -| 404 | eid_not_found | external identifier not found | -| 404 | source_id_not_found | no source attached to space_id `` | -| 429 | rate_limit_error | Attempted to delete more than 100 IDs per second for a single profile | +The API returns the following HTTP status codes: + +| HTTP Code | Code | Message | +| --------- | ---------------------- | ----------------------------------------------------------------------- | +| `200` | `success` | External identifier has been deleted. | +| `400` | `unsupported_eid_type` | Unsupported external id type. | +| `400` | `bad_request` | Missing required parameters in URL. | +| `400` | `bad_request` | Invalid URL: valid `user_id` is required. Unsupported ``. | +| `400` | `bad_request` | Only one external_id can be deleted at a time. | +| `400` | `bad_request` | Invalid collection: ``. | +| `400` | `bad_request` | External id specification must differ from lookup id. | +| `401` | `unauthorized` | The specified token is invalid. | +| `403` | `forbidden` | Deleted identifier not activated for space_id ``. | +| `404` | `not_found` | The resource was not found. | +| `404` | `eid_not_found` | External identifier not found. | +| `404` | `source_id_not_found` | No source attached to space_id ``. | +| `429` | `rate_limit_error` | Attempted to delete more than 100 IDs per second for a single profile. | ## Limitations and considerations From 84d74dd1851b25d2d3aa4cb43b1ca17ae0d197ed Mon Sep 17 00:00:00 2001 From: pwseg Date: Fri, 7 Nov 2025 09:08:03 -0600 Subject: [PATCH 13/15] add private beta alert --- .../delete-profile-identifier-api.md | 28 ++++++++++++------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/src/unify/identity-resolution/delete-profile-identifier-api.md b/src/unify/identity-resolution/delete-profile-identifier-api.md index ebe0862c41..d36e4d2255 100644 --- a/src/unify/identity-resolution/delete-profile-identifier-api.md +++ b/src/unify/identity-resolution/delete-profile-identifier-api.md @@ -8,6 +8,11 @@ The Delete Profile Identifier API removes identifiers from a profile while prese Use this API to clean up outdated or incorrectly added identifiers without deleting entire profiles and replaying events. +This page explains how to use the API, including how deletions work across Segment systems and what to consider before you begin. + +> info "Delete Profile Identifier API Private Beta" +> The Delete Profile Identifier API is in Private Beta, and Segment is actively working on this feature. Some functionality may change before it becomes generally available. + ## Use cases The Delete Profile Identifier API helps you clean up identifiers that shouldn't be associated with a profile, including: @@ -20,7 +25,10 @@ The Delete Profile Identifier API helps you clean up identifiers that shouldn't ## Before you begin -The Delete Profile Identifier API is available to Unify and Engage customers during private beta. +> warning "Deletion scope" +> This API removes identifiers from Unify systems only. For complete user data deletion across all Segment systems (required for GDPR, CCPA, and other privacy regulations), see [Segment's user deletion and suppression guidance](/docs/privacy/user-deletion-and-suppression/). + +The Delete Profile Identifier API is available to Unify and Engage customers during private beta. You need one of these roles to delete identifiers: @@ -28,7 +36,7 @@ You need one of these roles to delete identifiers: - Identity Admin - Unify and Engage Admin -See [the Roles documentation](/docs/segment-app/iam/roles/) for more details. +See [the Roles documentation](/docs/segment-app/iam/roles/) for more detailss. If you use [Profiles Sync](/docs/unify/profiles-sync/overview/), you must also: @@ -138,9 +146,9 @@ The API returns the following HTTP status codes: | `404` | `source_id_not_found` | No source attached to space_id ``. | | `429` | `rate_limit_error` | Attempted to delete more than 100 IDs per second for a single profile. | -## Limitations and considerations +## Considerations and deletion behavior - +Keep the following information in mind as you use the Delete Profile Identifier API. ### Deletion scope @@ -156,10 +164,10 @@ Segment allows up to 100 deletion requests per second per space and 100 deletion Most deletion requests complete in under 3 seconds. Deletions on profiles with more than 15 merges or 50 identifier mappings may take longer. -Deletion propagates to connected systems at different speeds: +Deletion syncs to connected systems at different speeds: -- **Real-Time Profile Storage**: seconds to 5 minutes -- **Profile Sync**: depends on your sync schedule +- **Real-time Profile storage**: seconds to 5 minutes +- **Profiles Sync**: depends on your sync schedule ### Space rebuilds and replays @@ -167,10 +175,10 @@ If you rebuild a space from Segment Archives, deletions don't replay automatical ### Identifier reintroduction -Segment may reintroduce deleted identifiers in the following cases: +Segment may reintroduce deleted identifiers in these limited cases: -1. **Event replays**: Replaying events from the Event Archive that reference deleted identifiers adds them back to the profile. -2. **Engage or Journey sync timing**: Deleting an identifier within 5 minutes of sending an event that references it may result in the identifier being reintroduced through Engage-generated events. +- **Event replays**: Replaying events from the Event Archive that reference deleted identifiers adds them back to the profile. +- **Engage or Journey sync timing**: Deleting an identifier within 5 minutes of sending an event that references it may result in the identifier being reintroduced through Engage-generated events. ### Profile API source From c851481d58b7923fbb979420db9ab65d27f7e6aa Mon Sep 17 00:00:00 2001 From: pwseg Date: Fri, 7 Nov 2025 09:14:05 -0600 Subject: [PATCH 14/15] final touchups [netlify-build] --- .../delete-profile-identifier-api.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/unify/identity-resolution/delete-profile-identifier-api.md b/src/unify/identity-resolution/delete-profile-identifier-api.md index d36e4d2255..9a5b1e1631 100644 --- a/src/unify/identity-resolution/delete-profile-identifier-api.md +++ b/src/unify/identity-resolution/delete-profile-identifier-api.md @@ -20,8 +20,8 @@ The Delete Profile Identifier API helps you clean up identifiers that shouldn't - Mistakenly imported identifiers, like incorrect email addresses, that prevent accurate targeting in downstream tools - Obsolete identifiers left over from database migrations or system changes - Identifiers with a short lifespan that need to transfer between profiles. For example, when a user changes phone numbers or when a prepaid service expires, you can remove the phone number from one profile and add it to another. -- Old identifiers that cause profiles to violate [ID Resolution limits]() -- Extra identifiers from misconfigured identity resolution settings. For example, if you reduced the `user_id` limit from 3 to 1, remove extra `user_id` values to resolve discrepancies between Segment and downstream tools like Braze or Amplitude. +- Old identifiers that cause profiles to violate [ID Resolution limits](/docs/unify/product-limits/#identity). +- Extra identifiers from misconfigured identity resolution settings. For example, if you reduced the `user_id` limit from 3 to 1, remove extra `user_id` values to resolve discrepancies between Segment and downstream tools like [Braze](/docs/connections/destinations/catalog/actions-braze-cloud/) or [Amplitude](/docs/connections/destinations/catalog/actions-amplitude/). ## Before you begin @@ -49,7 +49,7 @@ If you use [Profiles Sync](/docs/unify/profiles-sync/overview/), you must also: When you delete an identifier, Segment removes it from [Identity Resolution](/docs/unify/identity-resolution/) and syncs the change to connected systems. -The API confirms that Segment deleted the identifier from the Real-Time Identity Graph. The deletion then flows through these systems: +The API confirms that Segment deleted the identifier from the real-time Identity Graph. The deletion then flows through these systems: | System | What happens | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -152,7 +152,7 @@ Keep the following information in mind as you use the Delete Profile Identifier ### Deletion scope -The Delete Profile Identifier API removes identifiers from Unify systems, including Identity Resolution, Profile Storage, and Profile Sync to your data warehouse. However, deletion doesn't extend to all Segment systems. Identifiers remain in the Event Archive and are soft-deleted in the Batch Profile Data Lakehouse. +The Delete Profile Identifier API removes identifiers from Unify systems, including Identity Resolution, Profile Storage, and Profile Sync to your data warehouse. However, deletion doesn't extend to all Segment systems. Identifiers remain in the event archive and are soft-deleted in the Batch Profile Data Lakehouse. Segment doesn't delete identifiers from downstream destinations like Braze, Amplitude, Facebook, Engage Audiences, Journeys, Linked Audiences, or Consent settings. You must update these systems separately. @@ -171,7 +171,7 @@ Deletion syncs to connected systems at different speeds: ### Space rebuilds and replays -If you rebuild a space from Segment Archives, deletions don't replay automatically. You must rerun deletions after the replay completes. +If you rebuild a space from Segment archives, deletions don't replay automatically. You must rerun deletions after the replay completes. ### Identifier reintroduction From 53b3879a20fb36d538a55f481f839ac865fd4cd8 Mon Sep 17 00:00:00 2001 From: pwseg Date: Fri, 7 Nov 2025 09:56:07 -0600 Subject: [PATCH 15/15] quick fix --- src/unify/identity-resolution/delete-profile-identifier-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/unify/identity-resolution/delete-profile-identifier-api.md b/src/unify/identity-resolution/delete-profile-identifier-api.md index 9a5b1e1631..d4008c4a39 100644 --- a/src/unify/identity-resolution/delete-profile-identifier-api.md +++ b/src/unify/identity-resolution/delete-profile-identifier-api.md @@ -36,7 +36,7 @@ You need one of these roles to delete identifiers: - Identity Admin - Unify and Engage Admin -See [the Roles documentation](/docs/segment-app/iam/roles/) for more detailss. +See [the Roles documentation](/docs/segment-app/iam/roles/) for more details. If you use [Profiles Sync](/docs/unify/profiles-sync/overview/), you must also: