Marketers love Braze for its robust messaging channel options, marketer-friendly interface, and segmentation capabilities. But to unlock the power of Braze, an important step to take is to set up the REST API. Setting up Braze's REST API is an important step that empowers marketers to leverage the full potential of the platform by:

• Implementing seamless data integrations with other platforms like CDPs or analytics tools
• Leveraging the full power of your customer data to create more sophisticated audience segments
• Enabling cross-platform or in-platform automated workflows and tasks like triggering messaging or campaigns
• Using real-time customer data to deliver highly personalized messaging and campaigns

In this video, Brandon Heath (Solution Architect at Stitch) walks through how to go about setting up Braze's REST API, including using Postman to create a dummy record, where to find resources, creating an authentication key, and walking through a few example calls.

‍

‍

Transcript:

 Hi, I'm Brandon Heath. I'm a solution architect with Stitch. I'm going to do a demo on how to set up Postman so that we can start using Braze’s REST APIs. Postman is a tool that lets you execute API requests. So we're going to use that to create a test user just with some dummy events. So this could be good if you're just getting started and want to have something to play around with, create a test segment, or test campaign without having data flowing in quite yet.

One caveat is that it will consume some data points. What I'm going to show will be fairly limited, but just something to be mindful of and then just some assumptions I'm making on my end. One is that you have a Braze account and can log in and that you have an app group with at least one app set up and that you can access the developer console for that.

So if that sounds good, then let's get started. All right. So in order to get Postman you could go to Postman.com and when you get here, you'll notice you can either download the desktop app for your respective OS or Postman also has a web version. That you can use. I'm gonna move forward with showing the desktop app, but the steps will be very similar if you need to use the web version. I think the only difference is that for the web version, you do have to sign up for a free Postman account. But otherwise, they're pretty similar. So I'm on a Mac, so I'm gonna go ahead and download it for Mac. I have an Apple chip, and then once that downloads you should be able to open it up and it will look something like this. So now we just have an empty postman. And then next we want to go ahead and get the Braze REST API collection for Postman. So that's basically pre-built example API calls that Braze has created that you can import into Postman and start using.

So in order to do that, we go find the docs page and go to Braze.com/docs. I'm going to search for Postman and sample requests. And then on this page, you'll see this link here, postman docs. We'll go ahead and click that. Then once you get here, if you scroll up a little bit, you'll see this button run in Postman. So when we click that, it'll prompt us to run it on the web or the desktop app. So I'm going to go ahead and click Postman for Mac, open for Postman. Now if you're doing it for the web version or if you have signed up for a free account, one extra thing I might ask you to do is to select the workspace.

If that comes up as the default one it's just called My Workspace. You can go ahead and just either put it there or create a new one. But once you get the collection imported, Go ahead and expand it. You'll see that there are example calls for various things. So interacting with catalogs actually sending or scheduling messages, et cetera. Today we're going to look at this bottom folder, this user data one, and I'm going to open up this track users call. I'm just going to look at it, so we can see here that this is doing a post request to the API endpoint. And then if we look through here, if we click body, this is basically going to be the data that gets sent along with the request.

What Braze is showing here is just some okay kind of dummy values to tell you how to set certain attributes. So if you were setting up a user attribute that was a Boolean, true, or false, this is an example of how you would do that. One thing to note is that here in this URL, you'll see these this piece of text instance URL that is run by these curly braces. Basically, that just means that Braze set this up for that text to be swapped out. So there's one here in the URL. And if we go into headers and look at this authorization header, we'll see this API key. So basically, we need to change these two values with things that are going to be more relevant to our setup. So we could, you know, actually just change the text in place there. But Postman does have a slightly better way to do it with something it calls environments which basically just lets you set up mappings so that you can declare these. Variables along with their values and having it set up in an environment is good just because, you know, as you get more and more here in Postman, it's helpful to be able to toggle between different environments or different configuration settings and not have to update things like the URL or the API key, but we know these are two pieces of these are two things that we need to go get.

So, in order to use the REST API we need one, an API key, and then we also need our instance URL, or what, on a cluster, our Braze account is on. There's a specific URL for that REST gateway. So, I'm going to show you how to get both. So, let's start with API key. I'm going to go back into Braze, and then in making sure that I'm in the right app group, I'm just using a dummy one go down to the developer console and then in the API settings tab, if this is your first time coming here you'll see basically this empty section. So this is where we're going to create a new API key, so we'll go ahead and create it. And for every key that you create, you have to basically assign what allow permissions it has. So, for all of those examples calls here in Postman. These will have different levels of permission. If you know you're going to go and take this and do more things other than just interacting with user data.

