Delete Profile Identifier API

The Delete Profile Identifier API helps you clean up identifiers that shouldn't be associated with a profile, including:

• 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.

The Delete Profile Identifier API is available to Unify and Engage customers during public beta.

You need one of these roles to delete identifiers:

• Workspace Owner
• Identity Admin
• Unify and Engage Admin

See the Roles documentation for more details.

If you use Profiles Sync, 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 stay operational and account for the REMOVED flag.

When you delete an identifier, Segment removes it from 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:

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.

The API uses HTTP Basic Authentication. Base64-encode your access token with a trailing colon (the colon represents an empty password):

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.

The API accepts one identifier per request.

Send requests to this endpoint:

POST https://{HOST_NAME}/v1/spaces/{SPACE_ID}/collections/users/profiles/user_id:{USER_ID_VALUE}/external_ids/delete

Replace the following parameters in the URL:

Include these fields in the request body:

The API uses HTTP Basic Authentication. Base64-encode your access token with a trailing colon (the colon represents an empty password):

echo -n 'your_token:' | base64

Then send the delete request:

1
curl --location --request POST 'https://profiles.segment.com/v1/spaces/spa_abc123/collections/users/profiles/user_id:user_001/external_ids/delete' \
2
--header 'Authorization: Basic <base64_encoded_token_colon>' \
3
--header 'Content-Type: application/json' \
4
--data '{
5
  "delete_external_ids": [
6
    {
7
      "id": "example@gmail.com",
8
      "type": "email"
9
    }
10
  ]
11
}'

The API returns the following HTTP status codes:

Keep the following information in mind as you use the Delete Profile Identifier API.

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.

Segment allows up to 100 deletion requests per second per space and 100 deletions per second for identifiers on a single profile.

Most deletion requests complete in under 3 seconds. Deletions on profiles with more than 15 merges or 50 identifier mappings may take longer.

Deletion syncs to connected systems at different speeds:

• Real-time Profile storage: seconds to 5 minutes
• Profiles Sync: depends on your sync schedule

If you rebuild a space from Segment archives, deletions don't replay automatically. You must rerun deletions after the replay completes.

Segment may reintroduce deleted identifiers in these limited cases:

• 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.

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.