Braze Tutorial: How To Delete Users via API

Deleting users is always a nerve-racking task, because it’s usually an irreversible decision. We want to make sure we get it right!

Because it’s an irreversible decision, maybe Braze wanted to add some additional guardrails. Currently, there is no way to delete your endusers from the Braze dashboard UI.

However, there are times when we simply need this functionality. Braze Technical Marketers to the rescue, let’s talk about a solution using Webhooks.

🗣️ WATCH FULL YOUTUBE VIDEO HERE 🗣

https://youtu.be/kBhk55DbE6k

What’s up everyone, my name is Allan, Founder and Consultant at For Now Marketing, and welcome back to our channel!

Before we get started, if you have any questions, whether you are currently using Braze or considering using Braze, please feel free to reach out! You can find these addresses and more in the Youtube description below.

Today, we are going to talk through How To Delete Users in Braze.

Let’s get started!

Webhook Setup — ULTIMATE TUTORIAL

The first step is to create an API key enabled for the /users/delete endpoint and set up our webhook as a webhook template. If you haven’t already, please refer to this ULTIMATE TUTORIAL to get started. This is a step-by-step instruction video for how to set up most Braze webhooks, and this video will help you get as far as I am on this current page.

https://rest.iad-01.braze.com/users/delete

https://rest.iad-02.braze.com/users/delete

https://rest.iad-03.braze.com/users/delete

https://rest.iad-04.braze.com/users/delete

https://rest.iad-05.braze.com/users/delete

https://rest.iad-06.braze.com/users/delete

https://rest.iad-07.braze.com/users/delete

https://rest.iad-08.braze.com/users/delete

https://rest.fra-01.braze.eu/users/delete

https://rest.fra-02.braze.eu/users/delete

Delete A Single User

Once your webhook has been set up, let’s take a closer look at the /users/delete API endpoint documentation. So here, it says:

Use this endpoint to delete any user profile by specifying a known user identifier.

Also, it says:

Deleting user profiles cannot be undone. It will permanently remove users which may cause discrepancies in your data. Learn more about what happens when you delete a user profile via API in our Help documentation.

Let’s scroll down a little bit to the Request Body section, and here we see three fields they listed: external_ids, user_aliases, and braze_ids. These are the 3 main identifiers in Braze that we can use to identify a specific user.

It says “optional” for all three, but we do have to choose at least one of the three, and I’m guessing external_id or user_aliases will be the most common use cases for us.

For our first step, I just want to delete a single user by their external_id. I’m going to grab the entire example request from one curly bracket to the other, but I’ll be deleting most of it.

So I’m going to delete everything from this comma until the square bracket, and now, we have a clean request body that will allow us to delete specific users.

Actually, the code by itself allows us to delete 2 users, but I only need to delete one, so I’ll get rid of the second identifier here.

And inside the quote, I am going to put in the specific external_id I want to delete, which is “123deleteme”.

A quick check of the user profile, and you can see that this profile exists.

Back to our webhook, if we go to the “Test” tab, and click Send Test, this will make an actual API call. It’s only called a test because it’s a single API call, not to a large batch of users, but the API call will fire, and you can now see that my user profile “123deleteme” is now gone forever!

Let’s do another example, but this time, for alias profiles. Alias profiles always have a name-label pair, and I have an alias profile under name:allan.

Plug these values into the webhook, send a test call, and poof, my alias profile no longer exists!

I’ll share the request body for deleting a single user by both external_id and user_alias below.

Deleting by external_id:

{
  "external_ids": ["123deleteme"]
}

Deleting by user_alias:

{
    "user_aliases": [
        {
          "alias_name": "allan", 
          "alias_label": "name"
        }
    ]
}

And that is how I would go about deleting a single user profile.

Delete A Segment Of Users

Now, if you wanted to delete a whole Segment of users, we need to make one small change, and actually launch a Webhook Campaign. FYI, we can’t delete a segment of user_aliases, so I will just go over how to delete a segment of external_ids.

First, back inside our code, we’re going to replace the hard-coded “123deleteme” with the Braze Liquid variable.

Click the blue + sign, and look for user_id. Sometimes, Braze uses them interchangeably, and other times, user_id and external_id mean different things. In this case, user_id means external_id.

Click “Save Template”.

Next, let’s create a Webhook Campaign, and give it a very clear title: 2024–02–14, Deleting Segment XYZ.

Let’s choose the webhook template that we just saved.

And now, this webhook will be applied to all the users that we select in our Target Audience page on page 3. Before we progress, please keep in mind that you are actually deleting more than one user this time, so please be extra careful and double check the Segment that you’re about to choose.

On the Schedule Delivery type, either pick a launch time or delete immediately.

And on the Target Audience pages, choose the exact Segment of users you’d like to delete. Once again, as a final reminder, this webhook is being sent to every single user in this segment, and we will delete every user in this segment.

There’s a few more things to adjust here:

First, every API call has a limit called rate limit. Back on the API documentation page, you can find that this endpoint has a shared rate limit of 20000 requests per minute, which means we should not make more than 20000 requests per minute to this endpoint.

Let’s go back to our webhook campaign setup, and to be conservative, we’ll set the rate limit to 5000 per minute.

And then lastly, we don’t want a control group, so let’s uncheck the control group option. This makes sure that we’re deleting everyone in this Segment.

Nothing too important on the Assign Conversions page for this webhook setup; launch the Campaign, and boom, all your users in the segment are deleted!

Thank You!

That’s it for today!

As always, if you have any questions, please share them in the comments. We’re happy to help! 🙏

If you learned something from this video, please subscribe for more awesome Braze videos in the future!

Thank you for watching, and see you next time!

allan@fornowmarketing.com

fornowmarketing.com