If you want to, for example, start sending messages, creating content et cetera, then you may want to go ahead and just select what permissions are I'm going to be necessary in the future for today. Again, I'm just going to be updating user data. So I'm going to just be conservative here and only allow it to access the user data, but I'm going to go ahead and give it an API key name to create a test user, then I will. Scroll down to the bottom and save the API key. One thing to note is for any key that you create, the identifier or the value of that key will show up here. And one thing is basically just to be mindful of who has access to these keys. For example, if you did you know, give this more permission. So you just want to be careful who had access to that key because they could then use the rest API to access whatever permissions it had.

So, but we can see now that we've created it, here's the identifier or that key value. So I'm just going to go ahead and stash that away real quick. Once we get back into Postman we'll need that. That's the API key, so of those two things that we needed to get the API key and the instance URL, that is the API key. Then to get the instance URL, we can go back to the Braze docs and go into the API guide and then the API overview. That's going to have a table, basically, that shows all of the different instances or clusters that Braze has. So what you want to do is go into your dashboard and just take note of what the URL is there should be a match here in this table, and from there we'll get the rest endpoint. So I can see that for me, that my dashboard URL is this dashboard 02.Braze.eu. That looks like that is the last row here. So I know that this is going to be my rest endpoint. So we're going to copy this, but one thing we want to notice is that here, this instance URL, already has the protocol or the HTTPS included in the URL.

So I'm going to leave that out when I copy that. Again, I'm going to stash that real quick. All right. So then we have our two variables. So now I'm going to create an environment within Postman. So again, when we execute this request it'll tell Postman to swap this token, this instance URL, and API key token out with those two values that we just got. If you go up into the upper right-hand corner and click this button here and then go to environment add, then we'll go ahead and give it a name. I'm just going to call it Braze rest to create a test user. Alright. Then we know we need an instance URL. Which, for me, is that it's likely to be different for you, and then we just need the API key. I'll paste that in. Sometimes in this UI, this current value won't get populated. If that happens, just go up here and click reset all, and that'll basically take whatever's in this initial value column and move it over. The current value is basically what Postman to swap in. And then we'll want to go ahead and save it, right? So I saved that. So now when I come up to this drop-down, I should be able to select this braze, rest, and create a test user environment. And have it swap in the values. So again, this is just the kind of example call that Braze is showing. This user slash track is similar to if the SDK were, say, sending in an event.

Basically just lets us run a user track call, so we can for any amount of users set user attributes, both out of the box and custom send custom events and purchases, so what we end up wanting to put here is just going to be maybe particular to whatever our use case is. What I've done is I have another test payload and I'll just walk through the changes that I made and explain what these things mean. Basically, what this is saying is here in this attributes section, I'm going to be setting. A user attribute for this particular external I. D. is a dummy one I've created. I'm setting these out-of-the-box attributes of first name, last name, email, and gender. Then I'm also logging a test event.

So again, for that same external ID, and then for a particular app ID, I have to say that I viewed a product at this particular time for this particular product ID, and then I'm also logging a purchase. So for that particular product ID just tracking the price and quantity, et cetera.

So one thing to note is this app ID, I can show you where to get that. Back in our developer console in our app group, this is just a test app that I've set up. I haven't done anything else with it, but once you get that created, and then you'll see that API key, it creates this identifier, and that's basically the value that we want to plug in here for app ID. We're sending in the test viewed product and the purchase for that product, those two events through that. That particular app, essentially, right now for the attributes or basically what I'm setting here in this section, one helpful thing to maybe reference is back in the API docs. If you go over into objects and filters, you can look at, for example, the user attributes object, and that'll explain in a lot more detail, the schema for that section of the. Payload. So what properties it's expecting how it's expecting you to set them what certain out-of-the-box attributes look like, for example, email gender, etc. That's essentially where I had gotten that and a similar thing for events and purchases. So now, I'm going to go ahead and make sure that I have my environment selected, so Brace REST Create Test User, and then I should be ready to go ahead and send this call off over to Braze. So I'm going to go ahead, up to this upper right-hand corner, to the Send button, and click that, and hopefully, we don't see any errors. And yeah, it looks like it went through so we can see the attributes the events, and the purchases being processed, and just the status message saying that it was a success. So now one thing to note about this track call is that if a user isn't already created, it will go ahead and create that user for that external ID.

So I should now be able to go back into my account and go to. user search and now look up that external user ID. Hopefully, I should find it. Yep. So now I can find there's that Brandon Heath record with that user ID. We'd see that viewed product custom event and then see the purchase event that I sent through the quantity of two for this test product. So everything's looking good. One extra thing I might do is with this same call, now send over something that will set some additional attributes. What I'm going to do is now paste in this, so now I'm going to set a custom user attribute of favorite color to purple for that same external ID. Send that through. We should see a similar status message saying it was a success. This might take a minute or two, but if I come in here and refresh it, I would actually show up right away. My favorite color is purple. This is just scratching the surface, but this can be good again, if you're just wanting to you know, get your feet wet with the rest API, create a test user you know, and maybe try to build a test segment off of this this this is a good way to, to get started.

So hope this was helpful. And thank you for watching.

‍