This application is built out and maintained by the Braze Growth department. If you would like to reach out to the creators of this application, please create a github issue for any feedback or issues that may arise.
User Attribute CSV to Braze Import
The following article references a serverless application that allows you to easily deploy a Lambda process that will post user attribute data from a CSV file directly to Braze through the Braze User Track API endpoint. This application integration was tested with our Amperity partner and can be found on our Github here.
This process launches immediately upon uploading a CSV file to a configured AWS S3 bucket. It can handle large files and uploads, but due to Lambda’s time limits, the function will stop execution after 10 minutes. This process will then launch another Lambda instance to finish processing the remaining part of the file. For more details about function timing, check out the estimated execution times.
CSV User Attributes
User attributes to be updated are expected in the following
1 2 external_id,attr_1,...,attr_n userID,value_1,...,value_n
The first column must specify the external ID of the user to be updated and the following columns must specify attribute names and values. The number of attributes you specify can vary. If the CSV file to be processed does not follow this format, the function will fail.
CSV file example:
1 2 3 external_id,Loyalty Points,Last Brand Purchased abc123,1982,Solomon def456,578,Hunter-Hayes
Any values in an array (ex.
"['Value1', 'Value2']") will be automatically destructured and sent to the API in an array rather than a string representation of an array.
To successfully run this Lambda function, you will need:
- AWS Account to use the S3 and Lambda services
- Braze API URL to connect to Braze servers
- Braze API Key to be able to send requests to
- CSV File with user external IDs and attributes to update
You can find your API URL, or REST endpoint, in the Braze API documentation and through the dashboard.
- API Documentation
Per the API documentation, simply match your Braze instance URL to the REST endpoint URL. For example, if your dashboard shows
dashboard-01.braze.com/URL, your REST endpoint would be
From the left navigation panel, scroll down and select Manage Settings. There, you can find your
SDK Endpoint. Replace
restto get your REST Endpoint. For example, if you see
sdk.iad-01.braze.com, your API URL would be
To connect with the Braze servers, you will need an API key. This unique identifier allows Braze to verify your identity and upload your data.
To get your API key, open the Dashboard and scroll down the left navigation section. Select Developer Console under Settings. You will need an API key that has permission to post to
users.track API endpoint. If you know one of your API keys supports that endpoint, you can use that key.
To create a new one, click on
Create New API Key on the right side of your screen. Next, name your API Key and select
users.track under the User Data endpoints group. Scroll down and click on Save API Key.
- Deploy Braze’s publicly available CSV processing Lambda from the AWS Serverless Application Repository
- Drop a CSV file with user attributes in the newly created S3 bucket
- The users will be automatically imported to Braze
To start processing your User Attribute CSV files, we need to deploy the Serverless Application that will handle the processing for you. This application will create the following resources automatically to successfully deploy:
- Lambda function
- S3 Bucket for your CSV Files that the Lambda process can read from (Note: this Lambda function will only receive notifications for
- Role allowing for the creation of the above
- Policy to allow Lambda to receive S3 upload event in the new bucket
Follow the direct link to the Application or open the AWS Serverless Application Repository and search for braze-user-attribute-import. Note that you must check the
Show apps that create custom IAM roles and resource policies checkbox to see this application. The application creates a policy for the lambda to read from the newly created S3 bucket.
Click Deploy and let AWS create all the necessary resources.
You can watch the deployment and verify that the stack (ie. all the required resources) is being created in the CloudFormation. Find the stack named serverlessrepo-braze-user-attribute-import. Once the Status turns to
CREATE_COMPLETE, the function is ready to use. You can click on the stack and open Resources and watch the different resources being created.
The following resources were created:
- S3 Bucket - a bucket named
aaa123is a randomly generated string
- Lambda Function - a lambda function named
- IAM Role - policy named
braze-user-csv-import-BrazeUserCSVImportRoleto allow lambda to read from S3 and to log function output
To run the function, drop a user attribute CSV file in the newly created S3 bucket.
Monitoring and Logging
To make sure the function runs successfully, you can read the function’s execution logs. Open the Braze User CSV Import function (by selecting it from the list of Lambdas in the console) and navigate to Monitor. Here, you can see the execution history of the function. To read the output, click on View logs in CloudWatch. Select the lambda execution event you want to check.
Estimated Execution Times
2048MB Lambda Function
|# of rows||Exec. Time|
Updating an Existing Function
If you have already deployed the application and a new version is available in the repository, you can update by re-deploying the function as if you were doing it for the first time. That means you have to pass it the Braze API Key and Braze API URL again. The update will only overwrite the function code. It will not modify or delete other existing resources like the S3 bucket.
In case of an unexpected error that prevents the further processing of the file, an event is logged (accessible through CloudWatch described in Monitoring and Logging) that can be used to restart the Lambda from the point where the program stopped processing the file. It is important not to re-import the same data to save Data Points. You can find instructions to do this in our Github repo.